内容
# 记忆引擎
[](https://github.com/qq1009128320-dotcom/memory-engine/actions/workflows/ci.yml)
[](https://www.python.org/)
[](LICENSE)
[](https://github.com/qq1009128320-dotcom/memory-engine/releases)
[](https://github.com/astral-sh/ruff)
> **通过MCP实现四层持久化记忆，适用于AI智能体。**
<p align="center">
<img src="assets/demo.gif" alt="记忆引擎演示" width="650">
</p>
> 修正一次，记忆永恒。
---
## 为什么需要记忆引擎？
每个AI对话都从头开始 — 直到现在。记忆引擎为您的智能体提供跨会话的持久记忆，分为四个专门的层次：
| 传统AI | 使用记忆引擎 |
|---|---|
| 每次对话重置 | 跨会话记忆 |
| 反复犯同样的错误 | 自动从纠正中学习 |
| 每次都需要重新解释上下文 | 自动检索相关记忆 |
| 没有领域知识积累 | 不断学习您的规则和偏好 |
## 架构：四层记忆
```mermaid
graph TD
subgraph Agent["🤖 AI 智能体"]
A1[Hermes / Claude / 自定义] --> MCP["🔌 MCP 服务器<br/>22种工具"]
end
subgraph Layers["记忆引擎"]
L1["📚 第一层：记忆树<br/>向量搜索（FAISS）<br/>分层摘要"]
L2["⚙️ 第二层：偏好<br/>字段映射，日期规则<br/>从纠正中学习"]
L3["🔧 第三层：错误记忆<br/>记住过去的错误<br/>三次后自动升级"]
L4["🗺️ 第四层：知识图谱<br/>实体关系<br/>三级权限"]
end
MCP --> L1 & L2 & L3 & L4
L1 & L2 & L3 & L4 --> DB[("🗄️ SQLite")]
L1 --> FAISS[("📊 FAISS 索引<br/>384维向量")]
```
| 层 | 名称 | 功能 | 灵感来源 |
|-------|------|----------|-------------|
| L1 | 记忆树 | 外部数据摄入 + 向量搜索 + 分层摘要 | OpenHuman |
| L2 | 偏好 | 从用户纠正中学习规则和习惯 | Mem0 |
| L3 | 错误记忆 | 记住错误；三次后自动升级为规则 | **原创** |
| L4 | 知识图谱 | 实体/关系管理，具备三级权限 | Zep |
## 快速开始
```bash
# 1. 克隆并安装
git clone https://github.com/qq1009128320-dotcom/memory-engine.git
cd memory-engine
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
# 2. 初始化数据库
python3 -c "from memory_server import _init_db; _init_db()"
# 3. 启动MCP服务器（按Ctrl+C退出）
python3 memory_server.py
```
## 功能特点
- **四层专用记忆** — 树、偏好、错误记忆、知识图谱
- **22种MCP工具** — 通过MCP协议全面开放
- **混合搜索** — FAISS向量搜索（384维，<3ms热启动）+ 关键词 fallback
- **自动学习** — 错误记录；≥3次自动升级为硬规则
- **自动事实提取** — 从对话中提取实体、偏好和纠正
- **分层摘要** — L0（全局）→ L1（分组主题）→ L2（原始块）
- **健康检查和审计** — 内置30点综合审计
- **部署选项** — 轻量级（FAISS+SQLite）/ 重量级（Milvus+PostgreSQL+Redis）
- **第三方同步** — 飞书/Lark、本地文件、数据库表
- **Docker + systemd** — 生产环境就绪，具备OOM保护
## 基准测试
| 操作 | 冷启动 | 热查询 |
|-----------|-----------|-----------|
| 向量搜索（FAISS） | ~500ms（模型加载） | **~3ms** |
| 关键词搜索 | — | **~0.1ms** |
| 跨层搜索 | — | **~0.1ms** |
## MCP工具
### 记忆树（外部数据）
- `memory_tree_ingest` — 摄入数据（自动嵌入FAISS）
- `memory_tree_vector_search` — 语义向量搜索（推荐）
- `memory_tree_search` — 关键词搜索（fallback）
- `memory_tree_fetch` — 按ID获取完整内容
- `memory_tree_score` — 调整记忆相关性得分
- `memory_tree_reindex` — 重建FAISS索引
- `memory_tree_summary` — L0/L1/L2分层摘要
### 偏好（学习规则）
- `preference_add` / `preference_search` / `preference_list` / `preference_disable`
### 错误记忆（避免重复错误）
- `error_check` — 检查前：该任务是否以前失败过？
- `error_log` — 记录错误 + 用户纠正
- `error_list` — 列出未解决的错误
### 知识图谱
- `entity_add` / `entity_search` / `entity_link` / `graph_query`
### 跨层
- `memory_search` — 同时搜索所有4层
- `memory_stats` — 记忆统计概览
- `memory_health` — 健康检查 + 运行指标
## 自动事实提取
```bash
python3 run_extraction.py --text "用户：检查腾讯的研发费用
智能体：找到了。研发支出：28.3亿元。
用户：使用amt_jpy字段，而不是base_amt。
智能体：好的，我已经记住了。"
```
自动提取：字段别名 → 偏好规则 | 纠正 → 错误记忆 | 实体 → 知识图谱。
## 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `DEEPSEEK_API_KEY` | DeepSeek API密钥（用于提取/摘要） | （可选） |
| `MEMORY_DB_PATH` | SQLite数据库路径 | `./memory.db` |
| `FAISS_INDEX_PATH` | FAISS索引路径 | `./faiss.index` |
| `EMBEDDING_MODEL` | 嵌入模型名称 | `all-MiniLM-L6-v2` |
| `LLM_MODEL` | 用于提取的LLM模型 | `deepseek-chat` |
| `LLM_TIMEOUT` | LLM请求超时（秒） | `30` |
## 部署选项
| 选项 | 规格 | 适用场景 |
|--------|-------|----------|
| 轻量级（FAISS+SQLite） | 2 vCPU, 2GB RAM | 个人 / 小团队 |
| 重量级（Milvus+PG+Redis） | 8 vCPU, 16GB RAM | 企业 / 10M+ 向量 |
### 一键部署
```bash
chmod +x deploy.sh
./deploy.sh
```
自动化：Python检查 → 虚拟环境创建 → 依赖安装 → 数据库初始化 → FAISS重建 → 验证。
## 生产环境强化
- ✅ FAISS并发写锁（线程安全）
- ✅ 请求速率限制（BoundedSemaphore 50）
- ✅ 日志轮转 + 屏蔽（API密钥自动过滤）
- ✅ 启动配置验证
- ✅ 输入净化（NULL字节，控制字符）
- ✅ PID文件锁（防止重复进程启动）
- ✅ WAL自动检查点（每5分钟）
- ✅ 每日备份脚本（完整性检查 → gzip → 30天保留）
- ✅ OOM保护（systemd MemoryMax）
- ✅ Docker多阶段构建（非root用户）
## 生态系统
### Hermes智能体
添加到 `config.yaml`：
```yaml
mcp_servers:
enterprise-memory:
command: /path/to/venv/bin/python3
args: ["/path/to/memory_server.py"]
```
或连接到现有的HTTP服务器（端口8765）：
```yaml
mcp_servers:
enterprise-memory:
url: "http://127.0.0.1:8765/mcp"
```
### Claude Code / Codex CLI / 任意MCP客户端
记忆引擎使用标准MCP协议。连接任意兼容MCP的智能体。
## 项目结构
```
├── memory_server.py # MCP服务器（22种工具）
├── schema.sql # 数据库架构（6张表）
├── run_extraction.py # 端到端事实提取
├── extract_facts.py # LLM提示模板
├── summary_tree.py # 分层摘要生成器
├── auto_fetch.py # 飞书自动同步
├── observability.py # 指标 + 可观测性
├── validators.py # 输入验证
├── config.py # 统一配置
├── log_utils.py # 日志工具
├── audit.py # 30点综合审计
├── deploy.sh # 一键部署
├── Dockerfile # Docker镜像
├── docker-compose.yml # Docker Compose
└── memory-engine.service # systemd单元
```
## 与其他方案比较
| 功能 | 记忆引擎 | agentmemory | Mem0 | Zep | Letta |
|---------|:------------:|:------------:|:----:|:---:|:-----:|
| 记忆层 | **4** | 1 | 2 | 2 | 1 |
| 错误自动学习 | **✅** | ❌ | ❌ | ❌ | ❌ |
| FAISS向量搜索 | **✅** | ❌（自定义） | ✅ | ✅ | ❌ |
| 0外部数据库 | **✅** | ✅ | ❌（云） | ❌（云） | ❌（云） |
| MCP协议 | **✅** | ✅ | ❌ | ❌ | ❌ |
| 自托管 | **✅** | ✅ | ❌ | ✅（有限） | ❌ |
| 重量级部署 | **✅** | ❌ | ❌ | ❌ | ❌ |
| 生产环境审计 | **✅** | ❌ | ❌ | ❌ | ❌ |
| 飞书/Lark同步 | **✅** | ❌ | ❌ | ❌ | ❌ |
| 开源 | **✅ MIT** | ✅ Apache 2.0 | ✅ | ✅ | ✅ |
## 路线图
- [x] v2.0 — FAISS迁移，22种MCP工具，生产环境强化
- [x] v2.1 — CI/CD，Docker，综合审计，嵌入超时保护
- [x] v2.2 — 跨层搜索，错误自动升级，84项测试通过
- [ ] v2.3 — 英文文档，GitHub Pages站点，基准测试套件
- [ ] v2.4 — 多智能体记忆协调（ShadowClone-X集成）
- [ ] v3.0 — Milvus生产部署，水平扩展，企业SSO
## 许可证
MIT
---
## 记忆引擎 — 中文说明
四层智能体记忆系统。让智能体越用越聪明，越用越懂你。
### 核心理念
```text
传统AI：每次从头开始，能力不变
记忆引擎：每次被纠正就更聪明一点
```
### 快速开始（中文）
```bash
git clone https://github.com/qq1009128320-dotcom/memory-engine.git
cd memory-engine
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python3 -c "from memory_server import _init_db; _init_db()"
python3 memory_server.py
```
### 四层架构
| 层 | 名称 | 功能 | 借鉴 |
|----|------|------|------|
| L1 | 记忆树 | 外部数据感知，向量检索 + 层级摘要 | OpenHuman |
| L2 | 偏好记忆 | 从纠正中自动学习规则和习惯 | Mem0 |
| L3 | 纠错记忆 | 记住错误，≥3次自动升级为永久规则 | **原创** |
| L4 | 知识图谱 | 实体关系 + 三级权限 | Zep |
### 更多文档
详见中文版README的完整说明（本文件上半部分为英文、下半部分为中文）。
### GitHub
https://github.com/qq1009128320-dotcom/memory-engine
