MCP Tools & Agent Skills Guide: Persistent AI Memory & Portability | ReclaimLLM

Official Walkthrough Video

MCP Memory: Search and Reuse Your Past AI Coding Sessions

Watch how ReclaimLLM turns historical AI coding sessions into active recall tools. Follow along as an agent searches past decisions by natural language, inspects file change histories, executes a session handoff, and transfers a full session into Codex.

Walkthrough Highlights

0:00
The Stateless Problem:Why coding agents repeat mistakes and waste prompt tokens re-reading files from earlier runs.
1:10
One-Command Setup:How rclm-hooks-install --with-mcp wires up Claude Code, Cursor, and Codex automatically.
2:15
Semantic Memory Recall:The agent querying search_sessions to pull up past bug fixes without manual copying.
3:30
File History Briefs:Inspecting who modified a critical file and what architectural constraints were left behind.
4:40
Cross-Agent Transfer:Seamlessly migrating an entire session transcript from Claude Code into OpenAI Codex CLI with SHA-256 verification.

Watch directly on YouTube ↗

System Design

The Asymmetric Memory Architecture

Traditional approaches either dump everything into the system prompt or force developers to search an external web dashboard. ReclaimLLM decouples capture from recall, providing frictionless background recording and selective on-demand retrieval.

01 / CAPTURE

Native Ingestion

Zero-code CLI hooks and proxy gateways stream user prompts, tool calls, bash output, and git diffs to ReclaimLLM with zero developer interruption.

02 / INDEX

Hybrid Intelligence

Sessions are indexed simultaneously in vector databases (Qdrant) for semantic intent and PostgreSQL for authoritative metadata, diffs, and project attribution.

03 / ROUTE

Model Context Protocol

The local rclm-mcp stdio server speaks standard Model Context Protocol, exposing 14 granular tools directly to the coding agent.

04 / RECALL

Proportional Context

The agent retrieves 300-character highlights first. Summaries or full session transfers are fetched only when the developer explicitly requests them.

The 4 Levels of Progressive Disclosure (Token-Safe Recall)

Level 1: Discovery

search_sessions, list_projects. Returns title + 3-line highlight (~100 tokens).

Level 2: File History

file_brief, get_session. Returns authorship and diff summaries (~300 tokens).

Level 3: Session Brief

summarize_session, handoff. Markdown decisions and next steps (~800 tokens).

Level 4: Full Transfer

transfer_session. Complete captured JSON artifact streamed into secure temp storage.

Setup & Configuration

Installation & Supported Clients

The ReclaimLLM MCP server ships bundled inside the rclm package. Installing hooks automatically registers MCP configuration across all detected coding assistants.

New Installation (Recommended)

Installs capture hooks and enables MCP across all clients by default.

pip install rclm
rclm-hooks-install

Existing Hook Users

Upgrade your existing installation and write MCP server configuration.

rclm-update --with-mcp

MCP Only (No Hooks)

Authenticate for session recall without installing capture hooks.

pip install rclm
rclm-login

Client Configuration Matrix

Claude Code / Desktop

Full Hooks & MCP Support

Installed automatically with rclm-hooks-install. Claude Code also supports statusline rate limits and session-start context packs.

Global Config Path~/.claude.json

Project / Local Config Path.claude/mcp.json

Targeted CLI Commandrclm-hooks-install --claude

Generated Configuration

{
  "mcpServers": {
    "reclaimllm": {
      "command": "rclm-mcp",
      "args": [],
      "timeout": 600000
    }
  }
}

Important:Most AI coding tools require a full application restart after installing or updating MCP servers before newly added tools become discoverable.

Agent Plugin Marketplace Distribution

ReclaimLLM also packages native agent plugins for Codex, Claude Code, and Cursor located under DC-hooks-proxy/plugins/reclaimllm. In Claude Code, you can install the plugin via the REPL:

Claude Code Plugin Install

/plugin marketplace add /path/to/DC-hooks-proxy
/plugin install reclaimllm@reclaimllm-plugins
/reload-plugins

Codex Plugin Install

