MCP Light Memory

MCP Light Memory

面向编码 Agent 和 MCP 客户端的轻量级、本地优先持久记忆。
原名 internal-rag

---

这是什么？

MCP Light Memory 是一套轻量级、本地优先的持久记忆系统，面向编码 Agent 和 MCP 客户端（Warp、OpenCode、JetBrains AI Assistant / PyCharm、Claude Code、Cursor）。它充当检查点 + 检索层：只存储跨会话恢复复杂工作所需的最少持久状态，无需将完整对话保留在模型的上下文窗口中。

Agent 开始任务时，会调用 context 并获取相关的过往决策、注意事项、约束和假设，这些内容经过排序、去重并设定信任边界。任务结束时，它会为当前工作状态创建检查点。下一次会话中，即使重启后，记忆也依然存在。

为什么使用它？

问题	MCP Light Memory 的解决方式
Agent 会忘记不同会话之间的所有内容	Markdown 文件会持久保存在磁盘上；Agent 通过 BM25 + 可选嵌入检索这些文件
完整会话历史超出上下文容量	仅检索相关记忆（按令牌预算控制，并通过 MMR 实现多样化）
云端依赖 / 隐私顾虑	100% 本地运行、离线、零网络调用、无需守护进程
设置繁琐 / 依赖项过多	运行时无必需依赖（纯 Python 3.8+ 标准库）；可选安装 sentence-transformers，以获得更好的语义检索效果
存储的记忆中可能包含提示词注入	每条检索到的记忆都明确标记为 trust: untrusted 证据，并采用注入警告启发式检测（ADR-015）
多项目隔离	路由器采用注册表允许列表、write:false 硬性边界，并对每次调用进行子进程隔离
MCP 协议版本差异	支持两个时期的协议：现代版 2026-07-28 + 旧版 2024-11-05…2025-11-25

工作原理（机制）

• Markdown 是事实来源。 每条记忆都是一个包含 YAML frontmatter（id、type、status、tags、sources、links、valid_from、valid_to、supersedes）的 .md 文件。可供人阅读、便于比较差异且持久耐用。
• SQLite 是可重建的缓存。 包含 BM25/FTS5 索引、可选嵌入向量和使用情况跟踪。删除它后，所有内容都会从 Markdown 重新构建。
• 检索： 纯 Python BM25 + 可选稠密嵌入 → RRF 融合 → MMR 多样化 → 策略加权（类型 / 状态 / 时间）→ 按令牌预算截断。自适应模式：先进行稀疏检索，仅在效果不佳时才进行稠密检索。
• 生命周期： remember → update → supersede（双向建立链接，绝不删除历史记录）→ forget（归档，绝不删除）→ timeline（时间视图）。历史查询可使用 search --at YYYY-MM-DD。
• 信任边界： 检索到的内容会用 === BEGIN/END INTERNAL_RAG MEMORY === 包裹，并带有 SECURITY NOTICE 标题。结构化 JSON/MCP 数据会包含 trust: untrusted，以及可选的 security_flags: ["instruction_like_content"]。
• 证据时效性： 每条结果都包含 evidence_state（present/missing/unverifiable），用于标记类似本地路径的证据；该状态在检索时推导，绝不持久化。
• 多项目路由器： 一个 MCP stdio 服务可通过 JSON 注册表连接多个项目。启动子进程前，write:false 会阻止可变更数据的工具。每次调用都使用独立子进程隔离（不共享状态）。

设置

前置条件

• Python 3.8+（使用 py 启动器、python 或 python3——安装程序会自动检测实际解释器，并拒绝使用 WindowsApps 占位程序）
• Git（目标项目必须是 git 仓库）
• 可选：pip install sentence-transformers numpy，以获得更好的语义检索效果

当前版本由 VERSION 文件定义——请检查该文件（或运行 mlm.py --version），不要将预期版本号硬编码。

快速开始

克隆此仓库一次，然后安装到任意项目中：

# 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

安装程序会：

• 复制技能文件 + 创建 INTERNAL_RAG/ + AGENTS.md
• 运行 init + checkpoint + validate（因此 guard 会立即显示 OK）
• 在安全可行时自动将 MCP 服务注册到客户端配置中（否则会报告 MANUAL_REQUIRED / 打印 JetBrains 操作说明）
• 写入已验证 Python 解释器的绝对路径（避免 Windows PATH 问题）

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

