API 参考

全部 6 个 MCP 工具的完整参数文档。

learn

记录陈述性经验（事实、策略、教训、观察）。

参数

返回值

成功：

{
    "status": "created",
    "memory_id": 42,
    "auto_inferred": {
        "category": "observation",
        "confidence": 0.85,
        "tags": ["observation", "pattern"],
        "scope_files": []
    }
}

检测到重复：

{
    "status": "duplicate",
    "method": "jaccard",
    "existing_id": 15,
    "similarity": 0.78
}

自动分类类别

去重管道

第 1 层：精确匹配      → content_hash SHA-256 + memory_exists()
第 2 层：Jaccard > 0.70 → FTS5 候选 + token 重叠
第 3 层：Cosine > 0.85  → 向量相似度（需嵌入器可用）

recall

使用 BM25 + 向量混合搜索检索相关经验。

参数

返回值

{
    "memories": [
        {
            "id": 1,
            "content": "grip_force=12.5N optimal for cylindrical objects",
            "human_summary": "grip_force=12.5N optimal...",
            "type": "fact",
            "perception_type": null,
            "session_id": "abc-123",
            "category": "observation",
            "confidence": 0.85,
            "context": "{...}",
            "params": {"grip_force": {"value": 12.5}},
            "spatial": {"object_position": [1.3, 0.7, 0.42]},
            "robot": {"type": "UR5e"},
            "task": {"success": true},
            "_rrf_score": 1.0,
            "created_at": "2026-03-09T10:30:00"
        }
    ],
    "total": 1,
    "mode": "hybrid",
    "query_ms": 8.2
}

搜索模式

context_filter 语法

JSON 对象，键为 context JSON 中的点路径：

// 等值匹配
{"task.success": true}

// 范围运算符
{"params.force.value": {"$lt": 15.0}}
{"params.force.value": {"$gte": 10.0, "$lte": 20.0}}

// 组合（AND 逻辑）
{"task.success": true, "robot.type": "UR5e"}

限制：每次查询最多 10 个过滤条件。

spatial_sort 语法

{
    "field": "spatial.object_position",
    "target": [1.3, 0.7, 0.42],
    "max_distance": 0.1
}

• field：context JSON 中坐标数组的点路径
• target：参考位置（任意维度）
• max_distance：可选截断距离（欧几里得距离）

来源加权

来自真实世界数据的记忆相比仿真数据获得 1.5 倍权重提升。通过 context.env.sim_or_real == "real" 检测。

save_perception

存储感知/轨迹/力数据（程序性记忆）。

参数

返回值

{
    "memory_id": 42,
    "perception_type": "procedural",
    "collection": "default",
    "has_embedding": true
}

感知类型

forget

软删除错误的记忆。

参数

返回值

{
    "status": "forgotten",
    "memory_id": 3,
    "content": "grip_force=15N optimal...",
    "reason": "Sensor calibration error"
}

记忆被软删除（状态 → invalidated），而非物理移除。这样可以保留审计跟踪记录。

update

修改已有记忆的内容。

参数

返回值

{
    "status": "updated",
    "memory_id": 1,
    "old_content": "grip_force=12.5N optimal...",
    "new_content": "grip_force=11.0N optimal (recalibrated)...",
    "auto_inferred": {
        "category": "observation",
        "confidence": 0.85
    }
}

更新会自动： - 重新运行自动分类 - 重新生成嵌入向量 - 重新推断语义标签

start_session

开始一个新的 episode。

参数

返回值

{
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "collection": "default",
    "active_memories_count": 42
}

end_session

结束一个 episode —— 触发时间衰减、合并和主动召回。

参数

返回值

{
    "status": "ended",
    "session_id": "550e8400-...",
    "summary": {
        "memory_count": 15,
        "by_type": {"fact": 12, "perception": 3},
        "by_category": {"observation": 8, "pattern": 3}
    },
    "decayed_count": 42,
    "consolidated": {
        "merged_groups": 2,
        "superseded_count": 3,
        "compression_ratio": 0.2,
        "avg_similarity": 0.65
    },
    "related_memories": [
        {"id": 5, "content": "Similar experience from session X", "_rrf_score": 0.89}
    ]
}

合并规则

• 仅当会话拥有 >= 3 条可合并记忆时触发
• 受保护的类别不会被合并：constraint、postmortem、gotcha
• 高置信度记忆（>= 0.95）不会被合并
• 感知记忆（type=perception）不会被合并
• 使用 Jaccard 相似度 > 0.50 阈值
• 保留置信度最高的记忆（平局时：最高访问次数，再平局则取最新的）

时间衰减公式

confidence_new = confidence × (1 - decay_rate) ^ days_since_last_access

• 默认 decay_rate：0.01（每天 1%）
• 仅在 days_since_last_access > 1.0 时应用
• 仅在 confidence > 0.05 时应用
• 基准时间：last_accessed（由 recall 命中时更新），回退到 created_at