记忆系统

Claude Code 提供三个不同的内存子系统，每个子系统解决不同的持久性范围。 它们共享通用的文件格式，但在生命周期、受众和同步行为方面有所不同。

自动内存是主要的持久存储。 它住在 ~/.claude/projects/<sanitized-git-root>/memory/，默认启用，并使用两级结构：一个名为 MEMORY.md 和单独的主题文件。

MEMORY.md — 索引

该索引被加载到每个对话的系统提示中。 它的上限为 200 行/25,000 字节。 超出该范围的行会被默默地截断并发出警告。 索引永远不是内容所在的地方——它是一个指针列表：

# MEMORY.md (index file — no frontmatter)
- [User Role](user_role.md) — Senior engineer, Go expert, new to React frontend
- [Feedback — No mock DB](feedback_no_mock_db.md) — Always hit real DB in tests
- [Auth Rewrite Context](project_auth_rewrite.md) — Compliance-driven, not tech debt
- [Linear Project](reference_linear.md) — Pipeline bugs tracked in "INGEST"

主题文件——记忆本身

每个内存都存在于自己的 Markdown 文件中，其中 YAML frontmatter 声明了四个必填字段：

---
name: Feedback — No Mock Database
description: Integration tests must hit a real database, never mocks
type: feedback
---

Don't mock the database in tests.

**Why:** We got burned last quarter when mocked tests passed but the prod
migration failed. Mock/prod divergence masked a broken migration.

**How to apply:** Any test touching the data layer must use a real DB
instance. This is a project-wide testing policy, not a personal preference.

内存类型——封闭的分类法

该代码强制执行四种类型。 类型在解析时进行验证 - 未知值会优雅地降级（文件仍然加载，但类型字段已 undefined).

什么不该保存

来源明确排除了整个类别 - 即使用户询问：

// From memoryTypes.ts — WHAT_NOT_TO_SAVE_SECTION
// Code patterns, conventions, architecture, file paths → read the project
// Git history, recent changes, who-changed-what → `git log` is authoritative
// Debugging solutions or fix recipes → fix is in the code, commit msg has context
// Anything already in CLAUDE.md files
// Ephemeral task details: in-progress work, current conversation context
//
// "These exclusions apply EVEN when the user explicitly asks you to save."
// If they ask to save a PR list → ask what was *surprising* about it.

export const getAutoMemPath = memoize((): string => {
  const override = getAutoMemPathOverride() ?? getAutoMemPathSetting()
  if (override) return override
  const projectsDir = join(getMemoryBaseDir(), 'projects')
  return join(projectsDir, sanitizePath(getAutoMemBase()), 'memory') + sep
}, () => getProjectRoot())

记忆不会在谈话过程中积累——而是被提取出来 after 每个完整的查询循环。 两个不同的代理处理这个问题：

与主代理人相互排斥

主代理在其系统提示中始终有完整的保存指令。 当它自己写入内存文件时，提取代理会完全跳过该范围 - 它通过以下方式检测到这一点： hasMemoryWritesSince()，它扫描助理消息 Write/Edit 针对内存路径的工具调用：

function hasMemoryWritesSince(
  messages: Message[],
  sinceUuid: string | undefined,
): boolean {
  for (const message of messages) {
    // ... scan assistant message content blocks
    const filePath = getWrittenFilePath(block)
    if (filePath !== undefined && isAutoMemPath(filePath)) {
      return true
    }
  }
  return false
}

相关性召回——选择器模型

当新消息到达会话中途时，克劳德不会加载所有内存文件。 相反，轻量级 Sonnet 调用充当选择器 - 它读取 frontmatter 清单并选择 5 相关文件：

// findRelevantMemories.ts — SELECT_MEMORIES_SYSTEM_PROMPT (excerpt)
"Return a list of filenames for the memories that will clearly be useful
to Claude Code as it processes the user's query (up to 5). Only include
memories that you are certain will be helpful based on their name and
description. Be selective and discerning."

// If the model is actively using a tool, its reference docs are skipped
// (the conversation already contains working usage — adding docs is noise)
// BUT warnings, gotchas, and known issues ARE still selected.

export function memoryFreshnessText(mtimeMs: number): string {
  const d = memoryAgeDays(mtimeMs)
  if (d <= 1) return ''
  return (
    `This memory is ${d} days old. ` +
    'Memories are point-in-time observations, not live state — ' +
    'claims about code behavior or file:line citations may be outdated. ' +
    'Verify against current code before asserting as fact.'
  )
}