安装矩阵

一个安装程序，四种客户端，两种配置范围。完整指南：docs/INSTALLATION.md。

客户端	项目范围	全局范围
Warp（自动写入配置；项目激活可能需要批准）	install.py . --client warp	install.py . --client warp --global
OpenCode stable (V1)（安全写入 JSON 配置时自动完成）	install.py . --client opencode	install.py . --client opencode --global
OpenCode 2 (V2, beta)（安全写入 JSON 配置时自动完成）	install.py . --client opencode2	install.py . --client opencode2 --global
JetBrains AI / PyCharm（在 IDE 界面中手动操作）	install.py . --client jetbrains	install.py . --client jetbrains --global

• --global 会改变客户端配置的范围（~/.warp/.mcp.json 与 {repo}/.warp/.mcp.json，~/.config/opencode/opencode.json 与项目 opencode.json）。服务仍指向你安装到的目标项目。
• 需要为多个仓库使用一个全局 MCP 端点？ 使用多项目路由器——docs/MCP-MULTI-PROJECT.md。
• JetBrains/PyCharm 只能辅助配置，不能完全自动完成：安装程序会准备 JSON + 工作目录；你需要前往 Settings → Tools → AI Assistant → MCP 添加服务，并将 Server level 设为 Project 或 Global。
• 各客户端的手动设置方法（不使用安装程序）：docs/INSTALLATION.md + 客户端页面（Warp · OpenCode）。

零样本：适用于 Warp 和 OpenCode 的复制粘贴提示词

你可以将以下任一内容直接粘贴到客户端 Agent 中。将 C:\Projects\App 替换为目标仓库的实际路径。

Warp——为单个项目安装：

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——为单个项目配置全局客户端：

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——为单个项目安装（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——为单个项目配置全局客户端（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.

对于 OpenCode 2 / V2，使用相同的提示词，但需明确说明 OpenCode 2 / V2，并要求使用 --client opencode2。更多变体：docs/ZERO-SHOT-SETUP-PROMPTS.md。

---

配置详情

Warp

Warp 从 ~/.warp/.mcp.json（全局，自动启动）或 {repo}/.warp/.mcp.json（项目，需要根据 Warp 文档手动切换）读取 MCP 服务配置。 格式：mcpServers.<name>，包含 command、args、working_directory（务必设置——记忆存储会从此路径解析）。参见 examples/warp.example.json 和 docs/WARP-SETUP.md。

OpenCode stable (V1)

OpenCode 会读取项目根目录中的 opencode.json/.jsonc，或全局配置文件 ~/.config/opencode/opencode.json。V1 服务以扁平结构位于 mcp.<name> 下（没有 servers 子键），并使用 enabled: true，且 command 为数组——参见 examples/opencode-legacy.example.json 和 docs/OPENCODE.md。

OpenCode 2（V2，测试版）

配置文件相同，结构不同：mcp.servers.<name>、command 使用数组，且没有 enabled 字段（V2 通过 disabled: true 禁用）——参见 examples/opencode-v2.example.jsonc 和 docs/OPENCODE.md。

JetBrains AI Assistant / PyCharm

PyCharm 不会自动读取任何 MCP 配置文件。安装程序会输出可直接粘贴的 JSON 和工作目录；你需要在 Settings → Tools → AI Assistant → MCP (STDIO) 中添加服务，并选择 Server level = Project or Global。参见 examples/jetbrains.example.json。

---

多项目路由器

在多个项目前接入一个 MCP 连接——注册表允许列表、write:false 硬性边界，以及逐次调用的子进程隔离。

注册表文件（projects.json）

{
  "projects": {
    "backend": { "root": "/abs/path/backend", "write": true },
    "shared-lib": { "root": "/abs/path/shared-lib", "write": false }
  }
}

路由器的 Warp 配置

{
  "mcpServers": {
    "mcp-light-memory-router": {
      "command": "python3",
      "args": ["/abs/path/mcp-light-memory/.agents/skills/internal-rag/irag_mcp_router.py", "--registry", "/abs/path/projects.json"],
      "working_directory": "/abs/path/mcp-light-memory"
    }
  }
}

详情请参见 docs/MCP-MULTI-PROJECT.md。

---

工作流

context --task "current task"
  ↓
recovery, if required (RECOVERY REQUIRED)
  ↓
checkpoint before first change
  ↓
