Flow Memory

Flow Memory is an open-source autonomous AI agent operating system and local/testnet public-alpha preflight prototype.

Current build update

• receipted-memory/: Receipted Memory MV3 extension, local AES-GCM memory vault, Claude/ChatGPT release gate, P-256 signed disclosure receipts, hash-chained receipt log, compliance ZIP export, and offline verifier package.
• mandate/: Mandate Companion MV3 extension, local mandate signing, executor-gated browser actions, signed action ledger, encrypted BYO provider-key storage, revocation records, redacted export, demo harness, and offline verifier.
• sovereign/: Sovereign local-first kernel, setup wizard, local runtime adapters, and model-weight-manifest/1 package APIs for caller-supplied local model file names/hashes/metadata only. These manifests do not bundle or download weights, prove hash-source authenticity without user trust, prove execution, prove model quality, or protect against tampered runtimes/devices.
• Store, verifier distribution, coverage gaps, and user handoff docs: STORE_LISTING.md, privacy-policy.md, terms.md, SUPPORT.md, docs/VERIFIER_DISTRIBUTION.md, docs/COVERAGE_GAPS.md, docs/EXTENSION_USER_HANDOFF.md, and docs/PUBLIC_INSTALL_HANDOFF.md.

Public alpha quickstart

For a scrubbed GitHub-friendly handoff with install commands, install doctor commands, reproducible verification commands, Mermaid diagrams, artifact ownership rules, and public-alpha boundaries, see docs/PUBLIC_INSTALL_HANDOFF.md.

Windows PowerShell:

git clone https://github.com/FlowmemoryAI/flow-memory.git
cd flow-memory
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
python -m flow_memory own launch
python -m flow_memory own kit --out-dir owned-ai-launch-kit --zip owned-ai-launch-kit.zip
python -m flow_memory own remember "Flow Memory should remember that I want a local-first AI." --tag preference
python -m flow_memory own learn "I completed local setup" --outcome "Prefer one-command setup with receipts" --tag setup
python -m flow_memory own walkthrough --out-dir owned-ai-walkthrough --json
python -m flow_memory own learn-source owned-ai-walkthrough/owned-ai-source-events --tag setup
python -m flow_memory own export-bundle --out owned-ai-transfer.json
python -m flow_memory own import-bundle owned-ai-transfer.json
python -m flow_memory own ask "What should my AI remember?" --out owned-ai-demo.html --receipt-out owned-ai-answer-receipt.json
python -m flow_memory own device --identity owned-ai-device.json --name "This device" --json
python -m flow_memory own sign-receipt --file owned-ai-answer-receipt.json --identity owned-ai-device.json --out owned-ai-answer-signature.json --json
python -m flow_memory own verify-signature --signature owned-ai-answer-signature.json --identity owned-ai-device.json --json
python -m flow_memory own app --out owned-ai-app.html
python -m flow_memory own audit --file owned-ai-app.html --json
python -m flow_memory own prove --out release/owned-ai-cli-no-network.json --json
python -m flow_memory own prove --installed --out release/owned-ai-installed-no-network.json --json
python -m flow_memory own surfaces --json
python -m flow_memory install bootstrap --out-dir owned-ai-install --json
python -m flow_memory install guide --install-dir owned-ai-install --out owned-ai-install-guide.md
python -m flow_memory install claims --zip owned-ai-install.zip --json
python -m flow_memory own doctor --json
python -m flow_memory own audit-kit --dir owned-ai-launch-kit --json
python -m flow_memory own claim-status
python -m flow_memory own claim-status --json
python -m flow_memory own claim-plan --out owned-ai-claim-plan.md
python -m flow_memory own claim-instructions --all --json
python -m flow_memory own validate-inputs --manifest release/evidence/drills/signed-consumer-distribution-proof/_source/pending-input-manifest.json --input SignedInstallerManifestPath=installer-manifest.json --json
python -m flow_memory own claim-plan --json
python -m flow_memory own claim-roadmap --out owned-ai-claim-roadmap.md
python -m flow_memory own claim-acceptance --out owned-ai-claim-acceptance.md
python -m flow_memory own claim-roadmap --json
python -m flow_memory own claim-copy --out owned-ai-claim-copy.md --json
python -m flow_memory own copy-audit --file public-copy.md --json
python -m flow_memory own copy-audit --dir public-copy --json
python -m flow_memory own helper-smoke --evidence-root release/evidence/drills/helper-packaging-smoke --json
python -m flow_memory own claims --json
python -m flow_memory own browser-proof --out release/owned-ai-browser-no-network.json --json
python -m flow_memory own runtime "What should my local model answer?" --out owned-runtime-receipt.json
python -m flow_memory --json "Explore and report"
python -m flow_memory install doctor --json

Linux/macOS:

