无损长程记忆 QiuXu-Tech/memex

Memex —— 给 AI 智能体补上额外上下文的一层

一层高性能的额外上下文，夹在智能体的历史记录与模型窗口之间。 Memex 把上下文当作分层结构：符合条件的较早文本片段可以挪进粘性的 L2/L3 归档，容量靠冷层和有界批量摘要来管理，模型则能用混合检索取回匹配的记录。捕获、检索和窗口选择并不保证每条相关事实都被包含进来。

是上下文，不只是记忆。 DSH 能归档符合条件的文本片段，并保留压缩源事件信封。选中的记录可以在上下文预算内分页取回；被引用的外部附件字节不保证被捕获。读一读这个概念：额外上下文，不只是记忆。下一步方向：上下文物化 —— 精确的窗口物化，以及 transformer 上下文专家变体。已实现：规范事件、物化的常驻窗口（仓库检查点里可选；宿主配置档可以开启）、训练好的 transformer 编码器参考实现、可运行的 paged-KV/前缀宿主、结构保真度评测。A 路线已在 GPU 上验证： vLLM 0.10.2 + Qwen2.5-0.5B 借助原生 paged-KV 前缀缓存复用了 2,498 token 的稳定前缀（第二次请求前缀命中率 99.2%）。另一次 KV 张量探针在 CPU↔GPU 之间分页了 720 个块，精确重建了缓存（分页与直连的 logit 差为 0.0）。现在有自定义 vLLM KV 连接器把物化前缀存到外部；在 0.5B、Qwen2.5-3B 和真实 Qwen2.5-7B-AWQ 上，第二次请求 8/8 命中（36 层，420MB KV，GPU 利用率 91%；稳定存储 0.147s → 命中 0.094s）。端到端：一个真实的物化器窗口经连接器存储，第二次请求即命中（1,488 个 KV token，命中耗时 0.018s）。

它最初是 DeepSeek Harness 插件，现在不绑定任何智能体：

| 智能体 | 集成方式 |
| DeepSeek Harness | 原生 Cordis 包（L1 驱逐接缝、Web 面板、9 条 HTTP 路由、四个核心记忆工具） |
| Claude Code | MCP 服务器 + SessionStart / UserPromptSubmit / PreCompact 钩子 + CLAUDE.md 手册 |
| OpenAI Codex | MCP 服务器 + AGENTS.md 手册 + config.toml 片段 |
| Gemini CLI、Cursor、Cline、Windsurf、Zed、… | 一个 stdio MCP 服务器（packages/memex-mcp），4 个默认工具，可选高级工具 + 目录资源 |
| 任何 HTTP 智能体 | 同一套核心可以嵌入（@qiuxu/memex-core） |
状态：0.65.0（Memex），main 分支上还有未发布的修复 —— 与智能体无关的核心、MCP 服务器、热体救援、Claude Code/Codex 适配器、21 个模型配置档（13 个家族基座 + 专用 GPT-6.1 Sol/Terra/GPT-6 Astra、Claude Opus 5.5/Sonnet 5.5/Fable 5.1/Haiku 5.5、DeepSeek Flash 变体）、196/196 离线测试、38/38 SQLite 一致性测试、50/50 完整性与隔离测试，以及在 Blackwell GPU 上完成的 vLLM 分页 KV 前缀缓存验证。DSH 模式使用 DSH 0.2.1-rc.3；其他情况可用任何支持 MCP 的智能体。Memex 把记录存在本地，不上报任何遥测数据；智能体可能把召回的内容发给它的模型服务商。

归档与隐私修复： 压缩记录、规范事件和完成标记现在一起提交；不完整的来源仍可重试。Claude 转录副本拆成不可信、会话私有的部分，适配器层级的限制不再继承此前启用的共享范围。被取代和已过期的记录不再出现在常规召回中；新的物化器追踪只记录元数据，不记录全文。完整备份需要同时包含记录文件和对应的 SQLite 数据库。行为与剩余限制。

任务状态跟进（2026-11-02）： 记忆记录可以携带调用方声明的来源、版本、观察时间和过期时间；常规召回会隐藏被取代或明确过期的条目。在另一次单独登记的 30 问题、三会话历史回放中，28 对任务完成。最初的盲评只评了 13 个；对 15 个缺失评分单独登记补充评审后，对照组在 4 个上得分更高，20 个打平，Memex 在 4 个上得分更高。28 个最终答案中有 8 个明确引用了后来才打开的更早记录。之后在修复后的桥上又做了 4 问题跟进，已完成并评为 4/4，其中对照组高 1 个、两个打平、Memex 高 1 个。两组用的提交不同，必须分开解读。这些是 AI 评审的历史分诊回放，不能证明生产环境的正确性提升或成本节省。结果、用法与限制。

三会话问题回放结果与观察到的记忆活动

完整性跟进（2026-11-02）： 在另一次 25 问题的长讨论回放中，22 对完成，21 个有有效的最终 AI 评分：对照组在 3 个上得分更高，15 个打平，Memex 在 3 个上得分更高。SQLite 权限修复后只又跑了 4 个问题。这些是压缩过的历史分诊回放，不能证明生产环境的正确性或成本收益。结果、成本、图表与限制。

7B KV 策略对比（最新）

同一个真实 Qwen2.5-7B-AWQ 模型，8 个前缀 ×2 次请求（1,856 token 前缀），RTX PRO 6000 96GB：

