knowledge-session-state-and-context-project-auto-memory

name	knowledge-session-state-and-context-project-auto-memory
description	覆盖项目级 MEMORY.md 索引、主题文件、MemoryRead/MemoryWrite 工具和压缩后启发式巩固。 适用于修改跨 Session 记忆加载、topic 命名、手工读写、安全过滤、项目身份或 consolidation 规则。 不含单 Session Token 压缩与 replacement checkpoint（见 ../compaction-pipeline-and-checkpoints/）和 durable transcript（见 ../../durable-transcript-and-event-projection/）。 关键词：AutoMemoryManager, MemoryConsolidation, MemoryRead, MemoryWrite, MEMORY.md, topic, BLADE_AUTO_MEMORY。

Module Structure

Auto Memory 位于 Session transcript 之外，以项目路径派生独立存储目录。系统提示只自动加载有界索引，详细 topic 由工具按需读取；成功压缩后还会用无 LLM 的规则从被丢弃消息中追加少量候选知识。

Directory Layout

• packages/cli/src/memory/AutoMemoryManager.ts：索引、topic、列举和清理
• packages/cli/src/memory/MemoryConsolidation.ts：压缩后启发式提取
• packages/cli/src/memory/types.ts：启用开关与索引行数预算
• packages/cli/src/tools/builtin/memory/MemoryReadTool.ts：按 topic 读取或列举
• packages/cli/src/tools/builtin/memory/MemoryWriteTool.ts：手工写入与敏感模式拒绝
• packages/cli/src/prompts/builder.ts：新模型上下文中的索引注入
• packages/cli/src/slash-commands/memory.ts：用户侧项目记忆管理

Key Entry Points

• AutoMemoryManager.loadIndex()：加载有界 MEMORY.md
• AutoMemoryManager.readTopic() / writeTopic()：读取或更新详细主题
• extractLearnings()：从用户、assistant 和 tool 消息提取有限规则命中
• consolidateAfterCompaction()：按日期追加提取结果
• memoryReadTool / memoryWriteTool：模型侧手工访问入口

Gotchas

• MEMORY.md 自动注入只取前 200 行并附加剩余行提示；MemoryRead(topic="MEMORY") 仍可读取完整索引，因此索引过长不会丢失，但会增加一次显式工具调用 (packages/cli/src/memory/AutoMemoryManager.ts, packages/cli/src/tools/builtin/memory/MemoryReadTool.ts)
• BLADE_AUTO_MEMORY=0 只阻止 Prompt builder 自动注入索引，不会注销 MemoryRead/MemoryWrite，也不会阻止手工访问项目记忆 (packages/cli/src/prompts/builder.ts, packages/cli/src/tools/builtin/index.ts)
• topic 中的路径分隔符和特殊字符统一替换为 -；不同原始 topic 可能映射到同一个 .md 文件，调用方不能把原始名称当成无碰撞身份 (packages/cli/src/memory/AutoMemoryManager.ts)
• append 是“读取旧正文再整体 writeFile”，AutoMemoryManager 没有 keyed mutex 或原子替换；MemoryWrite 的非并发标记只约束单个 executor，跨 Session 同 topic 写入仍可能 last-writer-wins (packages/cli/src/memory/AutoMemoryManager.ts, packages/cli/src/tools/builtin/memory/MemoryWriteTool.ts)
• Memory 工具优先用 ExecutionContext.workspaceRoot 派生项目，Prompt builder 使用传入的 projectPath，自动巩固使用 getCwd()；worktree 和多 workspace 路径必须显式对齐，不能假设三条入口天然写到同一目录 (packages/cli/src/tools/builtin/memory/MemoryReadTool.ts, packages/cli/src/tools/builtin/memory/MemoryWriteTool.ts, packages/cli/src/prompts/builder.ts, packages/cli/src/memory/MemoryConsolidation.ts)
• MemoryWrite 的敏感信息拒绝只覆盖少量 password/token/secret/api key/private key 正则，既可能漏掉其他凭据，也允许不带赋值形态的普通 password 语句；通过校验不等于内容可安全持久化 (packages/cli/src/tools/builtin/memory/MemoryWriteTool.ts)
• MemoryRead 对 topic 不存在和空列表都返回 success: true，调用方必须检查返回正文，不能把工具成功当作记忆已命中 (packages/cli/src/tools/builtin/memory/MemoryReadTool.ts)
• listTopics() 只把 ENOENT 解释为空列表，其他文件系统错误会抛出并可由 retry-safe 的 MemoryRead 做瞬态重试；deleteTopic() 仍把任意 unlink 异常折叠为 false，两个入口的失败语义不同 (packages/cli/src/memory/AutoMemoryManager.ts, packages/cli/src/tools/builtin/memory/MemoryReadTool.ts)
• 自动巩固只识别用户显式 remember/convention/lesson 标记、assistant 的 fix 文本和有限 tool error 模式；tool error 每次最多保留 5 条，它不是对被丢弃上下文的完整语义总结 (packages/cli/src/memory/MemoryConsolidation.ts)
• 压缩成功后 consolidation 以 fire-and-forget 启动并吞掉全部异常；记忆写入失败既不回滚 checkpoint，也不会令 compaction 失败 (packages/cli/src/context/CompactionService.ts, packages/cli/src/memory/MemoryConsolidation.ts)

