AgentMesh Runtime is a fully local, open-source runtime scaffolding layer for your AI agent: persistent episodic memory across sessions, bounded OODA loop recording, and the ability to pick up cleanly after a crash. Once installed, the intelligence still comes from your agent (Claude Code / OpenClaw / Codex / Hermes / custom) — this layer just handles the dirty work underneath: remembering, recording, recovering. No account, no cloud, free, Apache 2.0.
$ git clone https://github.com/jiyangnan/AgentMesh-Runtime.git && cd AgentMesh-Runtime $ uv sync $ uv run agentmesh-runtime doctor # self-check: Neo4j / SQLite / ledger / checkpoint # Now let your agent drive it (see AGENTS.md): $ uv run agentmesh-runtime memory recall "your query" --top-k 5 $ uv run agentmesh-runtime memory ingest-file ./session.jsonl discord $ uv run agentmesh-runtime rehydrate --write-default --print-path # pick up after restart
Once the session ends, the process restarts, or the context window blows up — yesterday's decisions, the pitfalls you walked into, the failed attempts all go to zero.
AgentMesh Runtime handles the dirty work — memory, loop recording, restart recovery — so your agent can keep going day after day. How it actually thinks and decides stays in its own head.
No hand-waving. The list below is what the code actually does. Decision intelligence still comes from your agent; this layer just handles what's underneath.
Neo4j graph recall, SQLite FTS5 (BM25 + snippet), raw file grep, and an optional Gemini vector backend — four layers of failover. If any backend dies, the others keep serving. Session events, decisions, and lessons learned all recall across runs.
An Observe / Orient / Decide / Act / Verify / Record state machine that drops every step into a durable trace. Real decisions come from your agent — the scaffolding just ensures the steps happen, the process gets logged, and the discipline doesn't slip.
A deferred sync ledger across SQLite ↔ Neo4j, a checkpoint store, and a one-shot rehydrate command — after a restart, immediately rebuild "where I was" and inject it into the new session.
doctor emits a JSON health report; rule-based blind_retry / phantom_progress / pivot_exhaustion anti-pattern alerts — counters and thresholds, not magic.
Not tied to any one vendor. Any agent or custom script that can invoke a local CLI or a Python package can drive this layer.
Call agentmesh-runtime as a tool command; can ship a skill for auto-load.
This project's birthplace. Default paths already point at OpenClaw's runtime directories.
Invoke via shell or wrap as an MCP tool; fully compatible with the Codex CLI.
Any script that can spawn a Python subprocess can drive it; just point the env vars.
No cloud workers, no hosted database, no paid API. Install these three and the scaffolding runs locally. uv sync handles the Python side; the rest you install yourself.
Packaging via uv, aligned with the AgentMesh ecosystem. One uv sync installs everything.
The graph backend ships as docker compose: docker compose -f docker/docker-compose.neo4j.yml up. If it dies, SQLite + file grep keep going.
Semantic recall needs a GEMINI_API_KEY you register yourself. Without one, everything else still works — you just lose the vector lane.
The whole repo is built to be invoked by an agent, not typed line-by-line by you. Your job: install it and tell the agent how to use it. The agent does the rest.
git clone the repo, run uv sync, and you get agentmesh-runtime / amr commands. Run doctor once to confirm the environment is green.
See on GitHub →
The AGENTS.md at the repo root is written for the agent itself — when to recall, when to ingest, when to rehydrate, and what NOT to promise the human. Paste it into your Claude Code / OpenClaw / Codex / Hermes and you're set.
Read AGENTS.md →
Before each task the agent recalls prior decisions; after each task it ingests what it learned; after a restart it rehydrates its state. You see the output and never have to touch the plumbing.
GEMINI_API_KEY.decide and verify are intentionally minimal state-machine stubs — they record what you did, they don't think for you. The real reasoning comes from your agent; this layer just ensures the steps happen, the records get written, and the discipline holds.~/.openclaw/* for historical reasons — just set ARS_SESSION_BASE and ARS_MEMORY_DB to wherever your agent stores transcripts and memory. Claude Code / Codex / Hermes / any custom agent can drive it.chunks_fts MATCH ? is a proper FTS5 query. That mistake is documented in the decision-log errata.