The graph your AI
reasons over.

What it is

Cognition OS stores knowledge as a property graph and serves it back at every level a system needs: a single node, a neighbourhood, a semantic search, or a resolved set of concepts behind a sentence of free text. It is domain-agnostic — the same service backs people graphs, product-management graphs, code knowledge graphs and fully custom schemas, chosen per tenant rather than per deployment.

It never calls a language model directly. Extraction and synthesis are delegated to the Reasoning engine, which keeps the graph a clean, permissioned record of what is known — and keeps model choice out of your data layer.

Quickstart

Provision a tenant, write a node, link it, find it back.

1. Provision your tenant

One-time per application. Creates the isolated graph, its anchor node and the managed vector collections. Idempotent — safe to call on every boot.

curl -X POST https://<YOUR_COGNITION_HOST>/v1/tenants/provision \
  -H "Authorization: Bearer <YOUR_SERVICE_TOKEN>" \
  -H "X-Org-Id: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{ "tenant_id": "my-tenant", "template": "kora_hai" }'

Pass archetype to declare your own subtype tree, template to load a shipped one, or graph_type for a stock shape (product, people, code, kit, concept, custom).

2. Create a node

curl -X POST https://<YOUR_COGNITION_HOST>/v1/graphs/nodes \
  -H "X-Org-Id: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{
        "id": "concept-ml",
        "name": "Machine Learning",
        "node_type": "Concept",
        "description": "A branch of artificial intelligence",
        "graph_type": "custom",
        "graph_name": "my-graph",
        "metadata": { "source": "my-app", "seniority": "principal" }
      }'

# 201 Created
{ "id": "concept-ml", "message": "ok" }

Supplying your own id keeps identifiers stable across systems; the write merges rather than duplicating, so replays are safe. metadata is persisted as flat node properties.

3. Relate it

curl -X POST https://<YOUR_COGNITION_HOST>/v1/graphs/relationships \
  -H "X-Org-Id: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{
        "source_id": "concept-ai",
        "target_id": "concept-ml",
        "rel_type": "PARENT_OF",
        "source_label": "Concept",
        "target_label": "Concept",
        "properties": { "score": 0.91, "source": "vector_match" }
      }'

Passing source_label / target_label selects the indexed write path instead of a full scan — material on large graphs. Circular PARENT_OF / CONTAINS writes are rejected before they can corrupt the tree.

4. Search it back

curl -X POST https://<YOUR_COGNITION_HOST>/v1/search \
  -H "X-Org-Id: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{ "query": "artificial intelligence", "top_k": 10, "min_score": 0.0 }'

{ "query": "artificial intelligence",
  "results": [
    { "entity_id": "concept-ml", "score": 0.83, "title": "Machine Learning",
      "content": "A branch of artificial intelligence", "content_type": "Concept",
      "source_backend": "graph", "match_explanation": "name match" }
  ],
  "total": 1, "backends_used": ["graph"] }

Authentication

Two headers, two jobs. Most data routes need the first; administrative and reasoning routes need both.

Data model

Everything is a node with a type, or a typed relationship between two nodes.

Node

Five root primitives

Every node is rooted at exactly one of five types. Tenants don't invent roots — they declare subtypes beneath them.

Subtypes are a label chain

A subtype is written with its full ancestry, so both general and specific queries work without any schema migration:

(:Concept:Skill:SkillChain { id: "…", name: "…" })
(:Artefact:Document:Email  { id: "…", subject: "…" })
(:Artefact:ReasoningNode   { id: "…", kind: "inference" })

Match Concept and you get every skill, feature and requirement. Match SkillChain and you get exactly that. Subtype names are validated at provision time — the parent must resolve to a root or an inherited subtype, cycles are rejected, and roots cannot be redefined.

Relationship types

Edges carry properties — a match score and its source, or the reasoning step that produced it — so provenance lives on the edge itself.

Ontology & archetypes

Your graph's shape is declared, not hard-coded. An archetype composes platform ontology modules with your own subtypes, and is stored on the tenant anchor.

Declare your own subtypes in the archetype at provision time, or start from a shipped template. As patterns prove themselves across tenants, they can be promoted into the shared ontology — so the platform vocabulary grows from real usage rather than guesswork.

API reference

All paths are relative to /v1. Org marks routes needing X-Org-Id; Token marks routes needing a bearer token.

Nodes & relationships · Org

Create or merge a node. 201 with the id. Unknown node_type or graph_type returns 400.

Fetch one node; optional ?graph_name=. 404 if it isn't in your organisation's graph.

Update name and description.

Delete — soft by default; ?soft=false removes outright. 204.

Typed edge with optional properties. Cycle detection guards PARENT_OF and CONTAINS.

Remove a specific edge.

Outgoing neighbours — the primitive behind graph-augmented recall.

Node and edge counts for your graph.

Create or fetch the tenant anchor.

Bulk & dedup · Org

One request per node is the slow path. Two endpoints exist for volume.

