MCP Server

robotmem exposes 6 tools via the Model Context Protocol (MCP), enabling any MCP-compatible client to read and write robot memories.

Starting the Server

# stdio mode (standard for MCP)
python -m robotmem

The server uses FastMCP from the official mcp SDK and communicates over stdio.

Server Lifecycle

Start
  │
  ├── load_config()         → Config from ~/.robotmem/config.json
  ├── CogDatabase(config)   → SQLite connection + schema init
  │   ├── PRAGMA WAL/busy_timeout/synchronous/cache_size
  │   ├── initialize_schema()  → 5 tables + 7 indexes + FTS5 + triggers
  │   ├── initialize_vec()     → vec0 virtual table (if sqlite-vec available)
  │   └── _ensure_tag_meta()   → sync 50+ tags to tag_meta table
  ├── create_embedder()     → ONNX or Ollama backend
  └── check_availability()  → verify embedding service
  │
  ▼ Ready — 6 tools available
  │
Shutdown
  ├── embedder.close()      → close HTTP client (Ollama) or release model (ONNX)
  └── db_cog.close()        → close SQLite connection

Tool Definitions

learn

Tool: learn
Description: Record physical experience (declarative memory)

Parameters:
  insight: str (required) — Experience text, 1-300 chars
  context: str — JSON context with params/spatial/robot/task
  collection: str — Namespace (default: "default")
  session_id: str — Link to session

recall

Tool: recall
Description: Retrieve experience — BM25 + Vec hybrid search

Parameters:
  query: str (required) — Search query
  collection: str — Namespace (default: "default")
  n: int — Results count, 1-100 (default: 5)
  min_confidence: float — Threshold 0.0-1.0 (default: 0.3)
  session_id: str — Filter to episode
  context_filter: str — JSON structured filter
  spatial_sort: str — JSON spatial sorting

save_perception

Tool: save_perception
Description: Store perception/trajectory/force data

Parameters:
  description: str (required) — Description, min 5 chars
  perception_type: str — visual|tactile|auditory|proprioceptive|procedural (default: "visual")
  data: str — JSON sensor data
  metadata: str — JSON metadata
  collection: str — Namespace
  session_id: str — Link to session

forget

Tool: forget
Description: Soft-delete an erroneous memory

Parameters:
  memory_id: int (required) — Memory ID, must be > 0
  reason: str (required) — Deletion reason

update

Tool: update
Description: Correct a memory's content

Parameters:
  memory_id: int (required) — Memory ID, must be > 0
  new_content: str (required) — Updated text, 1-300 chars
  context: str — Updated context JSON

start_session

Tool: start_session
Description: Begin a new episode

Parameters:
  collection: str — Namespace (default: "default")
  context: str — Episode context JSON

end_session

Tool: end_session
Description: End episode — consolidate + proactive recall

Parameters:
  session_id: str (required) — Session ID from start_session
  outcome_score: float — Success score 0.0-1.0

Client Configuration Examples

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"]
    }
  }
}

With Custom Config

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

Error Handling

All tools are wrapped with @mcp_error_boundary:

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

The server never crashes on tool errors — all exceptions are caught and returned as structured error responses.

Logging

The server logs to stderr. Key log messages:

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 失败: ...  (degrades to BM25-only)