Memory Weave · Memory Graph Workspace for MCP

Memory Weave 是一个面向 MCP 的记忆图谱后端 + 治理工作台

• 后端：FastAPI + SQLite / PostgreSQL
• Agent 接口：MCP（stdio / SSE / Streamable HTTP）
• 治理工作台：React + Vite，提供指挥台、审核队列、记忆图谱、检索实验室、修订修剪等操作面

这个项目解决什么问题

Memory Weave 关注的是一套可治理的记忆操作流程：

• 用 namespace://route 暴露稳定访问路径
• 用 Memory / Revision / Link / Route 保持正文与结构分层
• 用并发版本号保护写入顺序
• 用审核队列与回滚能力兜住 Agent 写入风险
• 用触发词和全文检索补足召回与查找能力

运行时组件

数据模型

• Route / Link 负责访问路径与路由元数据。
• Memory / Revision 负责稳定实体与正文版本链。
• Trigger / SearchDocument 是召回与检索的辅助层。

核心能力

• Route 优先的访问模型：统一使用 namespace://route
• 图式存储：保留 Memory / Revision / Link / Route 四层模型
• 并发保护：读取会返回 expected_*_version 所需版本号，写入必须带回
• 审核队列：MCP 写入会进入审计快照缓冲层，支持审查、纳入、回退
• Trigger 绑定：关键词绑定记忆，支持规则型联想
• 检索派生层：支持 FTS 搜索，不把检索索引混同为源事实

工作台页面

当前前端包含 4 个主工作面：

• Audit Queue / 审核队列：审查 AI 写入分组，查看差异并执行纳入或回退
• Memory Atlas / 记忆图谱：按命名空间与 Route 浏览 Memory、别名和触发词
• Retrieval Lab / 检索实验室：对照 Trigger 网络与 FTS 索引
• Revision Pruning / 修订修剪：清理 superseded / detached Revision

快速开始

方式一：Docker 启动

git clone https://github.com/Usagi-org/memory-weave && cd memory_weave
cp env.example .env
docker compose up --build -d

服务组成：

• backend-api：REST API
• backend-sse：MCP SSE / HTTP
• postgres：数据库
• nginx：统一入口

默认前端入口：http://127.0.0.1:8765

方式二：本地开发

git clone https://github.com/Usagi-org/memory-weave && cd memory_weave
python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
npm --prefix frontend install

配置环境变量

cp .env.example .env

最小配置：

MEMORY_WEAVE_DATABASE_URL=sqlite+aiosqlite:///{PROJECT_ROOT}/memory_weave.db
MEMORY_WEAVE_ALLOWED_NAMESPACES=core,writer,game,notes,project
MEMORY_WEAVE_BOOT_MEMORY_URIS=core://agent,core://my_user

启动服务

后端 API：

python backend/main.py

MCP 传输层（SSE + Streamable HTTP）：

python backend/run_sse.py

前端开发：

npm --prefix frontend run dev

前端构建：

npm --prefix frontend run build

MCP 接入

当前提供三种 MCP 接入方式：

• http：http://127.0.0.1:8765/mcp（推荐）
• stdio：python backend/mcp_gateway.py
• sse：http://127.0.0.1:8765/sse

推荐优先级：

1. /mcp（HTTP）：远端部署、跨设备共享、也是默认示例
2. stdio：适合同机直连，不需要额外启动 backend/run_sse.py
3. /sse：仅用于仍使用 legacy SSE transport 的客户端

MCP HTTP 配置示例

查看 .env 中的 MEMORY_WEAVE_BEARER_TOKEN，对应配置如下：

{
  "mcpServers": {
    "memory-weave": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "Authorization": "Bearer ${MEMORY_WEAVE_BEARER_TOKEN}"
      }
    }
  }
}

Prompt / Agent 使用建议

如果希望 Agent 正确使用这套记忆接口，建议在系统提示词中明确以下规则：

• read_memory(uri) 是唯一 canonical 读取入口
• 新会话启动时先调用 read_memory("system://boot")
• 普通记忆与 system://* 动态视图都通过 read_memory(uri) 读取
• 写入前必须回传相应 expected_*_version

提示词模板可参考：PROMPT.md

常见位置：

• Gemini CLI：~/.gemimi/GEMINI.md
• Claude Code：~/.claude/CLAUDE.md
• Codex：~/.codex/AGENTS.md

常用 MCP 工具

• read_memory(uri)
• create_memory(parent_uri, content, priority, title?, recall_when, expected_parent_child_version)
• update_memory(uri, old_string/new_string | append, priority?, recall_when?)
• remove_route(uri)
• add_route_alias(new_uri, target_uri, priority?, recall_when?)
• manage_triggers(uri, add/remove)
• search_memories(query, namespace?, limit?)

详细参数说明见：docs/MCP_INTERFACE_REFERENCE.md

测试与回归

pytest -q
npm --prefix frontend run build

相关文档：

• docs/architecture-dataflow.md
• docs/testing.md
• docs/backend-smoke-test-results.md