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

39 tools total: 17 read (always available) and 22 write (require --allow-writes or RECALL_MCP_ALLOW_WRITES=1).

Read (17)

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.
  • 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.
  • doctor
    Read-only health snapshot of the local database: size, WAL, FTS5 fragmentation, integrity check, row counts. No side effects.
  • locate_sessionsPro
    Find a past conversation by topic, id, current terminal name or a previous alias. Claude Code and Codex searched together. If you run a local terminal-messaging bridge it also reports whether that exact session is still reachable; without one, every result still carries its saved context and the status reads unknown.

Document buckets

  • bucket_list
    Every bucket you have created, with document and chunk counts.
  • bucket_search
    Hybrid keyword plus vector search inside one bucket. Returns passages with document path, heading and position.
  • bucket_expand
    Read around a hit in original document order. Never crosses into another document.

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 (22)

Require --allow-writes flag. Rate-limited (default 60/min, shared across all write tools), zod-validated, and audited when they change data.

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.
  • list_sessions_to_tag
    Surface untagged or partially-tagged sessions for review. Part of the auto-tag flow, so it is write-gated with the rest of it.
  • apply_tags
    Add tags to a session (merge-mode, never deletes).

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
    Group the agent sessions running in a repo right now into one thread, so a fan-out of parallel terminals reads as a single piece of work.
  • generate_thread_titles
    Generate coherent titles for sessions in thread DAG.

Maintenance

  • optimize
    Run the local maintenance pass: WAL checkpoint, FTS5 segment merge, refresh planner stats. Optional VACUUM requires the daemon to be stopped.

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 write that changes your data is recorded in an append-only mcp_audit_events table inside your local database at ~/.recall/db.sqlite. Each row carries the tool name, the arguments, the outcome ok, error or rate_limited, and a timestamp. Read tools are not audited, because they change nothing. It is SQLite rather than a text file, so you query it instead of grepping it:

sqlite3 ~/.recall/db.sqlite "SELECT at, tool, result FROM mcp_audit_events ORDER BY at DESC LIMIT 50;"

Write calls also share one rate-limit budget, a sliding 60-second window across every write tool, so a runaway agent loop cannot saturate it. The default is 60 writes per minute; set RECALL_MCP_RATE_LIMIT in the MCP server’s environment to change it. The budget is re-seeded from the audit table on restart, so reconnecting does not hand an agent a fresh allowance.

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