AgentContext.record_decision() stores every AI decision as a node in the knowledge graph, linked by causal edges to the decisions that preceded it and the outcomes that followed. Use it to build an auditable reasoning trail — one that lets you reconstruct, six months later, exactly which classification caused which escalation, and which policy was checked before it was recorded.

What Is Decision Intelligence?

Decision Intelligence records and analyzes an agent’s own decisions as structured data that can be queried, analyzed, and reused. Instead of decisions disappearing after execution, they become persistent graph nodes with searchable metadata, reasoning chains, and causal relationships. Decision Intelligence records decisions by capturing the scenario, reasoning, outcome, confidence, and decision maker for each choice the agent makes. These decisions become queryable nodes in your knowledge graph. Decisions become graph nodes that can be linked causally (Decision A caused Decision B), searched by similarity (find decisions like this scenario), and analyzed statistically (confidence trends, common outcomes). The goal is auditability, explainability, precedent search, and causal tracing. You can trace why decisions were made, find similar past decisions for consistency, and understand the full causal chain from initial detection to final action. Decision Intelligence vs. Agent Memory: Agent Memory stores external knowledge (documents, facts, observations). Decision Intelligence stores internal decisions (classifications, approvals, actions the agent itself made). Decision Intelligence vs. Reasoning: Reasoning derives new facts from existing data using logical rules. Decision Intelligence records the choices and judgments the agent made during problem-solving. Decision Intelligence vs. Graph Analytics: Graph Analytics analyzes the structural properties of your knowledge graph. Decision Intelligence focuses specifically on the decision-making process and its audit trail.

Why Use Decision Intelligence?

Auditable AI actions. Every decision is recorded with reasoning, confidence, and timestamp, creating a complete audit trail for AI behavior in production systems. Explainability. When stakeholders ask “why did the system do X?”, you can trace the exact decision chain that led to that action, including intermediate reasoning steps. Precedent reuse. Before making new decisions, agents can search for similar past scenarios and their outcomes, promoting consistency and learning from previous experience. Causal analysis. Understand how early decisions cascade into later outcomes by following causal relationships between linked decision nodes. Governance and compliance. Policy engines can gate decisions against compliance rules, and all policy applications are recorded for regulatory audit.

When To Use / When Not To Use

Use Decision Intelligence when:
  • Building autonomous agents that make consequential choices
  • Implementing decision workflows requiring audit trails
  • Operating under compliance requirements (financial services, healthcare, defense)
  • Building approval systems with multiple decision points
  • Working in risk-sensitive environments where decisions must be explainable
Do not use when:
  • Building stateless chatbots that only retrieve information
  • Implementing simple RAG systems without decision-making
  • Creating read-only information retrieval applications
  • Building applications that never make actionable decisions requiring audit trails

API Architecture Overview

Decision Intelligence coordinates three main components: AgentContext serves as the high-level orchestration layer. It provides record_decision(), find_precedents(), and causal chain methods while managing the underlying storage and retrieval systems. PolicyEngine handles policy evaluation and compliance checking. It stores policy rules as graph nodes and validates decisions against those rules before they’re recorded. DecisionRecorder specializes in recording structured decision data, managing approval chains, and handling policy exceptions when decisions need to bypass normal rules.
Decision tracking requires both a VectorStore (for embedding-based precedent search) and a ContextGraph (for causal graph storage). Set decision_tracking=True on AgentContext — omitting ContextGraph raises a RuntimeError at call time. VectorStore is required by AgentContext itself: leaving the argument out raises a TypeError from Python’s argument binding, while passing vector_store=None raises a ValueError during initialization.

Recording the First Decision

The most common entry point is AgentContext.record_decision(). It writes a Decision node into the graph, generates embeddings for hybrid similarity search, and returns a UUID you use to link subsequent decisions causally.
The decision_maker field identifies the component, workflow, agent, or system that produced this decision. Use consistent identifiers like "cti_pipeline_v2", "analyst_chen", or "risk_model_v3" to enable filtering and analysis by decision source. The Decision dataclass that backs this node has the following fields — these are what get stored and searched:

Searching Precedents Before Deciding

Before making a significant call, the system should search past decisions for similar scenarios. This is how you prevent the same cluster being classified differently across two agent runs — the second agent finds the first agent’s decision and uses it as a prior.
Hybrid search blends two signals: semantic similarity over the scenario and reasoning text (weight 0.7), and structural graph proximity via Node2Vec embeddings (weight 0.3). The result is a ranked list of Decision objects — the most similar past decisions float to the top regardless of how differently they were phrased.

Building a Causal Chain

Decisions rarely exist in isolation. A classification decision causes an escalation decision, which causes a containment decision. Linking them with causal edges lets you traverse the chain in either direction — upstream to understand what caused an outcome, downstream to see what an early decision triggered.
Now trace the chain from the patch decision back to its root cause:
And trace downstream from the original classification to see everything it triggered:

Generating an Explainability Report

trace_decision_explainability gives you the full picture in one call: upstream causes, downstream effects, and total connection count. This is what you attach to a post-mortem or audit report.
For deeper causal analysis with confidence decay and distance bands, use trace_decision_causality on the graph directly:

Gating Decisions Against Policy

Before recording a high-stakes decision, check it against a versioned policy. The PolicyEngine stores Policy nodes in the graph and gates Decision objects against their rules.
When a high-urgency situation requires bypassing the policy gate, record the exception with the approver identity and justification:
For multi-level approval workflows, use DecisionRecorder.record_approval_chain() with a graph database backend (for example Neo4j/FalkorDB). The in-memory ContextGraph examples used in this guide do not support approval-chain persistence via execute_query().

Generating a Decision Audit Report

At the end of a shift or incident, get_decision_insights produces a statistical summary of every decision in the graph — useful for shift handover notes and compliance reporting.
Sample output:

Domain Examples

A CTI pipeline classifies threat clusters, records each classification with confidence and reasoning, links classification decisions to escalation decisions causally, and generates a daily audit report for the threat intelligence lead.

Persisting Decisions Across Restarts

When using the local ContextGraph, save at the end of every session and load at the start of the next. All decision nodes, causal edges, and FAISS embeddings are restored.

Common Pitfalls

Recording decisions without linking causal relationships. Isolated decision nodes provide less insight than connected decision chains. Use add_causal_relationship() to link related decisions and enable causal tracing. Creating isolated decision nodes. Decisions gain value when connected to entities, other decisions, or outcomes in your graph. Link decisions to relevant entities using the entities parameter. Recording too many low-value decisions. Not every minor choice needs permanent recording. Focus on consequential decisions that affect outcomes, require audit trails, or benefit from precedent search. Treating precedent similarity as proof. High similarity scores indicate related scenarios, not identical situations. Use precedents as guidance while considering the specific context of each new decision. Using Decision Intelligence when simple retrieval is sufficient. If your system only retrieves information without making actionable choices, traditional search or Agent Memory may be more appropriate than decision tracking.
  • Context Graphs — how ContextGraph stores decision nodes and causal edges
  • Distance Intelligencetrace_decision_causality() annotates causal chains with confidence decay and distance bands
  • Provenance — W3C PROV-O audit trail that wraps decision records in standards-compliant provenance
  • MCP Server — expose decision recording and precedent search to LLM agents via the record_decision and find_precedents tools
  • Change Management — checkpoint decision state with flush_checkpoint() for versioned snapshots