Neo4j Context Graph Decision-Aware Agent Framework

// When should you use the Neo4j Context Graph Decision-Aware Agent Framework?

Use this skill when building or auditing an AI agent that must take consequential or autonomous actions — especially where the agent will encounter situations its prompt engineering did not anticipate, or where decision traceability and accountability are required.

// What inputs do you need to design a decision-aware context graph agent?

• agent_objectiverequired
  The goal the agent is trying to achieve (e.g., 'keep fridge stocked with Red Bull', 'assess loan eligibility').
• operating_environmentrequired
  The domain or context in which the agent operates (e.g., consumer purchasing, medical guidance, financial services). Stakes level must be assessed.
• causality_chainrequired
  The sequence of reasoning steps and actions that led the agent to the current decision point.
• existing_rules_and_policies
  Hard and soft business rules available — formal (business process docs) or informal (Slack channels, Google Docs, etc.).
• prior_decisions
  Historical precedent stored in the context graph — what was decided before in similar circumstances.
• agent_authority_scoperequired
  What the agent is and is not authorised to act on autonomously.

// What are the core principles behind context graph decision-aware agents?

// How do you apply the context graph decision-aware agent framework step by step?

1. 1

   Frame the Local Context

   Capture three things: (1) the agent's current objective, (2) the causality — the reasoning chain and actions that produced this decision point, and (3) the operating environment and its stakes level (e.g., consumer commerce vs. medical care vs. financial services). Without this framing the agent cannot weight risks correctly.

2. 2

   Load the Global Context from the Context Graph

   Query the context graph for two inputs: (1) Prior Decisions — what was decided before in comparable circumstances; consistency is valuable unless rules have changed. (2) Hard and Soft Rules — formally documented policies and informal guidance. Both must be loaded and held in tension. A prior decision may need to be overruled by a rule that was updated since.

3. 3

   Perform Reference Class Validation

   Before risk-value analysis, classify the situation: which population or scenario class does this case actually belong to? Do not assume the majority case applies. Explicitly ask: Is this the 99% or the 1%? This step prevents statistically-correct-but-individually-catastrophic decisions.

4. 4

   Run Risk-Value Analysis

   Assess the risk side: Is the decision reversible? What is the cost of being wrong? What are the specific risks for the players involved (not just the general case)? Assess the value side: What is being maximised (savings, safety, speed) or minimised (cost, harm)? These must be explicit — the agent cannot infer them reliably from general knowledge.

5. 5

   Generate Alternatives Proposal (Analysis Agent Output)

   The output of the analysis stage is NOT a decision. It is a structured proposal listing available options with pros and cons for each. This proposal is handed off — do not collapse analysis and choice into a single agent step.

6. 6

   Check Authority and Act or Escalate (Decision Agent)

   A separate agent (or human) receives the proposal and asks: Do I have sufficient certainty? Do I have the authority to act? If yes to both: rank the options and execute. If no to either: escalate to a higher-privilege agent or trigger the human-in-the-loop oversight sub-process. Deferral (taking no action pending escalation) is a valid and sometimes correct output state.

7. 7

   Record Decision Trace Back into Context Graph

   Regardless of outcome (action taken, escalated, or deferred), write the complete record to the context graph: what was considered, what was rejected, the reasoning chain, the decision made, and the actions taken. This becomes Reasoning Memory and serves as precedent for future agents. This is the self-learning loop that improves agent quality over time.

// What are real-world examples of context graph decision-aware agents in action?

// What mistakes should you avoid when building context graph decision-aware agents?

• Conflating knowledge graphs with context graphs — storing only facts without storing the why (policies, rules, and decision rationale) leaves agents unable to make principled decisions.
• Using a single agent for both analysis and decision-making — collapsing these roles removes the authority checkpoint and produces unaccountable autonomous action.
• Relying on statistical majority behaviour without reference class validation — the 99% answer is fatal for the 1% case, and agents will default to it unless explicitly instructed otherwise.
• Leaving hard and soft rules implicit in prompts rather than encoding them in the context graph — informal rules degrade or disappear; graph-stored rules persist and can be queried.
• Skipping the decision trace step — without recording reasoning back to the context graph, agents cannot learn from precedent and auditability is lost.
• Allowing agents to guess under uncertainty rather than escalate — without an explicit 'act or escalate' checkpoint, autonomous agents will take actions they lack the authority or certainty to support.
• Assuming the framework generalises without domain tuning — every step of this workflow has domain-specific particulars; the framework is a skeleton, not a finished product.

// What are the key terms and concepts in the context graph agent framework?

Context Graph

A graph database structure that stores not only factual knowledge (what) but also policies, rules, and decision precedents (why), enabling agents to become decision-aware rather than merely knowledge-capable.

Decision-Aware Agent

An AI agent equipped with a context graph and decision workflow that allows it to handle situations not covered by its initial instructions, making principled choices grounded in rules, precedent, and explicit risk-value analysis.

Short-Term Memory

The layer of agent memory that captures the current conversation state and interaction history — what has happened in this session.

Long-Term Memory

The layer of agent memory that stores generalised, persistent knowledge about organisations, people, and entities — the stable world model.

Reasoning Memory

The layer of agent memory that stores policies, rules, and prior decision rationale — the why that governs agent behaviour and enables consistent, accountable decisions.

Reference Class Validation

A risk analysis step that explicitly classifies the current case into its relevant population segment before deciding, preventing the agent from applying majority-case logic to minority-case situations where that logic fails or causes harm.

Hard and Soft Rules

Hard rules are formally documented, non-negotiable policies. Soft rules are informal guidance (e.g., Slack channels, internal docs) that represent cultural or operational norms. Both must be encoded in the context graph and balanced against each other.

Act or Escalate

The binary decision gate at the authority-check step: if the agent has both certainty and authority, it acts; if it lacks either, it escalates to a higher-privilege agent or human-in-the-loop oversight sub-process.

Human-in-the-Loop Oversight Sub-process

The escalation pathway triggered when an agent determines it lacks the authority or certainty to act autonomously — routing the decision to a human or a higher-privilege agent.

Decision Trace

The complete recorded artefact of a decision event: what was considered, what was rejected, the full reasoning chain, the outcome, and actions taken — stored back into the context graph as precedent for future agents.

Text to Cypher

A tool that translates natural language queries into Cypher, the Neo4j graph query language, enabling agents to retrieve structured graph data without requiring users or agents to write graph queries manually.

// FREQUENTLY ASKED QUESTIONS