Memory Overview
The layers of Cogitator memory, from thread entries and retrieval to memory items, memory files and the stages between runs, what is on by default and why.
Why Memory Matters
LLMs are stateless. Every request starts from scratch unless you pass the conversation again, and a long conversation outgrows the context window. Memory keeps what was said, finds the part a turn needs, and keeps what a conversation established past the conversation itself.
Architecture
Memory is a stack of layers over one store. Read it from the bottom: the store keeps everything, the thread holds the conversation, the message index, memory items and memory files are built from the conversation or beside it, retrieval picks from them, and the context is what the model sees. The stages run around the stack, the brief before a turn and the rest after a run:
- Context of a turnwith contextBuildersystem, pinned, memory index, summaries, facts, recall, brief, newest turns, input
- Retrievalhybrid with embeddingsrecent, relevant or hybrid: the newest turns plus what matches the turn
- Message indexwith embeddingsevery message embedded once, in the background, so the whole thread is searched
- Memory itemswritten by extractionfacts, events, preferences, lessons: quoted, trusted by source, kept in time
- Memory filesopt-innotes under /memories through the memory tool, observations, the playbook
- Thread entriesalwaysa tree of entries: branches, rewind, fork, forget and redact
- StorealwaysSQLite, Postgres, Redis, MongoDB or in process, and a vector store
- Before a turnopt-ina brief of cards that quote their sources
- After a runopt-incompaction, extraction, observations and consolidation
Filled bands are on once memory is configured, the context and retrieval with memory.contextBuilder and the message index with memory.embedding. Plain ones are opt-in.
- Store. One thread store (
memory.adapter) keeps the entries, memory items and memory file versions, and a vector store keeps the embeddings: pgvector on Postgres,memory.qdrant, or vectors in process, which the message index embeds again after a restart, the first time each thread is used. See Choosing an Adapter. - Thread entries. A thread is a tree of entries: a run appends to the active branch, and a replay or a fork writes a branch of its own that never shows up in the conversation it split from. Rewinding, forgetting and redacting take what stands on an entry out of every layer above it. See Threads as Trees and Forgetting, Redacting and Rewinding.
- Message index. With
memory.embedding, every message is embedded once, in the background, so a search reaches the whole thread instead of its newest turns. See History Strategies. - Retrieval. The context builder fills a token budget by partitions and picks the history by a strategy:
recentthe newest turns that fit,relevantthe turns closest to the input,hybridthe newest turns plus a recall of earlier turns and memory items that match the turn. See Context Building and Recall. - Memory items. What conversations established, as facts, events, preferences, instructions, opinions and lessons, each grounded in quotes, trusted by who said it and kept with when it held, so a newer state closes the old one. Extraction writes them, the facts partition and recall read them. See Memory Items.
- Memory files. Notes an agent keeps under
/memorieswith thememorytool, every change a version. Observations of the entities memory knows about and the playbook of lessons are memory files too. See Memory Files and Between Runs. - Between runs. Compaction folds a long thread into a hierarchical summary, extraction writes memory items, observations and consolidation keep the files in shape, and the brief prepares cards for the next turn. See Sessions, Compaction and Core Facts.
What Is On by Default
The defaults follow the memory benchmarks: a stage is on only where it won without a cost worth noticing.
| Layer | Default | Measured reason |
|---|---|---|
History strategy (contextBuilder.strategy) | hybrid with memory.embedding, else recent | hybrid gained 7 to 60 points over recent on all seven datasets (averaged 44.9% against 18.0% over the seven datasets), as much as relevant at three quarters of its cost and with a lower p95 latency |
relevant | opt-in | An equal choice for question answering over long histories, without the prompt cache hybrid keeps |
Compaction (memory.compaction) | off | Saves 55% of the input tokens and helps sessions up to about 100K tokens, no better than recent past that. Use it to save tokens, not as memory |
Extraction (memory.extraction) | off, start with mode: 'shadow' | Gained 5 to 16 points over recent (most on preferences), below hybrid everywhere, and its calls cost three times the answers |
| Memory files, brief, observations, consolidation | off | Not measured by the benchmarks |
Without contextBuilder, a run loads the last 20 entries of the thread's active branch. A strategy you set is always kept, so set strategy: 'recent' to keep the newest turns only with embeddings configured. The memory stages (compaction chapters, extraction) were measured with claude-haiku-5-5 only.
Results and unwrap()
Adapter methods never throw for expected failures; they return a MemoryResult:
type MemoryResult<T> = { success: true; data: T } | { success: false; error: string };Check result.success, or use unwrap() to get the data and throw an Error with the adapter's message on failure:
import { InMemoryAdapter, unwrap } from '@cogitator-ai/memory';
const memory = new InMemoryAdapter();
await memory.connect();
const thread = unwrap(await memory.createThread('agent-1'));
const result = await memory.getThread(thread.id);
if (result.success && result.data) {
console.log(result.data.metadata);
}Core Concepts
Threads
A Thread represents a conversation session. Each thread belongs to an agent and holds an ordered list of memory entries. Pass a third argument to choose the thread id yourself:
import { InMemoryAdapter, unwrap } from '@cogitator-ai/memory';
const memory = new InMemoryAdapter();
await memory.connect();
const thread = unwrap(await memory.createThread('agent-1', { topic: 'onboarding' }));
const named = unwrap(await memory.createThread('agent-1', {}, 'support-ticket-42'));metadata.userId names the user a thread belongs to. When an agent run creates a thread, the runtime sets it from the run's userId — see Multiple Users.
Memory Entries
A MemoryEntry stores a single message along with its token count and optional tool call data.
await memory.addEntry({
threadId: thread.id,
message: { role: 'user', content: 'Hello!' },
tokenCount: 3,
});
await memory.addEntry({
threadId: thread.id,
message: { role: 'assistant', content: 'Hi there! How can I help?' },
tokenCount: 8,
});
const entries = unwrap(
await memory.getEntries({
threadId: thread.id,
limit: 50,
includeToolCalls: true,
})
);getEntries() returns entries oldest first, limit keeps the most recent ones, and before / after (dates) narrow the range. Tool calls and results are stripped unless includeToolCalls is true. It reads every branch of the thread (see below) and returns only message and tool_result entries unless types asks for more.
Threads as Trees
A thread's entries form a tree, not a list. Each entry points at the entry before it on its branch (parentId, null for the first entry), and the thread's activeLeafId names the entry its active branch ends at. Branches share the entries before the point they split at. Every entry also carries a seq (its place in the order the thread's entries were added), a type and a formatVersion.
This is what lets a run try something else from an earlier point, a replay go on beside the original, or a user edit a message, without copying or deleting the conversation.
addEntry without a parentId goes after the active leaf and becomes the new leaf in one step. With a parentId it goes on that branch, and activate: false adds it without moving the active leaf:
const question = unwrap(
await memory.addEntry({
threadId: thread.id,
message: { role: 'user', content: 'Plan a day in Rome' },
tokenCount: 6,
})
);
const answer = unwrap(
await memory.addEntry({
threadId: thread.id,
message: { role: 'assistant', content: 'Start at the Colosseum...' },
tokenCount: 6,
})
);
const retry = unwrap(
await memory.addEntry({
threadId: thread.id,
parentId: question.id,
activate: false,
message: { role: 'assistant', content: 'Start at the Vatican...' },
tokenCount: 6,
})
);The thread now has two branches that share the question, and the active one still ends at answer.
Entry Types
| Type | What it records |
|---|---|
message | A user, assistant (with its tool calls) or system message |
tool_result | The answer of a tool |
model_change | The run moved to another model, such as a fallback |
compaction | Entries before a point of the branch were summarized |
approval | A run paused for an approval decision |
interrupt | A run was stopped |
label | A name for a point of the thread |
custom | Anything else, for plugins |
All but message and tool_result are events of the session: they carry their payload in event and are never sent to a model. An entry without a type (written before types existed) is a message. getEntries and getPath return only message and tool_result entries by default, so code that knows nothing of events keeps seeing the conversation. Pass types: ['message', 'approval'] or types: 'all' to see more. The runtime records model_change, approval and interrupt itself, see Runs on Branches.
Reading a Branch
getPath reads one branch from its first entry to its leaf, oldest first, without reading the rest of the thread:
const active = unwrap(await memory.getPath({ threadId: thread.id }));
const other = unwrap(await memory.getPath({ threadId: thread.id, leafId: retry.id }));
const everything = unwrap(await memory.getPath({ threadId: thread.id, types: 'all' }));| Option | Default | Description |
|---|---|---|
threadId | required | The thread |
leafId | the active leaf | The entry the branch ends at |
limit | all | The newest limit entries of the branch |
before | none | Only entries before this one on its branch, to read in pages |
types | conversation | Entry types to return, or 'all' |
includeToolCalls | false | Keep toolCalls and toolResults on the entries |
A long branch reads in pages from its end: take the newest entries, then pass the oldest of them as before:
const newest = unwrap(await memory.getPath({ threadId: thread.id, limit: 50 }));
const oldest = newest[0];
if (oldest) {
const earlier = unwrap(
await memory.getPath({ threadId: thread.id, limit: 50, before: oldest.id })
);
}Postgres and SQLite read a path in one recursive query that stops at limit, MongoDB with $graphLookup, InMemory and Redis walk the parents entry by entry.
Rewind, Checkout and Fork
unwrap(await memory.rewind(thread.id, question.id));
unwrap(await memory.checkout(thread.id, retry.id));
const copy = unwrap(await memory.forkThread(thread.id, retry.id, 'rome-vatican'));rewind(threadId, toEntryId)moves the active leaf back to an entry of the active branch. Nothing is deleted: the next entry starts a new branch from there, and the old one stays readable withgetPath({ leafId }). An entry on another branch fails, check it out instead.checkout(threadId, entryId)makes the branch ending at any entry of the thread the active one.forkThread(threadId, atEntryId, newThreadId?)makes a new thread holding copies of the branch up toatEntryId, events included. Each copy names its original inmetadata.forkOf, the new thread names its origin inmetadata.forkedFrom({ threadId, entryId }), and the origin lists it inmetadata.memoryForks. A paused run of the origin is not copied.
deleteEntry splices an entry out of its branch: its children go after its parent, and when it was the active leaf, its parent becomes the leaf. clearThread removes every entry and the leaf with them.
These methods are optional on the MemoryAdapter interface, so an adapter of your own may leave them out. Every built-in adapter has them, and a run on a branch needs getPath. cog.rewind(threadId, toEntryId) rewinds a thread and marks as stale the memory items that stood only on the turns it left, see Forgetting, Redacting and Rewinding. With file checkpoints it brings back the files of the workspace to the same point, in the same operation.
Entries Written Before Trees
Entries written by earlier versions have no parent. Each store chains them in the order they were added the first time it meets them, so an old thread reads as one branch:
- Postgres moves its schema to version 2 on
connect()(adds the columns, chains the entries and sets each thread's leaf, in the setup transaction). - SQLite migrates on
connect(), byPRAGMA user_version. - Redis and MongoDB chain a thread the first time it is read or written.
Upgrade every process that shares a store at once: an older process appends entries without a parent.
Facts
Facts are long-term memories that persist across threads: user preferences, learned information, or system-level knowledge. Only PostgresAdapter implements FactAdapter, and it keeps each fact as a memory item of its own slot.
import { PostgresAdapter } from '@cogitator-ai/memory';
const postgres = new PostgresAdapter({
provider: 'postgres',
connectionString: process.env.DATABASE_URL!,
});
await postgres.connect();
await postgres.addFact({
agentId: 'agent-1',
content: 'User prefers dark mode',
category: 'preference',
confidence: 0.95,
source: 'user',
metadata: { userId: 'alice' },
});A fact with metadata.userId only goes into that user's context, a fact without one is shared by everyone the agent serves. Facts with an expiresAt in the past are no longer returned. updateFact with new content writes a new item that supersedes the one before, so what the fact said is kept in its history, while a change that keeps the statement (confidence, category, metadata, evidence, expiry) corrects the current item. deleteFact deletes the fact with its history. A fact without evidence comes back without the evidence field.
Lineage
A summary, a fact, a graph node or edge, or a reflection insight is derived from the conversation, and a model that derives it can get it wrong. Fact, GraphNode, GraphEdge and Insight take an optional evidence list that says what the item stands on, word for word:
interface Evidence {
entryId?: string; // the memory entry the quote is from
toolCallId?: string; // the tool call whose result the quote is from
fileRange?: { path: string; start: number; end: number };
quote: string; // the words, as they appear in the source
}@cogitator-ai/memory checks evidence against memory:
import {
evidenceOnPath,
unwrap,
verifyEvidence,
verifyEvidenceInMemory,
} from '@cogitator-ai/memory';
import type { Evidence } from '@cogitator-ai/types';
const said = unwrap(
await memory.addEntry({
threadId: thread.id,
message: { role: 'user', content: 'I am vegetarian, and I fly out of Lisbon.' },
tokenCount: 12,
})
);
const diet: Evidence = { entryId: said.id, quote: 'I am vegetarian' };
const airport: Evidence = { entryId: said.id, quote: 'I fly out of Porto' };
const evidence = [diet, airport];
verifyEvidence(diet, said); // 'verified'
verifyEvidence(airport, said); // 'suggested'
const checked = unwrap(await verifyEvidenceInMemory(memory, evidence));
checked.status; // 'suggested', since the second quote is not in the entry
checked.evidence.map((item) => item.status); // ['verified', 'suggested']
const branch = unwrap(await memory.getPath({ threadId: thread.id, types: 'all' }));
evidenceOnPath(evidence, new Set(branch.map((entry) => entry.id))); // trueverifyEvidence(evidence, entry)is'verified'when the quote appears in the entry word for word, whitespace aside: in its text, or in the results of its tool calls. With atoolCallIdonly the result of that call counts. Anything else, an empty quote included, is'suggested': keep it, but do not rely on it as fact.verifyEvidenceInMemory(memory, evidence)loads each entry withgetEntryand checks it. Evidence of an entry that is gone, or with noentryId(a file is not memory's to check), is'suggested'. The whole is'verified'only when every piece is.evidenceOnPath(evidence, pathIds)istruewhen every piece that names an entry names one ofpathIds. Use it with the ids of a branch fromgetPathto keep only the derived items that stand on that branch, so a fact learned on an abandoned branch does not leak into another.
Every built-in fact and graph adapter stores evidence and reads it back (a JSON column in Postgres and SQLite, a JSON property in Neo4j), updateFact, updateNode and updateEdge take it, and mergeNodes keeps the evidence of every merged node. Deleting or redacting entries follows this lineage, see Forgetting, Redacting and Rewinding.
Context Building
The ContextBuilder assembles the final message list sent to the LLM. It shares a token budget among the parts of a context, selects history entries by a strategy, and orders the result so that what stays the same from turn to turn comes first, where the provider's prompt cache can serve it.
import { ContextBuilder, createEmbeddingService } from '@cogitator-ai/memory';
const embeddings = createEmbeddingService({
provider: 'openai',
apiKey: process.env.OPENAI_API_KEY!,
});
const builder = new ContextBuilder(
{
maxTokens: 8192,
strategy: 'hybrid',
includeSystemPrompt: true,
includeFacts: true,
includeSemanticContext: true,
},
{
memoryAdapter: postgres,
factAdapter: postgres,
embeddingAdapter: postgres,
embeddingService: embeddings,
}
);
const context = await builder.build({
threadId: thread.id,
agentId: 'agent-1',
userId: 'alice',
systemPrompt: 'You are a helpful assistant.',
currentInput: 'What were we discussing yesterday?',
brief: 'Current date and time: Wednesday, October 21, 2026, 17:20.',
});
console.log(context.messages, context.tokenCount, context.truncated);
console.log(context.memoryContext); // facts, recall and the brief as one text, sent with the input
console.log(context.partitions); // tokens per partition, e.g. { system: 12, final: 9, facts: 40, recent: 3100 }
console.log(context.dropped.blocks); // every block left out, with its partition and reason
console.log(context.errors, context.warnings);| Option | Default | Description |
|---|---|---|
maxTokens | none | Total token budget. Without it, every build() needs its own maxTokens (a Cogitator run passes its model's window) |
reserveTokens | 10% of the budget (min. 100) | Tokens kept free for the model's reply. build() takes its own reserveTokens too |
strategy | - | recent, relevant or hybrid |
includeSystemPrompt | true | Put systemPrompt first. It is always kept and counted: the rest of the context only gets what it leaves of the budget |
includeFacts | false | Add a Known facts: block (needs memoryItems or factAdapter, the facts partition), see Memory Items in the Context |
includeSemanticContext | false | Add a Relevant context: block from the top 5 embeddings scoring 0.7 or more (needs embeddingAdapter + embeddingService and a currentInput, the recall partition) |
includeGraphContext | false | Add knowledge graph context (needs graphContextBuilder and a currentInput, the recall partition), see Knowledge Graphs |
graphContextOptions | {} | maxNodes, maxEdges, maxDepth, includeInferred, entityTypes |
partitions | see below | Budgets of the partitions, merged over the defaults |
timeZone | 'UTC' | IANA time zone the dates of recalled turns are shown in and the time a turn names is read on, when build() names none. The constructor throws on a name that is not an IANA zone |
build() takes threadId, agentId, userId, systemPrompt, currentInput, maxTokens, reserveTokens and leafId, plus three texts of your own: pinned (a list of what is always in context, after the system prompt), index (what memory holds, so the model knows what to look up) and brief (notes for this turn only, such as the current time). Two more set the moment and the calendar of the turn: asOf, the moment the turn is read at (now by default), from which the time a turn names ("yesterday", "last March") is resolved and as of which memory items are read, so a recorded conversation can be replayed as it was, and timeZone, the IANA zone of the thread in place of the builder's (a name that is not a valid zone is ignored).
The history comes from the thread's active branch (getPath), not from every entry of the thread, so a branch a replay or a fork wrote never shows up in the conversation it split from. Pass leafId to build() to build from the branch ending at that entry, or leafId: null for no history. An adapter without getPath gives the whole thread.
Partitions
A context is assembled from partitions, by the ContextAssembler. Each has a budget, a share of the context budget it may take, and may be required:
| Partition | Holds | Default budget |
|---|---|---|
system | the system prompt | required, always sent whole |
pinned | pinned texts | required |
index | the index text | required |
summaries | compaction summaries of the branch | required |
brief | the brief text | required |
facts | facts (includeFacts) | 15% |
recall | what a search of memory found (hybrid), semantic search results, then the knowledge graph context | 35% (60% for hybrid) |
recent | history entries, selected by the strategy | what the others leave |
final | currentInput, counted but not part of messages | required, always counted |
Required partitions are fitted first, in the order system, final, pinned, summaries, index, brief. system and final are always kept whole, the others take what is left of the budget and are cut down only when it cannot hold them. The partitions that are not required split what the required ones leave by their shares, each no more than it needs, and what one leaves unused is shared again among those that need more. What the shares cannot place goes to the partitions still short of room in the order they are filled, facts, recall, then recent, so no part of the budget sits unused while another partition is cut. recent takes the share the others leave (50% by default). Change a budget with partitions, merged over the defaults: a share must be between 0 and 1, and the shares of the partitions that are not required may add up to 1 at most, or the builder throws:
const builder = new ContextBuilder(
{
maxTokens: 16_000,
strategy: 'recent',
includeFacts: true,
partitions: { facts: { share: 0.2 }, recall: { share: 0.1 } },
},
{ memoryAdapter: memory, factAdapter: facts }
);The system prompt is always sent whole. A system prompt larger than maxTokens - reserveTokens leaves no room for history, and warnings says so.
A block that a more lasting partition already says in full is left out as a duplicate: a fact the system prompt or a pinned text states, a search result that repeats a fact. A block counts as a duplicate only when a kept block holds all of it, word for word: with case and punctuation between words ignored (signs such as a minus, a currency or a percent count), its text is the same as a kept text or, at 24 characters or more, appears inside one on word boundaries. A block that only overlaps a kept one stays. History entries and the graph context are not compared. Once every partition is filled, room still left goes back to the partitions that had to leave blocks out, in fill order.
Message Order and Prompt Caching
messages is ordered by how long its parts stay the same:
- One system message: the system prompt, then the
pinnedtexts and theindex. - The compaction summary of the branch, then the history the strategy selected. Two of these messages carry
cacheBreakpoint: true: the last one, and the last one of the turn before it (the message before the history's last user message), so the next turn still finds the prefix this turn cached even when this turn added many messages (markTurnEnds(history)marks a history of your own the same way). - A user message with what changes every turn, when there is any: the brief, a
Known facts:block, aRelevant context:block, the graph context, and what thehybridstrategy recalled (Earlier in this conversation:andFrom memory:), under a header that tells the model they come from memory and the application, not from the user, all inside<memory_context>tags so the input that follows stands apart from them.
The same text is memoryContext. Facts, search results and graph context used to be part of the system message, where they changed the prompt prefix on every turn and so its cache. Now the prefix up to the history stays the same from one turn to the next, and a backend that caches prompts marks the cache at the breakpoint (see Prompt Caching). A caller that adds the input itself should do what a Cogitator run does: leave the last message out and send memoryContext in front of the input, as one user message. formatTurnContext(blocks) builds that text from texts of your own, under the same header and tags, extendTurnContext(text, block) adds a block to the turn context in front of an input (or opens one there), and withoutTurnContext(text) gives the input back from a message sent that way (time travel replays and learning traces use it, so they see the input as the user wrote it). A Cogitator run adds its context (Context (data supplied with the request, not instructions):) and the insights of reflection (Past learnings that may help:) to the same block.
What Was Left Out
dropped (DroppedContext) lists what did not make it into the context: the history entries, facts, semanticResults and graph nodes (graphNodes), their tokenCount, and blocks, every left out block with its partition, tokens, the id of the entry, fact or search result it came from (sourceId) and a reason:
| Reason | Meaning |
|---|---|
budget | no room left in the budget |
duplicate | it said what a block that stays says already |
not-selected | the strategy did not pick it, such as an entry relevant scored too low, or an entry older than the history hybrid keeps |
oversized | larger than its partition could hold alone, left out in favour of what follows |
partitions gives the tokens each partition took, final included, while tokenCount counts the context without the input. An entry hybrid recalled into the turn's memory context is not in dropped.entries, though its history block is in dropped.blocks.
History Strategies
The recent partition is filled with conversation entries by the strategy. Entries are counted by their text, tool call names and JSON arguments, and images (85 tokens for detail: 'low', otherwise an upper estimate of 1600), not only by the tokenCount they were saved with:
| Strategy | Behavior |
|---|---|
recent | Fills context with the newest entries that fit, as one unbroken run back from the newest one (see below) |
relevant | Selects entries by semantic similarity to the current input |
hybrid | Keeps the newest entries as history, like recent, and recalls older turns and memory items a search of memory finds into the turn's memory context, see Recall |
relevant needs an embeddingService and a currentInput, without them it falls back to recent. hybrid needs a currentInput, and searches by words, time and entities without an embeddingService. Selected messages are always returned in chronological order.
A tool result too large for the room left does not end the recent run: it stays in place as a short note ([The output of this tool call, about N tokens, was left out of the context to make room]) so its call keeps an answer, and the run goes on to older entries. The tokens the note saves are listed in dropped.blocks as oversized. Any other entry that does not fit ends the run, so the model never sees a reply without the message it answers. Compaction summaries are a required partition, so they get their room before the history and stay in the context.
With a messageIndex each history entry is embedded once and its vector kept in an embedding store, sourceType: 'message'. The builder scores the newest 200 user and assistant entries (for hybrid, of those older than the history it keeps) against their kept vectors, embeds the few the index has not reached yet (and keeps them), and finds older entries of the thread close to the input with a search of the store, so recall is not limited to the newest 200. A turn embeds only its input. Without an index the builder keeps vectors in process, by entry id, for the newest 200 entries.
import { MessageIndex } from '@cogitator-ai/memory';
const index = new MessageIndex({ store: postgres, embedding: embeddings });
index.attach(memory); // embeds new entries in the background, deletes vectors with their entries
const builder = new ContextBuilder(
{ maxTokens: 8000, strategy: 'relevant' },
{ memoryAdapter: memory, embeddingService: embeddings, messageIndex: index }
);attach listens to the adapter's changes (onChange, every built-in adapter has it): new user and assistant entries are embedded in batches in the background, and deleting an entry, clearing or deleting a thread deletes their vectors. Writes and deletes run in order, and an entry is checked to still exist right before its vector is written, so a vector never outlives its entry. Threads and entries Redis expires are reported as deleted once a later write or read finds them gone (the thread index outlives the threads by seven lifetimes for this, so threads expiring after a longer silence are not reported). When the store fails, the builder scores the newest entries with vectors kept in process and records a relevance error, so a build never falls back to recent for it. A build's input is not embedded again when it is saved. On Postgres, pgvector 0.8 or later is recommended: its iterative scans keep filtered searches complete in a store that also holds message vectors. History written before the index is indexed in the background the first time a thread is built. Vectors of another embedding model are embedded again. flush() waits for the background work, close() stops it. Background failures go to onError, and the entries are embedded when a build needs them. vectorsKept keeps about that many vectors, dropping those of the threads used least lately, for a store in process that indexes a memory lasting longer than the process (every vector by default). A thread it dropped is indexed again when a build uses it.
Each vector is marked metadata.index: 'messages' and carries the thread's agentId and userId, so a search of a shared store filtered by user leaves out other users' messages, and the index never touches message vectors of others. Semantic context searches only facts and documents, so message vectors never show up in another thread's context (embeddings you stored yourself as sourceType: 'message' no longer do either).
A part that fails to load (the history, facts, the semantic search, the knowledge graph, or relevance scoring and recall) is left out and listed in errors as { source, error } instead of failing the build. When relevance scoring fails, relevant falls back to recent, and hybrid recalls without vectors.
Semantic context is scoped per agent: embeddings whose metadata.agentId belongs to another agent are never injected, while embeddings without an agentId (shared documents) are visible to every agent.
Pass userId to build() to scope it per user as well: facts, embeddings and knowledge graph nodes whose metadata.userId belongs to another user are left out, while those without one are shared. Agent runs do this with the run's userId — see Multiple Users.
Recall
With strategy: 'hybrid' the newest turns stay as history, in the recent partition, where the prompt cache serves them, and the rest of the thread and the memory items the run sees are searched for the turn. The turns searched are the ones older than what the budget leaves for history after the required partitions, facts and recall, so a search never brings back what the history holds anyway. What it finds goes into the turn's memory context, in the recall partition (60% of the budget for hybrid unless partitions.recall sets a share, at most what the other shares leave, and what it leaves unused goes to the history), best first:
Earlier in this conversation:
[2026-04-02] user: We booked the cabin in Gerês for the long weekend.
[2026-04-02] assistant: Noted: Friday April 17 to Monday April 20.
From memory:
- Ana ran her first half marathon (in March)
- Ana lives in Porto (2019-03-01 to 2026-09-14)Each recalled turn comes with the turn next to it that makes it readable (the question an answer replies to, the answer to a question) unless the history holds it, and with the date it was said on, in the thread's time zone. An item that no longer holds shows the interval it held, and an item about a time shows that time, in the words it was said in when it has them, else as a date. An item the facts partition kept is not repeated under From memory:. BuiltContext.recalled gives what was sent, { entries, items }.
The search reads the turn without a model first. A greeting, a thanks or a reply such as ok or sure is not searched. Any other turn asks one of five kinds of question, and the time it names is resolved from asOf in the thread's time zone:
| Kind | When the turn | What counts more |
|---|---|---|
temporal | asks when, how long, before or after, or names a time | turns said and items about the time it names, past states of items too |
aggregate | asks how many, how much, a total or a list | words and entities, past states of items too |
update | asks how things stand now (now, still, latest) | memory items, and among them those that still hold |
preference | asks for a recommendation, a suggestion or a favourite | memory items, and among them preferences and instructions |
general | anything else | turns close to the input by their vectors |
Then it searches in channels, each giving its best 50:
- turns close to the input by their vectors (with an
embeddingService): a cosine of 0.45 or more, and at least 0.6 of the best one of the turn - turns that hold the input's words, by BM25 over the thread, its index kept between turns
- turns said in the time the input names
- turns that name an entity of memory the input names
- memory items that hold the input's words, by BM25
- items close to the input by the vectors of their content (with an
embeddingService), on the same bars as turns: each item is embedded once and kept in process, since an item never changes - items about an entity the input names
- items about the time the input names, or that held or were said then
- items a personalized PageRank walk reaches over the graph of items and the entities they name, started from the entities of the turn and the best items of the other channels
- the turns the best items were extracted from (their evidence), so a turn is found by what it meant, not only by its words
The items searched are those the run's agent (under its memory id and its runtime id), user and thread see, one current state per slot as the facts choose it, that hold as of asOf, and for a temporal or aggregate question the states that held before too. They need a store that keeps memory items (ContextBuilderDeps.memoryItems). The channels are fused by weighted reciprocal rank, with the weights of the kind of question. A hit then gains by the share of the input's words it holds, rarer words counting more, an older turn counts a little less (never less than half), an item sent to a model more often counts slightly more (timesRetrieved), and the list is laid out for diversity (maximal marginal relevance over word overlap), so near copies of one fact do not crowd out the rest.
ContextBuilderDeps.reranker takes any Reranker, such as CohereReranker or LLMReranker from @cogitator-ai/rag, and reorders the best 30 hits after the search ranked them, each given as the text the context would show. A reranker that fails leaves the order as it was and records a relevance error.
import { ContextBuilder, MemoryItems } from '@cogitator-ai/memory';
import { CohereReranker } from '@cogitator-ai/rag';
const builder = new ContextBuilder(
{ maxTokens: 16_000, strategy: 'hybrid', includeFacts: true, timeZone: 'Europe/Lisbon' },
{
memoryAdapter: memory,
memoryItems: new MemoryItems({ adapter: memory }),
embeddingService: embeddings,
messageIndex: index,
reranker: new CohereReranker({ apiKey: process.env.COHERE_API_KEY! }),
}
);
const context = await builder.build({
threadId: 'ana-1',
agentId: 'concierge',
userId: 'ana',
currentInput: 'Where did we stay last April?',
asOf: new Date('2026-10-21T15:00:00Z'),
});
context.recalled; // { entries, items }: the earlier turns and the memory items sentUsing Memory with Cogitator
Configure memory on the runtime and every run with a threadId loads and saves its history automatically:
import { Cogitator, Agent } from '@cogitator-ai/core';
const cog = new Cogitator({
memory: {
adapter: 'postgres',
postgres: { connectionString: process.env.DATABASE_URL! },
embedding: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY! },
contextBuilder: {
maxTokens: 8000,
strategy: 'hybrid',
includeFacts: true,
includeSemanticContext: true,
},
},
});
const agent = new Agent({
name: 'assistant',
model: 'openai/gpt-5.5',
instructions: 'You are a helpful assistant.',
});
await cog.run(agent, { input: 'Hi, I am Alice', threadId: 'thread-alice' });
await cog.run(agent, { input: 'What is my name?', threadId: 'thread-alice' });memory.adapternames the thread store and takes its settings from the key of the same name:'memory'(inMemory),'redis'(redis.url,redis.host+redis.port, orredis.cluster),'postgres'(postgres.connectionString),'sqlite'(sqlite.path) or'mongodb'(mongodb.uri). When the required setting is missing or the connection fails, the run goes on without memory and logs a warning, and the failed adapter is disconnected so nothing keeps reconnecting in the background. An adapter you connect yourself can be assigned withcog.memory = adapter, such runs load the last 20 entries of the active branch, since the context builder is only created from thememoryconfig.- With
contextBuilderset, each run builds its context as described above. WithoutmaxTokensthe budget is the context window of the model the run starts on (from the model registry, else the model family, else 8192 tokens, and at most 4096 on Ollama, which serves no more by default, except Ollama Cloud), minus room for the answer (the agent'smaxTokens, else 15% of the window, at most half of it) and the tool schemas, and below the point wherecontextcompression would start when it is on, andstrategydefaults to'hybrid'whenmemory.embeddingis set, else to'recent'(astrategyyou set is kept, see What Is On by Default). The runtime passes that budget once, withreserveTokens: 0, and the builder counts the input in it (thefinalpartition), so nothing is reserved twice. WithmaxTokensset, the builder'sreserveTokensapplies as usual. SetmaxTokensto cap the history, and the cost of every turn, on long threads, or to use a larger context your Ollama server runs with (OLLAMA_CONTEXT_LENGTH). The agent's instructions are always sent and counted in the budget (includeSystemPrompt: falseis ignored with a warning), and a run with instructions larger than the budget logs a warning. What memory recalls for the turn (memoryContext, with the run'sbrief), the run'scontextand the insights of reflection go into the final user message in front of the input, inside one<memory_context>block, so the system prompt and the history stay the same from turn to turn and are read from the prompt cache, and only the input is saved to the thread. Parts that fail to load are passed toonMemoryErrorwith the'load'operation, and the run goes on without them. Options the runtime cannot serve log a warning at connect:includeFactsneeds a store that keeps memory items or facts (every built-in thread store keeps items),includeSemanticContextneedsmemory.embeddingand an embedding store, andincludeGraphContexthas no effect, since the runtime builds no knowledge graph. A Postgres store is also the fact adapter, and the embedding adapter unlessmemory.qdrantis set. The runtime creates the Postgresembeddingstable with the vector size ofmemory.embedding(768 without one, or the size of an existing table). A Postgres store without pgvector still keeps threads and facts, but is not used for semantic context, and a warning names the reason. Withrelevantorhybridandmemory.embedding, the runtime keeps a message index on every memory, so every message is embedded once, in the background, andclose()waits for that work: in the embedding store (the Postgres store ormemory.qdrant), else in process. The in-processmemoryadapter is always indexed in process, and a lasting store without an embedding store keeps up to 50,000 vectors, of the threads used lately, indexing a thread again when a run uses it after it was dropped. An adapter that reports no changes logs a warning, since the vectors of its deleted entries would stay. Indexing failures are logged with theindexoperation. WithoutcontextBuilder, a run loads the last 20 entries of the thread's active branch. - With
strategy: 'hybrid'each run recalls older turns and memory items into the turn's memory context.memory.reranker(aReranker, set in code) reorders the best hits.contextBuilder.timeZone(an IANA zone,memory.extraction.timeZoneby default, else UTC) is the calendar of recalled dates and of the time a turn names, and a run on a thread whosemetadata.timeZoneis a valid zone uses that one.RunOptions.asOfsets the moment the turn is read at, now by default, to replay or evaluate a conversation recorded at another time: "yesterday" is resolved from it, and the facts and recalled items are those that held then. - Embedding cost:
relevantandhybridembed every entry of a thread once, in the background, which is one embedding per message, plus one embedding of the input per turn. After importing a conversation,await cog.indexMemory(threadId)embeds every entry of the thread the index has not reached yet, a page of 500 at a time, and returns once the vectors are stored, so the first search already sees the whole thread. It does nothing without an index (therecentstrategy or nomemory.embedding). It fails when the embedding store refuses a vector. - A run counts the memory items it sent to the model, the facts and the recalled items, once it finishes or pauses for approval: each item's
timesRetrievedgoes up andlastRetrievedAtis set. The counts are written in the background, one after another, so the run does not wait on them, a failure is logged, andclose()waits for them. memory.embeddingtakes a provider's config (openai,ollama,google) or anEmbeddingServiceof your own, which the runtime uses as it is: another provider, or a cache in front of one, as long as it hasembed,embedBatch,modelanddimensions. A service is code, so it goes tonew Cogitator({ memory }), not intocogitator.ymlordefineConfig().'qdrant'is not a thread store. For semantic context from Qdrant, keep a thread store asadapterand addmemory.qdrant(url,apiKey,collection,dimensionsmatching the embedding model) together withmemory.embeddingandcontextBuilder: { includeSemanticContext: true }. The runtime searches the collection for semantic context, and with therelevantorhybridstrategy also keeps the vectors of the thread's messages in it (sourceType: 'message', so the key needs write access). Add facts and documents with your ownQdrantAdapter. See Configuration for a YAML example.- Per run,
useMemory: falsedisables memory,loadHistory: false/saveHistory: falseskip loading or saving, andonMemoryErroris called when a load or save fails.branch: { fromEntryId, activate? }runs on a branch of the thread, andresult.memorysays where the run wrote, see Runs on Branches. memory.filesgives every agent thememorytool and lists its files in each run's context, see Memory Files.await cog.memorySearchTools(memoryAgentId)builds the tools an agent searches memory with, see Agent Memory Tools.await cog.getMemory()connects and returns the adapter before any run — see Cogitator.
Choosing an Adapter
| Adapter | Persistence | Embeddings | Memory items | Memory files | Facts | Graph | Best For |
|---|---|---|---|---|---|---|---|
| InMemory | None | Separate¹ | Yes | Yes | No | No | Testing, short-lived agents |
| Redis | Optional TTL | No | Yes | Yes | No | No | Shared fast store, optional expiry |
| Postgres | Permanent | pgvector | Yes | Yes | Yes | PostgresGraphAdapter | Production with full features |
| SQLite | Permanent | No | Yes | Yes | No | SQLiteGraphAdapter | Single-process, local apps |
| MongoDB | Permanent | No | Yes | Yes | No | No | Document-oriented workloads |
| Qdrant | Permanent | Native | No | No | No | No | Dedicated vector search |
¹ InMemoryEmbeddingAdapter provides in-process vector and keyword search.
For most production deployments, Postgres is the recommended adapter since it supports threads, facts, embeddings, keyword search and (with PostgresGraphAdapter) knowledge graphs in a single database. See Memory Adapters for configuration.
Sessions, Compaction and Core Facts
Three helpers build on top of any MemoryAdapter. The channels gateway wires them up for you; you can also use them directly.
SessionManager maps a user on a channel to a long-lived thread (session_<channelType>_<userId>) and tracks its status, message count and per-session config overrides:
import { createLLMBackend } from '@cogitator-ai/core';
import { SessionManager, CompactionService, InMemoryAdapter } from '@cogitator-ai/memory';
const memory = new InMemoryAdapter();
await memory.connect();
const llm = createLLMBackend('google', {
providers: { google: { apiKey: process.env.GOOGLE_API_KEY! } },
});
const compaction = new CompactionService({
adapter: memory,
summarize: async (messages, { model, prompt } = {}) => {
const response = await llm.chat({
model: model ?? 'gemini-3.5-flash-lite',
messages: [
{ role: 'system', content: prompt ?? 'Summarize this conversation in a few sentences.' },
...messages,
],
});
return response.content;
},
});
const sessions = new SessionManager(memory, { compaction });
const session = await sessions.getOrCreate({
userId: 'alice',
channelType: 'telegram',
channelId: 'chat-1',
agentId: 'assistant',
});
await sessions.update(session.id, { config: { temperature: 0.2 } });
const active = await sessions.list({ status: 'active', limit: 20 });
await sessions.archive(session.id);list() reads the sessions from an index thread. Using a session (getOrCreate) adds it back to the index if the index lost it and rewrites the index at most once per indexRefreshInterval (one minute by default), so in a store whose threads expire, like Redis with a ttl, the index lives as long as any session is active. Keep the interval well below the TTL.
CompactionService shrinks a thread once its stored entries reach threshold tokens or messageThreshold entries, whichever comes first (set at least one), keeping the keepRecent latest entries:
const result = await compaction.compact(session.id, {
strategy: 'summary',
threshold: 8000,
keepRecent: 10,
summaryModel: 'gemini-3.5-flash',
summaryPrompt: 'Keep names, decisions and open questions.',
});
// { sessionId, originalMessages, compactedMessages, summaryTokens }| Strategy | Behavior |
|---|---|
summary | Replaces older entries with one [Conversation summary] system entry produced by your summarize |
sliding-window | Leaves older entries out without a summary |
hybrid | sliding-window when 5 or fewer entries would be removed, otherwise summary |
hierarchical | Keeps a tree of grounded atoms in place of older entries, see Hierarchical Compaction |
On an adapter with branches (every built-in one) compaction deletes nothing. It adds a compaction entry to the end of the active branch, whose event (CompactionEvent) names the first kept entry, and whose message is the summary. A reader of the branch then sees the summary followed by the kept entries and everything after them, a reply saved while the summary was being written included. ContextBuilder and the runtime read history this way, in pages from the leaf back to where the latest compaction goes on from, so a long compacted thread costs only its current conversation. Read it yourself the same way:
import { readCompactedHistory } from '@cogitator-ai/memory';
const conversation = await readCompactedHistory(memory, { threadId });
// conversation.data: the summary, the kept entries and everything after themcompactedHistory(path) builds the same conversation from a path you read yourself with types: HISTORY_ENTRY_TYPES.
Since the summarized entries stay, other branches that start among them and evidence that points at them keep working, and getEntries still returns every entry. The next summary compaction summarizes the previous summary together with what followed it, while a hierarchical one keeps the tree of the previous one and only adds to it. Compactions of the same thread in one process run one after another.
An adapter without getPath gets the older behaviour: the summary is dated a millisecond before the first kept entry and the summarized entries are deleted (an adapter that ignores the createdAt of addEntry gets the kept entries re-added after the summary).
summarize is your function, call any LLM in it. It receives the messages being replaced and, as a second argument, SummarizeOptions { model, prompt } taken from the summaryModel / summaryPrompt of the compact() config (either may be undefined). sessions.compact() throws unless the manager was created with { compaction }.
CoreFactsStore is a small key-value store in SQLite (requires better-sqlite3) for always-on facts about the user, with a history of every value. Its facts are memory items:
import { CoreFactsStore } from '@cogitator-ai/memory';
const coreFacts = new CoreFactsStore({ path: './memory.db' });
await coreFacts.initialize();
await coreFacts.set('name', 'Alice');
await coreFacts.set('timezone', 'Europe/Berlin');
const prompt = await coreFacts.formatForPrompt(); // "name: Alice\ntimezone: Europe/Berlin"
const history = await coreFacts.getHistory('timezone'); // [{ value, setAt }]
await coreFacts.close();Each key is the slot core:<key> of system items in the store's scope ({ agentId: 'core' } by default, new CoreFactsStore({ path, scope }) for another). set writes a new item that supersedes the current value, and setting the value a key already holds changes nothing, so it adds no history. delete lets the current value go and keeps the history of the key. A database an earlier version wrote, with core_facts and core_facts_history tables, is moved into memory items on initialize(), its history kept, and the old tables are renamed core_facts_legacy and core_facts_history_legacy.
Hierarchical Compaction
A summary that is summarized again at every compaction loses a little each time, and what it loses is often what matters later: a task still open, a rule to keep following, an error nobody fixed. strategy: 'hierarchical' keeps the summary as a tree of what the conversation established instead, checks every piece of it against the entries, and never sends the old conversation or the old summary to a model again.
const result = await compaction.compact(session.id, {
strategy: 'hierarchical',
threshold: 60_000,
keepRecent: 0,
keepRecentTokens: 8000, // newest whole turns kept verbatim
chapterTokens: 4000, // conversation one chapter covers (default)
chapterConcurrency: 1, // chapters read at once (default)
chaptersPerArc: 4, // chapters kept before the oldest fold into an arc (default)
arcsPerSaga: 4, // arcs kept before the oldest fold into the saga (default)
summaryPrompt: 'Mind the deadlines.', // added to the chapter prompt
});Chapters. The entries new since the last compaction, up to the kept tail, are cut into windows of about chapterTokens tokens. Each window opens with the last entries of the one before (about a tenth of chapterTokens), so what spans a cut is read whole. The summarizer gets each window as one user message, a transcript that numbers every entry and indents its further lines, so no text in an entry can pass for another one, and cuts an entry at about chapterTokens tokens, so one huge output does not overflow the summarizer. options.prompt asks it for a JSON array of atoms and lists the items still open before the window, which it closes when the window shows them done, with summaryPrompt added at its end. Your summarize must send options.prompt as its instructions. Windows are read one at a time, so each is told every item open before it. chapterConcurrency reads more at once, faster, but then a window is not told the items the model finds in the windows read along with it. chapterTokens, chapterConcurrency, chaptersPerArc and arcsPerSaga must be whole numbers above 0, else compact() throws.
With messageThreshold, a hierarchical compaction counts only the entries written since the last summary (sinceSummary), since a tail kept by tokens can hold more entries than the threshold.
A part to compact under a tenth of the kept tail is left for later (compact() changes nothing), since a new summary would change the cached prompt for little.
Atoms. A CompactionAtom is one thing the conversation established: its kind (fact, task, decision, constraint, error, file, or thread for a question left open), its status (open or closed), a short text and its evidence, quotes of the entries it stands on. Every kind but fact and file is a control atom, something a reader must not lose while it is open.
Grounding. Each quote is checked against the entry it names, as lineage checks facts. An atom whose quotes all hold is verified, any other is a suggestion. A constraint or a decision that only tool outputs show is not verified either, so text a tool fetched does not become a rule. The array of atoms is found past any text and brackets around it, and an element that is not an atom (such as one of another kind) is left out instead of the whole answer. A chapter call asks for an answer of up to 8000 tokens (SummarizeOptions.maxTokens), and an answer cut at that limit inside the array keeps the atoms it finished, and the summarizer is asked to go on after the last one, up to four times, so a dense chapter is summarized whole. An answer that holds no array is asked for again, up to three tries in all, and then the compaction fails. Some atoms need no model: the files tool calls worked on (arguments such as path, file, file_path or filename), tool calls that failed (bash {"command":"npm test"} failed: exit 1, known by the tool and its files, or its arguments when it names no files) and task lines (TODO:, - [ ]) are taken from the entries themselves, so no answer can lose them. A failed call is closed by a later call of the same tool that succeeds on the same files, or with the same arguments when it names no files, and - [ ] item by - [x] item.
Levels. Chapters beyond chaptersPerArc fold into arcs, oldest first, and arcs beyond arcsPerSaga fold into the saga. Folding merges atoms by kind and text with no model, so no open item in the middle of a long thread is lost. The saga keeps every open control atom and the newest 200 facts and files (SAGA_ATOMS), leaving out items done long ago, so the handoff stops growing. A later status wins, except that a control atom is closed or opened again only by an atom whose evidence holds: a claim of done the conversation does not show leaves it open, and a repeat that does not hold does not bring back an item that was done. An open item that a window shows only in the overlap it opens with belongs to the window before and is left out.
Loss check. A new summary is published only when every open control atom of the one before is still there or was closed. One that would drop such an item throws (The summary would lose N open item(s)) and the thread stays as it was.
Handoff. The message of the compaction entry is the handoff, the merged atoms laid out by what a reader goes on with: Open tasks, Constraints, Decisions, Unresolved errors, Open questions, Files, Facts and Done, an unverified atom marked (unverified). The order is the same every time, so a summary that did not change reads the same and stays in the prompt cache.
## Open tasks
- TODO: write tests
## Decisions
- Use PostgresThe tree in one entry. The whole tree is the one compaction entry: its event.levels (CompactionLevels) holds the saga, the arcs and the chapters, oldest first in each, every one a CompactionNode with the first and the last entry it covers (from, to) and its atoms. The next compaction starts from these levels and adds only the new chapters. A summary another strategy wrote becomes one closed, unverified fact of the first chapter. On an adapter without branches the levels are kept in the summary entry's metadata (compactionLevels).
Tail. With keepRecentTokens the newest tokens of the conversation stay verbatim, as whole turns that open with a user message, so a tool call keeps its result. When even the last turn is larger, it is kept from its user message on. Without it the newest keepRecent entries stay, moved back to the call a kept tool result answers. A thread of no more than keepRecent entries is not compacted either way.
CompactionService.chapterAtoms(window, config, { own, open }) returns the atoms of one window, the summarizer's checked answer together with the structural atoms of own (the window less the overlap it opens with, all of it by default), told the open items to close, for a pipeline of your own.
To have Anthropic write the atoms with its compaction on request, use anthropicCompactionSummarizer from @cogitator-ai/core as the summarizer. It sends the prompt as the compaction's instructions (beta compact-2026-09-04) and answers with the summary Anthropic returns, which is parsed and checked like any other answer. The signed compaction block is not kept, so the conversation goes on with Cogitator's own summary on every model.
import { anthropicCompactionSummarizer } from '@cogitator-ai/core';
const anthropicCompaction = new CompactionService({
adapter: memory,
summarize: anthropicCompactionSummarizer({ model: 'claude-sonnet-5-5' }), // ANTHROPIC_API_KEY
});Compaction After a Run
memory.compaction (MemoryCompactionConfig) has a Cogitator compact a run's thread once the run is done, so the next run starts from the handoff and the newest turns instead of a conversation that no longer fits. It is off by default: on the memory benchmarks it sent 55% fewer input tokens and helped threads up to about 100K tokens, and was no better than recent on longer ones, so use it to save tokens rather than as memory:
const cog = new Cogitator({
memory: {
adapter: 'postgres',
postgres: { connectionString: process.env.DATABASE_URL! },
compaction: {
at: 0.8, // share of the model's context window (default)
keepRecentTokens: 20_000, // default: the less of 20000 and a quarter of the window
summaryModel: 'google/gemini-3.5-flash', // default: the model the run ended on
beforeCompact: async ({ threadId, tokens, threshold }) => {
await notes.flush(threadId);
return { instructions: 'Keep every price that was quoted.' };
},
afterCompact: (result) => console.log(result.originalMessages, result.compactedMessages),
},
},
});Once the conversation of the branch the run wrote, counted from its latest summary on, passes at of the context window of the model the run ended on, the branch is compacted hierarchically. The other settings of CompactionConfig apply (keepRecent, keepRecentTokens, chapterTokens, chaptersPerArc, arcsPerSaga, summaryModel, summaryPrompt), and the summarizer is the Cogitator's own backend for summaryModel, or for the model the run ended on.
beforeCompact({ threadId, tokens, threshold })is awaited first, a chance to save what matters to memory. Returnfalseto skip this compaction, or{ instructions }to add to what the summarizer is asked, aftersummaryPrompt. An error it throws counts as a failed compaction.afterCompact(result)gets theCompactionResult.keepRecentTokenshas a default only whenkeepRecentis not set, sokeepRecentalone keeps that many entries.- A thread that outgrows its window again within two turns of its last compaction is not compacted again: a few huge outputs fill that conversation, and another summary would only churn. A warning says to clear tool outputs (
context.clearToolOutputs, see Context Management) instead. - A run that wrote aside of the thread's active branch, such as a fork, a replay or a run with
branch: { activate: false }, is left alone. - The summarizer's calls are counted in the run's costs (
getCostSummary()) and in theusageit returns, and they stop with the run'ssignal: an aborted run is not compacted, and a compaction stops when it aborts. - A compaction that fails is logged as a warning, and the run keeps its result. The thread is then left alone for a minute, twice as long after each failure in a row up to an hour, so a thread that cannot be compacted does not pay for the attempt on every run.
It is the built-in run middleware cogitator:memory-compaction, an afterRun hook: it runs after the run saved what it said and before run() returns, so a run that compacts takes as long as the compaction. It needs an adapter with branches (getPath), which every built-in one has.
Memory Items
A memory item is one thing a conversation established, kept apart from the conversation: a fact, an event, a preference, an instruction, an opinion or a lesson, with the quotes it stands on, who said it, and when it held. Compaction keeps what a thread needs to go on, memory items keep what an agent should know about a user in every thread.
Every built-in conversation adapter stores items (MemoryItemAdapter, isMemoryItemAdapter(adapter) tells), and MemoryItems keeps the rules on top of any of them, so the storage only stores:
import { InMemoryAdapter, MemoryItems, unwrap } from '@cogitator-ai/memory';
import type { MemoryItemScope } from '@cogitator-ai/types';
const memory = new InMemoryAdapter();
await memory.connect();
const items = new MemoryItems({ adapter: memory });
const scope: MemoryItemScope = { agentId: 'concierge', userId: 'ana' };
const thread = unwrap(await memory.createThread('concierge', { userId: 'ana' }));
const said = unwrap(
await memory.addEntry({
threadId: thread.id,
message: { role: 'user', content: 'I live in Porto, and I am vegetarian.' },
tokenCount: 12,
})
);
const [porto] = await items.write([
{
kind: 'fact',
content: 'Ana lives in Porto',
subject: 'Ana',
attribute: 'home city',
value: 'Porto',
trust: 'user',
confidence: 0.9,
scope,
evidence: [{ entryId: said.id, quote: 'I live in Porto' }],
verified: true,
saidAt: said.createdAt,
sessionAt: new Date('2026-03-02'),
},
]);
porto?.status; // 'active': the user said it, and the quote holdsA MemoryItem has its kind, its content (one statement that reads on its own), and for a state that can change the subject it is about, the attribute it records and the value it gives it. It keeps its status (suggested, active, stale or superseded), its trust, its confidence (0 to 1), its scope, its evidence and whether every quote of it was found in its entry (verified), when it was said (saidAt) and the date of the session it was said in (sessionAt), and the time it is about (about: the words, an interval and its precision). timesRetrieved and lastRetrievedAt count how often and when it last went to a model in a context, as a run counts it (noteRetrieved).
Slots and Supersession
Writing only adds. write(items) writes in order and gives each item its id, status and record time. The writes of one agent's memory go one after another within a process, and items written in the same millisecond are recorded a millisecond apart, so the later one stays later in its slot:
subjectis linked to an entity the writer's scope sees (see Entities), and with anattributethe item gets a slot, the key of the state it records, made of the entity and the attribute, normalized (slotOf,normalizeName). An item can name aslotof its own instead. An item of a slot starts to hold (validFrom) at its ownvalidFrom, else at the start of the time it is about, else at its session date.- An item said again merges into the one already kept instead of being kept twice: the newest one of the same scope and kind, open and not let go, with the same words (
normalizeName: case, spacing and an article in front aside) or, in a slot, the same value, that no other value followed since. A value said again after it changed is a new state, not the old one brought back with its old date. Values of a slot compare by their text (sameValue), spacing aside, so case and signs count:-5is not5, and a corrected spelling is a change. The evidence of both is kept, and the trust andverifiedcome together from the better source of the two: the more trusted one first, then the one whose quotes hold. So a quote of one source never vouches for another, asystemitem stayssystem, and a user's unverified claim stays the user's butsuggested. A suggestion that now qualifies becomesactive. - After every write of a state, the
activeandsupersededitems of its slot and exact scope are laid out by when each started to hold (then when it was recorded, then by id): each one is closed when the next one starts (superseded,validToset to when the next one started,supersededBynaming it, which lists it insupersedes), and the last one is open andactive. The layout depends only on the items, so writers that raced, a state told late and a close that failed half way all end in the same timeline. Nothing is deleted, so a question "as of" an earlier date still finds what held then. - A state told late, such as "I lived in Braga in 2019" said after the move to Lisbon, fits between the states around it in time and does not close the present one. A state set to start later, such as a move next month, leaves the current one holding until it starts.
- A state let go (
expire) keeps its place in the timeline, so the one before it does not come back, and neitherexpirenorpurgereopens anything. - A
suggesteditem stays out of the timeline untilactivate(itemId)makes itactive, such as once the user confirmed it.
const moved = unwrap(
await memory.addEntry({
threadId: thread.id,
message: { role: 'user', content: 'Big news: I moved to Lisbon!' },
tokenCount: 8,
})
);
const [lisbon] = await items.write([
{
kind: 'fact',
content: 'Ana moved to Lisbon',
subject: 'Ana',
attribute: 'home city',
value: 'Lisbon',
trust: 'user',
confidence: 0.9,
scope,
evidence: [{ entryId: moved.id, quote: 'I moved to Lisbon' }],
verified: true,
saidAt: moved.createdAt,
sessionAt: new Date('2026-09-14'),
},
]);
await items.query({ scope }); // Lisbon: what holds now
await items.query({ scope, asOf: new Date('2026-06-01') }); // Porto: what held then
if (lisbon?.slot) await items.history(scope, lisbon.slot); // Porto, then LisbonTrust and Activation
trust says who an item comes from: user (the person, in their own message), system (the application's code), model (the model's own words), tool (a tool's result) or web (a page a tool fetched). An item becomes active on its own when it comes from system, or from user with quotes that hold, at activationConfidence or above (default 0.7, DEFAULT_ACTIVATION_CONFIDENCE). Every other item stays suggested: it is kept and found with statuses: ['suggested'], but it is never part of a context, so text a model, a tool or a page wrote cannot plant itself in memory. status on the item you write overrides this, for an item the user confirmed. statusFor(item) gives the status an item would get.
An opinion said again, when the new statement has quotes that hold, gains 0.1 confidence (OPINION_GAIN), up to 1. A suggested opinion of a slot from a less trusted source (web, then tool, model, user and system) does not replace the active opinions of a more trusted source there: each of them loses 0.2 (OPINION_LOSS) instead.
Scopes
scope.agentId is always set, and userId, projectId and threadId narrow it. A run of a scope sees an item when the agent is the same and each of the item's user, project and thread is either the same or not set (visibleIn(item, scope)): an item of one user never reaches another, an item without a user is seen by everyone the agent serves, and an item with a threadId only in that thread.
Time
Item times are bitemporal: validFrom and validTo say when an item of a slot held in the world, recordedAt and expiredAt when memory took it in and let it go.
| Method | What it does |
|---|---|
query(query) | The items query.scope sees that hold now, by default, oldest recorded first |
history(scope, slot) | Every item of a slot, current and closed, by when they started to hold |
activate(itemId) | Makes a suggested item active, closing what it follows |
markStale(itemIds, because?, onlyFrom?) | Returns the ids it marked. Marks items as no longer trusted to hold: kept, found with statuses: ['stale'], because kept in metadata.staleBecause, and with onlyFrom an item whose status is no longer one of those left as it is |
expire(itemIds, at?) | Lets items go at at (now by default): kept, but found only by a knownAt before then. A state let go keeps its place in the timeline, so the one before it stays closed. An item with an expiredAt still to come is found until then |
purge(itemIds) | Deletes items for good, such as everything a user asked to be forgotten |
noteRetrieved(itemIds, at?) | Counts items as sent to a model once more at at (now by default): timesRetrieved goes up by one and lastRetrievedAt is set, in one step of the store (MemoryItemAdapter.countRetrieved, which every built-in store has), else each item read again and written back under its agent's lock |
get(itemId) | One item, or null |
link(scope, name, seenAt?, type?) | The entity a name stands for, made when there is none yet |
MemoryItemQuery takes the scope and narrows it with kinds, statuses (active and superseded by default), slots and entityIds. Which state of a slot holds is read from its times, not its status:
asOfis the moment in the world the answer is for: of the items of a slot, those that held then (validFromnot after it,validToafter it). It defaults toknownAt, so a state another one closed is left out, and a state set to close later still holds until then.knownAtis the moment of memory the answer is for: the items memory had then (recorded no later), those it let go later included. Without it the items are not filtered by when they were recorded, and an item memory let go is left out.includeClosedkeeps the items that no longer hold, for a history.textkeeps the items whose content or value holds every word of it, matched without case, andlimitthe newest that many.
Entities
link(scope, name, seenAt?, type?) finds the entity a name stands for, matching its name and aliases normalized (normalizeName: case, spacing, quotes and an article in front aside), among the entities the scope sees: its own, or a broader one such as the user's for a thread, so a slot of an entity is the same slot in a thread and in the user's memory. When there is none it makes one in the scope. It moves the entity's lastSeenAt and fills its type when it has none, and adds no aliases. When writers raced and made two entities for one name, every one of them settles on the first made. write links the subject of every item this way. A MemoryEntity has its id, scope, name, aliases, an optional type (such as person or place), and when it was first and last seen. Items about it carry its entityId, and query({ scope, entityIds }) finds them.
Dates
A model is good at marking up "last Friday" and bad at the calendar, so it only marks up the words and resolveTime(expression, sessionAt, timeZone?) works out the interval:
import { resolveTime } from '@cogitator-ai/memory';
const sessionAt = new Date('2026-10-21T15:00:00Z'); // a Wednesday
resolveTime(
{ text: 'last Friday', weekday: { day: 'friday', amount: -1 } },
sessionAt,
'Europe/Lisbon'
);
// { text: 'last Friday', start: 2026-10-15T23:00:00.000Z, end: 2026-10-16T23:00:00.000Z, precision: 'day' }
resolveTime(
{ text: 'last month', relative: { unit: 'month', amount: -1 } },
sessionAt,
'Europe/Lisbon'
);
// September 2026 in Lisbon, precision 'month'
resolveTime({ text: 'a while ago' }, sessionAt); // { text: 'a while ago', precision: 'approximate' }A TimeExpression has the text and one of date (YYYY, YYYY-MM, YYYY-MM-DD or YYYY-MM-DDTHH:mm, precision year, month, day or instant), relative ({ unit: 'day' | 'week' | 'month' | 'year', amount }, a shift from the session date, a week starting on Monday) or weekday ({ day, amount }: -1 the last one before the session date, 1 the next one after it, 0 the one of its week). A date the words give wins over a shift. start is inclusive and end exclusive, both in the time zone given (an IANA name, UTC by default). Words that name nothing the code can place keep only their text, with precision approximate.
Extraction
MemoryExtractor reads entries with a model and writes the items they establish:
import { MemoryExtractor } from '@cogitator-ai/memory';
const extractor = new MemoryExtractor({
items,
summarize: async (messages, { model, prompt } = {}) => {
const response = await llm.chat({
model: model ?? 'gemini-3.5-flash-lite',
messages: [{ role: 'system', content: prompt ?? '' }, ...messages],
});
return response.content;
},
windowTokens: 4000, // conversation one call reads (default)
prompt: 'Mind diets and allergies.', // added to the extraction prompt
});
const entries = unwrap(await memory.getPath!({ threadId: thread.id, includeToolCalls: true }));
const written = await extractor.extract(entries, { scope, timeZone: 'Europe/Lisbon' });extract(entries, context)leaves out system andcompactionentries and reads the rest in windows of aboutwindowTokenstokens, cut as compaction chapters are, one model call each. The model gets the window as a numbered transcript, each message with the date it was written, andEXTRACTION_PROMPTas its instructions, with the date of the session (sessionLine, such asThe session took place on Wednesday, 2026-10-21 (Europe/Lisbon).) andpromptafter it. Yoursummarizemust send the prompt it is given as its instructions, as for compaction.- The answer is a JSON array of items, each with its
kind,content,subject,attribute,value,confidence, the time words marked up as aTimeExpressionand itsevidenceas message numbers and quotes. The array is found past any text and brackets around it, such as a message number ([3]) the model mentions. A field that isnull, blank or does not fit is read as absent, and an item, or an element that is not JSON, is left out. An answer cut at its length limit inside the array keeps the items it finished, and the model is asked to go on after the last one (extractionContinuationPrompt), up toEXTRACTION_CONTINUATIONS(4) times, so a window dense with facts is read whole. A continuation that brings no array ends the window with what was read. Only an answer that holds no JSON array is asked for again, up to three tries in all, and thenreadthrows anExtractionAnswerError, andextractaWindowErrorwith the entries that window was the first to read (own). parseExtraction(answer, window, context)checks every item: each quote is tied to the entry its number names and checked against it (lineage), and an item isverifiedonly when it has quotes and all of them hold. Its trust is that of the least trusted entry one of its holding quotes is in (trustOfEntry: a user message isuser, ormodelwhen another user wrote it (itsmetadata.userId, which a run with a user saves on its user messages, is not the user ofcontext.scope), a tool resulttool, orwebfor a tool whose name says it fetches pages, such asweb_searchorfetch_url, and an assistant messagemodel), andmodelwhen no quote holds, so a statement a page or the assistant made is never the user's, whatever else is quoted with it. Its time words are resolved incontext.timeZonefrom the date of the first entry it quotes, the message that said them, else from the session date (context.sessionAt, the time of the window's last entry by default), and that date is itssaidAtandsessionAt.- The items are written in order through
MemoryItems, so an item said again merges and a newer state closes the one it follows. Nothing is updated or deleted on the model's word.extractreturns the items as written, andread(window, context)the checked items of one window, unwritten.extract(entries, context, { onWindow, skip })lets a caller keep its place:onWindow(own, items)is awaited once a window's items are written, andskip(error, own, index)may returntrueto go on without a window that failed.beforeWindow(own)returningfalsestops the extraction before a window's model call, with what it wrote so far, andbeforeWrite(items)returns the items of a window to write, such as without those whose entries were forgotten while the model answered.
Extraction After a Run
memory.extraction (MemoryExtractionConfig) has a Cogitator extract memory items from a run's conversation once the run is done:
const cog = new Cogitator({
memory: {
adapter: 'postgres',
postgres: { connectionString: process.env.DATABASE_URL! },
contextBuilder: { strategy: 'recent', includeFacts: true },
extraction: {
model: 'google/gemini-3.5-flash-lite', // default: the model the run ended on
scope: 'user', // default
timeZone: 'Europe/Lisbon', // default: UTC
windowTokens: 4000, // default
activationConfidence: 0.7, // default
mode: 'apply', // default, 'shadow' keeps every new item suggested for review
prompt: 'Mind diets and allergies.',
afterExtract: (kept) => console.log(kept.map((item) => item.content)),
},
},
});
await cog.run(agent, {
input: 'I moved from Porto to Lisbon last month.',
threadId: 'ana-1',
userId: 'ana',
});
// the next run of Ana's, in any thread, knows she lives in Lisbon- The entries read are those of the thread's active branch written since the last extraction, tool calls included. The thread keeps its place in
metadata.memoryExtraction(EXTRACTION_CURSOR,{ through, at, failures?, failedThrough? }) after every window, so a failure later on does not read the earlier windows again. For a thread's first extraction the run's own entries are read, and a cursor left on an abandoned branch is replaced by the run's branch point. A first extraction that fails stores where it started (throughthe entry the run went after,nullfor the thread's start), so the next one takes those entries too. - A window the model could not answer (no JSON array after three tries,
ExtractionAnswerError) fails the extraction, and the cursor counts it (failures,failedThrough). Only when the same window failed three extractions in a row does the next one leave it out, with a warning, so one window cannot hold the thread back. A provider, storage or abort failure never leaves a window out. - Runs of one thread extract one after another. A run whose leaf other runs of the thread appended after is still extracted.
- The items are kept under the agent's memory id, its configured
id, else itsname(memoryAgentId(agent), thememoryAgentIdof theafterRunevent), so a new instance of the agent finds them.scopedecides who they belong to:user(default) the run's own user, never the thread's owner,agenteveryone the agent talks to, andthreadthe thread alone. Withusera run without a user keeps its items in the thread's scope, so visitors never share them. User messages a run with a user saves carrymetadata.userId, so another user's words in a shared thread count as a claim (model), not as the user's. - Extraction is off by default. Turn it on with
mode: 'shadow'first: every new item is written assuggested, so it reaches no context, no recall and no fact, and an item said again merges into the one kept as before. Review what it wrote withMemoryItems.query({ scope, statuses: ['suggested'] })(afterExtracthears every item too), activate the items you trust withMemoryItems.activate(id), and switch toapplyonce the items are worth it. Amodethat is neitherapplynorshadowthrows when the middleware is built. - Relative dates are resolved in the thread's
metadata.timeZonewhen it is a valid IANA zone (isTimeZone), else intimeZone, else in UTC. windowTokensmust be a whole number above 0 andactivationConfidencefrom 0 to 1, else building the middleware throws.afterExtract(items)gets the items an extraction wrote, and an error it throws is logged.- Each call asks for an answer of up to 8000 tokens (
SummarizeOptions.maxTokens). The extraction calls are counted in the run's costs (getCostSummary()) and in theusageit returns, and they stop with the run'ssignal: an aborted run is not extracted. - A run on another branch than the thread's active one (a fork, a replay), and a store without memory items or branches, are left alone.
- An extraction that fails is logged as a warning, and the run keeps its result. The thread is then left alone for a minute, twice as long after each failure in a row up to an hour.
Reviewing what shadow mode wrote and activating what holds:
import { memoryAgentId } from '@cogitator-ai/core';
import { MemoryItems, isMemoryItemAdapter } from '@cogitator-ai/memory';
const memory = await cog.getMemory();
if (!memory || !isMemoryItemAdapter(memory)) throw new Error('this store keeps no memory items');
const items = new MemoryItems({ adapter: memory });
const scope = { agentId: memoryAgentId(agent), userId: 'ana' };
const suggested = await items.query({ scope, statuses: ['suggested'] });
for (const item of suggested) {
if (item.verified && item.trust === 'user') await items.activate(item.id);
}It is the built-in run middleware cogitator:memory-extraction (memoryExtractionMiddleware), an afterRun hook that runs before cogitator:memory-compaction, so a thread compacted after a run has its items taken first. run() returns once it is done. MemoryExtractionConfigSchema in @cogitator-ai/config validates the settings YAML can hold, afterExtract is set in code.
Memory Items in the Context
With includeFacts, a context builder whose store keeps memory items (ContextBuilderDeps.memoryItems, which a Cogitator sets for every built-in store) fills the facts partition with the items the run's agent (under BuildContextOptions.memoryAgentId, which a Cogitator run sets to the agent's configured id, else its name), user and thread see that hold now, in place of the facts of a FactAdapter. A slot shows one state: the one that started to hold last, of the narrowest scope (thread, then project, then user) when two started together, since a run sees a slot's states of its thread, its user and the agent at once. Instructions come first, then preferences, facts, opinions, events and lessons, newest first within a kind, and an item that superseded another names the value it replaced, when the run still sees that value and memory did not let it go:
Known facts:
- Ana is vegetarian
- Ana moved to Lisbon (previously: Porto)Suggested and stale items and closed states stay out. On Postgres the facts written through FactAdapter are memory items too, so they show up the same way. The items are read as of BuildContextOptions.asOf (now by default), so a replayed turn sees the facts that held when it was asked. With strategy: 'hybrid' the items that match the turn also come under From memory:, closed states included for a question about time or about many things, and an item Known facts: holds is not repeated there, see Recall.
The memory tools remember, recall and forget write, search and let go memory items when given them. Given the thread store, remember keeps a fact as the user's only when its quote is in one of the run user's own messages on the thread's active branch, and recall ranks the items with the same search Recall uses (their words, the entities they name and the graph around them, up to 10), where without it the items are matched by every word of the query. remember writes to the user's memory, or the thread's for a run without a user, recall sees the user's items and the thread's, and forget lets go only the run's own items that hold the query as whole words, see Memory Tools. To let an agent search the conversation itself too, give it the memory search tools.
Agent Memory Tools
The context builder decides what a run sees of memory before the model starts. The memory search tools let the model look further on its own, in as many steps as the question takes: search, open what looks right, search again with other words, and say it does not remember when nothing it opened answers.
import { Agent, Cogitator, memoryCitations } from '@cogitator-ai/core';
const cog = new Cogitator({
memory: {
adapter: 'postgres',
postgres: { connectionString: process.env.DATABASE_URL! },
embedding: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY! },
contextBuilder: { strategy: 'hybrid', timeZone: 'Europe/Lisbon' },
},
middleware: [memoryCitations({ onUncited: (references) => console.warn(references) })],
});
const agent = new Agent({
name: 'concierge',
model: 'openai/gpt-5.5',
instructions:
'Answer from memory. Cite what you rely on as [turn:<id>] or [item:<id>], and say so when you do not remember.',
tools: await cog.memorySearchTools('concierge'),
});
await cog.run(agent, {
input: 'Which cabin did we book in April?',
threadId: 'ana-1',
userId: 'ana',
});| Tool | Parameters | Returns |
|---|---|---|
search_memory | query, limit (1 to 20, default 8) | One ranked list of earlier turns of the run's thread (id, date, role and an excerpt of up to 280 characters) and memory items (ref as item:<id>, text, type, and held: the interval it held, since when, or the date it is about). A search that finds nothing returns a note asking to try other words or to say it does not remember |
open_turns | ids (1 to 10, as search_memory returned them), around (0 to 3, default 1) | The user and assistant turns whole, with around turns before and after each, oldest first, each with its ref (turn:<id>), date, role and text. Ids that are not turns of the thread come back as missing |
list_entities | query (part of a name, optional) | Up to 50 people, places, projects and things memory knows, with their aliases, type and how many memory items are about each, the most first |
search_memoryranks with the sameMemoryRetrieverthehybridstrategy recalls with: the five kinds of question, the channels, the fusion and the diversity are the same, so the agent and the context agree on what is relevant. A greeting or a thanks is not searched.- The turns searched are those of the branch the run stands on, without the entries the run saved itself, so a run that saves nothing still finds the last turns of earlier runs. A run with
useMemory: falsereads no thread. Built withcreateMemorySearchToolsand noplaceOf, the tools read the active branch of the tool context's thread and leave out its last question and what followed it. The items are those the run sees under the agent's memory id and its runtime id, of the run's user and thread, one current state per slot, and past states too for a question about time or about many things. - With
memory.embedding, the query is embedded once per search. Turns are also found by their vectors in the runtime's message index (therelevantandhybridstrategies keep one), and items by the vectors of their content: each item is embedded once and kept in process, up to 5000 vectors, the ones used least lately dropped. - Dates are shown in
contextBuilder.timeZone, elseextraction.timeZone, UTC by default. cog.memorySearchTools(memoryAgentId)connects memory and builds the tools over the runtime's own store, memory items, embedding service and message index. Pass the agent's memory id (memoryAgentId(agent), its configuredid, else itsname), the id extraction keeps its items under. It throws aCogitatorError(VALIDATION_ERROR) when no memory is configured.createMemorySearchTools({ memory, agentId, items?, embedding?, messageIndex?, timeZone?, placeOf? })from@cogitator-ai/corebuilds the same tools over a store of your own,MEMORY_SEARCH_TOOLSnames them. Without a store that keeps memory items (every built-in thread store does) the search reads turns only andlist_entitieslists nothing.
Citation Lock
memoryCitations(options?) is a run middleware that holds an answer to what the run actually opened. The search tools hand out references: item:<id> with each memory item search_memory returned, and turn:<id> with each turn open_turns opened, so a turn only seen as an excerpt does not count yet. A final answer that cites [turn:<id>] or [item:<id>] the run was never handed has that reference taken out, and onUncited(references, context) is called with what was taken out. A list such as [turn:<id>, item:<id>] is checked reference by reference, and the kind may be written in capitals or with a space after the colon. Only ids as the tools hand them out count (they hold a digit, _ or -), and code in the answer is left alone, so [item: string] in a type stays. An answer without references is left as it is.
const cog = new Cogitator({
memory,
middleware: [
memoryCitations({
onUncited: (references, context) => audit.log(context.runId, references),
}),
],
});- References are read only from the
reffields of the tools' results, never from text inside them, so a turn that quotes an earlier answer citing something hands out nothing. In an answer they are read the way a model may write them: in a list ([turn:a, item:b], each checked on its own), with spaces after the colon, in capitals and in fullwidth brackets. What a run opened is also read back from its tool results, so a resumed run still knows it. toolsnames the tools whose results hand out references,['search_memory', 'open_turns']by default, for a tool of your own that hands out the same references.- It holds the stream (
holdsStream): a streamed run sends each turn's text once the middleware has seen it, so a reference it takes out never reachesonToken.
Memory Files
memory.files gives every agent a memory directory, /memories: notes it views and edits across conversations with the memory tool, such as what the user prefers, decisions and progress on a long task. The tool has the commands of Anthropic's memory tool, and answers and fails with the same words. Claude 4 and later get it as Anthropic's native memory_20250818 tool, which they know from their training, and every other model, older Claude models among them, as a tool with the same commands.
import { Agent, Cogitator } from '@cogitator-ai/core';
const cog = new Cogitator({
memory: {
adapter: 'sqlite',
sqlite: { path: './memory.db' },
files: { scope: 'user' },
},
});
const agent = new Agent({
name: 'concierge',
model: 'anthropic/claude-sonnet-5-5',
instructions: 'Keep what you learn about the user in your memory directory.',
});
await cog.run(agent, {
input: 'Remember: I am allergic to peanuts.',
threadId: 'ana-1',
userId: 'ana',
});
await cog.run(agent, { input: 'Which snacks should I avoid?', threadId: 'ana-2', userId: 'ana' });| Option | Default | Description |
|---|---|---|
scope | 'user' | Who the files belong to: user the run's user (the thread for a run without one), agent everyone the agent talks to, thread the thread alone |
readOnly | false | The agent views the files and every change fails with The memory at <path> is read-only |
indexChars | 2000 | Characters the list of files takes in the context at most |
| Command | Fields | What it does |
|---|---|---|
view | path, view_range? ([first, last], -1 for the end) | A file with line numbers, or a directory two levels deep with the size of each entry, at most 500 entries |
create | path, file_text | A new file, failing when the path holds a file or a directory already |
str_replace | path, old_str, new_str | Replaces old_str, which must occur exactly once in the file, across lines or within one, and not be empty |
insert | path, insert_line, insert_text | Inserts after line insert_line, 0 for the start |
delete | path | Deletes a file, or a directory with everything under it |
rename | old_path, new_path | Moves a file or a directory, failing when the destination exists |
With memory.files the runtime gives every agent it runs the memory tool, under the agent's memory id (memoryAgentId(agent)), and lists the files the run sees in the turn's memory context, each with its size and first line, cut to indexChars with the rest counted:
Memory files you keep (notes you wrote, view them with the memory tool):
- /memories/user.md (20B): Allergic to peanuts.The list goes into the index partition, a required one, or in front of the input for a run without a context builder, and the run views a file whole when it needs it. A tool of the agent's own named memory takes the place of the built-in one. The store must keep memory files, which every built-in thread store does: a store of your own that keeps none is warned about once, and the tool is left out. MemoryFilesConfigSchema in @cogitator-ai/config validates the settings.
Versions, Branches and Locking
Memory files are kept as versions (MemoryFileVersion), never overwritten: every change adds a version of the file with its content (null for a deletion), its sha256, the id of the version it replaces (previousId), its scope, its sequence among the versions of its path, the path it was renamed from and its author (model for the tool). So the history of every file stays.
- A run sees the files of its user, its thread and the agent, each from the version of the narrowest scope that holds the path, and writes a change into its own scope (
scope) with every limit (user, project, thread) of the version it changes and, for a moved file, of its source, so the change always stands in front and a file is never shared wider than it was. Withscope: 'user', editing or deleting a file the agent keeps for everyone writes the user's own version, which that user sees from then on and nobody else does, and editing a file of the thread writes that user's version within the thread. - A version written in a conversation is placed after the newest entry of the run's branch. In its own thread it is seen only on the branches that hold that entry, so a fork or a run on a branch (
RunOptions.branch) keeps its own edits, while other threads see it as it is. - The tool keeps the
sha256of the version of each file a command of the run showed or wrote (MemoryFileAccess.observe). Astr_replace,insert,deleteorrenameof a file another writer changed since fails withThe file <path> changed since it was viewed. View it again before you edit it. - Two writers never add the same version: the store refuses a second version of one scope and path at the same
sequence(MEMORY_FILE_CONFLICT), and the change is made again on what stands then, up to three tries. In one process the changes of one agent's memory go one after another. A change of many files, such as a renamed directory, is added whole or not at all. Writers in two processes can still each make a file where the other makes a directory: a change that finds, once kept, a file of its own under another file or with files under it is taken back, its own versions withdrawn so the history stays whole however others wrote on top (a deletion whose path another writer built on since is kept), and refused withAnother writer changed the memory around <path> at the same time. View it again and try again., so the writer retries on what stands. - Paths start with
/memories, and.,..and backslashes are refused, so nothing is read or written outside it. Control characters and names longer than 255 characters are refused, one change keeps at most 8 MiB, a path ending in/is not a file, a file cannot sit under another file, and text with NUL characters is refused before any store sees it. A file holds at most 1 MiB (MAX_FILE_BYTES), and a failure of the store reaches the model as a plain note, its details kept as the error'scause. - The memory tool refuses every change of
/memories/playbook.md,/memories/playbook.next.mdand anything under/memories/observations/, a rename into one of them included, with<path> is kept by memory itself and is read-only here, and views them as any other file (MemoryFileAccess.reserved,MEMORY_RESERVED_PATHS). - Unless
scopeisagent, the memory tool refuses a run whose scope would name neither a user nor a thread: a run with neither, and withscope: 'thread'a run without a conversation. A run withuseMemory: falsesees no thread's files.
MemoryFiles from @cogitator-ai/memory reads and changes the files of any store that keeps them (isMemoryFileAdapter), as the tool does, for an admin screen, an import or an erasure:
import { isMemoryFileAdapter, MemoryFiles } from '@cogitator-ai/memory';
const memory = await cog.getMemory();
if (memory && isMemoryFileAdapter(memory)) {
const files = new MemoryFiles({ adapter: memory });
const access = { scope: { agentId: 'concierge', userId: 'ana' } };
await files.create({ ...access, author: 'system' }, '/memories/user.md', 'Prefers trains.');
await files.list(access); // [{ path, content, sha256, size, version }]
await files.history(access, '/memories/user.md'); // every version, oldest first
await files.redact(access, ['/memories/user.md'], 'erasure request'); // versions redacted
}| Method | What it does |
|---|---|
run(access, command) | Runs a command of the memory tool (MemoryFileCommand) and returns the answer the model reads |
view, create, strReplace, insert, delete, rename | The commands one by one. strReplace, insert, delete and rename take the sha256 the caller last read, to fail when another writer changed the file since |
list(access, directory?) | The files the access sees, by path |
read(access, path) | One file, or undefined |
history(access, path) | Every version of the file the access sees, oldest first |
redact(access, paths, reason?, { everyScope? }) | Replaces the content of every version of the files (and of the files under them, following each file's own history back through the paths it had and on to the ones it got, never into another file that took one of those paths later) with [redacted], kept as redacted with the reason, and returns how many it redacted. everyScope redacts the versions of every user, project and thread of the agent, not only those the access sees. The conversation keeps the tool calls that wrote the text, which a redaction does not touch, cog.redactEntries redacts those (see Forgetting, Redacting and Rewinding) |
index(access, maxChars?) | The list of files a run's context gets, undefined when there are none |
MemoryFileAccess is { scope, visibleTo?, place?, readOnly?, reserved?, author?, observe? }: where new versions go, what the access sees (scope by default), the branch it stands on, paths no change may touch (reserved), who writes, and a function that hears of the version of each file a command showed or wrote (its path and sha256, null once deleted). A refused command throws a MemoryFileError with the message the model reads, and memoryPath(path) normalizes a path or throws one. memoryFileTool({ memory, agentId, scope?, readOnly?, placeOf?, files? }) from @cogitator-ai/core builds the tool over a store of your own, for an agent run outside a Cogitator configured with memory.files. A store of your own keeps files by implementing MemoryFileAdapter, see Memory Files on the adapters page.
Between Runs
Memory does not only answer while a run builds its context. Three settings keep it useful between runs, each off unless set: a brief of what memory holds for the turn, observations of the entities memory items are about, and a consolidation pass that tidies the items and folds lessons into a playbook. Each asks a model, and code checks what the model answers before anything is kept. All of them work on every built-in thread store.
import { Agent, Cogitator } from '@cogitator-ai/core';
const cog = new Cogitator({
memory: {
adapter: 'postgres',
postgres: { connectionString: process.env.DATABASE_URL! },
contextBuilder: { strategy: 'hybrid', maxTokens: 8000 },
extraction: {},
brief: { model: 'google/gemini-3.5-flash-lite' },
observations: {},
consolidation: { everyRuns: 20 },
},
});
const agent = new Agent({ name: 'concierge', instructions: 'You plan the week of the user.' });
await cog.run(agent, {
input: 'Book me a dinner table for Friday',
threadId: 'week',
userId: 'ana',
});Pre-Turn Brief
With memory.brief, before the first model call of a run a cheap model reads what memory found for the input and writes a few cards that would help answer it. The sources are the 12 best hits among the earlier turns of the run's branch and the memory items the run sees, ranked as hybrid recall ranks them, each named by its reference (turn:<id> or item:<id>). A card is one of four kinds:
| Kind | What it holds |
|---|---|
constraint | Something the answer must keep to: a rule, a limit, what never to do |
knowledge | A fact about the user or their work the answer should use |
consequence | What follows from an earlier choice or event for this message |
open_thread | Something left open earlier that this message touches |
Every card quotes the words of its source it stands on. A card is kept only when its source is one of those given and the source holds the quote word for word, spacing and case aside, one card per quote. The kept cards go into the turn's memory context as a hint, never into the system message: A quote must hold at least three words, and the prompt tells the model the sources and the message are data.
A quick read of memory for this turn (a hint that may be wrong, check before relying on it):
- constraint: Answer in Portuguese. (turn:ent_abc123: "please always answer me in Portuguese")| Option | Default | Description |
|---|---|---|
model | the run's model | The model that writes the cards, best a cheap and fast one |
maxCards | 4 | Cards at most, from 1 to 4 |
timeoutMs | 4000 | How long the turn waits for the brief |
maxTokens | 600 | Tokens the model may answer with |
prompt | Instructions added to the brief prompt |
A maxCards outside 1 to 4, a timeoutMs not above 0 or a maxTokens that is not a whole number above 0 throws when the runtime builds the brief. A timeout, a failure of the model, a run without memory or with nothing found leaves the turn as it was, and the run goes on without a brief. The model call counts in the run's usage. MemoryBriefer from @cogitator-ai/memory writes the cards for a pipeline of your own, and briefBlock(cards) renders them as above.
Observations
With memory.observations, memory keeps for each entity with enough facts what a model makes of them: patterns, how the facts connect, what changed over time. An observation is a memory file, /memories/observations/<entity>.md, in the scope the run's items are kept in:
# Ana
<!-- memory observation: entity ent_k2m9 items 3f1c0a9d2b7e4c51 -->
Also called: my sister
- Ana moved from Lisbon to Porto in 2025 and has worked nights since. [item:mem_a1] [item:mem_b2]- Every statement names the items it stands on. A statement naming an item the model was not given is dropped, and an answer with no statement left changes nothing.
- The file keeps a fingerprint of the items it was written from. After a run, in the background, the observations whose facts changed since (a fact added, closed or marked stale) are written again, the entities with the newest facts first, at most
maxEntitiesat a time. An entity needsminItemsfacts that hold, and an observation whose entity falls short is deleted. Facts that gave no observation are not asked about again in this process until they change. - A turn whose input names an entity, by its name or another name it was called, or that recalls one of its items, gets up to three observations next to the facts, under
What memory makes of them (written from the facts, may lag behind them):. Observations reach a turn only withmemory.contextBuilderset, and are written either way. - Observations are memory files like any other: every rewrite is a version, and with
memory.filesthe agent reads them with the memory tool. A version of the playbook or of an observation a model wrote (author: 'model') is never shown to runs or read as an observation, only those memory itself or a user wrote. The memory tool cannot change them, see above.
| Option | Default | Description |
|---|---|---|
model | the model the run ended on, the agent's model for a pass on demand | The model that writes observations |
maxEntities | 3 | Observations one refresh writes at most |
minItems | 3 | Facts that hold an entity needs for an observation |
prompt | Instructions added to the observation prompt |
Consolidation
With memory.consolidation, a pass goes over the memory of the run's scope every everyRuns runs of a thread (counted in the thread's metadata.memoryConsolidation) and after memory.compaction compacted the thread (a compaction that changed nothing starts no pass). It runs in three steps:
- Repeats and contradictions. A model looks at the active items of exactly the run's scope, grouped by the entity they are about, only entities with an item recorded since the last pass, those whose newest item is oldest first, and names the items that repeat another one or that a newer one contradicts. They are marked
stale, never deleted, with the reason and the item kept inmetadata.staleBecause. Code checks every group: an item is never dropped for a less trusted one, a contradiction drops only items said before the one kept, and a group that names an item the model was not shown is refused whole. An answer the model left unfinished stops the pass before that subject, so a later pass asks again. One pass marks at mostmaxChangesitems and asks about at mostmaxSubjectsentities. A pass a cap stopped goes on where it stopped the next time: the thread's cursor moves to the start of a pass that looked at everything, else to the newest item of the last entity it looked at, and a pass that failed leaves the cursor where it was. - Lessons into the playbook. The
activelessons recorded since the playbook last took one (memory items of kindlesson), oldest first and 20 a pass, are folded into the playbook,/memories/playbook.md, in at most three edits. A lesson a model wrote stayssuggesteduntilMemoryItems.activatemakes itactive, a lesson from a tool or a page is never folded, even when active, and an answer the model did not finish folds nothing and leaves its lessons for the next pass. Each edit adds a rule or rewrites one rule it quotes exactly, every other rule stays as it was, and each rule names its lessons as[lesson:<id>]. So the playbook grows by deltas and is never written over whole, which would let its rules collapse into a summary of themselves. A rule holds at most 300 characters and the playbook at most 60 rules, past which lessons only rewrite rules. Lessons are ordered and folded by when they were activated (MemoryItems.activatekeepsmetadata.activatedAt), else by when they were recorded, so a lesson activated after a fold is still folded. - Observations whose facts changed are written again, when
memory.observationsis set.
Passes run in the background, one at a time per memory scope, a pass asked for while one runs going after it, so no run waits for them. Their model calls count in the cost router, not in a run's usage, and cog.close() stops the passes under way. A failure is logged and leaves memory as the last step that held left it. With security.pii the model calls of the brief, the observations and the consolidation, like those of memory extraction and compaction, are masked as a run's own calls are, since they go through the same routed backend. In redact mode nothing is restored, so placeholders such as [EMAIL_1] end up in what memory keeps (items, observations, the playbook, summaries), numbered per call.
Every fold of the playbook is a new version of the file, so its diff and the way back are in the file's history. With playbook: 'shadow' the edited playbook goes to /memories/playbook.next.md instead, and MemoryConsolidator.promotePlaybook(scope) makes the draft the playbook after review, only when the playbook did not change since the draft was made. While showPlaybook is on (it alone decides, so with playbook: false an existing playbook is still shown), every run of the scope sees the playbook in its memory context, up to 4000 characters, as a hint: A playbook every user of the agent shares (a scope without a user, project or thread, as with memory.extraction.scope: 'agent') takes only system lessons in apply mode, since one user's lesson would reach every other user, and shadow drafts the rest for review. A version of the playbook or of an observation a model wrote (author: 'model') is never shown to runs or read as an observation, only those memory itself or a user wrote. A fold builds on the newest version of the playbook memory or a person wrote, skipping one a model wrote, and promotePlaybook refuses a draft a model wrote.
The playbook memory keeps, rules learned from earlier work (a hint, check it against the task):
- Check dietary needs before booking food. [lesson:mem_c3]| Option | Default | Description |
|---|---|---|
model | the model the run ended on, the agent's model for a pass on demand | The model that finds repeats and folds lessons |
everyRuns | 20 | Runs of a thread between two passes |
afterCompaction | true | Pass after a compaction that changed the thread too |
maxChanges | 10 | Items one pass marks as stale at most, 0 to leave items alone |
maxSubjects | 10 | Entities one pass asks the model about at most, the next pass going on where it stopped |
playbook | 'apply' | apply edits the playbook, shadow writes a draft for review, false stops new lessons from reaching it (an existing playbook is still shown) |
showPlaybook | true | Show the playbook to every run of its scope, whatever playbook says |
prompt | Instructions added to the prompts of the pass | |
afterConsolidate | Called with what a pass changed |
cog.consolidateMemory(agent, { userId?, threadId?, since? }) runs a pass now, such as from a worker or a timer while the agent is idle, and returns what it changed. A pass of the same memory under way is waited for first. The memory is the one the agent's runs keep their items in, as memory.extraction.scope says: with the user scope (the default) it needs a userId, or a threadId for the memory of runs without a user, with thread a threadId (even with a userId), and with agent nothing. It throws VALIDATION_ERROR when neither memory.consolidation nor memory.observations is set, or when memory keeps no memory items. A pass on demand asks consolidation.model for repeats and lessons and observations.model for observations, each falling back to the agent's model (llm.defaultModel when the agent has none), while a pass after a run falls back to the model the run ended on. When report.dedupe.complete is false a cap stopped the look for repeats, and calling again with since: report.dedupe.through goes on from there.
const report = await cog.consolidateMemory(agent, { userId: 'ana' });
// {
// scope: { agentId: 'concierge', userId: 'ana' },
// stale: [{ itemId: 'mem_b2', keptId: 'mem_a1', reason: 'duplicate' }],
// playbook: { path: '/memories/playbook.md', editCount: 1, lessonIds: ['mem_c3'] },
// observations: ['/memories/observations/ana.md'],
// observationsDeleted: [],
// dedupe: { complete: true },
// }MemoryConsolidator and MemoryObservations from @cogitator-ai/memory run the same steps over any store that keeps memory items and memory files, for a pipeline of your own:
import {
MemoryConsolidator,
MemoryFiles,
MemoryItems,
MemoryObservations,
} from '@cogitator-ai/memory';
const items = new MemoryItems({ adapter: memory });
const files = new MemoryFiles({ adapter: memory });
const scope = { agentId: 'concierge', userId: 'ana' };
const consolidator = new MemoryConsolidator({ items, itemAdapter: memory, files });
const { complete, through } = await consolidator.dedupe(scope, { summarize, since: lastPass });
await consolidator.foldLessons(scope, { summarize, mode: 'shadow' });
await consolidator.promotePlaybook(scope);
await new MemoryObservations({ files, items, itemAdapter: memory }).refresh(scope, { summarize });Forgetting, Redacting and Rewinding
Memory derives a lot from a conversation: summaries, memory items, facts, graph nodes and edges, vectors, notes and a playbook. Each keeps the entries it stands on (lineage, a compaction's firstKeptEntryId and atoms, a memory file version's place). So deleting a turn alone is not forgetting it: a fact written from it would still reach the next run. cog.forget, cog.redactEntries and cog.rewind follow the lineage into every store:
import { Agent, Cogitator } from '@cogitator-ai/core';
const cog = new Cogitator({
memory: {
adapter: 'postgres',
postgres: { connectionString: process.env.DATABASE_URL! },
extraction: {},
},
});
const assistant = new Agent({ name: 'assistant', instructions: 'You are a helpful assistant.' });
await cog.forget({ entryIds: [locker.id] }); // the turn, its replies and what stands on them
await cog.redactEntries([passport.id], { reason: 'the user asked' }); // its place stays, '[redacted]' in it
await cog.rewind('chat', earlier.id); // the turns after it stay on their branch, their items go stale
await cog.forget({ threadId: 'chat' }); // the thread
const report = await cog.forget({ userId: 'ana' }, { agents: [assistant] }); // everything kept for the userWhat goes with the entries:
| What stands on the entries | Forget or redact | Rewind |
|---|---|---|
| Replies to a user message | Go with it: the entries after it on every branch up to the next user message, events such as a model change among them, unless keepReplies: true | Stay, on a branch of their own |
| Copies in forks | Go too: the copies of the entries and their replies in the threads forked from theirs (metadata.memoryForks, each copy naming its original in metadata.forkOf), and in the forks of those | Stay |
| Compaction summaries | Deleted when they cover an entry (it lies before firstKeptEntryId on their branch, or, when that entry is gone, at or before the last entry they left out) or quote one in an atom, and the next compaction writes them again | Stay, seen only on their branch |
| Memory items, facts, graph nodes and edges | Purged when they stand only on what went, those that stand on more lose the quotes of it (items.trimmed, facts.trimmed, graph.trimmed). Entities no item is about any more are deleted. Facts are reached when the memory adapter is a fact store, the graph with graph | Items that stood only on the turns after the target become stale |
| Vectors | Deleted with the entries, summaries and facts that go | Stay |
| Memory file versions | Redacted when written at one of the entries. A file whose version in front was redacted is then deleted, so its path leaves the listing once no version on any branch still holds its text and its history keeps the redacted versions | Stay, seen only on their branch |
| Observations and the playbook | Every version that names a purged item or lesson is redacted. The playbook in front is first written again without the rules that stood on such a lesson, and an observation is written again by the next refresh | Stay |
| Paused runs | Dropped for every thread the call touches, also from a runCheckpoints store of your own, as their messages would bring back on resume what went | Stay |
- Redacting keeps the turn in its place, on its branch and after its parent: its text, the arguments of its tool calls and the results of its tools become
[redacted], its tool calls lose their replay state and argument error too, and a user message loses its sendername. Its role and the ids that tie tool calls to results stay, so the conversation still reads as a whole, andmetadata.redactedrecords when and why. The replies of a redacted user message are redacted with it. An event entry among the ids or their replies (model_change,approval,interrupt,label,custom, or acompactionamong the ids) is deleted, not redacted, and is listed inentries.deleted. It needs an adapter withredactEntry(every built-in one). - A rewind deletes nothing. The turns after
toEntryIdstay on a branch of their own, as withmemory.rewind, and the memory items that stood only on them are markedstalewithstaleBecause: { reason: 'rewound', threadId, toEntryId, at }, so later runs no longer take them for what holds. A rewind marks the items stale before it moves the thread, so one that failed can be made again (a rewind the store refuses leaves them as they were), and a thread that stands attoEntryIdalready is left as it is. It takes onlyagents, as it reaches memory items alone. forget({ threadId })also purges the items and entities and redacts the memory file versions kept for that thread alone (their files then deleted), and takes the copies of its entries in its forks. The forks themselves stay.forget({ userId })deletes every thread whosemetadata.userIdis the user (a run with auserIdsets it) whole, the messages others wrote in it too, and the messages the user wrote in threads of others (those that list the user inmetadata.memoryUserIds) with their replies. It purges every item and entity and redacts every memory file version of the user's scope (their files then deleted), and deletes the facts and graph nodes and edges whosemetadata.userIdis the user, and the embeddings with that metadata, throughdeleteByFilterwhere the store has it. It lists every thread of the store to find them.- Legacy summaries kept as messages (
metadata.compactionSummary, on an adapter without branches) are dropped when their atoms quote what went.
Items, files, facts and the graph are kept by the memory id of an agent, its configured id, else its name. Every run notes in the thread's metadata the memory id of its agent and of every agent it hands over to (metadata.memoryAgentIds), and the user it ran for (metadata.memoryUserIds). A call goes through the memory of the agents the threads it touches name, for forget({ userId }) those of every thread of the user. A thread written before this release names only the agents that ran in it since, so pass agents (agents or their memory ids) for the ones before, and for a user without threads. The lists are read again just before each write, which narrows, but does not close, the window in which two runs writing at once keep only one name. graph is a knowledge graph of your own to go through, and the graph is reached only with it.
All three throw CogitatorError (VALIDATION_ERROR) when no memory is configured or the agents to go through are not known (a thread that names none and no agents, or a user without threads), redactEntries also when the adapter cannot redact, and rewind also when the adapter has no branches. A store that fails part of the way throws its own error, and the call can be made again: derived memory goes before the entries it stands on, so the next call still finds it.
forkThread lists each fork in its origin's metadata.memoryForks, and a fork does not copy the paused run of its origin. A fork made before this release is not listed, so the copies in it are not found.
Memory extraction and compaction after a run stop before their next model call once the run's branch is no longer the thread's active one, such as after a rewind or a checkout while they work, so nothing is learned or summarized from a branch the conversation left. Compaction refuses to write a summary whose entries were deleted or redacted while it was written, and extraction drops the items whose entries went while the model answered. A cascade also looks for derived memory again after the entries went, so what was written meanwhile goes too.
Each call returns what it changed, store by store:
// report
// {
// entries: { deleted: ['ent_4', 'ent_5'], redacted: [] },
// threads: [],
// threadsChanged: ['chat'], // threads that lost or had redacted some of their entries
// summaries: ['ent_9'], // compaction entries deleted, written again by the next compaction
// items: { purged: ['mem_a1'], trimmed: ['mem_b2'], stale: [] },
// entities: [],
// facts: { deleted: [], trimmed: [] },
// graph: { nodes: [], edges: [], trimmed: [] },
// fileVersions: ['ver_3'], // memory file versions redacted
// playbookRules: 1, // rules taken out of a playbook in front
// }What a cascade does not reach
A cascade follows lineage through the stores the runtime owns. It does not reach:
- traces and observers that captured the content of a run, and a studio store
- time-travel checkpoints of the execution
- results kept by
withCache - memory files the agent wrote on a later turn quoting the text: only the versions placed at an entry that went are reached
- in-process indexes of other processes, as change events reach only the process that made the change
- reflection insights
- data in stores the runtime does not own, such as a database a tool writes to
MemoryCascade from @cogitator-ai/memory runs the same cascades over stores of your own, for the agents in who:
import { MemoryCascade } from '@cogitator-ai/memory';
const cascade = new MemoryCascade({
memory, // the conversation store
items: memory, // a MemoryItemAdapter
files: memory, // a MemoryFileAdapter
graph, // a GraphAdapter
facts, // a FactAdapter
embeddings, // an EmbeddingAdapter
});
const who = { agentIds: ['assistant'], keepReplies: false };
await cascade.deleteEntries([locker.id], who);
await cascade.redactEntries([passport.id], { at: new Date(), reason: 'erasure request' }, who);
await cascade.deleteThread('chat', who);
await cascade.deleteUser('ana', who);
await cascade.rewind('chat', earlier.id, who);Every store but memory is optional, and what is not given is left alone. It goes through the agents in who alone, reading no metadata.memoryAgentIds, and leaves paused runs to you (threads and threadsChanged name the threads). An adapter that cannot redact or has no branches makes redactEntries or rewind throw. MemoryItems.reviseEvidence(itemIds, keep) keeps of each item's evidence the pieces keep takes and returns the ids of the items it changed.
Installation
pnpm add @cogitator-ai/memoryOptional peer dependencies based on your adapter choice:
pnpm add ioredis # Redis
pnpm add pg # Postgres (+ pgvector extension for embeddings)
pnpm add better-sqlite3 # SQLite, SQLiteGraphAdapter, CoreFactsStore
pnpm add mongodb # MongoDB
pnpm add @qdrant/js-client-rest # QdrantRedis connections go through @cogitator-ai/redis, which is installed with the memory package and uses ioredis under the hood.