How to List and Understand the 18 MCP Tools in ai-memory

ai-memory exposes 18 Memory-Control-Protocol (MCP) tools that enable AI agents to perform full-text search, write durable wiki pages, manage hand-offs, and maintain long-term memory through a narrow, well-documented HTTP interface.

The akitaonrails/ai-memory repository implements a "narrow on purpose" philosophy, exposing only essential operations as MCP tools to keep the attack surface minimal and the API comprehensible. These 18 tools are documented in docs/ARCHITECTURE.md【/cache/repos/github.com/akitaonrails/ai-memory/main/docs/ARCHITECTURE.md#L49-L71】and implemented across the Rust codebase in crates/ai-memory-mcp/src/tools/.

Complete Reference to the 18 ai-memory MCP Tools

The definitive tool catalogue lives in the Architecture document, where each entry follows the format | Tool | Hint | Purpose |. The tools divide into three functional categories:

Read-Only Query Tools (7 Tools)

These read-only tools retrieve information without modifying state:

• memory_query – Performs full-text search (FTS5) with optional entity-matching, graph-RRF, and vector-RRF. Supports global=true for cross-project search or defaults to the current project scope.
• memory_recent – Returns the most recently updated pages where is_latest=1.
• memory_read_page – Retrieves complete markdown content for a single page by path or by top search hit.
• memory_read_session_observations – Pages through raw hook observations for a specific session, limited to the current scope.
• memory_status – Returns basic server statistics including counts and version information.
• memory_briefing – Provides a structured snapshot of activity, recent pages, and active rules.
• memory_explore – Generates an LLM-prose digest of the briefing data (degrades to JSON without an LLM provider).

Hand-Off Management Tools (3 Tools)

These destructive tools manage context transfer between agents:

• memory_handoff_begin – Opens an owner-scoped handoff; setting shared=true publishes it to the project for other agents.
• memory_handoff_accept – Fetches and acknowledges the latest handoff (supports auto-hand-off or shared hand-offs).
• memory_handoff_cancel – Marks an open handoff as expired; root users can set any_owner=true to cancel any handoff regardless of owner.

Write and Maintenance Tools (8 Tools)

These tools modify memory state or perform housekeeping:

• memory_consolidate (destructive) – Triggers LLM-driven page rewrites for single or multi-page consolidation.
• memory_feedback (write) – Records quality signals (helpful/not_helpful) for specific pages.
• memory_auto_improve (write) – Reviews the completed session and stages wiki edits via the auto-improvement pipeline.
• memory_write_page (destructive) – Writes durable wiki pages with optional expires_at TTL support.
• memory_delete_page (destructive) – Deletes a page by exact path; idempotent operation that fires admission chain webhooks.
• memory_forget_sweep (destructive) – Executes retention passes that evict cold pages and hard-delete TTL-expired entries; use dry_run=true to preview.
• memory_lint (destructive) – Runs rule-based and LLM contradiction checks, outputting results to wiki/_lint/.
• memory_install_self_routing (read-only) – Returns the routing snippet and managed Agent Skill payloads for installing the tool surface itself.

How to Discover ai-memory MCP Tools Programmatically

While the Architecture document provides static documentation, you can retrieve the live tool catalogue through three methods:

Reading the Canonical Architecture Document

The authoritative source remains docs/ARCHITECTURE.md at lines 49-71, where the "MCP tool surface (18 tools)" section provides the ground-truth listing【/cache/repos/github.com/akitaonrails/ai-memory/main/docs/ARCHITECTURE.md#L49-L71】. This document updates when the tool surface changes, making it the definitive reference for implementation details.

Using memory_install_self_routing

Invoke the memory_install_self_routing tool to retrieve the current routing snippet containing the up-to-date tool catalogue:

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

The JSON response includes a routing field listing all 18 tools in the current deployment order.

Querying via the CLI

The ai-memory CLI can generate tool listings during MCP client installation. While no dedicated list sub-command exists, the --dry-run flag prints the generated tool JSON without registering it:

ai-memory install-mcp --client cursor --dry-run

