Loong Recall (LRC)

给 AI 装上记忆的本地服务 —— 跨会话记住你的代码与决策，并在记忆之间建立「相似度给不出」的关联。

---

它是什么，与普通向量检索差在哪

市面上的记忆方案（RAG / 向量库）几乎都是相似度检索：把你的问题编码成向量，找出"语义最像"的几条记录。

这在很多时候够用，但有一类需求它天然做不到。举例：你记过「游西湖」，也记过「在楼外楼吃饭」。这两句话没有一个共同词，语义也不相似——任何相似度算法都不会把它们关联起来。但你知道它们相关，因为那是同一次杭州之行。

LRC 在相似度之外，额外建立了一层由记录字段必然推导出的关联：

但这里有一个必须说清的前提：关联是「原料驱动」的。 你库里没有记忆、或记忆之间没写关联字段，算法再强也无从推导——这是实测结论，不是托辞。详见 原料瓶颈与当前边界。

---

工作原理

1. 检索怎么走（三条通路）

三条通路都是相似度驱动的，排序质量有 A/B 证据支撑，因此不会被其他通道改变。

2. 记忆怎么写

写入时可指定类型（fact / preference / decision / code_context / conversation / experience / synthesis）、重要性（1–10）与隐私级别，并支持同一批语句重复出现时自动融合为「结晶」条目（程序记忆）。

3. 联想怎么补（这是核心差异点）

检索返回后，LRC 以已召回结果为起点做一次有界的关联展开（expand_associations）：

记录层——从已有记录字段推导，必然成立：

符号层——由图结构推导的因果 / 时序 / 约束关系，可能不成立，界面单独标注「结构推导」，让用户一眼分辨可信度。

四条设计约束（每条都有明确理由）：

1. 不并入排序，单独分区返回——联想结果与相似度分数的证据性质不同，混排会让人误以为二者可比；
2. 复用检索的可见性规则（隐私 / 项目 / 类型 / 标签过滤）——否则联想就成了绕过权限的后门，这是安全红线；
3. 只对已召回的记忆展开，不扩张检索根集——保证联想与本次查询语义相关，并把成本限定在 k 次关联查询；
4. 只读检索不展开——保持"零伤害承诺"。

4. 三种用法

① 联想补全（自动）——搜索结果里，语义不相似但由记录必然关联的记忆单独分区展示，带「凭什么关联」的理由，可核验、不参与排序。

② 联想中心 · 探索（主动提问）——输入一句话，系统沿关联链逐层扩散（有界 BFS，带时间预算）：

今晚吃什么          → 想起：和谁吃 / 在哪吃 / 饮食约束 / 饭后惯例
我以前记过什么重要日子？ → 想起：结婚纪念日 / 家人生日 / 认识十周年

返回部分结果时明确告知"想得有点远，已展示完成的部分"；记忆库里确实没有相关内容时，返回诚实空态而不是硬凑答案。

③ 联想足迹——查看历史联想记录，可一键隐藏（隐藏后重启不复活，同时保持审计哈希链完整）。

5. 三层技术底座

三层在界面上分开显示，不混淆：用户能一眼看出哪条必然可信、哪条只是推测。

6. 代码搜索链路

源码 → 分块（chunker）→ 编码 → 近似最近邻索引（HNSW，M=16 / ef_search=50）→ 检索。代码索引驻留内存、不写磁盘；记忆检索与代码检索是两条相互独立的链路，互不影响。

7. 可审计性

记忆的增删改与联想足迹记录均写入防篡改哈希链（SHA256，event_hash = previous_hash + 事件内容），哈希链根另存独立封印文件 .lrc_audit_seal——即使有人改了审计日志并重算哈希链，封印文件仍能暴露篡改。隐藏某条记录不会破坏哈希链完整性。

---

能力水准

以下数据均来自仓库内可复现的基准报告，每条都注明样本规模、测试环境与版本口径。请注意各表之间样本构成不同，不可直接做数值减法。

内置基准（回归门禁）

cargo test --test benchmarks：11/11 通过，0 失败（v0.9.7，耗时 5.52s）。覆盖检索延迟、召回精度、会话召回、记忆衰减、合成触发、阴阳平衡、反污染、数据本地化、审计防篡改、隐私隔离、复杂度红线自检。

内部 A/B：ML 语义编码器 vs 统计编码器

受控条件：11 组「查询与目标记忆几乎没有共同关键词」的联想型查询；两臂各起独立空库，注入相同语料，唯一变量是编码器。

如实解读：top1 命中率提升 33%（0.273 → 0.364），且提升集中在"字面鸿沟"场景——这正是记忆联想要解决的问题域。但 top3 两臂持平（0.455），说明 ML 的优势在头部第一跳、不在扩大命中集合；反向也有 3 条统计编码器命中而 ML 未命中（查询与目标共享字面关键词时，字面匹配占优）。

