我的代码库终于有记忆了

我的代码库终于有记忆了

我用 Claude Code + Obsidian 搭建了永不失忆的 AI 架构大脑

作者：一只阿木木我相信：在 AI 时代，每个普通人都该拥有一个自动生长的知识系统。

先说一个让每个程序员都后背发凉的场景

2025 年 11 月，你花了两个小时搞定了一个诡异的 PostgreSQL 锁竞争问题。

你心想：这个解法太妙了，下次肯定还会遇到，我得记下来。

然后，你没记。

2026 年 5 月，你盯着同样的错误堆栈，脑子里一片空白。你隐约记得自己解决过这个问题，但想不起来怎么做的，也找不到任何记录。你又花了两个小时，从头摸索，走了一遍同样的弯路。

你花了两个小时调试一个棘手的 SQL 问题，终于搞定了，心想"我应该把这个记下来"——然后你没有记。六个月后，你盯着同样的报错，完全不记得上次怎么解决的。

这不是个人习惯问题。这是一个系统性的架构缺陷：你的工作没有记忆。

程序员面临的，是两个叠加的失忆问题

在我们深入解决方案之前，先把问题说清楚——因为大多数文章只提到了一半。

问题一：会话之间的失忆。 每次你打开新会话，就要重新解释你的项目：技术栈、过去的决策、当前的 bug、还有哪些没做完。Claude Code 对上一个会话毫无记忆。 

问题二：代码库理解的重复消耗。 Claude Code 每次都要重新读取你的项目文件来理解结构。一个有约 40 个文件的项目，光是让 Claude 定位自己，就要烧掉约 20,000 个 token——还没问任何问题。如果你一天开 10 个会话，那就是 20 万个浪费的 token。

两个问题叠加的结果是：每次开启新会话，你都是从零开始。你解释同样的架构决策，重新描述代码库里同样的怪癖，看着 Claude 犯你三个会话前就纠正过的同类错误。

这就是为什么很多程序员用了一段时间 Claude Code 之后会感觉"有点鸡肋"——工具的能力没问题，但上下文一直在漏。

你在用一个有顶级驾驶技术的司机，但每次上车他都不认识你，也不知道你要去哪。

解法不是"更好的备忘录"，而是给代码库装一个大脑

好消息是，Claude Code hooks 给了你一个干净的修复方式。你可以建立一个系统，自动捕获每个会话里发生的事情，提炼出可复用的经验，写进一个随时间变得更智能的 Obsidian vault。

核心思路是：把你的 Obsidian vault 变成代码库的外部大脑。

你的 Obsidian vault 是上下文知识的居所——思考过程、决策记录、研究成果——让 Claude 的输出真正贴近你的具体情况，而不是泛泛而谈。因为 Obsidian 把一切存储为本地机器上的纯 Markdown 文件，没有专有格式，没有云锁定，Claude Code 可以零摩擦地读写它。它就是一个 .md 文件的文件夹，Claude 已经知道怎么处理这些文件。

你需要的不是工具，是一套分层记忆架构

在动手配置之前，先理解一件事：这套系统之所以有效，是因为它把"记忆"按更新频率分成了不同的层。Obsidian 负责处理"决定了什么"（声明式记忆）。每一层有不同的更新节奏，不同的用途。

第一层：项目上下文（每天更新）

当前在做什么，今天遇到了什么问题，还有哪些没解决。

第二层：架构决策（每次架构变更时更新）

为什么选这个技术栈，哪个方案被否决了，当时的理由是什么。

第三层：代码模式与经验教训（每次解决新问题时更新）

什么写法踩过坑，什么模式在这个代码库里特别好用，哪些事后复盘值得保留。

第四层：身份配置（每季度更新一次）

你的技术偏好、命名习惯、代码风格要求，让 Claude 在所有项目里都像你的老搭档而不是陌生人。

没有这个分层，vault 在几周内就会变成噪音。有了它，每一层的信息都恰好在需要的时候出现。

实战：手把手建立代码库记忆系统

Step 1：建立 vault 文件夹结构

推荐的文件夹结构是：

text

~/claude-memory/
├── Patterns/       ← 可复用的代码模式
├── Mistakes/       ← 已知的坑，避免重蹈覆辙
├── Decisions/      ← 架构决策记录
├── Context/        ← 项目专属上下文
├── Sessions/       ← 会话日志
└── Index.md        ← 自动更新的总目录

