结论

记忆模块数据全部存储在文件系统上，介质为本地磁盘中的纯 Markdown 文件。 不使用 SQLite、不依赖外部数据库、不涉及云存储。唯一例外是远程 memory-stores API（HTTP 端点 /v1/memory_stores），但那是服务端概念，非本地记忆。

四大记忆系统

系统 存储介质 存储路径
自动记忆 (Auto Memory / memdir) 文件系统 (Markdown) ~/.claude/projects/<sanitized-cwd>/memory/
团队记忆 (Team Memory) 文件系统 (Markdown) ~/.claude/projects/<sanitized-cwd>/memory/team/
会话记忆 (Session Memory) 文件系统 (单一 Markdown) ~/.claude/projects/<sanitized-cwd>/<session-id>/session-memory/summary.md
CLAUDE.md / Rules 文件系统 (Markdown) 从 CWD 向上遍历至根目录

1. 自动记忆系统（Auto Memory）

1.1 存储路径

基础路径解析链：

  1. CLAUDE_CODE_REMOTE_MEMORY_DIR 环境变量（远程/CCR 模式）
  2. CLAUDE_CONFIG_DIR 环境变量
  3. 默认：~/.claude

最终路径：

<base>/projects/<sanitized-cwd>/memory/

<sanitized-cwd> 是将项目绝对路径中所有非字母数字字符替换为 - 的结果。例如 /Users/foo/my-project → -Users-foo-my-project。

1.2 文件结构

memory/
├── MEMORY.md              # 索引文件（入口点）
├── user_role.md           # 主题文件
├── feedback_testing.md    # 主题文件
├── project_bugs.md        # 主题文件
└── logs/
    └── YYYY/
        └── MM/
            └── YYYY-MM-DD.md   # 每日日志

  • MEMORY.md：索引文件，每行一个指向主题文件的链接：

    - [用户角色](user_role.md) -- 一句话描述
- [测试反馈](feedback_testing.md) -- 一句话描述

    加载上限：200 行 / 25KB。

  • 主题文件：带 YAML frontmatter 的 Markdown：

    ---
name: 用户角色
description: 用户的身份和偏好
type: user
---
# 实际记忆内容

1.3 记忆类型（4 类）

定义在 src/memdir/memoryTypes.ts：

类型 含义 默认可见性
user 用户角色、目标、偏好 私密
feedback 应避免/应做的指导 私密
project 进行中的工作、bug、事件 偏向团队
reference 外部系统指针 通常团队可见

1.4 启用/禁用控制

优先级链（src/memdir/paths.ts 中 isAutoMemoryEnabled()）：

  1. CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 → 关闭
  2. CLAUDE_CODE_SIMPLE（--bare 模式）→ 关闭
  3. CCR 模式且无 CLAUDE_CODE_REMOTE_MEMORY_DIR → 关闭
  4. settings.json 中 autoMemoryEnabled: false → 关闭
  5. 以上均不满足 → 默认启用

Settings 中可配置：

  • autoMemoryEnabled: boolean — 开关
  • autoMemoryDirectory: string — 自定义路径（支持 ~/ 展开，不允许写入 projectSettings）

1.5 记忆创建机制

方式一：主 Agent 直接写入 系统 prompt 中内嵌了指导模型使用 Write/Edit 工具写入记忆文件的指令。模型直接写主题文件并更新 MEMORY.md。

方式二：后台提取 Agent（src/services/extractMemories/extractMemories.ts）

  • 每次查询循环结束时，通过 handleStopHooks 触发
  • 以 "perfect fork" 方式运行，共享主 Agent 的 prompt cache
  • 工具权限受限（代码只读，仅可在 memory 目录写入）
  • 若主 Agent 本轮已写记忆则跳过
  • 最多 5 轮预算
  • 通过 runForkedAgent() 执行

1.6 记忆召回机制

  • 启动加载：MEMORY.md 在会话开始时加载到系统 prompt 中
  • 相关性筛选（findRelevantMemories.ts）：每次查询时扫描记忆文件 headers，通过小型 Sonnet 查询选出最多 5 个最相关文件
  • 搜索支持：可通过 grep -rn 在 memory 目录中搜索

2. 团队记忆系统（Team Memory）

2.1 存储路径

自动记忆目录的子目录：

<auto-memory-dir>/team/

2.2 启用条件

  • 自动记忆已启用
  • GrowthBook feature flag tengu_herring_clock 为 true

2.3 安全性

在 validateTeamMemWritePath() 和 validateTeamMemKey() 中实现了全面的路径遍历防护：

  • 拒绝 null 字节、.. 段、反斜杠、URL 编码遍历
  • 通过 realpath() 解析符号链接
  • 验证文件必须在真实的团队目录内
  • 使用 lstat() 检测悬空符号链接