git clone https://github.com/FlowmemoryAI/flow-memory.git
cd flow-memory
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
python -m flow_memory install bootstrap --out-dir owned-ai-install --json
python -m flow_memory install verify --dir owned-ai-install --json
python -m flow_memory install verify --zip owned-ai-install.zip --json
python -m flow_memory install guide --install-dir owned-ai-install --out owned-ai-install-guide.md
python -m flow_memory install claims --zip owned-ai-install.zip --json
python -m flow_memory own launch
python -m flow_memory own kit --out-dir owned-ai-launch-kit --zip owned-ai-launch-kit.zip
python -m flow_memory own remember "Flow Memory should remember that I want a local-first AI." --tag preference
python -m flow_memory own learn "I completed local setup" --outcome "Prefer one-command setup with receipts" --tag setup
python -m flow_memory own walkthrough --out-dir owned-ai-walkthrough --json
python -m flow_memory own learn-source owned-ai-walkthrough/owned-ai-source-events --tag setup
python -m flow_memory own ask "What should my AI remember?" --out owned-ai-demo.html
python -m flow_memory own export-bundle --out owned-ai-transfer.json
python -m flow_memory own import-bundle owned-ai-transfer.json
python -m flow_memory own app --out owned-ai-app.html
python -m flow_memory own audit --file owned-ai-app.html --json
python -m flow_memory own prove --out release/owned-ai-cli-no-network.json --json
python -m flow_memory own claim-status
python -m flow_memory own claim-status --json
python -m flow_memory own claim-plan --out owned-ai-claim-plan.md
python -m flow_memory own claim-plan --json
python -m flow_memory own claim-instructions --all --json
python -m flow_memory own validate-inputs --manifest release/evidence/drills/signed-consumer-distribution-proof/_source/pending-input-manifest.json --input SignedInstallerManifestPath=installer-manifest.json --json
python -m flow_memory own claim-roadmap --out owned-ai-claim-roadmap.md
python -m flow_memory own claim-roadmap --json
python -m flow_memory own claim-acceptance --json
python -m flow_memory own prove --installed --out release/owned-ai-installed-no-network.json --json
python -m flow_memory own claims --json
python -m flow_memory own runtime "What should my local model answer?" --out owned-runtime-receipt.json
python -m flow_memory own browser-proof --out release/owned-ai-browser-no-network.json --json
python -m flow_memory --json "Explore and report"
python -m flow_memory install doctor --json

Fastest path: python -m flow_memory own launch writes the self-contained browser app and opens it with the OS browser. Open owned-ai-app.html for the interactive browser app, or owned-ai-demo.html for the receipt generated from the CLI flow. Both are self-contained local files; no account, provider key, hosted server, or model download is required. The browser app stores memory in browser localStorage, records explicit user-triggered learning events, and can move memory through user-carried transfer bundles. The CLI can ingest user-selected permissioned source directories with receipts and also move the store through user-carried transfer bundles. The app can download/import memory JSON, seal/download/import a passphrase-encrypted AES-GCM vault from user-selected local files, clear the plaintext browser store after sealing, and copy/download answer or learning receipts.

