cmem-cli 0.1.0

DAG-based persistent component memory for Claude AI sessions

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

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

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

# 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

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