What Is the MCP Tool Surface in ai‑memory?

The MCP Tool Surface in ai‑memory is a public API that exposes 17 typed tools allowing AI agents to read, write, and manage long‑term memory through a narrow, well‑defined contract.

The ai‑memory project implements a markdown‑backed, SQLite‑powered knowledge base designed for AI coding agents. Whether you are using Claude Code, VS Code Copilot, Zed, or any other MCP‑capable client, the MCP Tool Surface serves as the standardized gateway that abstracts the underlying storage implementation while enforcing security and consistency invariants.

Core Purpose of the MCP Tool Surface

The architecture deliberately limits the API surface to a small, versioned set of operations. According to docs/ARCHITECTURE.md (lines 349‑371), this constraint ensures that agents can reliably plan invocations without needing to understand the internal SQLite actor model or markdown wiki structure.

A Narrow, Well‑Defined API Surface

The ai‑memory MCP implementation exposes exactly 17 tools (reduced from an initial 18 after pruning). Each tool is strictly typed, annotated with a read‑only or destructive hint, and guarded by the same scope‑resolution and authentication logic used internally by the server. This narrow surface prevents agents from performing undefined operations and guarantees that every action respects the single‑writer SQLite invariant and scoped permissions.

Unified Entry Point for MCP Clients

Regardless of transport mechanism—HTTP via the /mcp endpoint or stdio bridge—the MCP Tool Surface provides a single contract that all clients agree upon. As documented in docs/mcp-install.md (lines 1‑50), this abstraction allows Claude Code, Codex, OpenCode, Gemini CLI, Antigravity CLI, and third‑party MCP servers to query the same knowledge base without implementation‑specific knowledge. The server handles protocol translation in crates/ai-memory-mcp/src/lib.rs, routing incoming JSON requests through a unified ScopeResolver and WriterHandle.

Full Memory Lifecycle Management

The tool catalog covers every stage of the AI memory pipeline:

• Retrieval – memory_query, memory_recent, memory_read_page (read‑only)
• Session Inspection – memory_read_session_observations
• Hand‑off Coordination – memory_handoff_begin, memory_handoff_accept, memory_handoff_cancel
• Knowledge‑base Mutation – memory_write_page, memory_delete_page, memory_consolidate
• Feedback & Improvement – memory_feedback, memory_auto_improve, memory_lint
• Maintenance – memory_forget_sweep, memory_status, memory_briefing, memory_explore

By routing all actions through this versioned catalog, the server guarantees atomicity, auditability, and consistent enforcement of cross‑cutting invariants.

Available MCP Tools and Their Functions

Each tool in the ai‑memory MCP surface is implemented as a discrete module in crates/ai-memory-mcp/src/tools/. The following categorization reflects the read‑only versus destructivehints defined in the architecture documentation.

Read‑Only Retrieval Tools

• memory_query – Semantic search across the knowledge base with optional explanation
• memory_recent – Lists recently accessed or modified pages
• memory_read_page – Returns the full markdown content of a specific path
• memory_read_session_observations – Inspects observations captured during the current session
• memory_status – Reports server health and storage statistics
• memory_briefing – Generates a context summary for agent initialization
• memory_explore – Navigates the wiki structure without reading full pages

Destructive Mutation Tools

• memory_write_page – Creates or updates markdown pages (requires user consent)
• memory_delete_page – Removes pages from the knowledge base
• memory_consolidate – LLM‑driven merging of fragmented knowledge (requires LLM configuration)
• memory_forget_sweep – Scheduled cleanup of expired or low‑value entries
• memory_feedback – Records agent feedback for future retrieval improvements
• memory_auto_improve – Triggers automated refactoring of wiki structure
• memory_lint – Validates markdown formatting and internal link integrity

Hand‑off Coordination Tools

• memory_handoff_begin – Initiates a context transfer between agent sessions
• memory_handoff_accept – Completes the transfer and loads the prior context
• memory_handoff_cancel – Aborts an in‑progress hand‑off

How to Call MCP Tools in ai‑memory

The server listens on http://127.0.0.1:49374 by default. All tools are invoked via HTTP POST to the /mcp endpoint with a JSON payload specifying the tool name and parameters.

Querying the Knowledge Base

curl -X POST http://127.0.0.1:49374/mcp \
     -H "Content-Type: application/json" \
     -d '{
           "tool": "memory_query",
           "params": { "query": "rust async", "explain": true }
         }'

