Introducing a new way to review your PRs.

Read the announcement

thedotmack / claude-mem

Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More

View on GitHub

47 documents · Updated Nov 20, 2026

docs / mcp-recall-and-tooling

MCP recall and tool delivery

MCP recall and tool delivery makes retained memory available to compatible agents through one tool protocol. It supports local stdio clients and authenticated hosted clients, exposes search and context actions, and keeps the returned data inside the caller's team and project boundary.

MCP boundary

The MCP boundary connects an agent to memory without giving the agent direct access to storage. A client discovers tools through MCP, sends a tool call with structured arguments, and receives text content that it can inspect or place in a prompt.

Transport choices

The system supports two transport paths. The local path starts the installed MCP server as a child process and speaks over stdio. The hosted path uses streamable HTTP at /v1/mcp and sends a bearer key with each connection.

The hosted path is stateless at the MCP layer. Each request creates a server view over a backend already tied to the authenticated team. This makes local and hosted recall different transport choices for the same memory goal rather than separate memory stores.

References: src/…/ServerV1PostgresRoutes.ts• L1003-1063 plugin/…/mcp-server.cjs• L214-238

Hosted setup

Hosted setup creates a read-only API key and returns the MCP URL plus a paste-ready connection command. The raw key is shown once, so the client or operator must save it before leaving the key response.

The connection uses claude mcp add --transport http with the Authorization: Bearer header. A project-scoped key limits recall to that project. A team-scoped key can serve the projects allowed by the caller's team.

References: src/…/ServerV1PostgresRoutes.ts• L191-241 src/…/ServerV1PostgresRoutes.ts• L44-52

Local setup

Local setup registers claude-mem as an MCP stdio server. The installed plugin starts the bundled mcp-server.cjs entry point, so the agent does not need direct access to the memory store or to the worker's internal service.

Worker runtime uses the local worker-backed memory path. Server runtime routes observation_* tools through the server REST core instead and does not auto-start the worker. The runtime is checked for each call, so a runtime change can affect later calls without restarting the MCP process. Worker-only tools return a clear error while server runtime is selected.

References: plugin/.mcp.json• L1-12 plugin/…/mcp-server.cjs• L214-238 src/…/mcp-server.ts• L180-249 src/…/mcp-server.ts• L1204-1233

Client interaction

An MCP client first connects and asks which tools are available. It then calls a named tool with arguments and reads the returned content. The server keeps protocol errors separate from tool errors so a bad request can be reported to the agent without making the transport fail.

Discovery and calls

Tool discovery is runtime-aware. The client receives the tool name, description, input schema, and any client-use hints from tools/list; it can then choose a recall or delivery action that matches the current runtime.

Each call validates required values before it reaches memory access. A failed backend call, an unknown tool, or a missing argument returns MCP text marked as an error. This gives compatible agents a stable result shape for both successful and failed work.

References: src/…/mcp-server.ts• L1083-1114 src/…/mcp-server.ts• L1031-1041 src/…/recall-mcp-server.ts• L87-100 src/…/recall-mcp-server.ts• L146-157 plugin/…/mcp-server.cjs• L214-238

Tool visibility

Tool visibility prevents an agent from seeing actions that its selected runtime cannot serve. The MCP server computes the advertised list when the client asks for tools, while the complete handler set remains behind that list for the process.

Runtime-specific tools

Worker runtime advertises the progressive mem_search workflow and its worker-backed memory tools. It also provides explicit memory saving, workflow guidance, compatibility search, timeline lookup, detail lookup, and raw tool-use recall. Server runtime advertises server-backed observation tools for adding observations, recording events, searching observations, building context, and checking generation jobs.

The installed agent-facing catalog also includes a memory workflow guide, working-state tools, codebase inspection tools, deeper observation and raw tool-use recall, and knowledge-corpus actions. These actions help an agent manage ongoing work, inspect its current project, select the right recall depth, or query a focused knowledge set. They do not change the scope of retained-memory recall. File inspection stays inside the current project boundary.

Read-only recall, session context, code inspection, and corpus-listing tools advertise a read-only hint to compatible clients. This lets clients use those tools in plan mode without an extra prompt. Tools that write memory or work state, or change a corpus session, do not advertise that hint and keep their normal approval behavior.

