内容
# claude-memory-3tier
**停止每次会话都向编码代理解释项目。**
一个小型、自动激活的记忆系统，适用于 Claude Code（以及任何具有会话钩子的代理），该系统在新会话和 `/compact` 后仍能存活。不需要守护进程，不需要向量数据库，不需要云服务 —— 只需要一个 SessionStart 钩子和代理在启动时读取的 markdown 文件，在压缩后重新注入。
它由三个独立的层组成，每个层解决一种**不同的**故障模式：
| 层级 | 它记住什么 | 它存在于哪里 | 自动？ |
|------|-------------------|----------------|------------|
| **0 — 每个仓库的记忆库** | "我正在做什么，已经决定了什么，为什么" | `<repo>/.claude/memory/*.md` | ✅ 通过钩子加载和引导 |
| **1 — 跨项目** | 跨仓库的可重复使用的洞察/模式 | [basic-memory](https://github.com/basicmachines-co/basic-memory) → 你的 Obsidian 保险库 | ✅ 通过 MCP（可选） |
| **2 — 代码结构** | 什么调用什么，影响，调用者/被调用者 | [CodeGraph](https://github.com/) 索引（`.codegraph/`） | ✅ 通过钩子自动初始化（可选） |
只有 **Tier 0** 是必需的，且不依赖其他组件。Tier 1 和 Tier 2 是可选的附加功能。
---
## 问题
上下文窗口是有限的。即使在 1M 个令牌的情况下，长会话也会被 `/compact` 总结 —— 这是**有损**的。在同一个仓库中打开一个新会话，代理已经忘记了架构、决策和你正在进行的工作。
你无法“防止”压缩损失。唯一的解决方法是**将状态外部化**（到文件）并在会话开始时**重新注入**。这就是这个系统的作用 —— 但它是自动的，适用于每个 Git 仓库，包括在压缩后。
## Tier 0 工作原理
一个单独的 `SessionStart` 钩子在 `startup`、`resume`、`clear` 和 **`compact`** 时触发。在每次触发时：
1. 解析 Git 仓库根目录（跳过非项目和 `$HOME`）。
2. 如果缺少，引导 `.claude/memory/`，创建四个骨架文件：`activeContext.md`、`progress.md`、`decisions.md`、`architecture.md`。
3. 将它们的内容重新注入到代理的上下文中。
因为它也会在 `source == "compact"` 时触发，所以你的外部化状态会在**每次压缩后立即重新注入**。钩子只**加载**；你的代理在工作进展时**写入**文件（参见 [SKILL.md](SKILL.md)）。
钩子是**故障开启**的：任何错误都会以 0 退出，并且永远不会阻塞会话。
## 安装
```bash
git clone https://github.com/<you>/claude-memory-3tier.git
cd claude-memory-3tier
./install.sh
```
`install.sh` 将钩子复制到 `~/.claude/hooks/`，并将 `SessionStart` 条目合并到 `~/.claude/settings.json`（幂等，备份首先）。重启 Claude Code。从那时起，你打开的每个 Git 仓库都会自动获得一个记忆库。
### 可选 — Tier 2 (CodeGraph)
如果 `codegraph` CLI 在你的 `PATH` 上，钩子会在后台为任何缺少索引的 Git 仓库自动运行 `codegraph init -i`。跳过它，Tier 0 仍然有效。
### 可选 — Tier 1 (basic-memory → Obsidian)
```bash
uv tool install basic-memory
basic-memory project add ai-memory /path/to/your/ObsidianVault/AI-Memory
```
然后在 `~/.claude.json` 中将其注册为 MCP 服务器：
```json
"basic-memory": { "command": "basic-memory", "args": ["mcp"] }
```
## 退出一个仓库
```bash
touch <repo>/.claude/memory/.disabled
```
## 是否应该提交 `.claude/memory/`？
是的 —— 提交记忆库会记录你的项目状态，并在机器间同步。仓库的 `.gitignore` 应该忽略暂时的标记和索引：
```gitignore
.claude/memory/.codegraph-init-started
.codegraph/
```
## 先前的工作 / 鸣谢
- 每个仓库的 markdown 约定灵感来自 **Cline's Memory Bank**。
- Tier 1 使用 **basic-memory** 由 Basic Machines 构建。
- Tier 2 使用 **CodeGraph** 风格的 AST 索引。
该项目只是将它们组合成一个自动激活、压缩生存的系统。MIT 许可。
