Metadata-Version: 2.1
Name: cmem-cli
Version: 0.1.0
Summary: DAG-based persistent component memory for Claude AI sessions
Project-URL: Homepage, https://github.com/DhaivatV/cmem
Project-URL: Repository, https://github.com/DhaivatV/cmem
Project-URL: Issues, https://github.com/DhaivatV/cmem/issues
Keywords: claude,ai,memory,dag,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
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: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: tomlkit>=0.13
Requires-Dist: networkx>=3.3
Requires-Dist: rich>=13.7

# cmem

DAG-based persistent component memory for Claude AI sessions.

Instead of a flat notes file that gets overwritten, `cmem` gives each component in your project an **immutable DAG** — a chain of snapshots with annotated transitions between them. Claude can traverse this graph to answer *"why does this work this way?"* by reading the history of changes.

## Install

```bash
pip install cmem-cli
```

## How it works

Each component gets its own directory under `~/.claude/memory/<project>/<component>/`:

```
~/.claude/memory/
  my_project/
    auth_service/
      graph.toml          ← DAG index: nodes, edges, HEAD
      snapshots/
        N1.toml           ← immutable state snapshot
        N2.toml
      transitions/
        N1-N2.toml        ← what changed and why
```

Snapshots are **immutable** — once written, they can't be overwritten. Transitions record the trigger (bug fix, feature, refactor, discovery) and a diff summary. The DAG enforces no cycles.

## Quick start

```bash
# Initialize a component
cmem init my_project auth_service

# Create first snapshot (opens $EDITOR)
cmem snapshot my_project auth_service

# After a change, snapshot again and record the transition
cmem snapshot my_project auth_service
cmem transition my_project auth_service N1 N2

# View history
cmem log my_project auth_service

# ASCII DAG
cmem graph my_project auth_service
```

## Non-interactive use (for Claude)

Claude uses `--file` and `--trigger`/`--notes` to checkpoint without an editor:

```bash
# Write a temp snapshot file
cat > /tmp/snap.toml << 'EOF'
[state]
description = "Auth now uses JWT instead of session tokens"
key_files = ["auth/views.py", "auth/middleware.py"]
behavior = "Stateless JWT. Tokens expire in 24h. Refresh via /auth/refresh/."
open_questions = []
EOF

OLD=$(cmem head my_project auth_service | head -1)
cmem snapshot my_project auth_service --file /tmp/snap.toml
NEW=$(cmem head my_project auth_service | head -1)
cmem transition my_project auth_service $OLD $NEW \
  --trigger refactor \
  --notes "Switched to JWT to support stateless horizontal scaling"
```

## Write CLAUDE.md into a project

```bash
cmem install-claude my_project /path/to/project/root
```

This writes a `CLAUDE.md` file instructing Claude to autonomously checkpoint components after every meaningful change — no user prompting required.

## Commands

| Command | Description |
|---|---|
| `cmem init <project> <component>` | Create new component graph |
| `cmem snapshot <project> <component> [--file]` | Append new snapshot node |
| `cmem transition <project> <component> <from> <to> [--trigger] [--notes] [--file]` | Record a transition edge |
| `cmem log <project> <component>` | Print DAG history with transition notes |
| `cmem show <project> <component> <node>` | Show a specific snapshot |
| `cmem head <project> <component>` | Print current HEAD node |
| `cmem list` | List all projects and components |
| `cmem graph <project> <component>` | ASCII DAG visualization |
| `cmem install-claude <project> <path>` | Write CLAUDE.md into project root |

## Configuration

| Env var | Default | Description |
|---|---|---|
| `CMEM_ROOT` | `~/.claude/memory` | Root directory for all memory files |

## Transition triggers

`bug_fix` · `feature` · `refactor` · `discovery` · `breaking_change`

## License

MIT
