Knowledge and Decision Intelligence

Agents need more than similar text. They need to recover what was known, understand how domain entities relate, compare viable actions, distinguish predictions from observations, and improve future guidance without silently rewriting organisational knowledge.

Neutron provides that persistent layer beneath your application and reasoning models:

flowchart LR
  A["Remember"] --> B["Connect knowledge"]
  B --> C["Build bounded context"]
  C --> D["Compare options"]
  D --> E["Predict consequences"]
  E --> F["Record decisions"]
  F --> G["Observe outcomes"]
  G --> H["Review learning"]
  H --> C

It does not replace your model provider, professional judgement, application authorisation, domain simulator, or optimisation solver.

First-Class Temporal Knowledge

Entities are domain-neutral identities. Relationships are first-class records rather than hard-coded edges.

const field = await neutron.entities.upsert({
  nucleusId: "farm-operations",
  scopeId: "farm:alpha",
  id: "field_7",
  type: "field",
  name: "Field 7",
  attributes: { hectares: 24 },
  confidence: 0.96,
  provenance: {
    sourceType: "database",
    sourceId: "farm-erp",
    classification: "observed",
    recordedAt: Date.now(),
  },
});

await neutron.graph.connect({
  nucleusId: "farm-operations",
  scopeId: "farm:alpha",
  id: "field_7_uses_harvester_2",
  fromEntityId: field.id,
  toEntityId: "harvester_2",
  type: "depends_on",
  graphDimension: "operational",
  direction: "directed",
  confidence: 0.9,
  causal: false,
  evidence: [],
  provenance: {
    sourceType: "database",
    sourceId: "asset-register",
    classification: "observed",
    recordedAt: Date.now(),
  },
});

An entity can participate in organisational, operational, spatial, ownership, financial, dependency, skills, decision, consequence, or application-defined graph dimensions at the same time.

validAt asks what was true in the represented domain. knowledgeAt asks what Neutron had recorded at that system time. Updates append versions; they do not overwrite historically significant state. Tombstones remove records from current reads without letting queues, caches, archives, or compaction restore them.

Confidence, Provenance, and Contradictions

Important memory, entities, relationships, claims, consequences, decisions, outcomes, and learning can distinguish observed, provided, derived, inferred, predicted, and hypothesised information.

Provenance records the source type, stable source identifier, timestamp, actor, method, and optional model or solver identity. When two claims conflict, Neutron retains both claims, evidence, source reliability, confidence, and timestamps. A contradiction remains unresolved until an automatic, agent, or human resolution is recorded.

One Bounded Context Request

Applications do not need to query each subsystem separately.

const context = await neutron.context.build({
  nucleusId: "farm-operations",
  scopeIds: ["farm:alpha", "equipment:shared"],
  agentId: "agent_planner",
  task: "Compare harvest plans for Field 7",
  entities: [{ entityId: "field_7" }],
  graphDimensions: ["spatial", "operational", "ownership"],
  timeframe: {
    validAt: Date.now(),
    knowledgeAt: Date.now(),
  },
  tokenBudget: 4_000,
  includeContradictions: true,
  createSnapshot: true,
  debug: true,
});

The Context Engine can combine eligible memories, entities, relationships, graph neighbourhoods, previous decisions, consequence evidence, outcomes, procedures, contradictions, provenance, confidence, and reviewed learning. The response contains structured data and a prompt-ready representation.

Retrieval uses more than vector similarity. Its trace exposes semantic, lexical, graph, temporal, importance, confidence, entity, agent, and decision relevance components where available, plus applied and denied Scopes and estimated token use.

Persisted agent permissions are applied while context is assembled. A Nucleus-level token does not automatically give an agentId access to every Scope, and explicit deny rules take precedence.

Multi-Objective Decision Guidance

A decision preserves its situation, subject entities, objectives, hard and soft constraints, options, predicted consequences, selected option, actors, status, and decision-time knowledge snapshot.

Neutron evaluates the values and constraint results your application supplies. It reports:

• infeasible options and unresolved hard constraints;
• Pareto-dominated and Pareto-efficient options;
• priority profiles and explicit trade-offs;
• uncertainty, assumptions, evidence, and affected entities;
• an optional specialised solver result with its version and proof boundary.

Neutron does not force every problem into a weighted average. When several options preserve different trade-offs, guidance states that no universally optimal option exists.

Consequences, Simulations, and Counterfactuals

Consequences remain multi-dimensional records. They can carry financial, operational, environmental, human, risk, productivity, time, customer, regulatory, strategic, or domain-defined dimensions alongside probability, confidence, timeframe, affected entities, evidence, assumptions, and dependencies.

Dependencies form bounded first-order and downstream consequence chains. A dependency is not presented as proof of causation unless its evidence and confidence support that interpretation.

Domain simulation providers can plug into Neutron’s generic simulation interface. Without a compatible provider, Neutron returns a low-confidence optimistic, expected, and pessimistic envelope, declares missing domain models, and does not fabricate numerical magnitudes. Counterfactuals and simulated future states are stored separately from observations.

Outcomes and Reviewed Learning

Observed outcomes are separate from predicted consequences. Matching numerical metrics produce signed and percentage prediction errors where the baseline permits it.

Outcome recording creates an auditable learning candidate. Sensitive-domain learning requires review before activation. Activating learning appends versioned reliability evidence for relevant sources, agents, relationships, consequence models, or solvers. One observation never silently rewrites active knowledge.

Only active, reviewed learning enters later Context Engine guidance. Pending and rejected records remain available for audit.

Knowledge Snapshots

Significant decisions can capture immutable references to the exact memory, entity, relationship, claim, decision, outcome, and learning versions used at that time. A canonical digest makes the reference set reproducible without duplicating every source record.

Use snapshots for debugging, audits, evaluations, regulated workflows, and questions such as “What exactly did the system know when it made this recommendation?”

Integration Surfaces

The authenticated REST surface covers memory, entities, relationships, graph queries, context, decisions, consequences, outcomes, learning review, simulations, agents, snapshots, contradictions, and hybrid search. See the API reference.

The TypeScript SDK exposes typed memory, entities, graph, context, decisions, consequences, outcomes, learning, agents, snapshots, claims, contradictions, simulate, and search facades.

Python, PHP, Go, and Rust retain their existing typed memory and consequence workflows. Use the authenticated REST schemas for newer intelligence operations until typed parity is documented; do not assume all SDKs expose identical methods.

The focused MCP surface exposes the main memory, entity, graph, context, decision, consequence, outcome, and simulation workflows without splitting them into hundreds of narrow tools.

Safety Boundaries

• Keep provider credentials, session cookies, payment data, and private application secrets outside Neutron knowledge.
• Never persist raw chain-of-thought, hidden prompts, model scratchpads, or private reasoning.
• Treat predictions as uncertain decision support, not facts or guarantees.
• Require a recorded human approval for high-risk or irreversible actions.
• Keep external execution behind an authorised, scoped, idempotent action adapter with policy checks and a recovery plan.
• Use verified domain solvers for mathematical optimisation and retain the exact proof boundary.