What Are the MCP Tools Exposed by the ai-memory Server?

The ai-memory server exposes exactly 19 MCP (Model-Centric Protocol) tools organized into read-only queries, hand-off coordination, and write/maintenance operations, all defined in crates/ai-memory-mcp/src/server.rs to provide agents with stable, predictable access to long-term memory.

The ai-memory project implements a compact MCP surface that allows AI agents to persist, retrieve, and manage knowledge across sessions. These MCP tools expose a stable API for reading observations, coordinating session hand-offs, and maintaining the knowledge base through automated maintenance routines.

Overview of the 19 MCP Tools

The MCP tool surface is intentionally limited to 19 narrowly-scoped operations to ensure stability and predictable behavior. According to the architecture documentation, these tools fall into three distinct categories designed to cover the full lifecycle of memory management.

Read-Only Query Tools

These six tools retrieve data from the knowledge base without modifying state:

• memory_query – Search observations and pages using semantic or keyword matching.
• memory_recent – Retrieve the most recent hits in the current project.
• memory_status – Check system health and storage statistics.
• memory_briefing – Generate a summary briefing of current context.
• memory_explore – Browse the knowledge graph structure.
• memory_read_page – Fetch specific markdown pages by path.
• memory_read_session_observations – Access observations tied to the current session.

Hand-Off and Session Coordination Tools

These four tools enable multi-agent workflows where one agent can pass context to another:

• memory_handoff_list – Display open handoffs left by other agents.
• memory_handoff_accept – Claim a handoff and receive its payload.
• memory_handoff_begin – Initiate a new handoff sequence.
• memory_handoff_cancel – Abort a pending handoff transaction.

Write and Maintenance Tools

These nine tools handle persistence, deletion, and automated upkeep:

• memory_write_page – Persist user-provided markdown content (the primary "remember this" entry point).
• memory_delete_page – Remove specific pages from storage.
• memory_lint – Run quality checks on stored content.
• memory_feedback – Record agent feedback on memory usefulness.
• memory_forget_sweep – Prune stale or low-value observations.
• memory_consolidate – Merge duplicate or related memories.
• memory_auto_improve – Trigger the auto-improvement pipeline that proposes edits to pages.
• memory_install_self_routing – Configure automatic routing rules.
• memory_feedback – Submit ratings on memory retrieval quality.

MCP Tool Schema and Billing

Each tool follows a common schema defined in crates/ai-memory-mcp/src/server.rs. By default, calls are project-scoped, requiring project and workspace arguments. Setting global=true removes these workspace constraints for cross-project operations.

The implementation automatically records per-client call counters between lines 412-420 of server.rs, enabling usage-based billing and monitoring without requiring client-side instrumentation.

How to Invoke MCP Tools

Agents interact with these tools via HTTP POST requests to /api/v1/mcp or through the built-in Rust client (ai_memory_core::McpClient). The following examples demonstrate representative operations using the Rust SDK.

Query Recent Pages

Retrieve the most recent hits in the current project:

let client = McpClient::new("http://localhost:49374");
let resp = client.call("memory_recent", json!({"limit": 10})).await?;
println!("Recent hits: {:#?}", resp["hits"]);

Write a Permanent Page

Persist markdown content to the knowledge base:

let payload = json!({
    "path": "notes/todo.md",
    "body": "# TODO\n- Fix bug #123",

    "scope": "project"  // default, can be "global"
});
client.call("memory_write_page", payload).await?;

List Open Handoffs

Discover handoffs left by other agents:

let resp = client.call("memory_handoff_list", json!({"state": "open"})).await?;
println!("Open handoffs: {:#?}", resp["handoffs"]);

Accept a Handoff

Claim a handoff and receive its payload:

let resp = client.call("memory_handoff_accept", json!({"handoff_id": "f3e2…"})).await?;
println!("Accepted data: {}", resp["payload"]);

Run Auto-Improvement

Trigger the maintenance pipeline that proposes edits to existing pages:

client.call("memory_auto_improve", json!({"dry_run": true})).await?;

Key Implementation Files

The MCP tool surface is distributed across several crates with distinct responsibilities:

• crates/ai-memory-mcp/src/server.rs – Central MCP dispatcher and tool definitions. This file contains all 19 tool implementations, their argument schemas, and routing logic.
• crates/ai-memory-mcp/src/admin.rs – Admin-only endpoints including activity counters and system metrics.
• crates/ai-memory-store/src/ops.rs – Low-level SQLite operations that power the MCP tools, handling the actual reads, writes, and handoff persistence.
• docs/ARCHITECTURE.md (lines 367-428) – High-level documentation of the MCP tool surface and design rationale for the 19-tool limitation.
• docs/mcp-install.md – Integration guide for exposing these tools to external agents such as Pi or Claude Desktop.

Summary

• The ai-memory server exposes 19 MCP tools categorized into read-only queries, hand-off coordination, and write/maintenance operations.
• All tool definitions live in crates/ai-memory-mcp/src/server.rs, with low-level storage handled by crates/ai-memory-store/src/ops.rs.
• Tools are project-scoped by default, with a global flag for cross-project access.
• The system tracks per-client call counters for billing and monitoring purposes.
• Hand-off tools enable seamless multi-agent session continuity.

Frequently Asked Questions

How many MCP tools does ai-memory expose?

The ai-memory server exposes exactly 19 MCP tools. This limited surface area is intentional, as documented in docs/ARCHITECTURE.md, to ensure the API remains stable and predictable for agent integrations.

What is the difference between project-scoped and global MCP calls?

By default, all MCP tools require project and workspace arguments to isolate data boundaries. Setting global=true in the request payload removes these constraints, allowing the tool to operate across all projects. This behavior is enforced in the schema validation logic within crates/ai-memory-mcp/src/server.rs.

Which MCP tool should agents use to persist new memories?

Agents should call memory_write_page to persist content. This is the primary "remember this" entry point that accepts markdown content, a file path, and an optional scope parameter. It is the only tool that creates new persistent pages in the knowledge base.

How do agents coordinate sessions using MCP hand-off tools?

Agents use memory_handoff_begin to create a transfer payload, then memory_handoff_list to discover open transfers. The receiving agent calls memory_handoff_accept with the specific handoff_id to claim the context and continue the session. This four-tool workflow enables seamless multi-agent collaboration without losing conversational context.

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