One-command local install bundle: python -m flow_memory install bootstrap --out-dir owned-ai-install --json writes top-level START_HERE.html, a top-level README.md, root launchers (START_OWNED_AI.cmd and START_OWNED_AI.sh), portable local verifier files (VERIFY_INSTALL.html, VERIFY_INSTALL.cmd, VERIFY_INSTALL.sh, and self-contained VERIFY_INSTALL.py), EVIDENCE_INDEX.html, install manifest, whole-install owned-ai-install.zip, launch kit, walkthrough receipts, install doctor result, package-bundled local-runtime receipt, explicit/source/interaction learning boundary, optional scoped proof reports under owned-ai-proof-evidence/, local runtime connector contracts (owned-ai-local-runtime-contract.md and owned-ai-local-runtime-contract.json), explicit-learning connector contracts (owned-ai-learning-contract.md and owned-ai-learning-contract.json), blocked-claim action plan, owned-ai-claim-instructions.md, owned-ai-claim-instructions.json, owned-ai-claim-acceptance.md, owned-ai-claim-acceptance.json, and blocked-claim research roadmap into one folder. Start with owned-ai-install/START_HERE.html, owned-ai-install/EVIDENCE_INDEX.html, owned-ai-install/START_OWNED_AI.cmd on Windows, sh owned-ai-install/START_OWNED_AI.sh on macOS/Linux, or owned-ai-install/owned-ai-launch-kit/owned-ai-app.html directly. Verify by opening owned-ai-install/VERIFY_INSTALL.html, running owned-ai-install/VERIFY_INSTALL.cmd, sh owned-ai-install/VERIFY_INSTALL.sh, or python owned-ai-install/VERIFY_INSTALL.py; the verifiers check the manifest, SHA-256 file hashes, and bundled proof-report boundaries without importing FlowMemory. Keep the start page, README, evidence index, manifest, ZIP, runtime receipt, learning boundary, local runtime connector, explicit-learning connector, claim plan, owned-ai-claim-instructions.md/json, owned-ai-claim-acceptance.md/json, claim roadmap, and proof-evidence folder beside the app so another user can verify the install and the scoped claim boundaries locally. The install bundle also carries owned-ai-current-claim-copy.md and owned-ai-current-claim-copy-audit.json at the root so a recipient has current safe public-alpha copy plus a blocked-phrase audit before changing marketing text. The install bundle also carries owned-ai-user-carried-transfer-contract.md and owned-ai-user-carried-transfer-contract.json so recipients have the local export/import contract for moving a bundle themselves without a Flow Memory relay. The install bundle also carries owned-ai-data-movement-ledger.md and owned-ai-data-movement-ledger.json so recipients can distinguish local-only files from explicit user-carried artifacts before using no-egress language. The install bundle also carries RUN_LOCAL_PROOF_SMOKE.py, RUN_LOCAL_PROOF_SMOKE.cmd, and RUN_LOCAL_PROOF_SMOKE.sh so recipients can exercise deterministic local answer, explicit-learning, and user-carried transfer receipts without importing FlowMemory. The install bundle also carries owned-ai-network-evidence-guide.md, owned-ai-network-evidence-guide.json, and owned-ai-network-evidence-pending-inputs.json so recipients know which OS-wide/live network artifacts are still required before using zero-network/no-server/no-middle wording; the guide points non-developers to the offline start-sovereign-zero-network-release-drill.ps1 -WhatIfOnly checklist without treating that checklist as captured evidence. The install bundle also carries owned-ai-custody-evidence-guide.md and owned-ai-custody-evidence-guide.json so recipients know which sealed-vault, local-device signature, movement-intent, operator-destination, and OS observation artifacts are still required before using stronger no-egress ownership wording. The install bundle also carries owned-ai-live-evidence-dashboard.html and owned-ai-live-evidence-dashboard.json so non-developers can open one static local surface that maps all six blocked broad phrases to the shipped guide/pending-manifest files, safe replacement copy, next local files to open, and a boundary that the dashboard does not prove claims or capture live evidence. The install bundle also carries RUN_NETWORK_EVIDENCE_PREFLIGHT.py, RUN_NETWORK_EVIDENCE_PREFLIGHT.cmd, and RUN_NETWORK_EVIDENCE_PREFLIGHT.sh so recipients can hash and preflight supplied live OS/network evidence paths against the pending manifest without importing FlowMemory; --out-dir writes a hash-only preflight package for review. The install bundle also carries RUN_LIVE_EGRESS_AUDIT.py, RUN_LIVE_EGRESS_AUDIT.cmd, and RUN_LIVE_EGRESS_AUDIT.sh so recipients can snapshot local OS connection state and write hash-only live-egress observation packages without importing FlowMemory; it does not install firewall policy or graduate broad no-egress/zero-network wording. The install bundle also carries RUN_WEBRTC_MANUAL_PATH_AUDIT.html so recipients can open a static manual WebRTC copy/paste path audit page with no configured ICE servers; it helps collect scoped paired-device candidate/session hashes but does not prove broad no-middle claims. The install bundle also carries RUN_FIRST_TIME_SETUP.py, RUN_FIRST_TIME_SETUP.cmd, and RUN_FIRST_TIME_SETUP.sh so recipients can run a first-run readiness helper from the unpacked folder, write owned-ai-first-run-readiness-report.json, and keep broad claims blocked while checking local setup. The install bundle also carries RUN_COPY_AUDIT.py, RUN_COPY_AUDIT.cmd, RUN_COPY_AUDIT.sh, and RUN_COPY_AUDIT.html so recipients can audit edited public copy for the six blocked broad phrases before publishing, with a browser-only option for users without Python. The install bundle also carries RUN_LIVE_EVIDENCE_PACKAGER.html so recipients without Python can hash selected live OS/network/runtime/WebRTC/custody evidence files locally before review; it produces a hash-only index and does not prove broad claims. The install bundle also carries RUN_BROWSER_RUNTIME_EVIDENCE.html so recipients without Python can create a deterministic local answer receipt in the browser; it is scoped runtime evidence and does not prove product-wide local model inference. The install bundle also carries RUN_BROWSER_LEARNING_EVIDENCE.html so recipients without Python can create explicit-event/source learning receipts in the browser; it is scoped learning evidence and does not prove passive learning or model improvement. The install bundle also carries RUN_BROWSER_HANDOFF_EVIDENCE.html so recipients without Python can create user-carried export/import linkage receipts in the browser; it is scoped handoff evidence and does not prove WAN mesh, relay absence, or product-wide no-middle/no-server truth. The install bundle also carries RUN_BROWSER_NETWORK_EVIDENCE.html so recipients without Python can create page-local network API guard receipts in the browser; it is scoped browser evidence and does not prove OS-wide zero-network behavior. The install bundle also carries RUN_BROWSER_CUSTODY_EVIDENCE.html so recipients without Python can create local sealed-export custody receipts in the browser; it is scoped custody evidence and does not prove OS-wide no-egress behavior. The install bundle also carries RUN_BROWSER_SERVER_EVIDENCE.html so recipients without Python can audit selected local files for server/listener/remote-endpoint markers in the browser; it is scoped server-surface evidence and does not prove product-wide no-server truth. The install bundle also carries RUN_FIRST_TIME_SETUP.html so recipients without Python can use a browser-only setup checklist and download a local first-run readiness receipt. Reviewer/operator CLI evidence review: python -m flow_memory own review-evidence --file path/to/evidence.json --json classifies local evidence receipts against the six blocked broad claims, rejects receipts that set broad_claims_graduated: true, and reports covered/missing claim ids without approving marketing copy. The install bundle also carries RUN_LOCAL_RUNTIME_EVIDENCE.py, RUN_LOCAL_RUNTIME_EVIDENCE.cmd, and RUN_LOCAL_RUNTIME_EVIDENCE.sh so recipients can exercise package-bundled deterministic local answer receipts, runtime artifact hashes, provider-denial metadata, and a Python socket-trap observation without importing FlowMemory. The install bundle also carries RUN_LOCAL_LEARNING_EVIDENCE.py, RUN_LOCAL_LEARNING_EVIDENCE.cmd, and RUN_LOCAL_LEARNING_EVIDENCE.sh so recipients can exercise explicit-event/source receipts, no-raw-export metadata, rollback/delete metadata, and a Python socket-trap observation without importing FlowMemory. The install bundle also carries RUN_LOCAL_HANDOFF_EVIDENCE.py, RUN_LOCAL_HANDOFF_EVIDENCE.cmd, and RUN_LOCAL_HANDOFF_EVIDENCE.sh so recipients can exercise user-carried export/import linkage, no-middle observation metadata, no-upload/no-fetch metadata, and a Python socket-trap observation without importing FlowMemory. The install bundle also carries RUN_ALL_LOCAL_CHECKS.py, RUN_ALL_LOCAL_CHECKS.cmd, and RUN_ALL_LOCAL_CHECKS.sh so recipients can run one local check that verifies the manifest and runs the local proof smoke plus standalone local runtime, explicit-learning, user-carried handoff, network-evidence preflight, and live-egress audit helpers without importing FlowMemory. The install bundle also carries RUN_BROWSER_LOCAL_SMOKE.html so recipients without Python can open a static browser-only PASS/FAIL smoke for local answer, explicit-learning, user-carried transfer/import receipts, sealed-vault WebCrypto round-trip, guarded browser network APIs, and a downloadable local proof JSON.

