pip install robotmem

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

# Start an episode
session = start_session(context='{"robot_id": "arm-01", "task": "push"}')

# Record experience
learn(
    insight="grip_force=12.5N yields highest grasp success rate",
    context='{"params": {"grip_force": {"value": 12.5, "unit": "N"}}, "task": {"success": true}}'
)

# Retrieve experiences (structured filtering + spatial nearest-neighbor)
memories = recall(
    query="grip force parameters",
    context_filter='{"task.success": true}',
    spatial_sort='{"field": "spatial.position", "target": [1.3, 0.7, 0.42]}'
)

# Store perception data
save_perception(
    description="Grasp trajectory: 30 steps, success",
    perception_type="procedural",
    data='{"sampled_actions": [[0.1, -0.3, 0.05, 0.8], ...]}'
)

# End episode (auto-consolidation + proactive recall)
end_session(session_id=session["session_id"])

# Retrieve only successful experiences
recall(query="push to target", context_filter='{"task.success": true}')

# Find spatially nearest scenarios
recall(query="grasp object", spatial_sort='{"field": "spatial.object_position", "target": [1.3, 0.7, 0.42]}')

# Combine: success + distance  0.50 (protects constraint / postmortem / high-confidence entries)
- **Proactive Recall**: Returns historically relevant memories for the next episode

## FetchPush Demo

Three-phase experiment: baseline → memory writing → memory utilization. Expected Phase C success rate 10-20% higher than Phase A.

## Architecture

- CPU-only, no GPU required
- Single-file database `~/.robotmem/memory.db`
- MCP Server (7 tools) or direct Python import
- Web management UI: `robotmem web`

## Comparison

| Feature | MemoryVLA (Academic) | Mem0 (Product) | **robotmem** |
|---------|---------------------|----------------|-------------|
| Target users | Specific VLA models | Text AI | **Robotic AI** |
| Memory format | Vectors (opaque) | Text | **Natural language + perception + parameters** |
| Structured filtering | No | No | **Yes (`context_filter`)** |
| Spatial retrieval | No | No | **Yes (`spatial_sort`)** |
| Physical parameters | No | No | **Yes (`params` section)** |
| Installation | Compile from paper code | pip install | **pip install** |
| Database | Embedded | Cloud | **Local SQLite** |

## License

Apache-2.0