Retrieve The Forgotten Memory

---

问题

你的 AI Agent 正在盲目摸索。

它在数千个文件中搜索，却找不到能回答问题的文档；凭空编造不存在的模块；忘记你们在上次会话中的决定。项目越大，情况越糟。你换了更智能的模型，却毫无帮助。因为瓶颈不在智能，而在检索。

代码索引工具（Augment、Sourcegraph、Cursor）只能查看代码。但你的项目不只有代码，还有规范、PR、架构决策、研究论文、PDF、法规、知识库笔记——这些都是 Agent 不再靠猜测所需的上下文。

我为什么构建它

我当时在写一篇法国税务文章（约 50 页的法规文本，涉及法典条文之间的交叉引用、判例法和行政解释）。Claude Code 不停地循环搜索同一批目录，耗尽上下文，还自信满满地给出错误引文。我增加了更多记忆，改进了提示词，也换了更智能的模型，全都无济于事。问题不在于 Agent 推理得不好，而是它无法在包含 2,000 个文件的法律语料库中找到正确的段落。于是我不再试图让模型变得更聪明，转而构建它所缺少的那一层。这就是 RTFM。

解决方案

RTFM 为所有内容建立索引。 只需一条命令、一个 SQLite 文件，以及一个供 Agent 在搜索前查询的检索层。

pip install rtfm-ai && cd your-project && rtfm init

只需 30 秒。Claude Code 就能搜索你已建立索引的知识库——代码、文档、PDF，以及你放入其中的其他任何内容——支持全文、语义或混合搜索。Agent 首先看到 300 个 Token 的元数据，然后只展开相关内容。渐进式披露，而非倾倒上下文。

免费。本地运行。无需 API 密钥。无需云服务。你的数据仍由你掌控。

效果展示

$ rtfm search "authentication flow" --limit 3
[1] src/auth/handlers.py > authenticate_user (p.2)    score 9.12
    src/auth/handlers.py:147  42 lines
[2] docs/architecture/auth.md > SSO flow (p.1)        score 7.84
    docs/architecture/auth.md:1   23 lines
[3] docs/ADR/0007-oauth.md > Decision (p.1)           score 6.90
    docs/ADR/0007-oauth.md:12  18 lines

三个结果，约 300 个 Token。Agent 使用 rtfm_expand(source, target_section) 决定接下来要读什么——不是倾倒上下文，而是一场对话。

---

快速开始

推荐 — Claude Code 插件

在 Claude Code（CLI 或桌面端的 Code 选项卡）中：

/plugin marketplace add roomi-fields/claude-plugins
/plugin install rtfm@roomi-fields

RTFM 通过 roomi-fields/claude-plugins marketplace 分发，其中也提供用于带引用问答的 notebooklm-mcp。要一次性获取两者：

/plugin install notebooklm@roomi-fields

就这么简单。插件会在首次使用时自动初始化每个项目：

• 创建 .rtfm/library.db（一个 SQLite 文件）
• 将搜索说明注入 CLAUDE.md
• 预先授予 MCP 工具权限（每次搜索都无需确认）
• 在首次提示词时为项目编制索引，此后每次提示词都会增量重新编制索引

无需 pip install。 纯 Python，可在已将 Python 3.10+ 添加到 PATH 的 Linux / macOS / Windows / WSL 上运行。插件内置了自己的 MCP 服务（不依赖 mcp SDK），并会自动查找 python3 / python / py。

然后对 Claude 说：“查找身份验证流程”——它会使用 rtfm_search，而不是运行 grep。

可选附加组件（语义搜索、PDF 解析）

核心插件无需依赖。较重的可选附加组件（嵌入模型、PDF 解析器）会按需安装到插件数据目录中的隔离 venv 内，不会污染系统 Python，也不会产生 PEP 668 冲突：

/rtfm:install-embeddings    # FastEmbed ONNX (~85 MB), semantic + hybrid search
/rtfm:install-pdf           # pdftext only (~50 MB), fast text extraction
/rtfm:install-pdf-full      # + marker-pdf + CPU-only torch (~1.5 GB), complex layouts

pdf-full 安装会使用 PyTorch 的仅 CPU 索引（无需 CUDA 或 GPU），安装大小约为 1.5 GB，而不是 5 GB。

安装后重启 Claude Code，以加载这些附加组件。