implementation
  ↓
checkpoint after each milestone
  ↓
guard before finishing

核心命令（CLI 别名：mlm.py 或旧版 irag.py）：

mlm.py context --task "..."
mlm.py checkpoint --reason "..."
mlm.py search --query "..." --limit 8
mlm.py remember --type decision --title "..." --body "..."
mlm.py show <ref>
mlm.py update <ref> --status superseded
mlm.py status
mlm.py guard
mlm.py validate
mlm.py doctor

路径映射（品牌更名：internal-rag → MCP Light Memory）

新名称	旧路径（为兼容性保留）
MCP Light Memory（产品）	internal-rag（已弃用的产品名称）
mlm / mlm.py（主 CLI）	irag.py（旧版别名，仍可使用）
mcp-light-memory（MCP 服务名称）	internal-rag（旧名称，在配置中仍可使用）
mcp-light-memory-router（路由器名称）	internal-rag-router（旧名称）
INTERNAL_RAG/（存储文件夹——保持不变）	—
.agents/skills/internal-rag/（技能目录——保持不变）	—

磁盘上的文件夹 INTERNAL_RAG/ 和技能目录 .agents/skills/internal-rag/ 会有意保留旧名称，以实现零迁移向后兼容。参见 docs/MIGRATION-TO-MCP-LIGHT-MEMORY.md。

持久记忆（CRUD）

remember --type decision --title "..." --body "..." --tags "a,b" --evidence "src/x.py:42" --links "decisions/other.md"
show <path-or-id>
show <ref> --section Knowledge
update <ref> --add-tags "new" --append "New evidence: ..."
supersede <ref> --by <new> --reason "..."
forget <ref>              # archives, does not delete
link --from <ref> --to <ref>
timeline --limit 20
status
history

类型：decision、knowledge、constraint、gotcha、failure、hypothesis、session。

任务栈（中断）

mlm.py push --task "interrupted work" --reason "user-priority"
mlm.py tasks
mlm.py resume
mlm.py forget-task <id>   # drop a specific task
mlm.py forget-task         # clear the whole stack

配置（.irag.yml，可选）

retrieval:
  limit: 10
  mmr_lambda: 0.4
  min_score: 0.3
  embeddings: auto        # auto | on | off
  profile: english-fast   # english-fast (default) | multilingual (PL/EN projects)
  embeddings_model: null  # explicit model overrides the profile
tokens:
  context_budget: 5000
checkpoints:
  auto_archive_sessions: true
  max_task_stack: 24

mlm.py config 会显示生效的配置。mlm.py config --init 会写入一个模板。

可选嵌入（提升检索效果）

pip install -r requirements-optional.txt

当软件包可用且 .irag.yml 中设置了 embeddings: auto（默认值）时，检索会使用嵌入，并在必要时回退到 BM25。可在运行时通过 --embeddings on|off|auto 覆盖。

两种检索配置（参见 docs/EMBEDDINGS.md）：

• english-fast（默认，all-MiniLM-L6-v2）
• multilingual（intfloat/multilingual-e5-small）——适用于波兰语和英语项目

离线 / 隔离网络

python pack.py --with-embeddings --profile english-fast
# -> internal-rag-offline-1.8.1.zip   (name from pack.py; 1.8.1 = VERSION file)
# On the air-gapped machine:
unzip internal-rag-offline-*.zip -d internal-rag-offline
pip install --no-index --find-links wheels/ -r requirements-optional.txt
python install.py "/path/to/project" --client <warp|opencode|opencode2|jetbrains>

详情请参见 docs/OFFLINE.md。

隐私与 Git

默认安装模式为仅本地。安装程序使用 .git/info/exclude，而非项目的 .gitignore，以避免意外提交本地记忆和集成文件。

发布项目之前：

python .\privacy_check.py "D:\path\to\project"

预期结果：RESULT: PASS

从项目中彻底移除

python .\uninstall.py "D:\path\to\project"

卸载程序会在仓库外创建备份，然后移除 INTERNAL_RAG 及其集成。使用 --keep-memory 可保留记忆数据。

文档

• 安装 · 日常使用 · CLI 参考
• 架构 · 记忆生命周期 · 恢复
• MCP · 多项目 MCP
• 架构决策（ADR） · 配置
• 嵌入 · 离线 · Git 钩子
• 隐私与 Git · 卸载 · 故障排除
• 零样本设置提示词 · 迁移 · 品牌

