ASM — Agent Shared Memory

ASM gives local coding agents one shared, offline memory. It combines mapped source-code graphs, an optional Obsidian knowledge layer, and append-only implementation records behind one local Model Context Protocol (MCP) server.

Claude Code, Codex, Cursor, Kimi Code, Grok Build, Gemini CLI, and any other local stdio MCP host can query the same graph and write back to the same memory. The 3D interface is optional; recall and write-back continue to work when it is closed.

Why ASM

ASM keeps three useful forms of memory together:

1. Immediate work memory — structured records are appended to ~/.asm/memory.jsonl as soon as an agent documents a completed change.

2. Durable human memory — when an Obsidian vault is configured, the same record is appended to wiki/main/daily/YYYY-MM-DD.md.

3. Queryable context graph — brain.json joins files, dependencies, skills, infrastructure, vault concepts, and recent agent work.

The operating rule is simple: recall before reading or editing, inspect the current files, then record concrete outcomes after changing them. ASM is context, not a replacement for source control or verification.

Related MCP server: obsidian-emergent-mcp

Architecture

configured projects ──> Graphify ──┐
                                   ├──> merge.py ──> brain.json ──> local stdio MCP
optional Obsidian OKF graph ───────┘                         ├────> lifecycle hooks
                                                           └────> optional local UI
agent memory_record calls ──> memory.jsonl + optional Obsidian daily note

No hosted database or cloud memory service is required. The MCP server communicates over stdio and the optional UI binds to loopback by default.

Agent support

Grok, Kimi, Claude, and other names can describe either a model or an agent host. A model selected inside Cursor uses Cursor's local MCP and hook environment. A raw model API cannot launch a process on your computer; it needs an MCP-capable host or adapter.

Grok Build's native hooks provide live file activity and the one-retry stop gate. Its SessionStart and UserPromptSubmit hooks are passive: they can observe events but cannot inject context into the active prompt. Grok therefore receives the recall protocol through the ASM MCP server instructions and the shared skill, not through lifecycle context injection.

Requirements

• Python 3.11 or newer

• uv

• Graphify: uv tool install graphifyy

• Node.js 24 or newer for the complete frontend build and test workflow

• At least one local MCP-capable coding agent

• Optional: an Obsidian vault with the documented OKF structure

Quick start

git clone https://github.com/dizeldz20-ux/agent-shared-memory.git
cd agent-shared-memory

cp sources.example.json sources.json
# Edit sources.json: add projects and set vault to null for code-only mode.

uv tool install graphifyy

cd frontend
npm ci
npm run build
cd ..

chmod +x refresh.sh start-asm.sh install-agent-integrations.sh
./install-agent-integrations.sh

The installer:

• rebuilds the graph and deploys the runtime to ~/.asm;

• installs one portable agent-shared-memory skill under ~/.agents/skills for compatible agents and retains only Claude Code's client-specific compatibility copy;

• registers the same asm stdio MCP command with installed native CLIs;

• safely merges MCP entries for Gemini CLI, Cursor, current Kimi Code, and legacy Kimi CLI, with native lifecycle hooks for Cursor and current Kimi Code;

• configures Grok Build's native global activity and stop hooks without claiming unsupported session or prompt context injection;

• writes a portable MCP configuration to ~/.asm/client-configs/mcp.json;

• preserves unrelated settings and refuses to overwrite malformed JSON.

Restart open agent sessions after installation. Review the local hook command once in clients that expose a hook-trust screen.

Configure mapped sources

sources.json is deliberately ignored by Git because it contains machine-specific paths. Add explicit sources, auto-discover sibling project directories, or combine both:

{
  "vault": null,
  "layers": { "agents": "Projects", "asm": "ASM" },
  "sources": [
    { "layer": "asm", "raw": "asm-self", "base": ".", "prefix": "" }
  ],
  "discoverSources": [
    {
      "root": "../projects",
      "defaultLayer": "agents",
      "exclude": ["archive"]
    }
  ]
}

Discovery is deterministic, explicit entries win, and one missing source does not prevent the remaining sources from being merged.

Shared agent protocol

Every integrated agent receives the same contract through the shared skill, server instructions, or both:

1. Call brain_search before planning work in a mapped domain.

2. Call brain_context before the first read or edit of a mapped target file.

