Module graph 

#2 knowledge graph: rule-based relation-edge extraction.

Consolidation writes "supersedes" edges, but those point at superseded memories retrieval already excludes, so on their own they leave the graph-lite / petgraph backends behaving exactly like flat retrieval. This module derives MEANINGFUL "relates_to" edges between active memories that share a salient entity, so a query that hits memory A can reach a linked memory B it does not directly match (multi-hop retrieval).

The rule layer is fully deterministic and model-free: it parses inline [tags: ...] markers (via crate::consolidate::parse_tags) plus a small salient-term pass, indexes memories by entity, and links every pair that shares at least one entity. The optional LLM enrichment layer (--enrich) lives in the CLI, where the cheap-model provider is resolved.

Batch vs incremental (v2.6)

build_relates_to_edges rebuilds the whole graph and is what kimetsu brain graph build runs. Because it only ever ran when a user remembered to invoke it, memory_edges in practice held nothing but supersedes — so the graph-lite backend behaved like flat retrieval, and the published graph-lite benchmark number described a configuration almost nobody was running.

incremental_edges_for_memory closes that gap: one indexed lookup against the memory_entities projection, run on every write, bounded by the same fan-out cap. It asks for INCREMENTAL_MIN_SHARED_ENTITIES shared entities rather than the batch builder’s one, because a single shared word on the write path would attach each new memory to half the corpus.

Edges are persisted as memory.edge events via crate::projector::add_memory_edges, so they are rebuild-safe.

Structs

EdgeProposal

A proposed relation edge between two active memories.

Enums

EntitySource

Where an extracted entity came from. Author-supplied tags are high-signal; salient terms are the extractor’s guess. Ranking treats them differently, so the distinction is persisted rather than recomputed.

Constants

DEFAULT_MAX_FAN_OUT

Default cap on how many edges any single memory may originate, to stop a common entity (shared by many memories) from producing a quadratic hairball.

INCREMENTAL_MIN_SHARED_ENTITIES

Minimum shared entities before two memories are linked on the write path.

RELATES_TO

The rule-layer edge type.

Functions

build_relates_to_edges

Build rule-based relates_to edge proposals over all active memories: any two memories sharing >= 1 extracted entity are linked. Edges are undirected in meaning but stored once as src < dst (graph-lite traverses both directions), so each related pair yields exactly one proposal. max_fan_out caps the number of edges per source memory (0 = use DEFAULT_MAX_FAN_OUT).

extract_entities

Extract salient entities/keywords from one memory’s text. The result is lowercased and de-duplicated. Two sources:

extract_entities_with_source

extract_entities, keeping track of where each entity came from.

forget_entities

Drop the entity rows for one memory (used when a memory is invalidated or superseded, so the index does not keep routing traffic to a dead memory).

incremental_edges_for_memory

Propose relates_to edges from one freshly written memory to the active memories it shares entities with.

project_entities

Replace the entity rows for one memory. Pure projection of text, so it is safe to call on every accept, merge and rebuild.

reproject_all_entities

Rebuild memory_entities for every active memory. Used by kimetsu brain rebuild and by the v11 migration backfill, so an existing brain gets an entity index without waiting for its memories to be rewritten.