Flow Memory

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

Developer alpha quickstart

git clone https://github.com/FlowmemoryAI/flow-memory.git
cd flow-memory
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,ml]"
python -m flow_memory --neural tiny_torch --json "Explore and report"

Neural models advise. Policy and approval gates remain authoritative.

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

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. It does not claim audited contracts, hardened sandboxing, production API authentication, mainnet readiness, safe real-funds custody, or trained ML model performance.

Install

PowerShell:

cd E:\FlowMemory\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

.\.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

Observed during the public-alpha RC1 preflight build:

• Python tests: 287 passed, 1 skipped
• FlowLang compile demo: passed
• FlowLang runtime demo: passed
• FlowLang economy demo: passed
• CLI smoke: passed
• CLI --flow: passed
• deployment dry-run scripts: passed
• agent reliability gauntlet demo: passed
• adversarial economy simulation demo: passed
• clean clone validation: passed
• public-alpha release decision: passed

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/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/PRODUCTION_READINESS.md
• BUILD_REPORT.md
• FLOW_MEMORY_STATUS.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.

Neural Agent Layer v1

Flow Memory now includes an optional Neural Agent Layer v1. 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. 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.