Memory Links
Links connect loci inside LocusGraph. They are the typed relationships that drive how knowledge gets retrieved, scored, and graduated from event to pattern to skill.
Why Links Are the Engine
Plain memory systems store isolated snippets. LocusGraph treats relationships as first-class. Two events that reinforce each other together carry more confidence than either alone. A new event that contradicts an old one quietly demotes the old one in retrieval. This is how memory becomes knowledge.
Link Types
Five link types, ordered from weakest to strongest effect:
related_to
General association between two loci. No side effects on confidence scoring. Use when knowledge is connected but does not modify the target.
extends
Adds detail to another locus. No side effects on confidence. The extending locus is returned alongside the target during retrieval.
derived_from
Indicates the source locus was created because of the target. Auto-created for constraint, rule, and constraint_violation events when a context_id is present.
reinforces
Confirms another locus. Each reinforces link increases the target's confidence by +0.05, capped at 1.0. Use when new evidence supports existing knowledge — this is what drives the event → pattern → skill graduation chain.
contradicts
Conflicts with another locus. Each contradicts link decreases the target's confidence by -0.10, with a floor of 0.2. The target is never fully removed — low-confidence loci are deprioritized in retrieval instead so old knowledge fades but stays auditable.
Confidence adjustments from reinforces and contradicts are applied during admission. They compound: three reinforces links add +0.15 to the target's confidence and push the underlying knowledge closer to skill-grade.
Link Layers
Links operate across three layers:
| Layer | Connects | Example |
|---|---|---|
| Locus → Locus | Two individual knowledge nodes | A decision reinforces a fact |
| Locus → Context | A node to a context scope | A skill locus extends a session context |
| Context → Context | Two context scopes | A project context is related_to a skill context |
Example: The Graduation Chain
Links are how a single event becomes a pattern and then a skill:
- Event recorded. The agent stores an observation: "Used
varinstead ofconstin React component." - Pattern detected. After seeing this twice, the agent stores a fact: "Repeated use of
varin React." It links this to the original observation withderived_from. - Skill formed. The agent stores a decision: "Always use
constorletin React components." It links this to the pattern withextendsand to the original event withreinforces— confirming the learned lesson.
observation: "used var"
<- derived_from <- fact: "repeated var pattern"
<- extends <- decision: "always use const/let"
-> reinforces -> observation: "used var"LocusGraph now returns the skill-level decision in retrieval, backed by the full chain of evidence. Validated knowledge sits at the front of the queue.
Creating Links
Pass links when storing an event:
{
"event_kind": "fact",
"source": "agent",
"payload": { "topic": "const_usage", "value": "always use const in React" },
"links": [
{ "type": "reinforces", "target": "locus_abc123" },
{ "type": "derived_from", "target": "locus_def456" }
]
}Link Cheatsheet
| Use case | Reach for |
|---|---|
| New event confirms an old learning | reinforces |
| New event overrides an old learning | contradicts |
| New event adds detail to an existing one | extends |
| Event was created because of a rule or context | derived_from |
| Two events touch the same area but neither modifies the other | related_to |