Launch-kit handoff: run python -m flow_memory own kit --out-dir owned-ai-launch-kit --zip owned-ai-launch-kit.zip for a quick folder/ZIP; add --include-proof when you also want proof files. Then open owned-ai-launch-kit/owned-ai-app.html in a browser and keep owned-ai-launch-kit/README.md, owned-ai-launch-kit/CLAIMS.md, owned-ai-launch-kit/CLAIM_PLAN.md, owned-ai-launch-kit/CLAIM_ROADMAP.md, and owned-ai-launch-kit/TRANSFER.md beside it for the exact next commands, scoped claim copy, ordered live-evidence steps, claim research tracks, and transfer boundaries.

For a live browser proof beyond static marker checks, run python -m flow_memory own browser-proof --out release/owned-ai-browser-no-network.json --json; add --netlog --out release/owned-ai-browser-netlog-no-network.json for a browser-process NetLog capture. The default report captures one generated file:// owned-AI app session in a Chromium/Edge page target and records zero observed HTTP/HTTPS/WebSocket/FTP requests for that page when the report is ok: true; it is not OS-wide traffic proof and does not support broad all-network/all-serverless wording.

For a Python CLI proof, run python -m flow_memory own prove --out release/owned-ai-cli-no-network.json --json. For installed-wheel proof, run python -m flow_memory own prove --installed --out release/owned-ai-installed-no-network.json --json; it builds/installs a local wheel in a fresh venv, clears the setup guard log, and then proves the installed owned-AI command flow. A passing report means the guarded own learn/own learn-source/own export-bundle/own import-bundle/own ask/own runtime/own app/own audit flow made zero observed Python socket, DNS, urllib, HTTP connection, socketserver bind, or asyncio server-start attempts; it is not OS-wide, browser-wide, package-install, native-extension, or caller-runtime proof. For installability, python -m flow_memory install doctor --package-install --json builds a non-editable wheel in a fresh venv and then runs the installed own doctor and own walkthrough product probes.

To generate local-answer evidence immediately after install, run python -m flow_memory own runtime-evidence --json. By default it hashes the package-bundled deterministic local runtime, writes local provenance, enables the Python no-network guard, invokes the runtime through the owned-AI JSON seam, and writes the six runtime-evidence artifacts used by the real-runtime claim drill. Those artifacts are capture-ready for the serverless evidence-status/package-create verifier, while still carrying the bundled-runtime boundary. To move beyond that scoped bundled runtime toward a caller-owned local model, pass --model-artifact <local-model.gguf> --license-file <model-license.txt> --command "<local-runtime-command>" --python-network-guard --operator-attests-real-local-model --json. Broad local-answer wording stays blocked unless real model, license, no-network, and review evidence are supplied.

To generate explicit local-learning evidence immediately after install, run python -m flow_memory own learning-evidence --json. By default it creates a package-generated permissioned-source fixture, runs explicit-event plus user-selected-source learning under a Python network trap, writes the seven production-learning drill artifacts, and omits raw examples from those artifacts. Those artifacts are capture-ready for the serverless evidence-status/package-create verifier, while still carrying the generated-source boundary. To exercise a reviewed user-selected source through the combined blocked-claim drill, run python -m flow_memory own claim-drill --source-dir <reviewed-permissioned-source-dir> --operator-attests-permissioned-sources --out-dir release/evidence/owned-ai-claim-drill-bundle --out release/claim-drill-bundle.json --json; this can clear the scoped non-fixture learning-drill blocker while keeping passive/product-wide improvement wording blocked until live trainer/runtime and quality evidence are reviewed.

Before handing live files to a claim helper, run python -m flow_memory own validate-inputs --manifest <pending-input-manifest.json> --input RequiredName=path/to/live-file --json. It checks the manifest-required input names, file existence, and rejects pending manifests, templates, preflight-only files, and synthetic helper-smoke fixtures. It does not prove the files are truthful; it prevents accidentally packaging setup templates as live evidence.

To prove the current no-middle handoff boundary, operators can run python -m flow_memory own handoff-evidence --json. It exercises local export/import transfer files under a Python network trap and writes hash-only artifacts proving this drill used no Flow Memory upload, fetch, relay, server, or account path. This supports user-carried setup/handoff evidence only; it is not WAN mesh, remote peer liveness, transport-security, or broad no-server/no-network proof.

