Association Graph
Association Graph
The memory system doesn't just store memories in isolation — it builds a graph of connections between them. These connections make retrieval smarter over time: when you search for one memory, related memories are surfaced through their associations.
How Associations Work
An association is a link between two memories with a type and a strength (0.0 to 1.0):
| Association Type | What It Means |
|---|---|
| related | General topical relationship |
| supports | One memory supports or reinforces another |
| contradicts | One memory conflicts with another |
| caused | One memory caused or led to another |
| co_accessed | Two memories are frequently retrieved together |
Bidirectional Links
When memory A is linked to memory B, the reverse link (B→A) is automatically created at 80% of the original strength. If you link A→B with strength 0.8, B→A gets strength 0.64.
Co-Access Learning
This is how the graph gets smarter automatically. When two memories are retrieved together in the same context window, their association is strengthened — or created if it doesn't exist.
Over many conversations, memories that are relevant to similar topics naturally cluster together. The graph learns which memories belong together based on actual usage, not just semantic similarity.
Example: If your character discusses "database optimization" and both a memory about "index tuning" and one about "query performance" are retrieved, they get linked. Next time the character encounters a question about databases, finding one memory also surfaces the other.
Transitive Propagation
Strengthening a link between A and B can also boost connections to C, if B and C are already strongly linked. This creates ripple effects through the graph:
A ←strong→ B ←strong→ C
↕ strengthening A-B also slightly boosts A-C
This means the graph develops emergent structure — clusters of tightly connected memories form around topics, and these clusters become more cohesive with use.
Decay
Association strength decays over time if connections aren't reinforced:
- Weak associations (below 0.1 strength) are pruned during cleanup
- Strong associations decay slowly
- Frequently co-accessed pairs resist decay because they get reinforced
This prevents the graph from becoming cluttered with obsolete connections. Active, useful relationships persist while unused ones fade.
Viewing the Graph
The Brain Visualizer in the QUI Core dashboard displays the memory association graph as an interactive network:
- Nodes represent individual memories, colored by kind (fact, event, general, etc.)
- Edges represent associations, with thickness proportional to strength
- Clusters are groups of tightly connected memories (detected automatically)
[Screenshot: Brain visualizer showing memory nodes connected by association edges, with visible clusters]
You can filter by:
- Memory kind (facts, events, general, etc.)
- Compression level (raw, consolidated, etc.)
- Minimum importance threshold
- Specific character
The visualizer helps you understand how your character's knowledge is structured and where clusters of expertise have formed.
How Associations Affect Retrieval
When the Memory Service builds context for a character's response:
- Primary search — find memories semantically similar to the current message
- Association follow — for each result, check linked memories and include strongly associated ones
- Ranking — combine similarity score, importance, and association strength to rank final results
- Token budgeting — fit the best results into the available context window
This means retrieval is not purely keyword or similarity based — it follows the relationship graph to find contextually relevant memories that might not directly match the query but are connected to things that do.
Building Associations
Associations are created through several mechanisms:
| Mechanism | When It Happens |
|---|---|
| Co-access learning | Automatic — memories retrieved together get linked |
| Explicit linking | When storing a memory with associate_with IDs |
| Cortex processing | Pattern clustering processors build and prune associations |
| Duplicate detection | Near-duplicate memories get linked |
| Reply chains | Reply-to messages get parent_id links |
You don't need to manage associations manually — the system builds and maintains them through normal use. Cortex processing (especially the pattern_clustering processor) periodically strengthens useful links and prunes weak ones.