这个 Obsidian 记忆系统通过 Obsidian vault 为 Claude Code 提供一个结构化的持久大脑，跨会话存储信息。它在独立空间里组织项目专属数据，追踪短期会话目标、每日活动日志，以及架构决策和可复用代码模式等长期知识。通过弥合临时 AI 对话和永久文档之间的鸿沟，这套技能确保 Claude 记住你的偏好、过去的 bug 和设计选择，显著减少上下文切换和重复解释。

Step 2：写好 CLAUDE.md——这是整个系统最重要的文件

CLAUDE.md 是一个静态 Markdown 文档，在每个会话开始时加载进 Claude 的上下文。 8 把它想成你的工牌。你走进公司，工牌说明你的姓名、职位、权限等级。在门口刷一次卡，所有人就知道你是谁了。这就是 CLAUDE.md 在每个会话里做的事。

一份给程序员的 CLAUDE.md 模板应该包含：

Markdown

# 项目：[项目名]
## 技术栈
- 后端：Node.js + TypeScript + PostgreSQL
- 前端：React + Vite
- 部署：Docker + AWS ECS
## 架构约定
- 所有数据库查询走 Repository 层，不允许在 Controller 直接写 SQL
- API 响应统一用 Result<T, Error> 包装
- 错误处理：业务错误抛 AppError，系统错误记 log 后转 500
## 当前工作重点
- 正在重构 UserService，把身份验证逻辑拆到单独模块
- 已知问题：order_items 表在并发写入时有锁竞争，暂未解决
## 记忆文件位置
- 架构决策：~/claude-memory/Decisions/
- 踩坑记录：~/claude-memory/Mistakes/
- 项目上下文：~/claude-memory/Context/[项目名]/
## 工作规则
- 在做任何架构决策前，先检查 Decisions/ 里有没有相关记录
- 每次解决了一个棘手问题，记到 Mistakes/ 里
- 会话结束前，更新 hot cache

关键的上下文文件包括：Context/（项目专属笔记）、Decisions/（过去的架构选择）、Mistakes/（已知的坑）。Claude Code 在会话开始时读取 CLAUDE.md，并在整个对话中把它作为上下文。对于较大的 vault，你还可以指示 Claude 在遇到相关问题时搜索特定文件。

Step 3：建立"架构决策日志"——最被忽视的程序员超级武器

Decisions/ 是这套系统里回报最高的文件夹。每一次你做了重要的技术选择，花 3 分钟写一条决策记录。

Markdown

# 决策：选择 BullMQ 而不是 Celery 做任务队列
日期：2026-03-15
状态：已执行
## 背景
需要一个可靠的任务队列处理异步邮件发送和报表生成。
## 考虑过的方案
1. BullMQ（Redis-based，Node.js 原生）
2. Celery（Python，需要混合语言栈）
3. AWS SQS（managed，但需要额外依赖）
## 决策
选择 BullMQ。
## 理由
- 和现有 Node.js 栈零摩擦
- Redis 我们已经在用，无需新基础设施
- Celery 需要引入 Python 进程，运维复杂度不划算
## 已知风险
- Redis 宕机会导致任务丢失，需要做持久化配置
- 高并发下需要监控 Redis 内存
## 6 个月后回顾
（待填写）

为什么这个文件夹如此关键？因为它让 AI 在你做新决策的时候，能主动找到你自己的历史。

开发者正在使用这套系统，让 Claude 在做新的架构决策之前，先检查过去的架构决策记录。

想象这个场景：三个月后，你想把某个模块从 REST 改成 GraphQL。你问 Claude，Claude 先去读 Decisions/ 文件夹，找到你当初选 REST 时的理由，然后说："你 2026 年 1 月的决策记录里提到，选 REST 是因为客户端是第三方 iOS 团队，他们不支持 GraphQL 客户端。这个约束现在还存在吗？"

这就是有记忆的 AI 和没有记忆的 AI 之间的本质差距。

Step 4：让 wiki-update 自动把代码库变成知识图谱

把 claude-obsidian 指向一个 GitHub 仓库，它会构建一个架构 wiki：模块作为实体，模式作为概念，commit 作为来源。新工程师入职？/wiki 命令直接给你代码库的知识图谱。

操作流程：

Bash

# 在你的项目目录里
cd ~/projects/my-app
# 让 claude-obsidian 扫描代码库并生成架构 wiki
/wiki-update

/wiki-update 读取你的项目，判断哪些内容值得保留，并提炼进你的 Obsidian vault——架构决策、你发现的模式、关键概念、你评估过的权衡取舍。它不是复制代码或生成文件列表，而是提炼那些你三个月后会忘记的东西。 下次从同一个项目运行时，它会通过 git log 检查上次同步后变化了什么，只处理增量部分。

