Domain Model - Meerkat

Use this page to locate a record and understand its relationships to other records. Start with the knowledge model for the conceptual explanation, or the HTTP reference for request bodies and response envelopes.

Reader question	Record family
Where did this information come from?	`Source`, `Doc`, `DocRevision`, `DocNode`, `Assertion`
Which thing and which claim does it describe?	`Entity`, `Rel`, `Attribute`, `Event`
How were competing claims reconciled?	`ConflictGroup`, `TruthSlot`, `PredicateRegistry`
Why did processing stop or retry?	`WorkItem`, `WorkRun`, `WorkArtifact`
Which compiled view is the reader seeing?	`KnowledgeView`, `KnowledgeViewRevision`, `KnowledgeViewDefinition`
What access and provenance apply?	`BaseFields`, `Security`, `Provenance`

The Rust excerpts below omit serialization annotations and selected supporting fields. They are not request templates: API JSON generally flattens BaseFields into the record, serializes links as record ID strings, and uses snake-case enum values. Use the corresponding endpoint schema when constructing a request.

RecordId System

Every record in Meerkat Recall is identified by a RecordId — a typed Meerkat Recall record identifier with the format table:uuid (for example, entity:550e8400-e29b-41d4-a716-446655440000).

pub struct RecordId {
    pub table: TableName,
    pub id: Uuid,
}

New IDs are created with RecordId::new_v4(table) (random) or RecordId::new_v7(table) (time-ordered). The table component is drawn from the TableName enum, which lists every core table in the system.

TableName Enum

Table Name	Variant	Description
`entity`	`Entity`	People, orgs, apps, topics — the graph nodes
`rel`	`Rel`	Entity-to-entity relationships
`attribute`	`Attribute`	Entity-to-literal claims
`doc`	`Doc`	Ingested documents
`media_asset`	`MediaAsset`	Managed media bytes and metadata
`doc_revision`	`DocRevision`	Immutable rendered text snapshots
`doc_node`	`DocNode`	Structural chunks within a revision
`doc_chunk`	`DocChunk`	Legacy document chunks; active code uses `doc_node`
`chunk_embedding`	`ChunkEmbedding`	Vector embeddings for document nodes
`assertion`	`Assertion`	Evidence-bearing claims with resolution state and preserved mention strings
`truth_slot`	`TruthSlot`	Derived current claim selection for a slot
`conflict_group`	`ConflictGroup`	Competing claims grouped for resolution
`source`	`Source`	Provenance records (email, web, file, etc.)
`work_item`	`WorkItem`	Durable work queue items
`work_item_archive`	`WorkItemArchive`	Cold terminal work history
`work_edge`	`WorkEdge`	DAG dependencies between work items
`work_run`	`WorkRun`	Individual execution attempts
`work_run_archive`	`WorkRunArchive`	Cold completed execution history
`work_artifact`	`WorkArtifact`	Staged outputs from work runs
`work_deadletter`	`WorkDeadletter`	Failed items for operator review
`predicate_registry`	`PredicateRegistry`	Canonical predicate vocabulary
`predicate_alias`	`PredicateAlias`	Alias mappings for predicates
`space_config`	`SpaceConfig`	Per-space embedding and extraction config
`system_event`	`SystemEvent`	Outbox events with monotonic sequence
`event`	`Event`	Domain timeline events
`audit_log`	`AuditLog`	Immutable audit trail
`entity_identity_key`	`EntityIdentityKey`	Stable identity keys for entities
`identity_candidate`	`IdentityCandidate`	Proposed entity merge candidates
`entity_merge`	`EntityMerge`	Entity merge lineage
`rel_evidence`	`RelEvidence`	Evidence linking rels to sources
`id_map`	`IdMap`	Legacy ID mappings
`ingest_decision`	`IngestDecision`	Deduplication decisions during ingest
`cost_ledger_daily`	`CostLedgerDaily`	Daily cost tracking
`freshness`	`Freshness`	Freshness scores for staleness detection
`reprocess_job`	`ReprocessJob`	Backfill and re-extraction jobs
`knowledge_view`	`KnowledgeView`	Stable identity and lifecycle for a derived view
`knowledge_view_revision`	`KnowledgeViewRevision`	Immutable compiled view revision
`knowledge_view_definition`	`KnowledgeViewDefinition`	Governed typed definition of a graph-derived view
`knowledge_view_dependency`	`KnowledgeViewDependency`	Reverse dependency used for view invalidation
`source_watch`	`SourceWatch`	Durable refresh policy for a remote source
`source_watch_check`	`SourceWatchCheck`	Receipt for one remote source observation

