Persistent decision memory for AI coding assistants. When Claude's context compacts, your reasoning survives.

Claude Code loses context. Sessions end. Memory compacts. Six months later, nobody remembers why you chose approach A over approach B. The decisions that shaped your codebase evaporate.

Deciduous creates a persistent, queryable graph of every decision made during development. When a new Claude session starts—or when context compacts mid-session—Claude can query the graph to recover reasoning it never saw.

This isn't documentation written after the fact. It's a real-time record of how software gets built, captured as decisions happen.

cargo install deciduous

cd your-project
deciduous init

This creates:

• .deciduous/deciduous.db — SQLite database for the graph
• .claude/commands/ — Slash commands for Claude Code
• .windsurf/rules/ — Rules for Windsurf/Cascade
• docs/ — Static web viewer (deployable to GitHub Pages)
• CLAUDE.md — Project instructions with the logging workflow

Tell Claude to use the decision graph, or just start working—the CLAUDE.md instructions will guide it.

For context compaction:

• Claude logs decisions to a SQLite database as it works
• When context compacts, the graph survives
• New sessions run /context to query past decisions
• Claude picks up where it left off, with full reasoning intact

For long-term decision tracking:

• Every goal, decision, action, and outcome is timestamped and linked
• Confidence scores (0-100) show certainty at decision time
• Edge types capture relationships: chosen, rejected, requires, blocks
• The graph is queryable: "What did we decide about auth?" "Why did we reject Redux?"

For multi-user collaboration:

• Export decision patches to share with teammates
• Import patches from others (idempotent—safe to apply multiple times)
• Each node has a globally unique ID for conflict-free merging

For PR generation:

• Generate decision graph visualizations for PRs
• Auto-generate writeups from the graph
• Show reviewers why you made the choices you made

Claude runs /context to recover past decisions:

> /context

Current branch: feature/auth
Decision graph shows:
- Goal #12: "Add user authentication" (confidence: 90)
  └─> Decision #13: "Choose auth method" (confidence: 75)
        ├─> Option #14: "JWT tokens" (chosen)
        └─> Option #15: "Session cookies" (rejected: "stateless preferred")

Last action: #18 "Implementing JWT refresh flow"
Status: in_progress

Claude logs decisions in real-time:

# Starting a new feature - capture the user's prompt on the root goal
deciduous add goal "Add rate limiting" -c 90 -p "User asked: can we add rate limiting to the API?"

# Making a choice (downstream nodes don't need prompts - they flow via edges)
deciduous add decision "Choose rate limiter approach" -c 75
deciduous link 20 21 -r "Deciding implementation"
deciduous add option "Redis-based" -c 80
deciduous add option "In-memory with sliding window" -c 70

# Implementing
deciduous add action "Implementing Redis rate limiter" -c 85
deciduous link 21 23 --edge-type chosen -r "Scales across instances"

# If user gives new direction mid-stream, capture that prompt too
deciduous add action "Switch to token bucket" -c 85 -p "User said: actually use token bucket algorithm"

# Recording outcome
deciduous add outcome "Rate limiting working in prod" -c 95
deciduous link 23 24 -r "Implementation complete"

When to use --prompt: Capture user prompts on root goals and when the user redirects work mid-stream. Routine downstream nodes inherit context via edges.

deciduous sync   # Export graph to JSON for the web viewer

# Generate branch-specific visualization
deciduous dot --auto --nodes 20-24

# Generate PR writeup
deciduous writeup --auto -t "Add rate limiting" --nodes 20-24

Share decisions across team members working on the same codebase.

Each user has a local .deciduous/deciduous.db (gitignored). How do you share decisions?

Export/import patches using globally unique change IDs (inspired by jj/Jujutsu):

# Export your branch's decisions
deciduous diff export --branch feature-x -o .deciduous/patches/alice-feature.json

# Apply patches from teammates (idempotent)
deciduous diff apply .deciduous/patches/*.json

# Preview before applying
deciduous diff apply --dry-run .deciduous/patches/bob.json

# Check available patches
deciduous diff status

1. Create nodes while working
2. Export: deciduous diff export --branch my-feature -o .deciduous/patches/my-feature.json
3. Commit the patch file (NOT the database)
4. Open PR with patch file included
5. Teammates apply: deciduous diff apply .deciduous/patches/my-feature.json

Same patch applied twice = no duplicates.

deciduous tui

A rich, vim-style terminal interface for browsing your decision graph.

Navigation:

Filtering & Search:

File Operations:

Other:

The TUI includes syntax highlighting for file previews and diffs, using the same highlighting engine as bat.

deciduous serve --port 3000

Or deploy to GitHub Pages (workflow included with deciduous init).

Four visualization modes:

deciduous nodes              # List all nodes
deciduous nodes -b feature-x # Filter by branch
deciduous edges              # List all connections
deciduous graph              # Full graph as JSON
deciduous commands           # Recent command history

# Initialize
deciduous init

# Add nodes
deciduous add goal "Title" -c 90
deciduous add decision "Title" -c 75
deciduous add option "Title" -c 80
deciduous add action "Title" -c 85
deciduous add outcome "Title" -c 95
deciduous add observation "Title" -c 70

# Optional metadata (use -p when semantically meaningful)
deciduous add goal "Title" -c 90 -p "User prompt" -f "src/file.rs"  # Root goal with prompt
deciduous add action "Title" -c 85 -p "User redirect"               # When user changes direction
deciduous add goal "Title" -b feature-x    # Override branch
deciduous add goal "Title" --no-branch     # No branch tag

# Connect nodes
deciduous link 1 2 -r "Reason"
deciduous link 1 2 --edge-type chosen -r "Selected this"

# Query
deciduous nodes
deciduous nodes -b main                    # Filter by branch
deciduous edges
deciduous graph
deciduous commands

# Multi-user sync
deciduous diff export -o patch.json --branch feature-x
deciduous diff apply .deciduous/patches/*.json
deciduous diff apply --dry-run patch.json
deciduous diff status
deciduous migrate                          # Add change_id columns

# Visualize
deciduous serve
deciduous dot --png -o graph.dot
deciduous dot --auto --nodes 1-11

# Export
deciduous sync
deciduous writeup -t "Title" --nodes 1-11
deciduous backup

Nodes are automatically tagged with the current git branch.

Configuration (.deciduous/config.toml):

[branch]
main_branches = ["main", "master"]
auto_detect = true

Usage:

deciduous nodes --branch main        # Filter by branch
deciduous nodes -b feature-auth
deciduous add goal "Work" -b other   # Override auto-detection
deciduous add goal "Note" --no-branch # No branch tag

The web UI has a branch dropdown filter in the stats bar.

deciduous init creates a GitHub workflow that:

1. Deploys your graph viewer to GitHub Pages on push
2. Cleans up branch-specific PNGs after PR merge

Enable Pages: Settings > Pages > Source > Deploy from branch > gh-pages

Your graph will be live at https://<username>.github.io/<repo>/

See a real decision graph: deciduous_example

This shows 50+ decision nodes tracking a complete project with goals flowing through decisions to outcomes.

git clone https://github.com/notactuallytreyanastasio/deciduous.git
cd deciduous
cargo build --release
./target/release/deciduous --help

Optional dependency: graphviz (for --png flag)

brew install graphviz    # macOS
apt install graphviz     # Ubuntu/Debian

Deciduous trees shed their leaves seasonally but their structure persists. Like Claude's context, the leaves (working memory) fall away—but the decision graph (trunk and branches) remains, ready to support new growth.

MIT