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 We'll Follow

Let me tell you about snowflex, an Elixir library for connecting to Snowflake databases. It started as a simple ODBC wrapper—one module, one connection. Over 130 commits and two years, it evolved through five major architectural shifts: single connections to pools, pools to module-based APIs, ODBC to HTTP REST, single-auth to flexible key management. Each pivot was driven by real production pain. In this tutorial, you'll reconstruct that entire story using deciduous—then add a new chapter by working on a real open issue.

snowflex is the perfect subject because it's small enough to understand completely, but rich enough to have real decision history. Every project has this story buried in its git log. Most never get it told.

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 connection pooling?" and get the full reasoning back.

But here's what makes it genuinely useful: Deciduous is designed to be operated BY your AI assistant. You tell Claude to /decision-graph on your repo, or /work on an issue, and Claude handles the logging. You get to focus on the work.

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. Archaeology (Existing Projects)

Got an existing project with months or years of history? Point Claude at the repo and let it reconstruct the story:

Claude reads the git log, identifies pivots, and builds the decision graph. You get months of architectural history mapped in minutes.

2. Forward Logging (New Work)

When you start new work, Claude logs decisions in real-time as it goes:

Each decision is captured as it happens. The reasoning is fresh, the context is complete. You didn't have to type a single deciduous command.

A Quick Example

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

                ┌────────────────────┐
                │ goal: Fix timeout  │
                │ handling (#93)     │
                └─────────┬──────────┘
                          │
            ┌─────────────┼─────────────┐
            ▼                           ▼
     ┌──────────────┐          ┌──────────────┐
     │ option:      │          │ option:      │
     │ Retry with   │          │ Circuit      │
     │ backoff      │          │ breaker      │
     └──────┬───────┘          └──────────────┘
            │
            ▼
     ┌──────────────┐
     │ decision:    │
     │ Use retry    │──── "simpler, sufficient
     │ approach     │      for this case"
     └──────┬───────┘
            │
            ▼
     ┌──────────────┐
     │ action:      │
     │ Implement    │──── commit: abc123
     │ retry logic  │
     └──────┬───────┘
            │
            ▼
     ┌──────────────┐
     │ outcome:     │
     │ Timeouts     │
     │ reduced 95%  │
     └──────────────┘

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
• A conversational Q&A interface — ask your AI assistant questions about past decisions and get answers grounded in the graph
• Informed AI decisions — once the graph has history, your AI uses it to make better choices, avoiding approaches that were already tried and rejected
• Automatic context recovery when Claude starts new sessions
• Visual decision graphs for PRs and documentation
• Git commit integration linking decisions to code
• A web viewer for browsing the graph interactively

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.