长期记忆不是聊天记录：解读 Grok Build 的持久化记忆系统

先给结论：这是检索系统，不是对话回放#

Grok Build 的跨会话记忆由 xai-grok-memory 提供核心能力，xai-grok-shell 在会话生命周期中编排它，xai-grok-tools 则把它暴露为只读工具。它保存的不是某个模型实例的内部状态，也不会在新会话开始时把历史聊天全文重新发送给模型。

**设计的关键分层：**Markdown 文件保存可审阅、可手工编辑的知识；SQLite 的 FTS5 和可选向量表只保存检索副本；每次使用时按当前任务检索少量片段。删掉索引可以重建，删掉 Markdown 才是数据丢失。

1
1. 提炼对话在 session end、预压缩或空闲时由模型归纳为结构化 Markdown。 2. 落盘全局偏好、项目知识与会话日志保存在用户 Grok Home 下。 3. 建索引按 Markdown 结构分块，写入 FTS5；可选生成 embedding 并写入 sqlite-vec。 4. 取回首轮、压缩恢复或模型工具调用以当前查询取回相关片段。

因此，它解决的是“未来会话如何找到此前有效的决策、约定和排障知识”，而不是“如何在同一个上下文窗口里继续一段对话”。后一个问题由上下文压缩负责，二者在预压缩 flush 和压缩后的记忆恢复处相连，但存储模型不同。

三种“记忆”及其边界#

代码中 memory 一词也会指进程内状态或性能指标。阅读时最重要的是先把持久化记忆与它们区分开。

第三项复用同一套存储与检索机制，但目录是按 Agent 名称独立解析的：user 指向 ~/.grok/agent-memory/<name>/；project 和 local 分别位于项目中的 .grok/agent-memory/ 与 .grok/agent-memory-local/。这与普通记忆写入时的 Global/Workspace 选择是两种不同的 scope。

持久化模型：Markdown 是事实源#

MemoryStorage 默认根目录是 ~/.grok/memory/。会话初始化时会创建目录和两个 MEMORY.md 模板，并枚举其中的 Markdown 文件建立索引。典型布局如下：

1
~/.grok/memory/
2
├── MEMORY.md                         # 跨项目的人工维护知识
3
└── widgets-a3f7b2c9/                 # 一个工作区
4
    ├── MEMORY.md                     # 项目长期知识，由 dream 归并
5
    ├── index.sqlite                  # 可删除、可重建的检索索引
6
    └── sessions/
7
        └── 2026-07-17-auth-1234abcd.md  # 提炼后的会话日志

工作区目录格式为 {slug}-{hash8}。若当前目录属于有 origin 的 Git 仓库，身份优先取规范化后的 org/repo，因此同一仓库的 clone 和 worktree 共享记忆；没有可用 remote 时，才以规范化后的文件系统路径作为 hash 输入。slug 只是可读性，8 位 BLAKE3 前缀负责区分。

临时工作目录不会产生工作区记忆。MemoryStorage 对 /tmp、/var/tmp 和 macOS 临时目录标记为 ephemeral；工作区的初始化、追加和会话日志写入会跳过。这样不会为短命 worktree 和子任务留下大量孤儿目录。

写入与归并：flush 和 dream 做了什么#

系统不直接把原始聊天记录写进记忆文件，而是让模型产出结构化摘要，再用多层检查决定是否持久化。这里有两条不同粒度的写入路径。

1
// 讲解伪代码：run_memory_flush 的关键路径
2
recent = select_recent_messages_at_a_user_boundary(conversation)
3
summary = model.call(FLUSH_SYSTEM_PROMPT, recent)
4

5
if summary != NO_REPLY and has_markdown_headers(summary):
6
    if not exact_duplicate(summary) and not semantic_duplicate(summary):
7
        append sessions/YYYY-MM-DD-{trigger}-{sid8}.md
8
        reindex_and_embed(the_written_file)

索引和外部编辑如何保持一致#

