配置
robotmem 使用 3 层配置：dataclass 默认值 → ~/.robotmem/config.json → 环境变量。
配置文件
位置：~/.robotmem/config.json（首次运行时自动创建）
只需指定非默认值：
{
"embed_backend": "onnx",
"onnx_model": "BAAI/bge-small-en-v1.5"
}
所有设置
数据库
| 设置项 | 默认值 | 说明 |
|---|---|---|
db_path |
~/.robotmem/memory.db |
SQLite 数据库文件路径 |
向量嵌入
| 设置项 | 默认值 | 说明 |
|---|---|---|
embed_backend |
"onnx" |
向量嵌入后端："onnx" 或 "ollama" |
onnx_model |
"BAAI/bge-small-en-v1.5" |
FastEmbed ONNX 模型名称 |
onnx_dim |
384 |
ONNX 模型嵌入维度 |
fastembed_cache_dir |
""（系统默认） |
FastEmbed 模型缓存目录 |
embedding_model |
"nomic-embed-text" |
Ollama 向量嵌入模型名称 |
embedding_dim |
768 |
Ollama 模型嵌入维度 |
ollama_url |
"http://localhost:11434" |
Ollama API 端点 |
embed_api |
"ollama" |
Ollama API 风格："ollama" 或 "openai_compat" |
搜索
| 设置项 | 默认值 | 说明 |
|---|---|---|
top_k |
10 |
默认返回结果数 |
rrf_k |
60 |
RRF 融合常数（越大 = 低排名权重越高） |
记忆默认值
| 设置项 | 默认值 | 说明 |
|---|---|---|
collection |
"default" |
默认集合名称 |
default_confidence |
0.9 |
新记忆的初始置信度 |
default_decay_rate |
0.01 |
默认每日时间衰减率 |
min_confidence |
0.3 |
recall 过滤的默认最低置信度 |
环境变量
| 变量 | 作用 |
|---|---|
ROBOTMEM_HOME |
覆盖配置/数据库目录（默认：~/.robotmem） |
# 示例：使用项目专属数据库
export ROBOTMEM_HOME=/path/to/project/.robotmem
python -m robotmem
向量嵌入后端对比
| 维度 | ONNX（默认） | Ollama |
|---|---|---|
| 配置 | 零配置 | 需要 ollama serve + 拉取模型 |
| 速度 | ~5ms/查询 | ~20-50ms/查询 |
| 模型大小 | 67MB（自动下载） | 274MB（nomic-embed-text） |
| CPU/GPU | 纯 CPU | CPU（可选 GPU） |
| 离线 | 首次下载后完全离线 | 需要本地 Ollama 服务器 |
| 维度 | 384d | 768d |
| 质量 | MTEB retrieval 51.68 | 某些任务表现更好 |
| 多语言 | 有限 | 使用多语言模型时更好 |
切换到 Ollama
{
"embed_backend": "ollama",
"embedding_model": "nomic-embed-text",
"embedding_dim": 768,
"ollama_url": "http://localhost:11434"
}
ollama pull nomic-embed-text
OpenAI 兼容 API
对于暴露 OpenAI 兼容 /v1/embeddings 端点的向量嵌入服务器：
{
"embed_backend": "ollama",
"embed_api": "openai_compat",
"embedding_model": "your-model-name",
"embedding_dim": 768,
"ollama_url": "http://your-server:8080"
}
数据库 PRAGMA 设置
robotmem 使用生产优化的 SQLite 设置（不可配置）：
| PRAGMA | 值 | 原因 |
|---|---|---|
journal_mode |
WAL | 并发读取 + 单写入 |
busy_timeout |
5000ms | 数据库锁定时等待最多 5 秒 |
synchronous |
NORMAL | 安全性和性能之间的平衡 |
cache_size |
-8000 (8MB) | 适合机器人工作负载的合理内存用量 |
集合
集合是用于分隔记忆的逻辑命名空间。常见模式：
# 按机器人分集合
start_session(collection="fetch-001")
start_session(collection="ur5e-003")
# 按任务分集合
learn(insight="...", collection="grasping")
learn(insight="...", collection="navigation")
# 默认集合
learn(insight="...") # 使用 "default"
所有 recall、learn、save_perception 工具都接受 collection 参数。
优雅降级
robotmem 设计为即使组件失败也能正常工作：
| 组件 | 故障 | 行为 |
|---|---|---|
| sqlite-vec | 未安装 | 向量搜索禁用，仅 BM25 |
| 向量嵌入（ONNX/Ollama） | 模型不可用 | 向量搜索禁用，仅 BM25 |
| jieba | 未安装 | CJK 分词禁用，英文搜索正常 |
| FTS5 | 创建失败 | 全文搜索禁用（罕见） |
MCP 工具始终返回有效响应 — 错误会被记录但永远不会导致服务器崩溃。