muscle-memory 0.2.0__tar.gz

muscle_memory-0.2.0/.gitignore

@@ -0,0 +1,80 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+.hypothesis/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyright/
+.pytype/
+
+# Linting
+.ruff_cache/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# muscle-memory runtime artifacts
+.claude/mm.db
+.claude/mm.db-*
+.claude/mm.activations/
+.claude/mm.extract_queue.txt
+.claude/settings.json
+*.mm.db
+*.mm.db-*
+
+# Local env
+.env
+.env.*
+!.env.example
+
+# Logs
+*.log
+
+# Claude Code session state (don't commit personal sessions)
+.claude/projects/

muscle_memory-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Azhar Anwar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

muscle_memory-0.2.0/PKG-INFO

@@ -0,0 +1,174 @@
+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).

muscle_memory-0.2.0/README.md

@@ -0,0 +1,136 @@
+<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).

muscle_memory-0.2.0/pyproject.toml

@@ -0,0 +1,116 @@
+[project]
+name = "muscle-memory"
+version = "0.2.0"
+description = "Procedural memory for coding agents. Your past sessions, compiled."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+    { name = "Azhar Anwar", email = "azharcodes@gmail.com" },
+]
+keywords = [
+    "llm",
+    "claude-code",
+    "agent",
+    "memory",
+    "procedural-memory",
+    "procmem",
+    "skills",
+    "anthropic",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.7",
+    "pydantic>=2.6",
+    "sqlite-vec>=0.1.6",
+    "anthropic>=0.40",
+    "fastembed>=0.4",
+    "platformdirs>=4.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+    "mypy>=1.10",
+]
+openai = ["openai>=1.40"]
+voyage = ["voyageai>=0.2"]
+
+[project.scripts]
+mm = "muscle_memory.cli:app"
+muscle-memory = "muscle_memory.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/iamazhar/muscle-memory"
+Repository = "https://github.com/iamazhar/muscle-memory"
+Issues = "https://github.com/iamazhar/muscle-memory/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/muscle_memory"]
+include = [
+    "src/muscle_memory/**/*.py",
+    "src/muscle_memory/**/*.md",
+    "src/muscle_memory/prompts/*.md",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/muscle_memory",
+    "tests",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "UP",  # pyupgrade
+    "N",   # pep8-naming
+    "SIM", # flake8-simplify
+]
+ignore = [
+    "E501",  # line too long (let formatter handle)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["B011"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+no_implicit_optional = true

muscle_memory-0.2.0/src/muscle_memory/__init__.py

@@ -0,0 +1,24 @@
+"""muscle-memory: procedural memory for coding agents."""
+
+from muscle_memory.models import (
+    Episode,
+    Maturity,
+    Outcome,
+    Scope,
+    Skill,
+    ToolCall,
+    Trajectory,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Episode",
+    "Maturity",
+    "Outcome",
+    "Scope",
+    "Skill",
+    "ToolCall",
+    "Trajectory",
+    "__version__",
+]

muscle_memory-0.2.0/src/muscle_memory/__main__.py

@@ -0,0 +1,6 @@
+"""Enables `python -m muscle_memory ...` to dispatch to the CLI."""
+
+from muscle_memory.cli import app
+
+if __name__ == "__main__":
+    app()