For a research-grade view of how blocked phrases can be retired, scoped, or eventually graduated, run python -m flow_memory own claim-roadmap --out owned-ai-claim-roadmap.md or python -m flow_memory own claim-roadmap --claim no-server-ever --json. The roadmap separates literal-retirement work from live evidence capture, benchmark/runtime work, and safe scoped wording; it is planning only, not proof. For exact pass/fail criteria per blocked phrase, run python -m flow_memory own claim-acceptance --out owned-ai-claim-acceptance.md or python -m flow_memory own claim-acceptance --claim zero-network-requests --json. The acceptance matrix says which evidence, false gates, safe scoped copy, and live helper packages are still required; it is planning only, not proof.

To generate one local package that ties the blocked-claim evidence drills together, run python -m flow_memory own claim-drill --out release/claim-drill-bundle.json --json. It writes runtime, learning, and user-carried handoff drill outputs into one hash-manifested bundle, writes a top-level JSON summary for handoff packaging, shows which broad claims remain blocked, and defaults to the package-bundled deterministic local runtime plus a generated permissioned-source fixture unless you provide real local model/runtime and permissioned source evidence.

For an operator-ready list of what still needs live evidence before any blocked broad phrase can graduate, run python -m flow_memory own claim-plan --out owned-ai-claim-plan.md or python -m flow_memory own claim-plan --claim no-server-ever --json. The plan copies the exact WhatIf helper, pending-input manifest, template directory, required live flags, required operator inputs, package path, and safe scoped wording for each blocked phrase. It is a handoff checklist only; it does not run privileged drills or make the broad claims true.

Launch paths:

python scripts/launch_local_agent.py --goal "Explore and report"
python scripts/launch_flowlang_agent.py examples/flowlang_agent.flow --goal "Run the declared agent"
pip install -e ".[dev,ml]"
python scripts/launch_neural_agent.py --backend tiny_torch --goal "Explore and report"
python -m flow_memory --neural tiny_torch --neural-live --json "Explore and report"
python -m flow_memory neural live step --backend tiny_torch --goal "Explore and report"
python -m flow_memory launch agent --template live-research --neural tiny_torch --ticks 5 --emit-visual --json
python -m flow_memory launch agent --flow examples/live_research_agent.flow --ticks 5 --emit-visual --json
python -m flow_memory launch runs list --json
python -m flow_memory launch runs replay <run_id> --json
python -m flow_memory launch runs export <run_id> --out artifacts/launch/bundles/<run_id>.json --json
python -m flow_memory launch bundle public-alpha --out artifacts/launch/bundles/public-alpha-local-demo.json --json
python -m flow_memory launch visual embodiment --run live-agent-supervisor --out dashboard/src/mock-data/live-neural-embodiment.json --json
python -m flow_memory launch finalize public-alpha --out release_evidence/public_alpha_launch_finalizer.json --json
python -m flow_memory cognition predict --goal "verify dashboard" --action "check mission-control route" --json
python -m flow_memory cognition tick --agent live-research --goal "verify dashboard is serving real Mission Control" --json
python -m flow_memory launch supervisor start --template live-research --neural tiny_torch --predictive-core --ticks 5 --emit-visual --json
python -m flow_memory cognition benchmark run --scenario dashboard-stale-server --trials 5 --json
python -m flow_memory cognition benchmark run --scenario all --trials 5 --json
python -m flow_memory cognition lessons consolidate --json
python -m flow_memory cognition metrics --json
python -m flow_memory genesis archetypes list --json
python -m flow_memory genesis birth --user local-user --name Mira --archetype research-builder --purpose "Help me build Flow Memory" --instinct careful --instinct builder --consent private_only --json
python -m flow_memory genesis passport show <agent_id> --json
python -m flow_memory genesis mirror show <agent_id> --json
python -m flow_memory graph build --json
python -m flow_memory graph proofs list --json
python -m flow_memory graph reputation list --json
python -m flow_memory internet agents register --agent mira --json
python -m flow_memory internet skills publish --agent mira --skill research --skill memory --json
python -m flow_memory internet skills match --agent mira --task "build an agent skill matcher" --required-skill coding --required-skill verification --json
python -m flow_memory internet payment-intent simulate --from mira --to helper-agent --resource skill_match --amount 0.01 --json
python scripts/run_local_network.py --scenario all --json-out artifacts/network/local_network_report.json
python scripts/run_agent_learning_loop.py
python scripts/test_full_system.py --quick --json-out artifacts/full_system/quick_report.json
python scripts/run_local_network.py --scenario all --emit-visual-events --json-out artifacts/network/local_network_report.json
python scripts/export_visual_replay.py artifacts/network/local_network_report.json --out dashboard/src/mock-data/local-network-replay.json
python scripts/validate_visual_replay.py dashboard/src/mock-data/local-network-replay.json
python -m flow_memory compute plan --goal "Use budgeted local compute routing with dry-run settlement"
python -m flow_memory agent-builder defaults --json
python -m flow_memory agent-builder plan --name Mira --archetype research-builder --purpose "Help me build Flow Memory" --json
python -m flow_memory agent-builder birth --name Mira --archetype research-builder --purpose "Help me build Flow Memory" --json
python -m flow_memory agent-builder simulate-upgrades --agent <agent_id> --byok --wallet --onchain-dry-run --json

Neural, neural-live, RL, and compute-market signals advise. Policy and approval gates remain authoritative.

Mission Control visual path:

python scripts/run_local_network.py --scenario all --emit-visual-events --json-out artifacts/network/local_network_report.json
python scripts/export_visual_replay.py artifacts/network/local_network_report.json --out dashboard/src/mock-data/local-network-replay.json
python scripts/run_local_api_server.py --host 127.0.0.1 --port 8765
python -m flow_memory launch visual embodiment --run live-agent-supervisor --out dashboard/src/mock-data/live-neural-embodiment.json --json
python -m flow_memory launch finalize public-alpha --out release_evidence/public_alpha_launch_finalizer.json --json
cd dashboard
npm run build
npm test

