A Python library that gives robots a memory of what they tried, what happened, and what to do differently next time.
Robots fail. This repo helps them remember those failures.
Robot Experience Memory stores robot experiences as:
state -> action -> outcome
Then it helps software:
record what happened
find similar past situations
replay execution history
suggest recovery actions
Imagine a robot tries to pick up a part.
Sometimes it succeeds.
Sometimes it fails because:
- the part moved,
- the gripper missed,
- the object was misaligned,
- the path was blocked,
- the robot needed human help.
Usually, these events become logs.
This repo turns those events into reusable memory.
So instead of asking:
"What happened in the log?"
You can ask:
"Have we seen this before, and what worked last time?"
Most robot systems have:
- logs,
- telemetry,
- rosbags,
- traces,
- error messages.
These are useful for humans.
But they are not easy for software to reuse as memory.
Robot Experience Memory creates a structured memory layer around robot execution.
It stores each attempt as an experience.
Each experience contains:
state = what the robot or world looked like
action = what the robot tried to do
outcome = what happened after the action
metadata = context around the attempt
You can use this repo to:
- record robot task attempts,
- store successful and failed experiences,
- replay past execution history,
- retrieve similar past failures,
- suggest retry, fallback, or escalation actions,
- build robot recovery demos,
- evaluate memory-based robot behavior,
- connect memory to ROS2 workflows,
- test industrial scenarios in simulation.
This repo is not:
- a robot controller,
- a motion planner,
- a physics simulator,
- a replacement for ROS2,
- a replacement for rosbag,
- an LLM agent framework,
- a vector database.
It does not move the robot by itself.
It stores and analyzes robot experiences so another system can make better decisions.
Robot / Simulator / ROS2
|
v
Experience Recorder
|
v
Memory Store
|
+--> Replay Engine
|
+--> Retrieval Engine
|
+--> Recovery Engine
|
v
Reports / Evaluation / Debugging
Typed models for:
StateSnapshot
ActionRecord
OutcomeRecord
Metadata
ExperienceRecord
ExperienceBundle
These define what one robot experience contains.
Backends for saving experiences:
InMemoryStore
JSONLStore
SQLiteStore
Use in-memory for tests, JSONL for simple files, and SQLite for durable local storage.
The recorder captures successful and failed robot attempts.
Example:
from robot_experience_memory.recorder import ExperienceRecorder
from robot_experience_memory.store import InMemoryStore
store = InMemoryStore()
recorder = ExperienceRecorder(store)
experience = recorder.record(
state={"battery_level": 90.0},
action={"action_type": "pick", "command": "close_gripper"},
outcome={
"success": False,
"summary": "gripper missed the part",
"error_code": "GRASP_MISSED",
},
metadata={
"robot_id": "robot-a",
"environment": "lab",
"tags": ("pick-place", "failure"),
},
)Replay stored experiences as structured events.
This is useful for debugging, reports, demos, and validation.
from robot_experience_memory.replay import ReplayConfig, ReplayEngine
report = ReplayEngine(store, ReplayConfig(speed_multiplier=0.0)).replay()
print(report.total_experiences)Find similar past experiences.
Example question:
"Show me previous pick failures from this robot."
from robot_experience_memory.retrieval import RetrievalEngine, RetrievalQuery
engine = RetrievalEngine(store)
result = engine.retrieve(
RetrievalQuery(action_type="pick", robot_id="robot-a", top_k=3)
)
for match in result.matches:
print(match.score, match.experience.experience.experience_id)Suggest what to do after a failure.
Possible suggestions:
retry
fallback
escalate
Example:
from robot_experience_memory.recovery import RecoveryEngine
suggestion = RecoveryEngine(store).suggest_recovery(experience)
print(suggestion.suggestion_type, suggestion.confidence)The repo includes optional ROS2 integration helpers.
ROS2 is not required to install or test the package.
Use this when you want to connect memory to ROS-style robot execution, lifecycle nodes, rosbags, replay events, retrieval callbacks, or recovery callbacks.
A robot is doing a pick-and-place task.
State: object at position A
Action: close gripper
Outcome: failed, object slipped
Memory stores this failure.
State: similar object position
Action: close gripper
Outcome: failed again
Retrieval finds the previous similar failure.
Recovery suggests:
retry with adjusted approach
Now the robot system has a memory-backed reason for what to try next.
This repo includes synthetic industrial validation datasets for:
CNC tending
pick-and-place
failure recovery
retrieval evaluation
recovery evaluation
These are not real factory logs, but they are useful for testing the memory system.
pip install -e .[dev]pytest
ruff check .
mypy .
python -m buildVersion: v0.2.0
Tests: 218 passing
Typing: MyPy strict
Linting: Ruff clean
Build: passing
Python: 3.11+
License: MIT
Use this repo if you are building:
- robot task memory,
- failure recovery systems,
- replay/debugging tools,
- ROS2 memory adapters,
- industrial robot evaluation demos,
- memory-based robot learning experiments.
Do not use this repo if you need:
- real-time robot control,
- motion planning,
- low-level motor commands,
- physics simulation,
- neural policy training,
- LLM-based planning.
This repo works around those systems. It does not replace them.
Next useful validation targets:
- Gazebo pick-and-place demo
- RViz memory visualization
- real rosbag-backed dataset
- LeRobot adapter
- real robot execution logs
- benchmark against no-memory baseline
Latest release:
v0.2.0
MIT