生活场景联想链（联想"对不对"的人可读证据）

条件：53 条真实生活记忆组成 4 条联想链 + 8 条技术记忆 + 2 条异主题记忆作为"乱入检测器"；每条人工预标注联想层级 hop；5 个生活查询。

实际展开效果（ML 臂真实输出，查询「今晚吃什么好呢」）：

#1 [hop=1] 今晚想吃火锅，上次念叨的那家海底捞还没去   ← 直接答案
#2 [hop=3] 周末和家人在家包饺子，买了饺子皮和馅       ← 饮食场景
#6 [hop=2] 约了大学同学小美周五晚上吃饭还没定地方     ← 和谁吃
#8 [hop=3] 楼下菜场收摊前去能捡到便宜叶菜             ← 在哪吃
#9 [hop=4] 这周立flag要减脂，晚上尽量吃得清淡些       ← 饮食约束
#10[hop=5] 吃完晚饭一般会洗碗，洗碗布该换了           ← 饭后周边
→ 联想扩散 5 层（覆盖 hop 1/2/3/4/5）

外部基准：LongMemEval（ICLR 2025）

条件：LongMemEval-S 公开数据集；分层抽样覆盖全部 6 种题型、每类 5 实例，共 30 实例；3 分片并行，三片结果完全一致；deep 通路 + bge-base-zh；Top-K=10。

按题型：

量级参照（样本构成不同，仅作参照，不可直接相减）：

即：v0.9.7 的语义底座升级，首次让深度语义通路达到并超过关键词通路的历史精度。

---

原料瓶颈与当前边界

这一节是本项目的自我否证记录。我们刻意把失败项与成因写在这里——因为不写，用户就会用错误预期去评估它。

一、原料瓶颈：为什么效果要「用起来」才逐渐显现

关联是推导出来的，原料就是记忆本身以及记忆之间的关系字段。 真实库实测覆盖率：

再看结晶（记忆融合）的门槛——代码里写死需要至少 3 条相似记忆（min_cluster: 3，相似度阈值 similarity: 0.4）才会触发合成。冷启动阶段库里只有零星几条记忆时，这个能力在数学上就不会被触发。

结论（请按此建立预期）：

• 刚装好、库是空的 → 你只会看到一个诚实的空态提示，而不是硬凑的联想结果；
• 用一段时间、记够内容后 → 语义底座先发挥作用，联想质量随记忆增长而提升；
• 关联类能力的上限，取决于你写了多少带 event_id / 实体字段的记忆——这部分无法靠算法弥补。

你的记忆库里还没有和「量子物理是什么」相关的内容。
这次没有想起相关的念头——不是联想坏了，是记忆里还没有记过这类事情。

二、已实测的失败与缺陷（含成因）

三、被预注册判据否证的方向（诚实收场）

我们没有把"没验证过的设计"包装成卖点。道体（符号层）参与检索排序这条路线，用先写死判据、再跑数据的方式做了完整检验：

三个干预点（前 / 中 / 后）全部实测证伪，根本结论比"信号不够好"更深一层："检索方向信号 ≠ 检索召回增益"——hop3-5 的正确答案与查询语义高度相关，BGE 单查询已能覆盖大半，任何"另辟方向"的视图扩展捞回的多是干扰候选。

因此：道体不参与产品的检索与排序决策。记忆联想的实际召回能力由 BGE 语义底座 + 记录层确定性逻辑兑现。符号层保留为架构能力（默认关闭、零影响），启用与否属产品信念范畴，不再作为效果主张。

四、尚未验证的部分（主动声明）

1. 同一样本上的 stat-deep A/B 未做：ML-deep 的 0.90 严格对照应是"同样 30 实例喂统计编码器 deep"，但注入成本约 5.8 小时，本轮未跑。表中 0% 基线来自历史 5 实例小样本，跨样本不可直接相减；ML 优于统计的同受控对比由上文"内部 A/B"（相同查询集、相同语料、仅编码器不同）严格支撑。
2. 30 实例 ≠ 全量 500 实例：分层样本对稀有题型（preference 全量仅占 6%）做了等比放大，整体数值不等同于全量加权成绩。
3. 延迟数据受环境强影响：以上结论均来自特定机器（见各报告），不应视为跨机器保证。

---

快速开始

方式一：下载桌面端（推荐）

1. 前往 v0.9.9 Releases 下载桌面安装包（注意文件名，勿下载 CLI 二进制）：
   • Windows：lrc-desktop-v0.9.9-windows-x86_64-setup.exe
   • macOS：lrc-desktop-v0.9.9-macos-arm64.dmg
   • Linux：lrc-desktop-v0.9.9-linux-amd64.deb 或 lrc-desktop-v0.9.9-linux-x86_64.AppImage
