degraph 1.0.1

Decision-Evidence Graph: traceable, challengeable, temporal decision provenance for AI agents

DEG — Decision-Evidence Graph

Persistent decision memory for AI agents. DEG records WHY decisions were made, WHAT alternatives were rejected, and WHEN to reconsider — across sessions, with full provenance. It integrates as a Claude Code skill (via MCP + hooks) so decisions are captured and queried automatically, with zero manual documentation maintenance.

Quick Start

pip install degraph[mcp]
cd my-project
deg init --goal "Build a fraud detector" --phase "Research"
deg setup
# Restart Claude Code — DEG is now active

What Happens After Setup

Claude Code will automatically:

• Record decisions with evidence, alternatives, and reconsider-if triggers
• Surface stale decisions when triggers fire (time-based, metric drift, dependency changes)
• Trace provenance chains when you ask "why did we choose X?"
• Challenge decisions when new evidence contradicts them
• Hand off session state so the next session starts with full context

You don't invoke DEG manually. It runs reflexively via hooks and MCP tools.

Core Operations

Operation	Description
status()	Project state, stale alerts, and next actions
decide()	Record a decision with evidence, alternatives, and reconsider_if
evidence()	Record a finding with source, confidence, and temporal validity
search(query)	Hybrid semantic + keyword + graph-walk retrieval
trace(id)	Full upstream provenance chain (BFS)
challenge(id)	Check validity, triggers, evidence health, and alternatives
impact(id)	Downstream cascade — all affected nodes
continue_research(id)	Next searches, open questions, and look_for directives
close_session()	Save state for the next session
compile()	Incremental YAML-to-JSONL+FAISS compilation

CLI Commands

deg init          Initialize a DEG project (creates decisions/, evidence/, .deg/)
deg setup         Configure Claude Code skill (CLAUDE.md + MCP + hooks)
deg status        Show project state and stale alerts
deg decide        Record a decision interactively
deg evidence      Record evidence interactively
deg search        Search the decision graph
deg trace         Trace provenance for a node
deg challenge     Challenge a decision's validity
deg impact        Show downstream impact of a node
deg continue      Show next steps for a research thread
deg close         Close session and save state
deg compile       Force recompilation of all sources
deg export        Export graph as JSON/DOT/Mermaid
deg serve         Start MCP server (for non-Claude clients)

MCP Tools

DEG exposes 9 tools via MCP for any compatible AI client:

Tool	Purpose
deg_status	Get project state and alerts
deg_decide	Record a decision
deg_evidence	Record evidence
deg_search	Query the decision graph
deg_trace	Get provenance chain
deg_challenge	Challenge a decision
deg_impact	Get downstream cascade
deg_continue_research	Get next research steps
deg_close_session	Save session state

How It Works

decisions/         YAML frontmatter markdown (human-readable, git-friendly)
evidence/          Same format for findings, measurements, sources
.deg/
  index.jsonl      Compiled node index
  graph.jsonl      Edge list
  embeddings.faiss IDMap2(FlatL2) vector index
  state.yaml       Session handoff state

Architecture:

1. Decisions and evidence are stored as markdown files with YAML frontmatter
2. deg compile incrementally hashes and indexes them into .deg/ (content-hash dedup, ~100x embedding savings)
3. Claude accesses the graph via MCP tools during conversation
4. Hooks auto-fire deg status on session start and deg close on session end
5. Retrieval is hybrid: semantic (FAISS) + keyword (BM25-like) + graph walk (Personalized PageRank)
6. DEG itself makes zero LLM calls — all intelligence comes from the host agent

Latency: status 0.6ms, decide/evidence 22ms, search 6ms, trace/impact <1ms.

Ecosystem

DEG handles decision provenance. For full agent context, pair with:

• Understand-Anything — code structure graph (replaces architecture docs)
• TinyFish — web research with source tracking
• Probe-Ratchet — deterministic experiment loops with automatic evidence capture
• ML-Intern — deep literature research agent (feeds evidence into DEG)

Together with DEG, these replace all manually-maintained .md files except a minimal CLAUDE.md.

Install Options

pip install degraph[mcp]    # Recommended: MCP server + CLI + hooks
pip install degraph       # Minimal: CLI only, no MCP
pip install degraph[all]    # Full: adds local FAISS semantic search

Requirements

• Python 3.10+
• Claude Code (or any MCP-compatible client)
• No API keys needed — DEG makes zero external calls

License

MIT