Rlm Infinite Memory For Claude Code

RLM - Claude Code 的无限记忆

Claude Code 会话在执行 /compact 后就会忘记一切。RLM 可以解决这个问题。

Français | English | 日本語

---

问题

Claude Code 有上下文窗口限制。窗口满时：

• /compact 会清除对话历史记录
• 之前的决定、见解和上下文都会丢失
• 你不得不重复说明。Claude 会犯同样的错误，效率也会下降。

解决方案

RLM 是一款 MCP 服务，可让 Claude Code 在不同会话间拥有持久记忆：

You: "Remember that the client prefers 500ml bottles"
     → Saved. Forever. Across all sessions.

You: "What did we decide about the API architecture?"
     → Claude searches its memory and finds the answer.

只需 3 行即可安装。提供 14 个工具。无需配置。

---

快速安装

要求：Python 3.10+（下载）、Claude Code CLI

通过 PyPI 安装（推荐）

pip install mcp-rlm-server[all]

钩子和模板随软件包一同发布。由于 pip 安装不会提供代码仓库检出版本，因此需要询问软件包文件的安装位置：

python -m mcp_server --hooks-dir       # e.g. .../site-packages/mcp_server/hooks
python -m mcp_server --templates-dir

将 ~/.claude/settings.json 中的钩子命令指向该路径（参见钩子配置），或将它们复制到 ~/.claude/rlm/hooks/。

通过 uv 安装（速度快，不污染全局环境）

uv tool install mcp-rlm-server[all] --python 3.12

通过 Git 安装（完整安装，包含钩子）

git clone https://github.com/EncrEor/rlm-claude.git
cd rlm-claude
./install.sh

通过 Docker 安装

docker build -t rlm-server .
# Or pull from registry (when published):
# docker pull ghcr.io/encreor/rlm-claude

然后配置 Claude Code 使用 Docker 容器（参见下文的 Docker 设置）。

重启 Claude Code。完成。

从 v0.9.0 或更早版本升级

v0.9.1 将源代码从 mcp_server/ 移至 src/mcp_server/（PyPA 最佳实践）。软件包中包含兼容性符号链接，因此现有安装仍可正常工作，但我们建议重新运行安装程序：

cd rlm-claude
git pull
./install.sh          # reconfigures the MCP server path

你的数据（~/.claude/rlm/）不会受到影响。只会更新服务路径。

---

工作原理

                    ┌─────────────────────────┐
                    │     Claude Code CLI      │
                    └────────────┬────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │    RLM MCP Server        │
                    │    (14 tools)            │
                    └────────────┬────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              │                  │                   │
    ┌─────────▼────────┐ ┌──────▼──────┐ ┌──────────▼─────────┐
    │    Insights       │ │   Chunks    │ │    Retention        │
    │ (key decisions,   │ │ (full conv  │ │ (auto-archive,      │
    │  facts, prefs)    │ │  history)   │ │  restore, purge)    │
    └──────────────────┘ └─────────────┘ └────────────────────┘

不会悄无声息地丢失内容

分块是一项主动操作：RLM 绝不会自行写入分块。它会确保未保存的会话不会被忽略：

• 执行 /compact 前：如果过去 15 分钟内没有生成分块，手动执行 /compact 会被阻止。生成分块后重新执行即可通过。自动压缩永远不会被阻止（否则完整会话将无处可去），但会发出警告。
• 会话结束后：一个钩子会追踪每个会话操作过的内容（文件路径和允许列表中的程序名称，绝不记录命令行）。下次启动时，如果某个会话更改了内容并结束，却没有生成分块，该会话及其记录文本会列出，因此仍可恢复。崩溃和关闭终端的情况也能覆盖：检测的是缺失的分块，而非是否正常退出。

两套记忆系统

系统	存储内容	使用方法
见解	关键决定、事实、偏好	rlm_remember() / rlm_recall()
分块	完整的对话片段	rlm_chunk() / rlm_peek() / rlm_grep()

---

功能

记忆与洞察