When CLAUDE_MEM_WORK_STATE_ENABLED=false, the server removes work_state_write and work_state_read from the advertised catalog. It also rejects direct calls to those names with an MCP error, so a client that cached an earlier catalog cannot use disabled work-state tools.

The server runtime does not auto-start the local worker. This keeps server-backed tools independent from the worker and makes an incomplete server configuration visible as a tool error instead of silently using a different memory path.

References: src/…/mcp-tool-visibility.ts• L4-48 src/…/mcp-server.ts• L477-507 src/…/mcp-server.ts• L526-758 src/…/mcp-server.ts• L761-847 src/…/mcp-server.ts• L1085-1115 src/…/mcp-server.ts• L1204-1233 plugin/…/mcp-server.cjs• L220-251

Worker recall workflow

Worker recall uses progressive disclosure. The agent starts with mem_search, which returns a small index and a short continuation. Guided mode then moves through nearby context and selected full details. Auto mode completes the same bounded path in one call.

The workflow is exposed by important_workflow and described in the tool text. Agents should select IDs from the earlier result before requesting full details. The older search, timeline, get_observations, and get_tool_uses tools remain available for compatibility and advanced filters, but raw tool input and output stays a last resort because it can be much larger than an observation summary.

References: src/…/mcp-server.ts• L484-523 src/…/mcp-server.ts• L545-585 src/…/mcp-server.ts• L587-699 plugin/…/mcp-server.cjs• L223-247

Recall operations

Recall operations let an agent move from a broad memory view to a focused answer. The read-only hosted recall server exposes three actions: matching observations, recent observations, and a prompt-ready context pack.

Read-only recall

The hosted server advertises search, context, and recent. search returns relevant observations. recent returns the newest observations. context returns the matching observations plus a single string made by joining non-empty observation content with blank lines.

The server applies safe default and maximum result limits. It requires a non-empty project and query where the operation needs them, then calls a backend that already enforces team and project scope. It does not expose mutating tools through this recall surface.

References: src/…/recall-mcp-server.ts• L25-37 src/…/recall-mcp-server.ts• L39-80 src/…/recall-mcp-server.ts• L101-133

Hosted recall path

The hosted MCP route binds the read-only tools to the same Postgres observation data used by the versioned API. Authentication runs before the MCP handler, and each operation checks the key's project scope before reading.

Every hosted MCP read creates an audit record with its operation mode and result IDs. This keeps MCP reads visible in the same audit trail as REST reads while preserving one source of truth for search ranking and recent-record selection.

References: src/…/ServerV1PostgresRoutes.ts• L1010-1057 src/…/ServerV1PostgresRoutes.ts• L906-1001

Semantic search dependency

Worker semantic recall uses an internal chroma-mcp service to query vector data. ChromaMcpManager chooses local persistent data or a configured remote Chroma service, then presents that service through the same MCP tool-call model used by the worker.

The manager treats this service as a recoverable dependency. It prepares the runtime before connection, checks health through collection and query probes, retries transport failures once, and reports the dependency as unavailable when recovery fails. This keeps a vector-search problem from being mistaken for a general MCP protocol problem.

Local Chroma data has one writer owner at a time. The manager also limits and serializes local mutation calls, which protects the vector index while observations are added or changed.

References: src/…/ChromaMcpManager.ts• L187-299 src/…/ChromaMcpManager.ts• L379-427 src/…/ChromaMcpManager.ts• L754-835 src/…/ChromaMcpManager.ts• L872-935

Recall sequence

The following sequence shows how an agent moves from discovery to focused context without crossing the caller's memory boundary.

sequenceDiagram
    participant A as Agent
    participant M as MCP server
    participant G as Scope guard
    participant S as Memory store
    A->>M: list tools
    M-->>A: recall tools for selected runtime
    A->>M: search or mem_search(query)
    M->>G: check team and project
    G->>S: find matching observations
    S-->>M: ranked observations
    M-->>A: index or observation list
    A->>M: context or selected details
    M->>G: check team and project
    G->>S: find permitted observations
    S-->>M: observations
    M-->>A: focused context

References: src/…/recall-mcp-server.ts• L101-131 src/…/ServerV1PostgresRoutes.ts• L1010-1048 src/…/mcp-server.ts• L484-523