The derived view and watch records are described in Living Wiki architecture. Cold work history keeps the original public IDs; see work queue history.

Link<T>

Link<T> is a typed foreign-key reference to another record. The generic parameter T indicates the expected target type for compile-time safety, while the underlying storage is a RecordId.

pub struct Link<T> {
    pub id: RecordId,
    // PhantomData<T> for type safety
}

Use link.id() to read the underlying RecordId, or link.into_id() to consume it.

BaseFields

Every core record embeds BaseFields, which carries identity, multi-tenancy, timestamps, provenance, security, and subject scoping.

pub struct BaseFields {
    pub id: RecordId,
    pub space_id: String,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    pub created_by: String,
    pub deleted_at: Option<DateTime<Utc>>,
    pub provenance: Provenance,
    pub security: Security,
    pub subjects: Vec<Link<Entity>>,
    pub subjects_state: SubjectsState,
}

Field	Purpose
`id`	Unique `RecordId` for this record.
`space_id`	Multi-tenant scope, such as a workspace, project, or organization.
`created_at` / `updated_at`	Lifecycle timestamps.
`created_by`	Agent or service that created the record.
`deleted_at`	Soft-delete marker. `None` when active.
`provenance`	Source chain, extractor metadata, and work run linkage.
`security`	ABAC labels: `policy_id`, `level`, `labels`, `handling`.
`subjects`	Entity links for subject-scoped access control.
`subjects_state`	Whether subjects are `complete`, `partial`, or `unknown`.

Soft-delete marks a record without removing its stored representation. Ordinary reads filter deleted records; explicit history, recovery, or include_deleted reads may expose them when authorized. Retention and purge are separate operations. Do not use a soft-delete marker as a data-erasure guarantee.

Provenance

pub struct Provenance {
    pub sources: Vec<RecordId>,
    pub extractor: Option<Extractor>,
    pub work_run_id: Option<RecordId>,
    pub run_id: Option<String>,
    pub prompt_id: Option<String>,
    pub config_id: Option<String>,
    pub chain: Vec<ProvenanceStep>,
}

Security (ABAC Envelope)

pub struct Security {
    pub policy_id: String,
    pub level: i32,
    pub labels: Vec<String>,
    pub handling: Vec<String>,
}

Knowledge Graph Records

Entity

Core nodes in the knowledge graph. Entity types are freeform lowercase strings (e.g., person, org, topic, app).

pub struct Entity {
    pub base: BaseFields,
    pub entity_type: EntityType,       // freeform string, e.g. "person"
    pub display_name: String,
    pub aliases: Vec<String>,
    pub summary: Option<String>,
    pub handles: Vec<Handle>,
    pub identity_keys: Vec<String>,
    pub risk_level: Option<f64>,
    pub trust_level: Option<f64>,
    pub known_safe: bool,
    pub first_seen: Option<DateTime<Utc>>,
    pub last_seen: Option<DateTime<Utc>>,
    pub status: EntityStatus,          // Active | Merged
    pub redirect_to: Option<Link<Entity>>,
    pub metadata: Value,
}

When an entity is merged, status becomes Merged and redirect_to points to the surviving entity.

Rel

Entity-to-entity relationships. The subject (“from”) and object (“to”) are both entity links.