3. 会话记忆系统（Session Memory）

3.1 存储路径

~/.claude/projects/<sanitized-cwd>/<session-uuid>/session-memory/summary.md

3.2 工作机制

  • 一个 fork 子 Agent 定期将当前会话的笔记提取到 summary.md 中
  • 由 post-sampling hooks 触发，受 token 阈值和工具调用计数限制
  • 使用 runForkedAgent() 执行，工具权限局限为仅可编辑该记忆文件
  • 被自动压缩系统（sessionMemoryCompact.ts）用于上下文压缩
  • 可通过 /summary 命令手动触发

4. CLAUDE.md / Rules 系统

4.1 文件发现

从 CWD 向上遍历至根目录，收集以下文件：

类型 路径 说明
托管策略 /etc/claude-code/CLAUDE.md 全局策略
用户全局 ~/.claude/CLAUDE.md 私密全局记忆
用户规则 ~/.claude/rules/*.md 用户级规则
项目级 CLAUDE.md（每个祖先目录） 提交到仓库
项目级 .claude/CLAUDE.md 提交到仓库
项目规则 .claude/rules/*.md 提交到仓库
本地 CLAUDE.local.md gitignored，私密项目记忆

4.2 特性

  • @include 指令：文件可通过 @path 语法引用其他文件
  • 优先级：越靠近 CWD 的文件优先级越高（后加载）
  • 内容上限：每文件 40,000 字符（MAX_MEMORY_CHARACTER_COUNT）
  • 截断规则：自动记忆和团队记忆入口点截断至 200 行 / 25KB

5. 关键源码文件

文件 功能
src/memdir/paths.ts 路径解析、启用/禁用逻辑、自动记忆基目录
src/memdir/memdir.ts MEMORY.md 截断、prompt 构建、目录生命周期
src/memdir/memoryTypes.ts 四类记忆类型定义、类型解析、prompt 分段
src/memdir/memoryScan.ts 目录扫描、frontmatter 解析、清单格式化
src/memdir/memoryAge.ts 记忆年龄计算、过期警告
src/memdir/findRelevantMemories.ts 相关性召回（小型 Sonnet 查询）
src/memdir/teamMemPaths.ts 团队记忆路径、安全校验
src/services/extractMemories/extractMemories.ts 后台记忆提取 Agent
src/services/extractMemories/prompts.ts 提取 prompt 模板
src/services/SessionMemory/sessionMemory.ts 会话记忆提取
src/services/SessionMemory/sessionMemoryUtils.ts 会话记忆配置/状态
src/utils/claudemd.ts CLAUDE.md/rules 加载、@include 处理
src/utils/memoryFileDetection.ts 文件分类（auto/team/session/agent 记忆）
src/utils/teamMemoryOps.ts 团队记忆搜索/写入检测
src/utils/envUtils.ts getClaudeConfigHomeDir()
src/utils/sessionStoragePortable.ts sanitizePath()、getProjectsDir()
src/utils/permissions/filesystem.ts 会话记忆路径
src/utils/settings/types.ts autoMemoryEnabled、autoMemoryDirectory 设置项

6. 配置速查

配置项 环境变量 Settings 字段
配置主目录 CLAUDE_CONFIG_DIR （默认 ~/.claude）
禁用自动记忆 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 autoMemoryEnabled: false
自定义记忆路径 CLAUDE_COWORK_MEMORY_PATH_OVERRIDE autoMemoryDirectory
远程记忆目录 CLAUDE_CODE_REMOTE_MEMORY_DIR —
额外指导方针 CLAUDE_COWORK_MEMORY_EXTRA_GUIDELINES —
Simple/Bare 模式 CLAUDE_CODE_SIMPLE —

总结

整个记忆模块的设计遵循 "文件即记忆" 原则：

  • 所有记忆数据以 纯 Markdown 文件 形式存储在本地磁盘
  • 以项目为维度隔离（~/.claude/projects/<sanitized-cwd>/）
  • 模型通过标准的 Read/Write/Edit/Grep 工具与记忆交互
  • 没有 SQLite、没有数据库引擎、不依赖任何云服务
  • 持久化、可移植、可手动编辑

 

# oracle # jvm # 数据库
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

AI 智能体故障排查指南：ChatGPT、API 调用到企业 Agent 异常，怎么快速定位问题

avatar AI编程社区
cover

ChatGPT5.5越狱攻防战：安全防线如何炼成

avatar AI编程社区
cover

GPT-5.6 传闻越来越多：这次 OpenAI 真要把压力给到 Claude 了？

avatar AI编程社区