What is Deciduous and Why Should I Care?

Here's a scenario you've probably experienced:

You're three months into a project. Someone asks why you chose PostgreSQL over MongoDB. You vaguely remember there was a good reason, something about transactions and the data model, but the specifics? Gone. The Claude session where you worked through the tradeoffs? Long compacted. The Slack thread? Buried. You shrug and say "it made sense at the time."

This is the decision evaporation problem, and it's gotten dramatically worse with AI-assisted development.

The Story of a Real Project

Let me tell you about a project we'll call "Acme Inventory." It started as a weekend prototype—a simple CRUD app for tracking warehouse stock. The founder hacked it together with Claude's help in a few sessions. Worked great.

Six months later, Acme Inventory was running in production for 200 warehouses. The codebase had grown to 50,000 lines. And the founder was staring at a piece of code that made no sense:

// Why do we batch inventory updates in groups of 100?
// Why not 50? Why not 1000?
// This comment says "performance" but provides no context

The answer was in a Claude session from March. During a load test, they'd discovered that their PostgreSQL connection pool couldn't handle more than 100 concurrent inserts without timing out. The batch size of 100 was carefully chosen based on real performance data.

But that session was gone. The decision rationale was gone. All that remained was a magic number and a one-word comment.

The AI Context Problem

When you work with Claude (or any LLM), you make dozens of decisions per session. Claude might explore three authentication approaches, reject two, and implement one. It considers error handling strategies, weighs library choices, evaluates architectural patterns. All of this reasoning happens, informs your code, and then... disappears when the context window compacts or the session ends.

You're left with:

• Code that works (hopefully)
• No record of what was considered
• No memory of why alternatives were rejected
• No way to recover context in a new session

Deciduous solves this.

What Deciduous Does

Deciduous is a decision graph tool that captures every goal, decision, option, action, outcome, and revisit as you work. It stores them in a queryable SQLite database that survives session boundaries. When Claude's context compacts, the graph remains. When you start a new session six months later, you can query "what did we decide about batch sizes?" and get the full reasoning back.

But here's what makes it genuinely useful: it's designed to be logged in real-time by Claude itself. The workflow isn't "write documentation after the fact." It's "Claude logs decisions as it makes them, and those decisions become the documentation."

This means:

• Context survives compaction. When Claude runs /recover at session start, it queries the graph and recovers reasoning it never saw.
• PRs explain themselves. Generate decision visualizations and writeups directly from the graph.
• Institutional knowledge persists. Six months later, anyone can trace why things were built the way they were.
• LLM output becomes reviewable. Instead of just seeing code, you see the decision flow that produced it.

Two Ways to Use Deciduous

There are two main workflows, and most projects use both:

1. Forward Logging (New Work)

As you work with Claude on new features, Claude logs decisions in real-time:

Each decision is captured as it happens. The reasoning is fresh, the context is complete.

2. Archaeology (Existing Projects)

Got an existing project with months of history? Mine your git log, issues, and PRs to reconstruct the decision graph:

Archaeology doesn't capture everything, but it captures the important decisions that shaped your architecture.

A Quick Example

Here's what a decision flow looks like in deciduous:

                ┌────────────────────┐
                │ goal: Add rate     │
                │ limiting to API    │
                └─────────┬──────────┘
                          │
                          ▼
                ┌────────────────────┐
                │ decision: Choose   │
                │ strategy           │
                └─────────┬──────────┘
                          │
            ┌─────────────┼─────────────┐
            ▼             │             ▼
     ┌──────────┐        │      ┌──────────┐
     │ option:  │        │      │ option:  │
     │ Redis    │        │      │ In-mem   │
     │ sliding  │        │      │ token    │
     └──────────┘        │      └──────────┘
                         │
                         ▼
                ┌────────────────────┐
                │ action: Implement  │──── [chosen]
                │ Redis rate limiter │
                │ commit: abc123     │
                └─────────┬──────────┘
                          │
                          ▼
                ┌────────────────────┐
                │ outcome: Rate      │
                │ limiting working   │
                └────────────────────┘

Now this decision chain is permanently recorded. Anyone can query the graph to understand not just what was built, but why.

The Core Insight

The insight behind deciduous is simple:

When an AI assistant logs decisions in real-time, you get documentation as a side effect of the development process—not as an afterthought.

What You'll Get

After setting up deciduous, you'll have:

• A queryable history of every major decision
• Automatic context recovery when Claude starts new sessions
• Visual decision graphs for PRs and documentation
• Git commit integration linking decisions to code
• Multi-user sync so teams share decision context
• Three viewers: Terminal UI, web viewer, and CLI

Why "Deciduous"?

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.