这意味着：你每一次有意义的 commit，都可以转化成 wiki 知识的一次更新。代码库在增长，知识图谱也在同步增长。

Step 5：配置 Hot Cache——解决"每次开会话都要重新交代背景"

Hot cache（wiki/hot.md）是革命性的。在会话结束时，Claude 写入最近上下文的摘要。下一个会话从完全预热的状态开始——不需要"还记得我们之前聊的……"，不需要重新摄入，你的会话连续性可以跨越重启存活。

建立这个习惯：

text

# 每次会话结束前输入
update hot cache
# hot.md 会自动包含：
- 今天在做什么（当前任务）
- 卡在哪个问题上（阻碍）
- 已经排除的方向（避免重复尝试）
- 明天要继续的地方（下一步）

每个会话，Claude Code 都会写入一个结构化摘要。下个会话开始时，agent 在做任何事之前都先读取最近的会话日志。这创造了真正的连续性——agent 不是每次从零开始，它知道你昨天在做什么，记得你偏好简洁的条目而不是长段落，知道某个功能分支已经暂停。

Step 6：把 Mistakes/ 文件夹变成你的"防坑手册"

随着时间推移，vault 里积累的是来自你实际工作的真实知识——不是通用的编程建议，而是针对你的项目的具体模式和决策。

每次踩了一个坑，花 2 分钟记下来：

Markdown

# 坑：PostgreSQL advisory lock 死锁
日期：2026-05-20
项目：[项目名]
严重程度：高（导致生产事故）
## 触发条件
两个并发请求同时调用 acquire_lock(user_id)，
且都在等待对方释放锁，形成死锁。
## 根本原因
Advisory lock 和事务锁的顺序不一致：
- 请求 A：先拿 advisory lock，再开事务
- 请求 B：先开事务，再拿 advisory lock
## 解决方案
统一改为：先开事务，在事务内用 pg_try_advisory_xact_lock()
锁会随事务结束自动释放，无需手动 release。
## 关键代码
BEGIN;
SELECT pg_try_advisory_xact_lock($1) INTO lock_acquired;
IF NOT lock_acquired THEN ROLLBACK; END IF;
-- 实际业务逻辑
COMMIT;
## 预防方法
所有用到 advisory lock 的地方，都要 code review 检查锁的获取顺序。

这条记录一旦进入 Mistakes/，下次有类似场景时，Claude 在给你建议之前，会先在这个文件夹里搜索，然后告诉你："你有一条关于 advisory lock 死锁的踩坑记录，需要先看一下吗？"

Claude 看过你写的每一条笔记。它能找到你遗漏的关联——不是因为它比你聪明，而是因为它记住了你几个月内积累的所有内容。

Step 7：配置 git hook，让知识图谱随代码自动更新

推荐的完整工作流是：

text

打开 Claude Code 会话
│
├── /resume          ← 加载 vault 上下文（最近日志、决策、进度）
│
├── 查询 graph.json  ← 理解代码结构，无需重新读取所有文件
│
├── 写代码           ← 功能开发、bug 修复、重构
│
├── /save            ← 在 vault 里生成会话日志
│
└── git commit       ← hook 自动重建知识图谱

在 .git/hooks/post-commit 里加入：

Bash

#!/bin/bash
# 每次 commit 后，自动更新代码库知识图谱
echo "更新代码库 wiki..."
cd ~/claude-memory && claude --headless "/wiki-update ~/projects/my-app"
echo "完成。"

随着时间推移，vault 积累的是来自你真实工作的真实知识——不是通用编程建议，而是针对你项目的具体模式和决策。

真实效果：用数字说话

使用 Graphify + Obsidian 记忆系统后，每个会话的 token 消耗减少了 71.5 倍，并实现了跨会话的持久记忆，无需浪费 token 重新读取文件。

用人话翻译一下这个数字：

• 以前：每天 10 个会话 × 20,000 token/会话（光是定位代码库）= 20 万 token 的纯浪费
• 之后：知识图谱已经预编译好，Claude 直接导航，不需要重新读取全部文件

这 20 万 token，以当前 Claude 的价格大约是每天节省几美元。乘以 250 个工作日，是每年节省几百美元的 API 成本。但更重要的是：节省的是你等 Claude "理解项目" 的那段时间。

一个更深的价值：让 AI 成为你的主动治理伙伴