• rlm_remember - 按类别和重要性级别保存决策、事实和偏好
• rlm_recall - 按关键词（多词会分词）、类别或重要性搜索洞察
  • 不指定查询时，结果优先按重要性排序，其次按时间新近程度排序 — 一条已确定的 critical 规则优先于今天的 medium 记录
  • 结果被截断时会明确说明：回复会报告匹配数量，因此即使召回结果被限制，也不会让人误以为结果完整
• rlm_forget - 移除一条洞察
• rlm_status - 系统概览（洞察数量、分块统计、访问指标）

对话历史

• rlm_chunk - 保存带有类型分类的对话片段（snapshot、session、debug；insight 会重定向到 rlm_remember）
• rlm_peek - 读取一个分块（完整内容或按行范围读取部分内容）
• rlm_grep - 使用正则表达式搜索所有分块（+ 模糊匹配，以容忍拼写错误）
• rlm_search - 混合搜索：BM25 + 语义余弦相似度（FR/EN、重音符号归一化，搜索分块 + 洞察）
• rlm_list_chunks - 列出所有分块及其元数据

多项目组织

• rlm_sessions - 按项目或领域浏览会话
• rlm_domains - 列出可用于分类的领域
• 自动从 git 或工作目录检测项目
• 所有搜索工具均支持跨项目筛选

智能保留

• rlm_retention_preview - 预览将被归档的内容（试运行）
• rlm_retention_run - 归档长期未使用的分块，清除年代久远的分块
• rlm_restore - 恢复已归档的分块
• 3 区生命周期：活跃 → 归档（.gz）→ 清除
• 免疫机制：关键标签、频繁访问和关键词可保护分块
• 归档是降级，而非删除：已归档的分块会从活跃索引中移出，但 rlm_search 仍会按摘要和标签匹配它们，并将其列在 archived_matches 下 — rlm_peek(chunk_id) 可完整恢复分块
• 每次检索都会计为一次访问（peek、grep 和 search 都一样），因此搜索经常找到的分块会获得免疫，而不会因闲置被归档

安全保障与记忆路由（钩子）

• PreCompact 钩子：如果最近 15 分钟内没有分块，会阻止手动执行 /compact；自动 compact 时会发出警告（绝不阻止）。它本身不会创建分块
• PostToolUse 钩子（rlm_chunk）：记录最近一次创建分块的时间（供 PreCompact 钩子读取），并将分块关联到其会话（在索引中记录 session_id 和 transcript_path）
• PostToolUse 钩子（Edit/Write/Bash） — 会话追踪：将会话编辑的路径，以及运行的允许列表中程序的基本名称，追加到 ~/.claude/rlm/sessions/<session_id>.jsonl。绝不记录命令行：其中可能包含密码
• SessionStart 钩子 — 未保存的会话：列出曾更改内容、结束时既没有分块也没有确认的过往会话，并提供其 transcript 路径。使用 python3 ~/.claude/rlm/hooks/session_orphans.py --ack <session_id> "reason" 确认
• PostToolUse 钩子（Write/Edit）：检测对 Claude Code 自动记忆的写入，并提示改用 RLM 保存决策、洞察和会话日志
• 用户主导理念：由你决定何时创建分块，系统会在内容丢失前保存

语义搜索（可选）

• 混合 BM25 + 余弦相似度 - 结合关键词匹配与向量相似度，提升相关性
• 自动嵌入 - 新分块会在创建时自动生成嵌入
• 两种提供方 - Model2Vec（快速，256d）或 FastEmbed（准确，384d）
• 平滑降级 - 未安装语义搜索依赖时，会回退到纯 BM25

提供方对比（基于 108 个分块的基准测试）

	Model2Vec（默认）	FastEmbed
模型	potion-multilingual-128M	paraphrase-multilingual-MiniLM-L12-v2
维度	256	384
嵌入 108 个分块	0.06s	1.30s
搜索延迟	0.1ms/查询	1.5ms/查询
内存	0.1 MB	0.3 MB
磁盘（模型）	~35 MB	~230 MB
语义质量	良好（偏重关键词）	更好（真正的语义理解）
速度	快 21 倍	基准

