diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 00000000..6b58c7c9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,41 @@ +name: Bug +description: Report a defect in docs, protocol design, services, apps, hardware, crypto, or infra. +title: "[Bug]: " +labels: + - bug +body: + - type: textarea + id: summary + attributes: + label: Summary + description: What is broken or incorrect? + validations: + required: true + - type: textarea + id: current + attributes: + label: Current Behavior + description: What happens now? + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What should happen instead? + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Reproduction Or Evidence + description: Steps, logs, screenshots, file references, or reasoning. + validations: + required: false + - type: textarea + id: scope + attributes: + label: Suspected Scope + description: Which area or directory is likely affected? + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml new file mode 100644 index 00000000..cde35cf8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.yml @@ -0,0 +1,38 @@ +name: Feature +description: Propose a FlowMemory product, protocol, service, app, or infra feature. +title: "[Feature]: " +labels: + - feature +body: + - type: markdown + attributes: + value: | + Use this for scoped implementation proposals. Keep heavy data, secrets, and private credentials out of issues. + - type: textarea + id: goal + attributes: + label: Goal + description: What should exist after this feature is complete? + validations: + required: true + - type: textarea + id: scope + attributes: + label: Scope + description: Which directories, systems, or interfaces are in scope? + validations: + required: true + - type: textarea + id: boundaries + attributes: + label: Boundaries + description: What is explicitly out of scope? + validations: + required: true + - type: textarea + id: tests + attributes: + label: Tests Or Verification + description: What checks should prove this works? + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/hardware.yml b/.github/ISSUE_TEMPLATE/hardware.yml new file mode 100644 index 00000000..ccb2f8df --- /dev/null +++ b/.github/ISSUE_TEMPLATE/hardware.yml @@ -0,0 +1,38 @@ +name: Hardware +description: Track FlowRouter, Meshtastic, LoRa, enclosure, or field-test work. +title: "[Hardware]: " +labels: + - hardware +body: + - type: markdown + attributes: + value: | + Meshtastic and LoRa are low-bandwidth control signaling paths. Do not assume normal internet bandwidth. + - type: textarea + id: objective + attributes: + label: Objective + description: What hardware outcome is needed? + validations: + required: true + - type: textarea + id: components + attributes: + label: Components + description: Devices, radios, sensors, enclosure parts, boards, or power systems involved. + validations: + required: false + - type: textarea + id: constraints + attributes: + label: Constraints + description: Bandwidth, power, size, thermal, safety, field, or manufacturing constraints. + validations: + required: true + - type: textarea + id: validation + attributes: + label: Validation + description: How should this be tested or field-validated? + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/research.yml b/.github/ISSUE_TEMPLATE/research.yml new file mode 100644 index 00000000..2e5f623d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/research.yml @@ -0,0 +1,38 @@ +name: Research +description: Track AI memory, neural geometry, protocol, reliability, or appchain/L1 research. +title: "[Research]: " +labels: + - research +body: + - type: markdown + attributes: + value: | + Use this for research questions, hypotheses, experiments, and literature notes. + - type: textarea + id: question + attributes: + label: Research Question + description: What are we trying to learn? + validations: + required: true + - type: textarea + id: context + attributes: + label: Context + description: What project context or prior work matters? + validations: + required: true + - type: textarea + id: method + attributes: + label: Proposed Method + description: How should the research be conducted? + validations: + required: false + - type: textarea + id: output + attributes: + label: Expected Output + description: Paper note, decision record, experiment result, prototype, or other artifact. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/security.yml b/.github/ISSUE_TEMPLATE/security.yml new file mode 100644 index 00000000..b31f5822 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/security.yml @@ -0,0 +1,46 @@ +name: Security +description: Report or track protocol, service, hardware, crypto, or operational security work. +title: "[Security]: " +labels: + - security +body: + - type: markdown + attributes: + value: | + Do not include live secrets, private keys, seed phrases, or exploitable private details in public issue text. + - type: dropdown + id: area + attributes: + label: Area + options: + - Protocol + - Contracts + - Indexer or verifier + - AI memory + - Hardware + - Infrastructure + - Supply chain + - Other + validations: + required: true + - type: textarea + id: concern + attributes: + label: Concern + description: What is the security concern? + validations: + required: true + - type: textarea + id: impact + attributes: + label: Impact + description: What could go wrong if this is real? + validations: + required: true + - type: textarea + id: recommendation + attributes: + label: Recommendation + description: Proposed fix, mitigation, or next investigation step. + validations: + required: false diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..3d0a0565 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,27 @@ +# Summary + +## What Changed + +- TBD + +## Why + +- TBD + +## Tests Or Checks + +- [ ] I ran the relevant tests or checks. +- [ ] No tests exist yet for this scope. + +## Scope Discipline + +- [ ] I read `AGENTS.md`. +- [ ] I read `docs/START_HERE.md`. +- [ ] I read `docs/FLOWMEMORY_HQ_CONTEXT.md`. +- [ ] I read `docs/CURRENT_STATE.md`. +- [ ] I only edited files in my assigned scope. +- [ ] I did not hardcode secrets. + +## Risk And Follow-Ups + +- TBD diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 00000000..d5f27cb1 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,79 @@ +name: CI + +on: + pull_request: + push: + branches: + - main + +permissions: + contents: read + +jobs: + repository-hygiene: + name: Repository hygiene + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Check required bootstrap paths + shell: bash + run: | + required_paths=( + "AGENTS.md" + "README.md" + "docs/FLOWMEMORY_HQ_CONTEXT.md" + "docs/START_HERE.md" + "docs/PROJECT_CHARTER.md" + "docs/CURRENT_STATE.md" + "docs/ROADMAP.md" + "docs/ARCHITECTURE.md" + "docs/SECURITY_MODEL.md" + "docs/AGENT_ROLES.md" + "docs/DECISIONS" + "contracts" + "services" + "apps" + "hardware" + "research" + "crypto" + "infra/scripts" + "inbox/claude-code" + "inbox/old-prompts" + "inbox/unsorted" + ".github/pull_request_template.md" + ".github/ISSUE_TEMPLATE/feature.yml" + ".github/ISSUE_TEMPLATE/research.yml" + ".github/ISSUE_TEMPLATE/hardware.yml" + ".github/ISSUE_TEMPLATE/security.yml" + ".github/ISSUE_TEMPLATE/bug.yml" + ) + + missing=0 + for path in "${required_paths[@]}"; do + if [[ ! -e "$path" ]]; then + echo "::error::Missing required path: $path" + missing=1 + fi + done + + exit "$missing" + + - name: Check for obvious committed secrets + shell: bash + run: | + patterns=( + 'BEGIN (RSA|OPENSSH|PRIVATE) K[E]Y' + 'AWS_SECRET_ACCESS_K[E]Y' + 'PRIVATE_K[E]Y=' + 'SECRET_K[E]Y=' + 'gho_[A-Za-z0-9_]+' + ) + + for pattern in "${patterns[@]}"; do + if grep -RInE "$pattern" . --exclude-dir=.git; then + echo "::error::Potential secret detected. Remove it or document why this is a false positive." + exit 1 + fi + done diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..a64b52f9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,42 @@ +# FlowMemory Agent Instructions + +These instructions apply to every agent, assistant, script, and human operating in this repository. + +## Source Of Truth + +- Treat GitHub as the source of truth for project state, issues, pull requests, reviews, and final history. +- Read `docs/START_HERE.md` before starting any task. +- Read `docs/FLOWMEMORY_HQ_CONTEXT.md` before making design or implementation choices. +- Read `docs/CURRENT_STATE.md` immediately before working so you understand what exists and what does not. +- If local context conflicts with GitHub, stop and reconcile the difference before editing. + +## Scope Discipline + +- Work only on the assigned scope. +- Do not edit unrelated files. +- Do not rename, move, or delete files outside the task unless the task explicitly asks for it. +- Do not build product features during bootstrap, planning, or research tasks. +- When blocked, document the blocker and the smallest useful next step. + +## Engineering Rules + +- Do not hardcode secrets, tokens, private keys, seed phrases, RPC credentials, API keys, or webhook URLs. +- Keep heavy AI, model, memory, artifact, and media data off-chain. +- Remember that storage is not free and transaction hashes do not store arbitrary data. +- Remember that Uniswap v4 hooks cannot know `txHash` or `logIndex` at execution time. +- Let indexers and verifiers derive `txHash` and `logIndex` after reading receipts and logs. +- Store roots, receipts, commitments, attestations, proofs, and work state on-chain only when they are intentionally part of the protocol. +- Treat Meshtastic and LoRa as low-bandwidth control signaling, not normal internet bandwidth. +- Add tests where practical, especially for protocol logic, parsers, cryptography, indexers, verifiers, and hardware control paths. + +## Collaboration + +- Prefer small, reviewable pull requests. +- Keep documentation updated when changing architecture, security assumptions, public contracts, or agent workflows. +- Record durable architectural decisions in `docs/DECISIONS/`. +- Use issues for unknowns, research tasks, hardware tasks, security tasks, bugs, and feature proposals. +- End every task with a PR-ready summary that includes: + - What changed + - Why it changed + - Tests or checks run + - Risks, assumptions, and follow-ups diff --git a/README.md b/README.md index 09859607..aed1790a 100644 --- a/README.md +++ b/README.md @@ -1 +1,57 @@ -# FlowMemory \ No newline at end of file +# FlowMemory + +FlowMemory is a Base-native AI memory, neural-geometry, reliability, decentralized hardware, and future appchain/L1 research project. + +This repository is currently in bootstrap mode. It contains project context, collaboration rules, planning documents, GitHub templates, and placeholder directories for future implementation work. Do not treat the current repo as containing production product features yet. + +## What FlowMemory Is Exploring + +- Base and Uniswap v4 hook integrations +- FlowPulse events +- Rootflow and Rootfield state commitments +- AI memory and neural geometry research +- FlowRouter decentralized internet hardware +- Meshtastic and LoRa sidecar signaling +- 3D-printed hardware enclosures +- Dashboard, explorer, and hardware console applications +- Indexer, verifier, and worker services +- Cryptographic receipts, attestations, roots, and proofs +- Future FlowMemory appchain/L1 research + +## Important Boundaries + +- AI does not run on-chain. +- Storage is not free. +- Transaction hashes do not store arbitrary data. +- Uniswap v4 hooks cannot know `txHash` or `logIndex`. +- Indexers and verifiers derive `txHash` and `logIndex` after reading receipts and logs. +- Heavy AI, model, memory, and artifact data stays off-chain. +- On-chain state stores roots, receipts, commitments, attestations, proofs, and work state. +- Meshtastic and LoRa are low-bandwidth control signaling paths, not normal internet bandwidth. + +## Start Here + +Every contributor and agent should read: + +1. `AGENTS.md` +2. `docs/START_HERE.md` +3. `docs/FLOWMEMORY_HQ_CONTEXT.md` +4. `docs/CURRENT_STATE.md` + +Then work only inside the assigned scope. + +## Repository Map + +- `apps/`: future dashboard, explorer, and hardware console applications +- `contracts/`: future on-chain protocol and hook contracts +- `crypto/`: future cryptographic receipt, proof, and attestation work +- `docs/`: project context, architecture, roadmap, security model, and decisions +- `hardware/`: future FlowRouter, LoRa, Meshtastic, and enclosure work +- `infra/scripts/`: future automation and repository maintenance scripts +- `inbox/`: staging area for imported prompts, notes, and unsorted context +- `research/`: future AI memory, neural geometry, and appchain/L1 research +- `services/`: future indexer, verifier, worker, and API services + +## Current Status + +See `docs/CURRENT_STATE.md` for the latest repo state. diff --git a/apps/.gitkeep b/apps/.gitkeep new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/apps/.gitkeep @@ -0,0 +1 @@ + diff --git a/contracts/.gitkeep b/contracts/.gitkeep new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/contracts/.gitkeep @@ -0,0 +1 @@ + diff --git a/crypto/.gitkeep b/crypto/.gitkeep new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/crypto/.gitkeep @@ -0,0 +1 @@ + diff --git a/docs/AGENT_ROLES.md b/docs/AGENT_ROLES.md new file mode 100644 index 00000000..30549045 --- /dev/null +++ b/docs/AGENT_ROLES.md @@ -0,0 +1,118 @@ +# Agent Roles + +Agents may be assigned one of these roles. Each role should still read `AGENTS.md`, `docs/START_HERE.md`, `docs/FLOWMEMORY_HQ_CONTEXT.md`, and `docs/CURRENT_STATE.md`. + +## Bootstrap Agent + +Scope: + +- Repository structure +- Shared docs +- Templates +- CI hygiene + +Do not build product features. + +## Protocol Contracts Agent + +Scope: + +- `contracts/` +- Base integration +- Uniswap v4 hooks +- FlowPulse event schemas +- Rootflow and Rootfield commitment semantics + +Must document event and storage assumptions. + +## Services Agent + +Scope: + +- `services/` +- Indexers +- Verifiers +- Workers +- APIs + +Must derive `txHash` and `logIndex` from receipts and logs, not from hook execution assumptions. + +## Apps Agent + +Scope: + +- `apps/` +- Dashboard +- Explorer +- Hardware console + +Must distinguish observed, verified, pending, and failed states in UI. + +## Hardware Agent + +Scope: + +- `hardware/` +- FlowRouter +- Meshtastic and LoRa sidecars +- 3D-printed enclosures +- Field test notes + +Must treat radio links as low-bandwidth control signaling. + +## Research Agent + +Scope: + +- `research/` +- AI memory +- Neural geometry +- Reliability research +- Appchain/L1 research + +Must separate hypotheses, experiments, and accepted decisions. + +## Crypto Agent + +Scope: + +- `crypto/` +- Receipts +- Attestations +- Roots +- Proofs +- Commitment formats + +Must document threat assumptions and verification requirements. + +## Infra Agent + +Scope: + +- `infra/` +- CI +- Scripts +- Repository automation + +Must avoid leaking secrets through scripts, logs, or CI output. + +## Security Agent + +Scope: + +- Threat models +- Security reviews +- Secret handling +- Protocol and hardware risk analysis + +Must create actionable issues or PR comments for findings. + +## Handoff Format + +Every agent should finish with: + +- Summary +- Files changed +- Tests or checks run +- Risks and assumptions +- Recommended next issue or PR diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 00000000..9d804787 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,88 @@ +# Architecture + +## Overview + +FlowMemory is organized as a layered system: + +1. On-chain protocol layer on Base +2. Off-chain indexing and verification layer +3. AI memory and neural-geometry research layer +4. Hardware and control-signaling layer +5. Operator apps and explorer layer +6. Future appchain/L1 research layer + +No layer is fully implemented yet. + +## On-Chain Layer + +Expected responsibilities: + +- Emit FlowPulse events. +- Store intentional protocol state. +- Store roots, receipts, commitments, attestations, proofs, and work state where appropriate. +- Integrate with Base and possibly Uniswap v4 hooks. + +Boundaries: + +- On-chain storage is expensive. +- Transaction hashes are identifiers, not arbitrary data storage. +- Uniswap v4 hooks cannot know final `txHash` or `logIndex`. +- Contracts should not pretend to know receipt metadata that only exists after execution. + +## Indexer And Verifier Layer + +Expected responsibilities: + +- Read receipts and logs. +- Derive `txHash` and `logIndex`. +- Reconstruct FlowPulse streams. +- Resolve off-chain artifacts. +- Verify roots, receipts, commitments, attestations, and proofs. +- Produce deterministic verification outputs. + +## AI Memory Layer + +Expected responsibilities: + +- Store and process heavy memory, model, embedding, and artifact data off-chain. +- Commit to important data through roots or receipts. +- Support research into neural geometry, retrieval, continuity, compression, and reliability. + +## Hardware Layer + +Expected responsibilities: + +- Explore FlowRouter hardware. +- Test Meshtastic and LoRa sidecar signaling. +- Prototype 3D-printed enclosures. +- Define device identity, operator controls, and field diagnostics. + +Boundaries: + +- LoRa and Meshtastic are low-bandwidth control channels. +- Heavy data transfer must use appropriate network paths, not radio sidecar links. + +## App Layer + +Expected responsibilities: + +- Dashboard for operators. +- Explorer for protocol and verification state. +- Hardware console for FlowRouter and sidecar status. + +## Future Appchain/L1 Layer + +Expected responsibilities: + +- Research whether FlowMemory needs a dedicated execution, settlement, or verification environment. +- Compare appchain/L1 options against Base-native design. +- Define criteria before implementation. + +## Data Flow Sketch + +1. A protocol action emits events and updates intentional on-chain state. +2. Indexers read receipts and logs after execution. +3. Indexers derive transaction and log metadata. +4. Verifiers check off-chain artifacts against commitments and roots. +5. Apps present state, proofs, and operational health. +6. Hardware sidecars exchange compact control signals where useful. diff --git a/docs/CURRENT_STATE.md b/docs/CURRENT_STATE.md new file mode 100644 index 00000000..ec0deb6d --- /dev/null +++ b/docs/CURRENT_STATE.md @@ -0,0 +1,56 @@ +# Current State + +Last updated: 2026-05-12 + +## Repository State + +The repository is in bootstrap mode. + +Before bootstrap, the repository contained: + +- `README.md` + +This bootstrap pass adds: + +- Agent instructions +- Project docs +- Decision record directory +- Work-area directories +- GitHub issue and pull request templates +- A conservative CI workflow for repository hygiene + +## Implementation State + +No product implementation is present yet. + +- Contracts: not implemented +- Services: not implemented +- Apps: not implemented +- Hardware files: not implemented +- Research artifacts: not implemented +- Cryptographic proof systems: not implemented +- Infrastructure scripts: not implemented + +## Active Boundaries + +- Storage is not free. +- Transaction hashes do not store arbitrary data. +- Uniswap v4 hooks cannot know `txHash` or `logIndex`. +- Indexers and verifiers derive `txHash` and `logIndex` after reading receipts and logs. +- Heavy AI, model, memory, and artifact data stays off-chain. +- On-chain state stores roots, receipts, commitments, attestations, proofs, and work state. +- Meshtastic and LoRa are low-bandwidth control signaling paths, not normal internet bandwidth. + +## Open Questions + +- What is the first minimal FlowPulse event schema? +- What belongs in Rootflow versus Rootfield? +- Which facts require cryptographic receipts or attestations? +- What is the smallest useful indexer/verifier loop? +- What hardware proof-of-concept should FlowRouter start with? +- What AI memory and neural-geometry research artifacts should be tracked first? +- What appchain/L1 research criteria would justify deeper investment? + +## How To Update This File + +Update this file whenever the actual repo state changes in a way that affects new agents. Keep it factual and dated. diff --git a/docs/DECISIONS/README.md b/docs/DECISIONS/README.md new file mode 100644 index 00000000..02f4e54b --- /dev/null +++ b/docs/DECISIONS/README.md @@ -0,0 +1,41 @@ +# Decision Records + +Use this directory for durable architectural and product decisions. + +## Naming + +Use: + +`YYYY-MM-DD-short-title.md` + +Example: + +`2026-05-12-repository-bootstrap.md` + +## Template + +```md +# Title + +Date: YYYY-MM-DD + +## Status + +Proposed | Accepted | Superseded + +## Context + +What problem, constraint, or decision point led to this? + +## Decision + +What are we deciding? + +## Consequences + +What becomes easier, harder, safer, or riskier? + +## Follow-Ups + +What should happen next? +``` diff --git a/docs/FLOWMEMORY_HQ_CONTEXT.md b/docs/FLOWMEMORY_HQ_CONTEXT.md new file mode 100644 index 00000000..66f4a299 --- /dev/null +++ b/docs/FLOWMEMORY_HQ_CONTEXT.md @@ -0,0 +1,69 @@ +# FlowMemory HQ Context + +This document is the shared context packet for FlowMemory agents and contributors. Read it before proposing architecture, implementation, research, hardware, or protocol changes. + +## Project Identity + +FlowMemory is a Base-native AI memory, neural-geometry, reliability, decentralized hardware, and future appchain/L1 project. + +The long-term project shape combines: + +- On-chain roots, receipts, commitments, attestations, proofs, and work state +- Off-chain AI memory, model, artifact, retrieval, and neural-geometry data +- Indexer and verifier services that reconstruct facts from chain receipts and logs +- FlowRouter hardware for resilient local and decentralized connectivity experiments +- Meshtastic and LoRa sidecar signaling for low-bandwidth coordination +- Dashboards, explorers, and hardware consoles for operators and researchers +- Future appchain/L1 research once the protocol surface is mature enough + +## Core Concepts + +### Base And Uniswap v4 Hooks + +FlowMemory is expected to explore Base-native protocol mechanics and Uniswap v4 hooks. Hooks can emit events and update intentional on-chain state, but they cannot know final transaction metadata such as `txHash` or `logIndex` during hook execution. + +### FlowPulse Events + +FlowPulse events are the intended event stream for protocol activity, work lifecycle, routing signals, memory updates, and reliability checkpoints. The exact event schema is not implemented yet and should be designed before contracts or indexers depend on it. + +### Rootflow And Rootfield + +Rootflow and Rootfield refer to state commitment concepts for FlowMemory. They should be treated as commitment layers, not as unlimited data storage. Agents should define what is committed, what stays off-chain, and how verifiers reconstruct or challenge the claimed state. + +### AI Memory And Neural Geometry + +The project includes research into AI memory structures, retrieval, embeddings, semantic geometry, compression, continuity, and reliability. Heavy memory and model artifacts stay off-chain. On-chain records should point to commitments, receipts, and verification state rather than raw model data. + +### FlowRouter Hardware + +FlowRouter is the decentralized internet and local resilience hardware track. It may include routing experiments, operator interfaces, physical enclosures, radio sidecars, and device identity. Hardware tasks must distinguish between product ideas, test rigs, electrical design, firmware, enclosure design, and field validation. + +### Meshtastic And LoRa + +Meshtastic and LoRa are low-bandwidth control signaling paths. They are useful for coordination, pings, device state, compact receipts, or emergency signaling. They are not normal internet bandwidth and must not be designed as if they can carry heavy app, model, media, or artifact payloads. + +## Technical Boundaries + +- Storage is not free. +- Transaction hashes do not store arbitrary data. +- Uniswap v4 hooks cannot know `txHash` or `logIndex`. +- Indexers and verifiers derive `txHash` and `logIndex` after reading receipts and logs. +- Heavy AI, model, memory, and artifact data stays off-chain. +- On-chain state stores roots, receipts, commitments, attestations, proofs, and work state. +- Meshtastic and LoRa are low-bandwidth control signaling paths, not normal internet bandwidth. + +## Intended Work Areas + +- `contracts/`: Base contracts, Uniswap v4 hooks, events, commitments, and protocol state +- `services/`: indexer, verifier, worker, API, and background processing services +- `apps/`: dashboard, explorer, and hardware console experiences +- `hardware/`: FlowRouter, radio sidecars, firmware notes, enclosure models, and field test notes +- `research/`: AI memory, neural geometry, reliability, and future appchain/L1 research +- `crypto/`: receipts, attestations, roots, proofs, verification design, and threat analysis +- `infra/scripts/`: CI, automation, local setup, and maintenance scripts +- `docs/DECISIONS/`: accepted architectural decisions +- `inbox/`: temporary intake area for imported prompts, raw notes, and unsorted context + +## Collaboration Defaults + +Agents should assume the repo is used by multiple agents at once. Keep changes small, avoid unrelated edits, write down decisions, and finish each task with a PR-ready summary. diff --git a/docs/PROJECT_CHARTER.md b/docs/PROJECT_CHARTER.md new file mode 100644 index 00000000..5ace2e66 --- /dev/null +++ b/docs/PROJECT_CHARTER.md @@ -0,0 +1,42 @@ +# Project Charter + +## Mission + +FlowMemory aims to build a trustworthy memory and reliability substrate for AI and decentralized systems, combining Base-native protocol commitments, off-chain verification, neural-geometry research, and resilient hardware experiments. + +## Near-Term Goal + +The near-term goal is to create a clean multi-agent workspace where protocol, service, app, hardware, research, crypto, and security work can proceed without stepping on each other. + +## Long-Term Direction + +FlowMemory may evolve toward a dedicated appchain or L1 if the protocol, memory, reliability, and hardware research justify that path. Appchain/L1 work is research until the architecture and threat model are mature. + +## Principles + +- Keep heavy data off-chain and commit to it intentionally. +- Make verification paths explicit. +- Separate protocol facts from research hypotheses. +- Treat hardware constraints as real constraints. +- Favor durable documentation and decision records over hidden context. +- Use GitHub issues and pull requests as the operational source of truth. + +## Non-Goals During Bootstrap + +- No production contracts. +- No product dashboard. +- No hardware firmware. +- No token mechanics. +- No appchain/L1 implementation. +- No claims that data exists on-chain unless the design explicitly stores or commits it there. + +## Success Criteria + +The repository is ready for multi-agent work when: + +- Agents can orient themselves from `AGENTS.md` and `docs/START_HERE.md`. +- Current state and boundaries are documented. +- Work areas have clear directories. +- Issue and pull request templates exist. +- CI provides basic repository hygiene checks. +- Decisions have a durable home in `docs/DECISIONS/`. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 00000000..267e33a6 --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,55 @@ +# Roadmap + +This roadmap is directional. Use issues and decision records for committed work. + +## Phase 0: Repository Readiness + +- Establish agent instructions and shared context. +- Create work-area directories. +- Add issue and pull request templates. +- Add conservative CI. +- Record architecture, security, roadmap, and current state docs. + +## Phase 1: Protocol Definitions + +- Define FlowPulse event vocabulary. +- Define Rootflow and Rootfield commitment semantics. +- Decide what data is on-chain, off-chain, or derived. +- Draft receipt, attestation, proof, and root formats. +- Document Uniswap v4 hook constraints and Base assumptions. + +## Phase 2: Minimal Indexer And Verifier Loop + +- Read chain receipts and logs. +- Derive `txHash` and `logIndex` from observed logs. +- Reconstruct FlowPulse activity. +- Verify commitments against off-chain artifacts. +- Produce deterministic verification reports. + +## Phase 3: Applications + +- Build an operator dashboard. +- Build a protocol explorer. +- Build a hardware console. +- Make verification state visible and understandable. + +## Phase 4: Hardware Research + +- Define FlowRouter hardware scope. +- Validate Meshtastic and LoRa control-signaling use cases. +- Prototype device identity and compact receipt exchange. +- Develop and test 3D-printed enclosures. + +## Phase 5: AI Memory And Neural Geometry Research + +- Define memory artifact formats and commitments. +- Explore embedding, retrieval, continuity, and reliability metrics. +- Connect research artifacts to verifiable receipts. +- Keep heavy artifacts off-chain. + +## Phase 6: Appchain/L1 Research + +- Define why an appchain or L1 would be needed. +- Compare Base-native, appchain, and L1 tradeoffs. +- Model validator, data availability, verification, and hardware implications. +- Produce a go/no-go decision record before implementation. diff --git a/docs/SECURITY_MODEL.md b/docs/SECURITY_MODEL.md new file mode 100644 index 00000000..5adacbda --- /dev/null +++ b/docs/SECURITY_MODEL.md @@ -0,0 +1,74 @@ +# Security Model + +This document captures initial security assumptions. It is not a final audit model. + +## Assets + +- Private keys and deployer credentials +- RPC credentials and service tokens +- Contract ownership and upgrade controls +- Roots, commitments, receipts, attestations, and proofs +- Indexer and verifier outputs +- Off-chain memory artifacts and research data +- Hardware device identity and operator controls +- CI, release, and deployment credentials + +## Baseline Rules + +- Do not hardcode secrets. +- Do not commit private keys, seed phrases, API keys, RPC credentials, or webhook URLs. +- Keep heavy AI, model, memory, and artifact data off-chain. +- Commit to data intentionally with roots, receipts, attestations, or proofs. +- Treat chain logs as observed facts only after receipts are available. +- Treat hardware control channels as adversarial unless authenticated. + +## Threat Areas + +### Protocol + +- Incorrect assumptions about what hooks know during execution +- Event schemas that cannot be verified later +- Unclear ownership or upgrade authority +- Excessive on-chain storage +- Commitment formats that are ambiguous or replayable + +### Indexers And Verifiers + +- Log parsing errors +- Chain reorg handling gaps +- Incorrect `txHash` or `logIndex` derivation +- Non-deterministic verification output +- Trusting off-chain artifacts without checking commitments + +### AI Memory + +- Sensitive memory leakage +- Unbounded artifact storage +- Weak provenance +- Confusing model output with verified state +- Embedding or retrieval data that cannot be traced to a receipt + +### Hardware + +- Unauthenticated control messages +- Device identity spoofing +- Physical tampering +- Unsafe power or enclosure assumptions +- Overestimating LoRa or Meshtastic bandwidth + +### Supply Chain + +- Unpinned dependencies +- Unreviewed scripts +- CI secrets exposure +- Binary artifacts without provenance + +## PR Security Checklist + +- Does this change introduce or require secrets? +- Does it change trust assumptions? +- Does it change contract, receipt, proof, or attestation semantics? +- Does it depend on `txHash` or `logIndex` before a receipt exists? +- Does it place heavy data on-chain? +- Does it assume LoRa or Meshtastic can carry high-bandwidth traffic? +- Are tests or verification steps included where practical? diff --git a/docs/START_HERE.md b/docs/START_HERE.md index 4c70723e..d38c518e 100644 --- a/docs/START_HERE.md +++ b/docs/START_HERE.md @@ -1,6 +1,24 @@ -# START_HERE +# Start Here -## How to run multiple Codex agents safely from E drive +This is the first document to read after `AGENTS.md`. + +## Reading Order + +1. `AGENTS.md` +2. `docs/FLOWMEMORY_HQ_CONTEXT.md` +3. `docs/CURRENT_STATE.md` +4. The task-specific document or issue +5. Any relevant decision records in `docs/DECISIONS/` + +## Before You Edit + +- Confirm the assigned scope. +- Check the current branch and working tree. +- Read the files you plan to edit. +- Identify whether the task is docs, protocol, service, app, hardware, research, crypto, infra, or security work. +- If the task touches architecture, security assumptions, public schemas, or cross-agent workflow, update docs in the same pull request. + +## Multi-Agent Worktree Setup Use one Git worktree per Codex agent. Each worktree has its own branch and folder under `E:\FlowMemory`, so agents can work without sharing the same checkout. @@ -66,10 +84,30 @@ cd E:\FlowMemory\flowmemory-review codex ``` -Safety rules: +## Multi-Agent Safety Rules - Keep `E:\FlowMemory\flowmemory-main` as the main checkout and coordination point. - Run each agent only inside its assigned worktree folder. - Check `git status --short --branch` before starting and before handing off work. - Avoid assigning two agents to edit the same files at the same time. - Use `git worktree list` from `E:\FlowMemory\flowmemory-main` to inspect all local worktrees. + +## During Work + +- Keep changes small and reviewable. +- Do not edit unrelated files. +- Do not hardcode secrets. +- Add tests where practical. +- Document open questions instead of silently inventing protocol facts. +- Prefer explicit boundaries over vague claims. + +## Before You Finish + +Run the checks that exist for the area you touched. If no test suite exists yet, say that clearly. + +End with a PR-ready summary: + +- What changed +- Why it changed +- Tests or checks run +- Risks, assumptions, and follow-ups diff --git a/hardware/.gitkeep b/hardware/.gitkeep new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/hardware/.gitkeep @@ -0,0 +1 @@ + diff --git a/inbox/claude-code/.gitkeep b/inbox/claude-code/.gitkeep new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/inbox/claude-code/.gitkeep @@ -0,0 +1 @@ + diff --git a/inbox/old-prompts/.gitkeep b/inbox/old-prompts/.gitkeep new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/inbox/old-prompts/.gitkeep @@ -0,0 +1 @@ + diff --git a/inbox/unsorted/.gitkeep b/inbox/unsorted/.gitkeep new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/inbox/unsorted/.gitkeep @@ -0,0 +1 @@ + diff --git a/infra/scripts/.gitkeep b/infra/scripts/.gitkeep new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/infra/scripts/.gitkeep @@ -0,0 +1 @@ + diff --git a/research/.gitkeep b/research/.gitkeep new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/research/.gitkeep @@ -0,0 +1 @@ + diff --git a/services/.gitkeep b/services/.gitkeep new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/services/.gitkeep @@ -0,0 +1 @@ +