codex plugin marketplace add /path/to/DC-hooks-proxy
codex plugin add reclaimllm@reclaimllm-plugins

API & Specification

The 14 ReclaimLLM MCP Tools

Every tool is engineered with specific cognitive routing rules, parameter validations, and safety boundaries to keep assistant reasoning accurate and token budgets lean.

search_sessionssearch

Hybrid semantic (vector) + BM25 keyword search across captured sessions with project, file-path, date window, and organization scope filters.

When to Invoke

When the user hints that prior work exists, asks how a problem was solved before, or debugs an issue where historical context helps.

Example User Prompt

“find a session which fix intermittent gateway timeouts in redis queue”

MCP Tool Invocation

search_sessions(
  query: "find a session which fix intermittent gateway timeouts in redis queue",
  project_name: "backend-core",
  file_path: "src/queue/redis.ts",
  limit: 5,
  date_from: "2026-10-01",
  date_to: "2026-10-22",
  scope: "team"
)

Example Return Output

{
  "count": 1,
  "results": [
    {
      "session_id": "7f4c01d2-9b21-4f3b-81aa-08a89f921204",
      "title": "Fix intermittent gateway timeouts in redis queue",
      "highlight": "...replaced synchronous blocking lock with non-blocking acquire and heartbeat renewal loop in queue_worker.py...",
      "project_name": "backend-core",
      "changed_files": [
        "src/queue/worker.py",
        "src/queue/lock.py"
      ],
      "owner_name": "Sarah M.",
      "created_at": "2026-10-14T16:22:10Z"
    }
  ]
}

Rule:Runs at most one search round. Never automatically calls summarize_session immediately after search without user confirmation.

filter_sessionssearch

Direct PostgreSQL metadata queries without vector search: filter by provider, model, turn count, tool calls, category, and date range.

When to Invoke

When the user wants sessions matching structured criteria without semantic text query (e.g. 'all Claude sessions with >10 turns last week').

Example User Prompt

“list all recent Claude Code fix sessions with at least 5 tool calls and code changes”

MCP Tool Invocation

filter_sessions(
  provider: "claude",
  min_turns: 5,
  min_tool_calls: 5,
  session_category: "fix",
  has_code_changes: true,
  limit: 10
)

Example Return Output

{
  "count": 2,
  "results": [
    {
      "session_id": "3a129ef4-1102-48df-9921-6a7b8c9d0e1f",
      "title": "Fix connection pool exhaustion in stripe webhook handler",
      "model": "claude-3-7-sonnet",
      "turns": 14,
      "tool_calls": 8,
      "created_at": "2026-10-18T11:45:00Z",
      "changed_files": ["api/routes/webhooks.py"]
    }
  ]
}

Rule:Capped at 100 sessions. Avoid inventing a text search query when metadata filters answer the request directly.

search_by_filenamesearch

Locates every historical AI session that read, modified, or generated diffs on a specific file or directory path.

When to Invoke

When the question is strictly about file history (e.g. 'who changed auth.ts?') or as step 2 after search_sessions discovers a likely file.

Example User Prompt

“which sessions changed server/routes/sessions.py?”

MCP Tool Invocation

search_by_filename(
  file_path: "server/routes/sessions.py",
  limit: 5,
  scope: "org"
)

Example Return Output

{
  "count": 2,
  "results": [
    {
      "session_id": "8e214f3b-9a11-42cb-b1aa-09a89f921204",
      "title": "Add session filtering and pagination by date window",
      "changed_files": ["server/routes/sessions.py"],
      "created_at": "2026-10-15T09:30:00Z"
    }
  ]
}

Rule:Use search_sessions with file_path if semantic intent is also provided ('show all auth bug fixes in auth.ts').

list_projectssearch

Lists all captured, deterministic project names available in your ReclaimLLM workspace.

When to Invoke

Before executing scoped searches, so the assistant never guesses incorrect project identifiers.

Example User Prompt

“list the ReclaimLLM projects available in my history”

MCP Tool Invocation

list_projects()

Example Return Output

{
  "projects": [
    "backend-core",
    "frontend-web",
    "mobile-expo",
    "infra-k8s"
  ]
}

