Skip to main content

Class: AgentMemory

Defined in: packages/agentos/src/memory/AgentMemory.ts:121

High-level memory facade for AI agents.

Wraps either ICognitiveMemoryManager or the standalone Memory facade with a simple API that hides PAD mood models, HEXACO traits, SQLite storage details, and internal architecture.

Constructors​

Constructor​

new AgentMemory(backend?): AgentMemory

Defined in: packages/agentos/src/memory/AgentMemory.ts:126

Parameters​

backend?​

ICognitiveMemoryManager | StandaloneMemoryBackend

Returns​

AgentMemory

Accessors​

isInitialized​

Get Signature​

get isInitialized(): boolean

Defined in: packages/agentos/src/memory/AgentMemory.ts:829

Returns​

boolean

raw​

Get Signature​

get raw(): ICognitiveMemoryManager

Defined in: packages/agentos/src/memory/AgentMemory.ts:834

Access the underlying manager for advanced usage.

Returns​

ICognitiveMemoryManager

rawMemory​

Get Signature​

get rawMemory(): StandaloneMemoryBackend | undefined

Defined in: packages/agentos/src/memory/AgentMemory.ts:845

Access the underlying standalone Memory facade for advanced usage.

Returns​

StandaloneMemoryBackend | undefined

Methods​

consolidate()​

consolidate(): Promise<void>

Defined in: packages/agentos/src/memory/AgentMemory.ts:316

Run consolidation cycle.

Returns​

Promise<void>

export()​

export(outputPath, options?): Promise<void>

Defined in: packages/agentos/src/memory/AgentMemory.ts:374

Export memory data. Available only when backed by the standalone SQLite-first Memory facade.

Parameters​

outputPath​

string

options?​

ExportOptions

Returns​

Promise<void>

exportSnapshot()​

exportSnapshot(): Promise<CognitiveMemorySnapshot>

Defined in: packages/agentos/src/memory/AgentMemory.ts:714

Export full memory state as a serializable snapshot. Used for companion portability across worlds in wilds-ai.

Returns​

Promise<CognitiveMemorySnapshot>

Throws​

When backed by standalone SQLite

feedback()​

feedback(traceId, signal, query?): void

Defined in: packages/agentos/src/memory/AgentMemory.ts:386

Record used/ignored retrieval feedback. Available only when backed by the standalone SQLite-first Memory facade.

Parameters​

traceId​

string

signal​

"used" | "ignored"

query?​

string

Returns​

void

forceReflection()​

forceReflection(): Promise<{ superseded: number; traces: number; }>

Defined in: packages/agentos/src/memory/AgentMemory.ts:679

Force a reflection cycle (useful for testing / devtools). Triggers the Observer's note extraction and the Reflector's consolidation regardless of token thresholds.

Returns​

Promise<{ superseded: number; traces: number; }>

Reflection result with typed traces, or empty result if no observer

Throws​

When backed by standalone SQLite

getAssociations()​

getAssociations(seedTraceIds, opts?): Promise<object[]>

Defined in: packages/agentos/src/memory/AgentMemory.ts:483

Get spreading activation results from seed memories. Returns memories that are associatively connected to the seeds.

Parameters​

seedTraceIds​

string[]

IDs of seed traces to activate from

opts?​

Optional depth and limit controls

limit?​

number

maxDepth?​

number

Returns​

Promise<object[]>

Throws​

When backed by standalone SQLite

getClusters()​

getClusters(minSize?): Promise<object[]>

Defined in: packages/agentos/src/memory/AgentMemory.ts:615

Get clusters of strongly associated memories.

Parameters​

minSize?​

number

Minimum cluster size (default 3)

Returns​

Promise<object[]>

Throws​

When backed by standalone SQLite

getConflicts()​

getConflicts(): Promise<object[]>

Defined in: packages/agentos/src/memory/AgentMemory.ts:583

Get pairs of contradicting memory traces.

Returns​

Promise<object[]>

Throws​

When backed by standalone SQLite

getContext()​

getContext(query, options?): Promise<AssembledMemoryContext>

