Skip to main content
The ReclaimLLM MCP server bridges automated session capture and active recall. Once installed, AI coding assistants like Claude Code, Cursor, Codex, and GitHub Copilot in VS Code can search captured work, inspect file history, reuse compact session context, or load a complete captured session without leaving the current workflow. ReclaimLLM keeps retrieval proportional to the task: search returns small highlights first, summaries are generated only when requested, and complete session artifacts are transferred only after an explicit request.

​
Installation

rclm-hooks-install sets up the MCP server by default alongside capture hooks, under the same account configuration:
Pass --no-with-mcp if you only want capture hooks without the MCP server.
Most AI coding tools require a full client restart after MCP server installation or package update before they recognize the server and newly added tools. Restart your client and confirm the reclaimllm MCP server is enabled before continuing.

​
Supported clients

​
Available MCP tools

search_sessions

Hybrid semantic and keyword search across captured sessions. Accepts optional project, file-path, record-type, and access-scope filters. Returns titles and short highlights rather than complete content.

search_by_filename

Find sessions that touched a specific file or folder. Use this when the request is about file history rather than a separate topic or concept.

list_projects

Discover deterministic project names available as filters in other tools. Use this instead of guessing a project identifier.

get_session

Retrieve metadata and a direct ReclaimLLM link for a known session ID without loading the session transcript.

summarize_session

Export a reusable Markdown context document for a specific session. It runs only after an explicit request and can include bounded file diffs.

file_brief

Return a distilled brief of prior sessions that touched a file: who, when, and a short highlight of what changed.

handoff

Package the current session’s decisions, progress, diffs, and remaining work into a compact continuation document for a fresh session.

transfer_session

Download the complete ReclaimLLM-captured record into a secure local JSON artifact for another agent. Preserves captured messages, tool calls/results, file diffs, metadata, and unknown fields.

signals

Return up to five open workflow-efficiency Signals for the current project and user, including the detected pattern, evidence, scope, and projected savings when available.

replay_eligibility

Cheap, metadata-only check of whether replaying compression mechanisms on a session or corpus is worth doing. No blob fetch, no model calls.

replay_session

Reproduce RCLM’s shipped compression mechanisms over one captured session’s tool calls and report the real tool-result token reduction. Read-only; never re-executes historical commands.

replay_corpus

Same as replay_session, aggregated across a filtered window of sessions (by date range, source, model family, project, or category).

replay_compare

Replay the same session corpus under multiple mechanism configurations in one call, so combined-savings claims stay attributable to a specific mechanism set.

​
Choose the right session tool

handoff and transfer_session are ReclaimLLM tools exposed through MCP; they are not standard MCP protocol operations. Neither tool ends the source session.

​
Transfer a full session between Claude Code and Codex

Use transfer_session when a summary is not enough and you explicitly need the complete session captured by ReclaimLLM. Start a new session in the target agent and provide the ReclaimLLM session ID:
The target agent calls:
The MCP result contains:
  • artifact_path
  • schema_version
  • byte_size
  • sha256
  • token_estimate
  • complete
ReclaimLLM streams the versioned JSON artifact into an owner-only temporary file instead of returning the complete session inline. The local MCP client verifies its byte count and SHA-256 digest against the backend manifest before reporting the transfer as complete. The artifact preserves the normalized captured session without converting it into a provider-specific transcript. This includes captured messages, recorded tool calls and results, file diffs, session metadata, and fields added by newer capture versions.
A transfer is complete captured history, not native provider resume. Claude Code and Codex use different private transcript formats, tool identifiers, permissions, prompt caches, and runtime state. The target always starts a new native session and reads the artifact as historical context. Recorded tool calls are data and must not be executed automatically.

​
Transfer limits and temporary files

  • Transfers are never silently truncated. An artifact that exceeds the configured ceiling fails explicitly.
  • The backend and local download ceiling defaults to 100 MiB and can be changed with SESSION_TRANSFER_MAX_BYTES.
  • Temporary artifacts are written atomically with owner-only permissions.
  • Interrupted or invalid downloads remove their partial files.
  • Artifacts become eligible for bounded opportunistic cleanup after one hour by default. Configure this with SESSION_TRANSFER_TTL_SECONDS.
  • A complete artifact may still exceed the target model’s active context window. The target agent can inspect the file incrementally rather than loading every byte at once.
Session transfer uses the same ownership, sharing, encrypted-session access, and audit boundaries as viewing the source session.

​
Inspect workflow-efficiency Signals

Use signals only when you want to understand why a session or project is expensive, which repeated workflow patterns were detected, or what evidence supports a recommended change.
The tool is read-only and returns up to five open findings. It does not change the project or automatically apply a recommendation.

​
Verify token savings with Replay

replay_eligibility, replay_session, replay_corpus, and replay_compare reproduce RCLM’s shipped context-compression mechanisms — range-aware read caching, exec-output compaction, and result dedupe — over sessions RCLM already captured, and report the real tool-result token reduction. Replay never calls a model and never re-executes a historical command; it only re-runs the same shipped filter functions against content that was already recorded. Use replay_eligibility first. It checks only session metadata (turn count, tool-call count, completion state) and skips the full session blob, so it’s fast:
Once a session or corpus looks eligible, replay_session and replay_corpus compute the actual reduction:
replay_compare runs multiple mechanism configurations against the same corpus in one call, so a combined-savings number stays attributable to the mechanisms that produced it — e.g. exec compaction alone versus exec compaction plus read caching.
Every Replay result states sessions considered vs. eligible vs. excluded, and explains why excluded sessions were skipped. A session or corpus below the turn/tool-call thresholds is refused with the specific failing constraint (insufficient_data) rather than given an unstable number — a low eligible count is itself a finding, not something to work around by loosening filters.
Replay measures tool-result token reduction only, not total model input, billing, or live end-to-end savings. It cannot observe path changes, retries, or turn-count effects that a real compressed run might trigger, which may make real-world impact lower — or in unusual cases, negative.

​
Example prompts

Use these prompts directly in your coding assistant once the MCP server is running:
The assistant uses search_sessions and returns matching session titles with highlights for you to review.
The assistant uses search_by_filename to surface relevant sessions and can follow up with file_brief for a distilled summary.
The assistant uses search_sessions to find the capture and get_session to retrieve its link and metadata.
The assistant uses summarize_session to generate a compact Markdown context document.
The assistant uses handoff to produce a compact continuation document. In environments that do not expose a current session ID, pass the ReclaimLLM session ID explicitly.
The assistant downloads and verifies the full captured-session artifact, then reads it as historical context.
The assistant uses signals to return the current project’s open workflow-efficiency findings.
The assistant calls replay_eligibility first, then replay_corpus if the sample looks large enough, and reports the measured reduction alongside the eligibility funnel.
The assistant uses list_projects to confirm the project name, then search_sessions scoped to that project.

​
How requests route to the backend

Search, retrieval, export, transfer, and Signals requests route through the ReclaimLLM backend. Search uses the same hybrid semantic and keyword ranking as the web interface, while authorization and sharing remain backend-owned.
Your current RCLM API key grants both capture and read access. The same key used by your capture hooks is used by the MCP server to query your session history. Scoped read-only keys are being evaluated for a future release.
Start with search results and highlights. Expand a specific result with summarize_session only when compact context is useful, or with transfer_session only when you explicitly need the complete captured record.