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 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, and outcome 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 authentication?" 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 /context 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.

A Quick Example

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

Claude Code Session

> Add rate limiting to the API I'll implement rate limiting. Let me log this to the decision graph first. deciduous add goal "Add rate limiting" -c 90 -p "User: Add rate limiting to the API" Created node #47: goal "Add rate limiting" Now I need to decide on the approach... deciduous add decision "Choose rate limiting strategy" -c 75 Created node #48: decision "Choose rate limiting strategy" deciduous add option "Redis-based sliding window" -c 80 Created node #49: option "Redis-based sliding window" deciduous add option "In-memory token bucket" -c 70 Created node #50: option "In-memory token bucket" Looking at your infrastructure, I recommend Redis since you're already using it for sessions. deciduous add action "Implementing Redis rate limiter" -c 85 deciduous link 48 51 --edge-type chosen -r "Redis already in stack, scales across instances" [Claude implements the feature...] deciduous add outcome "Rate limiting working" -c 95 --commit HEAD deciduous sync

Now this decision chain is permanently recorded. Next week, next month, next year—anyone can query the graph to understand not just what was built, but why.

The Core Insight

The insight behind deciduous is simple:

Decisions are more valuable than documentation.

Documentation describes what exists. A decision graph captures why it exists, what alternatives were considered, and what tradeoffs were made. This is the knowledge that actually helps future developers (and future AI sessions).

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

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.

Previous Introduction Next How to Read This Tutorial