Prompt delivery

Prompt delivery turns recalled memory into content that an agent can use at session start or during an active task. The MCP layer provides the content, while the hook layer decides where it belongs in the agent's input and how to recover when MCP is unavailable.

Session-start context

The session_start_context tool asks the worker to render the same startup context used by the session hook. It accepts one project or a project chain, an optional platform source, full mode, and terminal-color mode. The project chain lets a worktree receive context from its parent and its primary project.

Codex requests this tool during SessionStart and places the returned text in model context. It does not copy that text into the user-visible system message because duplicate output can exceed the hook payload limit. A failed MCP request falls back to /api/context/inject.

References: src/…/mcp-server.ts• L386-435 src/…/mcp-server.ts• L739-759 src/…/context.ts• L83-121

Context packing

The context recall action is for a focused prompt injection. It preserves the structured observations for callers that need IDs and metadata, then supplies a joined context field for callers that only need readable memory.

The hosted REST context route uses the same packing rule as the hosted MCP tool. It searches the permitted project, removes empty content from the prompt string, and joins the remaining content with a blank line.

References: src/…/recall-mcp-server.ts• L114-125 src/…/ServerV1PostgresRoutes.ts• L952-1000 src/…/server-client.ts• L170-187

Prompt search categories

The worker search tool can search observations, sessions, or prompts when the caller uses the document category filter. The hosted recall tool is narrower: it reads observations only, which keeps its contract focused on retained memory that is ready for recall.

This difference matters when an agent moves between runtimes. A query that asks for prompt or session records must stay on the worker path rather than being sent to the observation-only server search endpoint.

References: src/…/mcp-server.ts• L587-635

Output parsing

Output parsing gives callers one simple text view over MCP's content array. The server serializes structured recall payloads as JSON text, while clients collect text content items and preserve the MCP error flag.

Structured results

Hosted recall results use JSON text with an observations field. Context results add a context field. Local server-mode observation tools follow the matching REST response shape, so callers can read observation and job results without a second MCP-specific data model.

The local mem_search workflow returns readable text for each bounded step. The client keeps only text content items and carries forward isError when the worker marks the result as failed. Other agent-facing tools return readable text for workflow guidance, project work state, codebase inspection, corpus actions, and workspace inspection.

References: src/…/recall-mcp-server.ts• L95-97 src/…/mcp-server.ts• L504-523 src/…/mcp-server.ts• L217-223 src/…/server-client.ts• L161-187 src/…/ChromaMcpManager.ts• L808-835 plugin/…/mcp-server.cjs• L227-251

Error results

A tool failure is returned as text with isError: true. A missing required argument and a scope rejection use the same result shape as a backend failure, so the client can report the cause without treating it as a broken MCP connection.

The internal Chroma caller turns transport failures into a reconnect attempt and turns an unsuccessful tool result into an error for its search caller. A caller that needs a fallback can then distinguish unavailable vector search from a valid empty result.

References: src/…/recall-mcp-server.ts• L148-157 src/…/mcp-server.ts• L223-235 src/…/mcp-server.ts• L1000-1017 src/…/ChromaMcpManager.ts• L773-835

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the local stdio registration and hosted HTTP connection command aligned with the server entry point and transport supported by compatible clients.
  • Keep tools/list filtering aligned with runtime selection. A tool must not be advertised when its handler requires an unavailable worker or server configuration.
  • Keep work-state catalog filtering and call-time rejection aligned. A disabled work-state feature must stay hidden from discovery and blocked for clients that use a stale catalog.
  • Keep runtime switching aligned with each handler's backend. Server observation tools must not fall back to the worker, and worker-only recall must not silently query a different store.
  • Keep read-only tool hints aligned with actual side effects. Removing a hint can block safe recall or inspection in plan mode, while adding one to a writer can bypass the expected approval step.
  • Keep the installed MCP tool catalog aligned with the source tool set. New recall-depth, work-state, file, or corpus actions must not imply broader memory access than the selected runtime allows.
  • Keep the workspace file boundary aligned with the project selected by the client. A path check must not allow a file tool to escape that project.
  • Keep local and hosted recall limits, project checks, platform handling, and output fields aligned where they promise the same recall behavior.
  • Keep progressive mem_search continuations, selected IDs, and detail limits aligned with the worker contract. Do not make callers fetch full details before filtering.
  • Keep context packing stable across MCP and REST. Agents may inject the returned string directly into a prompt.
  • Keep MCP text serialization aligned with every client that parses text content. Changing content types or JSON wrapping can turn valid tool results into malformed output.
  • Keep session_start_context arguments aligned with /api/context/inject and the session hook so project chains and platform filters do not silently change meaning.
  • Keep server runtime observation writes and event recording aligned with the shared REST path so MCP does not create a second write or job path.
  • Keep the internal Chroma MCP dependency's local or remote mode, health state, and single-writer rule aligned with semantic search availability.
  • Keep read-only hosted MCP scope and audit metadata intact when changing the backend or adding a recall operation.