| 策略 | 第一次请求 | 第二次请求 | 备注 |
| 无缓存 | 0.0907s | 0.0924s | 重算前缀 |
| 原生 vLLM 前缀缓存 | 0.0922s | 0.0187s | 最快的热路径 |
| Memex 外部 KV | 0.1468s | 0.0583s | 8/8 外部命中，654MiB 磁盘，约 91% GPU |

要点：

- 第二次请求时，原生 GPU 前缀缓存比外部磁盘 KV 快约 3 倍。
- 外部 KV 仍快于重算（约快 37%），并且带来持久化、租户隔离和跨重启复用。
- 首次走外部存储的请求开销明显；gzip 会让命中延迟变差。
- 下一步：混合路由（原生热缓存 + 外部冷缓存）、异步/固定 KV 加载、前缀长度交叉点调优，以及降低 GPU KV 预留以释放内存。

原始数据：docs/assets/benchmarks/kv-strategy-comparison.json。

历史 GPU 连接器实验与 DSH 集成

- 真实 7B-AWQ + 外部连接器：吞吐饱和在约 19 rps；单并发 p50 75.6ms，32 并发 1637ms（单进程）。
- 早前有个 DSH 配置档配了 local-memex 服务商，后端是经 SSH 隧道接入的连接器 vLLM；本次复测未验证当前运行时状态。
- 真实轨迹编码器：预训练 BGE-small 把真实档案排序从 0.518 提升到 0.593（仍受小语料限制）。

六项 KV 优化（v0.31.0）

- 原生优先的混合路由：热前缀留在原生前缀缓存；外部 KV 只服务冷前缀/未缓存前缀。
- 前缀阈值（min_prefix_tokens）、并行批量层加载、仅冷路径 gzip。
- 低 GPU 预留测试：50,103/97,887 MiB，外部冷 KV 仍可用。
- 交叉点证据：512/1024/1856 token 前缀原生约 0.013–0.020s；2,800 token 冷前缀走外部 0.363s，之后原生 0.024s。

前缀长度交叉点（v0.32.0）

真实 7B-AWQ，唯一前缀，50% GPU 预留：每个长度上原生前缀缓存都最快（第二次请求 0.0175–0.0249s）。2,833 token 时外部 KV 快于重算（0.102s 对 0.139s），但要付首次存储开销；混合模式下短前缀走原生约 0.017–0.022s。

学习式真实轨迹交叉编码器（v0.34.0）

在真实档案切分上微调 BGE-small 交叉编码器：0.963 样本准确率 / 成对排序（双编码器为 0.593），但切分规模小、记录有重叠、查询是模板化的。关键下一步：记录不重叠的真实查询评测，以及查询感知 materializer 集成。

学习式 materializer 原型（v0.35.0）

真实档案切分上，查询感知 BGE 交叉编码器选择器对比现有规则 materializer（27 个验证组，500 token 预算）：

- 规则 materializer 正例召回 0.519（平均 327 token）
- 学习式选择器 0.963（平均 388 token），GPU 上 8.64ms/查询

注意：查询是模板化的，切分中记录有重叠；这不代表生产环境泛化能力，也尚未集成进 JS/DSH。

真实查询泛化：负面结果（v0.36.0）

真实 DSH 会话查询，记录互斥验证（4 个验证组）：规则物化器召回 0.50；学习型交叉编码器 0.25；零样本 BGE 0.25。早先模板化的 0.963 偏乐观；学习型物化器尚未达到生产可用。

规则 + 学习型混合物化器（v0.37.0）

在真实会话查询验证上，规则召回 0.222 → 学习型 top-1 0.500 → 规则 ∪ 学习型 0.667。在小型人工真实查询集上：0.500 → 0.750。单独用学习型不稳定；混合方案保留规则作安全网，再补上学习型候选。

JS 混合物化器钩子（v0.38.0）

可选的 query + learnedRerank 会给物化窗口补一个学习型候选。真实会话查询验证：500 token 时规则 0.222 → 混合 0.333；1,000 时 0.722 → 0.833；1,500–2,400 时 0.778 → 0.889。当时默认规则路径未改动。

长程 memex A/B（v0.44.0）

合成 60 决策归档，10 个被逐出事实探针，两个真实 API 模型：基线近期尾部 0/10，memex 物化归档 10/10，同尺寸诱饵归档 0/10。增益与内容相关，不只是多了 token。成本：+2.3k/+3.6k 提示词 token。

跨会话跟进（2026-11-02；运行已结束；缺口与事后复核见下）： 真实公开 issue 在两个分别注册、随机化的 Claude Code 队列中回放。截至本快照，10/30 原始配对与 30/30 恢复协议配对完成了两个会话。在补充的主 AI 评分（28 对）中，对照组得分更高 12 对，持平 16 对，Memex 得分更高 0 对。这些是 AI 评估的历史分诊回放，不是线上生产正确性或节省成本的证据。自动写入与智能体发起的写入、失败与缺失用量另行报告。结果与局限。

跨会话 issue 回放进度

前瞻性工程金丝雀（2026-10-31）