Mission Control is connected to local state/replay/API data, with mock fallback clearly labeled. Live 3D Mode renders the neural embodiment as read-only local/replay telemetry; it is not an agent launcher, provider connector, settlement console, or policy bypass. cd dashboard && npm run dev serves the real Mission Control replay UI at /mission-control with the run selector, neural embodiment panel, Live 3D Mode, GPU evidence status, and public-alpha finalizer status from local fixtures. It does not expose unsafe write/control endpoints. Flow Memory Agent Builder is available at /agents/new in the dashboard dev server. It is the browser front door for first-agent birth: the first agent requires no wallet/API key/funds, private memory is default, network learning is opt-in, and BYOK, wallet identity, on-chain dry-run, and x402 dry-run route composition stay optional after birth. Flow Memory iPhone Agent Bridge is available at /phone-agent: a Sendblue/iMessage-first setup path for max-allowed iPhone access through a foreground web relay, Home Screen PWA metadata, Google Gmail/Calendar OAuth setup metadata, and optional no-Mac TestFlight companion with Microphone/Speech, Photo Library, HealthKit, Contacts, Location, EventKit, ReplayKit, and LiDAR/AR permission surfaces. It does not grant hidden full-device control, bypass iOS privacy prompts, or export raw phone data by default. The native iOS TestFlight companion now acts as a real iPhone perception layer for Flow Memory: it includes backend connection, Keychain token storage, semantic event models, a privacy-filtered local event queue, Core Motion state changes, Core Location place events, device battery/network context, NFC object tags, camera-on-demand observations, RoomPlan/LiDAR room summaries, object memory, agent chat, and compute eligibility simulation. It uploads semantic events by default, not raw surveillance streams. Predictive Cognition is available in CLI/API/replay mode: agents encode current state, retrieve similar experience records, predict candidate outcomes, score counterfactuals, observe actual results, compute prediction error, and write lessons under artifacts/cognition/experiences/. Predictive Learning Benchmark and memory consolidation are available in CLI/API/replay mode: repeated local scenarios write experience records, consolidate reusable lessons under artifacts/cognition/lessons/, reuse those lessons before later predictions, and export benchmark records under artifacts/cognition/benchmarks/. Agent Genesis is available in CLI/API/replay mode: birth a policy-gated agent with purpose, instincts, boundaries, private memory seed, genome, first prediction, mirror, passport, and private-only network learning by default. No download is required for the first agent concept; a local node download is optional for private tools, private compute, or compute contribution. Experience Graph + Proof of Learning is available in CLI/API/replay mode: local prediction/action/outcome records become graph edges, learned lessons become proof records under artifacts/experience_graph/proofs/, and agent reputation is scored from prediction accuracy, policy compliance, lesson usefulness, and private-payload exclusion. Agent Internet + Skill Matcher is available in CLI/API/replay mode: local agent nodes publish policy-gated identities and skill manifests, match collaborators by skills/reputation/privacy/policy fit, open structured shared workspaces, record collaboration graph edges, and expose MCP/x402/ERC-8004 adapter seams as local dry-run/export-only records.

The project now combines:

• FlowLang v0 agent declarations
• FlowIR manifests
• first-class AI agent profiles/state/goals/planning/execution
• layered memory and constitutional memory governance
• safe skill/tool execution seams
• local Economy V3 marketplace, escrow, settlement, disputes, slashing, reputation, receipts
• signed manifest/receipt/provenance prototypes
• SQLite durable storage
• internal API router and optional server seams
• Base Sepolia / ERC-4337 dry-run adapters
• sandbox hardening interfaces
• MCP/A2A/libp2p protocol seams
• dashboard scaffold and CI workflows
• Flow Memory Compute Market dry-run provider/route/quote/settlement simulation
• Live Agent Launchpad for one-command local neural-live agent runs and Mission Control replay artifacts
• Live Agent Operations registry for local run inspection, replay lookup, safe stop/no-op handling, and bundle export
• Bounded Live Agent Supervisor with heartbeat/status artifacts, continuation semantics, and Mission Control supervisor replay
• Mission Control run console for launchpad, operations, supervisor, and local-network replay fixture selection/status summaries
• Public-alpha local demo bundle export with replay references, docs, commands, release evidence, GPU status, and honest limitations
• Mission Control neural embodiment view for visible local neural runtime/session, loop phase, memory, learning, policy, supervisor heartbeat, and imported GPU evidence status
• Mission Control Live 3D Mode for read-only CSS 3D/WebGL-ready local neural embodiment telemetry with policy/approval authority intact
• Public-alpha local launch finalizer evidence for local demo bundle, Live 3D mode, launch evidence, release decisions, and backup exclusion checks for generated local artifacts
• Predictive Cognitive Core for local deterministic world-state encoding, candidate action prediction, counterfactual scoring, prediction-error records, experience memory, FlowLang cognition blocks, read-only Mission Control cognition telemetry, and policy-gated learning metadata
• Predictive Learning Benchmark and memory consolidation for deterministic local scenario replay, before/after prediction-accuracy metrics, consolidated lessons, lesson reuse, repeated-mistake reduction, and policy-authoritative benchmark evidence
• Agent Genesis and Network Learning Protocol for private-by-default agent birth, Agent Genomes, Memory Seeds, instincts, boundaries, first predictions, Agent Mirrors, Agent Passports, human teaching events, sanitized opt-in contributions, and Mission Control genesis telemetry
• Experience Graph + Proof of Learning ledger for graphing agents, goals, predictions, actions, outcomes, prediction errors, lessons, policy decisions, contributions, proof records, and learning reputation while excluding private payloads by default
• Agent Internet + Skill Matcher + Collaboration Graph for local agent identity registry, skill manifests, deterministic collaborator ranking, policy-gated shared workspaces, project graph edges, local reputation, MCP manifest quarantine, x402 dry-run payment intent records, and ERC-8004 export-only adapter files
• Flow Memory Agent Builder browser builder for /agents/new, first-agent no wallet/API key/funds onboarding, Capability Composer, Agent Internet handoff, optional BYOK/wallet/on-chain/x402 dry-run upgrades, Mission Control handoff, and read-only demo fixtures

