Frequently Asked Questions About Neo4j Context Graph Decision-Aware Agent Framework
21 answers covering everything from basics to advanced usage.
// Basics
What does 'decision-aware' actually add on top of a normal AI agent?
It adds the ability to handle situations the prompt never anticipated. A normal agent defaults to statistical averages when it hits an unknown; a decision-aware agent instead loads relevant rules and precedent from a context graph, classifies the situation's reference class, runs explicit risk-value analysis, and either acts within its authority or escalates. The difference is principled reasoning versus statistical guessing.
What is Reasoning Memory and how is it different from Long-Term Memory?
Long-Term Memory stores generalised knowledge about organisations, people, and things — the stable world model of what exists. Reasoning Memory stores the policies, rules, and prior decision rationale that tell the agent why to act a certain way. Long-Term Memory is facts; Reasoning Memory is governance and precedent. Both are needed, but only Reasoning Memory makes an agent accountable.
What are hard rules versus soft rules in a context graph?
Hard rules are formally documented, non-negotiable policies — clinical protocols, compliance requirements, business process docs. Soft rules are informal guidance representing cultural or operational norms, often living in Slack or internal docs. Both must be encoded in the context graph and balanced against each other; a soft rule can guide behaviour, but a hard rule overrides it and can override prior precedent too.
What is Text to Cypher and do I need it?
Text to Cypher is a tool that translates natural language into Cypher, Neo4j's graph query language, so agents can retrieve structured graph data without writing queries manually. You need it if you want agents to query the context graph fluidly at decision time without hardcoding every query path. It lowers the engineering cost of loading global context in workflow step two.
// How To
How do I convert implicit human understanding into an explicit context graph?
Interview stakeholders and mine informal channels to surface unstated assumptions about stakes, constraints, and edge cases, then encode each as explicit graph nodes and relationships. The Explicit Over Implicit principle warns that anything the agent isn't told, it defaults to statistical averages on. Prioritise the 1% edge cases where majority logic causes harm — those are the assumptions worth making explicit first.
How do I frame the local context for a decision correctly?
Capture three things: the agent's current objective, the causality chain (the reasoning and actions that produced this decision point), and the operating environment with its stakes level. Without stakes framing — consumer commerce versus medical care versus finance — the agent can't weight risks correctly. This is step one of the workflow and everything downstream depends on getting it right.
How do I build the act-or-escalate gate in practice?
Give the decision agent two explicit checks against the proposal it receives: sufficient certainty, and authority scope. Encode the agent's authority boundaries as data the agent can query. If both checks pass, rank options and execute. If either fails, route to a higher-privilege agent or trigger the human-in-the-loop sub-process. Treat deferral — no action pending escalation — as a first-class, valid output state.
How do I run risk-value analysis for a specific decision?
Assess the risk side first: Is the decision reversible? What's the cost of being wrong? What are the specific risks for the actual players involved, not just the general case? Then the value side: what's being maximised (savings, safety, speed) or minimised (cost, harm)? Make both explicit — the agent can't reliably infer them from general knowledge, so store them as retrievable context.
// Troubleshooting
My agent keeps taking actions it shouldn't. How do I fix it?
You're likely using a single agent for both analysis and decision-making, which removes the authority checkpoint. Split the roles: an analysis agent that only proposes alternatives, and a decision agent that verifies certainty and authority before acting. Also confirm the agent's authority scope is explicitly encoded and that guessing under uncertainty triggers escalation rather than execution.
My agent makes reasonable-sounding decisions but fails on edge cases. What's wrong?
You're probably skipping reference class validation and relying on statistical majority behaviour. Add an explicit step before risk-value analysis that classifies which population the current case belongs to and asks: Is this the 99% or the 1%? Statistically-correct decisions become individually-catastrophic on edge cases unless the agent is instructed to check reference class first.
My agents can't learn from past decisions. What am I missing?
You're likely skipping the decision trace step. Every decision — made, escalated, or deferred — must be written back to the context graph with its full reasoning chain, considerations, rejected alternatives, and outcome. Without this, there's no precedent for future agents to query and no auditability. The trace is the self-learning loop that improves agent quality over time.
I encoded rules in prompts but they keep degrading. Why?
Rules left implicit in prompts are fragile — informal guidance drifts or disappears and prompt length limits force trade-offs. Encode hard and soft rules as nodes and relationships in the context graph instead. Graph-stored rules persist, can be queried at decision time, and can be updated centrally so a new rule can correctly overrule stale prior decisions.
// Comparisons
How does this framework compare to a plain RAG pipeline?
RAG retrieves relevant facts to ground a response; it answers the 'what.' This framework adds the 'why' — policies, rules, and decision precedents — plus a structured decision workflow, reference class validation, and an act-or-escalate authority gate. RAG improves accuracy of answers; the context graph framework makes autonomous actions accountable, auditable, and safe on edge cases. They're complementary, not competing.
How does this compare to using a single powerful LLM with a big system prompt?
A big system prompt leaves rules implicit, degrades over time, and can't record precedent for future runs. It also collapses analysis and authority into one step, removing the accountability checkpoint. This framework externalises rules into a queryable context graph, separates analysis from decision authority, and writes decision traces back for auditability and self-improvement — none of which a monolithic prompt provides.
Is a context graph the same as a vector database for agent memory?
No. Vector databases store embeddings for semantic similarity retrieval — great for fuzzy fact lookup. A context graph stores explicit entities, relationships, rules, and decision precedents with structured traversable connections. You often use both: vectors for finding relevant material, the graph for encoding governing rules and precedent that must be reasoned over precisely rather than approximately matched.
// Advanced
How do I handle a case where a prior decision conflicts with an updated rule?
Load both the prior decision and the current hard and soft rules into global context and hold them in tension. Consistency with precedent is valuable, but a prior decision must be overruled when a rule has been updated since. Encode rule version or effective dates in the graph so the decision agent can detect the conflict and prefer the current rule.
How do I design authority scope across a multi-agent hierarchy?
Encode each agent's authorised actions explicitly as data, and define escalation paths from lower-privilege to higher-privilege agents ending in a human-in-the-loop sub-process. When a decision agent lacks certainty or authority, it escalates upward. This compartmentalisation — propose, don't decide — keeps analysis separate from authority and ensures no agent acts beyond its granted scope.
Can this framework be applied to an existing agent I want to audit?
Yes. Use the workflow as an audit checklist: does the agent frame local context with stakes, load rules and precedent, validate reference class, run explicit risk-value analysis, separate proposal from decision, gate on authority, and record a trace? Gaps in any step reveal where the agent may guess, act without authority, or fail edge cases. The framework doubles as an accountability audit.
Does the framework generalise across domains out of the box?
No — assuming it does is a listed pitfall. Every step has domain-specific particulars: stakes weighting, which rules are hard versus soft, what reference classes matter, and what authority thresholds are safe. The workflow is a skeleton, not a finished product. Budget for domain tuning at each step, especially reference class definitions and risk-value criteria, which vary enormously by field.
How do I decide the right stakes level for my operating environment?
Judge stakes by reversibility and cost of being wrong for the actual players. Consumer purchasing where an order can be cancelled is low stakes; medical treatment or financial approvals with irreversible harm are high stakes. Encode the stakes level in local context because it determines how conservatively the agent weights risk and how readily it should escalate rather than act.
What should a decision trace actually contain to be useful precedent?
It should contain the full considered set — what was proposed, what was rejected and why, the complete reasoning chain, the reference class determination, the risk-value analysis, the final outcome (acted, escalated, or deferred), and the specific actions taken. Rich traces let future agents query comparable circumstances and maintain consistency, while auditors can reconstruct exactly why any decision was made.