Skip to content
Model Context Protocol

A local MCP server that gives any agent permanent memory across every Claude Code session.

Read tools for search and recall. Write tools for tags and threads. Audit log on by default. Rate-limited. Bound to 127.0.0.1. Built on the open Model Context Protocol so any MCP-aware agent can call it.

Install

Claude Code

Open Claude Code and run:

/plugin install claude-recall

One command. The MCP server auto-connects. No config files, no JSON editing.

VS Code

Install in VS CodeInsiders

Click the button. VS Code opens, confirms the server, done.

Manual setup (any MCP client)

Add this to your MCP client config. Works with Claude Code, VS Code, Cursor, or any tool that speaks MCP:

{
  "recall": {
    "command": "npx",
    "args": ["-y", "@clauderecallhq/cli", "mcp"]
  }
}

Tools the agent can call

33 tools total: 14 read (always available) and 19 write (require --allow-writes or RECALL_MCP_ALLOW_WRITES=1).

Read (14)

Core

  • list_projects
    Every Claude Code project with session/message counts and latest activity.
  • list_sessions
    Recent sessions with alias, tags, message counts; filters: project, tag, date range.
  • list_tags
    Every tag with counts, most popular first.
  • list_sessions_to_tag
    Surface untagged or partially-tagged sessions for review.
  • apply_tags
    Add tags to a session (merge-mode, never deletes).
  • search
    Full-text search across sessions; supports inline #tag-name tokens; BM25 + optional vector fusion.
  • find_similar_sessionsPro
    Find semantically similar sessions using vector embeddings.
  • semantic_statusPro
    Health snapshot of semantic search: model, worker, queue depth.
  • get_session
    Fetch full session metadata and ordered messages.
  • context_for_session
    Render session as condensed markdown, ready to inject.
  • recall_neighborhood
    Bundle parents/children/citations/similar sessions as one budget-bounded markdown blob.

Threads

  • thread_list
    All threads, newest first; can exclude archived.
  • thread_get
    Full thread detail with every session edge.
  • thread_for_session
    Return non-archived threads referencing a session.

Write (19)

Require --allow-writes flag. Rate-limited (default 60/min), zod-validated, and audited.

Metadata

  • add_tag
    Apply single tag; normalized server-side.
  • remove_tag
    Remove tag; recorded in append-only log.
  • set_alias
    Set human-friendly session alias; previous alias archived.
  • append_note
    Append markdown to session note; separated by ---.
  • create_collection
    Create new collection; optional parent, icon, color.
  • add_session_to_collection
    Add session to collection; idempotent.
  • remove_session_from_collection
    Remove session; recorded in append-only log.

Threads

  • thread_create
    Create thread, optionally seed with origin session.
  • thread_add_session
    Attach session; role=origin or child.
  • thread_set_parent
    Change parent within thread; null clears parent.
  • thread_remove_session
    Detach session from thread.
  • thread_rename
    Change thread display name.
  • thread_close
    Mark thread as closed (sets closed_at).
  • thread_reopen
    Clear closed_at on closed thread.
  • thread_archive
    Soft-delete thread; hidden by default.
  • thread_merge
    Move all edges from source to dest, delete source.
  • thread_split
    Peel sessions into new thread.
  • sync_active_sessions
    Capture currently-active terminals in a repo into a thread (Captain Code Pattern).
  • generate_thread_titles
    Generate coherent titles for sessions in thread DAG.

Write tools never delete user data. Tag removal and session detach are recorded in append-only logs. Three-layer durability holds for everything written through MCP, the same as for human writes.

Why MCP, not a wrapper API

MCP is the protocol Claude Code already speaks for tool use. Building Claude Recall as a first-class MCP server means agents call it the same way they call file edits or web fetches. No glue code. No custom adapter. No extra latency.

Audit log and rate limits

Every MCP call is appended to an on-disk audit log under ~/.recall/audit/. You can grep it. The MCP server enforces a per-tool rate limit so a runaway agent loop cannot saturate it. Default limits are conservative; configurable in the daemon settings.

Example agent prompt

Drop something like this into a fresh Claude Code session and the agent will reach into your history without you having to drive:

Find the session where I last touched the auth retry logic.
Pull condensed context for it. Tell me what I changed and what was still broken.

The agent calls search, then context_for_session, and answers from the retrieved context. No human session-id juggling.

Privacy posture

Read this next