pub struct Rel {
    pub base: BaseFields,
    pub subject: Link<Entity>,         // "in" side
    pub object: Link<Entity>,          // "out" side
    pub rel_type: String,              // canonical predicate
    pub status: ClaimStatus,           // Candidate | Approved | Superseded | Disputed
    pub confidence: f32,
    pub validity_window: Option<ValidityWindow>,
    pub evidence: Vec<EvidenceRef>,
    pub temporal_audit: Option<TemporalAudit>,
}

ClaimStatus tracks the lifecycle from initial candidate through promotion to approved status. ValidityWindow models temporal claims with optional start/end bounds.

Attribute

Entity-to-literal claims. Like Rel, but the object is a typed Literal value rather than an entity.

pub struct Attribute {
    pub base: BaseFields,
    pub subject: Link<Entity>,
    pub attr_type: String,             // canonical predicate
    pub value: Literal,                // String | Integer | Float | Boolean | Date | DateTime | Duration | Json
    pub status: ClaimStatus,
    pub confidence: f32,
    pub validity_window: Option<ValidityWindow>,
    pub evidence: Vec<EvidenceRef>,
    pub temporal_audit: Option<TemporalAudit>,
}

Document Pipeline Records

Doc

Top-level source-backed document record ingested into Meerkat Recall. For media-backed ingest, text is the renderer-owned canonical searchable projection rather than the raw caller payload.

pub struct Doc {
    pub base: BaseFields,
    pub title: String,
    pub text: String,
    pub sidecar_text: Option<String>,
    pub source: Option<Link<Source>>,
    pub media_attachments: Vec<DocMediaAttachment>,
    pub rendition_key: String,
    pub metadata: Value,
}

DocRevision

Immutable normalized text snapshot produced by a renderer plugin. For multimodal docs, the revision also carries the authoritative render manifest that maps spans back to attachments and time ranges. If rendering improves, a new revision is created and the old one is superseded.

pub struct DocRevision {
    pub base: BaseFields,
    pub doc: Link<Doc>,
    pub text: String,
    pub text_hash: String,
    pub manifest: Option<RenderManifest>,
    pub renderer: RendererMetadata,
    pub supersedes: Option<Link<DocRevision>>,
    pub status: RevisionStatus,        // Active | Superseded | Failed
    pub rendered_at: DateTime<Utc>,
}

DocNode

Structural nodes over a revision — paragraphs, sections, chunks, summaries, etc.

pub struct DocNode {
    pub base: BaseFields,
    pub revision: Link<DocRevision>,
    pub role: NodeRole,                // Document | Section | Paragraph | Chunk | Summary | ...
    pub span: TextSpan,               // { start: u32, end: u32 }
    pub node_key: String,
    pub text: Option<String>,
    pub parent: Option<Link<DocNode>>,
    pub position: i32,
    pub depth: i32,
    pub embedding_model: Option<String>,
    pub collection: Option<String>,
}

Extraction and Truth Maintenance

Assertion

Evidence-bearing claims extracted from documents by the LLM extraction pipeline. Assertions preserve the original mention strings alongside their resolution status and optional resolved entity links. Staged artifact validation/commit resolves or creates graph records; later truth maintenance reconciles competing graph claims. A resolved assertion is not a guarantee that its claim is true.

pub struct Assertion {
    pub base: BaseFields,
    pub subject_text: String,
    pub predicate_raw: String,
    pub predicate_id: Option<String>,
    pub object_text: Option<String>,
    pub object_literal: Option<Value>,
    pub evidence: EvidenceSpan,
    pub source_event_time: Option<DateTime<Utc>>,
    pub observed_at: DateTime<Utc>,
    pub asserted_at: DateTime<Utc>,
    pub assertion_key: String,
    pub resolution_status: ResolutionStatus,  // Pending | Resolved | Partial | Abstained | Failed | Superseded
    pub resolution_method: Option<String>,
    pub resolution_confidence: Option<f32>,
    pub retry_state: AssertionRetryState,
    pub subject_entity: Option<Link<Entity>>,
    pub object_entity: Option<Link<Entity>>,
    pub confidence: f32,
    pub subject_entity_type: Option<String>,
    pub object_entity_type: Option<String>,
    pub significance: Option<String>,
    pub lifecycle_tier: String,        // "active" | "archived"
}

