项目记忆系统 - 文件级跨对话记忆架构

深度解析 Claude Code 记忆系统：基于文件的持久化存储、MEMORY.md 索引结构、四类型分类法、Sonnet 智能召回、Session Memory 压缩集成。

记忆系统的存储架构

源码路径：src/memdir/paths.ts、src/memdir/memdir.ts

Claude Code 的记忆系统是纯文件的——没有数据库、没有向量存储，只有 Markdown 文件和目录结构。

目录布局

~/.claude/projects/<sanitized-git-root>/memory/
├── MEMORY.md                    ← 入口索引（每次对话加载）
├── user_role.md                 ← 用户记忆
├── feedback_testing.md          ← 反馈记忆
├── project_mobile_release.md    ← 项目记忆
├── reference_linear_ingest.md   ← 参考记忆
└── logs/                        ← KAIROS 模式：每日日志
    └── 2026/
        └── 04/
            └── 2026-04-01.md

路径解析链路（getAutoMemPath()）：

1. CLAUDE_COWORK_MEMORY_PATH_OVERRIDE 环境变量（Cowork SDK 全路径覆盖）
2. autoMemoryDirectory 设置（仅限 policySettings/localSettings/userSettings——故意排除 projectSettings，防止恶意仓库将记忆路径指向 ~/.ssh）
3. 默认：<memoryBase>/projects/<sanitized-git-root>/memory/

同一个 Git 仓库的所有 worktree 共享一个记忆目录（通过 findCanonicalGitRoot() 找到真正的 .git 根）。

MEMORY.md 索引

MEMORY.md 是记忆的入口索引，每次对话都完整加载到上下文中：

// memdir.ts:34-38
export const ENTRYPOINT_NAME = 'MEMORY.md'
export const MAX_ENTRYPOINT_LINES = 200
export const MAX_ENTRYPOINT_BYTES = 25_000

索引有双重上限：200 行 AND 25KB。超过任何一条都会被 truncateEntrypointContent() 截断并追加警告。设计原因：p97 的索引文件用 200 行就能覆盖，但有些索引条目特别长（p100 观测到 197KB/200 行），字节上限捕捉这种长行异常。

索引条目格式：

- [Title](file.md) — one-line hook

每条一行，~150 字符以内。MEMORY.md 本身没有 frontmatter——它只是一个链接列表，不是记忆内容。

四类型分类法

源码路径：src/memdir/memoryTypes.ts

记忆被约束为一个封闭的四类型系统，每种类型有明确的 <when_to_save>、<how_to_use> 和 <body_structure> 规范：

类型	存储内容	典型触发
user	用户角色、偏好、技术背景	”我是数据科学家”、“我写了十年 Go”
feedback	用户对 AI 行为的纠正和确认	”别 mock 数据库”、“单 PR 更好”
project	非代码可推导的项目上下文	”合并冻结从周四开始”、“auth 重写是合规要求”
reference	外部系统指针	”pipeline bugs 在 Linear INGEST 项目”

关键设计约束：只存储无法从当前项目状态推导的信息。代码架构、文件路径、git 历史都可以实时获取，不需要记忆。

反馈类型的双通道捕获

feedback 类型的 when_to_save 指令特别强调：

Record from failure AND success: if you only save corrections, you will avoid past mistakes but drift away from approaches the user has already validated, and may grow overly cautious.

这意味着 AI 不仅在用户说”不要这样做”时保存，也在用户说”对，就是这样”时保存。后一种更难捕捉，但同等重要——它防止 AI 的行为随时间漂移。

每条记忆的 Frontmatter 格式

---
name: {{memory name}}
description: {{one-line description — 用于未来判断相关性}}
type: {{user, feedback, project, reference}}
---

{{memory content — feedback/project 类型建议包含 **Why:** 和 **How to apply:** 行}}

description 字段是关键：它不是给人读的摘要，而是给 AI 召回系统做相关性判断的搜索关键词。

智能召回机制

源码路径：src/memdir/findRelevantMemories.ts、src/memdir/memoryScan.ts

不是所有记忆都适合每次对话。系统使用一个轻量级 Sonnet 侧查询来筛选最相关的记忆。

召回流程

用户消息 → findRelevantMemories(query, memoryDir)
  ├── scanMemoryFiles() — 扫描所有记忆文件的 frontmatter
  ├── selectRelevantMemories() — Sonnet 侧查询，从清单中选出 ≤5 条
  └── 返回 [{path, mtimeMs}, ...]

核心是 selectRelevantMemories() 函数，它调用 sideQuery()（一个独立的轻量 API 调用）：

