# ReMe 设计文档 ## 整体定位 > 一句话总结：**自进化的个人知识库**——你只管往里扔东西和对话，它自己长成一张知识图谱。 ## 特性1：记忆分层 记忆按"原始 → 浅加工 → 深加工"三层组织： ### 1.1 目录结构 ``` - reme_session/ - agentscope|claude_code / # 使用内置的agent wrapper，session会保存在这里 {session_id}.jsonl UUID格式要求 # /Users/yuli/workspace/ReMe/reme4/components/agent_wrapper - dialog/ {session_id}.jsonl # auto memory保存 可以监控可以被检索【可选】 - resource/ - YYYY-MM-DD/ - {channel}_{xxxx}.html - {channel}_{xxxx}.md - daily/【日记，浅加工】 - YYYY-MM-DD.md - YYYY-MM-DD/ - session_{session_id}.md - {resource_stem}.md - digest/ - personal/ - procedure/ - wiki/ ``` ### 1.2 分层详解 | 目录 | 存什么 | 谁写入 | 举例 | |---------------------|----------------|-------------|-----------------------------------| | `resource/` | 原始文件（研报、网页、邮件） | upload / 手动 | PDF 研报、对话 JSONL | | `daily/` | 每天的事件记录 | auto-memory | "调试登录 CSS"、"与 Alice 聚餐" | | `digest/procedure/` | 方法论、步骤 | auto-dream | "webpack 编译卡死排查路径" | | `digest/personal/` | 用户画像、偏好 | auto-dream | "用户不爱写注释"、"用户喜欢 pnpm" | | `digest/wiki/` | 通用知识、决策先例 | auto-dream | "光伏产业链"、"React Server Components" | `resource/` 和 `daily/` 是只增不删的流水账；`digest/` 下三个桶是反复消费的精华层，各桶有独立的整合 prompt。 ## 特性2：Obsidian 兼容的 Markdown 格式 所有笔记都是标准 Markdown + Obsidian 语法，可以直接用 Obsidian 打开浏览： ``` ┌─────────────────────────────────────────────────────────────┐ │ 一个 .md 文件的完整结构 │ ├─────────────────────────────────────────────────────────────┤ │ --- │ │ name: 宁德时代 ← YAML front matter │ │ description: 全球动力电池龙头 │ │ tags: [新能源, 电池] │ │ --- │ ├─────────────────────────────────────────────────────────────┤ │ 所属行业:: [[新能源]] ← 语义化链接（Dataview） │ │ 竞争对手:: [[比亚迪]] │ │ │ │ # 基本面 ← Markdown 正文 │ │ 全球动力电池出货量第一，核心技术为 │ │ [[CTP]] 和 [[钠离子电池]]…… ← 标准 wikilink │ │ │ │ 参考 ![[2026Q1调研纪要]] ← 嵌入引用 │ ├─────────────────────────────────────────────────────────────┤ │ ↓ AST 语义分块 ↓ │ │ chunk 1: [标题骨架] + 正文片段 │ │ chunk 2: [标题骨架] + 正文片段 │ └─────────────────────────────────────────────────────────────┘ ``` ### 2.1 YAML front matter 每个笔记头部的元数据： ```markdown --- name: 光伏产业链研究 description: 从硅料到组件的全链条梳理 tags: [新能源, 光伏, 产业链] --- ``` `name` / `description` 是约定字段，其余键值对全部保留，不会丢弃任何自定义字段。 ### 2.2 四种 wikilink 写法 | 写法 | 示例 | 语义 | |------|----------------|----------| | 标准链接 | `[[光伏产业链]]` | 指向目标文件 | | 锚点链接 | `[[钴#应用]]` | 指向特定章节 | | 别名链接 | `[[宁德时代\|宁德]]` | 自定义显示文本 | | 嵌入引用 | `![[钴]]` | 内联嵌入目标内容 | ### 2.3 语义化链接（Dataview 风格） 普通 wikilink 只说"A 提到了 B"，语义化链接还能表达"A 和 B 是什么关系"： ```markdown 所属行业:: [[新能源]] ← 行级属性（独占一行） 总部:: [[宁德]] [竞争对手:: [[比亚迪]]] ← 内联属性（嵌入正文中） ``` `WikilinkHandler` 是全系统唯一的 wikilink 解析入口，确保 parser、graph、search 各层规则一致。 ### 2.4 AST 感知的语义分块 传统 RAG 按固定 token 长度切片，经常切坏文档结构。ReMe 基于 Markdown AST 做语义分块： - 按 H1/H2/H3 章节嵌套建树，递归分块 - **每个 chunk 保留完整标题骨架**——检索到片段后一眼看出它在哪个章节下 - 表格自动重复表头、代码块保留 fence、列表按项打包 ``` 示例 chunk： ───────────────────── # 光伏产业链 ## 上游：硅料 ### 多晶硅工艺 [chunk 正文] ← 实际内容 ## 中游：硅片 ← 骨架（只有标题） ## 下游：组件 ───────────────────── ``` ## 特性3：自进化 > **ReMe 的记忆不是被动存的，是主动长成知识图谱的。** ``` 用户对话 / 外部素材 │ ├───────────────────────────────────┐ ▼ ▼ ┌────────────┐ ┌────────────┐ │ auto-memory│ │auto-resource│ │ 对话→日记 │ │ 素材→解析 │ └─────┬──────┘ └──────┬─────┘ │ │ ▼ ▼ ┌─────────────────────────────────────────────────┐ │ daily/ │ │ (事件日记 + resource 加工笔记) │ └─────────────────────┬───────────────────────────┘ │ ▼ 定时触发 ┌─────────────┐ │ auto-dream │ │ 提炼 + 建图谱 │ └──────┬──────┘ │ ▼ ┌─────────────────────────────────────────────────┐ │ digest/ │ │ (知识卡片 + wikilink 互联 = 知识图谱) │ └─────────────────────────────────────────────────┘ ``` 用户什么都不用做，Agent 在后台让笔记自己长出结构。 ### 3.1 auto-resource 监控 `resource/` 目录，新文件进来后自动解析内容、整理为结构化笔记写入 `daily/` 下。 ### 3.2 auto-memory 对话进行时，ReMe 在后台把上下文自动写入当天日记。不是简单的对话摘要——而是一个拥有完整读写能力的 LLM Agent，自己决定记什么、怎么组织、合并还是新增。 ### 3.3 auto-dream + auto-link：睡眠式记忆整理 借鉴人在睡眠中巩固记忆的机制——把日记和素材提炼成知识卡片，并自动织出图谱关系： ``` ┌───────────────────────────┐ │ daily/2026-05-28/xxx.md │ ← 一篇日记或素材 └─────────────┬─────────────┘ │ ╔═════════════════════════════════════╗ ║ Phase 1 — Extract（一个 Agent） ║ ║ "这份材料教了什么道理？" ║ ║ ║ ║ 输出 N 个抽象单元，各带 bucket 标签 ║ ║ (空 → 结束，没东西值得记) ║ ╚══════════╤══════════╤═══════════════╝ │ │ ┌─────────────┘ └──────────────┐ ▼ ▼ ╔══════════════════════════════╗ ╔══════════════════════════════╗ ║ Phase 2 — Integrate ║ ║ Phase 2 — Integrate ║ ║ (每个 unit 独立一个 Agent) ║ ║ (每个 unit 独立一个 Agent) ║ ║ ║ ║ ║ ║ 1. search + traverse 召回 ║ ║ 1. search + traverse 召回 ║ ║ 2. 决策: CREATE / UPDATE ║ ║ 2. 决策: CREATE / UPDATE ║ ║ 3. 写入 + 自动织链接 ║ ║ 3. 写入 + 自动织链接 ║ ╚══════════════╤═══════════════╝ ╚══════════════╤═══════════════╝ │ │ ▼ ▼ ┌──────────────────────────────────────────────────────────────┐ │ digest/ │ │ procedure/key-rotation.md ←─ derived_from:: [[daily/..]] │ │ wiki/credential-compliance.md ─ relates_to:: [[...]] │ │ personal/user-pr-pref.md │ └──────────────────────────────────────────────────────────────┘ 知识图谱自动生长 ``` **Phase 1 筛选**——多个事实说明同一个道理就合并为一个 unit，分到三个桶：`procedure`（怎么做）/ `personal`（用户偏好）/ `wiki` （通用知识）。没东西值得记则流程结束。 **Phase 2 先搜后写**——先搜已有 digest，再决策：新建（CREATE）、追加佐证（CORROBORATE）、补充精度（REFINE）、修正矛盾（CORRECT）。 **auto-link 是写入的副产品**——写 digest 时自动加 `derived_from:: [[素材]]` 溯源 + `relates_to::` 概念互联，图谱随每次 dream 自动变密。 **CronDreamer 定时批跑**——每天扫描当天所有 daily + resource 文件，逐个执行上述管线。 ## 特性4：混合索引 + 渐进式展开 ``` 用户提问: "宁德时代的电池技术？" │ ├──────────────────────┬──────────────────────────┐ ▼ ▼ │ ┌─────────────────┐ ┌──────────────────┐ │ │ 全文倒排索引 │ │ 向量索引 │ │ │ (numpy + jieba) │ │ (faiss) │ │ │ │ │ │ │ │ "宁德时代" 精确 │ │ "动力电池龙头" │ │ │ 命中 │ │ 语义近似命中 │ │ └────────┬────────┘ └────────┬─────────┘ │ │ text_weight=0.3 │ vector_weight=0.7 │ └──────────┬──────────┘ │ ▼ │ ┌───────────────┐ │ │ RRF 融合排序 │ │ │ score = Σ(w/(k+rank)) │ └───────┬───────┘ │ ▼ │ ┌──────────────────────────────────────┐ │ │ 第一跳：Top-K chunk 全文 + 评分 │ │ └───────────────────┬──────────────────┘ │ ▼ │ ┌──────────────────────────────────────┐ │ │ 第二跳：邻居目录（只有标题，不展开正文）│ ← wikilink 图谱 │ └───────────────────┬──────────────────┘ │ ▼ │ ┌──────────────────────────────────────┐ │ │ 第 N 跳：Agent 按需追问，展开正文 │ │ └──────────────────────────────────────┘ │ ``` ### 4.1 混合索引构建 两套索引并行维护，各擅其长： - **全文倒排索引**（基于numpy）——精确匹配专有名词，搜"宁德时代"必须命中。支持增量更新索引，无原生扩展依赖。 - **向量索引**（基于faiss）——语义相似度，搜"锂电正极原料"能命中"钴"。 ### 4.2 基于 RRF 的混合检索 两条通路并行跑（`asyncio.gather`），用 RRF（Reciprocal Rank Fusion）融合排序： ``` 融合分 = Σ( weight_i / (k + rank_i) ) k=60, vector_weight=0.7, text_weight=0.3 ``` 为什么要两路？纯向量容易错配名词（"苹果公司"≈"水果"），纯关键词抓不到同义改写——融合互补盲区。 ### 4.3 渐进式链接展开 传统 RAG 一次性把 Top-K 全塞进上下文，token 浪费且噪音多。ReMe 分跳展开，按需深入： **第一跳** — 返回命中 chunk 全文 + 分数明细 **第二跳** — 展开 wikilink 邻居的"目录"（只有标题，不展开正文）： ``` ========== digest/wiki/宁德时代.md:5-22 [score=0.0247 vector=0.0156 keyword=0.0091] ========== # 宁德时代 全球动力电池出货量第一，核心技术为 CTP（Cell to Pack）和钠离子电池…… outlinks (2): → digest/wiki/磷酸铁锂.md name="磷酸铁锂正极路线" description="磷酸铁锂与三元路线对比" via predicate=相关技术 → digest/wiki/固态电池.md name="固态电池技术路线" description="全固态与半固态进展" via predicate=技术演进 inlinks (2): ← daily/2026-03-18/宁德调研.md name="宁德时代调研纪要" description="2026Q1产能与订单跟踪" via plain ← digest/wiki/新能源产业链.md name="新能源产业链全景" description="从锂矿到整车的全链条" via predicate=下游应用 ``` **第 N 跳** — Agent 看过"目录"后，自己决定哪些邻居值得深入，再发起 read 拿正文。 二跳目录每条只占一行（最多 10 outlink + 10 inlink），Agent 拥有全局视野却不撑爆上下文。 ## 特性5：多 Agent 框架集成 ReMe 不做独立 Agent 产品，而是作为**能力层**被任意框架调用： | 集成路径 | 适用对象 | 方式 | |---------------------|----------------------|---------------------------------------------| | SDK 深度集成 | AgentScope / Qwenpaw | middleware 注册 tools + prompt，hook 注册 auto-* | | MCP Tool + skill.md | Claude Code | MCP 注册 Tool，配 skill.md 开箱即用，hook 注册 auto-* | | HTTP API + CLI | 通用方案 | skill.md + CLI 调用 | --- # 二、工程架构 ``` ┌─────────────────────────────────────────────────────────────────┐ │ Service 层（HTTP / MCP 双协议） │ │ FastAPI + FastMCP，同一套 Job 同时暴露为 REST 和 MCP Tool │ ├─────────────────────────────────────────────────────────────────┤ │ Application 层 │ │ 配置加载 → 组件初始化 → Job 注册 → start() / close() 生命周期 │ ├─────────────────────────────────────────────────────────────────┤ │ Job 层（编排） │ │ 每个 Job = 一组 Step 的有序管线，YAML 声明式配置 │ ├─────────────────────────────────────────────────────────────────┤ │ Step 层（业务逻辑） │ │ 原子操作单元，按功能域分组：file_io / index / evolve / common │ ├─────────────────────────────────────────────────────────────────┤ │ Component 层（可插拔基础设施） │ │ 统一注册表 R，一行配置切换实现 │ │ file_store / embedding / keyword_index / llm / file_graph │ └─────────────────────────────────────────────────────────────────┘ ``` ## 2.1 服务层 每个 Job 同时暴露为两种协议，写一次逻辑、两种方式调用： | 协议 | 传输方式 | 适用场景 | |---------------|-------------------------------|------------------------------| | HTTP（FastAPI） | JSON POST / SSE | REST 调用、Web 前端 | | MCP（FastMCP） | stdio / SSE / streamable-http | Claude Code、Cursor 等 MCP 客户端 | - **按需拉起**：Agent 检测到服务未运行时自动后台启动，用户无感知 - **服务发现**：通过 `REME_SERVICE_INFO` 环境变量广播地址，`find_reme` 一键探活 ## 2.2 组件系统（Component） 统一注册表 `R`，所有基础设施都是可插拔的——改一行配置就能切换后端： | 组件 | 干什么 | 可选后端 | |-----------------|---------------|-----------------------| | file_store | 文件存储 + 索引协调 | local | | file_graph | wikilink 双向图谱 | local / nx / neo4j | | keyword_index | 全文倒排索引 | bm25（numpy + jieba） | | embedding_store | 向量存储与检索 | local（faiss） | | embedding | 文本转向量 | openai 兼容接口 | | llm | 大模型调用 | anthropic / openai 兼容 | | tokenizer | 分词 | regex / jieba | ## 2.3 Job 列表 **Job** 是 ReMe 暴露给外部的操作单元——同一个 Job 可以作为 Python 函数直接调用、作为 MCP Tool 被 Agent 使用、也可以作为 CLI 命令执行。 | 类别 | Job | 功能 | |------|---------------------------|----------------------------------| | 检索 | `search` | 混合检索（向量 + BM25 + RRF）+ 渐进式图展开 | | 检索 | `traverse` | 从指定路径遍历 wikilink 图谱 | | 文件读写 | `read` | 读取 markdown 文件内容 | | 文件读写 | `read_image` | 读取图片文件（base64） | | 文件读写 | `write` | 新建或覆写 markdown 文件（含 frontmatter） | | 文件读写 | `edit` | 文件内查找替换 | | 文件读写 | `delete` | 删除文件，返回残留入边 | | 文件读写 | `move` | 移动 / 重命名，自动重写 wikilink | | 文件读写 | `list` | 列出目录下文件 | | 文件读写 | `stat` | 文件元信息（大小、修改时间） | | 文件读写 | `frontmatter_read` | 读取 frontmatter | | 文件读写 | `frontmatter_update` | 合并更新 frontmatter | | 文件读写 | `frontmatter_delete` | 删除 frontmatter 字段 | | 日记管理 | `daily_create` | 幂等创建当天日记文件 | | 日记管理 | `daily_list` | 列出某天的所有日记 | | 日记管理 | `daily_reindex` | 重建当天索引页 | | 索引维护 | `reindex` | 清空并全量重建索引 | | 索引维护 | `update_store_index_loop` | 后台监听文件变更，增量更新 | | 自进化 | `auto_memory` | 对话记录写入日记（LLM Agent） | | 自进化 | `dream` | 单文件记忆提炼到 digest（LLM Agent） | | 自进化 | `auto-dream` | 批量扫描当天文件，逐个 dream | | 系统 | `health_check` | 组件健康检查 | | 系统 | `version` | 返回版本号 | | 系统 | `help` | 列出所有已注册 Job |