MCP 服务器

robotmem 通过 Model Context Protocol (MCP) 暴露 6 个工具，使任何兼容 MCP 的客户端都可以读写机器人记忆。

启动服务器

# stdio 模式（MCP 标准）
python -m robotmem

服务器使用官方 mcp SDK 中的 FastMCP，通过 stdio 通信。

服务器生命周期

启动
  │
  ├── load_config()         → 从 ~/.robotmem/config.json 加载配置
  ├── CogDatabase(config)   → SQLite 连接 + Schema 初始化
  │   ├── PRAGMA WAL/busy_timeout/synchronous/cache_size
  │   ├── initialize_schema()  → 5 张表 + 7 个索引 + FTS5 + 触发器
  │   ├── initialize_vec()     → vec0 虚拟表（需 sqlite-vec 可用）
  │   └── _ensure_tag_meta()   → 同步 50+ 标签到 tag_meta 表
  ├── create_embedder()     → ONNX 或 Ollama 后端
  └── check_availability()  → 验证嵌入服务可用性
  │
  ▼ 就绪 — 6 个工具可用
  │
关闭
  ├── embedder.close()      → 关闭 HTTP 客户端（Ollama）或释放模型（ONNX）
  └── db_cog.close()        → 关闭 SQLite 连接

工具定义

learn

工具: learn
描述: 记录物理经验（陈述性记忆）

参数:
  insight: str（必填）— 经验文本，1-300 字符
  context: str — JSON 上下文，包含 params/spatial/robot/task
  collection: str — 命名空间（默认: "default"）
  session_id: str — 关联到会话

recall

工具: recall
描述: 检索经验 — BM25 + Vec 混合搜索

参数:
  query: str（必填）— 搜索查询
  collection: str — 命名空间（默认: "default"）
  n: int — 结果数量，1-100（默认: 5）
  min_confidence: float — 阈值 0.0-1.0（默认: 0.3）
  session_id: str — 过滤到 episode
  context_filter: str — JSON 结构化过滤器
  spatial_sort: str — JSON 空间排序

save_perception

工具: save_perception
描述: 存储感知/轨迹/力数据

参数:
  description: str（必填）— 描述，至少 5 个字符
  perception_type: str — visual|tactile|auditory|proprioceptive|procedural（默认: "visual"）
  data: str — JSON 传感器数据
  metadata: str — JSON 元数据
  collection: str — 命名空间
  session_id: str — 关联到会话

forget

工具: forget
描述: 软删除错误的记忆

参数:
  memory_id: int（必填）— 记忆 ID，必须 > 0
  reason: str（必填）— 删除原因

update

工具: update
描述: 修正记忆的内容

参数:
  memory_id: int（必填）— 记忆 ID，必须 > 0
  new_content: str（必填）— 更新后的文本，1-300 字符
  context: str — 更新后的上下文 JSON

start_session

工具: start_session
描述: 开始一个新的 episode

参数:
  collection: str — 命名空间（默认: "default"）
  context: str — Episode 上下文 JSON

end_session

工具: end_session
描述: 结束 episode — 合并 + 主动召回

参数:
  session_id: str（必填）— 来自 start_session 的会话 ID
  outcome_score: float — 成功评分 0.0-1.0

客户端配置示例

Claude Code

~/.claude/settings.json：

{
  "mcpServers": {
    "robotmem": {
      "command": "python",
      "args": ["-m", "robotmem"]
    }
  }
}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "robotmem": {
      "command": "python",
      "args": ["-m", "robotmem"]
    }
  }
}

自定义配置

{
  "mcpServers": {
    "robotmem": {
      "command": "python",
      "args": ["-m", "robotmem"],
      "env": {
        "ROBOTMEM_HOME": "/path/to/project/.robotmem"
      }
    }
  }
}

错误处理

所有工具都使用 @mcp_error_boundary 包装：

• 数据库错误 → {"error": "数据库异常，请查看服务端日志"}
• 未知错误 → {"error": "内部错误，请查看服务端日志"}
• 验证错误 → {"error": "参数校验失败 (field): message"}

服务器永远不会因工具错误而崩溃——所有异常都会被捕获并作为结构化错误响应返回。

日志

服务器将日志输出到 stderr。关键日志信息：

INFO  robotmem 启动: onnx 后端可用，模型 BAAI/bge-small-en-v1.5 (384d)
INFO  CogDatabase 已连接: ~/.robotmem/memory.db (vec=True, dim=384)
INFO  MCP start_session: session_id=abc-123, collection=default
INFO  MCP end_session: session_id=abc-123, memories=15, decayed=42, consolidated=3
WARN  recall BM25 搜索异常: ...
WARN  learn embedding 失败: ...  (降级为仅 BM25)