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:

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:

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.

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

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

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

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

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

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

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

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

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.

Getting Started

Core Concepts

Core Features

Overview

Why Item Graph exists

Where Item Graph fits

Graph objects

Entity relationships

Processing flow

What gets stored

Why it matters

Example

Semantic relationships

Processing flow

What gets stored

Why it matters

Example

Temporal relationships

Processing flow

What gets stored

Why it matters

Example

Causal relationships

Processing flow

What gets stored

Why it matters

Example

Why these relationships matter

​Overview

​Why Item Graph exists

​Where Item Graph fits

​Graph objects

​Entity relationships

​Processing flow

​What gets stored

​Why it matters

​Example

​Semantic relationships

​Processing flow

​What gets stored

​Why it matters

​Example

​Temporal relationships

​Processing flow

​What gets stored

​Why it matters

​Example

​Causal relationships

​Processing flow

​What gets stored

​Why it matters

​Example

​Why these relationships matter

Overview

Why Item Graph exists

Where Item Graph fits

Graph objects

Entity relationships

Processing flow

What gets stored

Why it matters

Example

Semantic relationships

Processing flow

What gets stored

Why it matters

Example

Temporal relationships

Processing flow

What gets stored

Why it matters

Example

Causal relationships

Processing flow

What gets stored

Why it matters

Example

Why these relationships matter