2. 双击安装，启动 LRC Desktop
3. 按向导选择项目、配置 LLM（可选）、连接 AI 工具
4. 重启 IDE，AI 通过 MCP 自动发现并使用记忆与代码搜索能力

桌面端自动完成所有配置：检测 AI 工具、写入 MCP 配置、写入 AI 规则文件。

端口说明：稳定版默认使用 3099；开发实例端口约定见上文「质量与验证」一节。稳定版不会复用开发版 Sidecar。

注意：Release 中 lrc-v0.9.9-windows-x86_64.exe 等文件是 CLI 命令行工具（Sidecar 二进制），供开发者和脚本调用，不是安装包，双击无法安装。安装请使用 lrc-desktop-* 开头的安装包。

安装包体积说明：桌面安装包仅数 MB 是设计使然——语义模型按需下载（首次约 100~400MB，自动走国内镜像），道体推演引擎为独立研究资产不随产品分发（见下方边界说明）。

方式二：从源码编译

git clone https://github.com/zhibaiYingChuan/LRC.git
cd LRC
cargo build --release --features server
./target/release/code-memory-server --src-dir ./src --port 3099

如需离线语义搜索：cargo build --release --features server,ml（首次下载模型 ~500MB）。

---

通用语义引擎

默认嵌入模型为 BGE-small-zh（中文用户开箱最优）或 MiniLM-L6-v2（英文环境），并支持本地嵌入完成记忆结晶，无需 LLM API 即可享受记忆融合能力。

模型管理 CLI：

# 列出本地已下载模型
code-memory-server model list

# 下载模型（默认使用 hf-mirror.com 国内镜像）
code-memory-server model download BAAI/bge-small-zh

# 切换默认模型
code-memory-server model use BAAI/bge-small-zh

# 删除模型文件
code-memory-server model remove BAAI/bge-small-zh

镜像源配置：

下载失败时自动重试 3 次（2s/4s/8s 指数退避），3 次均失败后输出手动下载指引并降级到 TF-IDF 模式。

推荐模型对比：

---

MCP 接入方式

LRC 通过标准 MCP 协议向 AI 工具暴露记忆与代码搜索能力，支持 stdio 与 HTTP 两种传输。桌面端会自动写入配置；从源码编译的 CLI 用户按下文手动配置。

托管部署说明：LRC 依赖本机资源（本地源码索引、~/.loong-recall/ 记忆库、本机嵌入模型），不适合远程托管部署。在 ModelScope MCP 广场等平台创建时，托管类型请选择「仅本地可用」。

方式一：stdio（CLI 二进制，标准接入）

以 stdio 传输启动，由 AI 工具将 code-memory-server 作为子进程拉起：

{
  "mcpServers": {
    "lrc-memory": {
      "command": "code-memory-server",
      "args": ["--src-dir", ".", "--stdio"],
      "env": {
        "HF_ENDPOINT": "https://hf-mirror.com",
        "LRC_MODEL_MIRROR": "hf-mirror"
      }
    }
  }
}

• command 用 code-memory-server 需先把二进制加入 PATH；否则填完整路径（Windows 为 code-memory-server.exe）。
• --src-dir . 以 AI 工具的工作目录（通常为项目根）为索引目标；如需跨项目共享记忆，改用 --global 并省略 --src-dir。
• 以上 JSON 即 ModelScope「从 GitHub 仓库快速创建」自动解析的服务配置，env 中的键值对会被平台提取为环境变量配置项。

方式二：HTTP（LRC Desktop 或常驻端口模式）

服务常驻后由 AI 工具连接。LRC Desktop 会自动启动服务，CLI 等价启动命令：

code-memory-server --src-dir ./src --port 3099

再写入客户端配置：

{
  "mcpServers": {
    "lrc-memory": {
      "type": "http",
      "url": "http://127.0.0.1:3099/mcp"
    }
  }
}

常见客户端配置位置

也可用 code-memory-server --install-ide <IDE> 自动写入，支持 trae trae-cn cursor vscode windsurf codebuddy qoder kiro 等；--list-ides 可列出全部。

环境变量

---

MCP 工具

桌面端和 CLI 通过 MCP 提供记忆、检索、代码搜索与系统管理能力。当前内置工具数量和名称以运行中的 tools/list 返回为准，避免文档与实际版本漂移。

让 AI 主动用起来

LRC 提供配套的 AI 规则文件：会话开始先 recall 检索已有上下文、遇到不确定的模块优先 recall 而非直接读源文件、完成任务后自动同步记忆。桌面端会自动写入这些规则。

写「经历」类记忆时请填 event_id：这是记录型关联的唯一依据。不填，这些记忆之间就无法互相联想——因为它们的关联依据（同一次经历）从未被记录，事后无法补。