index.sqlite 有三层数据：chunks 保存路径、行号、正文、hash、来源和访问记录；chunks_fts 是 contentless FTS5 虚表；当 sqlite-vec 可加载时，会额外创建 chunks_vec 存 embedding。向量扩展不可用、没有配置 embedding model、或 embedding 请求失败时，系统仍可正常以 FTS-only 工作。

1
## Authentication
2
### Token refresh
3
...
4

5
分块后的 continuation：
6
[Context: ## Authentication]
7

8
### Token refresh
9
...

混合检索如何排序#

hybrid_search() 的结果不是简单的向量最近邻。它先取 FTS5 BM25 候选和全局/工作区常青来源的补充候选；若向量可用，再为查询生成 embedding 并做 KNN；最后按 chunk ID 合并、排序、筛选和截断。候选数是目标返回数的三倍，降低后处理过早截断的风险。

1
score = base_relevance × temporal_decay × source_weight × access_boost

base_relevance 由归一化的 BM25 和向量相似度给出。两者同时命中时按可配置权重合成，默认文本 0.3、向量 0.7，但结果不会低于纯 FTS 分数；只有 FTS 命中的块也不会因为缺向量而被降成 0.3 倍。这样在模型 embedding 未配置或新块尚未嵌入时，关键词检索仍然可用。

• **时间衰减：**默认只对 session 应用 7 天半衰期的指数衰减；global 和 workspace 保持常青。
• **来源权重：**可分别调整三类来源的优先级，默认都为 1.0。
• **访问提升：**被反复取用的块有很小的 ln(1 + access_count) 加成，不会替代相关性本身。
• **MMR 去重：**默认关闭；开启后用 snippet 的 Jaccard 相似度重排，减少结果列表中多个近似片段占满名额。
• **内容过滤：**只有标题、空白或已知初始化模板的块不会进入结果，避免新建的 MEMORY.md 变成无意义上下文。

session 结果超过 1 天会在工具输出中提示验证，超过 7 天会明确标为 stale；常青来源不显示这类警告。时效提醒并不阻止模型使用结果，它提醒模型把旧会话信息作为待验证线索，而不是当前事实。

模型怎样使用记忆#

系统没有把所有记忆自动注入每一轮。当前实现提供三条回流路径，每条都有不同的成本和触发条件。

首轮路径还会检测现有 conversation 的 leading system message 中是否已有 <memory-context>。若存在便复用而不是再次检索，因为重新排序的块会改变 system prompt 前缀，从而破坏下游模型的 prompt/KV cache。这个细节说明“检索正确”之外，稳定的 prompt 形状也是性能约束。

1
// 模型可见的典型工具序列
2
memory_search({ query: "authentication middleware patterns" })
3
  -> 结果含文件路径、行范围、片段、来源、分数
4

5
memory_get({ path: ".../MEMORY.md", from: 24, lines: 40 })
6
  -> 带 1-based 行号的完整上下文

两个工具都声明为只读。memory_search 使用后端配置的默认结果数与阈值；memory_get 在读取前 canonicalize 请求路径和记忆根目录，只有规范化后仍位于记忆目录树内的路径才允许读取。这使模型不能借由该工具读取任意本地文件。

并发、安全和生命周期细节#

长期记忆最容易在边界条件上失真，当前实现中有几处值得借鉴的防线：

1. **索引可重建。**Markdown 是事实源，SQLite 失败或向量扩展缺失只会降级检索，不会抹掉知识原文。
2. **删除也会同步。**watcher 不只处理 create/modify；文件不存在时显式删除其旧 chunks，避免已删知识持续被模型检索。
3. **写入有质量门。**flush 和 dream 都拒绝空响应、NO_REPLY 和缺标题的文本；flush 还有精确及语义去重。
4. **归并不删除活跃日志。**dream 成功后仅删除实际参与输入、且超过 5 分钟未修改的文件；近期修改意味着可能有并发会话仍在追加。
5. **网络文件系统考虑。**索引打开经由 xai-sqlite-journal 选择 journal mode，代码特别避免在网络挂载上 mmap 旧 WAL 的 -shm 文件。
6. **垃圾回收保守。**启动时只清理空的、过期的工作区目录；有 session 内容的普通工作区不会被 GC。默认空目录保留期为 30 天，tmp* 目录单独按 7 天策略处理。

**工程上的取舍：**外部编辑的同步延迟到下一次搜索，而不是在文件事件回调中立即写 SQLite。这让 watcher 保持轻量，同时在实际需要答案时保证索引最新。代价是第一次搜索需要承担该次 reindex 成本。

关键配置与默认行为#

完整聚合配置位于 xai-grok-shell/src/config/mod.rs，具体值类型在 xai-grok-config-types/src/memory.rs。记忆默认关闭，可通过 --experimental-memory、GROK_MEMORY=1 或配置启用；--no-memory 和 GROK_MEMORY=0 用于显式禁用。以下示例只展示最常需要调整的项：

1
[memory]
2
enabled = true
3

4
[memory.index]
5
max_chunk_chars = 1600
6
chunk_overlap_chars = 320
7

8
[memory.embedding]
9
# model 未设置时保持 FTS-only；设置后才会尝试 embedding 和向量检索
10
model = "your-embedding-model"
11
dimensions = 1024
12

13
[memory.search]
14
max_results = 6
15
min_score = 0.35
16
vector_weight = 0.7
17
text_weight = 0.3
18

19
[memory.search.temporal_decay]
20
enabled = true
21
half_life_days = 7.0
22

23
[memory.initial_injection]
24
enabled = true
25

26
[memory.dream]
27
enabled = true
28
min_hours = 4
29
min_sessions = 3
30

31
[compaction.memory_flush]
32
enabled = true
33
soft_threshold_tokens = 4000
34
max_flush_write_chars = 8000

首轮自动注入默认开启，且没有显式 min_score 时沿用 0.0 的历史行为，优先保证新会话有可用的项目线索；模型主动 memory_search 则默认采用 memory.search.min_score = 0.35。两条路径的差异是刻意的：前者服务于初始化，后者服务于精确的按需检索。

**不要把 embedding 看成系统前提。**默认 embedding model 为未设置状态，sqlite-vec 也可能无法加载。检索代码明确设计为 FTS-first 的优雅降级，配置 embedding 是提高语义召回，不是让记忆功能从无到有的开关。

源码索引#

按“存储事实源 - 建索引 - 检索 - 会话编排”的顺序阅读，最容易建立完整心智模型：

• crates/codegen/xai-grok-memory/src/storage.rs 目录布局、工作区身份、Markdown 读写、临时目录跳过和 GC。
• crates/codegen/xai-grok-memory/src/chunker.rs Markdown 标题、段落和行边界感知的分块实现。
• crates/codegen/xai-grok-memory/src/schema.rs 与 index.rs SQLite 表、FTS5、sqlite-vec、增量 reindex、删除和 claim 协调。
• crates/codegen/xai-grok-memory/src/search.rs、mmr.rs、backend.rs 混合召回、时间衰减、来源权重、MMR 和 FTS-only 降级。
• crates/codegen/xai-grok-memory/src/dream.rs 与 dream_lock.rs 长期归并的 gate、输入/输出上限、锁和安全清理。
• crates/codegen/xai-grok-shell/src/session/helpers/memory_flush.rs 预压缩 flush 的阈值、质量检查和语义去重。
• crates/codegen/xai-grok-shell/src/session/acp_session_impl/spawn.rs、memory_dream.rs、turn.rs 会话启动、后台索引、flush/dream 调用和首轮记忆注入。
• crates/codegen/xai-grok-tools/src/implementations/memory/ memory_search 与 memory_get 的只读工具接口。
• crates/codegen/xai-grok-agent/src/config.rs Agent 专属记忆的 user/project/local 目录解析。