内容
# 嵌套记忆
> 持久化、压缩的长期记忆，适用于 Claude 代码 —— 通过 MCP。
> 灵感来自 **嵌套学习** (NeurIPS 2025, [arXiv:2512.24695](https://arxiv.org/abs/2512.24695))
---
## 问题
Claude 代码在处理任务方面表现出色，但每次会话结束时就会忘记所有内容。
您发现自己每次都在重复相同的上下文：
- *"我们决定使用 SQLite 而不是 Postgres —— 记住吗？*
- *"该 API 的速率限制为 100 req/min，我上周告诉过你。*
- *"我们的编码风格是 X，别再建议 Y 了。*
外部记忆工具存在，但它们带来了摩擦：需要运行的向量数据库、需要调用的 API、需要维护的嵌入。大多数团队放弃了这些工具，而是手动粘贴上下文。
## 解决方案
`nested-memory` 为 Claude 代码提供了**持久化、自我压缩的长期记忆** —— 全部存储在一个本地 SQLite 文件中，无需任何基础设施。
记忆通过 4 层自动蒸馏：
```
L4：元数据 — 自我模型，系统级模式 [自动，阈值：30]
L3：程序性 — 结晶的工作流程，习惯 [自动，阈值：100]
L2：语义性 — 提取的事实，决策 [自动，阈值：50]
L1：情景记忆 — 原始观察，会话笔记 [会话结束]
↑ 每一层都由 LLM "压缩函数" 蒸馏
```
> **L4 控制：** 默认情况下，自动压缩是开启的。要手动保持 L4（元数据）：
> ```bash
> python3 cli.py compress --no-auto-l4
> ```
**使用嵌套记忆之前：**
```
会话 1："我们选择了 React，速率限制为 100/min。"
会话 2：[Claude 对会话 1 没有任何记忆]
会话 3：[Claude 再次建议 Postgres]
```
**使用嵌套记忆之后：**
```
会话 1：memory_add "选择了 React，速率限制为 100/min" → L1
→ 夜间压缩：关键事实提升到 L2（语义性）
会话 2：memory_search "架构" → 立即找到 React 决策
会话 3：Claude 在您输入之前就已经知道约束条件
```
**关键属性：**
- 🗄️ 零基础设施 — 单个 SQLite 文件，无需服务器
- 🔍 通过 SQLite FTS5 进行全文搜索（无需嵌入）
- 🤖 通过 Claude Haiku/Sonnet 进行 LLM 压缩（Anthropic API）
- 🏷️ 标签 + 重要性过滤，用于精确检索
- 🔌 适用于 Claude 代码 MCP 服务器 **和** OpenClaw 扩展（同一数据库）
- 🧪 83 个测试，94% 覆盖率
---
## 快速入门（Claude 代码）
### 步骤 1：克隆和安装
```bash
git clone https://github.com/tak633b/nested-memory.git
cd nested-memory
pip install anthropic
./install.sh
```
`install.sh` 处理以下所有操作：
- 数据库模式初始化
- 用于后台压缩的 launchd 作业（仅限 macOS）
- OpenClaw 插件注册（如果 `openclaw` 在您的 PATH 中）
### 步骤 2：注册为 MCP 服务器
```bash
claude mcp add nested-memory python3 /path/to/nested-memory/mcp_server.py
```
或手动添加到 `~/.claude.json`：
```json
{
"mcpServers": {
"nested-memory": {
"command": "python3",
"args": ["/path/to/nested-memory/mcp_server.py"],
"env": {
"ANTHROPIC_API_KEY": "sk-ant-..."
}
}
}
}
```
### 步骤 3：添加到项目的 `CLAUDE.md`
将以下内容粘贴到项目的 `CLAUDE.md` 中，以便 Claude 代码自动使用记忆：
```markdown
## 记忆
使用 `nested-memory` MCP 工具：
- 使用 `memory_add` 存储重要决策（层级=2，重要性≥0.8）
- 在回答有关先前工作的问题之前，使用 `memory_search` 搜索过去的上下文
- 长时间会话后，使用 `memory_compress` 压缩 L1 记忆
```
就这样。Claude 代码现在将跨会话记住内容。
---
## Claude 桌面版
将以下内容添加到 `claude_desktop_config.json`：
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"nested-memory": {
"command": "python3",
"args": ["/path/to/nested-memory/mcp_server.py"],
"env": {
"ANTHROPIC_API_KEY": "sk-ant-..."
}
}
}
}
```
---
## MCP 工具
| 工具 | 描述 |
|------|-------------|
| `memory_add` | 将记忆添加到特定层级 |
| `memory_search` | 跨记忆进行全文搜索 |
| `memory_compress` | 通过 LLM（异步）压缩层级 |
| `memory_compress_status` | 检查压缩作业进度 |
| `memory_stats` | 显示按层级划分的记忆数量 |
| `memory_list` | 列出某一层级的记忆 |
| `memory_entities` | 列出跟踪的实体（人员，概念） |
---
## 使用示例
### 存储决策
```
使用 memory_add 存储：
"选择 SQLite 而不是 PostgreSQL — 零基础设施，本地优先"
→ 层级=2，标签=["决策", "架构"]，重要性=0.9
```
### 搜索过去的上下文
```
使用 memory_search 查找有关 "SQLite" 的记忆
```
### 从对话中提取事实
```
使用 memory_add 从此次对话中提取关键事实：
"我们讨论了 React 与 Vue。选择了 React，因为生态系统更大，团队更熟悉。"
→ 层级=1，标签=["决策", "前端"]
```
### 长时间会话后压缩 L1
```
使用 memory_compress 压缩层级=1
→ 立即返回 job_id（在后台运行）
使用 memory_compress_status 和 job_id=<id>
→ {"status": "done", "compressed": true, "new_memory_id": "..."}
```
### 项目范围的记忆和标签
```
# 保存
memory_add: "项目 A：API 速率限制为 100 req/min"
→ 层级=1，标签=["项目-a", "api"]，重要性=0.7
# 召回
memory_search: 查询="速率限制" 标签=["项目-a"]
```
---
## CLI（独立使用）
```bash
# 添加
python3 cli.py add "Alice 更喜欢视觉学习" --layer 2 --tags "person,profile" --importance 0.9
# 搜索
python3 cli.py search "Alice" --layer 2 --limit 5
# 压缩 L1 → L2
python3 cli.py compress --from-layer 1
# 统计信息
python3 cli.py stats
# 按层级列出
python3 cli.py list --layer 1
# 实体
python3 cli.py entities --type person
```
`--layer` 接受数字（`1`）和名称（`episodic`、`semantic`、`procedural`、`meta`）。
---
## 数据库
默认路径：`~/.nested-memory.db`
使用自定义路径：
```bash
python3 cli.py stats --db /path/to/my-memory.db
```
或通过 MCP 环境变量设置：
```json
"env": {
"NESTED_MEMORY_DB": "/path/to/my-memory.db",
"ANTHROPIC_API_KEY": "sk-ant-..."
}
```
> **提示：** 要按项目范围划分记忆，请将 `NESTED_MEMORY_DB` 指向项目目录内的路径（例如 `./.nested-memory.db`）。将其添加到 `.gitignore` 以保持本地化。
---
## 自动压缩（macOS launchd）
要进行自动后台压缩，请运行 `install.sh`:
```bash
./install.sh
```
这安装了两个 launchd 作业：
| 作业 | 调度 | 操作 |
|-----|----------|--------|
| `com.baltech.nested-memory.daily` | 每天凌晨 3:00 | 压缩 L1 → L2 |
| `com.baltech.nested-memory.weekly` | 每周星期一凌晨 3:30 | 压缩 L2 → L3 |
日志：`~/.openclaw/logs/nested-memory-daily.log`
---
## 要求
- Python 3.9+
- `anthropic >= 0.86.0`
- 带有 FTS5 的 SQLite（包含在 macOS/Linux 标准 Python 中）
---
## 测试
```bash
python3 -m pytest tests/ -v
# 83 个测试，94% 覆盖率
```
---
## OpenClaw（奖励）
如果您使用 [OpenClaw](https://openclaw.ai)，可以直接从 [ClaWHub](https://clawhub.com) 安装此插件：
```bash
# 通过 ClaWHub 安装
/plugin marketplace add tak633b/nested-memory
```
或手动安装：
```bash
openclaw plugins enable nested-memory
```
MCP 服务器和 OpenClaw 扩展程序共享同一个 SQLite 数据库。
---
## 许可证
MIT
