快速开始

本章节是 GitHub Wiki: Getting Started 的镜像。

1. 构建

# 克隆仓库
git clone https://github.com/lingtian303/MemoryCenter.git
cd MemoryCenter

# 构建动态库（memory_center.dll / libmemory_center.so / libmemory_center.dylib）
cargo build --release -p memory-center-ffi

# 构建产物位于：
#   Windows: target/release/memory_center.dll
#   Linux:   target/release/libmemory_center.so
#   macOS:   target/release/libmemory_center.dylib

2. 接入方式选择

3. MCP Server 一键配置（推荐）

最简接入：构建 MCP server 二进制，在客户端配置文件中指定 command 即可。

cargo build --release -p memory-center-mcp
# 产物：target/release/memory-center-mcp

客户端配置（Claude Code / Cursor / Trae）：

{
  "mcpServers": {
    "memory-center": {
      "command": "/path/to/memory-center-mcp",
      "env": {
        "MEMORY_CENTER_ROOT": "/path/to/memory/data"
      }
    }
  }
}

启动后 Agent 会自动发现 21 个 tools，无需额外编码。

4. 下一步

• 理解 整体架构
• 选择合适的 Crate
• 详细配置见 MCP 配置指南

整体架构

本章节是 GitHub Wiki: Architecture 的镜像。

三层分层架构

Layer 3: Bindings       ① Python 原生绑定 (PyO3)  ② WASM 组件  ③ Node/Go/Java
Layer 2: Interface      ① C ABI  ② Axum HTTP REST  ③ MCP stdio  ④ MCP Streamable HTTP
Layer 1: Core (Rust)    纯逻辑 crate（core-logic）+ facade crate（core）

架构图

flowchart TB
    subgraph L3["Layer 3 · Bindings"]
        PY["Python (PyO3)"]
        WASM["WASM"]
        NODE["Node.js (napi-rs)"]
    end
    subgraph L2["Layer 2 · Interface"]
        FFI["C ABI"]
        HTTP["HTTP REST (Axum)"]
        MCP["MCP Server"]
    end
    subgraph L1["Layer 1 · Core (Rust)"]
        CORE["memory-center-core (facade)"]
        LOGIC["core-logic (纯逻辑)"]
        SEARCH["search (BM25 + 语义)"]
        LLM["llm (摘要+冲突)"]
        PRESET["presets (11 Agent + 7 Scenario)"]
    end
    subgraph STORE["Storage"]
        SQLITE["SQLite (含向量)"]
        FILE["文件树"]
    end

    PY --> FFI
    WASM --> LOGIC
    NODE --> FFI
    FFI --> CORE
    HTTP --> CORE
    MCP --> CORE
    CORE --> LOGIC
    CORE --> SEARCH
    CORE --> LLM
    CORE --> PRESET
    LOGIC --> STORE
    SEARCH --> STORE

设计原则

1. 纯逻辑与 IO 分离：core-logic 无 IO 依赖，可编译为 WASM；core 作为 facade 整合原生实现
2. 可插拔架构：Storage / Scorer / Migrator 等 trait 均可替换实现
3. 接入层无状态：HTTP / MCP server 无状态，水平扩展友好
4. 跨语言一致性：所有接入方式共享同一组核心操作（archive / retrieve / summaries / prompt / compaction）

数据流

归档流程

sequenceDiagram
    autonumber
    participant Agent
    participant MCP as MCP Server
    participant Core as Core
    participant Store as Storage

    Agent->>MCP: archive(session_id, turns_json)
    MCP->>Core: archive(turns)
    Core->>Store: freeze_context()
    Core->>Store: 生成索引钩子
    Store-->>Core: hook_id
    Core-->>MCP: 归档摘要
    MCP-->>Agent: 归档成功

检索流程

