🔶 MuscleMemory：面向 AI Agent 的开源程序性记忆系统

面向 AI Agent 的开源程序性记忆系统。
它会从有效的方法和失败的尝试中学习。
默认本地运行 · Apache-2.0 · 由 TheWariend 开发

编码 Agent 每次会话都会重新学习相同的事情：该打开哪些文件、如何运行测试、上次哪里出了问题。MuscleMemory 会观察你的 Agent 工作。当一项任务真正成功时（最后一次改动后测试通过），它会学习该任务是如何完成的。下次出现类似任务时，它会向 Agent 提供一段简短说明：需要修改的文件、证明任务成功的测试，以及应当避免的事项。

在使用真实 Codex 会话的基准测试中，它将输入 Token 减少了 25.5%、工具调用减少了 30.4%、耗时减少了 28.2%，同时所有任务仍然通过。在一次使用 Claude Code 和 Sonnet 5.5 的早期测试中，采用 Codex 学到的技能后，它将输入 Token 减少了 43.5%、工具调用减少了 30%。在来自 SWE-bench 的真实 Django Issue 上，使用从同一领域其他 Issue 中学习到的技能，Codex 解决的问题数量与无记忆时相同，但 Token 用量约为后者的一半（小规模测试；详情）。你可自行检查：python benchmarks/reproduce.py check。Codex 方法与数据 · Claude Code 测试运行 · 白皮书。

pipx install thewariend-musclememory  # or, from a clone: pip install -e .

musclememory init                      # sets up ~/.musclememory and the small search model
musclememory start                     # runs in the background on http://127.0.0.1:8080
cd your-project && musclememory connect codex   # or claude, cursor, cleanslate
musclememory dashboard                 # opens the dashboard, already signed in

随后照常使用你的 Agent 即可。无需复制任何密钥或配置文件。

你也可以让 Agent 自行完成设置：将以下内容粘贴到 Claude Code、Codex 或 Cursor 中。

Read https://thewariend.com/musclememory/llms.txt and set up MuscleMemory for this project.

更多内容请见安装说明。

flowchart LR
    A["Your agent works on a task"] --> B{"Tests pass after the last change?"}
    B -- no --> C["Nothing is learned"]
    B -- yes --> D["Learn a skill or count a check"]
    D --> E["Two separate passing checks"]
    E --> F["You tap Keep"]
    F --> H["Hook checks current files"]
    H -->|"match or partial match"| G["Short note; warning on partial match"]
    H -->|"mismatch"| I["No note; skip recorded locally"]
    G --> A

加载中

• 经过两次验证。 后续两个独立会话必须与该技能的操作相匹配，并且在最后一次代码改动后通过其自身保存的测试命令。管道、重定向和 Shell 包装命令会被标准化；参数化命令会保持形状匹配。自动检查使用最终通过的测试，因此无关测试无法计入。训练会话不计入其中。只有实际测试运行才会被计入（pytest、python -m unittest、go test、cargo test、npm test、make test 及类似命令）；仅提及测试的命令，例如 cargo build 或 ruff check，则不计入。
• 一次失败即可撤下。 如果 Agent 获得了某项技能、修改了代码，而该技能自身的测试在最后一次测试运行中失败，Hook 会报告一次失败检查，该技能将不再被提供给 Agent。仅仅中断的会话，或其他测试失败的会话，不会被计作该技能的负面记录。
• 从失败中学习。 失败尝试会转化为普通的“注意事项”和“如果出错”提示，使 Agent 避免再次走入相同死胡同。
• 你始终掌控决策。 每项技能在任何 Agent 可见前都需要你批准，无论它是通过 Hook、SDK、MCP 还是 API 学得；每个新版本也是如此。只有仪表盘可以进行批准；Agent 自身的密钥无法批准。你删除或退役的技能会保持移除状态：同一技能不会再次被学习。Agent 仍会像往常一样读取当前文件并请求批准。MuscleMemory 永远不会重放操作。
• 检查当前文件。 原生 Hook 要求某项技能发现的文件仍然存在（它创建的文件可以尚不存在），并且至少有一项保存的编辑前或编辑后内容相匹配。如果没有任何匹配项，它们会保持静默；部分匹配会包含不可被删减的警告。读取范围受限，并会拒绝符号链接。文件检查跳过记录在本地。服务器端和 MCP 回忆功能没有文件访问权限。精确规则。
• 该安静时保持安静。 如果没有适合的内容，就不会添加任何信息，Agent 也不会额外消耗 Token。
• 在 Agent 之间共享。 用 Codex 学得的技能也会提供给 Claude Code 或 Cursor：无论哪个工具修改文件，都会以同样的方式计数。经过验证的技能还可以作为 SKILL.md 导出到 Codex 或 Claude Code。
• 本地且开放。 默认使用 SQLite 和设备端小型模型：无需账户，也不会进行外部调用。团队可使用带 pgvector 的 PostgreSQL。

更多细节请参见工作原理。

参见集成说明。

项目会在同一工作区（namespace，默认值为 "default"）内共享技能，而不是为每个代码仓库分别创建工作区。跨仓库回忆尚未经过测试。为项目指定独立 namespace。

