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

> Discover how to list and understand the 18 MCP tools in akitaonrails/ai-memory. Enhance AI agent capabilities with full-text search, wiki management, and long-term memory.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-08-22

---

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

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

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

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

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

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

```bash
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`](https://github.com/akitaonrails/ai-memory/blob/main/docs/design-decisions.md) §10.
- **Read the Architecture document** at [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/memory_query.rs), [`memory_write_page.rs`](https://github.com/akitaonrails/ai-memory/blob/main/memory_write_page.rs)). The CLI generation logic for tool registration resides in [`crates/ai-memory-cli/src/commands/install_mcp.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/install_mcp.rs), with documentation in [`docs/mcp-install.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/mcp-install.md)【/cache/repos/github.com/akitaonrails/ai-memory/main/docs/mcp-install.md#L19-L35】.