Data Model¶

Every memory in uniko is a node or an edge in a single property graph. There is no separate document store, vector store, or relational table sitting beside it — the graph is the memory. When the system asks "what is true now?", "where did this come from?", or "what happened in this session?", it answers by traversing edges, not by joining across systems.

This page walks the node types, the edges that connect them, and the design rule that holds the whole thing together. The names here are the real ones, registered by uniko-store when a KnowledgeBase opens; the complete property-and-index catalogue lives in Reference > Schema.

The shape of the graph¶

uniko's schema registers 24 node types and 53 edge types with the underlying uni-db graph. They are organised into layers that map onto a cognitive-memory model — episodic (what happened), semantic (what we know), procedural (what works), and the meta-memory that tracks how knowledge was derived.

The single most important design rule is this:

That spine starts at the Message.

Message anchors everything¶

A Message is the atomic unit of communication — one thing someone said. It is the node that the rest of the episodic graph hangs off. Its registered edges are deliberately few and load-bearing:

// crates/uniko-store/src/schema/messages.rs — edge registration
builder
    .edge_type(edges::SENT_BY, &[labels::MESSAGE], &[labels::PARTICIPANT])
        .property_nullable("role", DataType::String)   // "user" | "assistant" | "system" | "tool"
        .done()
    .edge_type(edges::ADDRESSED_TO, &[labels::MESSAGE], &[labels::PARTICIPANT])
        .done()
    // IN_SESSION is multi-source: Message, Action and Episode all live in a Session
    .edge_type(edges::IN_SESSION,
        &[labels::MESSAGE, labels::ACTION, labels::EPISODE],
        &[labels::SESSION])
        .done()
    .edge_type(edges::NEXT, &[labels::MESSAGE], &[labels::MESSAGE])
        .property_nullable("gap_ms", DataType::Int64)   // wall-clock gap to the next turn
        .done()

From a single Message you can reach the Participant who sent it (SENT_BY), the Session it belongs to (IN_SESSION), the chronological next turn (NEXT), and — once extraction has run — every Entity it MENTIONS. Those four anchors are enough to reconstruct a conversation, attribute statements to people, and walk time forward and back.

From messages to knowledge¶

Extraction and consolidation lift raw turns into reusable knowledge through three node types, connected by provenance edges:

• Observation — a direct claim grounded in a source. "Caroline attended an LGBTQ support group." It carries OBSERVED_IN edges to the Message or Chunk it came from, OBSERVED_DURING to the Episode, and ABOUT to the Entity (or Participant) it concerns.
• Fact — consolidated from multiple observations over time. "Caroline is pursuing adoption." A Fact links back to its evidence via SUPPORTED_BY (to Observations) and DERIVED_FROM (to the Episodes whose observations provided the evidence).
• Entity — a named thing (person, place, org, concept, tool…) that messages, chunks, actions, artifacts, and episodes all MENTIONS.

A Fact is not eternal. When new evidence contradicts an old belief, consolidation does not delete the stale fact — it records the supersession explicitly:

// crates/uniko-store/src/schema/facts.rs — the INVALIDATES edge
.edge_type(edges::INVALIDATES, &[labels::FACT], &[labels::FACT])
    .property_nullable("reason", DataType::String)
    .property_nullable("invalidated_at", DataType::DateTime)
    .done()

The invalidated Fact keeps its history; its temporal validity simply closes. Validity itself is stored on the Fact as a single valid_at property of type Btic — a half-open interval [lo, hi) with per-bound certainty and granularity — so a question like "what was true on March 15?" is answered by an interval-containment check rather than juggling separate valid_from/valid_until columns. See Facts & Drift for how BTIC drives bitemporal recall.

A representative slice¶

graph LR
    P[Participant]
    S[Session]
    M[Message]
    E[Episode]
    En[Entity]
    O[Observation]
    F[Fact]
    R[Rule]

    M -->|SENT_BY| P
    M -->|IN_SESSION| S
    M -->|NEXT| M
    M -->|MENTIONS| En
    P -->|PARTICIPATED_IN| S
    E -->|IN_SESSION| S
    E -->|MENTIONS| En
    O -->|OBSERVED_IN| M
    O -->|OBSERVED_DURING| E
    O -->|ABOUT| En
    F -->|SUPPORTED_BY| O
    F -->|DERIVED_FROM| E
    F -->|ABOUT| En
    F -->|DERIVED_BY| R
    F -->|INVALIDATES| F

The diagram shows the load-bearing core. A Message (sent by a Participant, in a Session) mentions Entitys; an Observation grounded in that message is consolidated into a Fact, which knows the Rule that derived it and the Fact it replaced.

Node types¶

A representative subset of the 24 registered node types. Each is registered by a module under crates/uniko-store/src/schema/.

Edge types¶

A representative subset of the 53 registered edge types. The full list, with source/target labels and edge properties, is in the Schema reference.

Working memory is a view, not a node¶

There is no WorkingMemory node type. Working memory is a live view computed on demand by traversing the graph outward from a Goal — its Tasks, the Episodes and Sessions for those tasks, recent Messages, the Facts derived from those episodes, the Entitys involved, and any proven Procedures. Because the answer is recomputed from edges each time, it always reflects the latest state of the graph rather than a cached snapshot.

Where to go next¶