三会话问题复现（2026-11-01）： 对上一项研究的分析发现，28/28 个处理组首次会话搜索的都是空存储。MCP 现在能区分空归档与搜索未命中，不再建议多余的兜底调用。三个新的公开 issue 编码复现中，会话中断后完整原始 Codex 配对为 0/3。另有一个单独登记的 Claude 续跑，复用了其中一个 issue，写入并随后打开了一条记忆，但它的候选补丁没能通过一项额外继承的 setter 回归测试，尽管原始固定检查都通过了。AI 评审对候选补丁意见不一致；裁决者给对照组/Memex 打分 2/1。第四个新的 Chalk issue 起初在两个实验组都超时。同一 issue 上另有一次单独登记、超时更长的重试，每组完成 3/3 个会话，双方都通过冻结检查；Memex 没有写入记忆，输入 token 多用了 18.7%，不过这次单次重试中它的账户窗口求解器计费候选更低。事后复现一条已有上游断言时，两个补丁都失败了，两份最终解释都给出了不准确的下划线颜色说法，而按冻结标准打分的 AI 没有标记出来。Claude 和 Qwen 的评审失败被保留；GPT 和事后 DeepSeek 都给 2/2，Gemini 裁决者也是如此。互相矛盾的模型专属搜索/打开提示已与共享手册对齐，指引现在会标注未经验证的假设。这些历史复现不能证明生产环境的正确性或节省效果。方法、失败、成本与结果。

智能体复现覆盖率、先前 token 用量与一项补充兼容性检查

事后 Chalk 重试：会话完成度、token 用量、盲评分数与遗留断言

修复后 30 issue 研究（含事后重试完成）： 30 次原始公开 issue 尝试中，28 次完成了两个会话的 Codex 实验组；25/30 有两份盲评 AI 评分和无需恢复的裁决，另有 3 份补充裁决。30/30 个不同任务都有可评估配对，含事后重试。3 条裁决理由被标记。这些是历史源码调查，没有项目验收测试；完整成本与生产影响仍未知。结果、用量与限制。

30 issue 研究的覆盖率、AI 评审与配对 token 用量

在事后敏感性视图中，AI 裁决在 27 个任务上持平，Memex 更高为 0，对照组更高为 3。28 个完整原始配对报告对照组 8.59M、Memex 12.04M 输入 token，含缓存。
预览机制金丝雀检查： 在两对复用、带记忆提示的 Codex 组合中，新选项用了两次搜索、零次打开，对照组用了两次搜索、两次打开；报告输入低 26.6%。每对的两个回答都拿到两位 AI 评审和裁决者的 2/2。这只是一次小规模机制检查，不能作为生产环境节省成本的证据。

可执行真实智能体后续实验（2026-11-01）： 又跑了两个已登记的公开 issue 影子任务，每个实验组用三个全新 Codex 会话。两组都通过了原始 issue 检查；在一项相关的额外 Happy DOM 检查上，对照组通过，Memex 失败。两个 Memex 组里，智能体都先写入、之后打开并引用了同一条记录，同时也能访问普通交接材料。这两次试验中 Memex 组报告的输入 token 更多；缓存输入和未知的订阅费用让人无法得出节省成本的结论。原始队列至此完成 6/30 对配对调查，一个中断，23 个未开始。修复了两个 memory_grep 缺陷并做了回归测试。这些是历史回放，只有 AI 评审；其中一个任务用了模拟的 ML 依赖。结果、用量、修复与局限。

两个配对任务的可执行检查与报告输入

更早的独立 issue 检查点（2026-11-01）： 来自不同仓库和不同所有者的三十个公开 issue 调查已冻结源码快照和判定标准。到这个检查点，4/30 完成了随机化的三会话 Codex 实验组；一个中断，25 个未开始。四个 Memex 组都做了搜索，但都没写入记录；前两个遇到 memory_grep 缺陷，修复后另外两个才运行。这些是源码调查，只有 AI 评审，没有项目专属的可执行验收测试。另有一项 Krkn 编码金丝雀检查，两组都通过了冻结的模拟沙箱测试，有一条 Memex 记录跨会话写入、打开并被引用；归档访问存在重叠，所以无法判断它是否必要。十四行匹配的网关评审合计候选成本 $0.062814；Codex 订阅及其他费用仍然未知。结果、任务登记、评审分歧与局限。

更早检查点：30 个已登记公开 issue 调查真实智能体后续验证（2026-11-01）： 隔离仓库和测试 worker 现在可以通过 MCP 提供给真实的 Codex 和 Claude Code 客户端使用。在两对相关的 Codex 任务中，4/4 个候选通过了冻结测试；两个审计候选也都没能通过原始未适配的测试夹具，该夹具已为集成做了更新。在另一个单独注册、自适应的第三次会话中，Codex 按标准 Memex 手册搜索、打开并引用了它在上一进程中写入的一条记录。两次 AI 审计在轨迹保真度和引用使用上结论一致，但在必要性上存在分歧；裁定后的必要性为未知。更早一次运行因连接器意外加载而中断，结果予以保留。Codex 报告的使用量与订阅费用缺口、AI 评审分歧，以及 $0.010644 的候选 APIMaster 小计，都记录在报告中。这既不是一项已完成的独立生产研究，也不代表已经证明的成本节省。智能体配置。

真实智能体配对测试与观察到的跨会话记忆生命周期

双任务影子后续验证（2026-11-01）： 一个隔离的 Memex 维护任务和一个公开的 Axios issue，分别在有 Memex 和无 Memex 的条件下各试了一次。最初四次尝试完成了 0/4 项请求的修改。一次自适应重试完成了四项修改，但两个 Memex 候选都没能通过冻结的排序测试；Axios 候选得到的 AI 评估部分成立或彼此冲突，仍待验证。之后又做了一次仅针对 Memex 的重复，带沙箱测试工具，两组都通过了冻结检查，但两个候选都没能通过因 AI 评审分歧而追加的检查。再往后一次全新会话没有使用可用的记忆工具。一名调查者修复了审计校验器的缺陷并补充了测试。在所有尝试与评审中，124 次成功请求对应候选小计 $0.065068；11 次失败的 503 尝试和非模型费用仍属未知开销。这些重复的影子任务并不能算作完成了 30–50 个任务的生产研究。结果、评审、计费与局限。

