Cortex 内存系统¶

Cortex 将所有知识以原子化、带索引的 markdown 文件存储在文件系统中——即 Dense Context 结构（DR-0007）。没有向量数据库、没有 RAG 管道、没有外部知识存储。文件系统就是数据库。关于这如何融入更广泛的系统架构，参见 architecture.md。

为什么使用原子化内存¶

核心洞察（来自 DR-0007）是单体上下文文件无法扩展。单个 EXPERIMENTS.md 文件无限增长，使其加载到智能体上下文时代价高昂且难以搜索。解决方案是将每个实验、知识条目和模式原子化为自己的文件，并带有自动生成的索引以便快速查找。

此设计借鉴了学术工作：Du 2026 的智能体内存模式调查，QMatSuite 的分层知识层次（finding → pattern → principle），以及 A-MEM 的带动态链接的原子笔记（100 万条记忆时检索时间 < 4μs）。

目录布局¶

知识根目录是 ~/.cortex/context/，结构如下：

context/
├── CORTEX.md                    # 根索引——查找任何内容的入口点
├── OVERVIEW.md                  # 全局概览：每项目一行状态 + 上次扫描日期
├── decisions/                   # 系统级设计决策（DR-NNNN-title.md）
├── ideas/                       # 孵化中的研究方向
├── scans/                       # 知识扫描报告，每天一份
├── user/                        # 用户偏好（由 /user-learn 维护）
│   └── USER.md                  # 语言、风格、工作习惯（< 3KB）
└── projects/                    # 每个活跃研究项目一个子目录
    └── <project>/
        ├── CORTEX.md            # 项目级索引
        ├── mission.md           # 目标和成功条件
        ├── roadmap.md           # 带可测试清单条件的里程碑
        ├── STATUS.md            # 当前状态快照（覆盖式，最多 120 行）
        ├── ISSUES.md            # 执行摩擦（仅追加，已解决项删除，最多 80 行）
        ├── TASKS.yaml           # 结构化任务队列（机器可读 YAML）
        ├── tasks-archive.md     # 自动归档的已完成任务（由 task-archive 调度作业处理）
        ├── experiments/
        │   ├── index.md         # 自动生成——请勿手动编辑
        │   └── EXP-NNN.md       # 每实验一个文件，YAML frontmatter
        ├── knowledge/
        │   ├── index.md         # 自动生成
        │   └── K-NNN.md         # 每知识条目一个文件
        ├── patterns/
        │   ├── index.md         # 自动生成
        │   └── PAT-NNN.md       # 每跨实验模式一个文件
        ├── decisions/           # 项目级设计决策
        └── _meta/
            └── access-log.jsonl # 自动追踪的 Read/Grep 访问日志

三种原子类型¶

实验（EXP-NNN.md）¶

每个实验是一个记录单次调查的原子文件。实验记录做了什么、观察到了什么、得出了什么结论以及后续应该改变什么。

YAML frontmatter：

---
id: EXP-042
date: 2026-03-09
project: flywheel
summary: "从 573 个产物中初步提取对象注册表"
tags: [registry, data-analysis, milestone-2.2]
status: valid
executor: Cortex-lab2
links: [PAT-002]
refs: 2
last-ref: "2026-04-16T03:12:21.074Z"
---

必需字段： id、date、project、summary、tags。

可选字段： status、executor、links（相关条目）、refs（自动）、last-ref（自动）。

正文结构： markdown 正文遵循标准模板，包含以下部分：Background、Execution、Results、Conclusion 和 Reflection（目标达成、意外发现、过程缺陷、行为调整）。

状态生命周期：

状态	含义
`active`	当前进行中
`valid`	已完成，结论成立
`partial`	不完整但值得保留
`challenged`	结论有争议（标记为挑战实验）
`corrected`	结论曾错误，现已修正
`superseded`	被后续实验取代
`refined`	被后续实验更新/改进
`invalidated`	被证明错误，已墓碑化
`stale`	无活动，引用计数为零

知识条目（K-NNN.md）¶

知识条目是从实验中提炼的原子事实、反模式或启发式。每个条目必须在 evidence 字段中引用其来源实验。

YAML frontmatter：

---
id: K-008
date: 2026-04-01
project: flywheel
summary: "反模式：在未验证上游服务可用性的情况下运行烟雾测试或更广泛的验证"
tags: [anti-pattern, smoke-test, service-dependency]
evidence: [EXP-021, EXP-022, EXP-025, EXP-033, EXP-040]
refs: 2
last-ref: "2026-04-10T20:42:00.826Z"
---

必需字段： id、date、project、summary、tags、evidence。

反模式约定： 描述反模式的知识条目在摘要前加 ANTI-PATTERN: 并在 tags 中包含 anti-pattern。

模式（PAT-NNN.md）¶

模式综合了跨多个实验的不变量。模式陈述一个在一组实验中成立的可重用观察。

YAML frontmatter：

---
id: PAT-001
date: 2026-04-01
project: flywheel
summary: "当多阶段管道产生零输出时，按阶段量化通过率比端到端重试更快定位瓶颈"
tags: [pipeline, diagnosis, stage-isolation]
source-experiments: [EXP-001, EXP-005, EXP-006, EXP-008]
evidence: [EXP-001, EXP-005, EXP-006, EXP-008]
refs: 2
last-ref: "2026-04-16T03:16:28.890Z"
---

必需字段： id、date、project、summary、tags、source-experiments（从中提取模式的实验）。

