内容
<p align="center">
<img src="docs/logo.jpg" width="128" height="128" alt="记忆引擎 Logo" />
</p>
<h1 align="center">🧠 记忆引擎</h1>
<p align="center">
为 AI 助手打造的动态记忆系统 — 基于 SQLite + MCP（模型上下文协议）。<br>
不仅仅是一个键值存储。不仅仅是一个知识图谱。一个 <strong>动态记忆</strong>，它会随着 AI 的使用而衰减、学习和演化。
</p>
---
## ✨ 功能特点
- **原子记忆模型** — 知识以原子形式存储（事实、决策、事件、偏好、日志、程序、笔记、会话消息）
- **多因素排序** — 调用结合了全文搜索相关性 × 置信度 × 最近程度 × 权重（不仅仅是 BM25）
- **有机衰减** — 原子如果不被访问，其权重会随时间减少；关键原子会被标记为审查
- **学习引擎** — 当检测到矛盾、空白、弱原子或合并候选时，为人类生成问题
- **会话观察器** — 自动将 OpenClaw 会话消息作为原子导入，并带有 TTL（事件驱动，通过 inotify/watchdog）
- **自动绑定** — 在导入过程中自动在原子之间创建关系链接
- **图遍历** — 以深度控制和关系过滤的方式导航知识图谱
- **Markdown 导入** — 从现有的 Markdown 笔记进行单向同步（共存，而非替换）
- **合并与去重** — 智能合并相似原子
- **TTL 支持** — 原子自动过期
- **版本控制** — 自动跟踪原子历史
## 🏗️ 架构
```
┌─────────────────────────────────────────┐
│ 您的 AI 助手 │
│ （通过 MCP 协议） │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ MCP 服务器（FastMCP） │
│ 18 种工具（调用、记忆等） │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ 引擎层 │
│ 排序 · 衰减 · 学习 · 合并 │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ 会话观察器（watchdog/inotify） │
│ 监控 OpenClaw 会话 JSONL 文件 │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ SQLite（FTS5 + JSON1） │
│ 原子 · 绑定 · 版本 · 问答 │
└─────────────────────────────────────────┘
```
### 文件
| 文件 | 用途 |
|---|---|
| `server.py` | MCP 服务器 — 通过 FastMCP 公开 18 种工具 |
| `db.py` | SQLite 层 — CRUD、全文搜索、绑定、版本 |
| `engine.py` | 排序、衰减、相似性、空白检测 |
| `learning.py` | 问题生成（5 种触发类型） |
| `importer.py` | Markdown → SQLite 单向导入器 |
| `session_watcher.py` | 基于 watchdog 的会话 JSONL 监视器 |
| `schema.sql` | 数据库模式（原子、绑定、全文搜索、版本） |
**~1,800 行 Python 代码。** 依赖：`mcp` SDK + `watchdog`。
## 🔧 MCP 工具（18 种）
### 记忆操作
| 工具 | 描述 |
|---|---|
| `remember` | 创建或更新原子 |
| `recall` | 智能查询（全文搜索 × 置信度 × 最近程度 × 权重） |
| `get_atom` | 获取具有所有绑定的完整原子细节 |
| `list_atoms` | 列出具有过滤器的原子（领域、类型、状态） |
| `merge_atoms` | 合并两个原子（次要 → 主要） |
| `export_atom` | 将原子导出为 Markdown |
### 知识图谱
| 工具 | 描述 |
|---|---|
| `link` | 在原子之间创建类型化的绑定 |
| `unlink` | 删除绑定 |
| `search_graph` | 从原子遍历知识图谱 |
### 会话管理
| 工具 | 描述 |
|---|---|
| `recall_session` | 在特定会话中搜索消息 |
| `session_summary` | 获取会话概述（消息数量、时间范围） |
| `cleanup_sessions` | 删除过期的会话原子（TTL 清理） |
### 系统与学习
| 工具 | 描述 |
|---|---|
| `stats` | 内存统计（数量、领域、类型） |
| `decay_run` | 执行衰减周期（减少未使用的原子权重） |
| `learning_run` | 运行学习引擎（检测空白、矛盾） |
| `ask_pending` | 获取待处理的人类问题 |
| `answer_human` | 回答待处理的问题 |
| `import_markdown` | 导入 Markdown 文件（批量或单个） |
## 📖 使用示例
### 记忆决策
```python
remember(
title="从 npm 切换到 pnpm",
body="更快的安装，更好的 monorepo 支持。迁移于 2026-06-15 完成。",
type="decision",
domain="project:frontend",
confidence=0.9,
tags=["tooling", "npm", "pnpm"]
)
```
### 调用相关上下文
```python
recall(query="前端构建工具选择", limit=5)
# 返回结合全文搜索匹配、置信度、最近程度和权重的排名结果
```
### 链接相关概念
```python
link(
from_id="switched_from_npm_to_pnpm",
to_id="monorepo_setup",
relation="depends_on",
strength=0.8
)
```
### 在会话中搜索
```python
recall_session(
session_id="abc123-def456",
query="数据库模式设计",
limit=10
)
```
### 获取会话摘要
```python
session_summary(session_id="abc123-def456")
# 返回：消息数量、用户/助手分解、时间范围、首要话题
```
### 导入现有的 Markdown 笔记
```python
import_markdown() # 批量导入所有 Markdown 文件
import_markdown(filepath="/notes/project-decisions.md") # 单个文件
```
### 运行学习引擎
```python
learning_run()
# 检测：矛盾、弱原子、合并候选、衰减临界、空白
# 为发现结果生成人类问题
ask_pending(limit=5)
# 返回需要人类输入的问题
```
## 🔍 会话观察器
会话观察器实时监控 OpenClaw 会话 JSONL 文件：
- **事件驱动** — 使用 `watchdog`/inotify，几乎零开销（非轮询）
- **增量读取** — 跟踪文件偏移量，只处理新行
- **智能过滤** — 只捕获用户/助手文本，跳过工具结果、系统消息和心跳噪声
- **自动过期** — 会话原子具有可配置的 TTL（默认 30 天）
- **自动** — 服务器启动时启动，无需手动干预
### 配置
挂载会话目录并设置环境变量：
```yaml
volumes:
- /path/to/openclaw/sessions:/sessions:ro
environment:
- OPENCLAW_SESSIONS_DIR=/sessions
- SESSION_TTL_DAYS=30
```
## 🚀 快速开始
### Docker（推荐）
```yaml
# docker-compose.yml
services:
memory-engine:
build: .
restart: unless-stopped
expose:
- "8085"
volumes:
- memory-data:/data
- ./your-markdown-notes:/workspace/memory:ro
# 可选：OpenClaw 会话用于会话观察器
- /path/to/openclaw/sessions:/sessions:ro
environment:
- MEMORY_DB_PATH=/data/memory.db
- MARKDOWN_SOURCE=/workspace/memory
- MEMORY_HOST=0.0.0.0
- MEMORY_PORT=8085
# 可选：会话观察器
- OPENCLAW_SESSIONS_DIR=/sessions
- SESSION_TTL_DAYS=30
volumes:
memory-data:
```
```bash
docker compose up -d
```
### 本地（Python ≥3.11）
```bash
pip install -r requirements.txt
python server.py
```
### 连接到您的 MCP 客户端
添加到您的 MCP 客户端配置（例如 Claude Desktop、OpenClaw、Cline 等）：
```json
{
"mcpServers": {
"memory-engine": {
"url": "http://localhost:8085/sse",
"transport": "sse"
}
}
}
```
参见 [`mcp.json`](mcp.json) 获取现成的示例。
## 📊 用例
- **个人 AI 助手记忆** — 跨会话记住偏好、决策、项目上下文
- **会话连续性** — 自动捕获对话上下文，永远不会丢失您离开的地方
- **团队知识库** — AI 代理可访问的共享内存
- **项目文档** — 导入现有的 Markdown 文档，自然查询它们
- **学习日记** — 跟踪决策及其随时间推移的理由
## ⚙️ 配置
编辑 `config.json` 以调整：
| 部分 | 控制内容 |
|---|---|
| `decay` | 间隔、衰减因子、临界阈值、存档超时 |
| `ranking` | 全文搜索分数、置信度、最近程度和原子权重的权重 |
| `learning` | 矛盾、合并相似性、空白检测的阈值 |
| `sessions_dir` | OpenClaw 会话目录的路径 |
| `session_ttl_days` | 会话消息原子的 TTL（默认 30） |
## 🧬 它与众不同之处
| 功能 | memory-graph | sqlite-memory | **记忆引擎** |
|---|---|---|---|
| 存储 | SQLite | SQLite | SQLite |
| 全文搜索 | ❌ | ✅（BM25） | ✅（多因素） |
| 衰减 | ❌ | ❌ | ✅ |
| 学习/问答 | ❌ | ❌ | ✅ |
| 会话观察器 | ❌ | ❌ | ✅ |
| Markdown 导入 | ❌ | ❌ | ✅ |
| 自动绑定 | ❌ | ❌ | ✅ |
| 图遍历 | 基本 | ❌ | ✅（深度 + 关系） |
| 合并原子 | ❌ | ❌ | ✅ |
| TTL | ❌ | ❌ | ✅ |
| 版本控制 | ❌ | ❌ | ✅ |
## 📝 许可证
MIT — 参见 [LICENSE](LICENSE)。
## 🤝 贡献
欢迎贡献！打开问题或 PR。
---
<p align="center">
由 <a href="https://github.com/SimoneB79">SimoneB79</a> 用 🧠 制作
</p>
