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 launchd job that auto-unlocks AD4M on every boot

• Creates a ClaudeMemory Perspective and saves the UUID

• Prints the settings.json snippet to paste into Claude Code

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

Tools (13)

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)

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:

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