Author note, 2 September 2026, Jason DoyleThis project began as a feature forked from a private project and is now maintained independently as open source. The documentation is heavily AI assisted and may contain errors. Verify important behavior against the implementation, tests, and current release before using it in production.
Open source data infrastructure for long-running software agents.
Agentic Data Kernel keeps knowledge, workflow state, and external effects in a single governed system. It is designed for applications that need to answer:
-
What is currently known?
-
When was it valid?
-
Where did it come from?
-
What conflicts with it?
-
Which workflow or external action depended on it?
-
Bitemporal assertions with evidence, epistemic kind, perspective, and typed uncertainty
-
Explicit
known
,unknown
, andconflicted
resolution results - Hybrid lexical, vector, relational, graph, and temporal retrieval
- Durable workflow state, timers, idempotency, and execution receipts
- Transactional inventory reservations and payment effect intents
- Scoped API keys, purpose binding, and PostgreSQL row-level security
- Encrypted immutable artifact storage with key rotation
- Authorized effect delivery with budgets, retries, and status reconciliation
- HTTP, MCP, TypeScript, CLI, and read-only local SQL interfaces
| Use case | What the kernel provides |
|---|---|
| Catalog and master-data reconciliation | Source-backed claims, conflicting values, temporal correction, and reviewable resolution |
| Persistent agent memory | Distinct observations, facts, inferences, decisions, and experiences with provenance |
| Retail order workflows | Inventory holds, expiry timers, payment effects, idempotent retries, and durable order state |
| Customer support operations | Tenant-scoped context retrieval, current-state checks, and evidence-linked decisions |
| Incident response | Temporal observations, hypotheses, workflow history, and controlled remediation effects |
| Controlled payment automation | Purpose-scoped credentials, effect budgets, authorization fences, and audit receipts |
See docs/USE_CASES.md for detailed flows and current support.
The current release is 0.2.0-alpha.1
.
Two runtime profiles are maintained:
Development profile: embedded SQLite, loopback HTTP, local MCP, and read-only SQL for inspection.PostgreSQL profile: PostgreSQL 18, pgvector, forced tenant isolation, authenticated APIs, encrypted artifacts, provider embeddings, effect workers, TLS, migrations, metrics, backup, restore, and load tooling.
The PostgreSQL profile targets bounded single-primary deployments. See docs/PRODUCTION.md before exposing it outside a trusted environment.
Install the TypeScript library:
npm install agentic-data-kernel@next
Run the embedded example without cloning the repository:
npx --yes agentic-data-kernel@next example --db .data\example.db
Published prereleases use the npm next
tag. Production applications should pin an exact package version.
import { AgenticKernel, SqliteStore } from "agentic-data-kernel";
const store = new SqliteStore(".data/app.db");
const kernel = new AgenticKernel(store);
The npm package provides:
agentic-data-kernel
andagentic-data
for the embedded CLI;agentic-data-prod
for production administration and runtime commands;agentic-data-kernel/production
for PostgreSQL integrations.
Requirements:
- Node.js 22.19 or newer
- npm 10 or newer
npm install
npm run build
npm test
npm run example
The sample workflow:
- stores conflicting supplier claims about a product;
- preserves both claims and returns an explicit conflict;
- searches across a customer, product, and incident graph;
- reserves inventory transactionally;
- creates a durable payment effect;
- records the provider outcome;
- confirms the order without duplicating inventory changes on replay.
The sample database is written to .data\example.db
.
Node's built-in node:sqlite
API is experimental in Node 22. This affects only the development profile.
Build:
npm run build
Initialize a database:
node --no-warnings dist\cli.js init --db .data\agentic.db
Execute an operation:
node --no-warnings dist\cli.js execute `
--db .data\agentic.db `
--file examples\put-product.json
Inspect state with read-only SQL:
node --no-warnings dist\cli.js sql `
--db .data\agentic.db `
--query "SELECT assertion_id, predicate, status FROM assertions"
The SQL interface accepts SELECT
, EXPLAIN
, and schema-inspection PRAGMAs.
npm run serve
Default address: http://127.0.0.1:4318
| Route | Purpose |
|---|---|
GET /health |
|
| Liveness | |
GET /v1/catalog |
|
| Supported operations and guarantees | |
POST /v1/execute |
|
| Execute one Agent Intent operation |
The development server is loopback-only and has no network SQL route.
Start the development MCP server from a published package:
npx --yes agentic-data-kernel@next mcp --db .data\agentic.db
Or start it from a source checkout:
npm run mcp
It publishes agentic-data://catalog
and these tools:
execute_intent
search_knowledge
resolve_claims
reserve_inventory
get_machine
Use npm run prod:mcp
for an authenticated PostgreSQL-backed MCP process.
| Example | Command |
|---|---|
| TypeScript library | npm run example:library |
| MCP client | npm run example:mcp |
| Authenticated production HTTP | npm run example:production-http |
| Production retail workflow | npm run example:production-retail |
| Embedding provider | npm run example:embedding |
| Embedding protocol helper | npm run example:mock-embeddings |
| Effect receiver contract | npm run example:mock-effects |
Setup, environment variables, and receiver contracts are documented in docs/INTEGRATIONS.md.
Requirements:
- Docker with Compose
- An OpenAI-compatible 1536-dimensional embedding endpoint
- Generated database, authentication, and artifact-encryption secrets
Use the versioned production image:
Copy-Item .env.example .env
.\scripts\generate-secrets.ps1
$env:AGENTIC_DATA_IMAGE = "ghcr.io/jason-doyle/agentic-data-kernel:0.2.0-alpha.1"
docker compose --profile server pull
docker compose --profile server up --no-build
Or build the image from the checked-out source:
Copy-Item .env.example .env
.\scripts\generate-secrets.ps1
docker compose --profile server up --build
The included deployment:
- creates a non-superuser runtime database role;
- applies checksum-verified migrations separately;
- initializes artifact-directory ownership;
- runs the API and effect worker independently;
- publishes only the Caddy TLS endpoint;
- keeps PostgreSQL bound to loopback by default.
Full setup and operating procedures are in docs/PRODUCTION.md.
Version 0.1 executes one typed operation per envelope:
{
"protocolVersion": "0.1",
"requestId": "claim-1",
"idempotencyKey": "claim-1",
"principal": {
"tenantId": "example-retail",
"principalId": "catalog-agent",
"purpose": "catalog-ingestion"
},
"operation": {
"op": "assert",
"assertion": {
"subjectEntityId": "product:sku-17",
"predicate": "packaged_weight",
"object": {
"type": "number",
"value": 4.8,
"unit": "kg"
},
"kind": "reported_fact",
"strength": {
"type": "rank",
"value": "normal"
}
}
}
}
The production server derives authority from the authenticated API key and rejects envelopes whose tenant, principal, or purpose does not match.
HTTP / MCP / TypeScript / CLI
|
Agent Intent validation
|
identity, scope, purpose
|
knowledge + workflow kernel
| assertions and evidence
| conflict resolution
| hybrid retrieval
| timers and state machines
| effects and receipts
|
SQLite development adapter
or
PostgreSQL + pgvector + RLS
Use casesBenefits and tradeoffsIntegration guideAPI referenceProduction profileRelease processThreat modelSecurity policyContributingSupportCode of conductChangelog
- The included deployment uses one PostgreSQL primary.
- The default rate limiter is process-local.
- The vector schema currently requires 1536-dimensional embeddings.
- Effect receivers must honor idempotency keys.
- Projection epochs, multi-operation plans, and context-package optimization are not yet implemented.
Apache-2.0. See LICENSE.