---

质量与验证

LRC 的核心功能通过 Rust 单元测试、集成测试、前端契约检查和桌面端 CDP 回归门禁持续验证（当前：cargo test --features server 790 passed / 0 failed；desktop crate 96 passed / 0 failed；clippy 干净；算法泄露检测通过）。

启用提交前检查（推荐）：仓库自带版本控制的 Git 钩子，克隆后执行一次即可启用（提交前自动跑 fmt / clippy / check / test / 算法泄露检测 5 项检查）：

.\scripts\enable_git_hooks.ps1          # 等价于 git config --local core.hooksPath .githooks
git config --local --unset core.hooksPath   # 需要撤销时

性能数据会随版本、硬件和配置变化，发布前以当前版本的 CI 结果为准。

本地开发链路（桌面端 CDP 调试 / 双实例隔离）：以下脚本随仓库交付，供本地开发与 CDP 回归测试使用（非生产运行时依赖）：

python .\scripts\dev-proxy.py 1420 --dev   # 开发代理：服务磁盘最新 static/（禁用 WebView2 缓存），API 代理到 sidecar
.\scripts\run-dev.ps1                      # 开发版实例：端口 3100 + 独立数据目录，不影响稳定版 3099
.\scripts\run-dev.ps1 -Build               # 先编译再启动

端口约定：稳定版 3099；run-dev.ps1 开发实例 3100；--dev 模式锁定 3111。三者数据目录相互隔离。

tests/frontend/ 下的 CDP 测试优先经 localhost:1420 验证磁盘最新前端；dev-proxy 未启动时自动回退原地重载并告警。

---

版本特性（v0.9.9）

本版本主题：交互可用性修复 + ML 模式联想超时根因 + 符号层证据性质分离。

• 修复「每次打开都要手动点启动服务」：自动启动判据原为 setup_complete（是否走过向导），而正常使用不需要走向导（全局模式不选项目目录、不用 LLM）⇒ 该判据永远为 false，自动启动被永久跳过。改为按「是否确有使用痕迹」判定后，实测多次重开全部自动拉起。
• 符号层接入界面（证据性质分离）：联想的两类证据分开显示，不再混淆——「记录关联」（记录必成立）与「结构推导」（由结构算子推出，可能不成立）。后者带独立徽章，用户一眼可辨可信度。
• 修复联想探索超时阶梯：前端超时原与后端完全相等，导致后端的优雅收敛（返回部分结果 / 诚实空态）不可达、只能报超时。现改为单调阶梯，慢环境下也能拿到"已展示完成的部分"或"记忆库里还没有相关内容"。
• 修复 ML 模式下开发端联想超时：Cargo 默认对 dev profile 的依赖不做优化，ML 张量前向慢 2~4 倍而击穿超时。现只优化 ML 链路依赖（含易漏的 gemm 矩阵乘法后端），使 debug 与 release 行为一致——线上 CI 只需多编 13 个包。
• 修复 action_hints 语义反转：健康提示原会把「系统输出质量良好」升级成「请优先处理」；现只升级真正的 warning。

v0.9.8 及更早版本特性见 CHANGELOG.md；v0.9.7 联想能力的完整验证（含全部反例与边界）见 基准测试报告。

道体（Daoti）边界：LRC 本身即从道体体系延伸而来。符号层的推理与状态机依赖道体代码参与编译，因此 src/engine/ 下的道体模块（洛书编码、镜像梯形、结构调整器、导航等）会随安装包分发——这是功能必需，否则符号层无法工作。

• 公开仓库：道体源码与产品同源公开（src/engine/），无隐藏实现；
• 许可边界：这些文件适用 DaoTi Research License（非 Apache 2.0），明确禁止逆向工程、商业嵌入与算法原理重建（LICENSE §1.2）；二进制产物同样受该协议约束（LICENSE §2.2）；
• 独立研究资产：daoti_daemon / daoti_assoc 等推演服务为独立进程，LRC 仅通过 HTTP 消费其 JSON 信号（默认关闭、离线静默降级），其内部算法（结构算子、卦映射、调度）不在本仓库、不随包分发；
• 产品决策：道体不参与产品检索与排序决策——预注册判据实测无净增量，详见 原料瓶颈与当前边界。

---

隐私

LRC 是纯本地工具。你的代码和记忆永远不会主动离开你的机器。

• 不收集遥测、不埋点、不上报
• 源代码索引驻留内存，不写磁盘
• 记忆数据存储在 ~/.loong-recall/ 本地目录
• 联想只在本机进行；联想过程记录仅存于 ~/.loong-recall/
• 仅当你配置 --llm-api 时，查询文本（非源代码）会发送到你的 LLM API

---

文档导航

---

License

• 代码部分：Apache 2.0
• 检索引擎：DaoTi Research License