Memory Engine

🧠 Memory Engine MCP

以本地为先、支持图谱的 AI 助手长期记忆。
SQLite + 语义搜索 + 知识图谱 + MCP 工具，为需要保持连续性的 Agent 提供支持。

适用于 Claude Desktop · Claude Code · Cursor · Cline · Windsurf · OpenClaw · 任意 MCP 客户端

---

为什么选择 Memory Engine？

大多数 MCP 记忆服务要么是简单的键值存储，要么只是纯文本搜索封装。

Memory Engine 则不同：它将记忆建模为由类型化关系连接的类型化原子，再通过混合排序流程检索上下文，该流程结合了：

• 全文搜索（SQLite FTS5）
• 通过本地 Ollama 嵌入进行语义相似度搜索
• 置信度、时效性和权重
• 从相关记忆扩展图谱

目标不只是存储，而是构建一个能够随时间回忆、关联、衰减、整理和学习的记忆系统。

亮点

• 以本地为先 — 使用 SQLite 数据库，可选通过 Ollama 生成本地嵌入，无需云 API。
• 原生支持 MCP — 通过 FastMCP 提供 35 个工具。
• 支持图谱的回忆 — 通过双向关系扩展排名靠前的结果，提供更丰富的上下文。
• 语义搜索 — 使用 nomic-embed-text 按含义检索。
• 兼容 Markdown — 单向导入现有笔记，不会替代人类可读的记忆。
• 错误记忆 — 记住错误和更正；反复失败后会自动提升为偏好。
• 认知整理器 — 以非破坏性方式执行维护，包括压缩、关系建议、重复项检测和孤立原子分类。
• 会话监听器 — 规范的 OpenClaw SQLite 导入（架构 17）、可识别重置的摘要，以及 JSONL 旧格式回退。
• 备份与恢复 — 完整 SQLite 快照、JSON 导出/导入，以及带自动安全备份的验证恢复。
• 身份验证与加固 — 可选 API 令牌、安全绑定、输入验证、速率限制。
• 测试套件 — 144 项测试，覆盖 CRUD、排序、迁移、身份验证、备份、并发和对话记录导入。
• 基准测试 — CLI 回忆质量测试套件，包含 Precision@K、MRR 和延迟百分位数。

架构

AI assistant / MCP client
        │
        ▼
FastMCP server — 35 tools
        │
        ▼
Memory engine — hybrid ranking, graph recall, decay, learning
        │
        ├── SQLite — atoms, bonds, FTS5, JSON metadata, versions
        ├── Ollama — optional local embeddings
        ├── Curator — conservative maintenance
        └── Session watcher — OpenClaw SQLite + JSONL fallback

MCP 工具

记忆

工具	用途
remember	创建或更新一个原子
recall	通过图谱扩展进行智能混合回忆
working_set	构建面向任务的上下文包
semantic_search	纯语义搜索
get_atom	读取单个原子及其关系
list_atoms	按领域/类型/状态浏览原子
merge_atoms	合并重复原子
export_atom	将单个原子导出为 Markdown

知识图谱

工具	用途
link / unlink	创建或移除类型化关系
search_graph	从一个原子出发遍历图谱
suggest_bonds	为一个原子建议关系
suggest_bonds_all	批量建议或创建关系

学习与维护

工具	用途
curator_run	保守型整理
cognitive_status	图谱与记忆健康指标
learning_run	检测矛盾、薄弱原子、合并候选项和缺漏
ask_pending / answer_human	人机协作澄清
decay_run	运行衰减周期
cleanup_sessions	删除过期会话原子
cleanup_duplicates	删除重复的会话原子
reindex_embeddings	重建嵌入

错误记忆与偏好

工具	用途
error_check	执行任务前检查过往失败记录
error_log	记录错误及更正内容
error_list	浏览未解决/已解决的错误
preference_search	搜索结构化偏好

导入与自省

工具	用途
import_markdown	将 Markdown 笔记导入原子
memory_summary	三级摘要：全局 → 领域 → 细节
stats	数据库统计信息
version	服务版本
recall_session	搜索一个 OpenClaw 会话
session_summary	总结一个 OpenClaw 会话
memory_contradict	用较新的矛盾原子取代旧原子
list_contradictions	列出明确的矛盾/取代记录
classify_memory_tier	推断三级分类（情景/语义/程序）
memory_impact	影响分析：有哪些内容依赖此原子

备份、恢复与导出

工具	用途
backup_database	创建、列出、验证或清理 SQLite 快照
restore_database	从备份恢复（自动创建安全备份）
export_all	将所有记忆数据导出为可移植的 JSON
import_data	从 JSON 导入（合并或替换模式）

Web UI（可选）

Memory Engine 提供可选的 Web UI，用于探索图谱、检查原子、 浏览矛盾和进行影响分析。

