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.
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
- 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
| 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. |
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. |
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. |
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. |
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. |
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. |
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. |
- 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. |