{
  "graph_type": "custom",
  "graph_name": "my-graph",
  "nodes": [
    { "id": "svc-1", "name": "Billing",   "node_type": "Module" },
    { "id": "svc-2", "name": "Invoicing", "node_type": "Module" }
  ]
}

# 201 Created
{ "ids": ["svc-1", "svc-2"], "count": 2, "message": "ok" }

Graph-level fields sit on the envelope; each row carries only its own data. Writes merge, so a replayed batch converges rather than duplicating. An invalid row fails that row with a 400.

Collapse duplicate nodes sharing an id. Idempotent — a clean graph reports zero removed. Always dry-run first:

{ "graph_name": "my-graph", "dry_run": true, "batch_size": 100 }

{ "dry_run": true, "graph_name": "my-graph",
  "results": [ { "label": "Concept", "dup_groups": 3, "extra_rows": 11, "removed": 0 } ] }

Omit label to sweep every type. batch_size and an iteration cap keep each pass bounded on very large graphs.

Entity search · Org

Archetype-aware. The request carries no labels and no relationship names — your tenant's archetype supplies them. The same call finds people in a people graph, features in a product graph, or components in a code graph.

{ "target_concepts": ["kubernetes", "postgres"],
  "strong_anchors":  ["kubernetes"],
  "top_k": 10,
  "return_properties": ["name", "seniority"] }

Results are ranked by anchor coverage — how many of the concepts an entity actually connects to, weighted with average confidence and breadth — so a match on two of your three concepts outranks a strong match on one. Custom graphs may pass entity_types and via_relationship explicitly.

Concepts & resolution · Org

Add a concept, optionally under parent_id, with knowledge_domain and confidence.

Case-insensitive name search.

The query-understanding call. Free text in, anchored concepts out, through a three-tier cascade:

Returns { anchors, strong_anchors, neighbours, discoveries, all_concepts }. Each tier fails soft, so one backend being down still returns useful matches. Query strings are always parameters, never interpolated into the graph query.

Semantic search — returns concept_id, name, node_type, score.

Index one entity or many — batch returns { "indexed": n, "failed": n } — and remove entities from the vector collections.

Unified search · Org

One query across graph, vector and full-text backends, fused and ranked. Takes query, top_k, min_score and arbitrary filters. Every result carries the source_backend that produced it and a match_explanation — so you can show a user why something matched. The response reports backends_used.

Reasoning & provenance · Token

Record why the graph looks the way it does — a directed acyclic Graph of Thought, with node kinds of observation, inference, decision, question and answer.

Ask any entity what produced it — creations, updates, merges, splits and links are all linked back to the reasoning that caused them.

Design decisions carry context, rationale, alternatives considered and a lifecycle status.

Semantic search over reasoning chains.

Documents & tasks · Token

Submit a document for asynchronous cognitive processing — extraction, structuring, integration and validation. Returns a task id.

Poll the task, or subscribe over WebSocket for live progress.

Tenants · Token

Idempotent. Accepts archetype (your own subtype tree), template (a shipped one), or graph_type (a stock shape).

Access control · Token

Beyond tenant isolation, individual embeddings carry access levels — public, internal, confidential, restricted — and per-principal grants.

Permission-filtered search — results a principal may not see are never returned, rather than filtered in your application.

Agents, review & dead letters

Housekeeping agents · Org

Run the full batch with change detection, or name a subset. Six agents keep the graph coherent:

Each agent runs under its own timeout, so one hung agent can't block the scheduler.

Human review · Token + Org

Extractions below the confidence threshold are staged rather than written into the graph. Reviewers triage them:

Dead letter queue

A failed event handler publishes to a dead-letter topic instead of vanishing. Triage and replay:

Analyzers & sync · Token

Ingestion pipeline

Submitting a document runs a four-agent pipeline — Scribe extracts, Architect structures, Synthesizer integrates, Interrogator validates — alongside a four-phase progressive extraction: entities, then relationships, then hierarchy, then quality validation.

Everything then passes a confidence gate. High-confidence output is written to the graph and indexed for vector and full-text search. Low-confidence output is staged for human review instead of being written blind — the difference between a graph you can trust and one that slowly fills with plausible noise.

Events

State changes publish to an event bus you can subscribe to, in-process or distributed:

Reliability

Errors

Your data

Cognition OS stores the nodes and relationships you write, their metadata, and the embeddings computed for semantic search. Content is indexed into a vector store and a full-text index alongside the graph, so a single write produces derived copies used for retrieval.

Isolation is by organisation and enforced beneath the query layer — every tenant-scoped read carries an organisation filter, so a request cannot read across organisations. Embeddings additionally carry access levels and per-principal grants, and permission-filtered search honours them server-side. Because housekeeping mutates your graph, every change is recorded and attributable. Retention and erasure are set out in the privacy policy.

Availability & access

Cognition OS ships as part of the SeKondBrain platform. It is licensed, not open source: you buy the platform and integrate the graph into your own stack, with your organisation's data isolated and provisioned for you. It already runs in production behind our own products — what you integrate is proven, not a prototype.

Where it runs

What you get when you're set up