同样两个影子任务的初次与重试结果

集成就绪后续验证（2026-11-01，未发布）： MCP 记录操作现在遵循工作区和会话可见性，默认 L2 会话不再跨 MCP 进程，新的全局 Codex 配置不再固定 setup 项目，长单行正文可以续行。四项合成 Codex 检查保留了一次被拒绝的写入和一个无效夹具；修正后的读取确认了项目范围，一个脚本化的写入—搜索—打开循环在临时可写工作区中运行成功，并由新的 MCP 进程读回。这不是生产 A/B 测试，也不能证明记忆管理已实现自主。修复、检查、用量与局限。
四项合成的 Codex 集成检查，包括被拒绝的写入和无效的测试样本

早前 API 智能体后续实验（独立队列）： 30 组不同的公开 issue 配对已完成随机分组的两组实验，每组各有两份格式有效的 AI 评分，并完成了必要的格式有效分歧裁定。这合并了 18 个早前 issue 和 12 个新增后续 issue，包含单独登记的事后评分与裁定，并排除了两个无历史对照组。在这些选定的配对中，已解决的 AI 正确性得分有 25 组持平，Memex 在其中三组更高，关键词检索在其中两组更高。自适应批次、共享项目、公开解答暴露以及纯 AI 评判，使得我们无法宣称独立的生产改进、成本节省或自主记忆管理。结果、方法与局限。

新增后续实验登记了 20 个不同 issue；40 个合并实验组槽位中有 24 个通过部分检查，五个检查结果非零，四个未完成，两个超时后状态未知，五个未启动。本次后续实验中成功的服务商记录，按模型和汇总 token 数核对为 $0.631912；两笔超时费用和全部非模型成本仍为 UNKNOWN。早前的 503 错误带有 system_cpu_overloaded，但发出该错误的上游及其 CPU 指标未经验证。网关证据与计费。

后续 issue 配对、部分检查结果与 AI 评审覆盖情况

一项预先登记、隔离运行的 canary 在一个手动选定的公开 Lodash issue 上比较了三种条件。原始补丁过滤器在测试前拒绝了全部三份输出；修正后统一执行的事后检查让 3/3 未改动的候选通过。两位盲审 AI 评审员在正确性上一致，但在副作用安全性上于 3/3 配对评分中意见分歧。这只是一次范围很窄的流程检查，不能证明生产改进或自主记忆管理；原计划的 30–50 任务研究仍未完成。
在最初的工程金丝雀测试和更早的几批独立埋点之后，又追加了 30 个开源 issue，每个 issue 都配有检查项，并在调用前登记了随机配对顺序。两组都已完成，并通过了 21/30 个 issue 的部分检查，其中两个是明确标记的无历史对照组。只有 16/30 拿到了完整的最终响应，且每组各有两条格式有效的原始 AI 评分；剔除两个无历史对照组后剩 14 个。把单独登记的补充评分也算进来，是 20/30；不算这两个对照组则是 18 个，且不要求有效的裁决。在 41 个有两条有效原始评分的候选里，28 个出现分数分歧，其中 19 个的原始裁决无效。单独登记的事后复核和失败记录都保留在台账里。这些自适应、相互关联的批次，加上简短的公开 issue 讨论，不构成一项已完成的独立生产研究；它们无法证明生产环境有收益、有节省，也无法证明能自主管理记忆。结果、登记与局限。

在新的网关工作中，637 个请求在数据可得的情况下报告了 5,389,529 输入 / 160,684 输出 token。成功的服务商记录与候选小计 $1.229982 一致；四个失败请求没有用量数据，最终费用为 UNKNOWN。八次 Qwen 评审报告的输出 token 用量超出请求上限，网关是否强制执行尚未验证。记录的自动重试只针对明确的 503 响应，并用 mock 测试过；新试验中没有出现真实的 503，但确实发生了超时和一次传输错误。计费证据与缺口。

按独立登记划分的真实 issue 智能体埋点结果

按检索组和部分检查结果划分的新 issue 配对

回顾性试点跟进（2026-10-31）

一次跟进修复了试点测试框架中有界答案续写的问题，并在非盲审计中把历史来源 ID 与观测到的记忆 ID 分开。来自六个相关会话的十二个历史问题，在五种随机条件下重放。第一批在网关中断期间出现 32 个不完整答案；单独登记的中断后复现完成了 60/60 个答案，其中 6 个在触及输出上限后继续生成。这是重放，不是对原始任务的已验证完成。
复现中，24/24 次非盲 AI 自主性审计通过了当时现行的引用与 schema 检查，而模型对记忆保真度的看法出现分歧。后来更严格的「先写后用」检查尚未应用于这些历史评分。盲审答案评审在 92/120 次调用中有效；Astra 返回 27 个 HTTP 403 错误，两位评审在 15/29 条可比较的非空正确性评分上达成一致。两个队列与连通性探测共产生 728 次记录调用，报告 4,410,105 个提示词 token / 316,373 个补全 token；77 次调用缺少提示词/补全用量，实际费用仍为 UNKNOWN。结果不能证明生产准确率、成本节省或可靠的自主记忆。结果、方法、失败证据与完整成本缺口。

