Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Muscle Memory MCP Server find a saved script to convert CSV to JSON and run it on data.csv"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Your agent solves problems by writing scripts, then throws them away like they're nothing. Tomorrow it writes the same script again. Like having to figure out how to tie your shoelaces every morning. It lacks muscle memory.
The Muscle Memory MCP server gives your agent an empty library that it fills with its own tested scripts.
Hermes
hermes mcp add muscle-memory --command uvx --args muscle-memory-mcpClaude Code
claude mcp add muscle-memory -s user -- uvx muscle-memory-mcpTo keep the library somewhere other than the default, set MUSCLE_MEMORY_DIR in the server's environment.
Add to ~/.codex/config.toml:
[mcp_servers.muscle-memory]
command = "uvx"
args = ["muscle-memory-mcp"]
# env = { MUSCLE_MEMORY_DIR = "/absolute/path/to/library" }Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"muscle-memory": {
"command": "uvx",
"args": ["muscle-memory-mcp"]
}
}
}Related MCP server: engram
Add this standing rule to your AGENTS.md, CLAUDE.md, SOUL.md or equivalent agent instructions:
Before writing helper code, check muscle-memory with mm_list and run a match with mm_run.
After giving the user the result, save reusable new helpers with mm_save.
Skip this for code that is itself the deliverable.Tool descriptions contain the safety and testing specifics for each operation.
The server exposes mm_list, mm_run, mm_save and mm_setup. If the personal library has not been set up, the tools guide the agent to ask you once where it should live and then call mm_setup.
The personal library defaults to ~/.muscle-memory (%USERPROFILE%\.muscle-memory on Windows); MUSCLE_MEMORY_DIR selects another location. Scripts in the personal library are available across projects.
An optional .muscle-memory/ project library holds scripts specific to one codebase. Project-root detection depends on the MCP client's working directory. Set MUSCLE_MEMORY_PROJECT_DIR to the project's absolute path in the server environment to override detection explicitly. When a script name exists in both libraries, the project copy takes precedence; listings mark the personal copy as shadowed.
For personal libraries, saves write files locally if the folder is not in git. If the library is a git repo, each saved script is committed. Setup asks whether to also push scripts to the git remote automatically; run setup again to change your answer. Project libraries are never committed or pushed automatically: you commit them with your own work. On first project setup, the agent asks whether the library should be shared through git or kept private.
mm_list(area?) — list available areas and script counts, or list scripts in one area.
mm_run(script, args) — run a saved script, passing through arguments.
mm_save(name, code, test, area, usage, ...) — save or update a script after its test passes. Supports runner, test selection, and personal/project scope options; see the tool description for the full schema and safety behavior.
mm_setup(target, ...) — set up a personal library or optional project library. Ask the user before setup; see the tool description for modes and options.
The runner is picked by file extension: Python, bash/zsh, Node, Ruby, Perl, PHP, Swift, Go, Lua, R, PowerShell, and .cmd/.bat on Windows. Other languages need an explicit runner argv when saved. Runtimes are never installed for you; a missing one gives an error naming the command.
By default a script's test uses the same extension and runner. test_name and test_runner allow independent test selection. Tests live under tests/test_<stem>.<ext>; selection metadata is stored beside the script. Tests receive MM_SCRIPT (absolute script path) and MM_LIBRARY (library root). Exit status 0 passes; failed tests prevent saving. Replacing a test extension removes the prior test only after the replacement passes.
The same command is also a CLI:
uvx muscle-memory-mcp list [AREA]
uvx muscle-memory-mcp run SCRIPT [ARGS...]
uvx muscle-memory-mcp save NAME --code FILE --test FILE --area AREA --usage TEXT
uvx muscle-memory-mcp setup [--target personal|project] [OPTIONS]
uvx muscle-memory-mcp test [NAME]
uvx muscle-memory-mcp trust --projectWith no arguments it starts the MCP server over stdio. --help lists the options.
Scripts and tests run as you, with your environment and no sandbox. Passing tests is not a security review.
A project library runs only after you approve the project once with uvx muscle-memory-mcp trust --project.
Project-library detection depends on the client's working directory; set MUSCLE_MEMORY_PROJECT_DIR if needed.
MIT — see LICENSE.
List tested scripts; call before code at each reusable substep. Omit area to list areas, then select one. Same-name project scripts shadow personal. No matching script: write code. If unavailable, ask once before mm_setup.
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | Area from first call; omit to list areas. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does disclose important behavior such as project scripts shadowing personal scripts and the no-match fallback, but it does not describe return format, permissions, or error behavior beyond the unavailable case.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very compact and front-loads the core action. Every clause appears to serve a purpose, including the fallback and setup instructions, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter list tool with no output schema or annotations, the description covers the main invocation workflow, shadowing behavior, and fallback cases. It is slightly incomplete about what the listing returns, but it is sufficient for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the single area parameter is already documented. The description adds workflow meaning by saying to omit area to list areas and then select one, but it does not add syntax or formatting details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: "List tested scripts." It distinguishes the tool's role as a pre-coding lookup and names the mm_setup fallback, but it does not explicitly distinguish mm_list from mm_run, mm_save, or mm_setup beyond the unavailable-case instruction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit invocation guidance: call before code at each reusable substep, omit area to list areas and then select one, write code if no script matches, and ask once before mm_setup if unavailable. This is a clear when/when-not/alternative workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run code as you with inherited environment; no sandbox. Report output. [write]: --dry-run then readback. [irreversible]: --dry-run, show output, wait for explicit yes before execution. Repair via mm_save replace: true.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| script | Yes | Script file name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well to disclose critical traits: code runs as the user, inherits the environment, and has no sandbox. It also describes dry-run and confirmation workflows for risky operations, though it omits return-value details, timeout behavior, and failure handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loads the core purpose and safety behavior. The telegraphic bracket notation and semicolon-heavy phrasing are compact but make the classification rules harder to parse than necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It covers the most important behavioral risk, which is unsandboxed execution, and provides escalation steps for dangerous actions. But with no annotations, no output schema, and only 50% parameter coverage, it is incomplete on arguments, return values, and failure behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has only 50% description coverage: 'script' is documented as a script file name, but 'args' is undocumented. The description does not mention either parameter or explain how flags such as --dry-run are passed, so it does not compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: run code with inherited environment and no sandbox. This clearly distinguishes the tool from mm_list, mm_setup, and mm_save by implication, though it does not explicitly name those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives procedural safety steps for '[write]' and '[irreversible]' operations, including dry-run and explicit confirmation, and routes repair to mm_save. However, it does not explain how an agent should classify an action as write versus irreversible, nor does it state clear when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save reusable code and EXECUTE its test, unsandboxed; tests are not security reviews. Untrusted project library: nothing written or run; ask the user. Use args, env secrets, --dry-run for actions. Tests default to script runner/extension; test_name/test_runner override. MM_SCRIPT/MM_LIBRARY set; exit 0 passes. Failed new personal test saves nothing; replacement restores prior files. Personal commits, and pushes if chosen at setup; project never commits. Existing names: replace: true.
| Name | Required | Description | Default |
|---|---|---|---|
| area | Yes | Existing mm_list area. | |
| code | Yes | Script source. | |
| name | Yes | snake_case file name with language extension. | |
| test | Yes | Test source. | |
| scope | No | Codebase-specific or personal. | personal |
| usage | Yes | Usage line: <name> <args> — purpose [pure|read|write|irreversible]. | |
| runner | No | Installed runner argv. | |
| replace | No | Replace; restore if test fails. | |
| new_area | No | Create a new area. | |
| test_name | No | test_<script-stem>.<ext> basename. | |
| test_runner | No | Test interpreter argv. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: unsandboxed execution, tests-are-not-security-reviews caveat, exit-0-passes semantics, MM_SCRIPT/MM_LIBRARY injection, transactional behavior (failed new personal test saves nothing; replacement restores prior files), and commit/push policy split by scope. Remaining gaps are what the tool returns and what permissions/auth are needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is front-loaded and dense with no filler sentences, but it is written as a chain of telegraphic fragments ('Personal commits, and pushes if chosen at setup; project never commits') that are hard to parse. Given 11 parameters and irreversible semantics, the length is defensible, but structure could group save behavior, execution behavior, and scope rules.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating, code-executing tool with no annotations and no output schema, the description covers the risky parts an agent must know: sandboxing, untrusted-library behavior, rollback on test failure, and commit/push scope rules. It is not fully complete — return values and the mm_run boundary are unaddressed — but an agent could call it correctly from this text.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so a 3 is the baseline; the description earns above that by explaining the relationship the schema cannot — tests default to the script runner/extension unless test_name/test_runner override, and replace must be set to true for an existing name. Some parameters (runner vs test_runner, new_area, scope) still get no clarification beyond their one-line schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening clause gives a specific verb+resource: save reusable code and execute its test, with the important qualifier that execution is unsandboxed. It stops short of distinguishing the tool from mm_run (which also executes code) or mm_list/mm_setup, so the agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is one real exclusion — in an untrusted project library, nothing is written or run, ask the user — and a conditional ('Existing names: replace: true'). But there is no explicit statement of when to call mm_save versus mm_run or mm_setup, and no prerequisites for the area/scope selection beyond the schema's own wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
After asking which: personal (mode local/existing/clone) or project (shared true uses project git, false keeps private). push: user's answer to 'Push scripts to git remote automatically?'
| Name | Required | Description | Default |
|---|---|---|---|
| git | No | ||
| mode | No | ||
| path | No | ||
| push | No | ||
| remote | No | ||
| shared | No | ||
| target | No | personal |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and falls short: it doesn't disclose what setup actually changes (files written, git repos initialized, config persisted) or whether it is reversible. Only fragmentary hints appear ('shared true uses project git, false keeps private'), which is parameter meaning rather than behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is short, but it is not front-loaded with purpose and reads as a fragmentary parenthetical rather than a coherent instruction. The clauses ('project (shared true uses project git, false keeps private)') are dense and hard to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Seven parameters, zero schema descriptions, no annotations, and no output schema is a high-complexity surface that this definition does not adequately cover. An agent would have to guess at path/remote semantics and at the tool's side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it partly does: it explains target (personal/project), mode (local/existing/clone), shared, and push. Three parameters (git, path, remote) get no explanation and the phrasing for the ones covered is ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description never states what the tool does — there is no verb+resource like 'configure memory/script storage'. It only paraphrases a couple of parameters ('personal (mode local/existing/clone) or project'), which restates the schema rather than naming the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'After asking which:' implies this runs after collecting user answers, which is a faint sequencing hint. But it never says when to call mm_setup versus mm_save/mm_run/mm_list, nor what prerequisites exist before invoking it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0mm_listmm_runmm_savemm_setupScored across 4 tools
Each tool has a clearly distinct role: mm_list discovers scripts, mm_run executes existing code, mm_save stores reusable code and runs its test, and mm_setup configures personal vs project storage. Although mm_run and mm_save both involve execution, the action boundaries are clearly described and unlikely to be confused.
All tool names follow the same predictable mm_verb pattern: mm_list, mm_run, mm_save, and mm_setup. There are no naming style deviations.
Four tools is well-scoped for a focused script-memory server. Each tool maps to a core operation: discover, execute, save, and configure.
The surface covers the main lifecycle of listing, running, saving/replacing, and configuring script storage. A delete/remove operation and possibly a direct get/inspect operation are missing, but most workflows remain workable through list, run, and save with replace.
Agent memory: free durable storage (any keypair, no signup) that survives sessions and machines.
Build, test and publish agentic workflows from your AI client: approve steps, read tables, see runs.
Shared long-term memory vault for AI agents with 20 MCP tools.
Shared memory for coding agents. Stop re-explaining your codebase every session.