# In docker-compose.yml, add:
#   environment:
#     - MEM_UI_PORT=6000
#   expose:
#     - "6000"

或者独立运行：

python3 web_ui.py
# Open http://localhost:6000

Web UI：交互式图谱、原子详情、矛盾浏览器、统计信息面板

使用 Docker 快速开始

选项 A — 使用预构建镜像（推荐）

# docker-compose.yml
services:
  memory-engine:
    image: ghcr.io/simoneb79/memory-engine-mcp:2.1.0
    ports:
      - "8085:8085"
    volumes:
      - memory-data:/data
    restart: unless-stopped

volumes:
  memory-data:

docker compose up -d

固定版本。 在生产环境中使用 :1.7.0 这样的明确标签。 避免使用 :latest——它可能会在不另行通知的情况下发生变化。

选项 B — 从源代码构建

git clone https://github.com/SimoneB79/memory-engine-mcp.git
cd memory-engine-mcp
cp docker-compose.yml docker-compose.local.yml
# Edit volume paths in docker-compose.local.yml if needed
docker compose -f docker-compose.local.yml up -d --build

默认端点：

http://localhost:8085/sse

MCP 客户端配置示例：

{
  "mcpServers": {
    "memory-engine": {
      "url": "http://localhost:8085/sse",
      "transport": "sse"
    }
  }
}

有关 Docker、本地 Python、Claude Desktop、Cursor 和 OpenClaw 示例，请参阅 docs/INSTALL.md。

本地 Python

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python server.py

配置

主配置文件：config.json

重要环境变量：

变量	默认值	用途
MEMORY_DB_PATH	/data/memory.db	SQLite 数据库路径
MARKDOWN_SOURCE	/workspace/memory	用于导入的 Markdown 目录
MEMORY_HOST	127.0.0.1	服务绑定地址（安全默认值）
MEMORY_PORT	8085	SSE 端口
MEMORY_API_TOKEN	(none)	可选的身份验证 API 令牌（参见安全性）
OPENCLAW_AGENT_DB	(none)	首选的按 Agent 划分的 OpenClaw SQLite 数据库（架构 17）
OPENCLAW_SESSIONS_DIR	/sessions	未配置 Agent 数据库时使用的旧版 JSONL 回退目录
SESSION_DIGEST_DIR	/data/session_digests	可选的会话摘要输出目录

有关 SQLite 挂载、WAL/SHM 处理、筛选和安全边界，请参阅 OpenClaw 对话记录导入。

语义搜索要求容器或主机能够访问 Ollama。默认值：

{
  "ollama": {
    "enabled": true,
    "host": "http://ollama:11434",
    "model": "nomic-embed-text"
  }
}

如果不使用 Ollama，请将 ollama.enabled 设为 false；FTS 召回仍可使用。

记忆模型

原子包含：

• title
• body
• type：fact、decision、event、preference、log、procedure、note 等
• domain：项目或主题命名空间
• confidence
• weight
• tags
• 可选的 TTL

关联通过关系类型连接原子：

is_a · part_of · depends_on · contradicts · refines · derived_from · detail_of · related_to

使用示例

remember(
    title="Use PostgreSQL for analytics",
    body="SQLite is kept for local memory, PostgreSQL is used for multi-user analytics.",
    type="decision",
    domain="project:analytics",
    confidence=0.9,
    tags=["database", "architecture"]
)

recall(query="what database did we choose for analytics?", limit=5)

working_set(
    query="continue the analytics backend work",
    domain="project:analytics",
    limit=8,
    graph_depth=1
)

安全性

默认情况下，Memory Engine 以开放模式运行（无身份验证），适用于 stdio 或可信的本地环境。

要启用 API 令牌身份验证：

// config.json
{
  "security": {
    "api_token": "your-secret-token",
    "allow_remote": false
  }
}

或者通过环境变量启用：

MEMORY_API_TOKEN=your-secret-token

启用身份验证后：

• MCP SSE 请求必须包含 Authorization: Bearer <token>
• Web UI API 端点需要 ?token=<token> 或 Bearer 标头
• 除非设置 allow_remote: true，否则服务器会绑定到 127.0.0.1
• 输入验证（标题／正文大小限制）和速率限制始终启用

完整的安全功能列表请参阅 CHANGELOG.md。

发布与注册表

此仓库已为 MCP 发现做好准备：

• MCP Registry 名称：io.github.simoneb79/memory-engine-mcp
• 注册表元数据：server.json
• Docker/OCI 验证标签：已包含在 Dockerfile 中
• 客户端配置示例：mcp.json

发布检查清单请参阅 docs/PUBLISHING.md。

仓库状态

• GitHub 公开仓库：https://github.com/SimoneB79/memory-engine-mcp
• 现有条目：https://mcpmarket.com/server/memory-engine
• 许可证：MIT

许可证

MIT — 请参阅 LICENSE。

---

由 SimoneB79 用 🧠 制作