TruthSlot

The derived current selection for a claim slot. Each current_values entry references a graph claim by claim_id, with its confidence, status, and evidence. It does not contain the literal value itself. Read that claim to obtain its value. A slot can have several accepted values, be stale, or require more evidence; it is not an independent source of evidence.

pub struct TruthSlot {
    pub base: BaseFields,
    pub slot_key: String,
    pub slot_type: String,             // "rel" | "attribute" | "event" | "rel_set"
    pub subject_entity: String,
    pub predicate_id: String,
    pub current_values: Vec<CurrentValue>,
    pub conflict_group: Option<Link<ConflictGroup>>,
    pub confidence: f32,
    pub rationale: Option<String>,
    pub semantics_version: u32,
    pub alias_version: u32,
    pub stale: bool,
    pub stale_reason: Option<String>,
    pub computed_at: DateTime<Utc>,
    pub security_hash: String,
}

Source Provenance

Source

Tracks where data came from — emails, web pages, chat messages, device captures, manual entries, etc.

pub struct Source {
    pub base: BaseFields,
    pub type_: SourceType,             // Email | Calendar | Web | Drive | Chat | DeviceFrame | DeviceVideo | Transcript | Manual
    pub external_id: Option<String>,
    pub uri: Option<String>,
    pub path: Option<String>,
    pub parent: Option<Link<Source>>,
    pub range: Option<SourceRange>,
    pub timestamp: Option<DateTime<Utc>>,
    pub author: Option<String>,
    pub channel: Option<String>,
    pub hash: String,
    pub metadata: Value,
}

Work Scheduler Records

The durable work scheduler uses a DAG-based queue with lease-based execution. Each pipeline stage produces WorkItem records that are claimed, executed, and produce artifacts.

WorkItem

pub struct WorkItem {
    pub base: BaseFields,
    pub kind: String,                  // e.g. "render_doc", "plan_extraction", "extract_assertions", "validate_artifacts", "commit_artifacts"
    pub payload: Value,
    pub status: WorkItemStatus,        // Pending | Runnable | Running | Done | Failed | Cancelled
    pub priority: i32,
    pub idempotency_key: String,
    pub attempts: u32,
    pub lease_expires_at: Option<DateTime<Utc>>,
    pub leased_by: Option<String>,
    pub run_after: Option<DateTime<Utc>>,
    pub last_error: Option<String>,
}

WorkRun

A single execution attempt of a work item.

pub struct WorkRun {
    pub base: BaseFields,
    pub work_item: Link<WorkItem>,
    pub attempt: u32,
    pub started_at: DateTime<Utc>,
    pub completed_at: Option<DateTime<Utc>>,
    pub success: bool,
    pub error: Option<String>,
    pub metrics: WorkRunMetrics,
    pub worker_id: String,
    pub worker_version: String,
    pub model_version: Option<String>,
    pub prompt_id: Option<String>,
    pub config_hash: Option<String>,
}

WorkArtifact

Staged output produced by a work run. Goes through validation before being committed to canonical tables.

pub struct WorkArtifact {
    pub base: BaseFields,
    pub work_run: Link<WorkRun>,
    pub artifact_type: String,         // e.g. "knowledge_candidates", "commit_bundle"
    pub data: Value,
    pub status: ArtifactStatus,        // Draft | Validated | Committing | Committed | Rejected
    pub validation_errors: Option<Vec<String>>,
    pub validated_at: Option<DateTime<Utc>>,
    pub committed_at: Option<DateTime<Utc>>,
}

Configuration and Governance

SpaceConfig

Per-space configuration controlling embedding provider selection and extraction behavior.

pub struct SpaceConfig {
    pub base: BaseFields,
    pub embedding_provider: String,    // "fastembed" | "openai" | "fake"
    pub embedding_model: String,
    pub embedding_dims: i32,
    pub purpose: Option<String>,       // injected into extraction prompts
    pub skill: Option<String>,         // extraction skill ID
}