Defined in: packages/agentos/src/memory/AgentMemory.ts:280

Get assembled memory context for prompt injection within a token budget.

Parameters​

query​

string

options?​
tokenBudget?​

number

Returns​

Promise<AssembledMemoryContext>

getGraph()​

getGraph(): Promise<MemoryGraphSnapshot>

Defined in: packages/agentos/src/memory/AgentMemory.ts:405

Get a serializable snapshot of the memory graph for visualization. Returns nodes (traces), edges (associations), clusters, and aggregate stats.

Returns​

Promise<MemoryGraphSnapshot>

Graph snapshot suitable for JSON serialization

Throws​

When backed by standalone SQLite (requires CognitiveMemoryManager)

getObservationStats()​

getObservationStats(): Promise<ObservationPipelineStats>

Defined in: packages/agentos/src/memory/AgentMemory.ts:646

Get observation pipeline stats (pending notes, compression ratio, reflection count).

Returns​

Promise<ObservationPipelineStats>

Throws​

When backed by standalone SQLite

getProspectiveItems()​

getProspectiveItems(): Promise<ProspectiveMemoryItem[]>

Defined in: packages/agentos/src/memory/AgentMemory.ts:667

Get active prospective memory items (reminders/intentions). Alias for reminders() with a more descriptive name.

Returns​

Promise<ProspectiveMemoryItem[]>

getRelationalMemories()​

getRelationalMemories(opts?): Promise<ScoredMemoryTrace[]>

Defined in: packages/agentos/src/memory/AgentMemory.ts:530

Get relational memory traces (trust signals, boundaries, emotional bonds). Convenience wrapper around getTracesByType('relational').

Parameters​

opts?​
limit?​

number

Returns​

Promise<ScoredMemoryTrace[]>

getStrengthDistribution()​

getStrengthDistribution(): Promise<Record<MemoryType, MemoryTypeStats>>

Defined in: packages/agentos/src/memory/AgentMemory.ts:540

Get memory strength distribution by type. Returns count, average strength, decaying count, and flashbulb count per type.

Returns​

Promise<Record<MemoryType, MemoryTypeStats>>

Throws​

When backed by standalone SQLite

getTracesByType()​

getTracesByType(type, opts?): Promise<ScoredMemoryTrace[]>

Defined in: packages/agentos/src/memory/AgentMemory.ts:509

Get all traces filtered by memory type.

Parameters​

type​

MemoryType

Memory type to filter by (episodic, semantic, procedural, prospective, relational)

opts?​

Optional limit and minimum strength filter

limit?​

number

minStrength?​

number

Returns​

Promise<ScoredMemoryTrace[]>

Throws​

When backed by standalone SQLite

getWorkingMemory()​

getWorkingMemory(): Promise<WorkingMemorySlot[]>

Defined in: packages/agentos/src/memory/AgentMemory.ts:632

Get working memory slots — what's currently "in focus".

Returns​

Promise<WorkingMemorySlot[]>

Throws​

When backed by standalone SQLite

health()​

health(): Promise<MemoryHealthReport>

Defined in: packages/agentos/src/memory/AgentMemory.ts:326

Memory health diagnostics.

Returns​

Promise<MemoryHealthReport>

importFrom()​

importFrom(source, options?): Promise<ImportResult>

Defined in: packages/agentos/src/memory/AgentMemory.ts:362

Import previously exported memory data. Available only when backed by the standalone SQLite-first Memory facade.

Parameters​

source​

string

options?​

ImportOptions

Returns​

Promise<ImportResult>

importSnapshot()​

importSnapshot(snapshot): Promise<{ conflicts: number; imported: number; }>

Defined in: packages/agentos/src/memory/AgentMemory.ts:780

Import a memory snapshot (for character portability across worlds). Encodes each trace and registers prospective items.

Parameters​

snapshot​

CognitiveMemorySnapshot

Previously exported snapshot

Returns​

Promise<{ conflicts: number; imported: number; }>

Count of imported traces and conflicts detected

Throws​

