Intent Graph Kernel - Allternit Docs

Overview

The Allternit Intent Graph Kernel (IGK) is a durable, queryable graph database for intent, work, and memory. It stores typed nodes (intents, tasks, goals, decisions, plans, artifacts, and memories) and typed edges that describe how those nodes relate to one another. Every mutation is recorded as a provenance event, so the graph remains auditable and reproducible over time. IGK is designed as the substrate for higher-level projections:

UI projections — render boards, canvases, and agent workspaces from live graph state.
Context projections — assemble token-bounded context windows for agent reasoning.
Memory projections — surface now / next / later views of active and pending work.

The kernel is implemented as the Rust crate intent-graph-kernel (domains/kernel/allternit-intent-graph-kernel/) and exposes a standalone HTTP service on port 3120 by default. Status: Implementation IMPLEMENTED × Exposure — . The crate and its service exist and are tested, but on main nothing in the platform API, the cloud API or the UI calls it yet, and it is not part of the hosted deployment. The projections listed above are its design purpose, not live product features.

How this relates to the Agency Kernel

IGK is not part of the Agency Kernel’s run path. The kernel keeps its own run-level state; IGK is the long-lived layer that could inform runs. See Architecture for the kernel itself.

How IGK relates to run state

IGK sits above the run. It holds what persists across runs; the kernel’s run-level records hold what one run knows and does.

Store	Is the store for	Is not the store for
Intent Graph Kernel	Long-lived intent, knowledge and memory across runs, and the projections built from them	The state of any one run, or where a node is in its lifecycle
TaskIR and AgentState	What one run was asked to do, and its canonical semantic truth (facts, hypotheses, artifacts, verification, completion)	Long-lived knowledge, or lease and attempt bookkeeping
ComputeGraphIR	The executable plan for one run: nodes, edges, capabilities, levels	Whether a node is running right now
Work runtime ledger	Operational lifecycle: node status, leases, heartbeats, attempts, outputs, receipts	Semantic truth about the task or long-lived knowledge

Information flows down. The Intent Graph Kernel informs a run; it does not drive it.

Core invariants

IGK enforces four design invariants that keep agent reasoning grounded:

Invariant	Meaning
Single Reality	No branching or forking. Each real-world entity maps to exactly one node.
Append-Only Provenance	Every change is appended as an event. History is never overwritten.
Policy-Gated Mutation	AI or automation proposes mutations; policy decides whether to commit them.
No Silent State	Every state change must be citeable to a source object or policy decision.

These invariants make IGK suitable for agent systems where accountability and reproducibility matter as much as throughput.

Key concepts

Nodes

A node is the primary entity in the graph. Each node carries a UUID, type, status, priority, owner, source references, and arbitrary JSON attributes.

Node type	Purpose
`intent`	Something a user or agent wants to accomplish.
`task`	A concrete unit of work to be executed.
`goal`	A high-level objective that groups intents and tasks.
`decision`	A resolved or unresolved decision point.
`plan`	An execution plan composed of ordered steps.
`artifact`	A produced file, document, or output.
`memory`	A persistent memory fragment.

Node statuses

Status	Meaning
`proposed`	Suggested but not yet committed.
`active`	Committed and in progress.
`completed`	Finished successfully.
`deprecated`	Replaced or no longer relevant.

Edges

Edges connect nodes and describe semantic relationships.

Edge type	Meaning
`depends_on`	The source node depends on the target node.
`blocks`	The source node blocks the target node.
`part_of`	The source node is a component of the target node.
`implements`	The source node implements the target node.
`context_for`	The source node provides context for the target node.

Source references

Every node can cite one or more SourceRef objects that point back to the origin of the information. A source reference has a kind (for example, file, message, or ledger_event), a locator, an optional excerpt, and an optional content hash. Source refs make it possible to answer “where did this come from?” for any node in the graph.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Allternit surfaces                          │
│   Boards · Canvases · Agent workspaces · Context windows        │
└─────────────────────────────────┬───────────────────────────────┘
                                  │
          ┌───────────────────────┼───────────────────────┐
          │                       │                       │
          ▼                       ▼                       ▼