到目前为止我们说的都是"记忆"。但这套系统能做的，比记忆更深。

当你有了完整的决策日志，Claude 就能做主动治理，而不是被动执行。

场景举例：

你今天想把一个核心服务从同步改成异步。你把方案告诉 Claude，它先去 Decisions/ 读档案，然后说：

"在你 2025 年 9 月的复盘里，你提到上次把这个服务改成异步时出现了消息丢失的问题，因为没有做幂等处理。你 2026 年 1 月的路线图承诺在 Q2 之前完成这部分重构。你现在的改法里包含幂等处理了吗？"

这不是检索，这是决策审计。AI 把你自己说过的话还给你，让你对自己的历史负责。

这才是"代码库有记忆"真正的威力所在：不只是让 AI 记住你做了什么，而是让 AI 帮你坚守你自己定下的原则。

一个坦诚的提醒：这套系统的边界

我不想给你卖一个完美的故事，所以有几点真话要说。

问题一：格式一致性是挑战。

一个会话里，Claude 把某个条目格式化成 ## 决策：服务 A，下个会话里写成 **服务 A** 的决策，再下一个会话变成 服务 A - 2026 年 4 月。想用程序解析这些？祝你好运。

解法：在 CLAUDE.md 里明确规定格式模板，并在 lint 时检查格式一致性。

问题二：文件多了以后查询成本上升。

token 成本随文件数线性增长。如果你在运行 LLM Wiki，index 文件对每个 wiki 页面有一行摘要。10 个文件时，加载 index 大约需要 750 个 token。1,000 个文件时，你每次查询都要先花数千 token 扫描目录，Claude 才能开始推理。

解法：把知识分层，用 hot.md 处理高频访问的上下文，只在必要时才加载完整 index。

问题三：这套系统只适合你一个人维护。

两个 agent 无法安全地同时读写同一个 Markdown 文件。如果你在运行多个自主 agent（这个方向发展很快），你需要一个能处理并发访问的数据存储。SQLite 用 WAL 模式原生支持这个；Markdown 文件在两个进程同时写入时会悄悄损坏你的数据。

解法：单人使用这套系统很稳；如果要多人协作，需要加一层协调机制，或者在 vault 之外另建团队共享的知识库。

30 天行动计划：从今天开始，代码库终于有记忆了

第一天（45 分钟）：建立基础结构

Bash

# 1. 创建记忆 vault
mkdir -p ~/claude-memory/{Patterns,Mistakes,Decisions,Context,Sessions}
touch ~/claude-memory/Index.md
# 2. 在你最重要的项目里写第一份 CLAUDE.md
cd ~/projects/my-main-project
touch CLAUDE.md  # 按上面的模板填写
# 3. 在 Obsidian 里把 claude-memory 打开为 vault
# 打开 Obsidian → 打开其他保险库 → 选择 ~/claude-memory/

第一周（每天 10 分钟）：建立记录习惯

text

每天编码结束前做两件事：
1. 如果今天解决了一个有价值的问题 → 写一条 Mistakes/ 记录
2. 会话结束前 → update hot cache

第二周（累计 30 分钟）：补充历史决策

text

把脑子里记着的 3-5 个历史架构决策写进 Decisions/：
- 为什么用这个数据库
- 为什么选这个框架
- 曾经放弃过的方案和原因

第三周：配置 git hook，让更新自动化

Bash

# 在主项目里配置 post-commit hook（参考 Step 7）
# 验证：做一次 commit，检查 wiki/ 是否自动更新

第四周：验收——用系统回答一个真实问题

找一个你三周前遇到但已经忘记细节的问题，问 Claude：

text

查一下我有没有关于 [某个技术点] 的记录，
包括当时的解决方案和踩过的坑。

如果 Claude 能给你拿出具体的记录并引用具体页面，恭喜——你的代码库终于有了记忆。

写在最后

每个程序员都有一个时刻：

你在 Stack Overflow 上看到一个答案，心想"我当时怎么没想到这个"。然后你翻了翻自己 18 个月前的 commit，发现你当时其实想到了，写进了注释里，然后忘了。

这件事会反复发生，直到你建立一个真正的记忆系统。

我试过很多 PKM 方案，大多数最终在自身重量下崩溃了。这一套没有——因为这次终于不是我在维护它，Claude 和 Obsidian 承担了繁重的工作，把过去那个脆弱的系统变成了真正能持久运转的东西。

代码库会忘事，但你不必每次都从零开始。

raw/ → ingest → wiki → query。

你的代码库，终于有记忆了。