回顾性后续任务的用量与观察到的记忆操作

更早的扩展回顾性验证试点（2026-10-31）

对来自三个相关会话的九个历史问题做预注册的五条件重放，产出 41/45 个完整答案和四个截断答案。工具预算耗尽后，试点框架在 8/9 个受影响的答案阶段产出了完整兜底答案。在九次启用写入的运行中，智能体有八次在提问之前写入，三次搜索、打开并引用了自己先前的写入。这些是重放观察，不是经过验证的生产成功，也不能证明记忆管理忠实可靠。

两位盲审 AI 评审给出 79/82 条格式与来源 ID 均有效的评分；DeepSeek 在关闭思考模式后返回 41/41 条有效评分。在双方都给出非空评分的 36 个答案中，他们的正确性评分在 17 个上一致。另行计划的非盲自主性审计只有 8/18 条有效结果。网关报告本次后续的试验、评审、审计与六次诊断调用共消耗 2,409,708 个提示词 token / 153,749 个补全 token；一次失败调用缺少用量，实际成本仍为 UNKNOWN。样本复用、证据截断与 AI 评审使得无法声称生产准确率提升或成本节省。方法、完整结果、账本与局限。

扩展试点报告的用量与观察到的记忆操作

更早的探索性生产验证试点（2026-10-31）

一次预注册、隔离的五条件重放使用了来自两个会话的四个真实历史问题，其中包括与 Memex 相关的工作。17/20 次运行产出了非空答案；三次达到工具轮次上限。在四次启用写入的运行中，智能体有三次在提问之前写入，一次随后搜索、打开并引用了自己的写入。这是机械观察，不是经过验证的保真度或生产成功。
用户要求用 AI 评审代替人工评审。盲评机器评审回复只有 29/51 通过格式与历史来源 ID 检查；第二个可用模型是在反复出现 DeepSeek 空响应之后事后补入的。0/1/2 评分标准和截断的证据限制了结论的解读空间。跨任务运行、盲评、事后审计和合成预检，网关共报告 1,110,947 prompt / 113,967 completion tokens；发票与总成本 UNKNOWN。这四个问题不构成生产基准，也不能证明正确率提升或成本节省。方法、结果、成本台账与局限。

试点报告的用量与观察到的记忆操作

同义词与归档摘录重测（2026-10-31）

分页器可以选择让已配置的模型生成搜索改写词（materializerQueryExpansion: true，默认关闭），也可以在构建卡片之前，从过大的归档正文中抽取与查询相关的摘录。开启该选项会把问题发给对应服务商，并增加模型延迟与成本。在 12 道手工编写问题的十种种子布局中，开启改写后，规则版命中目标事实 4/120 → 91/120，混合版 0/120 → 104/120；同样的 12 道问题在各随机种子间重复使用。有一道英文问题在所有布局中都失败。深度归档探测现在能包含其事实，但不保证完整召回。十个精确线索、1000 万分配 token 的存储，在不开改写的情况下，规则版与混合版都保持 400/400 的事实可用性；静默启动门控一项都没通过。结果、图表与局限。

一次单会话回放比较了旧规则与修复后带查询改写的规则：两轮顺序的机器评判中，18 个有效配对里有 3 个偏向旧规则，8 个偏向扩展规则，1 个平局，6 个随顺序变化；20 个配对中有 2 个因空答案被排除。合成事实可用性和单会话回放都不能确立生产准确率、成本节省或自主记忆管理。生产验证方案规定了随机对照、独立人工评审和完整成本核算。

跨种子布局的合成查询扩展诊断

历史查询感知分页器与混合排序修复（2026-10-31）

在修复提交 a0a33db中，分页器把限定范围的搜索命中加入候选集，混合排序优先保证查询词覆盖，再把学习到的分数用作平局决胜。查询感知的规则选择现在会在预算内尝试搜索命中；混合模式仍需手动开启。在 400 个成对精确线索合成的 10M 分配 token 探针上，规则事实可用率从 22/400 → 400/400，混合模式从 0/400 → 400/400。在修复后候选完全相同的情况下，混合排序消融结果为 0/400 → 400/400。十项静默启动门禁全部失败；这不构成生产环境或低负载下的性能结论。

A separate 20-question synthetic topic diagnostic found the target fact 16/16 when searchable vocabulary overlapped, but 0/4 for lexically disjoint synonym questions. The system therefore still needs broader, human-verified evaluation. Methods, raw data, replay and limitations.

In a retrospective replay of 10 questions from one real session, two-order machine judging of 20 question/model pairs favored rule in both orders for 6, hybrid for 10, tied in 1 and changed with order in 3. These are not human labels or proof of production accuracy; at that historical commit a synthetic archive card omitted a deep fact even after its record was selected; the reproduced case is fixed in the newer retest above.

Paired 10M synthetic pager results before and after repair

Historical pager body repair and 10M retest (2026-10-31)

The pager now loads stored bodies, forwards excerpt/tokenizer options and preserves source-marked excerpts. At v0.65.0 + pager fix bfeee59, two five-seed synthetic cohorts each yielded separate search hit@1 200/200. Rule/hybrid pager windows contained the target fact 12/200 / 0/200 on Node 25.9, and 10/200 / 0/200 on Node 24.21. Each cohort was deliberately split 50/50 between resident and nonresident targets; these are availability checks, not production answer accuracy. No quiet-start gate passed. Methods, raw data and limitations.