两个提供方的前 5 条结果重合数：约 1.6/5（8 次查询中有 7 次结果不同）。FastEmbed 能捕捉更多语义含义，而 Model2Vec 更倾向于关键词相似度。混合 BM25 + 余弦融合可弥补两者的不足。

建议：先使用 Model2Vec（默认）。只有在需要更高语义准确度且能接受较慢启动速度时，才切换到 FastEmbed。

# Model2Vec (default) — fast, ~35 MB
pip install mcp-rlm-server[semantic]

# FastEmbed — more accurate, ~230 MB, slower
pip install mcp-rlm-server[semantic-fastembed]
export RLM_EMBEDDING_PROVIDER=fastembed

# Compare both providers on your data
python3 scripts/benchmark_providers.py

# Backfill existing chunks (run once after install)
python3 scripts/backfill_embeddings.py

检查嵌入覆盖率

嵌入采用尽力而为的方式：即使提供方不可用，分块也始终会写入。此时，该分块在获得向量之前无法通过语义搜索找到，因此系统会报告缺失，而不是任其被忽略，直到之后才被发现。

只要覆盖率不完整，rlm_status 就会发出警告；提供方加载失败时，它会说明原因，并显示 rlm.log 中最近的条目（该日志位于你的上下文目录中，仅追加写入）。要修复缺失：

# Dry-run first: lists chunks that would be embedded
python3 scripts/reconcile_stores.py

# Re-embed everything missing, with timestamped backups
python3 scripts/reconcile_stores.py --apply

两者都会遵循 RLM_CONTEXT_DIR。请使用与你的服务相同的 RLM_EMBEDDING_PROVIDER，脚本会拒绝混用不同的向量维度。

子 Agent 技能

• /rlm-analyze - 使用隔离的子 Agent 分析单个分块
• /rlm-parallel - 并行分析多个分块（采用 MIT RLM 论文中的 Map-Reduce 模式）

---

对比

功能	原始上下文	Letta/MemGPT	claude-mem	RLM
持久化记忆	否	是	是	是
适用于 Claude Code	不适用	否（使用自己的运行时）	插件（钩子 + 工作进程）	原生 MCP + 钩子
保存内容	无	由 Agent 管理	每次工具调用，由大模型压缩	你分块保存的内容；未保存的会话会被标记
后台大模型调用	否	是	是（每次观察时）	无
压缩前保护	否	不适用	不适用（持续捕获）	是（没有分块时会阻止手动执行 /compact）
搜索（正则 + BM25 + 语义）	否	基础	全文 + 可选向量	是
模糊搜索（容错拼写错误）	否	否	—	是
多项目支持	否	否	是	是
智能保留（归档/清除）	否	基础	—	是
子 Agent 分析	否	否	—	是
零配置安装	不适用	复杂	一条命令	3 行
FR/EN/JA 支持	不适用	仅 EN	多语言模式	3 种语言
成本	免费	可自托管	大模型用量或托管方案	免费

— = 未评估。claude-mem 一栏反映的是其截至 2026 年 10 月的文档内容。

claude-mem 和 RLM 选择了截然相反的方案。claude-mem 会自动记录所有内容，并通过大模型调用来压缩；RLM 只存储你决定保留的内容，不产生大模型成本，并会提醒你保存遗漏的会话，而不是让它们悄然丢失。

---

使用示例

会话启动（推荐）

# Load universal rules (apply regardless of topic).
# Pass a limit above your critical count — the default is 10, and a recall
# that returns 10 of 34 rules looks exactly like a complete one.
rlm_recall(importance="critical", limit=50)

# Load context for current topic
rlm_recall(query="deployment")

# Check memory status
rlm_status()

保存和回忆见解

# Save a universal rule (loaded every session)
rlm_remember("Always deploy LOCAL → VPS, never direct",
             category="decision", importance="critical",
             tags="deploy,workflow")

# Save a topic-specific insight
rlm_remember("WeasyPrint requires inline CSS for PDF rendering",
             category="finding", importance="high",
             tags="weasyprint,pdf")

# Find insights later
rlm_recall(query="source of truth")
rlm_recall(category="decision")
rlm_recall(importance="critical", limit=50)   # all universal rules (mind the default limit of 10)

