Luxas 文件化记忆系统拆解:不用向量数据库的跨项目记忆方案

原创2026-10-13 18:32:161,363 阅读

Luxas 文件化记忆系统拆解:不用向量数据库的跨项目记忆方案

Luxas 是一个开源的自主科研 Agent:给它一个研究问题,它能自己爬文献、跑实验、写出带真实引用的 LaTeX 报告。它的核心特色之一是文件化记忆系统——完全不引入向量数据库,跨项目记忆全部落在 Markdown、JSON 和 JSONL 文件里,靠确定性的读取路径注入新会话。本文拆解这套方案的三层布局、读写路径和信任纪律,帮你理解 AI Agent 记忆管理的一种轻量做法。

Luxas 文件化记忆系统驱动生成的科研报告首页

上图是 Luxas 全自动产出的科研报告 PDF 首页(摘要 + 章节),由 fixtures/claims-ppss/ 这个示例项目的完整工作流生成。

为什么 Luxas 不用向量数据库?

大多数 Agent 框架的记忆方案是:对话/笔记 → 切片 → embedding → 写入向量库 → 相似度检索。Luxas 反着来,它的选择基于三个现实约束:

  1. 检索对象不是"语义相似",而是"结构已知"。科研项目的记忆天然有固定结构:notes/experiments.md 记实验、notes/literature.md 记文献、notes/memory.md 记决策和死胡同。你要的不是"找出相似段落",而是"把整个文件读给我"。
  2. 可审计。文件可以直接 cat、git diff、人工审阅;向量库里的 embedding 是黑盒。
  3. 零依赖。不需要额外服务、索引和运维,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(),每次运行结束后依次做三件事:

  1. 更新注册表:把累计花费、token 数、lastRunFinished 状态写回 projects.json。注意一个细节——它镜像而不是累加花费,因为 usage.log 本身就是跨会话的累计真值,累加会在每次恢复运行时双重计数。
  2. 生成项目摘要:generateProjectSummary() 从 notes/literature.md 提取章节标题、从 notes/experiments.md 提取假设/结论/负结果关键行,拼出一段紧凑摘要存入注册表。
  3. 归档: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() 生成,聚合所有历史项目的成果、纠错和未走完的线索

Luxas 报告中由实验记忆驱动的 packing gain 分析图表页

上图是该报告的第 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:

  1. 信任规则:从历史项目读到的一切都是"dated, UNVERIFIED lead"(带日期的未验证线索)。任何数值必须重新走当前项目自己的证据链(重新读文献、重新跑实验)才能进入 report.tex。
  2. CORRECTIONS 约定:发现旧笔记里有错误主张时,追加一个 ## CORRECTIONS 段落说明错在哪、证据是什么,而不许改写原文——历史保持完整,反驳紧挨着原主张。
  3. 写入边界:~/.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 记忆量在"几十个文档"这个量级,且检索对象结构已知,这套"全文件 + 确定性注入 + 信任纪律"的方案比引入向量数据库更简单、更可审计——它证明了记忆系统的价值不一定来自更聪明的检索,也可以来自更清晰的文件布局和更严格的信任规则。

登录后查看全文
luxas