A separate retrospective replay from one real session produced 16 valid question/model answer pairs. In two-order machine judging, rule won both orders in 4 pairs, hybrid in 5, ties in 2, and the outcome changed with presentation order in 5. Four pairs were excluded for empty answers. This is not human annotation or a production benchmark; no default strategy change was made.

10M synthetic pager materializer comparison

10M-token controlled long-context experiment (2026-10-31)

Synthetic 10,000,000-token archive (2,000 records ×5,000 tokens; 50% cold), 40 probes whose facts exist only in the archive:

| condition | DeepSeek Flash | Claude Haiku | avg prompt tokens |
| recent tail only | 0/40 | 0/40 | 536 / 548 |
| memex retrieved evidence | 40/40 | 40/40 | 234 / 216 |
| same-size distractor | 0/40 | 0/40 | 234 / 216 |

- Retrieval hit@1: 40/40 = 100%, median 4.94 ms
- Store: 10M tokens written in 1.65 s; cold archive 1.32 s; DB 6.0 MB
- Wilson 95% CI for memex accuracy: 91.2–100%; baseline/distractor: 0–8.8%
- Exact FACT-id metric; synthetic, one stochastic run, 40 probes; the seed was not recorded. Full methods, limitations, and reproduction: docs/long-context-10m.md, raw aggregate: long-context-10m.json

Why

Long conversations and long-running projects hit the same wall: the native context window is finite. The usual answers are lossy — truncate, or summarize and lose the details that turn out to matter later. memex treats conversation history like a cache hierarchy instead:

| Level | What it is | Capacity | Semantics |
| L1 | The model's native context window | model window | untouched; eviction removes the oldest balanced span |
| L2 | Session-private archive | 10M tokens / session | Memex filters reads by workspace and session id |
| L3 | Workspace-shared archive | 100M tokens / cwd | Memex sessions in the same workspace can read it |

These are logical storage scopes, not operating-system security boundaries: a process with access to the database or record files can inspect them directly.

- L2 and L3 are independent, sticky switches — once enabled a level cannot be turned off (recorded context never silently disappears).
- Stored source events: DSH compaction retains captured event envelopes in SQLite alongside a rendered record, without an LLM on the critical path; rendered excerpts and referenced external files may be incomplete.
- Capacity compression on demand: when a pool is near full the model asks the user first; compression then applies a cold tier (lossless, zero-LLM) and optionally bounded map-reduce digests (batched, resumable, never one giant prompt).
- Cheap recall: hybrid keyword retrieval (FTS + card fields + bounded cold abstracts + lexical rerank), ~1–5 ms on realistic archives, tens of tokens per hit.
- Model-specific adaptation: profiles tuned per model family — context window, chars/token ratio, injection format (XML/Markdown/plain), catalog/recall budgets, digest prompt style, bilingual CJK guidance and retrieval rerank weights (title/tags/summary/useWhen/abstract/body/recency/bm25) passed into hybrid search. 13 family bases plus dedicated GPT-6.1 Sol / Claude Opus 5.5 / Claude Sonnet 5.5 / DeepSeek Flash profiles with vendor-current context limits and reasoning-mode guidance. See docs/model-profiles.md and the cold-start + long-horizon profile validation.
- Hot-body rescue: identifier-like body tokens are indexed (record_terms) so facts that never made it into a title/summary are still found when card matches fill the limit; a body rerank weight ranks them. On the controlled fixture this took hot-body hit@1/@5 from 0%/0% to 100%/100%.

Features

- Agent-agnostic core (@qiuxu/memex-core): markdown + SQLite store, hot/cold tiers, hybrid retrieval and capacity compression with zero host dependencies. DSH, MCP and CLI adapters share one record vocabulary.
- MCP server (@qiuxu/memex-mcp): stdio JSON-RPC, 4 default tools (memory_search/open/write/set_status); --all-tools advertises 6 additional maintenance tools. The memory://catalog resource and model-tailored instructions remain available.
- Claude Code adapter (@qiuxu/memex-claude): one command registers MCP, merges .claude/settings.json hooks and injects a model-tailored CLAUDE.md manual; PreCompact copies the transcript into session-private parts when L2 is enabled, Stop saves completed assistant responses as untrusted checkpoints, and UserPromptSubmit auto-recalls relevant previews from earlier sessions.
- Codex adapter (@qiuxu/memex-codex): AGENTS.md manual + codex mcp add / config.toml entry.
- Model profiles: per-family windows, token-estimation ratios, injection budgets and digest prompts; overridable by the integration.
- L1 eviction through the shipped compaction/prune + surface-replace seam; no custom session events, no replacement of the compaction backend.
- Sticky L2/L3 levels with a session-private/shared split, capture policy (deepest enabled level wins) and per-level capacities.
- Hybrid retrieval shared by memory_search and auto-recall: latin identifiers, quoted spans, CJK n-grams, stopword filtering, FTS + LIKE legs, bounded cold abstracts, lexical rerank with recency.
- Cold tier + compression: memory_compress with cold (lossless, zero LLM) and digest (bounded batched summaries, 2-way concurrency, retry/fallback, ids: enforcement, cold quota GC).
- Capacity consent protocol: [EXTRA CONTEXT CAPACITY] notice at 80% hot usage tells the model to ask the user before compressing.
- Sensitive-content policy: secret-looking spans (keys/tokens/passwords) are forced into private L2, or eviction is skipped when only L3 is available.
- Observability: compression_runs history, GET /api/memory.metrics, /memory status, and optional memory_index.
- Operations: restore/回热, cold GC, backup/verify/restore (SQLite VACUUM INTO + sha256 manifest).
- UI: composer context-ring inner arc (teal = L2 capture, blue = L3), a popover mode row, a full memory panel with compression/restore buttons and capacity warnings.