会话内存解决了与自动内存不同的问题：它是短暂的会话内状态，可以使长时间对话在上下文窗口之后保持一致。 它与自动压缩集成。

模板

每个会话内存文件都遵循固定的部分结构。 自定义模板可以放置在 ~/.claude/session-memory/config/template.md。 默认部分：

# Session Title         ← distinctive 5-10 word title, info-dense
# Current State         ← active work, pending tasks, immediate next steps
# Task specification    ← what the user asked to build + design decisions
# Files and Functions   ← important files + why they're relevant
# Workflow              ← bash commands, order, how to read output
# Errors & Corrections  ← errors encountered + what failed + what to avoid
# Codebase and System Documentation
# Learnings             ← what worked, what didn't
# Key results           ← exact outputs the user requested (tables, answers)
# Worklog               ← terse step-by-step of what was attempted

提取触发器

会话内存提取从后采样挂钩触发。 它受到两个必须同时满足的独立阈值的限制：

// sessionMemoryUtils.ts — DEFAULT_SESSION_MEMORY_CONFIG
{
  minimumMessageTokensToInit:  10_000, // init threshold
  minimumTokensBetweenUpdate:   5_000, // growth since last extraction
  toolCallsBetweenUpdates:          3, // AND tool call count
}
// OR: if no tool calls in the last turn AND token threshold is met
// → extract at natural conversation breaks even without tool activity

// If over budget, the update prompt includes:
"CRITICAL: The session memory file is currently ~N tokens, which exceeds
the maximum of 12000 tokens. You MUST condense the file to fit within this
budget. Aggressively shorten oversized sections by removing less important
details, merging related items, and summarizing older entries. Prioritize
keeping 'Current State' and 'Errors & Corrections' accurate and detailed."

团队内存是一个服务器同步子目录，位于 …/memory/team/。 它被门控后面 TEAMMEM 构建标志并需要 OAuth。 团队目录中的每个文件都映射到 Anthropic 服务器上平面键值存储中的键，其作用域为 GitHub 存储库。

同步语义

// From index.ts — the core sync contract:
//   GET  /api/claude_code/team_memory?repo={owner/repo}
//   PUT  /api/claude_code/team_memory?repo={owner/repo}
//
// Sync rules:
// - Pull: server wins per-key (local files overwritten)
// - Push: delta upload — only keys whose sha256 hash differs from
//         cached serverChecksums are uploaded
// - File deletions do NOT propagate. Deleting a local file won't
//   remove it from the server; the next pull restores it locally.
// - PUT body is batched at 200KB max; larger sets split into
//   sequential PUTs (server upsert-merge semantics make this safe)

文件观察者

会话级文件观察器监视团队内存目录。 当克劳德写入团队记忆文件时， 2 秒去抖推送 自动触发。 观察者使用原生 fs.watch({ recursive: true }) 而不是 chokidar 以避免保存数百个文件描述符。

秘密扫描——客户端守卫

在进行任何推送之前，都会扫描所有内容以查找源自 gitleaks 规则集的 35 多个秘密模式。 检测会阻止推送——秘密永远不会到达服务器：

// secretScanner.ts — sample rules (high-confidence patterns only)
{ id: 'anthropic-api-key',  source: `\\b(sk-ant-api03-[a-zA-Z0-9_\\-]{93}AA)...` },
{ id: 'github-pat',          source: 'ghp_[0-9a-zA-Z]{36}' },
{ id: 'aws-access-token',    source: '\\b((?:A3T[A-Z0-9]|AKIA|ASIA)...)' },
{ id: 'stripe-access-token',  source: '\\b((?:sk|rk)_(?:test|live|prod)_...)' },
// 35 rules total: cloud providers, AI APIs, VCS tokens, payment, crypto

当作为长期助手会话运行时（功能标志 KAIROS），Claude 从两步先写后索引模式切换为 仅附加每日日志:

// buildAssistantDailyLogPrompt() — different memory behavior
// Writes to: <autoMemPath>/logs/YYYY/MM/YYYY-MM-DD.md
// Append-only, timestamped bullets
// MEMORY.md is read-only (maintained by a separate nightly /dream skill)

// What to log:
// - User corrections and preferences
// - Facts about the user, role, or goals
// - Project context not derivable from code
// - Pointers to external systems
// - Anything explicitly asked to remember
//
// The nightly /dream skill distills logs → topic files + MEMORY.md

这在架构上很重要：KAIROS 模式不与 TEAMMEM 组合。 附加到个人日志与双方读写的共享索引从根本上不兼容。 该代码将它们相互排斥。

记忆系统是深门控的。 了解终止开关对于企业部署和测试非常重要：