Knowledge Graph

Memories in isolation are useful. Memories connected into a graph are powerful. Engram’s knowledge graph turns a flat collection of facts into a structured web of relationships that supports traversal, discovery, and automated maintenance.

Edges

An edge is a directed relationship between two memories. Each edge has a source, a target, and a relation type:

Relation	Meaning	Example
relates_to	General association	A debugging insight links to the architecture it applies to
contradicts	Conflicting information	Two memories disagree about the correct approach
supersedes	Newer replaces older	A revised design decision replaces the original
derived_from	Conclusion from evidence	A summary derived from several observations
part_of	Component of a whole	A detail belongs to an architecture overview
summarized_by	Consolidated summary	Redundant memories point to their consolidation

Edges use UUID references rather than database primary keys. This is critical for sync — when memories exist across multiple databases (personal, synced, team), integer IDs collide. UUIDs are globally unique, so edges remain valid across database boundaries.

Graph Patterns

Hub-and-Spoke

Complex topics are organized using hub memories. A hub is a brief overview; detail memories link to it via part_of edges. When you recall the hub with depth traversal, all its children surface automatically.

graph TD
    H[Sync Architecture Hub]
    H -->|part_of| D1[DB Layout]
    H -->|part_of| D2[SyncConfig Model]
    H -->|part_of| D3[Migration Flow]
    H -->|part_of| D4[Team Sync Design]

Hubs are created automatically when you use the parent_id parameter on remember.

Supersession Chains

When decisions evolve, supersedes edges preserve the history. The old memory drops in recall ranking, but the chain remains traceable — you can see how decisions changed over time.

graph TD
    V1[v1: REST polling] -->|supersedes| V2[v2: WebSocket sync]
    V2 -->|supersedes| V3[v3: IPC relay]

Contradiction Tracking

When two memories conflict, Engram connects them with a contradicts edge rather than automatically resolving the conflict. This is deliberate:

• Contradictions may represent legitimate disagreement between team members
• Auto-resolution risks silent data loss
• Both viewpoints surface together during recall, enabling informed decisions

graph TD
    C1[Use Redux] <-->|contradicts| C2[Use Context API]

Automatic Connections

Engram builds the graph automatically through several mechanisms:

• remember with parent_id — creates a part_of edge to the parent
• consolidate — creates summarized_by edges from originals to the summary
• Auto-connect on store — when a new memory is stored, Engram searches for semantically similar existing memories and creates relates_to edges. If those neighbors share a common hub, the new memory is linked to that hub too.
• Cross-project linking — if a memory’s content mentions another project by name, relates_to edges are created to relevant memories in that project

Traversal

The depth parameter on recall controls how far the search follows edges:

Depth	Behavior	Use case
0	Search results only	Focused lookup
1	Results + direct neighbors	Standard context gathering
2	Two hops out	Exploring a topic area
3	Three hops (maximum)	Deep exploration

Each hop follows all edge types in both directions. A part_of child surfaces its parent hub; a supersedes edge surfaces the newer version; a contradicts edge surfaces the conflicting viewpoint.

Community Detection

As graphs grow, natural clusters emerge. Engram provides two complementary discovery tools:

detect_communities — uses label propagation over the edge graph. Nodes start with their own label, then iteratively adopt the most common label among their neighbors. The algorithm converges when labels stabilize, revealing structurally connected communities.

find_clusters — uses embedding distance to find memories that are semantically similar, regardless of whether they’re connected by edges. This surfaces redundancy: memories that say similar things but haven’t been linked or consolidated yet.

Use both together — structural communities (what’s explicitly connected) and semantic clusters (what talks about the same thing) inform different maintenance actions.

Maintenance

The graph benefits from periodic cleanup:

Tool	Purpose
organize	Batch-reassign topics, create hub with part_of edges
consolidate	Merge redundant memories into a summary, link via summarized_by
merge	Combine two near-duplicate memories into one
connect / disconnect	Manually add or remove edges

Consolidated memories aren’t deleted — they’re set to importance 0 (deprioritized in recall) and linked to the summary via summarized_by. The originals remain for provenance. You can always trace back to the raw memories that informed a consolidation.