// findRelevantMemories.ts:98-121
const result = await sideQuery({
  model: getDefaultSonnetModel(),  // 用 Sonnet 做筛选（非主模型）
  system: SELECT_MEMORIES_SYSTEM_PROMPT,
  messages: [{
    role: 'user',
    content: `Query: ${query}\n\nAvailable memories:\n${manifest}${toolsSection}`
  }],
  max_tokens: 256,
  output_format: { type: 'json_schema', schema: { ... } },
})

近期工具去噪

当 AI 正在使用某个工具时，召回该工具的使用文档是噪音（对话中已有工作上下文）。recentTools 参数让召回系统跳过这些记忆：

// findRelevantMemories.ts:92-95
const toolsSection = recentTools.length > 0
  ? `\n\nRecently used tools: ${recentTools.join(', ')}`
  : ''

System Prompt 明确指示：“如果已提供最近使用的工具列表，不要选择该工具的使用参考或 API 文档。仍然要选择关于这些工具的警告、陷阱或已知问题——这正是使用时最关键的信息。“

已展示去重

alreadySurfaced 参数过滤之前轮次已展示过的文件路径，让 Sonnet 的 5 槽预算花在新的候选上，而不是重复召回同一文件。

记忆注入 System Prompt 的链路

源码路径：src/memdir/memdir.ts → src/context.ts

loadMemoryPrompt() 是记忆注入的入口，每会话调用一次（通过 systemPromptSection('memory', ...) 缓存）：

// memdir.ts:419-507
export async function loadMemoryPrompt(): Promise<string | null> {
  // 优先级：KAIROS 日志模式 → TEAMMEM 组合模式 → 纯自动记忆
  if (feature('KAIROS') && autoEnabled && getKairosActive()) {
    return buildAssistantDailyLogPrompt(skipIndex)
  }
  if (feature('TEAMMEM') && teamMemPaths!.isTeamMemoryEnabled()) {
    return teamMemPrompts!.buildCombinedMemoryPrompt(...)
  }
  if (autoEnabled) {
    return buildMemoryLines('auto memory', autoDir, ...).join('\n')
  }
  return null
}

注入时机：context.ts 中 getSystemContext() 调用时，记忆 Prompt 作为 system prompt 的一个 section 被组装。MEMORY.md 的内容作为 user context message 注入（而非 system prompt），这样可以利用 Prompt Cache 的 prefix 共享。

KAIROS 模式：每日日志

源码路径：src/memdir/memdir.ts（buildAssistantDailyLogPrompt）

长期运行的 assistant 会话使用不同的记忆策略：

• 标准模式：AI 维护 MEMORY.md 作为实时索引 + 独立记忆文件
• KAIROS 模式：AI 只往日期文件追加日志（logs/YYYY/MM/YYYY-MM-DD.md），不做重组

// 日志路径模式（非字面路径——因为 Prompt 被缓存）
const logPathPattern = join(memoryDir, 'logs', 'YYYY', 'MM', 'YYYY-MM-DD.md')

一个独立的夜间 /dream 技能负责将日志蒸馏为主题文件 + MEMORY.md 索引。

记忆漂移防御

源码路径：src/memdir/memoryTypes.ts（TRUSTING_RECALL_SECTION）

记忆可能过期。系统在 Prompt 中设置了一个专门的 section “Before recommending from memory”：

A memory that names a specific function, file, or flag is a claim
that it existed *when the memory was written*. It may have been
renamed, removed, or never merged. Before recommending it:

- If the memory names a file path: check the file exists.
- If the memory names a function or flag: grep for it.

这个 section 的标题经过 A/B 测试验证：“Before recommending from memory”（行动导向）比 “Trusting what you recall”（抽象描述）效果好（3/3 vs 0/3）。

忽略记忆的严格语义

If the user says to *ignore* or *not use* memory:
proceed as if MEMORY.md were empty.
Do not apply remembered facts, cite, compare against,
or mention memory content.

这解决了 AI 的一个常见反模式：用户说”忽略关于 X 的记忆”，AI 虽然正确识别了代码但仍然加上”不像记忆中说的 Y”——这不是”忽略”，而是”承认然后覆盖”。

Session Memory 与压缩的联动

源码路径：src/services/compact/sessionMemoryCompact.ts

记忆系统与上下文压缩有深度集成。当 tengu_session_memory 和 tengu_sm_compact 两个 feature flag 同时开启时，压缩优先使用 Session Memory 而非传统摘要：

// sessionMemoryCompact.ts:57-61
const DEFAULT_SM_COMPACT_CONFIG = {
  minTokens: 10_000,           // 压缩后至少保留 10K token
  minTextBlockMessages: 5,     // 至少保留 5 条文本消息
  maxTokens: 40_000,           // 最多保留 40K token
}

SM-compact 不调用压缩 API（没有摘要模型），而是直接使用已有的 Session Memory 作为摘要——更快、更便宜、且不会丢失信息。