MCP Light Memory

MCP Light Memory

Lightweight local-first persistent memory for coding agents and MCP clients.

formerly internal-rag

---

What is this?

MCP Light Memory is a lightweight, local-first, persistent memory system for coding agents and MCP clients (Warp, OpenCode, JetBrains AI Assistant / PyCharm, Claude Code, Cursor). It acts as a checkpoint + retrieval layer — it stores the minimum durable state needed to resume complex work across sessions, without keeping the full conversation in the model's context window.

When your agent starts a task, it calls context and gets back relevant past decisions, gotchas, constraints, and hypotheses — ranked, deduplicated, and trust-bounded. When it finishes, it checkpoints the working state. Next session, even after a restart, the memory is there.

Why use it?

How it works (mechanisms)

• Markdown is the source of truth. Every memory is a .md file with YAML frontmatter (id, type, status, tags, sources, links, valid_from, valid_to, supersedes). Human-readable, diffable, durable.
• SQLite is a rebuildable cache. BM25/FTS5 index + optional embedding vectors + usage tracking. Delete it and everything rebuilds from Markdown.
• Retrieval: pure-Python BM25 + optional dense embeddings → RRF fusion → MMR diversification → policy boosts (type/status/temporal) → token-budget cut. Adaptive mode: sparse first, dense only if weak.
• Lifecycle: remember → update → supersede (links both directions, never deletes history) → forget (archives, never deletes) → timeline (temporal view). search --at YYYY-MM-DD for historical queries.
• Trust boundary: retrieved content is wrapped in === BEGIN/END INTERNAL_RAG MEMORY === with a SECURITY NOTICE header. Structured JSON/MCP carries trust: untrusted + optional security_flags: ["instruction_like_content"].
• Evidence freshness: each result includes evidence_state (present/missing/unverifiable) for local path-like evidence — derived at retrieval time, never persisted.
• Multi-project router: one MCP stdio server in front of many projects via a JSON registry. write:false blocks mutating tools before spawning a child. Per-call subprocess isolation (no shared state).

Setup

Prerequisites

• Python 3.8+ (uses py launcher, python, or python3 — the installer auto-detects the real interpreter and rejects the WindowsApps stub)
• Git (the target project must be a git repo)
• Optional: pip install sentence-transformers numpy for better semantic retrieval

The current version is defined by the VERSION file — check it (or run mlm.py --version) instead of hard-coding an expected number.

Quick start

Clone this repo once, then install into any project:

# Windows (PowerShell)

git clone https://github.com/PeterPirog/mcp-light-memory.git ~/mcp-light-memory python ~/mcp-light-memory/install.py . --client warp

# Linux/macOS

git clone https://github.com/PeterPirog/mcp-light-memory.git ~/mcp-light-memory python3 ~/mcp-light-memory/install.py . --client warp

The installer:

• copies skill files + creates INTERNAL_RAG/ + AGENTS.md
• runs init + checkpoint + validate (so guard is OK immediately)
• auto-registers the MCP server in the client config when it can do so safely (or reports MANUAL_REQUIRED / prints JetBrains instructions)
• writes the absolute path to the verified Python interpreter (survives Windows PATH issues)

python .agents\skills\internal-rag\mlm.py --version   # reports the installed version

python .agents\skills\internal-rag\mlm.py status # expect: INTERNAL_RAG ready python .agents\skills\internal-rag\mlm.py guard # expect: GUARD OK

Installation matrix

One installer, four clients, two config scopes. Full guide: docs/INSTALLATION.md.

• `--global` changes the scope of the CLIENT CONFIG (~/.warp/.mcp.json vs {repo}/.warp/.mcp.json, ~/.config/opencode/opencode.json vs project opencode.json). The server still points at the target project you installed into.
• Need one global MCP endpoint for many repositories? Use the multi-project router — docs/MCP-MULTI-PROJECT.md.
• JetBrains/PyCharm is assisted, not fully automatic: the installer prepares the JSON + Working Directory; you add the server in Settings → Tools → AI Assistant → MCP and choose Server level = Project or Global.
• Manual setup (no installer) per client: docs/INSTALLATION.md + client pages (Warp · OpenCode).

Zero-shot: copy-paste prompts for Warp and OpenCode

You can paste one of these directly into the client agent. Replace C:\Projects\App with the real target repository path.

Warp — install for one project:

Install and configure MCP Light Memory (mcp-light-memory) as an MCP server for project C:\Projects\App in Warp, using project scope. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, update it with git pull --ff-only. Apply the canonical installation contract from the repository and run install.py with TARGET_PROJECT=C:\Projects\App and --client warp without --global. Do not force-overwrite an existing configuration. After installation, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the Warp configuration contains mcp-light-memory and the C:\Projects\App path. Report success only after MCP REGISTRATION: REGISTERED and successful verification. If Warp requires an additional project activation/toggle/approval, state the exact client-side step and do not claim the server is active before it is completed.

Warp — global client config for one project:

Install and configure MCP Light Memory (mcp-light-memory) in Warp globally for project C:\Projects\App. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, run git pull --ff-only. Apply the canonical installation contract and run install.py with TARGET_PROJECT=C:\Projects\App, --client warp, and --global. Remember: --global means the global Warp client configuration, while the server must still be bound to C:\Projects\App; do not use the multi-project router. After installation, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the global Warp configuration contains mcp-light-memory and the C:\Projects\App path. Report success only after MCP REGISTRATION: REGISTERED and successful verification.

OpenCode — install for one project (stable/V1):

Install and configure MCP Light Memory (mcp-light-memory) as an MCP server for project C:\Projects\App in OpenCode. By "OpenCode" I mean stable/V1, so use --client opencode, not opencode2. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, run git pull --ff-only. Run install.py with TARGET_PROJECT=C:\Projects\App and --client opencode without --global. Do not force-overwrite an existing configuration. If the installer returns MCP REGISTRATION: MANUAL_REQUIRED (for example because opencode.jsonc exists), do not report success: safely edit the JSONC while preserving comments and unrelated settings if you have appropriate file-editing tools; otherwise report the exact manual action required. After real registration, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the OpenCode configuration contains mcp-light-memory and C:\Projects\App.

OpenCode — global client config for one project (stable/V1):

Install and configure MCP Light Memory (mcp-light-memory) globally in OpenCode for project C:\Projects\App. By "OpenCode" I mean stable/V1, so use --client opencode. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, run git pull --ff-only. Run install.py with TARGET_PROJECT=C:\Projects\App, --client opencode, and --global. --global means the global OpenCode client configuration, while the server must still be bound only to C:\Projects\App; do not use the multi-project router. If the installer returns MCP REGISTRATION: MANUAL_REQUIRED, do not report success and follow the safe JSONC instructions. After real registration, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the global OpenCode configuration contains mcp-light-memory and the C:\Projects\App path.

For OpenCode 2 / V2, use the same prompts but explicitly say OpenCode 2 / V2 and require --client opencode2. More variants: docs/ZERO-SHOT-SETUP-PROMPTS.md.

---

Configuration details

Warp

Warp reads MCP server configs from ~/.warp/.mcp.json (global, auto-spawns) or {repo}/.warp/.mcp.json (project, requires a manual toggle per Warp docs). Shape: mcpServers. with command, args, working_directory (always set it — the memory store is resolved from it). See examples/warp.example.json and docs/WARP-SETUP.md.

OpenCode stable (V1)

OpenCode reads opencode.json/.jsonc in the project root, or `~/.config/opencode/opencode