{"slug": "musclememory-open-source-procedural-memory-for-ai-agents", "title": "MuscleMemory: Open-source procedural memory for AI agents", "summary": "TheWariend released MuscleMemory, an Apache-2.0 open-source procedural memory system for AI coding agents that learns from sessions where tests pass after the last change and hands agents a short note on files to change, the proving test, and what to avoid. In a benchmark of real Codex sessions, MuscleMemory cut input tokens by 25.5%, tool calls by 30.4% and time by 28.2% with every task still passing, and an early Claude Code run with Sonnet 5.5 using Codex-learned skills cut input tokens by 43.5% and tool calls by 30%. On real Django issues from SWE-bench, Codex with a skill learned from other issues in the same area solved as many tasks as without memory using about half the tokens, and the tool installs via pipx with local-by-default operation on http://127.0.0.1:8080.", "body_md": "**Open-source procedural memory for AI agents.**\n\n  It learns from what worked and what failed.\n\n  Local by default · Apache-2.0 · by TheWariend\n\nCoding agents relearn the same things every session: which files to open, how the tests run, what broke last time. MuscleMemory watches your agent work. When a task really succeeds (the tests pass after the last change), it learns how the task was done. The next time a similar task comes up, it hands the agent a short note: the files to change, the test that proves it worked, and what to avoid.\n\nIn a benchmark with real Codex sessions, it cut **input tokens by 25.5%, tool calls by 30.4%\nand time by 28.2%**, with every task still passing. In an early run with Claude Code and\nSonnet 5.5, using skills that Codex had learned, it cut **input tokens by 43.5% and tool\ncalls by 30%**. On real Django issues from SWE-bench, with a skill learned from other\nissues in the same area, Codex solved as many as without memory with about half the tokens\n(a small run; [details](https://github.com/TheWariend/MuscleMemory/blob/main/benchmarks/results/codex/django-forms-01/report.md)).\nCheck them yourself: `python benchmarks/reproduce.py check`.\n[Codex method and data](https://github.com/TheWariend/MuscleMemory/blob/main/benchmarks/results/codex/luna-03/report.md) ·\n[Claude Code run](https://github.com/TheWariend/MuscleMemory/blob/main/benchmarks/results/claude/sonnet-01/report.md) ·\n[Whitepaper](https://github.com/TheWariend/MuscleMemory/blob/main/docs/whitepaper.md).\n\n```\npipx install thewariend-musclememory  # or, from a clone: pip install -e .\n\nmusclememory init                      # sets up ~/.musclememory and the small search model\nmusclememory start                     # runs in the background on http://127.0.0.1:8080\ncd your-project && musclememory connect codex   # or claude, cursor, cleanslate\nmusclememory dashboard                 # opens the dashboard, already signed in\n```\n\nThen use your agent as usual. There are no keys or config files to copy.\n\nOr let your agent set it up: paste this into Claude Code, Codex or Cursor.\n\n```\nRead https://thewariend.com/musclememory/llms.txt and set up MuscleMemory for this project.\n```\n\nMore in [Install](https://github.com/TheWariend/MuscleMemory/blob/main/docs/install.md).\n\n``` php\nflowchart LR\n    A[\"Your agent works on a task\"] --> B{\"Tests pass after the last change?\"}\n    B -- no --> C[\"Nothing is learned\"]\n    B -- yes --> D[\"Learn a skill or count a check\"]\n    D --> E[\"Two separate passing checks\"]\n    E --> F[\"You tap Keep\"]\n    F --> H[\"Hook checks current files\"]\n    H -->|\"match or partial match\"| G[\"Short note; warning on partial match\"]\n    H -->|\"mismatch\"| I[\"No note; skip recorded locally\"]\n    G --> A\n```\n\n- **Verified, twice.** Two later sessions must match the skill's actions and pass its\nown stored test command after the last code change. Pipes, redirects and shell\nwrappers are normalized; parameterized commands keep shape matching. Automatic\nchecks use the final passing test, so an unrelated test cannot count. The training\nsession doesn't count. Only real test runs count (`pytest` ,`python -m unittest` ,`go test` ,`cargo test` ,`npm test` ,`make test` and similar); commands that only\nmention tests, like`cargo build` or`ruff check` , don't.\n- **One failure pulls it.** If an agent was given a skill, changed code, and the skill's\nown test then failed as the last test run, the hooks report a failed check and the\nskill stops reaching agents. A session that just stops, or where a different test\nfailed, doesn't count against it.\n- **Learns from failures.** Failed attempts become plain \"watch out\" and \"if it goes wrong\"\nnotes, so the agent avoids the same dead ends.\n- **You stay in charge.** Every skill waits for your OK before any agent sees it, however\nit was learned (hooks, SDK, MCP or the API), and so does every new version. Only the\ndashboard can approve; an agent's own key can't. Skills you delete or retire stay\nremoved: the same skill isn't learned again. Agents still read the current files and ask for approval as usual.\nMuscleMemory never replays actions.\n- **Checks current files.** Native hooks require the files a skill found in place to\nstill exist (files it created may not exist yet) and at least one stored before or\nafter edit to match. If none match, they stay quiet; partial\nmatches include a warning that cannot be trimmed. Reads are bounded and reject\nsymlinks. File-check skips are recorded locally. Server and MCP recall have no file\naccess.[Exact rules](https://github.com/TheWariend/MuscleMemory/blob/main/docs/how-it-works.md#checking-current-files-in-hooks) .\n- **Quiet when it should be.** If nothing fits, nothing is added, and the agent pays no\nextra tokens.\n- **Shared between agents.** A skill learned with Codex is handed to Claude Code or\nCursor too: changing a file counts the same whichever tool did it.\nProven skills can also be exported to Codex or Claude Code as`SKILL.md` .\n- **Local and open.** SQLite and a small on-device model by default: no account and no\noutside calls. Use PostgreSQL with pgvector for teams.\n\nMore detail in [How it works](https://github.com/TheWariend/MuscleMemory/blob/main/docs/how-it-works.md).\n\n| Agent | How it connects | \n|---|---|\n| Claude Code | `musclememory connect claude` installs capture hooks | \n| Codex | `musclememory connect codex` installs capture hooks | \n| Cursor | `musclememory connect cursor` installs capture hooks | \n| CleanSlate | `musclememory connect cleanslate` wires its host stream | \n| Any MCP client | Five tools: recall, observe, learn, evaluate, inspect | \n| Your own agent | Python and TypeScript SDKs | \n\nSee [Integrations](https://github.com/TheWariend/MuscleMemory/blob/main/docs/integrations.md).\n\nProjects share skills within the same workspace (`namespace`, default `\"default\"`),\nrather than getting a separate workspace per repository. Cross-repository recall is\nuntested. [Give a project its own namespace](https://github.com/TheWariend/MuscleMemory/blob/main/docs/install.md#workspace-scope-and-project-isolation).\n\n| **Home:** what your agents can reuse, and anything waiting for your OK | **Skills:** each one with the task it came from, the files it changes and the test that checks it | \n| **A skill:** its steps in plain words, its proof, and what to watch out for | **Connect:** one command per agent | \n\n- [Whitepaper](https://github.com/TheWariend/MuscleMemory/blob/main/docs/whitepaper.md) : the design, trust rules, retrieval and evaluation in one paper\n- [Install and run](https://github.com/TheWariend/MuscleMemory/blob/main/docs/install.md) : local setup, Docker and PostgreSQL, configuration\n- [How it works](https://github.com/TheWariend/MuscleMemory/blob/main/docs/how-it-works.md) : the learning loop, retrieval, storage and security\n- [Integrations](https://github.com/TheWariend/MuscleMemory/blob/main/docs/integrations.md) : each agent, MCP and the SDKs\n- [Benchmarks](https://github.com/TheWariend/MuscleMemory/blob/main/docs/benchmarks.md) : results, method and limits\n- [API contracts](https://github.com/TheWariend/MuscleMemory/blob/main/docs/contracts.md) : MCP tools and REST\n- [Roadmap](https://github.com/TheWariend/MuscleMemory/blob/main/docs/roadmap.md) : what's next and known limits\n\nMuscleMemory has Python and TypeScript tests, with optional PostgreSQL and live Codex\nchecks. It's early. The benchmarks cover repeat tasks on three controlled codebases,\nnot every kind of work, and the Claude Code run is small. The hooks and CleanSlate learn on their own; with the SDKs your code\nreports when a task succeeded.\nSee the [roadmap](https://github.com/TheWariend/MuscleMemory/blob/main/docs/roadmap.md).\n\nIssues and pull requests are welcome. Please report security issues privately, as\ndescribed in [SECURITY.md](https://github.com/TheWariend/MuscleMemory/blob/main/SECURITY.md).\n\nApache-2.0. Made by [TheWariend](https://thewariend.com).", "url": "https://wpnews.pro/news/musclememory-open-source-procedural-memory-for-ai-agents", "canonical_source": "https://github.com/TheWariend/MuscleMemory", "published_at": "2026-10-16 03:06:23+00:00", "updated_at": "2026-10-16 03:32:19.961527+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-research", "artificial-intelligence"], "entities": ["MuscleMemory", "TheWariend", "Codex", "Claude Code", "Sonnet 5.5", "SWE-bench", "Django", "Cursor"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/musclememory-open-source-procedural-memory-for-ai-agents", "markdown": "https://wpnews.pro/news/musclememory-open-source-procedural-memory-for-ai-agents.md", "text": "https://wpnews.pro/news/musclememory-open-source-procedural-memory-for-ai-agents.txt", "jsonld": "https://wpnews.pro/news/musclememory-open-source-procedural-memory-for-ai-agents.jsonld"}}