内容
# 内存数据库 — 最小化人工智能记忆
适用于人工智能代理的轻量级基于向量的记忆系统。通过语义搜索存储、检索和删除记忆。您拥有嵌入模型；我们处理向量。
## 为什么选择内存数据库？
**最少的令牌，最大化的模型自由度。**
- **约236令牌/回合** — 3个工具，描述简洁，无冗长指令
- **无知识图谱，无全文搜索，无仪表盘** — 模型决定如何使用记忆，而不是系统
- **6个文件，3个依赖** — 轻量级占用，易于理解和修改
**您提供嵌入API。**
- 使用llama.cpp、Ollama、OpenAI或任何OpenAI兼容的端点
- 随时切换模型 — 只需更改`EMBEDDING_API_URL`
- 在切换模型时，使用`memory-db-manage rebuild`重建向量
我们删除了所有限制模型的组件。记忆系统应该是一个工具，而不是框架。
## 架构
```
┌──────────────┐ ┌─────────────┐ ┌──────────────┐
│ MCP服务器 │─────▶│ Qdrant │◀──────│ │
│ (3个工具) │◀─────│ :6333 │ │ llama.cpp │
└──────────────┘ └─────────────┘ │ :8081 │
│ /v1/embed │
└──────────────┘
```
一个向量存储，一个嵌入API。3个适用于AI代理的MCP工具，一个用于运维的管理CLI。
## 安装
```bash
# 克隆仓库
git clone https://github.com/cunzai97/Memory-DB.git
cd Memory-DB
# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate # 在Windows上：venv\Scripts\activate
# 安装依赖
pip install -e .
# 启动Qdrant（必需）
docker compose up -d
```
现在您可以启动MCP服务器：
```bash
memory-db # 启动MCP服务器
```
或使用管理CLI：
```bash
memory-db-manage list # 列出所有记忆
```
## 快速入门
### 先决条件
- Qdrant运行在`:6333`（Docker Compose或独立）
- 嵌入API运行在`:8081`（您的llama.cpp实例）
```bash
docker compose up -d # 仅启动Qdrant
pip install -e . # 安装memory-db + CLI
memory-db # 启动MCP服务器
```
### 环境变量
| 变量 | 默认值 | 目的 |
|----------|---------|---------|
| `QDRANT_HOST` | `localhost` | Qdrant主机 |
| `QDRANT_PORT` | `6333` | Qdrant端口 |
| `EMBEDDING_API_URL` | `http://localhost:8081/v1/embeddings` | 嵌入API（OpenAI兼容） |
## MCP配置
### Claude Code — 全局配置
```bash
claude mcp add memory-db \
-e PYTHONPATH=/path/to/Memory-DB/src \
-e EMBEDDING_API_URL=http://localhost:8081/v1/embeddings \
-e QDRANT_HOST=localhost \
-e QDRANT_PORT=6333 \
-- /path/to/Memory-DB/venv/bin/python3 -m memory_simple.server
```
验证：`claude mcp list`（应显示 `✓ Connected`）。
### Hermes — 全局配置
编辑 `~/.hermes/config.yaml`，在 `mcp_servers` 下添加：
```yaml
mcp_servers:
memory-db:
command: /path/to/Memory-DB/venv/bin/python3
args: ["-m", "memory_simple.server"]
timeout: 120
env:
PYTHONPATH: /path/to/Memory-DB/src
EMBEDDING_API_URL: http://localhost:8081/v1/embeddings
QDRANT_HOST: localhost
QDRANT_PORT: "6333"
```
重启Hermes。
## MCP工具
### `store_memory(content, tags?, dedup_threshold=0.85)`
保存记忆。返回 `{id, deduped}`。
如果文本在语义上与现有的记忆相似（余弦≥阈值），则替换旧记忆 — 内置熵减少。设置`dedup_threshold=0`以禁用。
```
store_memory(content="Memory-DB 项目重构经验：从 80+ Python 文件精简到 6 个核心文件。移除了 knowledge graph (FalkorDB)、FTS5、dashboard、sessions，只保留 Qdrant + embedding API。MCP 工具从复杂变简单：store_memory、get_memories、delete_memory，约 236 tokens/turn。关键设计：语义去重（余弦相似度 ≥ 0.85）、recall_count 自动追踪、min_score 过滤、空内容校验 + 友好错误提示。依赖精简到：mcp、qdrant-client、httpx。", tags=["project", "refactor", "mcp", "memory-system"])
→ {"id": "a1b2c3d4-...", "deduped": false}
store_memory(content="Python是一门动态类型的编程语言")
→ {"id": "e5f6g7h8-...", "deduped": true} // 替换了重复项
```
### `get_memories(query, limit=5, min_score=0.5)`
语义搜索（余弦相似度）。返回按分数降序排列的顶部匹配结果。分数低于`min_score`的结果被过滤掉 — 使用0.8+进行严格匹配，使用较低的值（例如0.2）进行更广泛的搜索。每个命中自动增加`recall_count`并更新`last_recalled_at`。
```
get_memories(query="动态类型")
→ [{"id": "...", "content": "Python是动态类型语言", "score": 0.79,
"recall_count": 1, "last_recalled_at": "2026-06-27T...", ...}]
# 更广泛的搜索，阈值较低
get_memories(query="动态类型", min_score=0.2)
```
### `delete_memory(memory_id)`
按ID删除。返回 `{deleted: true/false}` — 如果记忆不存在，则为false。
```
delete_memory(memory_id="a1b2c3d4-...")
→ {"deleted": true, "id": "a1b2c3d4-..."}
```
### 令牌成本
MCP工具定义（描述 + JSON模式）在系统中每个回合的成本约为**236令牌** — 所有三个工具大约464个字符的描述文本。 自我解释的参数（`content`, `tags`, `query`, `limit`）被省略； 只有不明显的参数（`dedup_threshold`, `min_score`）被解释。 这是一个一次性开销，添加到每个请求中，而不是累积的。
## 管理CLI
通过终端进行管理员操作 — 不暴露给MCP工具。
```bash
# 列出所有记忆（无搜索）
memory-db-manage list [--limit N]
# 导出到JSON备份（保留原始文本，独立于向量）
memory-db-manage export --path backups/memories.json
# 从JSON导入（使用当前嵌入模型重新编码）
memory-db-manage import --path backups/memories.json
# 重建索引 — 使用相同或新的模型重新编码所有记忆
memory-db-manage rebuild [--embedding-url http://new-host:port/v1/embeddings]
# 清除未使用的记忆（熵减少）
memory-db-manage purge --min-recall-count 0 --unused-days 30 # 默认干预运行
memory-db-manage purge --min-recall-count 0 --unused-days 30 --execute # 实际删除
# 删除所有（破坏性，需要确认）
memory-db-manage delete-all [--force]
```
### 切换嵌入模型
当您更改嵌入模型时，现有的向量将变得过时。两个选项：
1. **原地重建** — 保留元数据和召回统计，仅替换向量：
```bash
memory-db-manage rebuild --embedding-url http://new-host:9090/v1/embeddings
```
2. **导出 → 导入** — 完整文本备份：
```bash
memory-db-manage export --path backups/old-model.json
# ... 切换模型 ...
memory-db-manage import --path backups/old-model.json
```
### 熵减少（清除未使用的记忆）
从未被召回的记忆会随着时间的推移而积累。使用`purge`进行清理：
```bash
# 预览将被删除的内容（默认干预运行）
memory-db-manage purge --min-recall-count 0 --unused-days 30
# 实际删除召回计数=0且30天以上未被召回的记忆
memory-db-manage purge --min-recall-count 0 --unused-days 30 --execute
```
## 记忆有效载荷模式
每个存储的记忆都带有此有效载荷到Qdrant：
```json
{
"id": "<uuid>",
"content": "原始文本",
"created_at": "2026-06-27T14:33:24+00:00",
"tags": ["rust", "systems"],
"recall_count": 3,
"last_recalled_at": "2026-06-27T15:00:00+00:00"
}
```
`tags`是可选的。`recall_count` / `last_recalled_at`在每次搜索命中时自动跟踪 — 在熵减少期间识别从未被召回的记忆很有用。
## 项目结构
```
src/memory_simple/
├── embedding.py # 嵌入API客户端（httpx）
├── service.py # 记忆服务 — 核心存储/获取/删除
├── admin.py # 记忆管理员 — 备份/导入/重建/清除
├── server.py # MCP服务器 — 暴露3个工具
└── manage.py # CLI — 管理操作
```
**依赖：** `mcp`, `qdrant-client`, `httpx` — 就是这样。
