> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openmemind.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Item Graph
The Item Graph is Memind's relationship layer.
Memory Items preserve what should be remembered. The Item Graph preserves how those memories relate, so Memind can move from isolated facts to connected knowledge.
It connects Memory Items through four kinds of relationships:
* **Entity relationships** — which items refer to the same real-world thing
* **Semantic relationships** — which items are meaningfully related
* **Temporal relationships** — how items relate in time
* **Causal relationships** — why one item explains, enables, or motivates another
## Overview
A Memory Item is useful on its own, but many memories only become meaningful when they are connected.
For example, these items may be extracted from different conversations:
```text theme={null}
The user is migrating the payment service to Java 21.
The payment-service repository still needs rollout documentation.
The user prefers stable tooling for production systems.
The user rejected an experimental dependency during the migration.
```
Each item is useful, but the relationship between them matters. They may refer to the same service, share a project context, happen in sequence, or explain a decision.
The Item Graph gives Memind a way to represent those relationships.
## Why Item Graph exists
Without a graph, memory becomes a collection of isolated facts.
That creates several problems:
* related memories can be missed if they use different wording
* project, tool, repository, or topic continuity can be lost across sessions
* retrieval may return direct matches but miss connected context
* long-running topics are harder to group into Memory Threads
* Insight Tree consolidation has less structure to work with
* agents may know facts without understanding how they relate
In short:
```text theme={null}
Memory Items tell Memind what should be remembered.
The Item Graph tells Memind how those memories are connected.
```
## Where Item Graph fits
The Item Graph is built after Memory Items are extracted.
```text theme={null}
Raw Data
-> Memory Items
-> Item Graph
-> Memory Threads
-> Insight Tree
-> Retrieval
```
It reads structured Memory Items and adds relationship signals around them.
Those relationships can then be used by Retrieval, Memory Threads, Insight Tree consolidation, and Memind UI inspection.
## Graph objects
The Item Graph is built from a small set of graph objects.
| Object | Meaning |
| ------------------------ | ------------------------------------------------------------- |
| **Graph Entity** | A canonical entity inside one memory namespace. |
| **Entity Alias** | A normalized alias or name variant for an entity. |
| **Item Mention** | A relationship showing that a Memory Item mentions an entity. |
| **Item Link** | A typed relationship between two Memory Items. |
| **Entity Co-occurrence** | A signal that entities appear together in related memory. |
These objects let Memind represent both entity-centered relationships and item-to-item relationships.
## Entity relationships
Entity relationships answer:
> Which items talk about the same real-world thing?
Entities act as anchors in the graph. They can represent projects, tools, repositories, people, organizations, systems, topics, or other named concepts.
Aliases help Memind connect different names for the same thing. Mentions connect Memory Items to entities. Co-occurrence tracks entities that repeatedly appear together.
### Processing flow
```text theme={null}
Memory Items
-> Entity Detection
-> Entity Normalization
-> Alias Resolution
-> Mention Recording
-> Co-occurrence Update
-> Entity Graph
```
### What gets stored
| Stored object | Meaning |
| ------------------------ | --------------------------------------- |
| **Graph Entity** | The canonical entity. |
| **Entity Alias** | A normalized alias or name variant. |
| **Item Mention** | The item-to-entity relationship. |
| **Entity Co-occurrence** | A signal that entities appear together. |
### Why it matters
Entity relationships help Memind:
* connect items across sessions
* handle naming variants such as `payment service` and `payment-service`
* expand from one item to other items about the same entity
* support Memory Thread projection around projects, tools, repositories, or topics
* help Insight Tree consolidation group related memory
### Example
```text theme={null}
Item A: The user is migrating the payment service to Java 21.
Item B: The payment-service repository still needs rollout documentation.
Entity:
payment service / payment-service
Result:
Both items are connected through the same entity.
```
## Semantic relationships
Semantic relationships answer:
> Which items are meaningfully related even if they do not mention the same words?
A semantic relationship connects Memory Items that are close in meaning, context, or intent. These links can come from signals such as vector similarity, same-batch context, or entity overlap.
### Processing flow
```text theme={null}
Memory Items
-> Candidate Search
-> Similarity Scoring
-> Entity Overlap Check
-> Link Filtering
-> Semantic Item Links
```
### What gets stored
| Stored object | Meaning |
| ---------------------- | ---------------------------------------------------------------------------------------------- |
| **Semantic Item Link** | A typed item-to-item relationship. |
| **Strength** | The relationship strength. |
| **Evidence Source** | The signal behind the link, such as `vector_search`, `same_batch_vector`, or `entity_overlap`. |
### Why it matters
Semantic relationships help Memind:
* connect memories with similar meaning but different wording
* improve recall during graph-assisted retrieval
* group related items for higher-level insights
* connect preferences, decisions, and actions that belong to the same pattern
### Example
```text theme={null}
Item A: The user prefers stable tools for production work.
Item B: The user avoided an experimental dependency during the migration.
Result:
The items are semantically related around risk avoidance and stable tooling.
```
## Temporal relationships
Temporal relationships answer:
> How are memory items related in time?
Not every memory should be treated as timeless. Projects, decisions, events, plans, and incidents often depend on order and timing.
Temporal links let Memind represent relationships such as `before`, `overlap`, and `nearby`.
### Processing flow
```text theme={null}
Memory Items
-> Time Extraction
-> Time Normalization
-> Temporal Candidate Pairing
-> Relation Classification
-> Temporal Item Links
```
### What gets stored
| Stored object | Meaning |
| ---------------------- | ---------------------------------------------------------------- |
| **Temporal Item Link** | A typed item-to-item time relationship. |
| **Relation Code** | The temporal relation, such as `before`, `overlap`, or `nearby`. |
| **Strength** | The confidence or weight of the relationship. |
### Why it matters
Temporal relationships help Memind:
* answer time-aware questions
* distinguish old state, current state, and future plans
* build timelines for Memory Threads
* understand how user preferences, projects, and decisions evolve
* support insight consolidation around change over time
### Example
```text theme={null}
Item A: The user decided last week to keep SQLite for local development.
Item B: The user later asked how to package the local server with Docker Compose.
Result:
Item A happened before Item B.
```
## Causal relationships
Causal relationships answer:
> Why did one memory lead to, explain, or support another?
Many useful memories are not just related by topic or time. One memory may explain a decision, enable an action, motivate a preference, or describe the cause of a resolved problem.
Causal links let Memind represent relationships such as `caused_by`, `enabled_by`, and `motivated_by`.
### Processing flow
```text theme={null}
Memory Items
-> Causal Signal Detection
-> Candidate Pairing
-> Relation Classification
-> Evidence Validation
-> Causal Item Links
```
### What gets stored
| Stored object | Meaning |
| -------------------- | -------------------------------------------------------------------------- |
| **Causal Item Link** | A typed item-to-item causal relationship. |
| **Relation Code** | The causal relation, such as `caused_by`, `enabled_by`, or `motivated_by`. |
| **Strength** | The confidence or weight of the relationship. |
### Why it matters
Causal relationships help Memind:
* understand why a decision was made
* connect problems with resolutions
* reuse troubleshooting knowledge
* preserve motivation behind preferences and constraints
* help Insight Tree consolidation capture “why” patterns, not only “what” facts
### Example
```text theme={null}
Item A: The Maven build failed because the Java version was too old.
Item B: The issue was resolved by switching to Java 21.
Result:
The resolution is connected to the diagnosis through a causal relationship.
```
## Why these relationships matter
The Item Graph is not only for visualization.
Graph relationships are used by multiple parts of Memind:
| Used by | How |
| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
| **Retrieval** | Graph assist can expand from direct matches to related memory. |
| **Memory Threads** | Related items can be grouped into evolving topic projections. |
| **Insight Tree** | Connected memory can be consolidated into higher-level understanding. |
| **Memind UI** | Developers can inspect entities, aliases, mentions, item links, relationship types, strengths, and evidence sources. |
This is how Memind moves from isolated facts to connected memory.