Public-alpha RC1 preflight adds clean-clone validation, an agent reliability gauntlet, asymmetric/DID signing seams, scoped API/auth/error contracts, typed dashboard mock API client, Base Sepolia dry-run artifacts, expanded contract security tests, optional Docker sandbox backend seam, storage replay scripts, adversarial economy simulation, and hashed release evidence. Flow Memory is production-shaped, not production-certified, not an AGI/sentience claim, not audited, and not mainnet-ready. It does not claim audited contracts, hardened sandboxing, production API authentication, safe real-funds custody, provider settlement, trained production ML model performance, bundled/downloaded model weights, model-weight authenticity without trusted caller-supplied hashes, faithful model execution, model quality, or tampered-runtime protection.

Install

PowerShell:

cd flow-memory
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

If no virtual environment exists:

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

Validate

Fast public install check:

.\.venv\Scripts\python.exe -m flow_memory install goal --json
.\.venv\Scripts\python.exe -m flow_memory install doctor --json
.\.venv\Scripts\python.exe -m flow_memory install doctor --smoke --full --target public-alpha-local-launch --json

Full developer validation:

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe examples\flowlang_compile_demo.py
.\.venv\Scripts\python.exe examples\flowlang_runtime_demo.py
.\.venv\Scripts\python.exe examples\flowlang_economy_demo.py
.\.venv\Scripts\python.exe -m flow_memory --json "Explore and report"
.\.venv\Scripts\python.exe -m flow_memory --flow examples\flowlang_agent.flow --json "Run the declared agent"
bash scripts/verify.sh
.\.venv\Scripts\python.exe scripts\generate_deployment_plan.py
.\.venv\Scripts\python.exe scripts\base_sepolia_dry_run.py
docker compose config
forge build
forge test
git diff --check
.\.venv\Scripts\python.exe scripts\public_alpha_smoke.py --root .
.\.venv\Scripts\python.exe scripts\clean_clone_validation.py --root . --out release_evidence\clean_clone_validation.json
.\.venv\Scripts\python.exe scripts\validate_base_sepolia_artifacts.py --dir deployments\base-sepolia
.\.venv\Scripts\python.exe scripts\export_event_log.py
.\.venv\Scripts\python.exe scripts\replay_event_log.py
.\.venv\Scripts\python.exe scripts\verify_storage_integrity.py
.\.venv\Scripts\python.exe scripts\sandbox_smoke_test.py
.\.venv\Scripts\python.exe scripts\release_decision.py --target public-alpha

Current verification should be generated by the reader in the current checkout. Use the reproducible commands in docs/PUBLIC_INSTALL_HANDOFF.md instead of copying old pass counts or one-machine release claims.

Run FlowLang agent

.\.venv\Scripts\python.exe -m flow_memory --flow examples\flowlang_agent.flow --json "Run the declared agent"

Run examples

.\.venv\Scripts\python.exe examples\agent_profile_demo.py
.\.venv\Scripts\python.exe examples\agent_economy_v3_demo.py
.\.venv\Scripts\python.exe examples\agent_dispute_slashing_demo.py
.\.venv\Scripts\python.exe examples\signed_manifest_demo.py
.\.venv\Scripts\python.exe examples\storage_persistence_demo.py

Important docs

• docs/AI_AGENT_LAYER.md
• docs/PUBLIC_ALPHA_QUICKSTART.md
• docs/LIVE_AGENT_LAUNCHPAD.md
• docs/NEURAL_LIVE_AGENTS.md
• docs/PUBLIC_ALPHA_READINESS.md
• docs/CLEAN_CLONE_VALIDATION.md
• docs/TESTNET_PREFLIGHT.md
• docs/RELEASE_GATES.md
• docs/CONTRACT_SECURITY_TESTS.md
• docs/DASHBOARD.md
• docs/AUDIT_REPLAY.md
• docs/ADVERSARIAL_ECONOMY_SIMULATION.md
• docs/AGENT_ECONOMY_V3.md
• docs/FLOWLANG_RUNTIME_INTEGRATION.md
• docs/STORAGE.md
• docs/SIGNED_MANIFESTS.md
• docs/API_SERVER.md
• docs/WEB3_ADAPTERS.md
• docs/BASE_SEPOLIA_DEPLOYMENT.md
• docs/SANDBOX_HARDENING.md
• docs/PROTOCOL_GATEWAYS.md
• docs/THREAT_MODEL.md
• docs/SQUIRE_GOAL.md
• docs/PRODUCTION_READINESS.md
• BUILD_REPORT.md
• FLOW_MEMORY_STATUS.md
• docs/MISSION_CONTROL_QUICKSTART.md
• docs/PREDICTIVE_COGNITIVE_CORE.md
• docs/PREDICTIVE_LEARNING_BENCHMARK.md
• docs/AGENT_BUILDER.md