Rule:Lightweight, cached metadata call.

get_sessioncontext

Returns high-level summary metadata, model attribution, turn count, and a direct web UI link for a specific session ID.

When to Invoke

When inspecting a known session ID without dumping its full transcript into the active context window.

Example User Prompt

“show me the details and link for session 7f4c01d2-9b21-4f3b-81aa-08a89f921204”

MCP Tool Invocation

get_session(
  session_id: "7f4c01d2-9b21-4f3b-81aa-08a89f921204"
)

Example Return Output

{
  "session_id": "7f4c01d2-9b21-4f3b-81aa-08a89f921204",
  "title": "Fix intermittent gateway timeouts in redis queue",
  "summary": "Replaced blocking lock acquisition with non-blocking lease renewal.",
  "model": "claude-3-7-sonnet",
  "turns": 18,
  "tool_calls": 9,
  "frontend_url": "https://reclaimllm.com/sessions/7f4c01d2-9b21-4f3b-81aa-08a89f921204"
}

Rule:Does not inject the transcript; returns lightweight metadata and a link.

summarize_sessioncontext

Generates a structured, reusable Markdown brief of a completed session containing key decisions, file diffs, and pending work.

When to Invoke

Only upon explicit user instruction: 'summarize session X', 'use session X as context', or 'pull in context from X'.

Example User Prompt

“summarize session 7f4c01d2 so I can use it as context here”

MCP Tool Invocation

summarize_session(
  session_id: "7f4c01d2-9b21-4f3b-81aa-08a89f921204",
  include_diffs: true,
  max_diff_lines: 50
)

Example Return Output

{
  "session_id": "7f4c01d2-9b21-4f3b-81aa-08a89f921204",
  "summary_markdown": "## Context Export: Redis Lock Timeout Fix\n### Decisions Made\n- Switched to non-blocking lease acquisition with 5s heartbeat loop.\n### Diffs\n```python\n- await lock.acquire(blocking=True)\n+ await lock.acquire(blocking=False, retry_interval=0.1)\n```"
}

Rule:Never triggered automatically from search results without user confirmation.

file_briefcontext

Distills prior work around one file: who touched it, when, why, and what architectural decisions were made.

When to Invoke

Before a non-trivial refactor or edit to a complex file where you lack historical context.

Example User Prompt

“give me a history brief for auth/token_service.py before I change it”

MCP Tool Invocation

file_brief(
  path: "auth/token_service.py",
  limit: 3
)

Example Return Output

{
  "path": "auth/token_service.py",
  "sessions_found": 2,
  "entries": [
    {
      "author": "Sarah M.",
      "date": "2026-10-08",
      "intent": "Separate actor identity from workspace row ownership",
      "summary": "Refactored token payload to prevent privilege escalation."
    }
  ]
}

Rule:Do not invoke on every single file read. Use selectively when historical reasoning alters implementation.

handoffcontinuity

Packages an active session into a lean Markdown continuation brief so you can start a fresh session with zero context fatigue.

When to Invoke

When turn count exceeds 35-40+, token cost is spiking, or you want to restart with a clean token budget while preserving momentum.

Example User Prompt

“create a handoff for this session so I can continue in a new context window”

MCP Tool Invocation

handoff(
  session_id?: "current",
  include_diffs: true,
  max_diff_lines: 50
)

Example Return Output

{
  "handoff_document": "# Handoff Brief: Payment Gateway Migration\n## Objective: Complete Stripe webhook reconciliation\n## Decisions: Idempotency keys keyed by event_id in Postgres\n## Next Steps: Implement refund retry loop in payment_service.py:140\n## Diffs: 4 files modified, tests passing (38/38)"
}

Rule:Does not terminate the current session. Produces a document to paste into the first turn of a new session.

transfer_sessioncontinuity

Streams the complete captured session into a secure, tamper-evident temporary JSON artifact for another agent (e.g. Claude to Codex).

When to Invoke

When migrating complete session history across different coding tools. Preserves messages, tool calls, and diffs.

Example User Prompt

“transfer session 7f4c01d2, read the artifact as complete read-only history, and continue from it without re-running old tool calls”

