How GUMem Works

GUMem is not a chat history database. It turns raw Message input into traceable Facts, compresses them into long-term Summary, and groups Summary under Topic. During recall, GUMem first uses Topic to narrow the search area, then retrieves Summary. If Summary is not enough for the current task, it adds supporting Facts and raw Message context.

GUMem Characteristics

Characteristic	Description
Layered memory	Raw input, traceable facts, long-term summaries, and topic entry points are managed separately.
Provenance	Facts keep source Message references for explanation, audit, correction, and deletion.
Grounded extraction	Facts and Summary should come from explicit input, not unsupported model guesses.
Long-term recall	When long-term writes are enabled, GUMem generates Summary and Topic for future retrieval.
Governance	Summary carries validity, management status, confidence, time, labels, and evidence fields.
Extensibility	WebHooks can add rules, clean data, or sync external systems during Facts, Summary, and Topic processing.

The four-layer Memory model

GUMem's public model is easiest to understand by recall depth:

GUMem organizes Memory in four layers to solve two problems at once: remember enough, and recall precisely.

Message keeps the raw input. Facts keep traceable evidence. Summary provides compressed memory that can be reused long term. Topic organizes memory into retrievable directions.

During write, information moves from concrete to abstract. During recall, the system moves from abstract to concrete. This lets the Agent find the relevant topic first, use the Summary, and go back to Facts and raw Message input when it needs evidence.

Layer	Role	Example
Topic	A high-level area used to find related memory.	team scheduling
Summary	A long-term compressed memory supported by Facts.	The user prefers Berlin as the default city for Europe team scheduling.
Facts	Traceable facts, preferences, plans, or constraints extracted from Message input.	The user said Europe maps to Berlin and Americas maps to Toronto.
Message	Raw conversation or behavior input.	User messages, searches, filters, saves, or tool results.

Memory Extraction Flow

The following flow shows how GUMem turns multimodal input into Facts Chunk, generates Summary and Topics by Memory Type, and aggregates updates into Topic.

1. GUMem receives a batch of Message input.
2. GUMem segments the input and extracts traceable Facts.
3. If long-term memory write is enabled, GUMem turns Facts into Summary.
4. GUMem assigns Summary to Topic and updates Topic summaries.
5. Facts, Summary, and Topic are written to retrieval indexes.

If long-term memory write is disabled, GUMem stops at Facts and does not generate Summary or Topic. This is useful when you need auditable facts but not cross-session long-term recall.

Recall Path

GUMem recalls memory in stages. It starts from Topic to find the relevant memory area. If the high-level result is enough, GUMem can return it directly. If the Topic result is not enough for the current query, GUMem drills down to Summary for more specific long-term memory. If Summary is still insufficient, GUMem adds supporting Facts as evidence-level context.

Recall starts from the high-level entry point:

Topic -> Summary -> Facts -> Message

1. GUMem decides whether the current query needs long-term memory.
2. If needed, it recalls related Topic entries.
3. It recalls Summary under those Topic entries.
4. If Summary is insufficient, it adds supporting Facts.
5. It combines the result with recent Message context from the current Session.

After candidate memories are recalled, GUMem runs merge + rerank: it combines candidates from different layers, then orders them by query relevance, confidence, and evidence strength before returning context to the Agent.

This avoids reading all history. Topic narrows the search area, Summary provides usable long-term context, and Facts explain provenance or add evidence when higher-level memory is not enough.

Memory Layers

Topic

Topic is the high-level organization layer for Summary and the first entry point for long-term recall. It usually represents a stable profile dimension, business topic, or task domain.

Topic characteristics:

• It is for recall, not a user-facing directory.
• One Topic can link to many Summary items.
• Topic keeps its own summary text to help recall find the right area.
• Topic should come from an allowed topic set to avoid uncontrolled topic growth.

Summary

Summary is long-term memory supported by Facts. It is shorter than raw Message input and more useful than a single Fact for later Agent tasks.

Summary characteristics:

• Its content should be supported by source Facts.
• It can carry confidence, labels, entities, and event time.
• It supports management states such as active, deprioritized, archived, and deleted.
• It supports retrieval boost, usage tracking, and later governance.
• When a user corrects information, write a new Message and let GUMem form a new evidence chain instead of treating old Summary as immutable truth.

Facts

Facts are traceable facts, preferences, plans, constraints, events, or behavior signals extracted from Message input. Facts are the evidence layer for explanation and governance.

Facts characteristics:

• They must trace back to one or more source Message entries.
• They keep time range, entities, labels, and evidence.
• They only express what the input supports.
• They can come from user, assistant, or system messages, while preserving speaker and speech act.
• When users update old information, Facts record the new state and its source.

Message

Message is GUMem's raw input. It can be a user, assistant, or system conversation message, or upstream text describing behavior or business events.

Message characteristics:

• It includes at least role and content.
• It can include metadata, timestamp, turn_id, and processing status.
• It is the source for Facts, not the final long-term memory itself.
• It should include enough time and business context for later explanation and audit.

Boundaries

• Do not use GUMem as a strongly consistent business database. Orders, permissions, billing, and inventory belong in business systems.
• Do not write unsupported inference as Facts.
• Do not store every input by default. Write information that can affect future answers, recommendations, tool calls, or risk decisions.
• Do not treat Summary as immutable truth. When users correct information, write a new Message.

Next Step

• Read Add Memory to write new Message input.
• Read Query Memory to recall Topic, Summary, Facts, and Message context.