Ad4m

AD4M MCP server for Claude Code — 14-tool semantic memory and enforcement layer.

Gives Claude Code persistent memory, cross-session context, and memory hygiene via a locally hosted AD4M executor. All data stays on your machine.

---

The Problem

Getting AD4M working with Claude Code requires:

• Figuring out the executor port (it reads from ~/.ad4m/executor-port, not a fixed value)
• Writing a custom MCP server from scratch — none existed
• Re-unlocking the agent on every reboot (no persistence)
• No documented integration path for Claude Code specifically

This server solves all of it. One command sets everything up.

---

One-Command Install

git clone https://github.com/thefranceway/mcp-ad4m.git
cd mcp-ad4m
./setup-claude-code.sh --passphrase YOUR_AD4M_PASSPHRASE

The script:

• Installs dependencies
• Stores your passphrase in macOS Keychain (not plaintext)
• Installs a launchd job that auto-unlocks AD4M on every boot
• Creates a ClaudeMemory Perspective and saves the UUID
• Registers the MCP server at user scope via claude mcp add -s user

Requires: Node.js 18+, AD4M executor running locally, macOS

---

Tools (14)

Tool	Description
ad4m_agent_status	DID, initialization state, keystore lock state
ad4m_list_perspectives	All local Perspectives
ad4m_create_perspective	Create a new named semantic graph
ad4m_write_memory	Write a LinkExpression (source → predicate → target)
ad4m_recall	Query links with optional source/predicate/target filters
ad4m_delete_memory	Remove links by filter — matched/removed/failed counts
ad4m_classify	Classify content by layer before writing (env/local/relay/ad4m)
ad4m_config_check	Detect MCP registration in the wrong config file or scope
ad4m_optimize	Deduplicate graph, flag stale entries, auto-runs every 10 writes
ad4m_stats	Total links, duplicate count, breakdown by predicate
ad4m_traverse	BFS multi-hop graph traversal — returns connected subgraph
ad4m_get_neighbourhood	Inspect a shared AD4M Neighbourhood
relay_write	Write cross-terminal live state via AD4M
relay_read	Read cross-terminal relay messages

---

Memory Architecture

AD4M stores information as signed links: source → predicate → target.

memory://project/zuafrique  →  ad4m://has-content  →  literal://Deployed CF Pages 2026-03-15
franc://session-log         →  franc://closed       →  literal://Session ended
franc://relay/terminal-a    →  franc://relay        →  literal://Build in progress

Layer Taxonomy (enforced by ad4m_classify)

Layer	Where it belongs	Examples
ad4m	AD4M semantic graph	Decisions, project facts, cross-session context
env	~/.zshrc	API keys, tokens, credentials
local	CLAUDE.md / settings.json	Rules, hooks, permissions
relay	AD4M relay predicate	Live cross-terminal state

Run ad4m_classify before ad4m_write_memory if unsure which layer to use.

---

Graph Traversal and Reasoning

ad4m_traverse exposes the semantic graph structure so Claude can reason over connected facts — not just retrieve individual entries.

How it works: Given a starting node URI, it runs a bidirectional BFS, following all links where the node appears as source or target. It expands outward hop by hop up to the requested depth, deduplicates edges, and returns the full subgraph grouped by predicate.

ad4m_traverse({
  perspective_uuid: "...",
  node: "memory://feedback/feedback_cloudflare_d1_builds",
  depth: 2
})

Returns:

{
  "root": "memory://feedback/feedback_cloudflare_d1_builds",
  "depth": 2,
  "node_count": 3,
  "edge_count": 2,
  "by_predicate": {
    "ad4m://has-name": [{ "from": "memory://...", "to": "literal://Cloudflare Worker + D1 build patterns" }],
    "ad4m://has-content": [{ "from": "memory://...", "to": "literal://Always use prepare().run()..." }]
  },
  "summary": "3 connected nodes, 2 edges — 2-hop subgraph"
}

Why this matters: ad4m_recall retrieves flat matches. ad4m_traverse returns the connected graph — Claude reads the full subgraph in one call and can derive conclusions, spot conflicts, and surface implications from graph structure alone. No formal logic engine required.

Depth guidance:

• depth: 1 — direct neighbors only (fast)
• depth: 2 — default, covers most use cases
• depth: 3–4 — broad context retrieval (more queries, richer output)

---

Self-Optimization

The graph self-prunes automatically. Every 10 writes from any terminal increments a shared counter stored in AD4M (franc://optimizer → franc://write-count). When it hits 10, ad4m_optimize runs and removes exact duplicates.

To run manually:

ad4m_optimize({ perspective_uuid: "...", dry_run: true })   // report only
ad4m_optimize({ perspective_uuid: "...", dry_run: false })  // remove duplicates

---

Cross-Terminal Relay

Two Claude Code terminals sharing the same AD4M executor can exchange live messages:

Terminal A:

relay_write({ perspective_uuid: "...", message: "build done", session_id: "terminal-a" })

Terminal B:

relay_read({ perspective_uuid: "...", since: "2026-05-16T00:00:00Z" })

---

Manual Setup (without the script)

1. Install

npm install

2. Register with Claude Code (user scope)

claude mcp add -s user ad4m /path/to/mcp-ad4m/index.js \
  --env AD4M_GQL_URL=http://localhost:4000/graphql

Important: Always use -s user. Without it, claude mcp add defaults to project scope and registers the server only for the current directory. Opening Claude Code from any other directory causes the server to silently disappear from claude mcp list with no error. See coasys/ad4m#822.

3. Unlock the agent before each session

curl -s http://localhost:4000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation { agentUnlock(passphrase: \"YOUR_PASSPHRASE\") { isUnlocked } }"}'

Or install the launchd job from launchd/dev.ad4m.auto-unlock.plist to auto-unlock on boot.

---

Troubleshooting

Server missing from claude mcp list

Run ad4m_config_check inside Claude Code. It reads ~/.claude.json, detects whether the server is registered at project scope instead of user scope, and returns the exact command to fix it.

Or check manually:

claude mcp list   # should show ad4m: ✓ Connected from any directory

If it only appears from one directory, re-register at user scope:

claude mcp remove ad4m
claude mcp add -s user ad4m /path/to/mcp-ad4m/index.js \
  --env AD4M_GQL_URL=http://localhost:4000/graphql

---

Error Messages

The server returns actionable errors:

Situation	What you see
Executor not running	AD4M executor not reachable. Start it with: ad4m serve --port 4000
Agent locked	Agent is locked. Unlock with: curl ... (exact command included)
Server missing from any directory	Registered at project scope — see Troubleshooting above

---

Tested On

• macOS 13.3 ARM64 (Apple M1)
• AD4M executor v0.12.x
• Claude Code CLI (Sonnet 4.6)
• Node.js v24

---

Project Structure

mcp-ad4m/
├── index.js              MCP server (14 tools, runs directly with Node)
├── dist/                 Runtime copy (used by wrapper binary)
├── launchd/
│   └── dev.ad4m.auto-unlock.plist
├── setup-claude-code.sh  One-command setup
└── package.json

---

License

MIT