{ "markdown": "

\n \"MCP\n

\n\n

\n \"MCP\n

\n\n

MCP Light Memory

\n\n

\n Lightweight local-first persistent memory for coding agents and MCP clients.
\n formerly internal-rag\n

\n\n

\n \"version\"\n \"license\"\n \"python\"\n \"deps\"\n \"mcp\"\n

\n\n---\n\n## What is this?\n\n**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.\n\nWhen 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.\n\n## Why use it?\n\n| Problem | How MCP Light Memory solves it |\n|---|---|\n| Agents forget everything between sessions | Markdown files persist on disk; the agent retrieves them via BM25 + optional embeddings |\n| Full session history is too large for context | Only relevant memories are retrieved (token-budgeted, MMR-diversified) |\n| Cloud dependency / privacy concerns | 100% local, offline, zero network calls, no daemon |\n| Heavy setup / dependencies | Zero required runtime deps (pure Python 3.8+ stdlib); optional `sentence-transformers` for better semantic retrieval |\n| Prompt injection via stored memory | Every retrieved memory is explicitly `trust: untrusted` evidence with an injection-warning heuristic (ADR-015) |\n| Multi-project isolation | Router with registry allowlist, `write:false` hard boundary, per-call subprocess isolation |\n| MCP protocol drift | Dual-era support: modern `2026-07-28` + legacy `2024-11-05`…`2025-11-25` |\n\n## How it works (mechanisms)\n\n- **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.\n- **SQLite is a rebuildable cache.** BM25/FTS5 index + optional embedding vectors + usage tracking. Delete it and everything rebuilds from Markdown.\n- **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.\n- **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.\n- **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\"]`.\n- **Evidence freshness:** each result includes `evidence_state` (`present`/`missing`/`unverifiable`) for local path-like evidence — derived at retrieval time, never persisted.\n- **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).\n\n## Setup\n\n### Prerequisites\n\n- **Python 3.8+** (uses `py` launcher, `python`, or `python3` — the installer auto-detects the real interpreter and rejects the WindowsApps stub)\n- **Git** (the target project must be a git repo)\n- Optional: `pip install sentence-transformers numpy` for better semantic retrieval\n\nThe current version is defined by the [`VERSION`](VERSION) file — check it (or run `mlm.py --version`) instead of hard-coding an expected number.\n\n### Quick start\n\nClone this repo once, then install into any project:\n\n```powershell\n# Windows (PowerShell)\ngit clone https://github.com/PeterPirog/mcp-light-memory.git ~/mcp-light-memory\npython ~/mcp-light-memory/install.py . --client warp\n```\n\n```bash\n# Linux/macOS\ngit clone https://github.com/PeterPirog/mcp-light-memory.git ~/mcp-light-memory\npython3 ~/mcp-light-memory/install.py . --client warp\n```\n\nThe installer:\n- copies skill files + creates `INTERNAL_RAG/` + `AGENTS.md`\n- runs `init` + `checkpoint` + `validate` (so `guard` is `OK` immediately)\n- auto-registers the MCP server in the client config when it can do so safely (or reports `MANUAL_REQUIRED` / prints JetBrains instructions)\n- writes the **absolute path** to the verified Python interpreter (survives Windows PATH issues)\n\n```powershell\npython .agents\\skills\\internal-rag\\mlm.py --version # reports the installed version\npython .agents\\skills\\internal-rag\\mlm.py status # expect: INTERNAL_RAG ready\npython .agents\\skills\\internal-rag\\mlm.py guard # expect: GUARD OK\n```\n\n### Installation matrix\n\nOne installer, four clients, two config scopes. Full guide: [docs/INSTALLATION.md](docs/INSTALLATION.md).\n\n| Client | Project scope | Global scope |\n|---|---|---|\n| **Warp** (config write automatic; project activation may require approval) | `install.py . --client warp` | `install.py . --client warp --global` |\n| **OpenCode stable (V1)** (automatic for safe JSON config writes) | `install.py . --client opencode` | `install.py . --client opencode --global` |\n| **OpenCode 2 (V2, beta)** (automatic for safe JSON config writes) | `install.py . --client opencode2` | `install.py . --client opencode2 --global` |\n| **JetBrains AI / PyCharm** (manual in IDE UI) | `install.py . --client jetbrains` | `install.py . --client jetbrains --global` |\n\n- **`--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.\n- **Need one global MCP endpoint for many repositories?** Use the multi-project router — [docs/MCP-MULTI-PROJECT.md](docs/MCP-MULTI-PROJECT.md).\n- **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.\n- Manual setup (no installer) per client: [docs/INSTALLATION.md](docs/INSTALLATION.md) + client pages ([Warp](docs/WARP-SETUP.md) · [OpenCode](docs/OPENCODE.md)).\n\n### Zero-shot: copy-paste prompts for Warp and OpenCode\n\nYou can paste one of these directly into the client agent. Replace `C:\\Projects\\App` with the real target repository path.\n\n**Warp — install for one project:**\n\n```text\nInstall 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.\n```\n\n**Warp — global client config for one project:**\n\n```text\nInstall 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.\n```\n\n**OpenCode — install for one project (stable/V1):**\n\n```text\nInstall 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.\n```\n\n**OpenCode — global client config for one project (stable/V1):**\n\n```text\nInstall 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.\n```\n\nFor 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](docs/ZERO-SHOT-SETUP-PROMPTS.md).\n\n---\n\n## Configuration details\n\n### Warp\n\nWarp reads MCP server configs from `~/.warp/.mcp.json` (global, auto-spawns) or\n`{repo}/.warp/.mcp.json` (project, requires a manual toggle per [Warp docs](https://docs.warp.dev/agents/capabilities/mcp/)).\nShape: `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](docs/WARP-SETUP.md).\n\n### OpenCode stable (V1)\n\nOpenCode reads `opencode.json`/`.jsonc` in the project root, or\n`~/.config/opencode/opencode.json` globally. V1 servers are **flat** under\n`mcp.` (no `servers` sub-key) with `enabled: true` and `command` as an\narray — see `examples/opencode-legacy.example.json` and [docs/OPENCODE.md](docs/OPENCODE.md).\n\n### OpenCode 2 (V2, beta)\n\nSame config files, different shape: `mcp.servers.`, `command` as an\narray, and **no `enabled` field** (V2 disables via `disabled: true`) — see\n`examples/opencode-v2.example.jsonc` and [docs/OPENCODE.md](docs/OPENCODE.md).\n\n### JetBrains AI Assistant / PyCharm\n\nPyCharm does **NOT** auto-read any MCP config file. The installer prints\nready-to-paste JSON + Working Directory; you add the server in\nSettings → Tools → AI Assistant → MCP (STDIO) and choose **Server level =\nProject or Global**. See `examples/jetbrains.example.json`.\n\n---\n\n## Multi-project router\n\nOne MCP connection in front of many projects — registry allowlist, `write:false` hard boundary, per-call subprocess isolation.\n\n### Registry file (`projects.json`)\n\n```json\n{\n \"projects\": {\n \"backend\": { \"root\": \"/abs/path/backend\", \"write\": true },\n \"shared-lib\": { \"root\": \"/abs/path/shared-lib\", \"write\": false }\n }\n}\n```\n\n### Warp config for the router\n\n```json\n{\n \"mcpServers\": {\n \"mcp-light-memory-router\": {\n \"command\": \"python3\",\n \"args\": [\"/abs/path/mcp-light-memory/.agents/skills/internal-rag/irag_mcp_router.py\", \"--registry\", \"/abs/path/projects.json\"],\n \"working_directory\": \"/abs/path/mcp-light-memory\"\n }\n }\n}\n```\n\nSee [docs/MCP-MULTI-PROJECT.md](docs/MCP-MULTI-PROJECT.md) for details.\n\n---\n\n## Workflow\n\n```text\ncontext --task \"current task\"\n ↓\nrecovery, if required (RECOVERY REQUIRED)\n ↓\ncheckpoint before first change\n ↓\nimplementation\n ↓\ncheckpoint after each milestone\n ↓\nguard before finishing\n```\n\nCore commands (CLI alias: `mlm.py` or legacy `irag.py`):\n\n```text\nmlm.py context --task \"...\"\nmlm.py checkpoint --reason \"...\"\nmlm.py search --query \"...\" --limit 8\nmlm.py remember --type decision --title \"...\" --body \"...\"\nmlm.py show \nmlm.py update --status superseded\nmlm.py status\nmlm.py guard\nmlm.py validate\nmlm.py doctor\n```\n\n## Path mapping (rebrand: internal-rag → MCP Light Memory)\n\n| New name | Legacy path (kept for compatibility) |\n|---|---|\n| `MCP Light Memory` (product) | `internal-rag` (deprecated product name) |\n| `mlm` / `mlm.py` (primary CLI) | `irag.py` (legacy alias, still works) |\n| `mcp-light-memory` (MCP server name) | `internal-rag` (legacy, still works in configs) |\n| `mcp-light-memory-router` (router name) | `internal-rag-router` (legacy) |\n| `INTERNAL_RAG/` (storage folder — unchanged) | — |\n| `.agents/skills/internal-rag/` (skill dir — unchanged) | — |\n\nThe on-disk folder `INTERNAL_RAG/` and the skill directory `.agents/skills/internal-rag/` are intentionally kept under their legacy names for **zero-migration** backward compatibility. See `docs/MIGRATION-TO-MCP-LIGHT-MEMORY.md`.\n\n## Durable memory (CRUD)\n\n```text\nremember --type decision --title \"...\" --body \"...\" --tags \"a,b\" --evidence \"src/x.py:42\" --links \"decisions/other.md\"\nshow \nshow --section Knowledge\nupdate --add-tags \"new\" --append \"New evidence: ...\"\nsupersede --by --reason \"...\"\nforget # archives, does not delete\nlink --from --to \ntimeline --limit 20\nstatus\nhistory\n```\n\nTypes: `decision`, `knowledge`, `constraint`, `gotcha`, `failure`, `hypothesis`, `session`.\n\n## Task stack (interrupts)\n\n```text\nmlm.py push --task \"interrupted work\" --reason \"user-priority\"\nmlm.py tasks\nmlm.py resume\nmlm.py forget-task # drop a specific task\nmlm.py forget-task # clear the whole stack\n```\n\n## Configuration (`.irag.yml`, optional)\n\n```yaml\nretrieval:\n limit: 10\n mmr_lambda: 0.4\n min_score: 0.3\n embeddings: auto # auto | on | off\n profile: english-fast # english-fast (default) | multilingual (PL/EN projects)\n embeddings_model: null # explicit model overrides the profile\ntokens:\n context_budget: 5000\ncheckpoints:\n auto_archive_sessions: true\n max_task_stack: 24\n```\n\n`mlm.py config` shows the effective configuration. `mlm.py config --init` writes a template.\n\n## Optional embeddings (better retrieval)\n\n```bash\npip install -r requirements-optional.txt\n```\n\nWhen the package is available and `.irag.yml` has `embeddings: auto` (default), retrieval uses embeddings with fallback to BM25. Override at runtime with `--embeddings on|off|auto`.\n\nTwo retrieval profiles (see `docs/EMBEDDINGS.md`):\n- `english-fast` (default, `all-MiniLM-L6-v2`)\n- `multilingual` (`intfloat/multilingual-e5-small`) — for Polish-English projects\n\n## Offline / air-gapped\n\n```bash\npython pack.py --with-embeddings --profile english-fast\n# -> internal-rag-offline-1.8.1.zip (name from pack.py; 1.8.1 = VERSION file)\n# On the air-gapped machine:\nunzip internal-rag-offline-*.zip -d internal-rag-offline\npip install --no-index --find-links wheels/ -r requirements-optional.txt\npython install.py \"/path/to/project\" --client \n```\n\nSee `docs/OFFLINE.md` for details.\n\n## Privacy & Git\n\nThe default install mode is **local-only**. The installer uses `.git/info/exclude`, not the project's `.gitignore`, so local memory and integration files are not accidentally committed.\n\nBefore publishing a project:\n\n```powershell\npython .\\privacy_check.py \"D:\\path\\to\\project\"\n```\n\nExpected: `RESULT: PASS`\n\n## Full removal from a project\n\n```powershell\npython .\\uninstall.py \"D:\\path\\to\\project\"\n```\n\nThe uninstaller creates a backup outside the repository, then removes INTERNAL_RAG and its integrations. Use `--keep-memory` to preserve the memory data.\n\n## Documentation\n\n- [Installation](docs/INSTALLATION.md) · [Daily usage](docs/DAILY-USAGE.md) · [CLI reference](docs/CLI.md)\n- [Architecture](docs/ARCHITECTURE.md) · [Memory lifecycle](docs/MEMORY-LIFECYCLE.md) · [Recovery](docs/RECOVERY.md)\n- [MCP](docs/MCP.md) · [Multi-project MCP](docs/MCP-MULTI-PROJECT.md)\n- [Architecture decisions (ADR)](docs/ADR.md) · [Configuration](docs/CONFIG.md)\n- [Embeddings](docs/EMBEDDINGS.md) · [Offline](docs/OFFLINE.md) · [Git hooks](docs/GIT-HOOKS.md)\n- [Privacy & Git](docs/PRIVACY-AND-GIT.md) · [Uninstall](docs/UNINSTALL.md) · [Troubleshooting](docs/TROUBLESHOOTING.md)\n- [Zero-shot setup prompts](docs/ZERO-SHOT-SETUP-PROMPTS.md) · [Migration](docs/MIGRATION-TO-MCP-LIGHT-MEMORY.md) · [Branding](docs/BRANDING.md)\n\n## Structure in a target project\n\n```text\nproject/\n├── AGENTS.md\n├── .irag.yml # optional config\n├── INTERNAL_RAG/\n│ ├── WORKING_STATE.md\n│ ├── INDEX.md\n│ ├── .checkpoint.json\n│ ├── decisions/ knowledge/ gotchas/ failures/ hypotheses/ sessions/ archive/\n│ └── exports/\n├── .agents/skills/internal-rag/\n│ ├── SKILL.md\n│ ├── mlm.py # primary CLI (forwards to irag.py)\n│ ├── irag.py # core (legacy alias, still the canonical module)\n│ ├── irag_embeddings.py # optional plugin\n│ └── irag_hooks.py # optional git hooks\n└── .opencode/ # OpenCode integration (optional)\n```\n\n## Source of truth\n\n1. current user instructions, 2. current code/tests/configuration, 3. specifications/ADRs, 4. verified memory, 5. session notes, 6. hypotheses.\n\nMemory can be stale. Code takes precedence.\n\n## License\n\nMIT.\n\n---\n\n## Changelog\n\n### 1.8.0 — JetBrains manual setup\n\n- `--client jetbrains` no longer writes a fake config file (PyCharm ignores MCP config files). Prints ready-to-paste JSON + IDE menu instructions instead.\n- `--unregister --client jetbrains` prints a reminder to remove in the IDE UI.\n\n### 1.7.2 — JetBrains cwd + client-specific messages\n\n- JetBrains: writes `working_directory` as a hint + prints `WARNING` with exact path to set in `Settings → Tools → AI Assistant → MCP`.\n- Client-specific restart messages (Restart PyCharm / Restart Warp / Restart OpenCode).\n- `Memory store: ` printed in install output for immediate verification.\n\n### 1.7.1 — Windows Python stub fix\n\n- `detect_python()` rejects the WindowsApps 0-byte stub; prefers `py -0p`; verifies each candidate with `--version`.\n- Post-register verification: runs `--version` immediately after writing the config and reports `PASS`/`FAIL`.\n- `--unregister` deletes empty config files + parent dirs (fixes dead `.warp/.mcp.json` skeleton → `GUARD STALE`).\n\n### 1.7.0 — Rebrand to MCP Light Memory\n\n- Total rebrand from `internal-rag` to **MCP Light Memory** (`mcp-light-memory`). New CLI alias `mlm` (`mlm.py`). Logo/icon assets. Migration doc. GitHub rebrand checklist.\n- Backward-compatible: `irag.py`, `INTERNAL_RAG/`, old MCP server names preserved as deprecated aliases.\n- 18 rebrand consistency tests.\n\n### 1.6.1 — Post-v1.6 hardening\n\n- Mutation/lifecycle benchmark (11 scenarios). Trust boundary (ADR-015): `trust: untrusted` + `security_flags`. Evidence freshness (ADR-016): `evidence_state`. Scale benchmark (100/1k/10k). Router security regressions (+12 tests). Docs consistency test. 249 tests pass.\n\n### 1.6.0 — Retrieval quality + MCP 2026-07-28\n\n- Memory-quality benchmark (37 cases). MCP `2026-07-28` dual-era (`server/discover`, `_meta`, `structuredContent`, `outputSchema`). Registry strict `write`. Sources in chunk prefix. Adaptive retrieval. Link-aware context. `consolidate --prepare`. Router latency benchmark. ADR-010…016.\n\n### 1.5.0 — Abstention gate + multi-project router\n\n- Relevance/abstention gate (`--meta`). FTS5 candidate prefilter. Multi-project MCP router. MCP protocol hardening (pure stdout, SDK-verified). 168 tests.\n\n### 1.4.0 — Chunking + dedup + temporal lifecycle\n\n- Section-aware chunking (schema v3). SimHash dedup. Multilingual PL/EN profile. Temporal lifecycle (`valid_from`/`valid_to`/`supersedes`/`--at`). `consolidate --dry-run`.\n\n### 1.3.0 — Persistent embedding cache\n\n- Chunk-level float32 BLOBs in SQLite. Multiple models coexist. `index --vacuum`/`--embed-missing`.\n\n### 1.0.2 — Token budget + privacy\n\n- Token budget enforcement. Stale memory detection. Duplicate detection. Privacy scan at write-time. Auto-checkpoint timer. Offline/air-gapped pack.\n\n### 1.0.0 — Initial release\n\n- BM25 + MMR retrieval. Full memory CRUD. Task stack. MCP server (JSON-RPC stdio). Git hooks. Diagnostics. Export/import. Token budget.", "bytes": 22248, "sha": "acfc781f11adf240096b1dc8c5beec8deeddfd5adf5f727f26ba9083ccee7576", "repo_slug": "peterpirog/mcp-light-memory", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_peterpirog_mcp_light_memory_63aae26d/readme" }