Honest limitations

• FlowLang remains v0/prototype.
• Economy V3 is local/testnet-ready architecture, not a live funds system.
• Contracts are unaudited.
• Signing uses local HMAC by default plus local deterministic asymmetric seams; production key custody is not implemented.
• Base Sepolia scripts produce dry-run payloads and artifacts only.
• Sandbox hardening includes profiles, receipts, policy checks, and an optional Docker backend seam; default local sandboxing is not hardened isolation.
• Protocol gateways are local/offline-safe seams, not production transports.
• Dashboard is a typed mock API scaffold, not a live operator console.
• Compute Market integration is local dry-run planning/routing only; it does not move funds, broadcast transactions, call providers, or imply settlement execution.
• Predictive learning benchmarks are scoped to deterministic local Flow Memory scenarios and do not provide broad external forecasting.
• Flow Memory Agent Builder creates first agents in the browser without wallet/API key/funds; BYOK, wallet identity, on-chain dry-run, and x402 dry-run routes are optional post-birth simulations unless future audited modes are explicitly added.

Neural Agent Layer v1

Flow Memory now includes an optional Neural Agent Layer v1 and a local neural-live runtime for public-alpha agents. The base install still has no PyTorch requirement. Install flow-memory[ml] to run tiny CPU-safe PyTorch prototypes for dual-stream perception, appearance-suppressed dorsal motion, tiny JEPA-style world modeling, advisory plan scoring, skill routing, risk scoring, and neural memory retrieval. Neural-live mode adds local runtime sessions, deterministic perception/prediction/plan/risk/learning telemetry, metadata-only checkpoints, and Mission Control replay signals. V-JEPA 2 and VideoMAE are adapter seams that require explicit local checkpoints; Flow Memory never downloads checkpoints automatically. Neural scores never override policy or approval gates.

Local HTTP API server

Flow Memory now includes a dependency-free local HTTP API server for public-alpha operator testing. Run it with python scripts/run_local_api_server.py --host 127.0.0.1 --port 8765. Add --api-key dev-local-only --require-scopes to exercise local API-key and scope gates. This is not production internet authentication; it is a local server boundary for smoke tests, demos, and preflight tools.

Flow Arena RL + Neural Evidence RC update

This repo now includes Flow Arena, a dependency-free local RL environment layer for agent-economy decision training, plus GPU evidence import/release-gate seams. RL policies are advisory only; policy, approval, autonomy, and economy risk controls remain authoritative. Neural GPU validation evidence is stored as text/JSON metadata and hashes; raw checkpoint/model artifacts are not committed.

Live Agent Supervisor

python -m flow_memory launch supervisor start --template live-research --neural tiny_torch --ticks 5 --tick-interval-ms 10 --emit-visual --json
python -m flow_memory launch supervisor status --json
python -m flow_memory launch supervisor heartbeat <run_id> --json

The supervisor is local-only, bounded, inspectable, and policy-gated. GPU-gated release targets use imported RunPod evidence and still require current gate evidence.

Mission Control run console and demo bundle:

python -m flow_memory launch bundle public-alpha --out artifacts/launch/bundles/public-alpha-local-demo.json --json
python -m flow_memory launch finalize public-alpha --out release_evidence/public_alpha_launch_finalizer.json --json

The dashboard run selector can inspect Live Neural Agent Launch, Live Agent Operations, Live Agent Supervisor, Live Neural Embodiment, and Local Network Replay fixtures. The bundle is local-only and does not move funds, use private keys, broadcast transactions, or claim production ML certification. Mission Control Live 3D Mode reads the same visible embodiment fixture and keeps it read-only/local-only; the finalizer records Live 3D readiness, public-alpha launch evidence, release decisions, demo bundle status, and generated-local-artifact backup exclusion checks. Predictive Learning Benchmark adds deterministic local scenarios for dashboard stale-server recovery, GPU evidence import, policy denial, compute-market dry-run, and git clean-commit behavior. It writes experience, lesson, and benchmark artifacts under artifacts/cognition/ and exposes Mission Control trend data through dashboard/src/mock-data/predictive-learning-benchmark.json.

Optional BYOK and on-chain upgrade path

Flow Memory keeps the first-agent path simple: first agent does not require wallet/API key/funds. After an agent exists, users can attach optional capability metadata for BYOK provider keys, x402 Base Sepolia payment-route preparation, wallet identity binding, and on-chain dry-run upgrade intents.

flowchart LR
  Birth[Agent Genesis] --> Local[Local Agent Value]
  Local --> BYOK[Optional BYOK Ref]
  Local --> X402[x402 Route Metadata]
  Local --> Wallet[Optional Wallet Identity]
  X402 --> Sepolia[Base Sepolia eip155:84532]
  Wallet --> Prepare[Prepare Dry Run]
  Prepare --> Sign[External Sign Request]
  Sign --> Relay[Relay Disabled]

Loading

x402 support is installable with python -m pip install "x402[fastapi,httpx,evm]>=2.11.0". Flow Memory tracks the x402.org testnet facilitator and Coinbase CDP facilitator metadata, but the public-alpha route is prepare-only by default.

Public-alpha invariants: no raw API keys in artifacts, no private keys, no seed phrases, no funds moved, no transaction broadcast, mainnet writes disabled, and relay disabled by default.