# ai-memory MCP Tools: Complete Guide to All 18 Available Tools

> Explore all 18 ai-memory MCP tools for query, retrieval, session management, and more. This complete guide details every available single-call tool for your technical needs.

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

---

**The ai-memory MCP server exposes 18 single-call tools** for query, retrieval, session management, page operations, and maintenance—accessed via HTTP POST to the `/mcp` endpoint.

The **ai-memory** repository by akitaonrails implements a Memory-Control-Protocol (MCP) server that gives LLM agents durable, structured memory through a compact tool surface. Each **memory_*** function represents one discrete capability that agents can invoke without chaining multiple requests. This article catalogs all 18 tools as documented in [`docs/usage.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md) and implemented across the Rust codebase.

## Query and Retrieval Tools (6 tools)

These six tools handle search, browsing, and raw data access across the compiled wiki.

### memory_query

Performs **hybrid search** combining FTS-5 full-text search, entity matching, graph traversal, and optional vector similarity. This is the primary search interface for agents retrieving contextual information.

### memory_recent

Returns pages sorted by modification time, surfacing the most actively maintained content in a project.

### memory_briefing

Generates a **read-only summary** of recent project activity—useful for quick orientation when an agent starts work.

### memory_explore

Produces a **prose-style digest** that automatically scales its depth based on elapsed time since the last session. Longer gaps trigger more comprehensive summaries.

### memory_read_page

Fetches the raw markdown of a specific page by its path, enabling agents to consume full content when summaries are insufficient.

### memory_read_session_observations

Retrieves the raw observation records tied to a specific session UUID, exposing underlying data for debugging or deep analysis.

## Hand-off Management Tools (3 tools)

Session continuity relies on explicit hand-off notes passed between agent instances.

### memory_handoff_begin

Creates a **manual hand-off**—a short "what-to-do-next" note saved before ending a session. This captures intent for the next agent instance.

```bash
ai-memory handoff begin --body "Finish the auto-improve run tomorrow"

```

### memory_handoff_accept

Consumes a pending hand-off when a new session starts, transferring context across the session boundary.

```bash
ai-memory handoff accept

```

### memory_handoff_cancel

Invalidates a hand-off that was created in error, preventing stale guidance from reaching future sessions.

## Session and Project Administration Tools (5 tools)

These tools manage the workspace hierarchy and report system health.

### memory_status

Reports **aggregate counts**: pages, observations, sessions, plus health status of configured LLM and embedding providers.

### memory_sessions

Lists open or recent sessions for a project, showing activity patterns across the workspace.

### list_memory_projects

Enumerates all memory projects known to the server, supporting multi-project deployments.

### create_memory_project

Creates a new project with generated workspace and project UUID. This is the entry point for new memory domains.

### delete_memory_project

Removes a project and **all associated data**—use with caution as this is irreversible.

## Page-Level Operations Tools (4 tools)

Core CRUD and quality-control functions for wiki content.

### memory_write_page

Writes a durable wiki page with optional **pinning** or **time-bounding**. Pinned pages resist decay; time-bounded pages automatically expire.

```bash
ai-memory write-page \
  --path decisions/0010-embedding.md \
  --title "Embedding Provider Choice" \
  --body $'# Embedding Providers\n\nWe prefer OpenAI embeddings when available.' \

  --pinned

```

### memory_delete_page

Removes a page by exact path, permanently deleting its content from the store.

### memory_feedback

Records **structured feedback** (`helpful`, `not_helpful`, `stale`, `wrong`) on pages. This feeds into retention scoring and linting priorities.

### memory_lint

Runs **rule-based quality checks**: stale page detection, contradiction identification, duplicate title detection, and other consistency validation.

## LLM-Driven Automation Tools (2 tools)

These tools invoke the configured language model for intelligent processing.

### memory_consolidate

Triggers LLM generation of a **summary page** for a completed session, distilling ephemeral observations into durable knowledge.

### memory_auto_improve

Activates the **auto-improvement scheduler** to propose wiki edits based on recent session patterns. Can run automatically on schedule or be invoked manually:

```bash
ai-memory auto-improve --session-id <SESSION_UUID>

```

## Maintenance and House-Keeping Tools (2 tools)

System-level operations for health and configuration.

### memory_forget_sweep

Executes **decay-based pruning** of low-salience episodic pages, reclaiming storage while preserving high-value content.

### memory_install_self_routing

Installs the **minimal routing snippet** that makes MCP tools visible to agents. This is read-only and idempotent.

## Ingestion Tools (1 tool)

### memory_ingest

Directly inserts raw observations into the store. Primarily used by **internal ingestion pipelines** rather than interactive agents.

## Implementation Architecture

The 18 tools are implemented across layered Rust crates in the `akitaonrails/ai-memory` repository:

| File | Responsibility |
|------|--------------|
| [`docs/usage.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md) | Authoritative documentation of all tool schemas and behaviors |
| [`docs/mcp-install.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/mcp-install.md) | Agent registration patterns and request/response examples |
| [`crates/ai-memory-mcp/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/lib.rs) | HTTP `/mcp` endpoint and request dispatch |
| [`crates/ai-memory-mcp/src/tools.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/tools.rs) | Rust struct definitions for all 18 tool schemas |
| [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) | Page operations: write, read, delete |
| [`crates/ai-memory-store/src/store.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/store.rs) | SQLite storage layer for sessions, observations, and metadata |

All tools conform to the **single-call I8 constraint**: each completes in one HTTP POST with a JSON payload matching the tool's defined schema, returning structured results suitable for immediate agent consumption.

## Summary

- **18 total MCP tools** in ai-memory, grouped into 7 functional categories
- **Query and retrieval**: `memory_query`, `memory_recent`, `memory_briefing`, `memory_explore`, `memory_read_page`, `memory_read_session_observations`
- **Hand-off management**: `memory_handoff_begin`, `memory_handoff_accept`, `memory_handoff_cancel`
- **Project administration**: `memory_status`, `memory_sessions`, `list_memory_projects`, `create_memory_project`, `delete_memory_project`
- **Page operations**: `memory_write_page`, `memory_delete_page`, `memory_feedback`, `memory_lint`
- **LLM automation**: `memory_consolidate`, `memory_auto_improve`
- **Maintenance**: `memory_forget_sweep`, `memory_install_self_routing`
- **Ingestion**: `memory_ingest`

## Frequently Asked Questions

### How do I call ai-memory MCP tools from my agent?

Send an HTTP POST to `/mcp` with a JSON payload containing `tool` (the function name) and `arguments` (parameters object). The exact schema for each tool is defined in [`crates/ai-memory-mcp/src/tools.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/tools.rs) and documented in [`docs/usage.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md).

### What is the difference between memory_query and memory_recent?

`memory_query` performs intelligent hybrid search across all content using FTS-5, entities, graphs, and vectors. `memory_recent` simply returns pages sorted by modification time without semantic relevance ranking.

### When should I use memory_consolidate versus memory_auto_improve?

Use `memory_consolidate` after a session ends to generate a one-time summary page. Use `memory_auto_improve` periodically to trigger the scheduler that continuously suggests wiki improvements based on accumulated session patterns.