┌─────────────────┐   ┌──────────────────┐   ┌──────────────────┐
│  UI projection  │   │ Context projection│   │Memory projection │
│    engine       │   │     engine        │   │     engine       │
└────────┬────────┘   └────────┬─────────┘   └────────┬─────────┘
         │                     │                      │
         └─────────────────────┼──────────────────────┘
                               │
                    ┌──────────▼──────────┐
                    │    QueryEngine      │
                    │   MutationEngine    │
                    │  ProjectionEngine   │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │      Storage        │
                    │   (SQLite + sqlx)   │
                    └──────────┬──────────┘
                               │
         ┌─────────────────────┼─────────────────────┐
         │                     │                     │
         ▼                     ▼                     ▼
┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐
│  nodes          │   │  edges          │   │  events         │
│  intent graph   │   │  relationships  │   │  provenance log │
└─────────────────┘   └─────────────────┘   └─────────────────┘

Storage layer

IGK persists data in three SQLite tables:

nodes — stores the typed intent graph nodes.
edges — stores directed relationships between nodes.
events — stores an append-only log of every mutation, including actor, action, target, before/after state, and optional policy decision.

The schema is created automatically by the migration at migrations/001_init.sql when the service starts.

Engines

Engine	Responsibility
`QueryEngine`	Fetch nodes, search by type/owner, and retrieve subgraphs.
`MutationEngine`	Propose and commit node/edge creations with provenance events.
`ProjectionEngine`	Compute temporal views (`now` / `next` / `later`) and token-bounded context windows.

Running the service

The kernel service reads the database path from IGK_DB_PATH and listens on HOST/PORT.

export IGK_DB_PATH=./igk.db
export HOST=127.0.0.1
export PORT=3120

cargo run -p intent-graph-kernel

On startup the service applies migrations, then serves an Axum router on http://127.0.0.1:3120.

HTTP API

Endpoints

Method	Path	Description
`GET`	`/health`	Service health check.
`GET`	`/nodes/:id`	Retrieve a node by UUID.
`POST`	`/nodes`	Create a new node.
`POST`	`/edges`	Create a new edge between nodes.
`POST`	`/query/subgraph`	Query the subgraph rooted at a node.
`POST`	`/query/projections`	Compute temporal projections for a root node.
`POST`	`/context/window`	Build a token-bounded context window.

Create a node

curl -X POST http://127.0.0.1:3120/nodes \
  -H "Content-Type: application/json" \
  -d '{
    "node_type": "goal",
    "priority": 10,
    "owner": "orchestrator",
    "source_refs": [
      {
        "kind": "message",
        "locator": "thread:abc123",
        "excerpt": "Refactor the checkout module",
        "hash": null
      }
    ],
    "attributes": {
      "title": "Refactor checkout",
      "description": "Split the monolithic checkout module into smaller services."
    },
    "policy_decision": "approved"
  }'

{
  "node_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created"
}

Create an edge

curl -X POST http://127.0.0.1:3120/edges \
  -H "Content-Type: application/json" \
  -d '{
    "from_node_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to_node_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "edge_type": "depends_on",
    "metadata": {"reason": "checkout depends on payment service"},
    "policy_decision": "approved"
  }'

Query a subgraph

curl -X POST http://127.0.0.1:3120/query/subgraph \
  -H "Content-Type: application/json" \
  -d '{
    "root_node_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "depth": 3
  }'

{
  "node": { "node_id": "...", "node_type": "goal", ... },
  "edges": [ ... ],
  "edge_count": 2
}

Compute projections

curl -X POST http://127.0.0.1:3120/query/projections \
  -H "Content-Type: application/json" \
  -d '{
    "root_node_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

{
  "now": 1,
  "next": 3,
  "later": 5
}

Build a context window

curl -X POST http://127.0.0.1:3120/context/window \
  -H "Content-Type: application/json" \
  -d '{
    "root_node_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "token_budget": 4096
  }'

{
  "token_count": 1820,
  "budget": 4096,
  "within_budget": true,
  "node_count": 4
}

Using the Rust crate

Add the dependency

[dependencies]
intent-graph-kernel = { path = "domains/kernel/allternit-intent-graph-kernel/allternit-intent-graph-kernel" }

Create a node with policy-gated mutation

use intent_graph_kernel::{
    Node, NodeType, NodeStatus, SourceRef,
    mutation::MutationEngine,
    storage::Storage,
};
use uuid::Uuid;
use chrono::Utc;

