# Complete Guide to Read Category MCP Tools in ai-memory

> Explore 17 read-only MCP tools in akitaonrails/ai-memory. Safely query the SQLite store via the /mcp endpoint without data mutation for efficient agent interactions.

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

---

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

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

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

```

Retrieving recent activity:

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

```

Generating a scope briefing:

```json
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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs).

Canonical documentation appears in [`AGENTS.md`](https://github.com/akitaonrails/ai-memory/blob/main/AGENTS.md) (root directory), which serves as the definitive tool catalog for agent developers, while [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/AGENTS.md) and [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/AGENTS.md) at the repository root, which specifies available tools, their JSON schemas, and expected behavior patterns. The [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md) file provides additional context on how these tools integrate with the broader ai-memory storage system.