Metadata-Version: 2.4
Name: muscle-memory
Version: 0.2.0
Summary: Procedural memory for coding agents. Your past sessions, compiled.
Project-URL: Homepage, https://github.com/iamazhar/muscle-memory
Project-URL: Repository, https://github.com/iamazhar/muscle-memory
Project-URL: Issues, https://github.com/iamazhar/muscle-memory/issues
Author-email: Azhar Anwar <azharcodes@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agent,anthropic,claude-code,llm,memory,procedural-memory,procmem,skills
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.40
Requires-Dist: fastembed>=0.4
Requires-Dist: platformdirs>=4.2
Requires-Dist: pydantic>=2.6
Requires-Dist: rich>=13.7
Requires-Dist: sqlite-vec>=0.1.6
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.40; extra == 'openai'
Provides-Extra: voyage
Requires-Dist: voyageai>=0.2; extra == 'voyage'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/assets/hero.png" alt="Pixel art of a vintage CRT monitor with a tiny brain character flexing a bicep on its amber phosphor screen" width="720">
</p>

<h1 align="center">muscle-memory</h1>

<p align="center">
  <em>Procedural memory for coding agents. Your past sessions, compiled.</em>
</p>


`muscle-memory` gives Claude Code a memory that actually compounds. Instead of dumping prose into `CLAUDE.md` files that bloat every context, it watches your sessions, extracts reusable **Skills** — executable playbooks with activation conditions, steps, and termination criteria — and retrieves the right ones on demand when you start a new task.

Inspired by [ProcMEM (arxiv:2602.01869)](https://arxiv.org/abs/2602.01869), but purpose-built for coding agents.

## The problem

```
Session 1:  Figure out the monorepo's weird test runner (15 min)
Session 2:  Figure it out again (15 min)
Session 3:  Add a note to CLAUDE.md (2 min, bloats future context)
Session 50: CLAUDE.md is 4000 lines, half stale, nobody reads it
```

## What muscle-memory does instead

```
Session 1:  Figure out the test runner (15 min) → extractor creates a Skill
Session 2:  "run the tests" → Skill activates automatically, zero rediscovery
Session 5:  Skill gets refined from more examples
Session 20: Skill has been invoked 18x, 17 successes → promoted to "proven"
Session 50: Unused skills auto-pruned, active ones keep improving
```

Skills are **on-demand** (not always in context), **execution-scored** (good ones survive, bad ones die), and **user-editable** (plain text, no opaque embeddings).

## Quickstart

```bash
# install (Anthropic default)
uv tool install muscle-memory

# or with OpenAI support baked in
uv tool install 'muscle-memory[openai]'

# in your project
cd ~/code/my-project
mm init                    # creates .claude/mm.db, registers Claude Code hooks

# optional: bootstrap from recent history
mm bootstrap --days 30

# now just use Claude Code normally.
# skills accumulate automatically.

# inspect what you've learned
mm list
mm show <skill-id>
mm stats
```

## Authentication

`muscle-memory` needs an LLM for skill extraction (runs after each session,
not on every prompt). **It cannot reuse your Claude Code subscription auth**
— that's a known limitation; Anthropic does not currently expose a
subscription-capable SDK for third-party tools.

Your options:

| Provider | Setup | Cost |
|---|---|---|
| **Anthropic** (default) | `export ANTHROPIC_API_KEY=sk-ant-...` — **needs API credits, not a Max/Pro subscription** | ~$0.001 / session with Haiku 4.5 |
| **OpenAI** | `export OPENAI_API_KEY=sk-...` and `export MM_LLM_PROVIDER=openai` | ~$0.0005 / session with gpt-4o-mini |
| **Local / Ollama** | *(planned, not yet implemented)* | free |

If you already use Claude Code via a Max/Pro subscription, you'll still
need a separate Anthropic API key with billing credits, or use OpenAI.
See [docs/authentication.md](docs/authentication.md) for details.

## How it works

```
┌──────────────────────────────────────────────────────┐
│                 Claude Code Session                   │
│                                                        │
│  user prompt ─┐                                       │
│               ▼                                        │
│       ┌───────────────┐     top skills                │
│       │  Retriever    │────────────►  inject context  │
│       │  (embedding)  │                                │
│       └───────────────┘                                │
│               │                                        │
│               ▼                                        │
│       [ LLM executes with Skill hints ]               │
│               │                                        │
│               ▼                                        │
│       ┌───────────────┐                                │
│       │   Extractor   │  proposes new Skills           │
│       │   (async)     │                                │
│       └───────┬───────┘                                │
│               │                                        │
│               ▼                                        │
│       ┌────────────────────┐                          │
│       │   Scorer           │  updates / prunes        │
│       └────────────────────┘                          │
│               │                                        │
│               ▼                                        │
│       ┌────────────────────┐                          │
│       │   SQLite + vec     │                          │
│       └────────────────────┘                          │
└──────────────────────────────────────────────────────┘
```

## Skill anatomy

Each Skill is three editable text fields:

```json
{
  "activation":  "When pytest fails with ModuleNotFoundError in this monorepo",
  "execution":   "1. Check if tools/test-runner.sh exists.\n2. If yes, use it instead of invoking pytest directly.\n3. Set PYTEST_ADDOPTS=--no-cov for speed.",
  "termination": "Tests pass, or runner is confirmed missing",
  "tool_hints":  ["Bash: tools/test-runner.sh"]
}
```

No DSL. No code templates. Plain English that the agent reads and executes with judgment.

## Status

**Alpha.** Core extraction + retrieval + scoring are working. The Non-Parametric PPO refinement loop from the paper is planned for v2.

## License

MIT — see [LICENSE](LICENSE).
