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

> Discover the 19 MCP tools in ai-memory server for agents. Learn about read-only queries, hand-off coordination, and write/maintenance operations for stable long-term memory access.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: deep-dive
- Published: 2026-09-12

---

**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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```rust
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:

```rust
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:

```rust
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:

```rust
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:

```rust
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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs)** – Admin-only endpoints including activity counters and system metrics.
- **[`crates/ai-memory-store/src/ops.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs)**, with low-level storage handled by **[`crates/ai-memory-store/src/ops.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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.