PredicateRegistry

Canonical predicate definitions with semantic configuration that drives truth maintenance behavior.

pub struct PredicateRegistry {
    pub base: BaseFields,
    pub predicate_id: String,
    pub description: Option<String>,
    pub status: String,                // "active" | "deprecated"
    pub semantics: Option<PredicateSemantics>,
    pub semantics_status: SemanticsStatus,
    pub first_seen_at: Option<DateTime<Utc>>,
    pub usage_count: u64,
    pub last_used_at: Option<DateTime<Utc>>,
}

PredicateSemantics controls temporal model, cardinality, conflict policy, recency basis, promotion thresholds, and alias confidence thresholds.

PredicateAlias

Maps raw extraction strings to canonical predicates with confidence-scored aliases.

pub struct PredicateAlias {
    pub base: BaseFields,
    pub alias: String,
    pub alias_type: AliasType,         // RawString | PluginCode | SchemaField
    pub source_plugin: Option<String>,
    pub confidence: f32,
    pub status: AliasStatus,           // Proposed | Active | Deprecated
    pub scope: AliasScope,             // Global | PluginOnly | SourceType
    pub predicate_id: String,
    pub confidence_version: u32,
    pub usage_count: u64,
}

System Records

Event

First-class domain timeline events with temporal precision and evidence links.

pub struct Event {
    pub base: BaseFields,
    pub title: String,
    pub summary: Option<String>,
    pub status: EventStatus,           // Candidate | Approved | Superseded | Rejected
    pub time_start: Option<DateTime<Utc>>,
    pub time_end: Option<DateTime<Utc>>,
    pub time_precision: TimePrecision, // Exact | Minute | Hour | Day | Month | Year | Unknown
    pub confidence: f32,
    pub time_confidence: f32,
    pub assertion_refs: Vec<Link<Assertion>>,
    pub source_refs: Vec<Link<Source>>,
    pub metadata: Value,
}

SystemEvent

Outbox events for reliable change-data streaming. Each carries a monotonic sequence number.

pub struct SystemEvent {
    pub base: BaseFields,
    pub seq: i64,
    pub event_type: String,
    pub payload: Value,
}

AuditLog

Audit entries record supported mutations with optional before/after snapshots. The record type alone does not guarantee that every internal mutation emits an entry. Consult the mutation handler and audit revert contract when building an administrative recovery workflow.

pub struct AuditLog {
    pub base: BaseFields,
    pub action: AuditAction,           // Create | Update | Delete | Restore | Purge | Promote | Merge
    pub actor: String,
    pub record: RecordId,
    pub before: Option<Value>,
    pub after: Option<Value>,
    pub timestamp: DateTime<Utc>,
    pub reason: Option<String>,
}

All struct definitions above are simplified for documentation purposes. Derive macros, impl blocks, and serde attributes are omitted. See the actual source in crates/types/src/records/ for the full definitions.

​RecordId System

​TableName Enum

​Link<T>

​BaseFields

​Provenance

​Security (ABAC Envelope)

​Knowledge Graph Records

​Entity

​Rel

​Attribute

​Document Pipeline Records

​Doc

​DocRevision

​DocNode

​Extraction and Truth Maintenance

​Assertion

​TruthSlot

​Source Provenance

​Source

​Work Scheduler Records

​WorkItem

​WorkRun

​WorkArtifact

​Configuration and Governance

​SpaceConfig

​PredicateRegistry

​PredicateAlias

​System Records

​Event

​SystemEvent

​AuditLog

RecordId System

TableName Enum

Link<T>

BaseFields

Provenance

Security (ABAC Envelope)

Knowledge Graph Records

Entity

Rel

Attribute

Document Pipeline Records

Doc

DocRevision

DocNode

Extraction and Truth Maintenance

Assertion

TruthSlot

Source Provenance

Source

Work Scheduler Records

WorkItem

WorkRun

WorkArtifact

Configuration and Governance

SpaceConfig

PredicateRegistry

PredicateAlias

System Records

Event

SystemEvent

AuditLog