Class: CognitiveMemoryManager

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:325

Implements

• ICognitiveMemoryManager

Constructors

Constructor

new CognitiveMemoryManager(): CognitiveMemoryManager

Returns

CognitiveMemoryManager

Methods

assembleForPrompt()

assembleForPrompt(query, tokenBudget, mood, options?): Promise<AssembledMemoryContext>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1086

Assemble memory context for prompt injection within a token budget.

Parameters

query

string

tokenBudget

number

mood

PADState

options?

CognitiveRetrievalOptions = {}

Returns

Promise<AssembledMemoryContext>

Implementation of

ICognitiveMemoryManager.assembleForPrompt

---

checkProspective()

checkProspective(context): Promise<ProspectiveMemoryItem[]>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1380

Check prospective memory triggers (Batch 2).

Parameters

context

events?

string[]

maxTierRank?

number

Policy-tier ceiling forwarded to prospective.check, so the direct prospective-check path gates by session tier exactly like the assembly path (assembleForPrompt) already does.

now?

number

queryEmbedding?

number[]

queryText?

string

Returns

Promise<ProspectiveMemoryItem[]>

Implementation of

ICognitiveMemoryManager.checkProspective

---

compactIfNeeded()

compactIfNeeded(systemPromptTokens, memoryBudgetTokens): Promise<ContextMessage[] | null>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1528

Run context window compaction if needed. Call BEFORE assembling the LLM prompt. Returns the (potentially compacted) message list for the conversation. If infinite context is disabled, returns null (caller should use original messages).

Parameters

systemPromptTokens

number

memoryBudgetTokens

number

Returns

Promise<ContextMessage[] | null>

---

deleteScope()

deleteScope(scope, scopeId, options?): Promise<MemoryDeletion>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1609

Delete every trace of one scope for good (MemoryStore.deleteScope), a batch at a time. What this manager keeps of each trace in a batch goes before the batch's traces (forgetTraces), so a call that fails part way can be made again and finds the same traces. With turnUserId, only the scope's traces that user filed as a second user on the session.

Parameters

scope

MemoryScope

scopeId

string

options?

turnUserId?

string

Returns

Promise<MemoryDeletion>

Throws

TypeError when scopeId is empty, or when turnUserId is given and is not a non-empty string.

Implementation of

ICognitiveMemoryManager.deleteScope

---

deleteTraces()

deleteTraces(traceIds): Promise<MemoryDeletion>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1622

Delete the given traces for good, as deleteScope does for a scope. An id the store finds no trace of (no Brain row, nothing it holds) is skipped, and nothing this manager keeps under that id is touched.

Parameters

traceIds

readonly string[]

Returns

Promise<MemoryDeletion>

Implementation of

ICognitiveMemoryManager.deleteTraces

---

encode()

encode(input, mood, gmiMood, options?): Promise<MemoryTrace>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:688

Encode a new input into a memory trace. Called after each user message.

Parameters

input

string

mood

PADState

gmiMood

string

options?

contentSentiment?

number

entities?

string[]

perspectiveSource?

{ eventHash: string; eventId: string; }

When encoding a subjective trace from PerspectiveObserver (@framers/agentos/memory/pipeline/observation/PerspectiveObserver), thread the source-event identifiers through so the resulting MemoryTrace carries the MechanismMetadata fields that applyReconsolidation reads at retrieval time.

perspectiveSource.eventHash

string

perspectiveSource.eventId

string

scope?

MemoryScope

scopeId?

string

sourceType?

MemorySourceType

tags?

string[]

turnUserId?

string

MemoryTrace.turnUserId: set on a trace a turn with no learner files for a second user.

type?

MemoryType

Returns

Promise<MemoryTrace>

Implementation of

ICognitiveMemoryManager.encode

---

ensureEncodedScopeIds()

ensureEncodedScopeIds(): Promise<number>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1630

Re-files the Brain's plain user and persona scope ids that hold a /, a % or a : in the encoded form a learning layer reads, once per Brain, and moves what the manager's store holds of the traces it moved; on a Brain another handle or process re-filed, the store follows the Brain's rows (MemoryStore.ensureEncodedScopeIds). The layer calls it when it first opens the manager. Optional, so a host's own implementation keeps compiling.

Returns

Promise<number>

How many traces its re-file moved: none when the Brain held the record already.

Implementation of

ICognitiveMemoryManager.ensureEncodedScopeIds

---

exportToString()

exportToString(options?): Promise<string>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1758

Export the full brain state as a JSON string. Delegates to JsonExporter through the MemoryStore's brain. Throws if no brain is attached.

Parameters

options?

ExportOptions

Returns

Promise<string>

---

flushReflection()

flushReflection(mood?, scopeOverride?): Promise<FlushReflectionResult>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1706

Step-8: Force the reflector to run over pending notes regardless of threshold. Encodes reflection traces, soft-deletes superseded IDs. Safe to call when no reflector or no pending notes exist (returns an empty result). Errors do not propagate — reflection is non-critical.