手动安装（Cursor、Codex、Claude Desktop 聊天、其他 MCP 客户端）

适用于没有 Claude Code 插件系统的客户端：

pip install rtfm-ai
cd /path/to/your-project
rtfm init

然后将 MCP 客户端指向 rtfm-serve（pip 包提供的入口）。可选附加组件可通过 pip install rtfm-ai[embeddings,pdf] 安装。

---

对比

	RTFM	Augment CE	Sourcegraph	Code-Index-MCP	MemPalace
代码索引	✅（感知 AST）	✅	✅	✅	浅层（按字符分块）
文档、规范、Markdown	✅（按标题解析）	部分支持	❌	有限支持	原样分块
法律 / 监管内容	✅（XML、BOFiP）	❌	❌	❌	❌
研究资料（LaTeX、PDF）	✅	❌	❌	❌	❌
自定义解析器	✅（约 50 行）	❌	❌	❌	❌
知识图谱	✅（文件 / 代码链接）	❌	部分支持	❌	实体图谱（人物）
文件版本历史	✅（无限）	❌	❌	❌	❌（清空后替换）
原生支持 MCP	✅	✅	✅	✅	✅
本地运行	✅	云端	企业版	✅	✅
开源	MIT	❌	部分开源	✅	MIT
价格	免费	每月 $20-200	每月 $$$	免费	免费

RTFM 是唯一一款开源方案，能够通过结构化解析为多领域内容建立索引，并提供代码级知识图谱和无限的单文件历史记录。 这就是它的定位。

与 MemPalace 的具体区别：MemPalace 是面向对话的实体级记忆（在 SQLite 中存储人物 / 项目 / 决策三元组，并在 ChromaDB 中存储原样分块）。RTFM 则是面向制品的检索层——按格式解析、在文件级别建立关联，并随时间保留版本。两者可以组合使用，并非相互竞争。

如需深入了解 RAG 的设计选择（分块、检索、增强、集成、时效性、存储），请参阅 RAG 基础知识——6 个维度 →

---

跨会话延续的记忆

大多数 Agent 在会话之间都会遗忘。RTFM 会为你机器上所有项目中的 Claude Code 自带记忆文件建立索引，并保留完整版本历史。

rtfm memory                    # Manual snapshot
rtfm memory --install-hook     # Auto-snapshot on every SessionEnd