When backed by standalone SQLite

ingest()​

ingest(source, options?): Promise<IngestResult>

Defined in: packages/agentos/src/memory/AgentMemory.ts:350

Ingest files, directories, or URLs. Available only when backed by the standalone SQLite-first Memory facade.

Parameters​

source​

string

options?​

IngestOptions

Returns​

Promise<IngestResult>

initialize()​

initialize(config): Promise<void>

Defined in: packages/agentos/src/memory/AgentMemory.ts:166

Initialize the cognitive-manager path. Only needed when constructing the legacy cognitive backend directly (not via AgentMemory.wrap() or AgentMemory.sqlite()).

Parameters​

config​

CognitiveMemoryConfig

Returns​

Promise<void>

observe()​

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

Defined in: packages/agentos/src/memory/AgentMemory.ts:266

Feed a conversation turn to the observational memory system. The Observer creates dense notes when the token threshold is reached.

Parameters​

role​

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

content​

string

Returns​

Promise<ObservationNote[] | null>

Example​

await memory.observe('user', "Can you help me debug this?");
await memory.observe('assistant', "Sure! The issue is in your useEffect...");

recall()​

recall(query, options?): Promise<RecallResult>

Defined in: packages/agentos/src/memory/AgentMemory.ts:230

Recall memories relevant to a query.

Parameters​

query​

string

options?​

SearchOptions

Returns​

Promise<RecallResult>

Example​

const results = await memory.recall("what does the user prefer?");
for (const m of results.memories) {
  console.log(m.content, m.retrievalScore);
}

remember()​

remember(content, options?): Promise<RememberResult>

Defined in: packages/agentos/src/memory/AgentMemory.ts:183

Store information in long-term memory.

Parameters​

content​

string

options?​
entities?​

string[]

importance?​

number

scope?​

MemoryScope

scopeId?​

string

sourceType?​

MemorySourceType

tags?​

string[]

type?​

MemoryType

Returns​

Promise<RememberResult>

Example​

await memory.remember("User prefers dark mode");
await memory.remember("Deploy by Friday", { type: 'prospective', tags: ['deadline'] });

remind()​

remind(input): Promise<ProspectiveMemoryItem | null>

Defined in: packages/agentos/src/memory/AgentMemory.ts:294

Register a prospective memory (reminder/intention).

Parameters​

input​

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

Returns​

Promise<ProspectiveMemoryItem | null>

reminders()​

reminders(): Promise<ProspectiveMemoryItem[]>

Defined in: packages/agentos/src/memory/AgentMemory.ts:307

List active reminders.

Returns​

Promise<ProspectiveMemoryItem[]>

search(query, options?): Promise<ScoredMemoryTrace[]>

Defined in: packages/agentos/src/memory/AgentMemory.ts:253

Search memories (alias for recall with simpler return).

Parameters​

query​

string

options?​

SearchOptions

Returns​

Promise<ScoredMemoryTrace[]>

shutdown()​

shutdown(): Promise<void>

Defined in: packages/agentos/src/memory/AgentMemory.ts:335

Shutdown and release resources.

Returns​

Promise<void>

sqlite()​

static sqlite(config?): Promise<AgentMemory>

Defined in: packages/agentos/src/memory/AgentMemory.ts:156

Create an initialized SQLite-backed AgentMemory for standalone usage.

Parameters​

config?​

MemoryConfig

Returns​

Promise<AgentMemory>

wrap()​

static wrap(manager): AgentMemory

Defined in: packages/agentos/src/memory/AgentMemory.ts:140

Create an AgentMemory wrapping an existing CognitiveMemoryManager. Use this in wunderland where the manager is already constructed.

Parameters​

manager​

ICognitiveMemoryManager

Returns​

AgentMemory

wrapMemory()​

static wrapMemory(memory): AgentMemory

Defined in: packages/agentos/src/memory/AgentMemory.ts:149

Create an AgentMemory wrapping the standalone SQLite-first Memory facade.

Parameters​

memory​

StandaloneMemoryBackend

Returns​

AgentMemory