# udit-rawat/muscle-memory- architecture

> Architecture diagram of the GitHub repository udit-rawat/muscle-memory-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/udit-rawat/muscle-memory-
- Repository: https://github.com/udit-rawat/muscle-memory-

## Overview

Muscle Memory learns a UI workflow with an LLM, compiles the observed actions into a typed capability, then replays that capability deterministically without a model. The main path is discovery → compilation and approval → replay, with policy enforcement, evidence recording, and operator intervention supporting both runtime stages. The tree also includes a mock core-banking UI and two example capabilities. The README is only a short product description, and several implementation areas were not sampled, so edges are limited to documented behavior and visible source ownership.

Main entry points: [`src/mm/cli.py`](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/cli.py) (CLI commands), [`src/mm/agent/loop.py`](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/agent/loop.py) (Discovery loop), [`src/mm/replay/executor.py`](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/replay/executor.py) (Deterministic replay), [`src/mm/policy/guard.py`](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/policy/guard.py) (Guarded surface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["Capability lifecycle"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_discovery["Discovery loop<br/>[loop.py]"]
  node_decision["Agent decisions<br/>[decision.py]"]
  node_compiler["Capability compiler<br/>[compiler.py]"]
  node_capability_schema["Capability schema<br/>[schema.py]"]
  node_capability_store["Artifact store<br/>[store.py]"]
  node_approval["Artifact approval<br/>[approval.py]"]
end

subgraph group_runtime["UI runtime"]
  node_replay["Deterministic replay<br/>[executor.py]"]
  node_surface["Web surface<br/>[web.py]"]
  node_llm_router["LLM provider router<br/>[router.py]"]
end

subgraph group_safety["Safety and oversight"]
  node_policy_guard["Guarded surface<br/>[guard.py]"]
  node_policy_model["Safety policy<br/>[model.py]"]
  node_handoff_controller["Handoff controller<br/>[intervention.py]"]
  node_lease["Control lease<br/>[lease.py]"]
  node_console["Operator console<br/>[console.py]"]
  node_recorder[("Run evidence<br/>[recorder.py]")]
end

subgraph group_example["Banking example"]
  node_cap_examples["Banking capabilities"]
  node_bank_pack["Corebank pack<br/>[corebank.yaml]"]
  node_bank_app["Mock bank UI<br/>[app.py]"]
  node_bank_data[("Synthetic bank data<br/>[data.py]")]
  node_bank_templates["Bank page templates"]
end

node_operator_user(("CLI user"))
node_browser["Browser"]
node_llm_provider["LLM provider"]

node_operator_user -->|"invokes"| node_cli
node_cli -->|"starts discovery"| node_discovery
node_discovery -->|"requests decisions"| node_decision
node_discovery -->|"requests structured output"| node_llm_router
node_llm_router -->|"calls provider"| node_llm_provider
node_discovery -->|"observes and acts through"| node_policy_guard
node_discovery -->|"records evidence"| node_recorder
node_cli -->|"compiles successful run"| node_compiler
node_compiler -->|"builds"| node_capability_schema
node_cli -->|"loads and saves"| node_capability_store
node_cli -->|"approves capability"| node_approval
node_cli -->|"starts replay"| node_replay
node_replay -->|"executes"| node_capability_schema
node_replay -->|"performs guarded actions"| node_policy_guard
node_replay -->|"records run"| node_recorder
node_policy_guard -->|"enforces"| node_policy_model
node_policy_guard -->|"checks control"| node_lease
node_policy_guard -->|"forwards allowed actions"| node_surface
node_surface -->|"drives"| node_browser
node_discovery -->|"requests intervention"| node_handoff_controller
node_replay -->|"requests intervention"| node_handoff_controller
node_handoff_controller -->|"coordinates ownership"| node_lease
node_console -->|"dispatches operator actions"| node_handoff_controller
node_cli -->|"uses capability files"| node_cap_examples
node_cli -->|"loads pack"| node_bank_pack
node_surface -.->|"interacts with"| node_bank_app
node_bank_app -->|"reads and updates"| node_bank_data
node_bank_app -->|"renders"| node_bank_templates

click node_cli "https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/cli.py"
click node_discovery "https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/agent/loop.py"
click node_decision "https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/agent/decision.py"
click node_compiler "https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/artifact/compiler.py"
click node_capability_schema "https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/artifact/schema.py"
click node_capability_store "https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/artifact/store.py"
click node_approval "https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/artifact/approval.py"
click node_cap_examples "https://github.com/udit-rawat/muscle-memory-/tree/main/capabilities"
click node_bank_pack "https://github.com/udit-rawat/muscle-memory-/blob/main/packs/corebank.yaml"
click node_replay "https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/replay/executor.py"
click node_surface "https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/surface/web.py"
click node_llm_router "https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/llm/router.py"
click node_policy_guard "https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/policy/guard.py"
click node_policy_model "https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/policy/model.py"
click node_handoff_controller "https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/handoff/intervention.py"
click node_lease "https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/handoff/lease.py"
click node_console "https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/handoff/console.py"
click node_recorder "https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/evidence/recorder.py"
click node_bank_app "https://github.com/udit-rawat/muscle-memory-/blob/main/mock_bank/app.py"
click node_bank_data "https://github.com/udit-rawat/muscle-memory-/blob/main/mock_bank/data.py"
click node_bank_templates "https://github.com/udit-rawat/muscle-memory-/tree/main/mock_bank/templates"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_discovery,node_decision,node_compiler,node_capability_schema,node_capability_store,node_approval,node_operator_user,node_browser toneBlue
class node_replay,node_surface,node_llm_router toneAmber
class node_policy_guard,node_policy_model,node_handoff_controller,node_lease,node_console,node_recorder toneMint
class node_cap_examples,node_bank_pack,node_bank_app,node_bank_data,node_bank_templates toneRose
class node_llm_provider toneIndigo
```

## Components

### Capability lifecycle

- [CLI commands](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/cli.py): `src/mm/cli.py`
- [Discovery loop](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/agent/loop.py): `src/mm/agent/loop.py`
- [Agent decisions](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/agent/decision.py): `src/mm/agent/decision.py`
- [Capability compiler](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/artifact/compiler.py): `src/mm/artifact/compiler.py`
- [Capability schema](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/artifact/schema.py): `src/mm/artifact/schema.py`
- [Artifact store](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/artifact/store.py): `src/mm/artifact/store.py`
- [Artifact approval](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/artifact/approval.py): `src/mm/artifact/approval.py`

### UI runtime

- [Deterministic replay](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/replay/executor.py): `src/mm/replay/executor.py`
- [Web surface](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/surface/web.py): `src/mm/surface/web.py`
- [LLM provider router](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/llm/router.py): `src/mm/llm/router.py`

### Safety and oversight

- [Guarded surface](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/policy/guard.py): `src/mm/policy/guard.py`
- [Safety policy](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/policy/model.py): `src/mm/policy/model.py`
- [Handoff controller](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/handoff/intervention.py): `src/mm/handoff/intervention.py`
- [Control lease](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/handoff/lease.py): `src/mm/handoff/lease.py`
- [Operator console](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/handoff/console.py): `src/mm/handoff/console.py`
- [Run evidence](https://github.com/udit-rawat/muscle-memory-/blob/main/src/mm/evidence/recorder.py): `src/mm/evidence/recorder.py`

### Banking example

- [Banking capabilities](https://github.com/udit-rawat/muscle-memory-/tree/main/capabilities): `capabilities`
- [Corebank pack](https://github.com/udit-rawat/muscle-memory-/blob/main/packs/corebank.yaml): `packs/corebank.yaml`
- [Mock bank UI](https://github.com/udit-rawat/muscle-memory-/blob/main/mock_bank/app.py): `mock_bank/app.py`
- [Synthetic bank data](https://github.com/udit-rawat/muscle-memory-/blob/main/mock_bank/data.py): `mock_bank/data.py`
- [Bank page templates](https://github.com/udit-rawat/muscle-memory-/tree/main/mock_bank/templates): `mock_bank/templates`

### Other components

- **CLI user**
- **Browser**
- **LLM provider**

## Connections

- CLI user → CLI commands: invokes
- CLI commands → Discovery loop: starts discovery
- Discovery loop → Agent decisions: requests decisions
- Discovery loop → LLM provider router: requests structured output
- LLM provider router → LLM provider: calls provider
- Discovery loop → Guarded surface: observes and acts through
- Discovery loop → Run evidence: records evidence
- CLI commands → Capability compiler: compiles successful run
- Capability compiler → Capability schema: builds
- CLI commands → Artifact store: loads and saves
- CLI commands → Artifact approval: approves capability
- CLI commands → Deterministic replay: starts replay
- Deterministic replay → Capability schema: executes
- Deterministic replay → Guarded surface: performs guarded actions
- Deterministic replay → Run evidence: records run
- Guarded surface → Safety policy: enforces
- Guarded surface → Control lease: checks control
- Guarded surface → Web surface: forwards allowed actions
- Web surface → Browser: drives
- Discovery loop → Handoff controller: requests intervention
- Deterministic replay → Handoff controller: requests intervention
- Handoff controller → Control lease: coordinates ownership
- Operator console → Handoff controller: dispatches operator actions
- CLI commands → Banking capabilities: uses capability files
- CLI commands → Corebank pack: loads pack
- Web surface → Mock bank UI: interacts with
- Mock bank UI → Synthetic bank data: reads and updates
- Mock bank UI → Bank page templates: renders