Skip to main content

Module knowledge_object

sochdb_core

Module knowledge_object 

Source
Expand description

§Knowledge Object — Object-Centric Data Model for Knowledge Fabric

The KnowledgeObject is the atomic unit of the Knowledge Fabric. Unlike the tabular TOON format (which separates data, embeddings, edges, and temporal metadata across different structures), a Knowledge Object co-locates all information about a single entity:

  • Content-addressed identity: oid = BLAKE3(canonical_payload) — immutable, collision-resistant, enabling structural deduplication and content verification.
  • Embedded edges: Relationships are stored within the object, so loading an object immediately provides its connections without a separate graph lookup.
  • Multi-space embeddings: A single object can carry embeddings in multiple semantic spaces (e.g., "semantic", "code", "temporal"), enabling domain-specific similarity search without separate vector indices.
  • Bitemporal coordinates: Every object carries (valid_from, valid_to, system_time), supporting both “what was true?” (valid time) and “what did the system know?” (system time) queries.
  • Provenance chains: Hash-linked derivation tracking — every transformation records its parent OIDs, creating an auditable lineage.

§Why Co-Location Matters

In a traditional architecture, a compositional query (“find entities similar to X that are connected to Y and were valid at time T”) requires:

  1. Vector index lookup → candidate set (separate I/O)
  2. Graph traversal → filter by connectivity (separate I/O)
  3. Temporal filter → narrow by validity (separate I/O)
  4. Attribute filter → apply predicates (separate I/O)

Each boundary adds serialization, allocation, and cache misses. With co-located Knowledge Objects, the fused query executor can evaluate all predicates in a single pass, reducing latency from ~11 ms to ~300 μs (30–50× improvement).

§Relationship to TOON

Knowledge Objects wrap SochValue payloads — TOON data remains the content format. The Knowledge Object adds the metadata envelope that enables the Knowledge Fabric’s compositional queries.

§Example

ⓘ
use sochdb_core::knowledge_object::*;

let ko = KnowledgeObjectBuilder::new(ObjectKind::Entity)
    .attribute("name", SochValue::Text("Alice".into()))
    .attribute("role", SochValue::Text("engineer".into()))
    .embedding("semantic", vec![0.1, 0.2, 0.3])
    .edge(Edge::new(target_oid, EdgeKind::typed("works_at"), 1.0))
    .valid_from(1700000000_000000)
    .valid_to(u64::MAX)
    .build();

assert!(ko.oid().as_bytes().len() == 32);
assert_eq!(ko.edges().len(), 1);
assert!(ko.embedding("semantic").is_some());

Structs§

BitemporalCoord
Bitemporal versioning coordinate for a Knowledge Object.
Edge
A directed, typed, weighted, temporally-versioned edge between two Knowledge Objects.
EmbeddingSpace
An embedding vector in a named semantic space.
KnowledgeObject
The atomic unit of the Knowledge Fabric.
KnowledgeObjectBuilder
Ergonomic builder for constructing Knowledge Objects.
ObjectId
A 256-bit BLAKE3 content hash serving as the immutable identity of a Knowledge Object.
Provenance
Records how a Knowledge Object was derived.

Enums§

CompressionMode
Per-object compression strategy.
EdgeKind
The kind/type of an edge between Knowledge Objects.
KnowledgeObjectError
Errors for Knowledge Object operations.
ObjectIdError
Errors when parsing ObjectId.
ObjectKind
Classification of a Knowledge Object. Determines which indices and query optimizations apply.