目标项目中的结构

project/
├── AGENTS.md
├── .irag.yml                    # optional config
├── INTERNAL_RAG/
│   ├── WORKING_STATE.md
│   ├── INDEX.md
│   ├── .checkpoint.json
│   ├── decisions/  knowledge/  gotchas/  failures/  hypotheses/  sessions/  archive/
│   └── exports/
├── .agents/skills/internal-rag/
│   ├── SKILL.md
│   ├── mlm.py                   # primary CLI (forwards to irag.py)
│   ├── irag.py                  # core (legacy alias, still the canonical module)
│   ├── irag_embeddings.py       # optional plugin
│   └── irag_hooks.py            # optional git hooks
└── .opencode/                   # OpenCode integration (optional)

信息来源优先级

1. 当前用户指令，2. 当前代码／测试／配置，3. 规范／ADR，4. 已验证的记忆，5. 会话笔记，6. 假设。

记忆可能过时。代码优先。

许可证

MIT。

---

更新日志

1.8.0 — JetBrains 手动设置

• --client jetbrains 不再写入虚假的配置文件（PyCharm 会忽略 MCP 配置文件）。改为打印可直接粘贴的 JSON 和 IDE 菜单说明。
• --unregister --client jetbrains 会提示在 IDE 界面中移除。

1.7.2 — JetBrains 工作目录与客户端专属消息

• JetBrains：将 working_directory 写为提示，并打印 WARNING，其中包含要在 Settings → Tools → AI Assistant → MCP 中设置的确切路径。
• 提供客户端专属的重启消息（Restart PyCharm / Restart Warp / Restart OpenCode）。
• 安装输出中会打印 Memory store: <path>，便于立即验证。

1.7.1 — Windows Python 存根修复

• detect_python() 会拒绝 WindowsApps 中的 0 字节存根；优先使用 py -0p；并通过 --version 验证每个候选项。
• 注册后验证：写入配置后立即运行 --version，并报告 PASS／FAIL。
• --unregister 会删除空配置文件及其父目录（修复无效的 .warp/.mcp.json 空架构 → GUARD STALE）。

1.7.0 — 更名为 MCP Light Memory

• 从 internal-rag 全面更名为 MCP Light Memory（mcp-light-memory）。新增 CLI 别名 mlm（mlm.py）。新增 Logo／图标资源、迁移文档和 GitHub 更名检查清单。
• 向后兼容：保留 irag.py、INTERNAL_RAG/ 以及旧 MCP 服务名称，作为弃用别名。
• 新增 18 项更名一致性测试。

1.6.1 — v1.6 后强化

• 变更／生命周期基准测试（11 个场景）。信任边界（ADR-015）：trust: untrusted + security_flags。证据时效性（ADR-016）：evidence_state。规模基准测试（100/1k/10k）。路由器安全回归测试（+12 项）。文档一致性测试。249 项测试通过。

1.6.0 — 检索质量 + MCP 2026-07-28

• 记忆质量基准测试（37 个用例）。MCP 2026-07-28 双时代（server/discover、_meta、structuredContent、outputSchema）。注册表严格执行 write。来源写入分块前缀。自适应检索。感知链接的上下文。consolidate --prepare。路由器延迟基准测试。ADR-010…016。

1.5.0 — 弃答门控 + 多项目路由器

• 相关性／弃答门控（--meta）。FTS5 候选项预筛选。多项目 MCP 路由器。MCP 协议强化（纯 stdout，已通过 SDK 验证）。168 项测试。

1.4.0 — 分块 + 去重 + 时间生命周期

• 感知章节的分块（schema v3）。SimHash 去重。多语言 PL/EN 配置。时间生命周期（valid_from／valid_to／supersedes／--at）。consolidate --dry-run。

1.3.0 — 持久化嵌入缓存

• SQLite 中按分块存储的 float32 BLOB。多个模型可共存。index --vacuum／--embed-missing。

1.0.2 — Token 预算 + 隐私

• 强制执行 Token 预算。过时记忆检测。重复项检测。写入时隐私扫描。自动检查点计时器。离线／隔离网络环境软件包。

1.0.0 — 初始版本

• BM25 + MMR 检索。完整记忆 CRUD。任务栈。MCP 服务（JSON-RPC stdio）。Git Hooks。诊断。导出／导入。Token 预算。