memory_relate
Create directional links between memories to record supersedes, caused_by, contradicts, or containment facts that similarity search cannot infer, improving related recall.
Instructions
Create a directional link between two memories. Relations are used by spreading activation (recalling one memory wakes its related cluster) and are returned when include_related=True in memory_recall.
An edge must encode something search cannot infer. Recall already ranks
by hybrid text + semantic similarity, so "these two memories are about the
same topic" is knowledge the index has for free. What only a relation can
record is direction and time: which memory REPLACED which, what CAUSED what,
what CONTRADICTS what, what CONTAINS what. Prefer, in this order:
supersedes, contradicts, caused_by, parent_of/child_of.
Reach for related_to only when a genuine connection exists that none of
those describe - it is the fallback, not the default.
Quality over volume: spreading activation surfaces at most 3 neighbours per
seed memory, and it weights by relation type - a directional edge outranks
related_to, so on any memory with more than 3 edges the related_to
ones are what lose their slot. A vague edge is therefore not merely
low-value, it is likely to never fire at all; and precise edges still
compete against each other for those 3 slots, so a handful of them
retrieves better than a dense mesh. If you cannot name the directional fact
an edge records, do not create it.
A mislabelled edge is repairable: memory_unrelate retypes or removes one.
source_id is the memory making the claim about target_id. relation_type
must be one of: supersedes (source replaces target), contradicts (conflicting
claims), caused_by (source was caused by target), parent_of (source contains
target), child_of (source belongs to target), related_to (fallback: a real
connection none of the above captures).
Batch by passing edges instead of the single-edge fields - an array of
up to MAX_BATCH_EDGES objects, each with source_id, target_id and
relation_type (all required; there is no default type for a batch op):
[{"source_id": "a", "target_id": "b", "relation_type": "supersedes"},
{"source_id": "a", "target_id": "c", "relation_type": "caused_by"}]All-or-nothing, same as memory_unrelate's batch: every op is validated
(both memories exist, the type is real, no self-edge) before anything is
written, and the whole set is applied in one transaction, so a failure on op k
leaves ops 0..k-1 unwritten too - a half-applied relation set is the graph
state hardest to notice and hardest to repair. Relate is idempotent on
(source, target, type), so each result reports created or exists
rather than pretending a no-op was a write. Pass either edges or the
single-edge fields, never both.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| edges | No | ||
| source_id | No | ||
| target_id | No | ||
| relation_type | No |