安装

快速安装

pip install robotmem

这将安装带有 ONNX 向量嵌入支持的核心库（纯 CPU，无需外部服务）。

系统要求

可选依赖

# Web 管理界面
pip install robotmem[web]

# Ollama 向量嵌入后端（替代 ONNX）
pip install robotmem[ollama]

# CJK（中日韩）全文搜索
pip install robotmem[cjk]

# 开发（测试）
pip install robotmem[dev]

作为 MCP 服务器运行

Claude Code

添加到 Claude Code MCP 设置（~/.claude/settings.json）：

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

Claude Desktop

添加到 Claude Desktop 的配置文件：

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

直接 Python 导入

from robotmem import learn, recall, save_perception, start_session, end_session

注意：直接导入时，函数是 MCP 工具相同逻辑的轻量包装。

运行 Web 界面

# 默认: http://127.0.0.1:6889
python -m robotmem web

# 自定义端口
python -m robotmem web --port 8080

# 自定义主机（暴露到网络）
python -m robotmem web --host 0.0.0.0 --port 6889

Web 界面提供： - 记忆浏览器，支持分页和过滤 - 跨所有记忆的全文搜索 - 会话时间线视图 - 集合管理 - 健康诊断（/api/doctor）

验证安装

1. 检查 MCP 服务器

python -m robotmem
# 应启动 MCP 服务器（等待 stdio 输入）
# 按 Ctrl+C 退出

2. 检查 Web 界面

python -m robotmem web
# 在浏览器中打开 http://127.0.0.1:6889
# 访问 http://127.0.0.1:6889/api/doctor 进行健康检查

3. 检查向量嵌入

from robotmem.embed_onnx import FastEmbedEmbedder
import asyncio

emb = FastEmbedEmbedder()
ok = asyncio.run(emb.check_availability())
print(f"ONNX 向量嵌入可用: {ok}")
# 首次运行会下载模型（~67MB）到 ~/.cache/fastembed/

数据存储位置

默认所有数据存储在 ~/.robotmem/：

~/.robotmem/
├── memory.db          # SQLite 数据库（记忆、会话、标签）
└── config.json        # 配置覆盖（可选）

通过 ROBOTMEM_HOME 环境变量覆盖：

export ROBOTMEM_HOME=/path/to/custom/dir

故障排除

sqlite-vec 加载失败

WARNING: sqlite-vec 加载失败

这表示向量搜索不可用，但 robotmem 仍可使用 BM25 纯文本搜索。修复方法：

pip install --upgrade sqlite-vec

fastembed 模型下载失败

首次运行会下载 ONNX 模型。如果失败（网络问题）：

# 手动下载
python -c "from fastembed import TextEmbedding; TextEmbedding('BAAI/bge-small-en-v1.5')"

Ollama 向量嵌入无法连接

# 确保 Ollama 正在运行
ollama serve

# 拉取向量嵌入模型
ollama pull nomic-embed-text

# 测试
curl http://localhost:11434/api/embed -d '{"model": "nomic-embed-text", "input": "test"}'