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

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 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.

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.

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.

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:

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	Authoritative documentation of all tool schemas and behaviors
docs/mcp-install.md	Agent registration patterns and request/response examples
crates/ai-memory-mcp/src/lib.rs	HTTP /mcp endpoint and request dispatch
crates/ai-memory-mcp/src/tools.rs	Rust struct definitions for all 18 tool schemas
crates/ai-memory-wiki/src/wiki.rs	Page operations: write, read, delete
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 and documented in 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.

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