Complete Guide to Read Category MCP Tools in ai-memory

The ai-memory repository exposes 17 read-only MCP (Memory Control Protocol) tools that query the underlying SQLite store through the ReaderPool type without mutating data, enabling safe agent interactions via the /mcp HTTP endpoint.

The akitaonrails/ai-memory project implements a persistent memory layer for AI agents organized around strict data access protocols. All Read category MCP tools are thin wrappers around methods defined in crates/ai-memory-store/src/reader.rs, specifically implemented via the ReaderPool struct that manages SQLite read connections for zero-side-effect operations.

What Are Read Category MCP Tools?

Read category MCP tools provide query-only access to the ai-memory store. Unlike Write category tools, these never invoke the SQLite writer or wiki-mutation APIs, making them safe for agents lacking write permissions. They expose functionality ranging from full-text search to session analytics, all routed through the core ReaderPool implementation in the Rust codebase.

Complete Inventory of Read MCP Tools

The repository defines 17 distinct Read tools, categorized by their functional domain.

Page Content and Structure

These tools retrieve document bodies, metadata, and graph relationships without loading unnecessary data.

• memory_read_page: Returns the complete markdown content including front-matter. Implemented via ReaderPool::read_page at crates/ai-memory-store/src/reader.rs:954.

• memory_list_pages: Enumerates all page paths within a specified workspace or project scope. Calls ReaderPool::list_pages.

• memory_page_meta: Retrieves title, updated-at timestamps, tags, and other metadata without fetching the body. Uses ReaderPool::page_meta at line 991.

• memory_page_links: Returns backlink and forward-link relationships (graph edges) for a specific page. Maps to ReaderPool::page_links at line 1090.

Search Capabilities

• memory_search_pages: Executes full-text search using SQLite FTS5 across all pages, optionally scoped to specific workspaces. Implements ReaderPool::search_pages.

• memory_hybrid_search: Combines vector similarity search with FTS5 full-text results for semantic ranking. Calls ReaderPool::hybrid_search.

Scope Analytics and Briefings

• memory_briefing: Generates a condensed "briefing" snapshot of a workspace or project scope, optimized for LLM context windows. Uses ReaderPool::briefing at line 809.

• memory_recent: Retrieves the most recently updated pages within a scope, sorted by modification time. Implements ReaderPool::recent at line 485.

• memory_status_counts: Provides aggregate statistics including page counts, session totals, and observation counts. Maps to ReaderPool::status_counts at line 645.

Session Management Tools

• memory_sessions_for_scope: Lists all session IDs associated with a given workspace or project scope. Calls ReaderPool::sessions_for_scope at line 455.

• memory_session_observations_scoped: Retrieves observations linked to a specific session, filtered by scope parameters. Uses ReaderPool::session_observations_scoped at line 578.

• memory_session_brief_pages: Returns a curated list of pages touched during a specific session, useful for generating changelogs. Implements ReaderPool::session_brief_pages at line 879.

• memory_session_summary_scoped: Produces structured summaries of session activity within a defined scope. Maps to ReaderPool::session_summary_scoped at line 454.

Workspace and Health Monitoring

• memory_list_projects: Enumerates all projects within a workspace, optionally including usage statistics. Uses ReaderPool::list_all_workspace_scopes at line 912.

• memory_list_workspaces: Lists all known workspaces registered in the store. Calls ReaderPool::list_all_scopes at line 923.

• memory_audit_contamination: Returns advisory contamination metrics for a scope without modifying audit trails. Implements ReaderPool::audit_contamination at line 660.

• memory_workflow_health_detail: Reports health diagnostics such as missing embeddings or index status for workspaces. Uses ReaderPool::health_detail_for_workspace at line 1117.

Invoking Read Tools via the MCP Endpoint

Agents interact with these tools through HTTP POST requests to /mcp. The JSON body requires three top-level fields: tool (the tool name), input (method parameters), and session_id (authentication token).

Fetching a specific page's content:

POST /mcp
{
  "tool": "memory_read_page",
  "input": {
    "workspace_id": "default",
    "project_id": "my-project",
    "path": "README.md"
  },
  "session_id": "example-session"
}

Performing a full-text search:

POST /mcp
{
  "tool": "memory_search_pages",
  "input": {
    "query": "ai-memory",
    "workspace_id": "default"
  },
  "session_id": "example-session"
}

Retrieving recent activity:

POST /mcp
{
  "tool": "memory_recent",
  "input": {
    "workspace_id": "default",
    "project_id": "my-project",
    "limit": 10
  },
  "session_id": "example-session"
}

Generating a scope briefing:

POST /mcp
{
  "tool": "memory_briefing",
  "input": {
    "workspace_id": "default",
    "project_id": "my-project"
  },
  "session_id": "example-session"
}

Core Implementation Architecture

The read-only toolset depends entirely on the ReaderPool type defined in crates/ai-memory-store/src/reader.rs. This pool manages SQLite read-only connections and exposes methods like read_page, search_pages, and briefing that directly back the MCP tool surface.

Tool registration and routing occur in crates/ai-memory-mcp/src/lib.rs, which maps incoming JSON-RPC calls to specific ReaderPool method invocations. The HTTP transport layer handling request parsing and session validation lives in crates/ai-memory-mcp/src/server.rs.

Canonical documentation appears in AGENTS.md (root directory), which serves as the definitive tool catalog for agent developers, while docs/ARCHITECTURE.md explains the integration patterns between MCP tools and the broader storage engine.

Summary

• ai-memory provides 17 read-only MCP tools for querying persistent memory without side effects.
• All Read tools delegate to ReaderPool methods implemented in crates/ai-memory-store/src/reader.rs.
• The tool surface covers page retrieval, full-text and hybrid search, session analytics, and workspace enumeration.
• Standard invocation uses HTTP POST to /mcp with JSON payloads containing tool, input, and session_id fields.
• Source authority derives from AGENTS.md and docs/ARCHITECTURE.md alongside the Rust implementation files.

Frequently Asked Questions

What distinguishes Read category MCP tools from Write tools?

Read tools exclusively query data through the ReaderPool and never modify SQLite records or wiki state. Write tools, conversely, acquire exclusive locks and mutate the store through separate writer interfaces, requiring elevated permissions that Read tools do not need.

How does memory_hybrid_search differ from memory_search_pages?

While memory_search_pages performs traditional FTS5 full-text search across page content, memory_hybrid_search combines vector similarity search with FTS5 results. This hybrid approach leverages embeddings stored in the SQLite vector extension to rank results by semantic relevance rather than just keyword matching.

Can I use Read tools without authentication?

No. All MCP tool invocations require a valid session_id in the request body, as enforced by the server implementation in crates/ai-memory-mcp/src/server.rs. However, Read tools do not require write-capable session permissions, allowing read-only agents to operate safely.

Where is the complete list of MCP tools documented?

The definitive catalog appears in AGENTS.md at the repository root, which specifies available tools, their JSON schemas, and expected behavior patterns. The docs/ARCHITECTURE.md file provides additional context on how these tools integrate with the broader ai-memory storage system.

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