重要性级别

级别	使用场景	加载时机
critical	通用规则（无论主题如何都适用）	每次会话
high	特定主题的规则	处理该主题时
medium	有用但不会造成阻碍的信息	显式搜索时

测试：「即使处理完全不同的主题，这条规则也适用吗？」如果适用 → critical。

管理对话历史

# Save important discussion (typed)
rlm_chunk("Discussion about API redesign... [long content]",
          summary="API v2 architecture decisions",
          tags="api,architecture",
          chunk_type="session")        # or "snapshot", "debug"

# Search across all history
rlm_search("API architecture decisions")      # BM25 ranked
rlm_grep("authentication", fuzzy=True)         # Typo-tolerant

# Read a specific chunk
rlm_peek("2026-01-18_MyProject_001")

多项目组织

# Filter by project
rlm_search("deployment issues", project="MyApp")
rlm_grep("database", project="MyApp", domain="infra")

# Browse sessions
rlm_sessions(project="MyApp")

---

项目结构

rlm-claude/
├── src/mcp_server/
│   ├── server.py              # MCP server (14 tools)
│   └── tools/
│       ├── memory.py          # Insights (remember/recall/forget)
│       ├── navigation.py      # Chunks (chunk/peek/grep/list)
│       ├── search.py          # BM25 search engine
│       ├── tokenizer_fr.py    # FR/EN tokenization
│       ├── sessions.py        # Multi-session management
│       ├── retention.py       # Archive/restore/purge lifecycle
│       ├── embeddings.py      # Embedding providers (Model2Vec, FastEmbed)
│       ├── vecstore.py        # Vector store (.npz) for semantic search
│       ├── diagnostics.py     # Warning log (rlm.log) — degraded ops stay visible
│       └── fileutil.py        # Safe I/O (atomic writes, path validation, locking)
│
├── hooks/                     # Claude Code hooks
│   ├── i18n.py                # Translations (EN/FR/JA) for hook messages
│   ├── pre_compact_chunk.py   # Guard before /compact (PreCompact hook)
│   ├── memory_write_redirect.py # Redirect auto-memory writes to RLM (PostToolUse hook)
│   ├── reset_chunk_counter.py # Last-chunk time + chunk ↔ session link (PostToolUse hook)
│   ├── session_trace.py       # What a session touches, metadata only (PostToolUse hook)
│   ├── session_orphans.py     # Unsaved past sessions at startup, --ack (SessionStart hook)
│   └── session_common.py      # Shared paths, config and lock-safe index update
│
├── templates/
│   ├── hooks_settings.json    # Hook config template
│   ├── CLAUDE_RLM_SNIPPET.md  # CLAUDE.md instructions
│   └── skills/                # Sub-agent skills
│
├── context/                   # Storage (created at install, git-ignored)
│   ├── session_memory.json    # Insights
│   ├── index.json             # Chunk index
│   ├── chunks/                # Conversation history
│   ├── archive/               # Compressed archives (.gz)
│   ├── embeddings.npz         # Semantic vectors (Phase 8)
│   └── sessions.json          # Session index
│
├── install.sh                 # One-command installer
└── README.md

---

配置

Hook 配置

安装程序会自动在 ~/.claude/settings.json 中配置钩子：

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "manual",
        "hooks": [{ "type": "command", "command": "python3 ~/.claude/rlm/hooks/pre_compact_chunk.py" }]
      },
      {
        "matcher": "auto",
        "hooks": [{ "type": "command", "command": "python3 ~/.claude/rlm/hooks/pre_compact_chunk.py" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "mcp__rlm-server__rlm_chunk",
        "hooks": [{ "type": "command", "command": "python3 ~/.claude/rlm/hooks/reset_chunk_counter.py" }]
      },
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "python3 ~/.claude/rlm/hooks/memory_write_redirect.py" }]
      },
      {
        "matcher": "Edit",
        "hooks": [{ "type": "command", "command": "python3 ~/.claude/rlm/hooks/memory_write_redirect.py" }]
      },
      {
        "matcher": "Edit|Write|MultiEdit|NotebookEdit|Bash",
        "hooks": [{ "type": "command", "command": "python3 ~/.claude/rlm/hooks/session_trace.py" }]
      }
    ],
    "SessionStart": [{
      "matcher": "",
      "hooks": [{ "type": "command", "command": "python3 ~/.claude/rlm/hooks/session_orphans.py" }]
    }]
  }
}