sequenceDiagram
    autonumber
    participant Agent
    participant MCP as MCP Server
    participant Core as Core
    participant Store as Storage

    Agent->>MCP: prompt(session_id)
    MCP->>Core: render_prompt()
    Core->>Store: load_summaries()
    Store-->>Core: 摘要钩子列表
    Core-->>MCP: prompt 文本
    MCP-->>Agent: 注入 system prompt

    Note over Agent,Store: LLM 需要细节时
    Agent->>MCP: retrieve(hook_id)
    MCP->>Core: retrieve(hook_id)
    Core->>Store: load_full_turns()
    Store-->>Agent: 完整对话上下文

详细文档

完整的架构设计文档见 docs/ARCHITECTURE.md（仓库内）与 Wiki: Architecture。

Crate 选择指南

本章节是 GitHub Wiki: Crate Guide 的镜像。

Crate 矩阵

选择决策树

你的场景是什么？
├─ AI 编程客户端（Claude Code / Cursor / Trae）
│   └─ memory-center-mcp（stdio 模式）
├─ 远程 Agent / Web 端
│   └─ memory-center-server（MCP Streamable HTTP + REST API）
├─ Python 项目
│   └─ memory-center-python（PyO3 原生绑定）
├─ Node.js 项目
│   └─ memory-center-node（napi-rs）
├─ C/C++ 项目
│   └─ memory-center-ffi（C ABI 动态库）
├─ Rust 项目
│   └─ memory-center-core（直接依赖 facade crate）
├─ 浏览器 / Edge
│   └─ memory-center-wasm（wasm-bindgen）
└─ 其他语言
    └─ 通过 HTTP REST API 接入

依赖关系

• core-logic：纯逻辑，无 IO 依赖，可编译为 WASM
• core：依赖 core-logic，添加原生 IO（SQLite / 文件树）
• ffi / python / node / wasm：依赖 core（或 core-logic for WASM）
• server / mcp：依赖 core + llm + search + presets 等
• 业务 crate 不可反向依赖入口 crate

详细文档

完整指南见 Wiki: Crate Guide。

MCP 集成

本章节是 GitHub Wiki: MCP Integration 的镜像。

MCP 是什么

MCP（Model Context Protocol）是 Anthropic 推出的 Agent 工具调用协议，主流 AI 编程客户端全支持。MemoryCenter MCP server 让 Agent 通过标准协议调用记忆库能力，无需自己实现归档/检索逻辑。

两种传输模式

21 个 Tools 一览

最简配置（stdio 模式）

{
  "mcpServers": {
    "memory-center": {
      "command": "/path/to/memory-center-mcp",
      "env": {
        "MEMORY_CENTER_ROOT": "/path/to/memory/data"
      }
    }
  }
}

Streamable HTTP 模式

{
  "mcpServers": {
    "memory-center": {
      "url": "https://your-server/mcp",
      "transport": "streamable-http"
    }
  }
}

详细配置

各环境详细配置、踩坑排查见 MCP 配置指南。

完整 MCP tools 实现见 crates/memory-center-mcp/src/lib.rs。 MCP 集成测试见 crates/memory-center-mcp/tests/（56 个测试用例）。

MCP 配置指南

本章节是 GitHub Wiki: MCP Configuration Guide 的镜像。

配置总览

MemoryCenter MCP 支持两种传输模式 × 四种部署环境，组合出 8 种典型配置场景。

详细配置文档

完整配置指南（含通用配置 / stdio / HTTP / Cloudflare / Docker / 环境变量参考 / 常见问题排查 / 配置检查清单）见 Wiki: MCP Configuration Guide。

关键环境变量速查

踩坑提示

1. Cloudflare CDN 必须 HTTPS：HTTP 请求会被 301 重定向到 HTTPS，MCP 客户端不处理重定向，导致 Connection closed
2. Binary 名称带连字符：memory-center-mcp（正确）vs memorycenter-mcp（错误）
3. HTTP 模式 Agent 识别：服务端无法获取 MCP ClientInfo，需通过 MEMORY_CENTER_PRESET_AGENT 环境变量指定

