Metadata-Version: 2.4
Name: degraph
Version: 1.0.1
Summary: Decision-Evidence Graph: traceable, challengeable, temporal decision provenance for AI agents
Project-URL: Homepage, https://github.com/rkstu/deg
Project-URL: Repository, https://github.com/rkstu/deg
Project-URL: Issues, https://github.com/rkstu/deg/issues
Author-email: Rahul Kumar <rahulkc.dev@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: adr,ai-agents,architecture-decision-records,claude,context,cursor,decisions,knowledge-graph,mcp,memory,provenance,session-memory,temporal
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: deg[graph,mcp,search]; extra == 'all'
Provides-Extra: graph
Requires-Dist: networkx>=3.0; extra == 'graph'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: search
Requires-Dist: faiss-cpu>=1.7; extra == 'search'
Requires-Dist: numpy>=1.24; extra == 'search'
Requires-Dist: sentence-transformers>=2.2; extra == 'search'
Description-Content-Type: text/markdown

# 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

```bash
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

```bash
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