同一配置块位于 templates/hooks_settings.json，安装程序会读取该文件。

会话追踪

可选的 ~/.claude/rlm/session_trace.json（所有键均为可选项）：

{
  "notable_commands": ["ssh", "scp", "rsync", "psql", "kubectl", "terraform", "ansible-playbook", "deploy.sh"],
  "min_edits": 5,
  "idle_hours": 2,
  "retention_days": 30,
  "max_listed": 5
}

• notable_commands：会话运行这些程序时，会记录其基本名称（不会记录参数）。会话中只要运行过一次值得关注的命令，该会话就会被计入。
• min_edits：Edit/Write 操作次数超过此值的会话会被计入。
• idle_hours：空闲时间少于此值的会话会被视为仍在运行（不会干扰并行会话）。
• retention_days：超过此天数的追踪记录会被删除。请与 Claude Code 的 cleanupPeriodDays 保持一致（默认值为 30）：超过此期限后，记录文本会被删除，无法再恢复会话。

语言

钩子消息默认使用英语。设置 RLM_LANG=fr 可使用法语，设置 RLM_LANG=ja 可使用日语：

# Option 1: Set globally in your shell profile (~/.zshrc, ~/.bashrc)
export RLM_LANG=fr   # or ja

# Option 2: Set per-hook in ~/.claude/settings.json
# Replace the command with:
"command": "RLM_LANG=fr python3 ~/.claude/rlm/hooks/pre_compact_chunk.py"

支持的语言：en（默认）、fr、ja。

存储目录

RLM 默认将数据存储在 ~/.claude/rlm/context/ 中。使用 RLM_CONTEXT_DIR 更改存储目录：

export RLM_CONTEXT_DIR=/path/to/custom/storage

这对 Docker 部署尤其有用（见下文）。

自定义域

使用自定义域按主题整理分块：

{
  "domains": {
    "my_project": {
      "description": "Domains for my project",
      "list": ["feature", "bugfix", "infra", "docs"]
    }
  }
}

安装后编辑 context/domains.json。

---

手动安装

通过 pip

pip install -e ".[all]"
claude mcp add rlm-server -- python3 -m mcp_server

通过 uv

uv tool install mcp-rlm-server[all] --python 3.12
claude mcp add rlm-server -- ~/.local/bin/mcp-rlm-server

钩子设置（pip 和 uv 安装必需）

./install.sh 脚本会自动完成此操作。手动安装时：

# Get hook scripts from the repo
git clone https://github.com/EncrEor/rlm-claude.git /tmp/rlm-setup