This outputs the tool definitions that would be registered for the specified client (Claude Code, Cursor, Zed, etc.), as implemented in crates/ai-memory-cli/src/commands/install_mcp.rs.

Practical Examples of Using ai-memory MCP Tools

Searching Memory with memory_query

Execute full-text searches against the vector and graph indices:

curl -X POST http://127.0.0.1:49374/mcp \
     -H 'Content-Type: application/json' \
     -d '{
           "tool":"memory_query",
           "params":{"query":"ai-memory architecture","limit":5}
         }'

The response returns JSON containing hits with page metadata, content snippets, and optional score_details when relevance scoring is enabled.

Writing Pages with memory_write_page

Create durable wiki entries with optional expiration dates:

curl -X POST http://127.0.0.1:49374/mcp \
     -H 'Content-Type: application/json' \
     -d '{
           "tool":"memory_write_page",
           "params":{
               "path":"knowledge/ai-memory_overview.md",
               "body":"# ai-memory Overview\n...",

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

Returns { "ok": true, "page_id": 12345 } on success, with the admission chain firing asynchronously.

Triggering Auto-Improvement

Review the current session and stage automated wiki edits:

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

The response indicates the processed session ID and any staged improvements ready for human review.

Retrieving the Tool Catalogue

For dynamic client configuration, fetch the routing snippet:

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

This returns the complete tool list suitable for programmatic client registration, ensuring your agent always knows the current 18-tool surface exposed by the akitaonrails/ai-memory server.

Summary

• ai-memory exposes exactly 18 MCP tools following a "narrow on purpose" design philosophy documented in docs/design-decisions.md §10.
• Read the Architecture document at docs/ARCHITECTURE.md lines 49-71 for the definitive tool reference【/cache/repos/github.com/akitaonrails/ai-memory/main/docs/ARCHITECTURE.md#L49-L71】.
• Query programmatically using memory_install_self_routing or the CLI's install-mcp --dry-run to discover the live tool surface.
• Route calls through crates/ai-memory-mcp/src/lib.rs, which dispatches HTTP POST requests to individual tool handlers in crates/ai-memory-mcp/src/tools/*.
• Use hints (read-only, write, destructive) to understand side effects before invoking tools like memory_forget_sweep or memory_consolidate.

Frequently Asked Questions

What is the complete list of ai-memory MCP tools?

The complete list includes 18 tools: memory_query, memory_recent, memory_read_page, memory_read_session_observations, memory_status, memory_briefing, memory_explore, memory_handoff_begin, memory_handoff_accept, memory_handoff_cancel, memory_consolidate, memory_feedback, memory_auto_improve, memory_write_page, memory_delete_page, memory_forget_sweep, memory_lint, and memory_install_self_routing. This catalogue is hardcoded in the Architecture document and retrievable via the memory_install_self_routing tool.

Why does ai-memory limit the MCP surface to exactly 18 tools?

According to the source code analysis of docs/design-decisions.md §10, the project follows a "narrow on purpose" philosophy. New tools must earn their place in the surface API, ensuring the attack surface remains minimal and the interface stays comprehensible for AI agents. This constraint forces careful consideration of which operations truly require first-class MCP exposure versus internal implementation details.

How do I determine if an ai-memory MCP tool is safe to call?

Each tool carries a hint attribute documented in the Architecture table: read-only indicates no state changes, write indicates state modification without data loss risk, and destructive indicates operations that delete or irreversibly transform data. For example, memory_forget_sweep and memory_delete_page carry destructive hints, while memory_query and memory_status are read-only.

Where is the MCP tool routing logic implemented in the source code?

The HTTP router that dispatches MCP calls lives in crates/ai-memory-mcp/src/lib.rs, which routes incoming requests to individual tool implementations in crates/ai-memory-mcp/src/tools/* (e.g., memory_query.rs, memory_write_page.rs). The CLI generation logic for tool registration resides in crates/ai-memory-cli/src/commands/install_mcp.rs, with documentation in docs/mcp-install.md【/cache/repos/github.com/akitaonrails/ai-memory/main/docs/mcp-install.md#L19-L35】.

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