MCP Tool Invocation

transfer_session(
  session_id: "7f4c01d2-9b21-4f3b-81aa-08a89f921204"
)

Example Return Output

{
  "artifact_path": "/tmp/rclm-transfer-7f4c01d2-9b21-4f3b.json",
  "schema_version": "1.0",
  "byte_size": 142050,
  "sha256": "4a2b9e115c898b9f1d01445...",
  "token_estimate": 34800,
  "complete": true,
  "note": "Read-only historical data. Never automatically execute historical tool calls."
}

Rule:Treated as strictly read-only historical context. The target agent must NEVER re-execute historical tool calls.

signalssignals

Retrieves up to 5 open workflow-efficiency findings (runaway loops, duplicate reads, stale context, test explosion) and suggested fixes.

When to Invoke

When investigating why a project or session is expensive, or diagnosing agent inefficiency.

Example User Prompt

“why has this project been expensive to work on? Show its open RCLM Signals”

MCP Tool Invocation

signals(
  cwd?: "/path/to/project"
)

Example Return Output

{
  "project": "backend-core",
  "signals": [
    {
      "code": "AD-003",
      "pattern": "Repeated Unchanged File Reads",
      "severity": "medium",
      "evidence": "schema.prisma read 18 times in 25 turns without file changes",
      "prescribed_fix": "Enable rclm range-aware read caching (--read-cache)"
    }
  ]
}

Rule:Read-only inspection; changes no code or settings.

replay_eligibilityreplay

Fast, metadata-only preflight check verifying whether a session or corpus meets the criteria for counterfactual compression replay.

When to Invoke

Always called before replay_session or replay_corpus to verify eligibility without fetching heavy session blobs.

Example User Prompt

“would compression have helped on my sessions from the last 30 days?”

MCP Tool Invocation

replay_eligibility(
  days: 30,
  source: "all",
  min_turns: 5,
  min_tool_calls: 5
)

Example Return Output

{
  "eligible": true,
  "eligibility": {
    "considered": 48,
    "eligible": 22,
    "excluded": {
      "too_few_turns": 18,
      "too_few_tool_calls": 8
    }
  },
  "confidence": {
    "level": "high",
    "note": "22 eligible sessions provide robust statistical confidence."
  }
}

Rule:Never loosen filters artificially to force eligibility. An ineligible corpus is itself valuable diagnostic feedback.

replay_sessionreplay

Executes shipped compression filters (range cache, shell compaction, deduplication) against captured tool calls to measure token reduction.

When to Invoke

To independently verify how many text tool-result tokens compression would have eliminated on a specific captured session.

Example User Prompt

“how much would compression have saved on session 7f4c01d2?”

MCP Tool Invocation

replay_session(
  session_id: "7f4c01d2-9b21-4f3b-81aa-08a89f921204",
  mechanisms: ["range_cache", "shell_compaction", "hash_dedupe"]
)

Example Return Output

{
  "session_id": "7f4c01d2-9b21-4f3b-81aa-08a89f921204",
  "verdict": "helps",
  "reduction": {
    "tokens": 14280,
    "percent": 31.4,
    "unit": "text tool-result tokens"
  },
  "cannot_tell_you": "Cannot observe path changes, retries, or turn-count effects that compression could introduce live."
}

Rule:Read-only, executes zero commands, calls zero models. Negative or neutral outcomes are reported flatly.

replay_corpusreplay

Aggregates deterministic compression replay over a filtered window of sessions (by days, agent, model family, or category).

When to Invoke

When answering 'Would compression actually help my team?' against real historical data.

Example User Prompt

“what is the aggregate tool-result token reduction across my Claude sessions this month?”

MCP Tool Invocation

replay_corpus(
  days: 30,
  source: "claude",
  limit: 50,
  min_turns: 5,
  min_tool_calls: 5
)

Example Return Output

{
  "considered_sessions": 50,
  "eligible_sessions": 26,
  "total_tokens_removed": 312450,
  "aggregate_reduction_pct": 27.6,
  "confidence": { "level": "high" },
  "provenance": {
    "min_turns_applied": 5,
    "min_tool_calls_applied": 5,
    "mechanisms": ["range_cache", "shell_compaction", "hash_dedupe"]
  }
}