Demo

memex panel and compression flow

A condensed illustration of the context-ring popover, the capacity notice, a lossless compression run, and the memory panel (rendered animation, not a screen recording).

Architecture (short version)

Any agent (DSH · Claude Code · Codex · Cursor · …)
├─ adapters: DSH bundle / MCP server / Claude hooks / Codex CLI
│ • one shared agent-agnostic core, one record vocabulary
│ • model profile → budgets, injection format, manual, digest prompt
│
DSH agent session
├─ L1 (native window) ── evict oldest balanced span ──► extra context
│ • compaction/prune shadow price + user/message surfaceOp replace
│ • receipt message keeps the model oriented
├─ L2 session archive (10M) ─┐
├─ L3 workspace archive (100M)┘ sticky, verbatim, scoped
│
├─ retrieval: memory_search / memory_open (optional memory_grep; hybrid FTS + cold abstracts)
├─ capacity: hot/cold accounting, memory_compress (cold/digest), quota GC
└─ Web: context ring + memory panel via /api/memory.* (9 owner-scoped routes)

Full design: docs/architecture.md. Measured results: docs/evaluation.md. Hosted docs: <https://qiuxu-tech.github.io/memex/>. Security policy: SECURITY.md. Upstreaming plan: docs/upstream.md.

Repository layout

| Path | Purpose |
| packages/memex | installable DSH bundle (patch + exports; modules/ is generated and git-ignored) |
| packages/memex-core | agent-agnostic core: vocabulary, query terms, store/retrieval/compression, model profiles, manual + engine facade |
| packages/memex-mcp | universal MCP stdio server (Claude Code, Codex, Gemini CLI, Cursor, Cline, …) |
| packages/memex-claude | Claude Code integration: init (MCP+hooks+CLAUDE.md) and hook handlers |
| packages/memex-codex | Codex integration: AGENTS.md manual + MCP config snippet/writer |
| packages/memex-seam | DSH ctx.memory service over the core (re-exports its vocabulary) |
| packages/memex-local | SQLite + markdown store: hot/cold tiers, FTS, compression history |
| packages/memex-checkpoint | checkpoint policy: archive/receipt/catalog/recall, capacity notice |
| packages/memex-tool | four core tools, optional maintenance tools and the stable memory manual prompt section |
| packages/memex-command | /memory on|off|status|compress|restore|gc|search|remember|pin|… |
| packages/memex-evict | L1 → L2/L3 eviction policy (sensitive-content aware) |
| packages/memex-compress | capacity compression (cold + digest) and compression history |
| packages/memex-api | nine /api/memory. HTTP routes for the panel |
| packages/memex-ui | Web client half: panel + context-ring bridge |
| test/ | offline harness (196 tests, no node_modules; stubs for host packages) |
| scripts/ | build/check bundle, scale & recall benchmarks, backup/verify/restore |

Requirements

- Node.js 24+ (node:sqlite, ESM) — for every integration.
- DeepSeek Harness 0.2.1-rc.3 only for DSH mode (this repo is an extension, not a fork).
- An MCP-capable agent for universal mode (Claude Code, Codex, Gemini CLI, Cursor, Cline, Windsurf, Zed, …).
- No npm dependencies for the offline test suite; the MCP server and adapters need only the core package.

Quick start — any MCP agent

git clone https://github.com/QiuXu-Tech/memex.git
cd memex
node scripts/build-bundle.mjs # only needed for DSH mode; MCP/adapters read the source packages

Claude Code: registers MCP + hooks + CLAUDE.md manual in this project
node packages/memex-claude/bin/cli.mjs init --model claude-sonnet-5-5

Codex: writes AGENTS.md + prints/installs the MCP config
node packages/memex-codex/bin/cli.mjs init --model gpt-6.1-sol --write-config

Any MCP client: point it at the stdio server
node packages/memex-mcp/bin/server.mjs --root ~/.memex --model deepseek-flash --levels l3

See docs/integrations.md, Claude Code, Codex, generic MCP clients and model profiles.

MCP writes are marked untrusted because an agent's assertion is not itself verification; existing records keep their labels. Search results show bounded summaries and trust labels. For a focused query, memory_search can also include up to 2,000 characters of the top record with openTop: true. Check that the result is relevant, and use memory_open to continue a truncated preview.

Install (DSH local bundle)

memex ships as a DSH bundle (a patch plus runtime modules). It is not published to npm; install it as a linked local bundle in a DSH profile:

git clone https://github.com/QiuXu-Tech/memex.git
cd memex
node scripts/build-bundle.mjs # generates packages/memex/modules
node scripts/check-bundle.mjs # verifies generated modules match sources

1. Register packages/memex as an installed bundle in your DSH profile (see docs/install.md for the profile/plugin-manager and manual-patch options).
2. Reload the profile. It contributes eight rows (memory, memory-checkpoint, memory-tools, memory-evict, memory-compress, memory-api, memory-ui, memory-commands) with the config in packages/memex/cordis.patch.yml.
3. Open a session: the composer context ring gains an “额外上下文” popover row with L2 / L3 switches (off by default; sticky once on).

Some local DSH builds require the client row to be addressed by a file: URL instead of the @qiuxu/memex/ui subpath; docs/install.md has the fallback row.