Important failure modes

TriggerConsequenceGuard
The hosted client omits or uses an invalid bearer keyMCP connection or recall is rejected before memory accessThe route applies read authentication and team/project scope checks.
A project-scoped key requests another projectThe recall call returns an error instead of cross-project observationsThe hosted backend checks the key's project scope for every operation.
A worker-only tool is called while server runtime is selectedThe call cannot use the local worker pathRuntime-aware discovery hides incompatible tools and worker-only handlers return a runtime error.
A server-only tool is called while worker runtime is selected or server settings are incompleteThe call returns a clear tool error instead of writing to or reading from an unintended pathServer observation handlers require server runtime and complete server configuration.
Work state is disabled after a client cached the tool catalogA direct call to a disabled work-state tool returns an MCP errorDiscovery removes the work-state tools, and the call handler checks the setting again before execution.
A read-only tool lacks its MCP read-only hintA compatible client can block the tool or ask for an unnecessary prompt in plan modeThe source marks read-only recall, context, inspection, and listing tools before advertising them.
The installed MCP server entry point or worker bundle cannot be found or startedLocal tool calls fail before discovery or recall, or worker-backed tools fail after discoveryThe plugin registration points to the bundled server entry point and worker startup reports the missing or dead worker.
The marketplace directory is missing while only a cached plugin copy existsMCP search can work, but hooks do not capture new memoriesStartup reports the missing marketplace marker and directs the operator to repair the plugin install.
A file tool resolves outside the current projectThe agent could read data outside the intended workspaceThe bundled server resolves the path and rejects paths outside the project root.
session_start_context fails for CodexThe session could start without its startup memoryThe hook falls back to the worker context endpoint and can return a safe empty result.
A recall backend rejects a scope or argumentThe agent receives an MCP tool error rather than a transport crashTool handlers validate arguments and convert backend failures to isError: true results.
The internal Chroma service is unavailable or its collection is missingSemantic recall is unavailable even when MCP transport worksPrewarm, health probes, bounded reconnects, and dependency-health reporting expose the failure.
More than one local Chroma writer uses the same data directoryVector writes can conflict or corrupt the local indexA writer lock and serialized local mutation calls allow one owner at a time.

Key files

FileWhy to read it
src/…/recall-mcp-server.tsDefines the hosted read-only recall contract, limits, context packing, and MCP error behavior.
src/…/ServerV1PostgresRoutes.tsShows hosted MCP setup, API-key creation, HTTP transport, scope checks, audit records, and the shared Postgres read path.
src/…/mcp-server.tsDefines the local stdio server, runtime-aware discovery, progressive worker recall, session-start delivery, server-mode observation tools, work-state visibility, codebase tools, and corpus tools.
src/…/mcp-tool-visibility.tsShows which tools are visible in worker and server runtimes and when work-state tools are removed.
plugin/…/mcp-server.cjsShows the installed MCP catalog, staged recall workflow, project-bound file tools, corpus actions, and the bundled agent-facing server boundary.
src/…/context.tsShows how Codex uses MCP for session-start context and falls back to worker HTTP.
plugin/.mcp.jsonShows the installed local MCP registration and launcher boundary.
src/…/server-client.tsDefines the server-mode response shapes for observation search and prompt-ready context.
src/…/ChromaMcpManager.tsShows how worker semantic search reaches the internal Chroma MCP service and how availability and local writes are controlled.