mcp-ad4m
The mcp-ad4m server provides persistent semantic memory, cross-session context, graph reasoning, and cross-terminal relay for Claude Code via a locally hosted AD4M executor (all data stays on your machine). It exposes 14 tools across these capability areas:
Agent & Configuration
Check agent status (DID, initialization state, keystore lock) via
ad4m_agent_statusDetect MCP registration misconfigurations and get fix instructions via
ad4m_config_check
Perspective (Graph) Management
List, create, and inspect named semantic graph Perspectives and Neighbourhoods
Memory Read & Write
Write signed LinkExpressions (
source → predicate → target) to a Perspective; auto-deduplicates every 10 writesQuery links by source, predicate, and/or target filters
Delete links by filter, returning matched/removed/failed counts
Graph Intelligence
Traverse (
ad4m_traverse): Bidirectional BFS multi-hop traversal from a starting node, returning a full connected subgraph grouped by predicate — enabling reasoning over structured facts, not just flat retrievalClassify (
ad4m_classify): Determine the correct storage layer (ad4m,env,local,relay) before writing to prevent misplacement
Memory Hygiene & Analytics
Optimize (
ad4m_optimize): Deduplicate and flag stale entries; supports dry-run mode; runs automatically every 10 writesStats (
ad4m_stats): View total link count, duplicate count, predicate breakdown, and oldest/newest entry timestamps
Cross-Terminal Relay
Write/read relay messages (
relay_write/relay_read): Exchange live state messages between multiple Claude Code terminals sharing the same AD4M executor, optionally filtered by session ID or timestamp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-ad4m remember that we decided to use React for the frontend"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-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.
Related MCP server: mem0-mcp-selfhosted
One-Command Install
git clone https://github.com/thefranceway/mcp-ad4m.git
cd mcp-ad4m
./setup-claude-code.sh --passphrase YOUR_AD4M_PASSPHRASEThe script:
Installs dependencies
Stores your passphrase in macOS Keychain (not plaintext)
Installs a
launchdjob that auto-unlocks AD4M on every bootCreates a
ClaudeMemoryPerspective and saves the UUIDRegisters 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 |
| DID, initialization state, keystore lock state |
| All local Perspectives |
| Create a new named semantic graph |
| Write a LinkExpression (source → predicate → target) |
| Query links with optional source/predicate/target filters |
| Remove links by filter — matched/removed/failed counts |
| Classify content by layer before writing (env/local/relay/ad4m) |
| Detect MCP registration in the wrong config file or scope |
| Deduplicate graph, flag stale entries, auto-runs every 10 writes |
| Total links, duplicate count, breakdown by predicate |
| BFS multi-hop graph traversal — returns connected subgraph |
| Inspect a shared AD4M Neighbourhood |
| Write cross-terminal live state via AD4M |
| 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 progressLayer Taxonomy (enforced by ad4m_classify)
Layer | Where it belongs | Examples |
| AD4M semantic graph | Decisions, project facts, cross-session context |
|
| API keys, tokens, credentials |
|
| Rules, hooks, permissions |
| 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 casesdepth: 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 duplicatesCross-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 install2. 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/graphqlImportant: Always use
-s user. Without it,claude mcp adddefaults 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 fromclaude mcp listwith 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 directoryIf 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/graphqlError Messages
The server returns actionable errors:
Situation | What you see |
Executor not running |
|
Agent locked |
|
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.jsonLicense
MIT
Available Tools
13 toolsad4m_agent_statusA
Get the local AD4M agent status: DID, initialization state, keystore lock state.
Inputs: no named parameters.
ad4m_classifyA
Classify a piece of information by which layer it belongs to: ad4m, local, env, or relay. Run this BEFORE ad4m_write_memory if unsure.
Inputs: content (required).
ad4m_config_checkA
Check whether mcp-ad4m is registered in the correct config file. Detects the wrong-file misconfiguration that causes silent connection failures.
Inputs: no named parameters.
ad4m_create_perspectiveA
Create a new named Perspective. Returns its UUID for subsequent link operations.
Inputs: name (required).
ad4m_delete_memoryA
Remove links from a Perspective by source, predicate, and/or target filter. Returns matched/removed/failed counts.
Inputs: perspective_uuid (required), source, predicate, target.
ad4m_get_neighbourhoodB
Read a shared AD4M Neighbourhood by Perspective UUID.
Inputs: uuid (required).
ad4m_list_perspectivesA
List all Perspectives on the local AD4M executor.
Inputs: no named parameters.
ad4m_optimizeA
Audit the memory graph for duplicates and stale entries. dry_run: true (default) reports without deleting.
Inputs: perspective_uuid (required), dry_run.
ad4m_recallA
Query links from a Perspective by source, predicate, or target. Omit any field to match all.
Inputs: perspective_uuid (required), source, predicate, target.
ad4m_statsB
Memory graph statistics: total links, duplicates, breakdown by predicate, oldest and newest entries.
Inputs: perspective_uuid (required).
ad4m_write_memoryA
Write a signed LinkExpression (source → predicate → target) to a Perspective. Auto-optimizes the graph every 10 writes across all terminals.
Inputs: perspective_uuid (required), source (required), target (required), predicate.
relay_readA
Read cross-terminal relay messages from AD4M. Optionally filter by session_id or since a timestamp.
Inputs: perspective_uuid (required), session_id, since.
relay_writeA
Write a cross-terminal relay message to AD4M. Both terminals share the same AD4M executor so state is immediately visible.
Inputs: perspective_uuid (required), message (required), session_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool addresses a distinct operation: status, classification, config, perspective CRUD, link query/write/delete, optimization, stats, and relay messaging. No two tools have overlapping purposes; even similar-sounding tools like recall and stats serve different functions (query vs. summary).
Most tools follow the ad4m_ prefix with snake_case, but two tools (relay_read, relay_write) use a relay_ prefix instead. This minor inconsistency is clear and does not cause confusion, but it prevents a perfect score.
13 tools cover the core AD4M operations: agent management, perspective lifecycle, link manipulation, optimization, statistics, and relay messaging. The count feels well-proportioned for the domain, with no obvious bloat or insufficiency.
The set covers essential operations: create, read, list, delete for perspectives and links, plus classification, optimization, stats, and relay. Missing are update operations for perspectives or links, but these may be less critical in an immutable or signed-graph context. Minor gap.
Maintenance
Related MCP Connectors
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceEnables Claude Code to store, search, update, and delete persistent memories across sessions, backed by self-hosted Qdrant vector storage, an optional Neo4j knowledge graph, and Ollama embeddings, with Anthropic or Ollama as the main LLM. Exposes 11 MCP tools plus session hooks and a CLAUDE.md guide so context is injected at startup and saved automatically at session end.-
- FlicenseNot gradedqualityAmaintenanceEnables Claude Code to store and recall persistent cross-session memory backed by self-hosted Qdrant, Neo4j, and Ollama, using Anthropic or fully local Ollama as the LLM. Exposes tools for adding, searching, listing, updating, and deleting memories plus querying knowledge-graph entities and relationships, with optional session hooks for automatic context injection and saving.-
- FlicenseNot gradedqualityAmaintenanceEnables Claude Code to maintain persistent, searchable memory across sessions using self-hosted Qdrant vector storage, optional Neo4j knowledge graphs, and Ollama embeddings, with Claude or local Ollama as the main LLM. Exposes tools for adding, searching, updating, deleting, and managing memories and graph entities.-
- FlicenseNot gradedqualityAmaintenanceEnables Claude Code to store, search, update, and delete persistent cross-session memories backed by self-hosted Qdrant, Neo4j, and Ollama, exposing 11 MCP tools plus knowledge-graph entity lookups. It also provides session hooks that automatically inject relevant context at startup and save session summaries on exit.-