Metadata-Version: 2.1
Name: cmem-cli
Version: 0.1.1
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.

---

## The problem: how Claude currently remembers things

Claude Code has a built-in memory system based on a file called `MEMORY.md`, stored per-project at:

```
~/.claude/projects/<project-path>/memory/MEMORY.md
```

Claude reads this file at the start of every session and writes to it whenever it learns something worth keeping — key patterns, architectural decisions, recurring gotchas, workflow preferences. It works like a running notepad.

**The limitations:**

| Limitation | What it means |
|---|---|
| **Flat file, ~200 line cap** | Everything lives in one file. Old entries get compressed or dropped as it fills up. |
| **Overwrite model** | When something changes, the old entry is replaced. There's no record of what it used to be. |
| **No structure** | All components of a project share one file. A large codebase with 20+ components quickly becomes noise. |
| **No history** | Claude can tell you what a component does now, but not why it works this way or what changed. |
| **No causality** | "We switched from Redis pub/sub to SQS for ranking" — gone after the next overwrite. |

In practice, for any non-trivial project, Claude's memory degrades over time. It knows the current state but loses the archaeological record of how things evolved.

---

## What cmem adds

`cmem` gives each component in your project its own **immutable DAG** — a chain of snapshots connected by annotated transitions.

```
~/.claude/memory/
  my_project/
    auth_service/
      graph.toml          ← DAG index: nodes, edges, HEAD pointer
      snapshots/
        N1.toml           ← immutable: state of the component at a point in time
        N2.toml
        N3.toml
      transitions/
        N1-N2.toml        ← what changed, why, and what was affected
        N2-N3.toml
    job_router/
      graph.toml
      snapshots/
      transitions/
```

**How it's different:**

| Capability | MEMORY.md | cmem |
|---|---|---|
| Remembers current state | ✅ | ✅ |
| Per-component structure | ❌ | ✅ |
| Immutable history | ❌ | ✅ |
| "Why does this work this way?" | ❌ | ✅ — traverse transitions |
| Handles 20+ components | ❌ (hits 200-line cap) | ✅ — each component is independent |
| Causality chain | ❌ | ✅ — trigger + notes on every edge |
| DAG (branching/merging) | ❌ | ✅ — full directed acyclic graph |

**The two systems work together, not against each other.** `MEMORY.md` holds cross-cutting project facts (stack, URL patterns, workflow preferences). `cmem` holds the deep, per-component history. `MEMORY.md` points Claude to `cmem` for component-level context.

---

## How Claude uses cmem autonomously

When you add a `CLAUDE.md` to your project (via `cmem install-claude`), Claude checkpoints components automatically — no user prompting needed.

**At session start**, when touching a known component:
```bash
cmem head my_project auth_service    # load current state
cmem show my_project auth_service N3
```

**After any meaningful change** (bug fix, feature, refactor, discovery), Claude runs:
```bash
OLD=$(cmem head my_project auth_service | head -1)
# ... does the work ...
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 bug_fix \
  --notes "Fixed ranking to use SQS queue instead of Redis pub/sub"
```

**When asked "why does X work this way?"**, Claude runs:
```bash
cmem log my_project auth_service
```
and traces back through transitions to find the answer.

---

## Install

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

---

## Quick start

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

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

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

# 4. View history
cmem log my_project auth_service

# 5. ASCII DAG
cmem graph my_project auth_service

# 6. Wire up Claude to do all of this automatically
cmem install-claude my_project /path/to/project/root
```

---

## Non-interactive use (for Claude)

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

```bash
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. Works with any project, any language.

---

## 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
