内容
<div align="center">
<img src="docs/assets/deep-memory-logo.svg" alt="deep-memory" width="500">
<p><strong>适用于所有智能代理的机器本地内存。检查它们记住的内容。决定它们保留的内容。</strong></p>
<p>
为 Claude Code、Codex、OpenCode 和 Hermes 提供共享、可检查的内存层。
在机器本地的 SQLite 数据库中存储显式、持久的事实和程序，与全局、用户、租户、工作区和项目命名空间的作用域记录相关 —
不是隐藏的云状态、不是原始的转录抓取、不是不透明的全局内存。
</p>
<p>
<a href="README.md">English</a> ·
<a href="README.zh-CN.md">简体中文</a>
</p>
<p>
<a href="https://github.com/benbenlijie/deep-memory/actions/workflows/ci.yml"><img src="https://github.com/benbenlijie/deep-memory/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python">
<img src="https://img.shields.io/badge/license-MIT-green" alt="License">
<img src="https://img.shields.io/badge/status-alpha-orange" alt="Status">
</p>
<p>
<a href="#quickstart">快速开始</a> ·
<a href="docs/AGENT_INSTALL_GUIDE.md">智能代理安装指南</a> ·
<a href="#talk-to-your-agent">与您的智能代理对话</a> ·
<a href="#connect-your-agent">连接您的智能代理</a> ·
<a href="#evidence-not-magic">基准测试和评估</a> ·
<a href="docs/SAFETY_AND_PRIVACY.md">安全性和隐私</a>
</p>
</div>
<p align="center">
<img src="docs/assets/deep-memory-architecture.svg" alt="deep-memory architecture" width="920">
</p>
<p align="center">
<img src="docs/assets/webui-memory-inspector.png" alt="deep-memory WebUI memory inspector screenshot" width="920">
</p>
## 选择适合您需求的路径
| 如果您是... | 从这里开始 | 您将获得 |
| --- | --- | --- |
| 想要最快安装的智能代理操作员 | [快速开始](#quickstart) | 机器本地数据库、一个测试内存和成功的检索 |
| 为用户安装此功能的 AI 智能代理 | [与您的智能代理对话](#talk-to-your-agent) | 直接任务提示和验证检查清单 |
| 连接 Claude Code、Hermes、Codex 或 OpenCode | [连接您的智能代理](#connect-your-agent) | MCP 或包装器设置针对一个共享的本地数据库 |
| 评估声明是否真实 | [证据，而不是魔术](#evidence-not-magic) | 检查的评估、基准测试基线和复制命令 |
| 在发布前检查安全边界 | [安全边界](#safety-boundary) | 显式写入规则、作用域边界和破坏性控制 |
| 检查系统如何构建 | [架构](#architecture) | 机制、存储模型、检索路径和扩展表面 |
## 为什么存在这个问题
大多数智能代理内存都以两种方式之一失败：它会忘记所有有用的信息，或者在用户无法检查的地方记住太多信息。两者都是严重工作的不良基础。
`deep-memory` 是围绕一个较窄的机制构建的：
- **跨智能代理连续性。** 一个共享的内存层，用于 Claude Code、Codex、OpenCode 和 Hermes，以便有用的约定不必从头开始教授。
- **默认可检查。** 通过 CLI、Python SDK 或本地 WebUI 读取、编辑、导出、软删除、硬删除和审计记录。
- **机器本地治理。** 一个本地 SQLite 存储可以跨智能代理共享，而 `scope` 和 `scope_id` 将记录限定在全局、用户、租户、工作区或项目命名空间内。
- **中文检索作为一等公民路径。** FTS5 加本地中文/英文令牌回落，可选 `jieba` 和检查的中文检索装置，使声明可衡量而不是装饰。
- **内存到技能候选导出。** 程序内存可以导出为可审查的技能候选，以便成功的流程成为可审计的工件，而不是无声地变成行为规则。
- **回归测试检索。** 检查的评估涵盖中文检索、双语内存/无内存任务和核心 CLI/SDK 行为。
持久的智能代理内存非常强大，因为它会改变未来的行为。 `deep-memory` 保持机制狭窄：存储持久的事实和可重复使用的程序，保持本地和可检查，检索相关上下文，并使删除和策略边界明确。
该控制表面很重要，因为有用的内存层需要比存储更多：
- **可检查性。** 人类应该能够看到智能代理将继续执行的操作。
- **删除。** 错误、过时、私有或不安全记录必须可删除，而不仅仅是隐藏在排名中。
- **作用域。** 机器级内存应通过固定作用域和显式命名空间 ID 保持相关性。
- **回归测试。** 检索质量和安全边界应使用装置进行检查，而不是在副本中声明。
## 快速开始
如果您想要最快的路径，请询问您的编码智能代理：
> 为这台机器安装 deep-memory，将其设置为跨我的智能代理工具的共享内存层，并验证您可以写入和检索一个持久的内存。告诉我您配置了哪些作用域（例如全局、工作区或项目）。
智能代理检查清单：
1. 阅读 [`docs/AGENT_INSTALL_GUIDE.md`](docs/AGENT_INSTALL_GUIDE.md)。
2. 安装依赖项并初始化机器本地内存存储。
3. 通过 MCP 或包装器连接您的智能代理。
4. 验证一个持久的内存可以被写入和检索。
5. 报告您配置的作用域（例如全局、工作区或项目）。
### 先决条件
- Python 3.10–3.12 (`requires-python = >=3.10,<3.13` 在 `pyproject.toml` 中）
- [`uv`](https://docs.astral.sh/uv/) 用于环境同步和命令执行
- 根据需要选择额外的功能：
- `dev`：pytest + ruff 用于本地验证
- `mcp`：用于 MCP 原生智能代理集成的 `deep-memory-mcp` 服务器
- `retrieval`：用于更高保真度的中文分段的可选 `jieba` 分词器
如果您尚未安装 `uv`，请执行以下操作：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### 零配置首次运行
如果您只想在连接任何智能代理之前证明该机制有效，此路径为您提供一个本地数据库、一个持久内存和一个检索往返：
```bash
uv sync --extra dev --extra mcp
uv run deep-memory init ~/.deep-memory/deep-memory.db
uv run deep-memory add ~/.deep-memory/deep-memory.db \
"用户希望智能代理使用 deep-memory 作为共享持久内存" \
--kind semantic \
--scope project \
--scope-id deep-memory \
--importance 0.8
uv run deep-memory search ~/.deep-memory/deep-memory.db "共享持久内存" \
--scope project \
--scope-id deep-memory
```
预期 CLI 形状：
```text
$ uv run deep-memory search ~/.deep-memory/deep-memory.db "共享持久内存" --scope project --scope-id deep-memory
score=... scope=project scope_id=deep-memory kind=semantic content=用户希望智能代理使用 deep-memory 作为共享持久内存
```
这是核心循环：安装一个机器本地内存存储，让智能代理共享它，并使用固定的 `scope` 和自定义 `scope_id` 来限定记录。
如果您是为用户安装此功能的 AI 智能代理，请遵循 [`docs/AGENT_INSTALL_GUIDE.md`](docs/AGENT_INSTALL_GUIDE.md) — 它涵盖了 MCP 设置、包装器、安全内存写入规则以及如何在 star 项目之前询问用户。
## 与您的智能代理对话
如果您更喜欢直接交接，请复制其中一个提示。
### 最快的安装提示
> 为这台机器安装 deep-memory，通过 MCP 或包装器将其连接到我的智能代理工具，并验证您可以写入和检索一个持久的内存。告诉我您选择的作用域布局以及原因。
### 共享智能代理部署提示
> 将 deep-memory 设置为 Claude Code、Codex、OpenCode 和 Hermes 的共享机器本地内存层。使用相同的 SQLite 数据库存储每个工具，保持内存写入显式，并向我展示您运行的 exact 检索测试。
### 安全优先评估提示
> 评估 deep-memory 是否适合我的工作流程。检查安全边界、作用域模型、删除路径和基准证据，然后在安装任何内容之前推荐部署计划。
### 项目范围内存
> 将 deep-memory 连接到此仓库，并将检索限定为项目范围。在工作之前，搜索此仓库的约定；在验证成功后，仅写入持久的项目特定事实或程序，并向我展示您添加的 exact 记录。
### 程序内存到技能提示
> 使用 deep-memory 捕获此任务中的一个成功工作流程作为程序内存，然后将其导出为可审查的技能候选，而不是自动安装。向我展示导出的工件并解释为什么它应该保持审查优先。
## 证据，而不是魔术
这些检查故意很谦逊。它们是内部评估和回归，而不是声称内存已解决。
| 评估 | 当前检查结果 | 复制 |
| --- | --- | --- |
| 中文检索 v1 | 默认本地后端 55/55；可选 `jieba` 55/55；早期纯 SQLite FTS 基线为 24/55 | `uv run python evals/chinese_retrieval_eval.py --data evals/data/zh_memory_retrieval.jsonl` |
| 中文检索 v2 | 20 个更难的多内存案例，干扰项；本地 top-1 准确率 1.0，MRR 1.0 此检查基线 | `uv run python evals/chinese_retrieval_eval.py --data evals/data/zh_memory_retrieval_v2.jsonl --json` |
| 内存基准测试 v0 | 20 个双语任务；无内存基线 0/20；`deep-memory` 应至少通过测试 16/20，通常 20/20 默认检索限制 | `uv run python benchmarks/memory_benchmark.py` |
| 测试套件 | 核心行为、策略、导入/导出、CLI 路径和回归由 pytest 和 CI 覆盖 | `uv run pytest -q` |
详情：[`docs/CHINESE_RETRIEVAL_EVAL.md`](docs/CHINESE_RETRIEVAL_EVAL.md)，[`docs/MEMORY_BENCHMARK.md`](docs/MEMORY_BENCHMARK.md)。
## 连接您的智能代理
当您的智能代理支持时使用 MCP。当不支持时使用包装器。无论哪种方式，都将每个工具指向同一个机器本地数据库，然后依赖作用域以保持记录相关：
```text
~/.deep-memory/deep-memory.db
```
| 智能代理 | 集成路径 | 配置文件/触摸点 | 难度 |
| --- | --- | --- | --- |
| Claude Code | MCP | `CLAUDE.md` + Claude MCP 配置 | 简单 |
| Hermes | MCP | `~/.hermes/config.yaml` | 简单 |
| Codex / OpenCode / OpenClaw 样式工具 | 包装器优先，MCP 后 | 任务包装器/启动脚本 | 中等 |
<details>
<summary>Claude Code 设置</summary>
```bash
claude mcp add deep-memory -- uv --directory /absolute/path/to/deep-memory run deep-memory-mcp
```
将此添加到 `CLAUDE.md` 以使策略明确：
```markdown
在大型任务之前，搜索 deep-memory 以获取相关项目约定。
验证成功后，仅添加持久的事实或可重复使用的程序。
永远不要存储秘密、原始凭证或临时问题状态。
```
</details>
<details>
<summary>Hermes 设置</summary>
```yaml
mcp_servers:
deep_memory:
command: "uv"
args: ["--directory", "/absolute/path/to/deep-memory", "run", "deep-memory-mcp"]
timeout: 30
```
Hermes 然后公开诸如 `mcp_deep_memory_add`、`mcp_deep_memory_search` 和 `mcp_deep_memory_stats` 等工具。
Hermes 还可以导入显式事实 JSONL：
```bash
cat > /tmp/hermes-session.jsonl <<'JSONL'
{"session_id":"s_demo","facts":[{"content":"用户更喜欢使用英文技术术语进行简洁的答案","kind":"semantic","importance":0.9}]}
{"session_id":"s_demo","facts":[{"content":"成功的工作流程应成为可审查的技能候选","kind":"procedural","confidence":0.8}]}
JSONL
uv run deep-memory hermes-import ~/.deep-memory/deep-memory.db /tmp/hermes-session.jsonl
```
</details>
<details>
<summary>Codex、OpenCode 和 OpenClaw 样式包装器设置</summary>
在安装 MCP 之前，请使用包装器。搜索任务前，写入仅验证的事实：
```bash
MEMORY_DB=~/.deep-memory/deep-memory.db
uv run deep-memory search "$MEMORY_DB" "此任务的相关约定" \
--scope project \
--scope-id deep-memory
# 将结果作为短的“相关内存”块传递给智能代理
# ...运行智能代理...
uv run deep-memory add "$MEMORY_DB" \
"工作流程：对于此仓库，运行 uv run pytest -q 和 uv run ruff check . 在审查之前" \
--kind procedural \
--scope project \
--scope-id deep-memory \
--importance 0.8 \
--source codex:manual
```
</details>
<details>
<summary>完整适配器参考</summary>
有关完整的适配器表面 - 集成点、读写路径、权限、风险 - 请参阅 [`docs/ADAPTERS.md`](docs/ADAPTERS.md) 和每个智能代理的命令 [`docs/AGENT_QUICKSTART_MATRIX.md`](docs/AGENT_QUICKSTART_MATRIX.md)。
</details>
## 内存范围
`deep-memory` 默认情况下是机器本地的，但记录仍然可以显式限定：
| 范围 | 主要用途 | 典型内容 | 跨项目？ |
| --- | --- | --- | --- |
| `global` | 长期事实，应遵循整个机器 | 持久的用户偏好、稳定约定、机器级策略 | 是 |
| `user` | 共享主机上的每用户分区 | 一个人的偏好、角色、语言、循环工作流习惯 | 有时 |
| `workspace` | 相关仓库或文件夹的共享上下文 | 相邻项目笔记、共享构建/测试约定、多仓库上下文 | 有时 |
| `project` | 仓库特定内存 | 仓库约定、本地架构事实、审查清单 | 否 |
| `tenant` | 团队/环境隔离 | 组织通道分离、暂存与生产边界、多租户执行状态 | 取决于租户设计 |
数据库是共享的；`scope` 是固定的治理层（`global`、`user`、`tenant`、`workspace` 或 `project`），`scope_id` 是该层内的自定义命名空间，例如 `deep-memory`、`repo-a` 或 `ben`。从保留您期望的行为的最窄范围开始，然后仅当内存真正跨项目或智能代理时才扩大。
## 检查内存
```bash
uv run deep-memory webui ~/.deep-memory/deep-memory.db --host 127.0.0.1 --port 8765
# 打开 http://127.0.0.1:8765
```
`deep-memory webui ...` 是受支持的启动路径。`deep-memory-webui` 不是当前的控制台脚本或启动合同。
WebUI 可以列出、搜索、编辑和软删除记录。它绑定到 `127.0.0.1`，现在提供 `/favicon.svg` 和 `/favicon.ico`，并在浏览器选项卡中使用相同的项目图标。如果端口 `8765` 已被占用，请使用 `--port` 选择另一个空闲端口，例如 `--port 8876`。
导出和审计：
```bash
uv run deep-memory export ~/.deep-memory/deep-memory.db # 仅活动记录
uv run deep-memory export ~/.deep-memory/deep-memory.db --include-deprecated # 审计/备份
uv run deep-memory hard-delete ~/.deep-memory/deep-memory.db <memory-id> # 物理删除一条记录
```
## Python API
```python
from pathlib import Path
from deep_memory import DeepMemory
mem = DeepMemory(Path("~/.deep-memory/deep-memory.db").expanduser())
mem.add(
"用户更喜欢使用英文技术术语进行简洁的答案",
kind="semantic",
importance=0.9,
scope="user",
scope_id="ben",
)
mem.add(
"项目约定：使用 uv 进行测试",
kind="procedural",
importance=0.8,
scope="project",
scope_id="deep-memory",
)
for result in mem.search(
"应该如何测试这个仓库？",
scope="project",
scope_id="deep-memory",
limit=3,
):
print(result.score, result.record.kind, result.record.content)
```
## 今天什么有效
| 领域 | 状态 | 备注 |
| --- | --- | --- |
| 本地持久性 | 已实现 | 用户控制的机器本地 SQLite DB，固定范围和自定义范围 ID。 |
| 搜索 | 已实现 | FTS5 加本地中文/英文令牌回落。 |
| 可选中文分词器 | 已实现 | 通过 `uv sync --extra retrieval` 的 `jieba` 后端。 |
| 元数据 | 已实现 | `kind`、`importance`、`confidence`、`source`、时间戳、冲突状态、范围和衰减。 |
| 冲突处理 | 已实现 | 候选人、已解决、取代、废弃。 |
| Python SDK + CLI | 已实现 | `add`、`search`、`stats`、`conflicts`、`resolve-conflict`、`export`、`hard-delete`、`hermes-import`、`webui`。 |
| MCP 服务器 | 已实现 | 用于 `add`、`search` 的 `deep-memory-mcp` 服务器。 |
| Hermes 导入 | 已实现 | 显式会话事实 JSONL 到 `deep-memory` 记录。 |
| 本地 WebUI MVP | 已实现 | 检查、搜索、编辑、软删除和基于收藏图标的浏览器身份，用于内存记录。 |
| 内存到技能候选 | 已实现 | 将程序内存导出为可审查的技能 Markdown；不会自动安装。 |
| Codex 包装器 MVP | 已实现 | `deep-memory codex-run` 注入限定上下文并仅在成功后导入 `--facts-out` JSONL。 |
| 每个智能代理的原生适配器 | 规格/原型 | 使用 MCP 或包装器。参见 `docs/ADAPTERS.md`。 |
| 矢量检索/托管同步 | 路线图 | 评估和隐私边界证明其合理性后。 |
</div>
</div>
</div>
## 架构
核心系统故意设计得小巧：
1. 代理或开发者生成显式事实、程序和持久约定；
2. SDK、CLI、MCP 或包装路径验证并写入记录；
3. 机器本地 SQLite + FTS5 存储带有元数据和范围的搜索内存；
4. 未来的代理在工作前检索有限的上下文块；
5. 人工检查、编辑、导出、删除、评估或将程序记录提升为技能候选。
SQLite 很枯燥但有意为之。它易于安装、检查、测试、备份和稍后更换。单个机器本地存储使代理互操作；范围使检索有限。矢量检索保留在路线图中，带有模式占位符和可选迁移路径；参见 [`docs/VECTOR_ROADMAP.md`](docs/VECTOR_ROADMAP.md)。
<details>
<summary>阅读更多架构和策略文档</summary>
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
- [`docs/SAFETY_AND_PRIVACY.md`](docs/SAFETY_AND_PRIVACY.md)
- [`docs/MEMORY_POLICY.md`](docs/MEMORY_POLICY.md)
- [`docs/MCP_INTEROPERABILITY.md`](docs/MCP_INTEROPERABILITY.md)
- [`docs/ADAPTERS.md`](docs/ADAPTERS.md)
- [`docs/ROADMAP.md`](docs/ROADMAP.md)
- [`docs/VECTOR_ROADMAP.md`](docs/VECTOR_ROADMAP.md)
</details>
## 安全边界
持久内存会改变未来的行为。保持默认设置狭窄：
- 存储显式持久事实，而不是原始记录；
- 默认使用机器本地 SQLite；
- 将 `scope` 视为固定层，将 `scope_id` 视为自定义命名空间，以便全局内存是故意的，项目/工作区内存保持有限；
- 检索一个小的相关上下文块；
- 检索遥测仅限本地，可以通过 `DEEP_MEMORY_TELEMETRY=off` 禁用 - 参见 [`docs/SAFETY_AND_PRIVACY.md`](docs/SAFETY_AND_PRIVACY.md)；
- 绝不存储秘密、私钥、身份验证 cookie、原始凭证、原始私人记录或临时任务状态；
- 仅在测试、审查或用户确认后写入程序内存；
- 自动备份具有可配置的 7 天 TTL 的破坏性操作；
- 导出技能候选以供审查，而不是自动安装它们。
阅读 [`docs/MEMORY_POLICY.md`](docs/MEMORY_POLICY.md) 以获取允许/拒绝/需要确认的写入策略，并在添加自动写入或共享团队内存之前阅读 [`docs/SAFETY_AND_PRIVACY.md`](docs/SAFETY_AND_PRIVACY.md)。
## 贡献
这是受控的预览通道，而不是广泛的发布声明。贡献应该使内存层更易于检查、重现、范围限定或更易于运行。
新来者？从 [good first issue](https://github.com/benbenlijie/deep-memory/labels/good%20first%20issue) 开始，评论认领，运行建议的命令，并使用证据打开一个小的 PR。
良好的起点：
- `good first issue`：小fixture、文档修复、CLI 输出润色和重现失败案例；
- `adapter`：Claude Code、Codex、OpenCode、OpenClaw 样式工具和 Hermes 的烟雾记录和包装器/MCP 兼容性注释；
- `eval`：中文检索、隐私边界、内存/无内存和内存 × 技能回归案例；
- `governance`：写入策略、同意、导出/删除和冲突生命周期检查；
- `docs`：快速入门、故障排除、词汇表和贡献路径。
### 贡献的具体路径
- **添加新的代理适配器。** 更新 `docs/AGENT_QUICKSTART_MATRIX.md` 中的代理面向命令矩阵，在 `docs/ADAPTERS.md` 中记录集成表面和信任边界，在 `src/deep_memory/` 下添加实现或包装器入口，并在 `tests/` 下用至少一个 CLI 或集成测试覆盖路径。
- **添加新的评估fixture。** 在 `evals/data/` 下添加fixture数据，在 `evals/` 或 `benchmarks/` 下将新案例连接到相关评估或基准测试运行器，在 `docs/CHINESE_RETRIEVAL_EVAL.md` 或 `docs/MEMORY_BENCHMARK.md` 中记录它测量什么，并在 `tests/` 中添加回归断言，如果行为应在 CI 中保持稳定。
<details>
<summary>更多贡献参考</summary>
从 [`CONTRIBUTING.md`](CONTRIBUTING.md)、[`docs/COMMUNITY.md`](docs/COMMUNITY.md) 和 [`docs/NEXT_PHASE_BACKLOG.md`](docs/NEXT_PHASE_BACKLOG.md) 开始。
</details>
## 许可证
deep-memory 为您的代理提供一个本地内存层，您可以检查和治理。
如果该项目在您的工作流中有用，请考虑为存储库加星并通过实际部署反馈打开问题或讨论。
联系方式和反馈：
- GitHub 问题：<https://github.com/benbenlijie/deep-memory/issues>
- GitHub 讨论：<https://github.com/benbenlijie/deep-memory/discussions>
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器