MuscleMemory

MuscleMemory is an open-source procedural memory system from TheWariend for AI coding agents. It watches agent sessions, learns how a task was done when tests pass after the last change, and hands the agent a short note the next time a similar task comes up. It runs locally by default with SQLite and is released under Apache-2.0.

What It Is

MuscleMemory stores procedures that a test proved, not conversations. Hooks capture each tool call an agent makes, with secrets removed before storage. A session teaches something only when a test passed after the last code change and every tool call was captured. Learned skills are surfaced to agents as guidance; the agent still reads current files and asks for approval as usual, and MuscleMemory never re-runs an old session.

How the trust lifecycle works

A new skill must pass two separate later sessions and then wait for the user's approval in the dashboard before any agent sees it. One failed check pauses it. Failed attempts are turned into plain "watch out" notes so agents avoid repeated dead ends. Native hooks also check that files a skill relies on still exist and that stored edits match before delivering a note; if nothing fits, nothing is added.

What the agent receives

The note is added once at the start of a session, at most 350 tokens. It carries a warning that it is an untrusted prior result, the files that changed, before-and-after edit snippets, the test command that passed, and one thing to avoid. Skills can be shared across agents, so a skill learned with Codex can be used by Claude Code or Cursor, and proven skills can be exported as SKILL.md.

Integrations and deployment

It connects to Claude Code, Codex, Cursor and CleanSlate through hooks, to any MCP client through five tools (recall, observe, learn, evaluate, inspect), and to custom agents through Python and TypeScript SDKs. Browser agents are supported through an optional browser that learns site-confirmed skills. Data stays local by default; PostgreSQL with pgvector is available for team sharing, and a hosted option is described as planned.

Benchmark claims and status

The project reports that in a Codex run over nine paired tasks, input tokens fell 25.5%, tool calls 30.4% and wall time 28.2%, with every task still passing in both modes. It states these results show repeat tasks getting cheaper rather than higher success rates, and that the Claude Code run is small. The README describes the project as early, with benchmarks covering repeat tasks on three controlled codebases.