MCP Search Tools
Relevant source files
The following files were used as context for generating this wiki page:
MCP Search Tools provide a standardized interface for querying persistent memory within the claude-mem ecosystem. By implementing the Model Context Protocol (MCP), these tools allow AI agents like Claude to programmatically access historical observations, session summaries, and project-specific knowledge stored in SQLite and Chroma vector databases.
The system utilizes a thin-client architecture where a dedicated MCP server acts as a wrapper, delegating complex business logic and database operations to a centralized Worker HTTP API. This design ensures efficient token usage through a multi-layered retrieval strategy, preventing context window saturation while maintaining deep access to project history.
Sources: src/servers/mcp-server.ts:1-12, README.md:144-150, src/services/worker/README.md:5-10
3-Layer Workflow Architecture
The core philosophy of the MCP Search Tools is Progressive Disclosure. Instead of fetching massive amounts of data in a single request, the tools enforce a 3-layer pattern that optimizes for token efficiency and relevance.
Workflow Pattern
- Search Layer: Identifies relevant entries and returns a compact index containing unique IDs. This typically costs ~50-100 tokens per result.
- Timeline Layer: Provides chronological context around a specific anchor ID to help the agent understand the sequence of events.
- Detail Layer: Fetches full observation data only for the specific IDs filtered by the agent in previous steps. This costs ~500-1,000 tokens per result but is only applied to highly relevant items.
Sources: src/servers/mcp-server.ts:121-137, README.md:152-164
Data Flow Diagram
The following diagram illustrates how an MCP tool request flows from the AI agent through the MCP Server to the Worker Service.
Available MCP Tools
The system exposes four primary tools through the mcp-search-server.
| Tool Name | Purpose | Key Parameters |
|---|---|---|
__IMPORTANT | Documentation tool providing workflow instructions to the agent. | N/A |
search | Full-text and filtered search of the memory index. | query, project, type, limit, dateStart |
timeline | Retrieves chronological context around an observation. | anchor (ID), depth_before, depth_after |
get_observations | Batch retrieval of full observation details. | ids (Array of Numbers) |
Sources: src/servers/mcp-server.ts:119-196, README.md:167-172
Tool Implementations
1. Search Tool
The search tool is the entry point for most queries. It proxies requests to the /api/search endpoint of the Worker Service. It supports various filters defined in the project's mode configuration, such as observation types (bugfix, feature, refactor, decision).
Sources: src/servers/mcp-server.ts:168-179, plugin/modes/code.json:5-48
2. Timeline Tool
The timeline tool allows agents to "scrub" through history. By providing an anchor ID, the agent can see what happened immediately before or after a specific event. It proxies to the /api/timeline endpoint.
Sources: src/servers/mcp-server.ts:181-189, src/services/worker/README.md:76-77
3. Batch Retrieval (get_observations)
To save on HTTP overhead and token counts, get_observations accepts an array of IDs. Unlike the search tools which use GET requests, this tool uses a POST request to the /api/observations/batch endpoint.
Sources: src/servers/mcp-server.ts:74-110, src/servers/mcp-server.ts:191-207
Technical Implementation Details
MCP Server Configuration
The MCP server is implemented in TypeScript and uses the @modelcontextprotocol/sdk. It is designed to be a "Thin HTTP Wrapper."
// Example of the HTTP delegation pattern in mcp-server.ts
async function callWorkerAPI(endpoint: string, params: Record<string, any>) {
const searchParams = new URLSearchParams();
for (const [key, value] of Object.entries(params)) {
if (value !== undefined) searchParams.append(key, String(value));
}
const url = `${WORKER_BASE_URL}${endpoint}?${searchParams}`;
const response = await fetch(url);
return await response.json();
}
Sources: src/servers/mcp-server.ts:40-66
Standardized Search Parameters
The SearchRoutes in the Worker Service handle a wide variety of specific search types, all of which are accessible via the unified MCP tools or direct API calls.
- Concept Search:
GET /search/by-concept(e.g., "how-it-works", "gotcha"). - File-based Search:
GET /search/by-file(filtering by specific paths). - Semantic Search: Handled via Chroma vector database integration for natural language queries.
Sources: src/services/worker/README.md:75-92, plugin/modes/code.json:49-78
Security and Protocol Integrity
The MCP server explicitly redirects console.log to stderr. This is critical because the MCP protocol uses standard input/output (stdio) for JSON-RPC messages; any stray text on stdout would corrupt the protocol and cause the connection to fail.
Sources: src/servers/mcp-server.ts:14-22
Summary of Configuration
MCP Search Tools are configured primarily through the settings.json file located in ~/.claude-mem/.
| Setting | Description | Default |
|---|---|---|
CLAUDE_MEM_WORKER_PORT | The port the worker API listens on for tool requests. | 37777 |
CLAUDE_MEM_MODE | Determines valid observation types and concepts for search. | code |
Sources: src/services/worker-service.ts:47, src/services/worker/README.md:7
The MCP Search Tools architecture provides a robust, scalable way for Claude to maintain continuity across coding sessions while strictly managing token consumption. By separating the MCP protocol handling from the core search logic, the system remains portable and extensible for future search providers or database backends.