scopeOverride forces every encoded reflection trace to use the caller-supplied scope + scopeId, overriding whatever the reflector LLM invented. Callers that want all reflection traces to land in a single canonical scope (e.g. bench adapters that retrieve under user/bench) should pass this override.

Parameters

mood?

PADState

scopeOverride?

scope

MemoryScope

scopeId

string

Returns

Promise<FlushReflectionResult>

Implementation of

ICognitiveMemoryManager.flushReflection

---

forSession()

forSession(): ICognitiveMemoryManager

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:646

This manager as one session sees it: the same store, graph and mechanisms, with a working memory of its own. encode, retrieve and assembleForPrompt on the view focus traces in that working memory, and the view's active context lists only the traces the session encoded or recalled. Sessions that call the manager directly share its one working memory, whose slot list (trace ids and activations) is part of every assembled context.

shutdown() on the view does nothing: whoever owns the manager shuts it down.

Returns

ICognitiveMemoryManager

A view to hand to one session (one GMI).

---

getCompactionHistory()

getCompactionHistory(): readonly CompactionEntry[]

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1561

Get compaction history for audit/UI.

Returns

readonly CompactionEntry[]

---

getConfig()

getConfig(): CognitiveMemoryConfig

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1677

Get the resolved cognitive-memory runtime config.

Returns

CognitiveMemoryConfig

Implementation of

ICognitiveMemoryManager.getConfig

---

getContextTransparencyReport()

getContextTransparencyReport(): string | null

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1556

Get full transparency report (for agent self-inspection or UI).

Returns

string | null

Implementation of

ICognitiveMemoryManager.getContextTransparencyReport

---

getContextWindowManager()

getContextWindowManager(): ContextWindowManager | null

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1571

Get the context window manager (for advanced usage).

Returns

ContextWindowManager | null

---

getContextWindowStats()

getContextWindowStats(): ContextWindowStats | null

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1551

Get context window transparency stats.

Returns

ContextWindowStats | null

Implementation of

ICognitiveMemoryManager.getContextWindowStats

---

getGraph()

getGraph(): IMemoryGraph | null

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1681

Get graph module when enabled.

Returns

IMemoryGraph | null

Implementation of

ICognitiveMemoryManager.getGraph

---

getHydeRetriever()

getHydeRetriever(): HydeRetriever | null

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1809

Get the HyDE retriever if configured, or null.

Returns

HydeRetriever | null

Implementation of

ICognitiveMemoryManager.getHydeRetriever

---

getMemoryHealth()

getMemoryHealth(): Promise<MemoryHealthReport>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1463

Get memory health diagnostics.

Returns

Promise<MemoryHealthReport>

Implementation of

ICognitiveMemoryManager.getMemoryHealth

---

getObserver()

getObserver(): MemoryObserver | null

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1685

Get observer module when enabled.

Returns

MemoryObserver | null

Implementation of

ICognitiveMemoryManager.getObserver

---

getProspective()

getProspective(): ProspectiveMemoryManager | null

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1749

Get prospective-memory manager when enabled.

Returns

ProspectiveMemoryManager | null

Implementation of

ICognitiveMemoryManager.getProspective

---

getReflector()

getReflector(): MemoryReflector | null

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1690

Step-8: accessor mirror of getObserver, for the reflector.

Returns

MemoryReflector | null

Implementation of

ICognitiveMemoryManager.getReflector

---

getRerankerService()

getRerankerService(): RerankerService | null

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1820

Return the attached neural reranker, or null when none is configured. Public read-only accessor for Step-3 bench wiring: the bench constructs a per-case HybridRetriever that needs the same reranker the manager uses, without bracket-accessing the private field.

Returns

RerankerService | null

Implementation of

ICognitiveMemoryManager.getRerankerService

---

getStore()

getStore(): MemoryStore

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1597

Access the underlying long-term memory store for diagnostics/devtools.

Returns

MemoryStore

Implementation of

ICognitiveMemoryManager.getStore

---

getSummaryContext()

getSummaryContext(): string

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1546

Get the rolling summary chain text for prompt injection.

Returns

string

---

getTraceCount()

getTraceCount(): number

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1668

Total number of memory traces currently resident in the manager's in-memory trace cache. Ergonomic passthrough to MemoryStore.getTraceCount; used by agentos-bench for memory-footprint telemetry without reaching into getStore().

Returns

number

Implementation of

ICognitiveMemoryManager.getTraceCount

---

getTypedNetworkObserver()

getTypedNetworkObserver(): TypedNetworkObserver | null

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:675

Stage E: typed-network observer (LLM extractor), or null.

Returns

TypedNetworkObserver | null

---

getTypedNetworkStore()

getTypedNetworkStore(): TypedNetworkStore | null

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:670

Stage E: typed-network store, or null when typed-network not configured.

Returns

TypedNetworkStore | null

---

getTypedSpreadingActivation()

getTypedSpreadingActivation(): TypedSpreadingActivation | null

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:680

Stage E: typed spreading activation, or null (only set for 'full' variant).

Returns

TypedSpreadingActivation | null

---