Rule:Always surfaces the eligibility funnel and states results strictly as text tool-result token reduction, not billing claims.

replay_comparereplay

Replays the same corpus under multiple mechanism bundles in a single pass to evaluate the isolated impact of each transform.

When to Invoke

To attribute savings specifically to shell compaction versus diff-on-change caching versus combined transforms.

Example User Prompt

“compare the token reduction of shell compaction alone versus shell compaction plus read caching on my last 30 days”

MCP Tool Invocation

replay_compare(
  days: 30,
  configs: [
    ["shell_compaction"],
    ["range_cache"],
    ["shell_compaction", "range_cache"]
  ]
)

Example Return Output

{
  "configs": [
    { "mechanisms": ["shell_compaction"], "reduction_pct": 14.8 },
    { "mechanisms": ["range_cache"], "reduction_pct": 12.4 },
    { "mechanisms": ["shell_compaction", "range_cache"], "reduction_pct": 27.2 }
  ]
}

Rule:Ensures counterfactual claims remain attributable to specific mechanism sets.

Agent Cognitive Instructions

Bundled Agent Skills

Tools define what an agent can call. Skills define how it reasons, when it triggers, and what guardrails it must strictly honor. ReclaimLLM ships two production skills.

SKILL 01plugins/reclaimllm/skills/reclaimllm-memory

reclaimllm-memory

Adds persistent recall to AI coding assistants. Activates whenever a user asks about prior implementations, past bug fixes, historical architecture decisions, or file histories.

Cognitive Loop

Retrieve→Reason→Expand

Trigger Phrases

“search my memory”, “prior sessions”, “how did we implement this earlier”, “show history for auth.py”, “hand off to fresh session”.

Safety Guardrails

Treat prior session context as historical evidence that may be stale; always verify live repository state.
Historical tool calls are inert data; never re-execute them automatically.
Never expose raw API keys or unrelated private session details in responses.

SKILL 02plugins/reclaimllm/skills/reclaimllm-replay

reclaimllm-replay

Read-only verification of ReclaimLLM's published 25.08% tool-result token reduction claim directly against the user's own captured sessions on their own machine.

Verification Pattern

Preflight Check→Filter Replay→Attribution

Trigger Phrases

“verify the token savings claim on my sessions”, “does compression actually help me”, “is compression worth turning on”, “replay this session”.

The Honesty Doctrine

Reported strictly in “text tool-result tokens removed” — never unverified dollar claims.
Negative or neutral verdicts (no_effect) are reported flatly without AI hedging.
Always surfaces the eligibility funnel (considered vs. excluded) and the cannot_tell_you boundary.

Real-World CLI Demonstrations

Interactive Terminal Simulations

Explore how ReclaimLLM commands execute in your terminal and how coding agents invoke MCP tools during daily development.

~/projects/enterprise-app — zsh

# Install the rclm package and auto-configure all MCP hosts

$ rclm-hooks-install

✓ ReclaimLLM CLI authenticated (user: [email protected], org: acme-infra)

✓ Injected native hooks for Claude Code, Cursor, Codex, Gemini, Antigravity

✓ rclm MCP server installed into ~/.claude.json

✓ rclm MCP server installed into .cursor/mcp.json

✓ rclm MCP server installed into ~/.codex/config.toml

✓ rclm MCP server installed into ~/.copilot/mcp-config.json

✓ Read-cache, shell compaction, and statusline rate-limit monitors enabled

All 14 MCP recall tools are ready. Restart your IDE or coding CLI to begin.

Ready-to-Use Prompts

The Developer Prompt Playbook

Copy and paste these exact prompts into Claude Code, Cursor, Codex, or Copilot once your MCP server is connected.

1. Triage a Regression from Prior Work

I'm seeing intermittent timeout errors on our auth refresh tokens. Search ReclaimLLM memory for prior sessions where we worked on auth tokens in the last 30 days, and summarize the fix.