This read‑only operation searches for "rust async" and returns ranked results with relevance explanations.

Reading Full Page Contents

curl -X POST http://127.0.0.1:49374/mcp \
     -H "Content-Type: application/json" \
     -d '{
           "tool": "memory_read_page",
           "params": { "path": "concepts/async_await.md" }
         }'

Use this when the query result snippet is insufficient and you need the complete markdown source.

Writing to the Knowledge Base

curl -X POST http://127.0.0.1:49374/mcp \
     -H "Content-Type: application/json" \
     -d '{
           "tool": "memory_write_page",
           "params": {
               "path": "concepts/async_await.md",
               "body": "# Async/Await in Rust\n…",

               "expires_at": "2027-01-01T00:00:00Z"
           }
         }'

This destructive operation requires user consent and is recorded in the audit log. The expires_at parameter enables automatic expiration via memory_forget_sweep.

Accepting Session Hand‑offs

curl -X POST http://127.0.0.1:49374/mcp \
     -H "Content-Type: application/json" \
     -d '{
           "tool": "memory_handoff_accept",
           "params": {}
         }'

Retrieves context from a previous agent session, enabling continuous workflows across independent CLI invocations.

Consolidating Project Knowledge

curl -X POST http://127.0.0.1:49374/mcp \
     -H "Content-Type: application/json" \
     -d '{
           "tool": "memory_consolidate",
           "params": {
               "project": "my_project",
               "multi_page": true
           }
         }'

Triggers an LLM‑driven consolidation that merges fragmented notes into coherent, multi‑page documentation.

Key Implementation Files

Understanding the MCP Tool Surface requires familiarity with these specific source locations:

• docs/ARCHITECTURE.md (lines 349‑371) – Catalogs all 17 MCP tools with their read‑only/destructive hints and concise purpose descriptions.
• docs/mcp-install.md (lines 1‑50) – Documents the /mcp endpoint, client registration procedures, and transport configuration for stdio bridges.
• crates/ai-memory-mcp/src/lib.rs – Implements the HTTP/stdio bridge, JSON parsing, and routing to concrete tool handlers through the ScopeResolver.
• crates/ai-memory-mcp/src/tools/*.rs – Contains individual tool implementations (e.g., memory_query.rs, memory_write_page.rs) enforcing authentication and the single‑writer SQLite invariant.
• AGENTS.md – Specifies the policy that additions or removals from the MCP tool surface must be synchronized with auto‑generated routing code and documentation updates.

Summary

• The MCP Tool Surface is the canonical API that ai‑memory exposes to AI agents, consisting of 17 strictly typed tools.
• It provides a uniform entry point for HTTP and stdio clients, abstracting the markdown‑wiki and SQLite storage implementation.
• Tools cover the complete memory lifecycle: read‑only retrieval, destructive mutation, session hand‑offs, and maintenance operations.
• All tools route through crates/ai-memory-mcp/src/lib.rs, enforcing atomicity, auditability, and scoped permissions.
• The surface is intentionally narrow to ensure agents can reliably plan actions without needing internal storage knowledge.

Frequently Asked Questions

What is the MCP Tool Surface in ai‑memory?

The MCP Tool Surface is the public API exposed by the ai‑memory server that allows MCP‑compatible clients to interact with the long‑term memory storage. It consists of 17 typed tools that handle retrieval, writing, session hand‑offs, and maintenance, all accessible via the /mcp HTTP endpoint or stdio bridges.

How many tools does the ai‑memory MCP surface expose?

The ai‑memory MCP surface exposes 17 tools, reduced from an initial 18 after architectural pruning. This limited set is documented in docs/ARCHITECTURE.md (lines 349‑371) and includes operations for querying, writing, consolidating, and maintaining the knowledge base.

What is the difference between read‑only and destructive MCP tools?

Read‑only tools (such as memory_query and memory_read_page) return data without modifying the SQLite backing store or markdown files. Destructive tools (such as memory_write_page and memory_consolidate) mutate state and require user consent, admission chain validation, and are permanently recorded in the audit log.

How do MCP clients connect to the ai‑memory server?

Clients connect via the /mcp HTTP endpoint at http://127.0.0.1:49374 by default, or through stdio bridges for local editor integrations like Claude Code or VS Code Copilot. The connection details and registration steps are documented in docs/mcp-install.md, which explains how to configure the server for both transport methods.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}