let storage = Storage::new(pool.clone());
let mutation = MutationEngine::new(storage);

let node = Node {
    node_id: Uuid::new_v4(),
    node_type: NodeType::Intent,
    status: NodeStatus::Proposed,
    priority: 5,
    owner: "builder-agent".to_string(),
    source_refs: vec![SourceRef {
        kind: "file".to_string(),
        locator: "src/checkout.rs:42".to_string(),
        excerpt: Some("Payment validation is duplicated here.".to_string()),
        hash: None,
    }],
    attributes: serde_json::json!({
        "title": "Deduplicate payment validation",
        "effort": "small"
    }),
    created_at: Utc::now(),
    updated_at: Utc::now(),
};

let event = mutation
    .commit_create_node(&node, "builder-agent", Some("approved".to_string()))
    .await?;

Query nodes

use intent_graph_kernel::query::QueryEngine;
use intent_graph_kernel::schema::NodeType;

let query = QueryEngine::new(storage);
let intents = query
    .search_nodes(Some(NodeType::Intent), Some("builder-agent"), Some(10))
    .await?;

Compute temporal projections

use intent_graph_kernel::projection::ProjectionEngine;

let projection = ProjectionEngine::new(storage);
let views = projection
    .compute_temporal_projections(&root_node_id)
    .await?;

for node in views.now {
    println!("now: {:?}", node.attributes);
}

Policy-gated mutation

IGK distinguishes between proposing and committing a mutation. The mutation engine can mark a node as requiring policy approval based on its type (intent and goal require policy by default). When a policy decision is supplied, the commit path writes both the node/edge and a provenance event that records the decision.

AI proposes mutation
        │
        ▼
┌───────────────┐
│ Policy engine │
│ evaluates risk│
└───────┬───────┘
        │
   approved / denied
        │
        ▼
┌───────────────┐
│ MutationEngine│
│ commits node  │
│ + event       │
└───────────────┘

This design lets autonomous agents plan freely while keeping consequential changes under explicit policy control.

Projections

Temporal projections

The projection engine divides nodes into three buckets relative to a root node:

now — the root node itself plus anything updated within the last hour.
next — nodes updated recently but not directly under the root.
later — everything else.

Temporal projections are useful for surfacing “what needs my attention right now?” in agent UIs.

Context windows

A context window is a ContextSlice composed of root nodes, selected edges, source references, and a token budget. The projection engine estimates token usage from node attributes and source excerpts, then returns the subset that fits within budget.

use intent_graph_kernel::schema::ContextSlice;

let slice = ContextSlice {
    root_nodes: vec![root_node_id],
    edges: vec![edge_id],
    sources: vec![source_ref],
    token_budget: 4096,
};

let window = projection.compute_context_window(&slice).await?;
assert!(window.within_budget);

Error handling

IGK operations return IGKError:

Variant	Meaning
`Database`	SQLite or `sqlx` failure.
`Serialization`	JSON serialization/deserialization failure.
`NodeNotFound`	Requested node does not exist.
`PolicyViolation`	Mutation rejected by policy.
`DuplicateNode`	Attempted to create a node that already exists.
`Internal`	Unexpected internal error.

HTTP endpoints translate these into standard status codes: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, and 500 Internal Server Error.

Configuration

Environment variable	Default	Description
`IGK_DB_PATH`	`igk.db`	SQLite database file.
`HOST`	`127.0.0.1`	Bind address.
`PORT`	`3120`	Listen port.

Gizzi Runtime
Gizzi Core
Allternit Factory
Memory Fabric
Orchestration
Session Manager
Living Agent Architecture: how the Intent Graph Kernel maps onto the agent kernel planes
Canonical Computer Use

​Overview

​How this relates to the Agency Kernel

​How IGK relates to run state

​Core invariants

​Key concepts

​Nodes

​Node statuses

​Edges

​Source references

​Architecture

​Storage layer

​Engines

​Running the service

​HTTP API

​Endpoints

​Create a node

​Create an edge

​Query a subgraph

​Compute projections

​Build a context window

​Using the Rust crate

​Add the dependency

​Create a node with policy-gated mutation

​Query nodes

​Compute temporal projections

​Policy-gated mutation

​Projections

​Temporal projections

​Context windows

​Error handling

​Configuration

​Related docs