推荐语
Claude Code 解决了本地数据管理的核心痛点，让RAG和agent开发更安全高效。核心内容： 1. 本地数据管理的五大常见问题与解决方案 2. Claude Code存储架构的四大设计原则 3. 多级配置体系与灵活扩展机制
杨芳贤
53AI创始人/腾讯云(TVP)最具价值专家
企业级场景中，无论是做RAG还是Agent，我们都会面临一个问题：出于数据隐私以及合规要求，数据必须保留在本地。但传统的本地存储方案往往存在数据隔离性差、崩溃易丢数据、配置管理混乱、操作不可撤销等问题。Claude Code 通过一套精心设计的存储体系，系统性地解决了这些痛点。多项目隔离问题：路径编码的项目目录 + Session文件独立存储 → 不同项目数据物理隔离，无交叉干扰；数据丢失问题：JSONL流式追加写入 + 每条消息实时持久化 → 崩溃时仅可能丢失最后一行未写入数据，损失最小化；对话追溯问题：uuid+parentUuid消息链 + 完整消息类型（thinking/tool_use/summary） → 可回溯每一轮交互的上下文、工具调用逻辑；操作不可撤销问题：file-history-snapshot前置备份 + 哈希存储原始内容 + 快捷键撤销 → 支持一键回滚代码修改，无风险；配置灵活度问题：三级配置体系（全局→本地→项目） + 权限优先级（deny>ask>allow） → 兼顾统一管理与局部定制，同时保障安全；功能扩展问题：plugins + skills三级架构 → 支持插件、Skill的灵活扩展，适配不同开发场景。下文是Claude Code 存储架构的核心逻辑、实现方案的详细拆解。01
设计背景：本地 AI 编程助手的存储痛点
对于本地化运行的 AI 编程工具而言，数据存储需要兼顾多维度需求：多项目隔离：开发者通常同时维护多个项目，会话数据若混存会导致溯源困难、管理混乱；数据安全性：AI 对话过程中的实时交互数据（如代码修改、工具调用记录）若未实时持久化，程序崩溃易造成数据丢失；可追溯性：复杂的编程对话包含多轮交互和工具调用，需要完整的上下文链路支撑回溯和问题定位；操作可恢复性：AI 自动修改代码后，若效果不符合预期，需支持快速撤销回滚；配置灵活性：不同机器、不同项目可能有差异化的权限、插件配置，需兼顾全局统一和局部定制。针对这些痛点，Claude Code 确立了四大核心设计原则，作为整个存储架构的底层指导。02
核心设计原则：构建可靠、可管的存储体系
Claude Code的存储架构围绕以下四大原则展开将Session（会话）数据严格按项目路径组织，每个项目的会话数据独立存储，避免不同项目的交互记录相互干扰，同时方便按项目维度管理、清理数据。采用JSONL（JSON Lines）格式存储核心会话数据，支持流式追加写入，每条消息生成后立即落地，即使程序崩溃也仅能最大程度保障数据完整性。通过消息链结构（uuid + parentUuid）串联所有交互记录，支持完整的对话回溯和问题定位。基于file-history-snapshot（文件历史快照）机制，在修改文件前自动备份原始内容，降低误操作风险。03
全局目录搭建思路
Claude Code的所有本地数据集中存储在用户主目录下，核心分为以下两部分
{"projects": {"/Users/xxx/my-project": {"MCPServers": {"jarvis-tasks": {"type": "stdio","command": "python","args": ["/path/to/run_mcp.py"]}}}},"recentPrompts": ["Fix the bug in auth module","Add unit tests"]}
~/.claude/├── settings.json ├── settings.local.json ├── history.jsonl │├── projects/ │ └── -Users-xxx-project/ │ ├── {session-id}.jsonl │ └── agent-{agentId}.jsonl │├── session-env/ │ └── {session-id}/ │├── skills/ │ └── mac-mail/│ └── SKILL.md│├── plugins/ │ ├── config.json │ ├── installed_plugins.json │ ├── known_marketplaces.json │ ├── cache/ │ └── marketplaces/│ └── anthropic-agent-skills/│ ├── .claude-plugin/│ │ └── marketplace.json│ └── skills/│ ├── pdf/│ ├── docx/│ └── frontend-design/│├── todos/ │ └── {session-id}-*.json │├── file-history/ │ └── {content-hash}/ │├── shell-snapshots/ ├── plans/ ├── local/ │ └── claude │ └── node_modules/ │├── statsig/ ├── telemetry/ └── debug/
04
Claude Code配置文件层级设计
为兼顾全局统一配置和局部定制需求，Claude Code设计了三级配置体系，优先级从高到低依次为：项目级配置 > 本地配置 > 全局配置。
┌─────────────────────────────────────────┐│ 项目级配置 │ 优先级最高│ 项目/.claude/settings.json │ 项目专属，覆盖其他配置├─────────────────────────────────────────┤│ 本地配置 │ 机器特定，不提交版本控制│ ~/.claude/settings.local.json │ 覆盖全局配置├─────────────────────────────────────────┤│ 全局配置 │ 优先级最低│ ~/.claude/settings.json │ 基础默认配置└─────────────────────────────────────────┘
（1） ~/.claude/settings.json（全局设置）
{ "$schema": "https://json.schemastore.org/claude-code-settings.json", "permissions": { "allow": ["Read(**)", "Bash(npm:*)"], "deny": ["Bash(rm -rf:*)"], "ask": ["Edit", "Write"] }, "enabledPlugins": { "document-skills@anthropic-agent-skills": true }, "cleanupPeriodDays": 30}
（2） ~/.claude/settings.local.json（机器特定，不提交版本控制）
{ "permissions": { "allow": ["Bash(git:*)", "Bash(docker:*)"] }, "env": { "ANTHROPIC_API_KEY": "sk-ant-xxx" }}
（3）项目/.claude/settings.json（项目专属）
{ "permissions": { "allow": ["Bash(pytest:*)"] }}
合并规则：最终配置 = 全局配置 + 本地配置覆盖 + 项目配置覆盖（后加载的配置覆盖先加载的同字段）；权限优先级：deny > ask > allow > 默认行为（严格遵循，保障操作安全）。05
Session数据存储：核心交互数据的持久化设计
Session是Claude Code最核心的数据，存储了所有对话历史和上下文，其设计直接决定了数据可靠性和可追溯性。存储路径：~/.claude/projects/ + 路径编码后的项目目录；
/Users/bill/My Project → -Users-bill-My-Project
Session数据采用JSONL（JSON Lines）格式，而非普通JSON，核心原因如下：
{"type":"user","message":{"role":"user","content":"Hello"},"timestamp":"2026-01-05T10:00:00Z"}{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}]}}{"type":"user","message":{"role":"user","content":"Help me fix this bug"}}
使用JSONL，让每个消息独立一行的核心价值在于：
（3）Session JSONL数据结构（完整消息类型与示例）Session文件包含多种消息类型，每种类型承担特定职责：
{"type": "user","uuid": "7d90e1c9-e727-4291-8eb9-0e7b844c4348","parentUuid": null,"sessionId": "e5d52290-e2c1-41d6-8e97-371401502fdf","timestamp": "2026-01-05T10:00:00.000Z","message": {"role": "user","content": "分析一下这个项目的架构"},"cwd": "/Users/xxx/project","gitBranch": "main","version": "2.0.76"}
助手消息完整示例（含工具调用与token使用）如下
{"type": "assistant","uuid": "e684816e-f476-424d-92e3-1fe404f13212","parentUuid": "7d90e1c9-e727-4291-8eb9-0e7b844c4348","message": {"role": "assistant","model": "claude-opus-4-5-20251101","content": [{"type": "thinking","thinking": "用户想了解项目架构，我需要先查看目录结构..."},{"type": "text","text": "让我先看一下项目结构。"},{"type": "tool_use","id": "toolu_01ABC","name": "Bash","input": {"command": "ls -la"}}],"usage": {"input_tokens": 1500,"output_tokens": 200,"cache_read_input_tokens": 50000}}}
消息通过 uuid（自身唯一标识）和 parentUuid（父消息标识）形成完整链式结构，支持全链路回溯：
file-history-snapshot (messageId: A)↓user (uuid: A, parentUuid: null) ← 用户提问（链路起点）↓assistant (uuid: B, parentUuid: A) ← AI思考 + 文本回复↓assistant (uuid: C, parentUuid: B) ← AI工具调用（如Bash命令）↓user (uuid: D, parentUuid: C) ← 工具执行结果（如Bash输出）↓assistant (uuid: E, parentUuid: D) ← AI基于工具结果继续回复↓summary (leafUuid: E) ← 会话摘要（关联链路终点）
06
file-history-snapshot：实现操作可撤销的核心机制
这是Claude Code保障代码修改可恢复的关键设计，核心逻辑是修改前备份原始内容，撤销时恢复，所有细节如下：（1）核心定义：什么是Checkpoint，作用如何？每当用户发送新消息时，Claude Code会自动创建 file-history-snapshot，专门记录「即将被修改的文件的原始内容」，作为撤销操作的数据源：
用户提问 → 创建snapshot（备份原始内容） → Claude修改文件 → 用户不满意 → Esc+Esc撤销↑ ↓存储原始内容 ←─────────────────────────────── 从snapshot恢复原始内容
{"type": "file-history-snapshot","messageId": "7d90e1c9-e727-4291-8eb9-0e7b844c4348","snapshot": {"messageId": "7d90e1c9-e727-4291-8eb9-0e7b844c4348","trackedFileBackups": {"/path/to/file1.py": "原始文件内容\ndef hello():\n print('old')","/path/to/file2.js": "// 原始内容..."},"timestamp": "2026-01-05T10:00:00.000Z"},"isSnapshotUpdate": false}
trackedFileBackups 存储的是文件修改前的原始内容，而非修改后的内容。这是撤销功能的核心建设思路：
┌──────────────────┐│ 修改前 app.py ││ print("old") │───────→ 备份到 snapshot 的 trackedFileBackups└──────────────────┘↓┌──────────────────┐│ Claude 修改后 ││ print("new") │───────→ 写入磁盘（覆盖原文件）└──────────────────┘↓┌──────────────────┐│ 用户执行撤销 ││ 按下 Esc + Esc │───────→ 从 snapshot 恢复 "old" 内容到磁盘└──────────────────┘
- 用户发送消息：触发创建空的 file-history-snapshot 记录；
- Claude 准备修改文件：系统自动扫描即将修改的文件，将其原始内容备份到 trackedFileBackups；
- 执行修改操作：Claude 执行 Edit/Write 指令，将修改后的内容写入磁盘；
- 用户发起撤销：按下 Esc + Esc 快捷键，触发撤销流程；
- 恢复原始内容：系统从 trackedFileBackups 中读取备份的原始内容，覆盖当前文件，完成撤销。
- 快照记录存储：与对应Session绑定，存储在 ~/.claude/projects/-path-to-project/{session-id}.jsonl 中；
- 文件内容备份：原始文件内容按哈希存储在 ~/.claude/file-history/{content-hash}/ 目录；
- 默认保留期：30天（与全局 cleanupPeriodDays 配置一致）；
- 配置方式：可通过 ~/.claude/settings.json 中的 cleanupPeriodDays 字段调整保留天数。
07
其他重要目录
~/.claude/plugins/├── config.json插件全局配置（如启用/禁用规则）├── installed_plugins.json已安装插件列表（含版本、状态）├── known_marketplaces.json插件市场源配置（如Anthropic官方市场）├── cache/插件下载缓存（避免重复下载）└── marketplaces/市场源存储目录└── anthropic-agent-skills/官方插件市场├── .claude-plugin/│ └── marketplace.json市场元信息└── skills/市场提供的Skills├── pdf/PDF处理相关Skill├── docx/Word文档处理相关Skill└── frontend-design/前端设计相关Skill
Skills 按使用范围做分层存储，适配不同场景的功能定制，层级关系如下：
- 存储路径：~/.claude/todos/{session-id}-*.json；
- 关联关系：文件名包含对应Session ID，确保任务与对话上下文绑定；
- 内容类型：存储TodoWrite工具生成的任务列表（含任务描述、状态、优先级等）。
- 核心内容：claude 可执行文件（CLI工具入口）、node_modules/（本地运行依赖）；
- 作用：保障Claude Code在本地环境独立运行，无需依赖外部服务。
- shell-snapshots/：存储Shell会话的状态快照（如当前目录、环境变量），支持Shell操作回溯；
- plans/：存储Plan Mode生成的执行计划（如多步骤编程任务的分解流程）；
- statsig/：缓存特性开关配置（如是否启用新功能），减少重复请求；
- telemetry/：存储匿名遥测数据（如功能使用频率），用于产品优化；
-
debug/：存储调试日志（含错误堆栈、执行流程），方便问题排查。
陈彪
Zilliz Senior Staff Software Engineer
粤ICP备14082021号
免费POC，
零成本试错
