Crate grit_core 

grit-core

An embedded, bi-temporal property graph for agent memory: one SQLite file, in-process, deterministic. See AGENTS.md at the repo root for the full design contract; the short version:

• All writes are GraphOps appended to an op-log; graph tables are derived state applied in the same transaction (sync-ready by design).
• Facts are never mutated in place. Edges carry two timelines — event time (valid_at/invalid_at) and system time (created_at/expired_at) — so “what did I believe in March?” is a query, not archaeology.
• No LLM, no network, no embedding computation. Time is injected via Clock; embeddings are stored, never created.

Example

use grit_core::{Budget, GraphOp, Grit, Options, Query, Traversal};
let g = Grit::open(&path, Options::new("device-a"))?;

let yoneda = g.new_id();
let functor = g.new_id();
g.apply(GraphOp::AddNode {
    id: yoneda,
    kind: "concept".into(),
    name: "Yoneda lemma".into(),
    summary: "Objects are determined by their relationships".into(),
    attrs: serde_json::json!({}),
    group_id: "category-theory".into(),
})?;
g.apply(GraphOp::AddNode {
    id: functor,
    kind: "concept".into(),
    name: "Functor".into(),
    summary: "Structure-preserving map between categories".into(),
    attrs: serde_json::json!({}),
    group_id: "category-theory".into(),
})?;
g.apply(GraphOp::AddEdge {
    id: g.new_id(),
    src: yoneda,
    dst: functor,
    rel: "STATED_IN_TERMS_OF".into(),
    fact: "The Yoneda lemma is stated in terms of hom-functors".into(),
    attrs: serde_json::json!({}),
    group_id: "category-theory".into(),
    valid_at: None,
    invalid_at: None,
})?;

let hits = g.search(
    Query::text("yoneda").group("category-theory").budget(Budget::items(10)),
)?;
assert!(!hits.is_empty());

let ctx = g.traverse(&[yoneda], &Traversal::default())?;
assert_eq!(ctx.nodes.len(), 2);

Structs

Edge

A fact edge as stored (the “fat edge”).

Episode

A provenance episode as stored.

Grit

Handle to one grit database: a writer actor plus a read connection.

Hlc

A single hybrid-logical-clock reading.

HlcGenerator

Issues monotonically increasing HLCs for one device, folding in the highest HLC observed from remote ops so causality survives clock skew.

ImportStats

Counts of what an import inserted.

ManualClock

A deterministic, manually-advanced clock for tests and simulations.

MergeCandidate

A scored suggestion from Grit::find_merge_candidates. Grit never merges on its own — deciding is Layer 2’s LLM-judgment call; grit only scores.

Node

An entity node as stored.

NodeHistory

Bi-temporal audit trail for one node: every incident edge row ever believed, including invalidated and expired ones, oldest belief first.

OplogEntry

One row of the oplog: an op plus its global identity and merge metadata. This is the unit a future sync mechanism ships between devices.

Options

Open-time configuration for Grit.

Query

A hybrid search request. Build with Query::text, refine with the builder methods, execute with Grit::search.

SearchHit

One fused search result with provenance.

Stats

Row counts, as reported by Grit::stats.

Subgraph

A connected fragment returned by traversal: nodes plus the edges that connect them, all valid at the requested instant.

SystemClock

The real system clock. This is the caller’s choice of default — grit itself only ever sees the trait.

Traversal

Parameters for Grit::traverse. Default gives depth 3 (the AGENTS.md default bound), both timelines evaluated “now”, no group filter.

Enums

Budget

How much context to return (Layer 3 asks for “context that fits”).

Error

Everything that can go wrong inside grit-core.

GraphOp

A single append-only write. See module docs.

SearchKind

Result kinds a Query may be restricted to (see Query::targets).

SearchTarget

What a search hit points at.

Constants

SCHEMA_VERSION

The schema version this build reads and writes.

Traits

Clock

A source of wall-clock time. Injected into crate::Grit via crate::Options; tests inject ManualClock for full determinism.

Functions

import_jsonl

Load a JSONL export into a fresh database file at db_path (errors if the file already contains data — imports never merge). FTS mirrors are rebuilt by the schema triggers as rows insert.

Type Aliases

Result

Convenience alias used across the crate.

TimestampMs

Milliseconds since the Unix epoch, UTC.