3. Use brain_neighbors when a change may affect several components.

4. Inspect and verify the current code normally.

5. After changing files, call memory_record with the result, affected files, decisions, verification, and open threads.

6. Never store credentials, private keys, tokens, raw transcripts, or secret-bearing tool output.

Clients with an installed Stop hook also get a one-retry memory gate: a session with a recognized editor, delete, or conservative file-mutating shell operation is prompted once to write its handoff before stopping. Read-only tools and recognized read-only shell commands are not blocked, and a missing MCP server cannot create an infinite loop. This is a workflow guardrail, not a complete operating-system audit. Passive lifecycle events are not treated as context injection.

MCP tools

For a client not handled by the installer, copy the asm entry from ~/.asm/client-configs/mcp.json. The portable shape is:

{
  "mcpServers": {
    "asm": {
      "command": "/absolute/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/.asm",
        "python",
        "mcp_server.py"
      ]
    }
  }
}

Refresh the brain

./refresh.sh            # every source
./refresh.sh --changed  # only sources with files newer than their last extract

The refresh rebuilds the optional vault OKF graph, extracts each code source independently, merges the graph, atomically deploys runtime files, and hot-reloads the UI only if it is already running. It does not start the UI. --changed makes a refresh cheap enough to run after every real change instead of once a week.

PowerShell users can run ./refresh.ps1. The POSIX integration installer currently provides the complete automatic multi-agent setup; Windows users can copy the portable MCP entry into their client configuration.

Optional live UI

./start-asm.sh

Open http://127.0.0.1:8930. Connectome provides the interactive 3D neural view; Map and Cortex are 2D projections of the same graph and live routes. File-access activity is buffered locally while the UI is closed and replayed when it starts again.

The server expects a production frontend in frontend/dist. Build it with npm run build. To refresh the tracked, sanitized public demo separately, run npm run demo:data; the normal brain refresh does not rewrite demo assets.

Runtime layout

~/.asm/
├── brain.json
├── brain.index.json
├── memory.jsonl
├── usage.jsonl          # node opens (brain_node / brain_context) — recall feedback
├── skill-map.json       # derived skill routing map (rebuilt from every installed SKILL.md)
├── skill-map.overrides.json  # your curated routing rules (private; seeded from hook/skill-map.overrides.example.json)
├── skill-usage.jsonl    # skill hints and loads — routing precision feedback
├── events.jsonl
├── pending.jsonl
├── sessions/            # per-session mutation markers, recall ledgers, and skill state (<id>.skills.json)
├── asm-paths.json
├── mcp_server.py
├── client-configs/
│   └── mcp.json
└── hooks/
    ├── asm-session-start.js
    ├── asm-prompt-recall.js
    ├── asm-activity-hook.js
    ├── asm-memory-gate.js
    └── asm-skill-router.js   # Claude Code only: SKILL.state-style skill routing (see docs/implementation-notes.md)

Privacy and security

• Keep sources.json, generated runtime data, credentials, and local event logs out of Git.

• brain.json contains graph metadata and local file paths. Obsidian note bodies are not copied into it, but the graph still belongs on the local machine unless deliberately sanitized.

• Live activity records agent name, tool name, phase, and file paths. It does not send prompts, source contents, tool inputs, or tool output to the UI event stream.

• The optional Codex rollout fallback derives tool names and paths without publishing prompt text or command output. Disable it with ASM_CODEX_ROLLOUT_FALLBACK=0.

• Keep the UI bound to 127.0.0.1; do not expose the local runtime through a public tunnel without adding authentication and reviewing the data boundary.

• Treat all text passed to memory_record as durable. Review it before recording and never include secrets.

Migration from C2B

During one-time migration, ASM imports recoverable JSONL files from ~/.claude/c2b, removes the old user-scoped c2b MCP registration and permission, and leaves the legacy directory untouched as a rollback/audit source. Stable historical vault IDs are not renamed because doing so would break existing links.

Development checks

uv run python -m unittest discover -s tests
bash -n refresh.sh install-agent-integrations.sh start-asm.sh

cd frontend
npm ci
npm run test:unit
npm run build:preview
npm run test:e2e

See implementation notes for graph/runtime invariants and vault structure for the optional Obsidian contract.

License

MIT