• 跨项目索引 — ~/.rtfm/memory.db 中的一个数据库即可查看你机器上所有 ~/.claude/projects/*/memory/ 目录。询问 rtfm_search("OAuth auth decisions")，即可从你的全部 18 个项目中获取匹配结果。
• 无限版本历史 — 记忆文件的每次更改都会生成快照（不会清理）。rtfm_history <slug> 会返回完整的演变记录。
• 在 SessionEnd 时自动生成快照 — 只需一条命令即可安装全局 Claude Code hook。每次结束会话时，都会捕获新快照。
• 经过整理，而非原样记录 — RTFM 为 Agent 在会话期间自行整理的笔记建立索引（精简、有结构、信息密度高）。这与 MemPalace 的理念不同：后者会在 ChromaDB 中为完整对话记录建立索引（内容庞大、噪声较多，需要进行积极的语义过滤）。

---

Obsidian 库模式

RTFM 是 Karpathy LLM Wiki 模式的检索层。Karpathy 本人写道：“规模较小时，索引文件就够用了；但随着 Wiki 增长，你就需要完善的搜索。” 这就是完善的搜索。

cd /path/to/your-obsidian-vault
rtfm vault

• 检测 .obsidian/，并提出文件夹到语料库的映射
• 按照 Obsidian 规则解析 [[wikilinks]] → 存储为图边
• 生成 _rtfm/，提供 Obsidian 原生导航（索引、Mermaid 图、中心页、孤立笔记、Dataview frontmatter）
• 已在一个包含 1,700 篇笔记的研究库中测试

_rtfm/
├── index.md      # Hub: corpus list, top connected documents
├── graph.md      # Hub documents, orphans, broken links, Mermaid
├── recent.md     # Recently modified files
└── corpus/       # Per-corpus indexes

LLM 仍会为你编写 Wiki。RTFM 负责处理 index.md 无法扩展支持的检索工作。

完整的 Obsidian 指南 →

---

NotebookLM 集成

RTFM 与 notebooklm-mcp 天然适配。NotebookLM 将每个笔记本的查询次数限制为每天 50 次；RTFM 通过在本地为答案建立索引，打破这一上限——查询一次，永久检索，离线可用，耗时仅毫秒。

notebooklm-mcp 的 /batch-to-vault 端点会将带引用的问答写入 {slug}.md（包含 frontmatter 的 Markdown）和 {slug}.json（结构化的 nblm-answer-v1 sidecar）。两者可保证共存。今天即可使用以下两种集成方式：

• 方式 A — Markdown（零配置）：将库放入 RTFM，然后运行 rtfm sync。默认的 Markdown 解析器会自动将每个答案切分为问题、答案和逐条引用的区块。无需映射、无需模式、无需代码。
• 方式 B — JSON sidecar（类型化元数据）：将 nblm-answer.yaml 映射放入 .rtfm/mappings/。每个 .json 答案文件都会生成类型化区块，其中包含可通过 SQL 查询的 notebook_id、source_name、citation_marker，并生成答案与来源之间的 cites 边候选项。

除非你确实需要按结构化引用字段筛选或构建图，否则请使用方式 A。

完整的 NotebookLM 操作指南 →

---

测量结果

我进行了两类基准测试。实际情况比较复杂——检索对那些确实可解决、且 Agent 正在花时间查找内容的任务帮助最大。

文档密集型任务：法语税务文章生成（B10）

根据法律条文、判例法和行政解释语料，撰写一篇约 50 页的规范性文章。使用相同的 Agent（Claude Code + Sonnet 4）和相同的提示词，测试了 8 种配置。

配置	耗时	成本	Token 数
基线（不使用 RTFM）	8m 16s	$22.61	8.21 M
使用 RTFM（默认 FTS）	6m 58s	$11.14	3.22 M

Δ：成本 −51 %、Token 数 −61 %、耗时 −16 %，且事实准确性更高。 这正是 RTFM 的设计用途：在大型多领域语料中查找内容，而 grep 往往找不到正确段落。

代码任务：FeatureBench（LiberCoders 数据集）

11 个任务、3 个不同规模的仓库、4 种条件（A = 标准提示词，包含文件路径；B = 探索，不提供路径；C = RTFM FTS；D = RTFM 混合模式），每种条件各运行 3 次。

仓库	大小	RTFM 有帮助的情况
metaflow	620 个文件	所有任务都已解决——RTFM 没有带来可测量的提升
astropy	1,119 个文件	所有条件的 F2P 通过率均为 25–30 %；没有任务完全解决
mlflow	8,255 个文件	所有条件的 F2P 通过率均为 0–5 %；没有任务完全解决

在一次范围较小的运行中（metaflow 上的 test_stub_generator），与不提供路径的基线相比，RTFM 将 Agent 耗时缩短了 −37 %。在较大的仓库中，无论使用何种检索方式，任务本身都难到 Sonnet 4 无法在 20 分钟超时内解决。

诚实地说，仍有一些限制

• 只有一个模型（Sonnet 4）和一个 Agent（Claude Code），统计结果并非万无一失。
• 对于小型代码库（少于 1k 个文件），grep 已经够用，而 RTFM 反而会增加开销。
• FeatureBench 衡量的是代码修改，而非信息检索。它并不适合用来评测检索工具——我仍用它进行评测，只因为目前有这个基准。更合适的基准（RepoQA、SWE-QA、LocAgent）已列入路线图。

这说明了什么

当瓶颈是**“在包含 2,000 个文件的语料库中找到正确段落”**时，RTFM 的效果有可衡量的优势。它不会神奇地让无法解决的任务变得可解。模型仍然需要完成工作——RTFM 只是确保它能获取正确的上下文来完成工作。

---

适用对象

只要你的项目不只有代码，RTFM 就能派上用场：

• 法律科技 — 代码 + 税法 + 监管规范。内置 Legifrance XML 和 BOFiP 解析器。
• 研究 — 代码 + LaTeX 论文 + 数据集。内置 LaTeX 和 PDF 解析器。
• 金融科技 — 代码 + 金融法规 + XBRL 报告。只需 50 行代码即可编写 XBRL 解析器。
• 医疗科技 — 代码 + 医疗记录（HL7/FHIR）+ 临床指南。
• 拥有大型项目的独立开发者 — 别再每次会话都看着 Agent 对同样的 8,000 个文件执行 grep。
• Obsidian / PKM 用户 — 让 AI 真正能够搜索你的知识库。
• 任何受监管的行业 — 如果你的项目混合了代码与领域文档，RTFM 就适合你。

---

完整功能列表

搜索与检索

• FTS5 全文搜索 — 即时、零配置，开箱即用
• 语义搜索 — 可选嵌入（FastEmbed/ONNX，无需 GPU）
• 混合模式 — 结合两种方式，按相关性得分排序
• 元数据优先 — 搜索结果返回文件路径和得分（约 300 个 token），而非内容倾倒
• 渐进式披露 — Agent 只展开实际需要的内容块
• 知识图谱 — 将 wikilinks + Python 导入解析为图边，支持枢纽检测和中心性排序

多格式索引

• 内置 24 种解析器 — Markdown、Python（AST）、LaTeX、YAML、JSON、TOML、Shell、PDF、XML、HTML、SQLite、Jupyter、CSV/TSV、XLSX、EPUB、MOBI/AZW、FB2、DJVU、DOCX、ODT、RTF、MIDI、音频标签（MP3/FLAC/OGG/M4A/WAV/AIFF…）、纯文本
• 可扩展 — 用约 50 行 Python 支持任意格式
• 自动同步钩子 — 每次提示词后保持索引最新，无需手动操作
• 增量处理 — 只重新索引发生变化的内容

集成

• 原生 Claude Code 插件 — /plugin install rtfm@roomi-fields/rtfm，按项目自动初始化
• 纯 Python MCP 服务 — 无外部依赖，无需 mcp SDK / pydantic / 原生二进制文件
• 跨平台 — Linux、macOS、Windows、WSL（只需 PATH 中有 Python ≥ 3.10）
• 14 个 MCP 工具 — 搜索、上下文、展开、图谱、历史记录、同步、标签等
• 手动安装备用方案 — 使用 pip install rtfm-ai，适用于 Cursor、Codex、Claude Desktop chat 及其他 MCP 客户端
• CLI + Python API — 可用于编写流水线脚本
• 无侵入性 — 不会触碰你的代码，也不会替换你的编辑器

---

解析器架构

需要索引一种目前没有任何工具支持的格式？用约 50 行代码编写解析器即可。

from rtfm.parsers.base import BaseParser, ParserRegistry
from rtfm.core.models import Chunk
import json
from uuid import uuid4

@ParserRegistry.register
class FHIRParser(BaseParser):
    """Parse HL7 FHIR medical records."""
    extensions = ['.fhir.json']
    name = "fhir"

    def parse(self, path, metadata=None):
        data = json.loads(path.read_text())
        for entry in data.get('entry', []):
            resource = entry.get('resource', {})
            yield Chunk(
                id=resource.get('id', str(uuid4())),
                content=json.dumps(resource, indent=2),
                book_title=f"FHIR {resource.get('resourceType', 'Unknown')}",
                book_slug=resource.get('id', 'unknown'),
                page_start=1,
                page_end=1,
            )

将它放入项目，重启 Claude Code，你的医疗 AI Agent 就能理解 FHIR 记录了。

两种 JSON 集成方式

对于基于 JSON 的格式，RTFM 还提供了第二种扩展方式，无需使用 Python：

级别	操作	效果
1. 通用	无需操作。直接索引文件即可。	每个顶层键都会成为一个内容块。全文搜索可搜索值。
2. 映射	将 YAML 映射文件放入 .rtfm/mappings/（约 30 行）。	获得带有已声明元数据、自定义标题、数组 foreach 提取和边候选项的类型化内容块。生成该数据的项目（NotebookLM、Linear、Notion、OpenAPI 等）提供映射；RTFM 保持通用。

请参阅 JSON schema 映射了解完整参考，并参阅 RTFM × NotebookLM查看具体示例。

内置解析器

解析器	扩展名	策略
Markdown	.md	按标题拆分，提取 YAML frontmatter
Python	.py	基于 AST：每个类或函数 = 1 个分块
LaTeX	.tex	按 \section、\chapter 等拆分
YAML	.yaml、.yml	按顶层键拆分
JSON	.json	按顶层键或数组元素拆分
TOML	.toml	顶层表；生成 depends_on 边（PEP 621、Cargo、Poetry）
Shell	.sh、.bash、.zsh	按函数拆分
PDF	.pdf	按页拆分（pip install rtfm-ai[pdf]）
Legifrance XML	.xml	法国法律法规（LEGI 格式）
BOFiP HTML	.html	法国税务法规
SQLite	.sqlite、.sqlite3、.db	每个表包含架构和示例行；外键边（只读）
Jupyter	.ipynb	按 Markdown 标题对单元格分组；丢弃输出
CSV / TSV	.csv、.tsv	标题行 + 示例行 + 轻量级类型推断
XLSX	.xlsx	每个工作表的架构和示例（pip install rtfm-ai[xlsx]）
纯文本	.js、.ts、.rs、.go、...	按行边界拆分（约 500 个字符）

---

MCP 工具

工具	功能
rtfm_search	搜索索引（全文、语义或混合）
rtfm_context	获取主题的相关上下文（仅元数据）
rtfm_expand	显示来源的所有分块及完整内容
rtfm_discover	快速扫描项目结构（约 1 秒，无需建立索引）
rtfm_books	列出已索引的文档
rtfm_stats	知识库统计信息
rtfm_sync	同步目录（增量）
rtfm_ingest	摄取单个文件
rtfm_tags	列出所有标签
rtfm_tag_chunks	为指定分块添加标签
rtfm_remove	从索引中移除文件
rtfm_graph	显示来源的依赖关系图（导入、链接）
rtfm_history	文件版本历史和记忆快照
rtfm_coverage	对比索引内容与磁盘上的内容

---

CLI 参考

# Search
rtfm search "authentication flow"
rtfm search "article 39" --corpus cgi --limit 5

# Sync
rtfm sync                              # All registered sources
rtfm sync /path/to/docs --corpus docs  # Specific directory
rtfm sync . --force                    # Force re-index

# Source management
rtfm add /path/to/docs --corpus docs --extensions md,pdf
rtfm sources

# Obsidian vault
rtfm vault                             # Initialize for cwd vault
rtfm vault /path/to/vault              # Specific vault
rtfm vault --regenerate                # Regenerate _rtfm/ files

# Cross-project Claude memory
rtfm memory                            # Manual snapshot
rtfm memory --install-hook             # Auto-snapshot on SessionEnd

# Status & info
rtfm status
rtfm books
rtfm tags
rtfm history path/to/file.md           # Memory version history

# Semantic search
rtfm embed                             # Generate embeddings (one-time)
rtfm semantic-search "tax deductions" --hybrid

# MCP server
rtfm serve

---

Python API

from rtfm import Library

lib = Library("my_library.db")

# Index
stats = lib.ingest("documents/article.md", corpus="docs")
result = lib.sync(".", corpus="my-project")  # SyncResult(+3 ~1 -0 =42)

# Search
results = lib.search("depreciation", limit=10, corpus="cgi")
results = lib.hybrid_search("amortissement fiscal", limit=10)

# Export for LLM
prompt_context = results.to_prompt(max_chars=8000)

lib.close()

---

RTFM 的定位

RTFM 不是任务管理器，也不是 Agent 框架。无论你已经在使用什么，RTFM 都是 Agent 所需的底层知识层。

┌─────────────────────────────────┐
│  GSD / Taskmaster / Claude Flow │  ← Orchestration
├─────────────────────────────────┤
│              RTFM               │  ← Knowledge (you are here)
├─────────────────────────────────┤
│          Claude Code            │  ← Execution
└─────────────────────────────────┘

没有 RTFM，你的编排器驱动的 Agent 会产生幻觉。有了 RTFM，Agent 就能了解自己所构建的基础。

---

参与贡献

添加解析器是最简单、也最有影响力的贡献方式。请参阅 CONTRIBUTING.md。

发现了 Bug？有想法？提交问题。

致谢

@AVeryTastyRaspberry 让 RTFM 能在原生 Windows 上运行。RTFM 在 Linux 上开发，而每条命令在 Windows 上都会出错——CLI 在导入时就崩溃，甚至还没来得及解析参数。问题报告 (#8) 指明了出错的代码行；随后在一台真实的 Windows 11 机器上进行的测试，通过 tasklist 而非 RTFM 自己的说法进行核验，发现了另外五个相关缺陷，并确认每项修复都有效。接着，#9 追查了那些不断弹出的控制台窗口。没有这项贡献，本项目就无法支持这个平台。

许可证

MIT — 使用、分叉、扩展、发布，悉听尊便。

作者

Romain Peyrichou — @roomi-fields

---