Class: CognitiveMemoryManager

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

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:946

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:1207

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:1351

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>

---

encode()

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

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

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 the input is a perspective-encoded subjective trace from PerspectiveObserver, pass the source-event identifiers here so the resulting MemoryTrace carries the MechanismMetadata fields that applyReconsolidation uses to halve drift on perspective traces and that downstream audit queries use to back-reference the objective source event.

perspectiveSource.eventHash

string

perspectiveSource.eventId

string

scope?

MemoryScope

scopeId?

string

sourceType?

MemorySourceType

tags?

string[]

type?

MemoryType

Returns

Promise<MemoryTrace>

Implementation of

ICognitiveMemoryManager.encode

---

exportToString()

exportToString(options?): Promise<string>

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

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:1460

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

---

getCompactionHistory()

getCompactionHistory(): readonly CompactionEntry[]

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

Get compaction history for audit/UI.

Returns

readonly CompactionEntry[]

---

getConfig()

getConfig(): CognitiveMemoryConfig

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

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:1379

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:1394

Get the context window manager (for advanced usage).

Returns

ContextWindowManager | null

---

getContextWindowStats()

getContextWindowStats(): ContextWindowStats | null

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

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:1435

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:1563

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:1286

Get memory health diagnostics.

Returns

Promise<MemoryHealthReport>

Implementation of

ICognitiveMemoryManager.getMemoryHealth

---

getObserver()

getObserver(): MemoryObserver | null

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

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:1503

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:1444

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:1574

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:1412

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:1369

Get the rolling summary chain text for prompt injection.

Returns

string

---

getTraceCount()

getTraceCount(): number

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

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:540

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:535

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:545

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:1427

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:1526

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:321

Parameters

config

CognitiveMemoryConfig

Returns

Promise<void>

Implementation of

ICognitiveMemoryManager.initialize

---

listProspective()

listProspective(): Promise<ProspectiveMemoryItem[]>

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

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:1130

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:1223

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:1256

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:1238

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:709

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:1266

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:1389

Search compaction history for a keyword.

Parameters

keyword

string

Returns

CompactionEntry[]

---

setHydeRetriever()

setHydeRetriever(retriever): void

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

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:1402

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:1342

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