Use

- Enable: ring popover / memory panel → L2 本会话 or L3 工作区; or /memory on l2|l3|both. Levels are sticky.
- Use memory: MCP defaults to memory_search, memory_open, memory_write and memory_set_status; add --all-tools for maintenance tools. DSH uses the same four core names; set advancedTools: true on its memory-tools row for grep, index and restore. Compression remains a separate DSH tool.
- Capacity: at 80% hot usage the model receives a bilingual capacity notice and asks the user first; /memory compress [l2|l3] [ratio] or the panel button runs the lossless cold compression; memory_compress strategy=digest additionally produces bounded batch summaries.
- Maintain: /memory status (hot/cold/history), /memory restore <id>, /memory gc <keepTokens>, node --import ./test/register.mjs scripts/memory-backup.mjs backup|verify|restore.

Configuration (row config via the bundle patch)

| Row | Config fields |
| memory (backend) | root, capacityTokens (L3, 100M), sessionCapacityTokens (L2, 10M), defaultLevels (none|l2|l3|both), settingsTtlDays (90) |
| memory-checkpoint | autoArchive, autoRecall, catalogMaxChars, recallMaxChars, cardModel, materializer, materializerMaxTokens, materializerPageTokenCap, materializerHybridRerank, materializerQueryExpansion, materializerLearnedTopK, materializerLearnedPageMaxTokens, capacityNoticeRatio (0.8), capacityNoticeCooldownMs (10 min) |
| memory-evict | evictAtRatio (0.6), retainRatio (0.35), maxChars (250k), captureLevel (deepest|l2), sensitivePolicy (auto|off) |
| memory-compress | batchRecords (20), batchChars (120k), maxBatches (6), minAgeMs (1h), minDigestTokens (2000), coldQuotaTokens (0 = unlimited) |

HTTP API: GET /api/memory.index|record|search|metrics, POST /api/memory.status|level|compress|restore|gc (owner-scoped by the host; document-relative paths).

Evaluation

The public benchmark below is the historical v0.30.0 run; later materializer/selection experiments are in docs/context-materialization.md and are not a rerun of the public benchmark suite. The latest offline harness passed 196/196, with 38/38 SQLite consistency checks and 50/50 integrity and isolation checks.

| Metric | Result |
| Private archive re-check (40 curated questions; v0.5.1) | Reported hit@1 68% / hit@3 90% / hit@5 93%, cold recall 94%, p50 1.5 ms; this private archive cannot be independently reproduced from the public fixture |
| Synthetic recall suite (v0.30.0) | 80/80 target-record hits at rank 1 |
| Codex / GPT-6.1 Sol A/B (v0.30.0; 3 synthetic histories) | Exact answers: control with tail titles/summaries 3/60, treatment with pre-retrieved evidence 60/60; evicted subset 0/57 → 57/57. Method and limits |
| 10k records / 100M assigned tokens (v0.30.0, synthetic, quiet-start gate) | write 9.4 s; cold spill 5,000 records/50M tokens in 14.45 s; cold GC 2,500 records/25M tokens in 5.36 s. Timing context |
| SQLite index (synthetic v0.30.0 100M-token pool) | 10.7 MiB after writing, 28.3 MiB after cold spill; x-only bodies do not measure identifier-bearing body index overhead |

Synthetic 160K history / 80K window, on v0.30.0: the retained tail made 20/40 target facts available; the previously supplied summary plus tail made 24/40 available. memex search returned the target record for 40/40 probes. These are availability and retrieval checks, not end-to-end answer accuracy. Full charts, timing conditions and methodology: docs/benchmark.md. Recent experiments and the optimization backlog: docs/optimization-findings.md. Post-rename verification and improvement points: docs/experiments-v040.md. Live endpoint A/B harness/status: docs/live-testing.md.

SQLite consistency: the fix included since v0.15.0 serializes file-backed operations with SQLite and recovers process-interrupted transactions without overwriting existing records. Previously damaged legacy stores require inspection; process-crash recovery and its limits are described in SQLite and file consistency.

Reproduction commands, including the required saved summary and cold target ratios, are in docs/benchmark.md. Additional context is in docs/evaluation.md.

Privacy

- Memex records are stored locally in $DSH_HOME/memories (SQLite index + markdown files + cold/ tier), with no Memex telemetry. An agent's model calls can transmit prompts containing recalled memory; host integrations may have their own network behavior.
- Archives are raw conversation/tool output — treat them with the same care as your transcripts. L3 is intentionally shared across sessions in the same working directory; sensitive-looking spans are routed to L2 when possible.
- Backup files contain the same data: store them securely (scripts/memory-backup.mjs writes a sha256 manifest).

Development

node scripts/build-bundle.mjs # generate bundle modules
node scripts/check-bundle.mjs # source/bundle parity
node --import ./test/register.mjs ./test/run.mjs # offline harness (196 tests)
node --import ./test/register.mjs scripts/recall-eval.mjs --suite all
node --import ./test/register.mjs scripts/scale-bench.mjs

The test harness stubs the host packages (@deepseek-ai/) with ESM loader hooks, so it needs no node_modules and no DSH install; it spawns the MCP server and adapter CLIs to test the universal path end-to-end. See test/README.md and CONTRIBUTING.md. Upstream package export: node scripts/export-upstream.mjs (see docs/upstream.md).

License

MIT © QiuXu-Tech. Not affiliated with or endorsed by DeepSeek; DeepSeek Harness is a separate project and is not bundled here.