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_status
Detect 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 writes
Query 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 retrieval
Classify (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 writes
Stats (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.
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.
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: Cortex
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 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
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 |
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 progressad4m_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.
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)
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 duplicatesTwo 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" })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.
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/graphqlThe 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 |
macOS 13.3 ARM64 (Apple M1)
AD4M executor v0.12.x
Claude Code CLI (Sonnet 4.6)
Node.js v24
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.jsonMIT
Get the local AD4M agent status: DID, initialization state, keystore lock state.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states it gets local status but does not disclose idempotency, authentication needs, or error conditions, though the tool is a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 15 words, concise and front-loaded with the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description is complete: it explains the action, resource, and returned fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters in the input schema, so the description cannot add parameter meaning. Baseline for 0 parameters is 4, and the description adequately states what is retrieved.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'local AD4M agent status', and lists specific fields (DID, initialization state, keystore lock state), distinguishing it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking agent status but does not explicitly state when to use it versus alternatives or any exclusions. It provides minimal guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Classify a piece of information by which layer it belongs to: ad4m, local, env, or relay. Run this BEFORE ad4m_write_memory if unsure.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The information or description to classify |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the action and layers but does not mention whether the tool is read-only, requires authentication, rate limits, or any side effects. Minimal behavioral context beyond the core functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states the action and resource, second provides a usage tip. No redundant information, front-loaded with key purpose, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (one parameter, no output schema), the description covers purpose and categories but lacks information about the return value format or structure. Since there is no output schema, the description should ideally describe the output to make the tool fully usable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a description for the single parameter 'content'. The description adds value by enumerating the classification categories (ad4m, local, env, relay), which the schema does not provide. Could be improved by specifying expected format or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'classify' and the resource 'piece of information', lists the possible layers (ad4m, local, env, relay), and distinguishes from sibling tool ad4m_write_memory by suggesting to run this first if unsure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool ('Run this BEFORE ad4m_write_memory if unsure'), providing clear context. However, it does not explicitly mention when not to use it or other alternatives beyond the one sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether mcp-ad4m is registered in the correct config file. Detects the wrong-file misconfiguration that causes silent connection failures.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It reveals the behavior (registration check and misconfiguration detection) but does not specify the return format, output on success/failure, or potential side effects. This is adequate but lacks detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single efficient sentence that conveys the purpose and detection capability with no wasted words. It is front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose and use case but lacks information about the tool's return value or output format. Since there is no output schema, the agent is left guessing what the result looks like, which is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema coverage is 100%. The description does not need to add parameter information. Baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Check' and the resource 'mcp-ad4m registration in config file', and specifies detection of a specific misconfiguration. It is distinct from sibling tools like ad4m_agent_status or ad4m_optimize.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when silent connection failures due to wrong-file misconfiguration are suspected. It provides clear context but does not explicitly state when not to use it or list alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new named Perspective. Returns its UUID for subsequent link operations.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Human-readable name for the Perspective |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It correctly identifies this as a mutation creating a perspective and returning a UUID, but lacks details on side effects, error handling, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no extraneous information. Key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple creation tool with one parameter, the description covers purpose, return value, and downstream usage. Minor omission: no mention of uniqueness constraints or what happens if the name duplicates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'name' is fully described in the schema (100% coverage), so the description adds minimal extra meaning. The baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Create'), the resource ('Perspective'), and the return value ('UUID'), clearly distinguishing from sibling tools like ad4m_list_perspectives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for subsequent link operations but offers no explicit guidance on when to choose this over alternatives like ad4m_list_perspectives or ad4m_write_memory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove links from a Perspective by source, predicate, and/or target filter. Returns matched/removed/failed counts.
| Name | Required | Description | Default |
|---|---|---|---|
| perspective_uuid | Yes | Perspective UUID to delete from | |
| source | No | Filter by source URI | |
| predicate | No | Filter by predicate URI | |
| target | No | Filter by target URI |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description mentions destructive nature ('remove') and return of counts, but lacks details on irreversibility, required permissions, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence conveys purpose, filtering capability, and output. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should clarify return format. It mentions counts but not structure or error handling. Adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description adds filter semantics but does not provide new meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it removes links from a Perspective using filters (source, predicate, target). This distinguishes it from siblings like ad4m_write_memory (adds) and ad4m_recall (retrieves).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use when needing to delete specific links by filter. No explicit when-not or alternatives, but context of sibling tools makes it clear this is the delete operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a shared AD4M Neighbourhood by Perspective UUID.
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | Perspective UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must carry the full burden. It states 'Read' implying read-only, but it does not disclose any side effects, authorization requirements, or what the output contains. Since there is no contradiction with missing annotations, a score of 2 reflects minimal value added.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is clear and to the point. Every word contributes meaning without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should at least mention what is returned. It lacks any details about the return value or format. For a tool with one parameter, more context is needed for an agent to correctly interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a description for the 'uuid' parameter. The description adds 'by Perspective UUID', which essentially restates the schema. Baseline 3 is appropriate as the description does not provide additional semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and the resource 'AD4M Neighbourhood', with the key parameter 'Perspective UUID'. It distinguishes from sibling tools like ad4m_list_perspectives by specifying a single lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, nor any preconditions or context for its use. The description does not help the agent decide between this and sibling tools like ad4m_list_perspectives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Perspectives on the local AD4M executor.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'List all Perspectives' implying a read operation, but does not disclose side effects, authentication requirements, error handling, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with key information front-loaded. No wasted words or unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with no parameters and no output schema, the description is adequate but minimal. It does not mention the structure of returned data or behavior when no perspectives exist, which would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters, and schema coverage is 100%. Per guideline, baseline is 4. The description adds no parameter info, which is acceptable since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'List' and resource 'Perspectives' with scope 'local AD4M executor'. It clearly distinguishes from siblings like ad4m_create_perspective or ad4m_get_neighbourhood.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs siblings. While the purpose is clear, the description does not state when to prefer list_perspectives over other tools like get_neighbourhood or create_perspective.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit the memory graph for duplicates and stale entries. dry_run: true (default) reports without deleting.
| Name | Required | Description | Default |
|---|---|---|---|
| perspective_uuid | Yes | Perspective UUID to audit | |
| dry_run | No | If true (default), report only — do not delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It explains the dry_run behavior (report only vs. delete), but does not specify what the report contains, whether changes are permanent when dry_run is false, or any permission requirements. The description is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, followed by the dry_run behavior. No extraneous information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two parameters and no output schema, the description is mostly complete for its purpose. However, it does not describe the return value or output format, which would help an agent interpret results. The description covers core functionality but lacks full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The description adds specific context by mentioning 'duplicates and stale entries', which goes beyond the dry_run parameter's schema description. This helps the agent understand the tool's purpose for the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Audit the memory graph for duplicates and stale entries', which specifies the verb (audit) and resource (memory graph). This distinguishes it from sibling tools like ad4m_delete_memory (deletion) and ad4m_stats (statistics).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for cleanup of duplicates and stale entries, but does not explicitly state when to use it over alternatives like ad4m_delete_memory or ad4m_stats. No 'when not to use' guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query links from a Perspective by source, predicate, or target. Omit any field to match all.
| Name | Required | Description | Default |
|---|---|---|---|
| perspective_uuid | Yes | Perspective UUID to query | |
| source | No | Filter by source URI | |
| predicate | No | Filter by predicate URI | |
| target | No | Filter by target URI |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'Query links' without disclosing behavioral traits such as read-only nature, error handling, or performance implications. This is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It is front-loaded and efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 simple parameters and no output schema, the description is adequate but lacks detail on return values (structure of links). For a query tool, it is minimally complete but could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, baseline is 3. The description adds 'Omit any field to match all', which clarifies parameter optionality and behavior beyond the schema. This adds meaningful value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it queries links from a Perspective with optional filters by source, predicate, or target. It distinguishes from sibling tools like ad4m_write_memory (write) and ad4m_list_perspectives (list perspectives).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool vs alternatives like ad4m_classify or ad4m_get_neighbourhood. It implies usage for link queries but lacks guidance on exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Memory graph statistics: total links, duplicates, breakdown by predicate, oldest and newest entries.
| Name | Required | Description | Default |
|---|---|---|---|
| perspective_uuid | Yes | Perspective UUID to inspect |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It does not explicitly state that the tool is read-only or non-destructive. The term 'statistics' implies a read operation, but no safety or permission information is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys all key information without unnecessary words. It is front-loaded with the core purpose and lists specific statistics efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description adequately covers the expected statistics. However, it lacks details on return format, error conditions, or whether the perspective must exist, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides a description for the single parameter ('Perspective UUID to inspect') and has 100% coverage. The description adds no additional meaning beyond the schema, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides memory graph statistics and enumerates specific metrics (total links, duplicates, predicate breakdown, oldest/newest entries). It distinguishes from sibling tools which focus on recall, write, or agent status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like ad4m_recall or ad4m_agent_status. The description fails to specify context for choosing stats over other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a signed LinkExpression (source → predicate → target) to a Perspective. Auto-optimizes the graph every 10 writes across all terminals.
| Name | Required | Description | Default |
|---|---|---|---|
| perspective_uuid | Yes | Target Perspective UUID | |
| source | Yes | Source URI — e.g. 'agent://session/2026-03-22' | |
| predicate | No | Predicate URI — e.g. 'ad4m://knows' (default: ad4m://relates) | |
| target | Yes | Target URI or literal — e.g. 'literal://decision text' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the auto-optimization side effect but omits details on mutation (e.g., destructiveness, idempotency, authorization requirements). No annotation contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words, front-loaded with the core action. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a write tool with moderate complexity (4 params, no nested objects). Missing return value description, error handling, and further context on the optimization behavior, but not critical given sibling tools like ad4m_recall for reading.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds semantic context by explaining parameters as parts of a LinkExpression (source, predicate, target) and providing example URIs, going beyond the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Write a signed LinkExpression (source → predicate → target) to a Perspective,' specifying the action and resource. It also mentions auto-optimization, distinguishing it from siblings like ad4m_delete_memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for writing link expressions to perspectives but provides no explicit guidance on when to use it vs alternatives like relay_write, nor any prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read cross-terminal relay messages from AD4M. Optionally filter by session_id or since a timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| perspective_uuid | Yes | Perspective UUID (use ClaudeMemory UUID) | |
| session_id | No | Filter to a specific terminal/session | |
| since | No | ISO timestamp — only return messages after this time |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool is read-only, but lacks details on side effects, rate limits, authentication needs, or return behavior. For a tool with no annotations, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, no fluff, and front-loaded with the primary action. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters and no output schema. The description explains the purpose and optional filters, but does not mention output format, pagination, or error behavior. Given the lack of annotations, more detail would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; each parameter is described in the schema. The description merely summarizes the optional filters without adding new semantics beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and the resource 'cross-terminal relay messages from AD4M'. It also mentions optional filters, distinguishing it from the sibling 'relay_write' (write). This is specific and non-tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for reading vs writing, but does not explicitly state when to use this tool over alternatives or provide exclusion criteria. No mention of prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a cross-terminal relay message to AD4M. Both terminals share the same AD4M executor so state is immediately visible.
| Name | Required | Description | Default |
|---|---|---|---|
| perspective_uuid | Yes | Perspective UUID (use ClaudeMemory UUID) | |
| message | Yes | Message to relay | |
| session_id | No | Terminal/session identifier (default: 'default') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, placing full burden on the description. It discloses that state is immediately visible across terminals, a useful behavioral trait. However, it omits details on mutation effects, error handling, or side effects, which are important for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The first sentence front-loads the purpose and unique characteristic of shared executor. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple write operation with 3 parameters fully described in the schema and no output schema, the description provides the key behavioral context (immediate visibility) but lacks guidance on when to use, error scenarios, or interaction with sibling tools. It is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add meaningful semantics beyond what the schema already provides; it simply mentions writing a message but does not elaborate on parameter usage or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool writes a cross-terminal relay message to AD4M, with a specific verb and resource. It also adds a unique behavioral note about immediate visibility due to shared executor, distinguishing it from other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for inter-terminal communication via 'cross-terminal' and shared executor, but does not explicitly state when to use this over alternatives like relay_read or ad4m_write_memory. No exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.0.0ad4m_agent_statusad4m_classifyad4m_config_checkad4m_create_perspectivead4m_delete_memoryad4m_get_neighbourhoodad4m_list_perspectivesad4m_optimizead4m_recallad4m_statsad4m_write_memoryrelay_readrelay_writeScored 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.
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.