Architecture

• AutoMemoryManager 通过项目存储路径把 MEMORY.md 与 topic 文件放在 Session transcript 之外，使同一项目的后续 Session 可以复用，但不会继承 rewind、fork 或 committed seq 语义 (packages/cli/src/memory/AutoMemoryManager.ts, packages/cli/src/context/storage/pathUtils.ts)
• Prompt builder 只把索引放入 <auto-memory>，详细 topic 不自动进入系统提示；MemoryRead 是渐进披露入口 (packages/cli/src/prompts/builder.ts, packages/cli/src/tools/builtin/memory/MemoryReadTool.ts)
• MemoryRead 是并发安全且可重试的 ReadOnly 工具，MemoryWrite 是不可并发、不可自动重放的 Write 工具；两者仍通过统一 ToolExecutor 权限与结果契约 (packages/cli/src/tools/builtin/memory/MemoryReadTool.ts, packages/cli/src/tools/builtin/memory/MemoryWriteTool.ts)
• consolidation 不调用额外模型，只把规则命中按日期追加到 preferences、conventions、lessons 或 debugging topic，避免压缩额外产生 Provider 请求 (packages/cli/src/memory/MemoryConsolidation.ts)

Decisions

• Auto Memory 以索引加 topic 的两层结构实现渐进披露：启动成本固定在索引前 200 行，详细经验留给按需工具读取 (packages/cli/src/memory/AutoMemoryManager.ts, packages/cli/src/prompts/default.ts, git:40128981)
• 自动巩固采用保守启发式并在失败时不影响压缩主路径，优先保证 Session checkpoint 可提交，而不是保证每次压缩都产生记忆 (packages/cli/src/context/CompactionService.ts, packages/cli/src/memory/MemoryConsolidation.ts)

Patterns

• topic="MEMORY" 是索引写入的保留入口，topic="_list" 只在 MemoryRead 中表示列举；普通 topic 最终统一补 .md 后缀 (packages/cli/src/tools/builtin/memory/MemoryReadTool.ts, packages/cli/src/tools/builtin/memory/MemoryWriteTool.ts, packages/cli/src/memory/AutoMemoryManager.ts)
• append 会在旧正文缺少尾换行时补一个分隔换行，consolidation 自身则把每条结果格式化为带 ISO 日期的 Markdown 列表项 (packages/cli/src/memory/AutoMemoryManager.ts, packages/cli/src/memory/MemoryConsolidation.ts)
• topic 列表按最后修改时间降序返回并包含 MEMORY 本身；UI 或 Agent 若要把索引固定在首位，需要在消费端另行排序 (packages/cli/src/memory/AutoMemoryManager.ts)