|
---|---
|
**主页：**你的 Agent 可复用的内容，以及所有等待你批准的内容 | **技能：**每项技能都附带其来源任务、变更的文件和用于验证的测试
|
**一项技能：**以自然语言说明的步骤、其验证依据及注意事项 | **连接：**每个 Agent 一条命令

MuscleMemory 拥有 Python 和 TypeScript 测试，并提供可选的 PostgreSQL 与实时 Codex 检查。它仍处于早期阶段。其基准测试覆盖的是三个受控代码库中的重复任务，并非所有类型的工作，而且 Claude Code 测试规模较小。Hook 和 CleanSlate 会自行学习；使用 SDK 时，由你的代码报告任务何时成功。参见路线图。

欢迎提交 Issue 和 Pull Request。请按照 SECURITY.md 中的说明私下报告安全问题。

Apache-2.0。由 TheWariend 制作。

Open-source procedural memory for AI agents.
It learns from what worked and what failed.
Local by default · Apache-2.0 · by TheWariend

Coding 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.

In a benchmark with real Codex sessions, it cut input tokens by 25.5%, tool calls by 30.4% and time by 28.2% , with every task still passing. In an early run with Claude Code and Sonnet 5.5, using skills that Codex had learned, it cut input tokens by 43.5% and tool calls by 30%. On real Django issues from SWE-bench, with a skill learned from other issues in the same area, Codex solved as many as without memory with about half the tokens (a small run; details). Check them yourself: python benchmarks/reproduce.py check. Codex method and data · Claude Code run · Whitepaper.

pipx install thewariend-musclememory  # or, from a clone: pip install -e .

musclememory init                      # sets up ~/.musclememory and the small search model
musclememory start                     # runs in the background on http://127.0.0.1:8080
cd your-project && musclememory connect codex   # or claude, cursor, cleanslate
musclememory dashboard                 # opens the dashboard, already signed in

Then use your agent as usual. There are no keys or config files to copy.

Or let your agent set it up: paste this into Claude Code, Codex or Cursor.

Read https://thewariend.com/musclememory/llms.txt and set up MuscleMemory for this project.

More in Install.

flowchart LR
    A["Your agent works on a task"] --> B{"Tests pass after the last change?"}
    B -- no --> C["Nothing is learned"]
    B -- yes --> D["Learn a skill or count a check"]
    D --> E["Two separate passing checks"]
    E --> F["You tap Keep"]
    F --> H["Hook checks current files"]
    H -->|"match or partial match"| G["Short note; warning on partial match"]
    H -->|"mismatch"| I["No note; skip recorded locally"]
    G --> A

Loading

• Verified, twice. Two later sessions must match the skill's actions and pass its own stored test command after the last code change. Pipes, redirects and shell wrappers are normalized; parameterized commands keep shape matching. Automatic checks use the final passing test, so an unrelated test cannot count. The training session 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 mention tests, like cargo build or ruff check, don't.
• One failure pulls it. If an agent was given a skill, changed code, and the skill's own test then failed as the last test run, the hooks report a failed check and the skill stops reaching agents. A session that just stops, or where a different test failed, doesn't count against it.
• Learns from failures. Failed attempts become plain "watch out" and "if it goes wrong" notes, so the agent avoids the same dead ends.
• You stay in charge. Every skill waits for your OK before any agent sees it, however it was learned (hooks, SDK, MCP or the API), and so does every new version. Only the dashboard can approve; an agent's own key can't. Skills you delete or retire stay removed: the same skill isn't learned again. Agents still read the current files and ask for approval as usual. MuscleMemory never replays actions.
• Checks current files. Native hooks require the files a skill found in place to still exist (files it created may not exist yet) and at least one stored before or after edit to match. If none match, they stay quiet; partial matches include a warning that cannot be trimmed. Reads are bounded and reject symlinks. File-check skips are recorded locally. Server and MCP recall have no file access. Exact rules.
• Quiet when it should be. If nothing fits, nothing is added, and the agent pays no extra tokens.
• Shared between agents. A skill learned with Codex is handed to Claude Code or Cursor too: changing a file counts the same whichever tool did it. Proven skills can also be exported to Codex or Claude Code as SKILL.md.
• Local and open. SQLite and a small on-device model by default: no account and no outside calls. Use PostgreSQL with pgvector for teams.

More detail in How it works.

See Integrations.

Projects share skills within the same workspace (namespace, default "default"), rather than getting a separate workspace per repository. Cross-repository recall is untested. Give a project its own namespace.

|
---|---
|
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
|
A skill: its steps in plain words, its proof, and what to watch out for | Connect: one command per agent

MuscleMemory has Python and TypeScript tests, with optional PostgreSQL and live Codex checks. It's early. The benchmarks cover repeat tasks on three controlled codebases, not every kind of work, and the Claude Code run is small. The hooks and CleanSlate learn on their own; with the SDKs your code reports when a task succeeded. See the roadmap.

Issues and pull requests are welcome. Please report security issues privately, as described in SECURITY.md.

Apache-2.0. Made by TheWariend.