Storage and schema (Kuzu)

MemState stores all durable state in embedded Kuzu through GraphStore. The adapter initializes schema idempotently and caches one KuzuGraph per resolved file path.

Storage model and schema bootstrap

  • Database path source: MEMSTATE_KUZU_PATH (default memstate.kuzu).
  • Parent directory behavior: created automatically by the adapter when missing.
  • Schema bootstrap: bootstrap_kuzu_schema() runs at store init and tolerates already-existing tables.
  • Schema version marker: MemStateMeta {key: "schema", version: "3"}.

Physical schema

Entity Type Purpose
Topic Node table Primary memory object: scalar metadata, JSON fields/history, embedding vector, archive flag.
RELATED Relationship table Explicit graph links between topics with free-form kind.
FieldHead, FieldVersion, HAS_FIELD, LATEST, PREV Legacy structures Backward compatibility path; active writes use fields_json on Topic.
MemStateMeta Node table Schema version and migration metadata.

Storage access diagram

Executor / UI API / LLM tools all call one GraphStore GraphStore topic CRUD field history append edge add/remove + KNN KuzuGraph query() / ro_query() kuzu.Connection execute path-cached handle memstate.kuzu Schema on open: Topic + RELATED + legacy tables + MemStateMeta Idempotent DDL, safe across restarts against same path

All state transitions pass through the same GraphStore facade, regardless of API surface.

Key data write patterns

Operation Store behavior Notes
Create topic create_topic() inserts scalar columns plus serialized fields_json and embedding columns. Initial topic history event (kind=created) is written.
Append field history append_field_history() prepends revision, caps history length, persists fields_json. Also re-syncs topic salience from average field salience.
Update topic metadata update_topic_meta() patches only provided columns and always updates updated_at. Used by query salience bump and UI patch endpoint.
Relationship merge add_related_edge() uses Cypher MERGE on (from,to,kind). Idempotent for repeated writes with same key.

Vector retrieval path

  1. Executor embeds query text or topic title/summary.
  2. vector_knn_topic_ids() reads candidate topic embeddings (excluding archived by default).
  3. Similarity fallback is local cosine if native vector index behavior is unavailable.
  4. Candidate lists feed query and ingest flows for topic selection or suggestions.
Operational note: cloud-synced folders can hold file locks. If health checks report lock errors, move MEMSTATE_KUZU_PATH to a non-synced path.