# Install hooks and i18n
mkdir -p ~/.claude/rlm/hooks
cp /tmp/rlm-setup/hooks/*.py ~/.claude/rlm/hooks/
chmod +x ~/.claude/rlm/hooks/*.py

# Install skills (optional)
mkdir -p ~/.claude/skills/rlm-analyze ~/.claude/skills/rlm-parallel
cp /tmp/rlm-setup/templates/skills/rlm-analyze/skill.md ~/.claude/skills/rlm-analyze/
cp /tmp/rlm-setup/templates/skills/rlm-parallel/skill.md ~/.claude/skills/rlm-parallel/

# Cleanup
rm -rf /tmp/rlm-setup

然后在 ~/.claude/settings.json 中配置钩子（见上文钩子配置）。

Docker 设置

构建镜像：

git clone https://github.com/EncrEor/rlm-claude.git
cd rlm-claude
docker build -t rlm-server .

配置 Claude Code MCP 以使用 Docker：

claude mcp add rlm-server -- docker run -i --rm -v ~/.claude/rlm/context:/data rlm-server

或者在 ~/.claude/settings.json 中手动配置：

{
  "mcpServers": {
    "rlm-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "~/.claude/rlm/context:/data", "rlm-server"]
    }
  }
}

Docker 镜像内部使用 RLM_CONTEXT_DIR=/data，卷挂载会将其映射到本地存储。

卸载

./uninstall.sh              # Interactive (choose to keep or delete data)
./uninstall.sh --keep-data  # Remove RLM config, keep your chunks/insights
./uninstall.sh --all        # Remove everything
./uninstall.sh --dry-run    # Preview what would be removed

---

安全性

RLM 内置了安全运行保护措施：

• 路径遍历防护 - 分块 ID 会根据严格的允许列表 ([a-zA-Z0-9_.-&]) 进行校验，并验证解析后的路径是否位于存储目录内
• 原子写入 - 所有 JSON 和分块文件都采用先写入临时文件再重命名的方式，防止因写入中断或崩溃导致文件损坏
• 文件锁定 - 对共享索引进行并发读写操作时，会使用 fcntl.flock 独占锁
• 内容大小限制 - 分块大小限制为 2 MB，gzip 解压（归档恢复）限制为 10 MB，以防资源耗尽
• SHA-256 哈希 - 内容去重使用 SHA-256（而非 MD5）

所有 I/O 安全原语都集中在 mcp_server/tools/fileutil.py 中。

---

故障排查

“未找到 MCP 服务”

claude mcp list                    # Check servers
claude mcp remove rlm-server       # Remove if exists
claude mcp add rlm-server -- python3 -m mcp_server

“钩子无法正常工作”

cat ~/.claude/settings.json | grep -A 10 "PreCompact"  # Verify hooks config
ls ~/.claude/rlm/hooks/                                  # Check installed hooks

---

路线图

• 阶段 1：记忆工具（remember/recall/forget/status）
• 阶段 2：导航工具（chunk/peek/grep/list）
• 阶段 3：自动分块 + 子 Agent 技能
• 阶段 4：生产环境功能（自动摘要、去重、访问追踪）
• 阶段 5：高级功能（BM25 搜索、模糊 grep、多会话、保留策略）
• 阶段 6：生产就绪（测试、CI/CD、PyPI）
• 阶段 7：受 MAGMA 启发的功能（时间过滤、实体提取）
• 阶段 8：混合语义搜索（BM25 + 余弦相似度、Model2Vec）
• 阶段 9：类型化分块 — chunk_type 参数（snapshot/session/debug/insight 重定向）
• 阶段 10：自动记忆与 RLM 共存 — Write/Edit 钩子将自动记忆重定向到 RLM + 日语本地化
• 阶段 11：安全保障 — PreCompact guard v2、按重要性排序的召回并报告截断情况、会话追踪 + 未保存会话报告

---

灵感来源

研究论文

• RLM 论文（MIT CSAIL） - Zhang 等人，2025 年 12 月 - “递归语言模型”——奠基性架构（分块/窥探/grep、子 Agent 分析）
• MAGMA（arXiv:2601.03236） - 2026 年 1 月 - “基于记忆 Agent 的记忆增强生成”——时间过滤、实体提取（阶段 7）

库与工具

• Model2Vec - 静态词嵌入，用于快速语义搜索（阶段 8）
• BM25S - 纯 Python 实现的快速 BM25（阶段 5）
• FastEmbed - 基于 ONNX 的嵌入，可选提供方（阶段 8）
• Letta/MemGPT - AI Agent 记忆框架——早期灵感来源

标准与平台

• MCP 规范 - Model Context Protocol
• Claude Code Hooks - PreCompact / PostToolUse 钩子

---

贡献

翻译

本仓库以英文维护。面向用户的文件可以翻译成你的语言：

文件	用途	欢迎翻译
README.md	主要文档	README.xx.md（例如，README.fr.md、README.ja.md）
templates/CLAUDE_RLM_SNIPPET.md	CLAUDE.md 指令	CLAUDE_RLM_SNIPPET.xx.md

代码、注释和提交信息均使用英文。

---

作者

• Ahmed MAKNI (@EncrEor)
• Claude Opus 4.6（联合研发）

许可证

MIT License - 详见 LICENSE