完整踩坑排查见 Wiki: MCP Configuration Guide §常见问题排查。

REST API 参考

本章节是 GitHub Wiki: API Reference 的镜像。

接口概览

所有 REST API 路径前缀：/api/v1

示例

归档

curl -X POST http://localhost:8765/api/v1/sessions/sess-001/archive \
  -H "Content-Type: application/json" \
  -d '{"turns": [...], "project_id": "proj-a"}'

获取摘要

curl http://localhost:8765/api/v1/sessions/sess-001/summaries

渲染 prompt

curl http://localhost:8765/api/v1/sessions/sess-001/prompt

检索记忆

curl http://localhost:8765/api/v1/sessions/sess-001/memories/<hook_id>

周期任务

curl -X POST http://localhost:8765/api/v1/sessions/sess-001/compaction \
  -H "Content-Type: application/json" -d '{"period": "weekly"}'

启动服务

MEMORY_CENTER_HOST=0.0.0.0 \
MEMORY_CENTER_PORT=8765 \
MEMORY_CENTER_ROOT=./data \
cargo run -p memory-center-server

完整文档

完整 API 文档（含请求/响应 schema、错误码、鉴权）见：

• Wiki: API Reference
• crates/memory-center-server/src/handlers.rs

部署指南

本章节是 GitHub Wiki: Deployment 的镜像。

部署方式选择

单二进制 + systemd（最简）

1. 构建二进制

cargo build --release -p memory-center-server
# 产物：target/release/memory-center-server

2. systemd 配置

# /etc/systemd/system/memory-center.service
[Unit]
Description=MemoryCenter Server
After=network.target

[Service]
Type=simple
User=mc
WorkingDirectory=/opt/memorycenter
Environment=MEMORY_CENTER_HOST=127.0.0.1
Environment=MEMORY_CENTER_PORT=8765
Environment=MEMORY_CENTER_ROOT=/var/lib/memorycenter/data
Environment=MEMORY_CENTER_MCP_ENABLED=true
Environment=MEMORY_CENTER_MCP_ALLOWED_HOSTS=your-domain.com,localhost,127.0.0.1
ExecStart=/opt/memorycenter/memory-center-server
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

3. 启动

sudo systemctl daemon-reload
sudo systemctl enable --now memory-center
sudo systemctl status memory-center

Nginx 反代配置

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /memory-center/ {
        proxy_pass http://127.0.0.1:8765/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;  # SSE 流需要
    }
}

完整文档

完整部署文档（含 Docker / Cloudflare / 备份 / 监控 / 排查）见：

• Wiki: Deployment
• deploy/ 目录

变更历史

本章节是 GitHub Wiki: Changelog 的镜像，保持与 CHANGELOG.md 同步。

版本状态

• ✅ MVP（P0-P5）：核心库 + C ABI 动态库 + 文档 + 示例 + 跨语言测试 + 性能基准
• ✅ v2.1：HTTP/Axum REST API 服务（无状态，水平扩展）
• ✅ v2.2：Python 原生绑定（PyO3 + maturin，OOP 风格 + 上下文管理器）
• ✅ v2.3：MCP Server（rmcp，stdio 传输）+ 预设系统（11 Agent + 7 Scenario）+ 差异化定位文档
• ✅ v2.3x：冲突检测 + 压缩前归档（pre_compress_hook）+ 语义检索 + project_memory 反向写入 + install_rules 规则安装
• ✅ v2.35：WASM 组件（wasm-bindgen + MemoryStorage + JsStorage + MemoryCenterCore JS API）
• ✅ v2.36：MCP Streamable HTTP 传输（/mcp 端点，与 REST API 共享 Axum 服务）
• ✅ v2.37：install_rules 远程模式（HTTPS MCP 模式下返回模板让 LLM 用 Write 工具创建文件）
• 🚧 v2.4 路线图：Go/Java 绑定 + 语义检索增强（向量库集成）

详细变更

完整变更历史见 CHANGELOG.md 与 Wiki: Changelog。