Luxas 文件化记忆系统拆解:不用向量数据库的跨项目记忆方案
Luxas 文件化记忆系统拆解:不用向量数据库的跨项目记忆方案
Luxas 是一个开源的自主科研 Agent:给它一个研究问题,它能自己爬文献、跑实验、写出带真实引用的 LaTeX 报告。它的核心特色之一是文件化记忆系统——完全不引入向量数据库,跨项目记忆全部落在 Markdown、JSON 和 JSONL 文件里,靠确定性的读取路径注入新会话。本文拆解这套方案的三层布局、读写路径和信任纪律,帮你理解 AI Agent 记忆管理的一种轻量做法。
上图是 Luxas 全自动产出的科研报告 PDF 首页(摘要 + 章节),由 fixtures/claims-ppss/ 这个示例项目的完整工作流生成。
为什么 Luxas 不用向量数据库?
大多数 Agent 框架的记忆方案是:对话/笔记 → 切片 → embedding → 写入向量库 → 相似度检索。Luxas 反着来,它的选择基于三个现实约束:
- 检索对象不是"语义相似",而是"结构已知"。科研项目的记忆天然有固定结构:
notes/experiments.md记实验、notes/literature.md记文献、notes/memory.md记决策和死胡同。你要的不是"找出相似段落",而是"把整个文件读给我"。 - 可审计。文件可以直接
cat、git diff、人工审阅;向量库里的 embedding 是黑盒。 - 零依赖。不需要额外服务、索引和运维,
readFileSync就是全部基础设施。
官方 README 直接点明了这个定位:file-backed memory (no embeddings, no vector store)。
文件化记忆的三层布局
Luxas 的记忆按作用域分成三层,全部是磁盘上的普通文件:
| 层级 | 位置 | 内容 | 维护者 |
|---|---|---|---|
| 项目内记忆 | <项目>/notes/*.md |
实验记录、文献笔记、决策草稿 | 各 Agent 在运行中实时写入 |
| 全局记忆 | ~/.sisyphus/ |
项目注册表、跨项目经验、项目归档 | 运行框架自动维护 |
| 生涯记忆 | ~/.sisyphus/career/ |
结构化成果、纠错记录、未走通的研究线索 | 项目收尾时机械收割 |
核心实现在 src/memory.ts,文件头注释写得很直白:
~/.sisyphus/memory.md—— Agent 自己维护的跨项目经验(自由格式 Markdown)~/.sisyphus/projects.json—— 所有研究项目的注册表,每条记录含路径、名称、日期、自动生成的摘要、累计花费~/.sisyphus/archive/<slug>/—— 每个已完成项目的 notes 和report.tex副本
而"跨项目记忆的访问协议"本身也是一个技能文件:skills/memory/SKILL.md,定义了信任规则、文件地图和写入边界。
写入路径:项目收尾时自动归档
写入侧的关键函数在 src/memory.ts 的 updateProjectAfterRun(),每次运行结束后依次做三件事:
- 更新注册表:把累计花费、token 数、
lastRunFinished状态写回projects.json。注意一个细节——它镜像而不是累加花费,因为usage.log本身就是跨会话的累计真值,累加会在每次恢复运行时双重计数。 - 生成项目摘要:
generateProjectSummary()从notes/literature.md提取章节标题、从notes/experiments.md提取假设/结论/负结果关键行,拼出一段紧凑摘要存入注册表。 - 归档:
archiveProjectNotes()把三份 notes 和report.tex复制到~/.sisyphus/archive/<slug>/,并在文件头加上项目名、源路径、归档时间的 HTML 注释——这样即使原项目目录被删,记忆仍可溯源。
这里有个耐人寻味的 bug 修复史:archiveSlug()(src/memory.ts)的 slug 原来只做字符清洗,纯中文项目名会被清空成空字符串,导致所有中文项目互相覆盖同一个归档根目录。修复方式是拼上路径的 sha256 前 6 位,保证 slug 非空且唯一。
读取路径:把过去注入新会话
记忆的价值在读取侧。Luxas 的做法是:新建会话时,把历史项目压缩成几个 XML 标签块,注入 brain 的半静态系统层(src/context.ts 的 buildSemiStaticSystemLayer()):
<past_research>:由 buildPastResearchDigest() 生成。列出每个历史项目的名称、日期、notes 路径和原始研究问题,按最近运行倒序排列<global_memory>:直接读取~/.sisyphus/memory.md,按条目边界截断到预算内<career>:由 src/career.ts 的buildCareerBlock()生成,聚合所有历史项目的成果、纠错和未走完的线索
上图是该报告的第 4 页:图表与正文中每个数字都能回溯到 data/experiments/ 下的 results.json——这正是"文件即记忆"思想在数据侧的对应。
<past_research> 的设计里藏着一个刻意的克制:digest 只带研究问题,不带结论。注释解释得很清楚——错误"事实"要进入当前项目,唯一通道是显式读取那个项目的 notes,而在那份文件里,结论紧挨着它自己的局限性和红队审查段落。摘要反而可能把脱离上下文的数字带进新会话,造成污染。
没有 embedding 的"相关性":token 重叠匹配
Career 层要回答一个问题:用户有 20 个历史项目,哪些和当前研究问题相关?Luxas 的答案在 src/career.ts:
/** Significant-token overlap match: no embeddings by design (CLAUDE.md). */
function tokens(t: string): Set<string> { ... }
function overlap(a: Set<string>, b: Set<string>): number { ... }
把研究问题和每条 career 记录都拆成 token 集合(长度 > 3 的词,且中文按字直接参与——正则 [^a-z0-9一-鿿 ] 保留了 CJK 字符),然后数重叠 token 数量,超过阈值(≥2)才入选。没有 embedding 模型,没有相似度服务,一次 readFileSync + 集合交集就跑完了。对"科研术语高度集中"的领域文本,词面重叠本身就是很强的相关信号,而这套代码的确定性和零成本比一个小模型召回更可控。
信任纪律:历史是"过期线索",不是事实
文件化记忆最大的风险是旧结论污染新结论。Luxas 用三条纪律应对,全部写在 skills/memory/SKILL.md:
- 信任规则:从历史项目读到的一切都是"dated, UNVERIFIED lead"(带日期的未验证线索)。任何数值必须重新走当前项目自己的证据链(重新读文献、重新跑实验)才能进入
report.tex。 - CORRECTIONS 约定:发现旧笔记里有错误主张时,追加一个
## CORRECTIONS段落说明错在哪、证据是什么,而不许改写原文——历史保持完整,反驳紧挨着原主张。 - 写入边界:
~/.sisyphus/memory.md和archive/在白名单内可直接读写;其他项目的活动 notes 只能追加(cat >>),不许重写或删除。
示例项目 fixtures/claims-ppss/notes/memory.md 里有一段真实的跨项目交叉引用,能直观感受这套纪律的效果:
Prior project cross-check (unverified leads)
- single_photon_297nm: C6_PP(theta)~sin^4 for Rb nP3/2 stretched; anisotropy 23.6x ... All [unverified] — re-derive in E1.
上一项目的数值被引用,但明确标注 unverified,并要求在当前项目的 E1 实验中重新推导——这正是"线索 vs 事实"的边界。同文件的 PREMISE-ACK: 记录则展示了纠错如何落盘:每个被实验证伪的前提都留下了一条带日期、带证据的确认行。
工程细节:预算、隔离与自愈
这套系统能长期稳定运行,靠的是几个不显眼但关键的工程决策:
- 字符预算 + CJK 加权:digest 总预算 12000 字符、溢出索引 3000 字符(src/memory.ts);
budgetWeight()给 CJK 字符 ×2 权重,因为中文字符约 1 token/字而 ASCII 约 1/4。截断global_memory时按条目边界切(truncateGlobalMemory),宁可少一条也不截半条——一条没有来源标签的半截结论正是污染规则的禁区。 - 注册表损坏隔离:
projects.json解析失败时不会静默变成空注册表(那样下次写入会抹掉所有其他项目),而是重命名为.corrupt.<时间戳>隔离起来并大声报错(src/memory.ts)。 - 临时目录防污染:
/tmp下的抛弃型测试项目会注册但不会进入 digest,避免垃圾污染跨项目记忆。 - notes 自动瘦身:项目内
notes/*.md超过 8000 字符时,src/notes-compaction.ts 会用 LLM 做去噪整理——删已完成 TODO、合并重复观察、压缩死胡同记录,但"拿不准就保留",误删比噪音更糟。
小结:这套方案的可借鉴之处
Luxas 的文件化记忆系统本质上是把"记忆"拆成了四个正交问题,每个都用最朴素的文件操作解决:
| 问题 | 解法 | 对应实现 |
|---|---|---|
| 存在哪 | 三层文件:notes/ → ~/.sisyphus/ → career/ | src/memory.ts |
| 何时写 | 运行中实时写 notes;收尾时归档 + 收割 | updateProjectAfterRun / src/career.ts |
| 何时读 | 新会话构建 digest,注入系统层 | src/context.ts |
| 怎么信 | 过期线索 + CORRECTIONS + 重新验证 | skills/memory/SKILL.md |
如果你的 Agent 记忆量在"几十个文档"这个量级,且检索对象结构已知,这套"全文件 + 确定性注入 + 信任纪律"的方案比引入向量数据库更简单、更可审计——它证明了记忆系统的价值不一定来自更聪明的检索,也可以来自更清晰的文件布局和更严格的信任规则。