正文结构： Observation、Evidence（引用带具体发现的实验表格）、Pattern Statement、Scope & Limitations、Implications。

索引自动生成¶

项目下的每个目录（experiments/、knowledge/、patterns/）都有一个由 memory-index-regen 作业自动生成的 index.md。索引文件包含警告：

> Auto-generated by memory-index-regen.ts from YAML frontmatter. Do not edit manually.
> Last updated: 2026-05-06T20:31:10

索引结构：

活跃表 — 所有状态为 active、valid 或 partial 的条目，按引用计数排序（降序）
取代/弃用表 — 被后续工作取代的条目
无效表 — 被证明错误的墓碑化条目
统计部分 — 总计数、热门条目（refs >= 5）、冷条目（refs = 0，年龄 > 14 天）

重建命令：

# 对所有项目
cd agent-server && node --import tsx src/memory-index-regen.ts --all

# 对特定项目
cd agent-server && node --import tsx src/memory-index-regen.ts <project-name>

重建过程读取所有原子文件的 YAML frontmatter，从当前索引中提取 refs 和 last-ref 以保留访问追踪，并写入新索引。

访问追踪¶

Cortex 自动追踪研究期间访问了哪些实验、知识和模式文件。这通过 ~/.cortex/hooks/memory-ref-tracker.mjs 中的 Claude Code PostToolUse 钩子实现（完整钩子系统参见 hooks.md）。

工作原理：

每次 Read 或 Grep 工具调用后，钩子检查访问的文件路径是否匹配模式 /(experiments|knowledge|patterns)/(EXP-\d+[a-z]?|K-\d+|PAT-\d+)\.md$/
如果匹配，它从路径中提取项目名称并追加一行 JSON 到 _meta/access-log.jsonl：
```
{"file":"EXP-001.md","tool":"Read","ts":"2026-04-02T03:12:21.074Z"}
```
对于匹配多个文件的 Grep 操作，它解析工具输出以计算每个文件的匹配数，避免重复计数
如果 Grep 返回零个文件匹配，则记录 _directory_search
钩子自动提交访问日志更改，消息为 chore: update access log

index.md 中的引用计数（refs）由 memory-index-regen 基于这些访问日志更新——研究期间频繁读取的文件获得更高的引用计数并在索引中排名更高。

项目日志文件¶

每个项目都有一组治理文件，共同构成其运行内存：

mission.md — 宪章¶

定义项目的目标、成功条件和范围边界。此文件是稳定的，只应在明确的用户批准下更改。它回答：我们试图实现什么，以及我们如何知道已经成功？

roadmap.md — 里程碑地图¶

分层阶段，每个阶段包含带可测试清单条件的里程碑。已完成的里程碑保留打勾标记（不删除）。路线图显示项目去过哪里、现在在哪里以及要去哪里。

STATUS.md — 当前快照¶

一个覆盖式（不是仅追加）文件，捕获当前状态，上限 120 行。必需部分：当前阶段、近期进展、开放阻塞、下一步。这是在一段时间后恢复项目工作时首先阅读的文件。

ISSUES.md — 执行摩擦¶

一个仅追加的日志，记录减慢工作的问题，上限 80 行。每个条目有带日期的标题和要点列表：问题、何时发生、调查过程。已解决的问题从文件中删除（不归档）。

decisions/ — 决策记录¶

每个决策是一个文件，命名为 NNNN-title.md。格式遵循项目决策记录模板：Date、Status、Context、Alternatives（至少 2 个）、Decision、Consequences。

Dense Context 约定¶

Dense Context 系统遵循以下运行约定：

每个目录有 CORTEX.md 索引 — 描述目录的用途、文件列表和查找规则
创建文件 → 更新索引 — 向目录添加新文件时，更新该目录的 CORTEX.md
覆盖 vs. 追加 — STATUS.md 覆盖（仅当前状态）；ISSUES.md 追加然后删除；experiments/knowledge/patterns 追加并保留
来源强制 — 每个事实声明必须追溯到特定的 EXP-NNN、K-NNN、file:line 或内联计算
Git 作为持久化 — 所有上下文更新通过 git 增量提交，在每逻辑工作单元后

全新会话测试¶

Dense Context 质量的酸性测试：如果你启动一个仅对仓库有读取权限的全新会话，你能学到上一个会话知道的所有信息吗？如果答案是否定的，说明有内容未被正确记录。

内存索引重建作业¶

memory-index-regen 程序化调度器作业（通过 job-registry.ts 注册，通常由 dispatchType: "memory-index-regen" 的调度触发）从 YAML frontmatter 重建所有索引文件。它：

扫描 context/projects/ 下的所有项目
从每个 EXP-*.md、K-*.md 和 PAT-*.md 读取 frontmatter
保留当前索引中已有的 refs 和 last-ref
写入更新后的 index.md 文件

生命周期：实验维护¶

experiment-maintenance 技能对实验文件运行周期性检查：

识别结论可能陈旧的实验（基于更新的矛盾实验）
标记引用为零且年龄 > 14 天的实验（"冷"条目）
检查 frontmatter 有效性
建议相关实验的合并机会

规模¶

截至上次索引重建，系统在 9 个项目中共追踪：

项目	实验	知识	模式
flywheel	56	11	4
cortex-self	66	15	6
tactile-reasoning	27	~13	2
其他项目	各不相同	各不相同	各不相同

所有索引同时重建——命令在不到一秒内完成。