getWorkingMemory()

getWorkingMemory(): CognitiveWorkingMemory

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1673

Access the working-memory model for diagnostics/devtools.

Returns

CognitiveWorkingMemory

Implementation of

ICognitiveMemoryManager.getWorkingMemory

---

importFromString()

importFromString(json, options?): Promise<ImportResult>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1772

Import a JSON brain payload into the attached brain. Delegates to JsonImporter through the MemoryStore's brain. Throws if no brain is attached.

Parameters

json

string

options?

Pick<ImportOptions, "dedup">

Returns

Promise<ImportResult>

---

initialize()

initialize(config): Promise<void>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:373

Parameters

config

CognitiveMemoryConfig

Returns

Promise<void>

Implementation of

ICognitiveMemoryManager.initialize

---

listProspective()

listProspective(): Promise<ProspectiveMemoryItem[]>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1407

List active prospective reminders.

Returns

Promise<ProspectiveMemoryItem[]>

Implementation of

ICognitiveMemoryManager.listProspective

---

observe()

observe(role, content, mood?, options?): Promise<ObservationNote[] | null>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1303

Feed a conversation message to the observation pipeline.

Pipeline flow:

1. Observer extracts typed observation notes from buffered messages
2. Notes are fed to the Reflector for consolidation into long-term traces
3. Reflected traces are encoded via encode() (typed as semantic/episodic/etc.)
4. Superseded traces are soft-deleted
5. Commitment and intention notes are auto-registered with ProspectiveMemoryManager

Parameters

role

Message role (user, assistant, system, tool)

"user" | "tool" | "system" | "assistant"

content

string

Message text content

mood?

PADState

Optional PAD emotional state at observation time

options?

contentSentiment?

number

Returns

Promise<ObservationNote[] | null>

Observation notes if threshold was reached, null otherwise

Implementation of

ICognitiveMemoryManager.observe

---

registerProspective()

registerProspective(input): Promise<ProspectiveMemoryItem>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1396

Register a new prospective reminder/intention.

Parameters

input

Omit<ProspectiveMemoryItem, "id" | "createdAt" | "triggered" | "cueEmbedding"> & object

Returns

Promise<ProspectiveMemoryItem>

Implementation of

ICognitiveMemoryManager.registerProspective

---

rehydrate()

rehydrate(traceId, requestContext?): Promise<string | null>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1429

Rehydrate a gisted/archived trace to its original verbatim content.

Delegates to the configured IMemoryArchive. Returns null when no archive is configured or when the trace is not found/integrity fails.

Parameters

traceId

string

The trace id to rehydrate.

requestContext?

string

Optional caller hint for audit.

Returns

Promise<string | null>

The original verbatim content, or null.

Implementation of

ICognitiveMemoryManager.rehydrate

---

removeProspective()

removeProspective(id): Promise<boolean>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1411

Remove a prospective reminder.

Parameters

id

string

Returns

Promise<boolean>

Implementation of

ICognitiveMemoryManager.removeProspective

---

retrieve()

retrieve(query, mood, options?): Promise<CognitiveRetrievalResult>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:839

Retrieve relevant memories for a query. Called before prompt construction.

Parameters

query

string

mood

PADState

options?

CognitiveRetrievalOptions = {}

Returns

Promise<CognitiveRetrievalResult>

Implementation of

ICognitiveMemoryManager.retrieve

---

runConsolidation()

runConsolidation(): Promise<ConsolidationResult>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1439

Run consolidation cycle (Batch 2).

Returns

Promise<ConsolidationResult>

Implementation of

ICognitiveMemoryManager.runConsolidation

---

searchCompactionHistory()

searchCompactionHistory(keyword): CompactionEntry[]

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1566

Search compaction history for a keyword.

Parameters

keyword

string

Returns

CompactionEntry[]

---

setHydeRetriever()

setHydeRetriever(retriever): void

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1804

Attach a HyDE retriever to enable hypothesis-driven memory recall.

When set, the retrieve() and assembleForPrompt() methods can accept options.hyde = true to generate a hypothetical memory trace before searching. This improves recall for vague or abstract queries by producing embeddings that are semantically closer to stored traces.

Parameters

retriever

A pre-configured HydeRetriever instance, or null to disable HyDE.

HydeRetriever | null

Returns

void

Example

memoryManager.setHydeRetriever(new HydeRetriever({
  llmCaller: myLlmCaller,
  embeddingManager: myEmbeddingManager,
  config: { enabled: true },
}));

Implementation of

ICognitiveMemoryManager.setHydeRetriever

---

shutdown()

shutdown(): Promise<void>

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1579

Shutdown and release resources.

Returns

Promise<void>

Implementation of

ICognitiveMemoryManager.shutdown

---

trackMessage()

trackMessage(role, content): void

Defined in: packages/agentos/src/cognition/memory/CognitiveMemoryManager.ts:1519

Track a conversation message for context window management. Call for every user/assistant/system/tool message in the conversation.

Parameters

role

"user" | "tool" | "system" | "assistant"

content

string

Returns

void