Memory Thread

Memory Threads are Memind’s topic-level memory projections. They group related Memory Items into evolving threads so agents can follow long-running subjects across sessions: projects, workflows, incidents, investigations, decisions, recurring preferences, and repeated agent behaviors. A Memory Thread is not a chat thread. It is a derived memory object that tracks how a topic changes over time.

Overview

Memory Threads sit after Memory Items and the Item Graph in the memory construction flow.

Raw Data
  -> Memory Items
  -> Item Graph
  -> Memory Threads
  -> Insight Tree
  -> Retrieval

Memory Items capture what should be remembered. The Item Graph connects related memories. Memory Threads use those items and graph signals to create a topic-level projection. A thread can represent:

a project
a workflow
an incident
an investigation
a decision path
a recurring preference
a repeated agent behavior
a general long-running topic

The goal is to turn related memory fragments into an evolving topic state that can be inspected, retrieved, and updated over time.

Why Memory Threads exist

Individual Memory Items are useful, but long-running topics are rarely captured by a single item. A project may span many conversations. A decision may depend on several prior constraints. A recurring preference may appear across different tasks. A resolved problem may involve a diagnosis, a blocker, a fix, and a final outcome. The Item Graph connects related memory, but the graph itself does not always provide a clear topic state. Memory Threads add that layer. They help Memind answer:

What ongoing topic does this memory belong to, and what is the current state of that topic?

This is useful because agents often need topic continuity, not only isolated facts. Without Memory Threads, an agent may retrieve several related items but still fail to understand the broader project, workflow, or decision path they belong to.

Thread projection flow

Memory Threads are derived from Memory Items and Item Graph signals. At a high level, the flow is:

Memory Items + Item Graph
  -> Candidate Matching
  -> New or Existing Thread
  -> Membership Update
  -> Event Extraction
  -> Projection Update
  -> Lifecycle Update
  -> Optional Enrichment
  -> Memory Thread

Each step has a specific role.

Step	Purpose
Candidate Matching	Find existing threads that may match new items.
New or Existing Thread	Decide whether to create a new thread or update an existing one.
Membership Update	Attach relevant Memory Items to the thread.
Event Extraction	Normalize meaningful changes into thread events.
Projection Update	Update the thread headline, snapshot, state, counters, and timestamps.
Lifecycle Update	Move threads between active, dormant, and closed states.
Optional Enrichment	Improve the thread with additional reasoning when enabled.

This process turns related items into a materialized topic projection.

Thread model

A Memory Thread is made of several related concepts: type, memberships, events, projection state, and optional enrichment.

Thread types

Memind can classify threads into broad types.

Type	Meaning
`WORK`	A project, workflow, implementation effort, or work-like process.
`CASE`	An incident, investigation, problem, or resolution path.
`RELATIONSHIP`	A recurring relationship between entities, behaviors, or preferences.
`TOPIC`	A general topic-level thread.

These types help Memind organize long-running subjects without forcing every thread into the same shape.

Memberships

A thread is connected to the Memory Items that belong to it. A membership records that an item participates in a thread. It can also store whether the item is a primary member and how strongly it belongs to the thread. Conceptually, a membership includes:

Field	Meaning
`threadKey`	The thread identity.
`itemId`	The related Memory Item.
`role`	The role of the item inside the thread.
`primary`	Whether this is a primary membership.
`relevanceWeight`	How strongly the item belongs to the thread.

Memberships let a thread stay connected to the source items that shaped it.

Events

Events form the thread timeline. They capture meaningful updates, decisions, blockers, milestones, setbacks, and resolutions. Common event types include:

Event type	Meaning
`OBSERVATION`	New information was observed.
`UPDATE`	The topic was updated.
`STATE_CHANGE`	The thread state changed.
`BLOCKER_ADDED`	A new blocker appeared.
`BLOCKER_CLEARED`	A blocker was removed.
`DECISION_MADE`	A decision was recorded.
`QUESTION_OPENED`	An unresolved question appeared.
`QUESTION_CLOSED`	A question was answered or closed.
`MILESTONE_REACHED`	A meaningful milestone was reached.
`SETBACK`	A negative change or regression happened.
`RESOLUTION_DECLARED`	The thread or case was resolved.

Events are what make a thread more than a static group of items. They show how the topic evolves.

Enrichment

Thread enrichment is optional. When enabled, Memind can use additional reasoning to improve the thread projection after enough meaningful events have accumulated. Enrichment can help update:

the thread headline
the topic snapshot
current state
important context
unresolved questions
blockers or milestones

Enrichment is controlled by runtime configuration, so applications can choose whether thread updates should stay lightweight or use additional reasoning.

Lifecycle and state

Memory Threads track both lifecycle status and topic state. These are related but not the same.

Lifecycle status

Lifecycle status describes whether a thread is still active.

Status	Meaning
`ACTIVE`	The topic is current or recently updated.
`DORMANT`	The topic has not received meaningful updates for a while.
`CLOSED`	The topic is considered finished or no longer active.

This helps Memind avoid treating every historical topic as current.

Object state

Object state describes the current state of the topic itself.

State	Meaning
`ONGOING`	The topic is still moving.
`BLOCKED`	Progress is blocked by an issue or dependency.
`STABLE`	The topic is stable and not changing much.
`RESOLVED`	The topic or case has been resolved.
`UNCERTAIN`	The current state is unclear.

For example, a thread may be ACTIVE and BLOCKED, or DORMANT and STABLE. Lifecycle tells Memind whether the thread is active. Object state tells Memind what is happening inside the topic.

How threads are used

Memory Threads are used by several parts of Memind.

Used by	How
Retrieval	Thread assist can retrieve related items through topic projections.
Insight Tree	Threads provide topic-level grouping signals for higher-level understanding.
Memind UI	Developers can inspect thread state, members, events, timestamps, and snapshots.
Agent context	Threads help agents understand long-running topics without reading every item.

This lets agents retrieve not only facts, but also the topic continuity behind those facts. A thread can help answer questions such as:

What project is this item part of?
What decisions have already been made?
Is this topic still active?
What is currently blocked?
What was resolved?
What changed since the last session?

Configuration

Memory Threads are controlled by MemoryThreadOptions. At a high level, the configuration includes:

Option group	Purpose
`enabled`	Controls whether Memory Threads are enabled.
`derivation`	Controls whether thread derivation is enabled and whether it runs asynchronously.
`rule`	Controls matching thresholds, candidate limits, member limits, and retrieval member limits.
`lifecycle`	Controls when threads become dormant or closed.
`enrichment`	Controls optional thread enrichment behavior.

Memory Threads can be enabled when applications need topic continuity across sessions. If an application only needs simple item-level memory, this layer can be disabled.

Getting Started

Core Concepts

Core Features

Overview

Why Memory Threads exist

Thread projection flow

Thread model

Thread types

Memberships

Events

Enrichment

Lifecycle and state

Lifecycle status

Object state

How threads are used

Configuration

​Overview

​Why Memory Threads exist

​Thread projection flow

​Thread model

​Thread types

​Memberships

​Events

​Enrichment

​Lifecycle and state

​Lifecycle status

​Object state

​How threads are used

​Configuration

Overview

Why Memory Threads exist

Thread projection flow

Thread model

Thread types

Memberships

Events

Enrichment

Lifecycle and state

Lifecycle status

Object state

How threads are used

Configuration