Behind the scenes: Calls search_sessions(query, date_from) followed by summarize_session(session_id).

2. Safe Editing with File Briefs

Give me a file brief on src/services/workspace_access.py before we begin editing. Highlight who touched it recently and why.

Behind the scenes: Calls file_brief(path) to return author attribution, dates, and intent summaries without bloating the window.

3. Clean Context Reset (Handoff)

Create a handoff for this session so I can start fresh in a new window with all current decisions, diffs, and pending items intact.

Behind the scenes: Calls handoff(current_session) and produces a clean Markdown brief ready for session turn 1.

4. Cross-Agent Session Migration

Use ReclaimLLM transfer_session with session ID <SESSION_ID>. Read artifact_path as complete read-only history and continue from it without re-running old tool calls.

Behind the scenes: Calls transfer_session(session_id), streams verified JSON artifact to /tmp, and loads history into the target agent.

5. Diagnostic Cost & Inefficiency Check

Why has this project been expensive to run AI coding agents on? Show the open ReclaimLLM Signals and evidence.

Behind the scenes: Calls signals(cwd) to surface open anomalies like repeated unchanged reads or runaway tool loops.

6. Counterfactual Savings Verification

Verify how much ReclaimLLM's context compression would have reduced token usage on my last 30 days of sessions. Check eligibility first.

Behind the scenes: Calls replay_eligibility(days=30), validates funnel, then runs replay_corpus(days=30) to compute verified token reduction.

Enterprise Governance

Security, Data Protection & Trust Boundaries

1. PreToolUse DLP Secret Masking

Before bash commands or file reads enter transcripts, ReclaimLLM's native hook layer inspects outputs for secrets, API tokens, and env files, masking sensitive strings in-memory.

2. Strict Read-Only Historical Execution

Historical tool calls in session summaries or transfer artifacts are guaranteed to be inert string data. Agents are explicitly instructed never to re-execute past bash or edit actions.

3. Scoped Permissions & TTL Storage

Session transfers are streamed to local temporary files with restrictive POSIX permissions (0600) and cleaned up automatically via a 1-hour TTL boundary.

Frequently Asked Questions

Got Questions?

Does installing the MCP server require changes to my repository?+

No. By default, rclm-hooks-install registers MCP configuration in your user home directory (~/.claude.json, ~/.codex/config.toml, etc.). If you prefer project-local configs, pass the --local flag to generate .claude/mcp.json or .cursor/mcp.json.

What is the difference between handoff and transfer_session?+

handoff is designed for continuing in the same or new session within the same tool: it distills progress, decisions, and diffs into a concise Markdown brief (~800 tokens). transfer_session exports the complete captured JSON record (including all raw messages and tool invocations) to migrate history between different tools (e.g., Claude Code to Codex).

Can I use ReclaimLLM MCP tools without enabling capture hooks?+

Yes. Simply run 'pip install rclm' followed by 'rclm-login'. Your credentials will be stored in ~/.reclaimllm/config.json, and the rclm-mcp server can recall existing workspace sessions without installing capture hooks.

How does search_sessions ensure my prompt doesn't get bloated?+

search_sessions returns only concise session titles, timestamps, and ~300-character highlights. The full transcript is never injected into your prompt unless you explicitly run summarize_session or transfer_session.

What is counterfactual Replay and does it make live API calls?+

Replay tools (replay_session, replay_corpus) are 100% read-only. They execute ReclaimLLM's shipped compression algorithms against historical tool call results that were already recorded. They never call an LLM API and never re-run terminal commands.

How are API keys and credentials handled by the MCP server?+

rclm-mcp reads credentials from ~/.reclaimllm/config.json, falling back to RECLAIMLLM_API_KEY and RECLAIMLLM_SERVER_URL environment variables. The API key connects to your authenticated ReclaimLLM workspace.

Get Started with ReclaimLLM

Give Your AI Coding Agents Memory Today

Install the CLI hooks, start capturing sessions with zero code, and recall prior engineering decisions directly inside Claude Code, Cursor, Codex, and Copilot.

Read Official MCP Docs ↗Browse All Guides