Connect topics so retrieval can follow the story.
MemState links topics in two ways: with typed edges between topics, and with field-level references that point from an attribute value to another topic. Both participate in retrieval; each serves a different modeling intent.
Two kinds of links
Extension
The target belongs to the same broader context as the source — a sub-project, a deliverable, a chapter of a larger topic.
Association
Two independent topics that happen to relate — a person and a project, two concepts that interact, a task and its owner.
How extension and association appear on disk
Extension and association are modeling intents, not two different physical edge tables.
Both are stored as RELATED edges with a free-form kind string. Retrieval and the
reasoner inspect kind (and your own conventions) to decide whether to treat an edge as
parent–child context (extension) or peer linkage (association). Field
references remain separate: they live on field revisions as ref_topic_id and are merged into
structural expansion by the query path.
| Intent | Meaning | Typical edge names | When to use |
|---|---|---|---|
| Extension | Target extends or specializes the source. | has_detail, has_subtopic, part_of, extends |
The child topic retains the parent's context. Retrieval should expand from parent to child. |
| Association | Peer-to-peer relationship between independent topics. | associated_with, mentions, collaborates_with, references |
Two topics share meaning without one subsuming the other. |
Graph edges versus field references
MemState offers two physical ways to connect topics. They are not alternatives — they model different things. You often use both for the same pair of topics.
| Mechanism | Where it lives | Best for |
|---|---|---|
Typed edge (RELATED) |
Native graph relationship in the store. | Traversal, neighborhood expansion during retrieval, structural queries. |
Field reference (ref_topic_id) |
Attribute on a field record. | Attribute-level pointers ("manager is topic X") that should travel with the field value and its history. |
You can use a typed edge, a field reference, or both for the same pair of topics.
Edge semantics
- Directed. Every edge is written from a source to a target.
- De-duplicated. The same (source, target, kind) triple yields one edge, no matter how many times you merge it.
- Multi-kind. The same pair of topics can carry multiple named relationships at once.
- Participates in retrieval. Structural retrieval expands candidates through these edges to build neighbor context.
Field reference semantics
- A reference is an attribute on a single field record, not a separate row in the graph.
- It is the right tool when the pointer belongs to a specific attribute (
manager,owner,parent_doc). - Field references are preserved as the field's history evolves — a revision can keep the ref unchanged or redirect it.
- The UI graph renders field references as synthetic edges so you can see them alongside typed edges.
Which one should I use?
| Use case | Pick | Why |
|---|---|---|
| Parent / child topic containment. | Typed edge, extension intent. | Signals structural containment; retrieval will expand from parent to child. |
| Peer relationship between two independent topics. | Typed edge, association intent. | Multi-kind support; graph traversal sees it cleanly. |
| Attribute-scoped pointer ("manager", "owner"). | Field reference. | Lives with the field it describes; survives revisions and rollbacks on that field. |
| You want both typed traversal and attribute-scoped meaning. | Both. | They are not exclusive; the field reference captures attribute meaning, the edge enables traversal. |