muscle-mem 0.0.1

muscle memory

Muscle Memory

muscle-mem is a skill cache for AI agents.

It is a Python SDK that records your agent's tool-calling patterns as it solves tasks, and will deterministically replay those learned trajectories whenever the task is encountered again, falling back to agent mode if edge cases are detected.

The goal of muscle-mem is to get LLMs out of the hotpath for repetitive tasks, increasing speed, reducing variability, and eliminating token costs for the many cases that could have just been a script.

This system is inspired by:

• Building computer-use agents at Pig.dev, and realizing users don't want AI, they just want better RPA
• The Voyager paper
• JIT compilers
• Human muscle memory

Dev Log

• May 7, 2025 - First working demo
• May 8, 2025 - Open sourced

How It Works

muscle-mem is not another agent framework.

You implement your agent however you want, and then plug it into muscle-mem's engine.

When given a task, the engine will:

1. determine if the environment has been seen before (cache-hit), or if it's new (cache-miss) using Checks
2. perform the task, either
   • using the retrieved trajectory on cache-hit,
   • or passing the task to your agent on cache-miss.
3. collect tool call events to add to cache as a new trajectory

It's all about Cache Validation

To add safe tool reuse to your agent, the critical question is cache validation. Ask yourself:

For each tool we give to our agent, what features in the environment can be used to indicate whether or not it's safe to perform that action?

If you can answer this, your agent can have Muscle Memory.

Docs

muscle-mem is a Python SDK to instrument tool calls with custom cache validation functions.

It sits on top of

Prior trajectories are stored in an in-process database

It runs an in-memory database to store prior observations, using

Installation

pip install muscle-mem

Instrumenting your tools

Use the tool decorator to capture all invocations of your action-taking functions.

from muscle_mem import Engine

engine = Engine()

@engine.tool()
def greet(name: str):
    print(f"Hello {name}!")

Adding Checks

Checks can be run before, or after, a tool call, to capture data from the engironment at runtime, and compare the current environment against past environments at query time.