AI guides

不会做RAG、agent的本地数据管理?都来学Claude Code!附深度拆解

By 陈彪0 viewsSource: Zilliz
不会做RAG、agent的本地数据管理?都来学Claude Code!附深度拆解

企业级场景中,无论是做RAG还是agent,我们都会面临一个问题:出于数据隐私以及合规要求,数据必须保留在本地。但传统的本地存储方案往往存在数据隔离性差、崩溃易丢数据、配置管理混乱、操作不可撤销等问题。

The full text has not been translated yet. The Chinese original is shown below.

企业级场景中,无论是做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的存储架构围绕以下四大原则展开

1. 按项目隔离:解决多项目数据混存问题

将Session(会话)数据严格按项目路径组织,每个项目的会话数据独立存储,避免不同项目的交互记录相互干扰,同时方便按项目维度管理、清理数据。

2. 实时持久化:解决崩溃丢数据问题

采用JSONL(JSON Lines)格式存储核心会话数据,支持流式追加写入,每条消息生成后立即落地,即使程序崩溃也仅能最大程度保障数据完整性。

3. 可追溯:解决上下文链路断裂问题

通过消息链结构(uuid + parentUuid)串联所有交互记录,支持完整的对话回溯和问题定位。

4. 可恢复:解决操作不可撤销问题

基于file-history-snapshot(文件历史快照)机制,在修改文件前自动备份原始内容,降低误操作风险。

03

全局目录搭建思路

Claude Code的所有本地数据集中存储在用户主目录下,核心分为以下两部分

不会做RAG、agent的本地数据管理?都来学Claude Code!附深度拆解

(1)~/.claude.json 完整示例如下

{

"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"

]

}

(2)claude完整目录结构如下:

~/.claude/

├── settings.json # 全局设置(权限、插件、清理周期)

├── settings.local.json # 本地设置(机器特定,不提交Git)

├── history.jsonl # 命令历史记录

│

├── projects/ # 📁 Session 数据(按项目组织,核心目录)

│ └── -Users-xxx-project/ # 路径编码后的项目目录

│ ├── {session-id}.jsonl # 主会话数据(JSONL格式)

│ └── agent-{agentId}.jsonl # 子代理会话数据

│

├── session-env/ # Session 环境变量

│ └── {session-id}/ # 按Session ID隔离

│

├── skills/ # 📁 用户级 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 # 关联Session的任务文件

│

├── file-history/ # 文件编辑历史(按内容hash存储)

│ └── {content-hash}/ # 哈希命名的文件备份目录

│

├── shell-snapshots/ # Shell 状态快照

├── plans/ # Plan Mode 计划存储

├── local/ # 本地工具/node_modules

│ └── claude # Claude CLI 可执行文件

│ └── 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最核心的数据,存储了所有对话历史和上下文,其设计直接决定了数据可靠性和可追溯性。

(1)存储思路:按项目路径编码隔离

存储路径:~/.claude/projects/ + 路径编码后的项目目录;

路径编码规则:将 /、空格、~ 替换为 -;

示例

/Users/bill/My Project → -Users-bill-My-Project

(2)存储格式:JSONL的优势与示例

Session数据采用JSONL(JSON Lines)格式,而非普通JSON,核心原因如下:

不会做RAG、agent的本地数据管理?都来学Claude Code!附深度拆解

JSONL格式完整示例

{"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文件包含多种消息类型,每种类型承担特定职责:

不会做RAG、agent的本地数据管理?都来学Claude Code!附深度拆解

用户消息完整示例如下

{

"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

}

}

}

(4)消息链结构(完整链路示例)如下

消息通过 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恢复原始内容

(2)完整数据结构示例

{

"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

}

(3)关键步骤:备份修改前的内容

trackedFileBackups 存储的是文件修改前的原始内容,而非修改后的内容。这是撤销功能的核心建设思路:

┌──────────────────┐

│ 修改前 app.py │

│ print("old") │───────→ 备份到 snapshot 的 trackedFileBackups

└──────────────────┘

↓

┌──────────────────┐

│ Claude 修改后 │

│ print("new") │───────→ 写入磁盘(覆盖原文件)

└──────────────────┘

↓

┌──────────────────┐

│ 用户执行撤销 │

│ 按下 Esc + Esc │───────→ 从 snapshot 恢复 "old" 内容到磁盘

└──────────────────┘

(4)完整工作流程

  1. 用户发送消息:触发创建空的 file-history-snapshot 记录;
  2. Claude 准备修改文件:系统自动扫描即将修改的文件,将其原始内容备份到 trackedFileBackups;
  3. 执行修改操作:Claude 执行 Edit/Write 指令,将修改后的内容写入磁盘;
  4. 用户发起撤销:按下 Esc + Esc 快捷键,触发撤销流程;
  5. 恢复原始内容:系统从 trackedFileBackups 中读取备份的原始内容,覆盖当前文件,完成撤销。

(5)存储位置与保留策略

  • 快照记录存储:与对应Session绑定,存储在 ~/.claude/projects/-path-to-project/{session-id}.jsonl 中;

  • 文件内容备份:原始文件内容按哈希存储在 ~/.claude/file-history/{content-hash}/ 目录;

  • 默认保留期:30天(与全局 cleanupPeriodDays 配置一致);

  • 配置方式:可通过 ~/.claude/settings.json 中的 cleanupPeriodDays 字段调整保留天数。

(6)相关命令

不会做RAG、agent的本地数据管理?都来学Claude Code!附深度拆解

07

其他重要目录

(1)plugins/ - 插件管理

~/.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

(2)skills/ - 分层存储

Skills 按使用范围做分层存储,适配不同场景的功能定制,层级关系如下:

不会做RAG、agent的本地数据管理?都来学Claude Code!附深度拆解

(3)todos/ - 任务列表存储

  • 存储路径:~/.claude/todos/{session-id}-*.json;

  • 关联关系:文件名包含对应Session ID,确保任务与对话上下文绑定;

  • 内容类型:存储TodoWrite工具生成的任务列表(含任务描述、状态、优先级等)。

(4)local/ - 本地工具存储

  • 核心内容:claude 可执行文件(CLI工具入口)、node_modules/(本地运行依赖);

  • 作用:保障Claude Code在本地环境独立运行,无需依赖外部服务。

(5)其他补充目录

  • shell-snapshots/:存储Shell会话的状态快照(如当前目录、环境变量),支持Shell操作回溯;

  • plans/:存储Plan Mode生成的执行计划(如多步骤编程任务的分解流程);

  • statsig/:缓存特性开关配置(如是否启用新功能),减少重复请求;

  • telemetry/:存储匿名遥测数据(如功能使用频率),用于产品优化;

  • debug/:存储调试日志(含错误堆栈、执行流程),方便问题排查。

作者介绍

不会做RAG、agent的本地数据管理?都来学Claude Code!附深度拆解

陈彪

Zilliz Senior Staff Software Engineer

文章来自于“Zilliz”,作者 “陈彪”。

Related topics

After reading

Join the AINRK community

Read how to join the community and connect with people working in AI.

Community information (opens in a new tab)