mcp-ad4m
AD4M MCP server for Claude Code — 13-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:
- Builds the TypeScript server
- Stores your passphrase in macOS Keychain (not plaintext)
- Installs a
launchdjob that auto-unlocks AD4M on every boot - Creates a
ClaudeMemoryPerspective and saves the UUID - Prints the
settings.jsonsnippet to paste into Claude Code
Requires: Node.js 18+, AD4M executor running locally, macOS
Tools (13)
| 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 |
ad4m_optimize |
Deduplicate graph, flag stale entries, auto-runs every 10 writes |
ad4m_stats |
Total links, duplicate count, breakdown by predicate |
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.
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. Build
npm install && npm run build
2. Add to ~/.claude/settings.json
"ad4m": {
"command": "/path/to/mcp-ad4m/bin/mcp-ad4m",
"args": [],
"env": {
"AD4M_GQL_URL": "http://localhost:4000/graphql"
}
}
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.
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) |
| Timeout | fetch failed with port and URL |
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/
├── src/
│ └── index.ts TypeScript source (13 tools)
├── dist/ Compiled output (generated by npm run build)
├── launchd/
│ └── dev.ad4m.auto-unlock.plist
├── setup-claude-code.sh One-command setup
├── package.json
└── tsconfig.json
License
MIT
