API Reference

Complete parameter documentation for all 6 MCP tools.

learn

Record declarative experience (facts, strategies, lessons, observations).

Parameters

Parameter	Type	Required	Default	Description
`insight`	string	Yes	—	Experience text (1–300 chars, auto-trimmed)
`context`	string	No	`""`	JSON context with params/spatial/robot/task partitions
`collection`	string	No	`"default"`	Logical namespace for grouping memories
`session_id`	string	No	`null`	Link to a session (from `start_session`)

Returns

Success:

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

Duplicate detected:

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

Auto-Classification Categories

Category	Trigger Pattern	Decay	Example
`constraint`	"must always", "never", "forbidden"	None (protected)	"Must never exceed 15N grip force"
`preference`	"prefer X over Y", "recommended to use"	Normal	"Prefer approach from left side"
`worldview`	"X is better than Y", "from now on"	Normal	"ONNX is faster than Ollama for small models"
`tradeoff`	"tradeoff", "pros and cons", "vs"	Normal	"Speed vs accuracy: use 10Hz for real-time"
`root_cause`	"caused by", "because", "root cause"	Normal	"Failure caused by sensor drift"
`decision`	"chose", "decided", "instead of"	Normal	"Chose PID over MPC for simplicity"
`pattern`	"every time", "whenever", "recurring"	Normal	"Every time humidity > 80%, grip fails"
`postmortem`	"lesson", "postmortem"	None (protected)	"Lesson: always calibrate before new session"
`gotcha`	"gotcha", "pitfall", "trap"	None (protected)	"Pitfall: joint limits not checked in sim"
`observation`	"found that", "discovered", "noticed"	Normal	"Found that red cups require more force"
`code`	(default fallback)	Normal	General technical notes

Deduplication Pipeline

Layer 1: Exact match       → content_hash SHA-256 + memory_exists()
Layer 2: Jaccard > 0.70    → FTS5 candidates + token overlap
Layer 3: Cosine > 0.85     → Vector similarity (if embedder available)

recall

Retrieve relevant experience using BM25 + vector hybrid search.

Parameters

Parameter	Type	Required	Default	Description
`query`	string	Yes	—	Search query (natural language)
`collection`	string	No	`"default"`	Collection to search in
`n`	int	No	`5`	Number of results (1–100)
`min_confidence`	float	No	`0.3`	Minimum confidence threshold (0.0–1.0)
`session_id`	string	No	`null`	Filter to specific episode
`context_filter`	string	No	`null`	JSON structured filter (see below)
`spatial_sort`	string	No	`null`	JSON spatial sorting (see below)

Returns

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

Search Modes

Mode	When	Pipeline
`hybrid`	Embedder available + both return results	BM25 + Vec → RRF merge
`bm25_only`	Embedder unavailable or vec returns empty	BM25 only
`vec_only`	BM25 returns empty (rare)	Vector only

context_filter Syntax

JSON object where keys are dot-paths into the context JSON:

// Equality
{"task.success": true}

// Range operators
{"params.force.value": {"$lt": 15.0}}
{"params.force.value": {"$gte": 10.0, "$lte": 20.0}}

// Combined (AND logic)
{"task.success": true, "robot.type": "UR5e"}

Operator	Meaning
(none)	Exact equality
`$lt`	Less than
`$lte`	Less than or equal
`$gt`	Greater than
`$gte`	Greater than or equal
`$ne`	Not equal

Limits: max 10 filter conditions per query.

spatial_sort Syntax

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

field: Dot-path to a coordinate array in context JSON
target: Reference position (any dimensionality)
max_distance: Optional cutoff (Euclidean distance)

Source Weighting

Memories from real-world data get 1.5x weight boost over simulation data. Detected via context.env.sim_or_real == "real".

save_perception

Store perception/trajectory/force data (procedural memory).

Parameters

Parameter	Type	Required	Default	Description
`description`	string	Yes	—	Human-readable description (min 5 chars)
`perception_type`	string	No	`"visual"`	One of: `visual`, `tactile`, `auditory`, `proprioceptive`, `procedural`
`data`	string	No	`null`	JSON sensor data (actions, trajectories, readings)
`metadata`	string	No	`null`	JSON metadata (format, sample rate, units)
`collection`	string	No	`"default"`	Collection namespace
`session_id`	string	No	`null`	Link to session

Returns

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

Perception Types

Type	Use Case	Typical Data
`visual`	Camera, scene description	Image features, object detection results
`tactile`	Force/torque sensors	Contact events, grip force readings
`auditory`	Sound, voice	Audio features, command transcripts
`proprioceptive`	Joint state, pose	Joint angles, velocities, end-effector pose
`procedural`	Action sequences	Sampled trajectories, step-by-step plans

forget

Soft-delete an erroneous memory.

Parameters

Parameter	Type	Required	Description
`memory_id`	int	Yes	Memory ID to delete (must be > 0)
`reason`	string	Yes	Explanation for deletion

Returns

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

The memory is soft-deleted (status → invalidated), not physically removed. This preserves audit trails.

update

Modify an existing memory's content.

Parameters

Parameter	Type	Required	Default	Description
`memory_id`	int	Yes	—	Memory ID (must be > 0)
`new_content`	string	Yes	—	Updated content (1–300 chars)
`context`	string	No	`""`	Updated context JSON

Returns

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

Updating automatically: - Re-runs auto-classification - Re-generates embedding vector - Re-infers semantic tags

start_session

Begin a new episode.

Parameters

Parameter	Type	Required	Default	Description
`collection`	string	No	`"default"`	Collection namespace
`context`	string	No	`null`	Episode context JSON (robot, environment, task)

Returns

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

end_session

End an episode — triggers time decay, consolidation, and proactive recall.

Parameters

Parameter	Type	Required	Default	Description
`session_id`	string	Yes	—	Session ID from `start_session`
`outcome_score`	float	No	`null`	Episode success score (0.0–1.0)

Returns

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

Consolidation Rules

Only triggered when session has >= 3 consolidatable memories
Protected categories are never consolidated: constraint, postmortem, gotcha
High confidence memories (>= 0.95) are never consolidated
Perceptions (type=perception) are never consolidated
Uses Jaccard similarity > 0.50 threshold
Keeps the memory with highest confidence (ties: highest access_count, then newest)

Time Decay Formula

confidence_new = confidence × (1 - decay_rate) ^ days_since_last_access

Default decay_rate: 0.01 (1% per day)
Only applied when days_since_last_access > 1.0
Only applied when confidence > 0.05
Base time: last_accessed (updated by recall hits), fallback to created_at

← Previous Configuration Getting Started Next → MCP Server Core Concepts