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
- 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 providesrecord_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 isAgentContext.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.
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.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.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.
trace_decision_causality on the graph directly:
Gating Decisions Against Policy
Before recording a high-stakes decision, check it against a versioned policy. ThePolicyEngine stores Policy nodes in the graph and gates Decision objects against their rules.
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.
Domain Examples
- Defense — CTI/Threat
- Security — SOC/Incident
- Life Science — Clinical/Pharma
- Banking — Risk/Compliance
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 localContextGraph, 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. Useadd_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.
Related Guides
- Context Graphs — how
ContextGraphstores decision nodes and causal edges - Distance Intelligence —
trace_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_decisionandfind_precedentstools - Change Management — checkpoint decision state with
flush_checkpoint()for versioned snapshots
