Class: AgentMemory

Defined in: packages/agentos/src/cognition/memory/AgentMemory.ts:128

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/cognition/memory/AgentMemory.ts:133

Parameters

backend?

ICognitiveMemoryManager | StandaloneMemoryBackend

Returns

AgentMemory

Accessors

isInitialized

Get Signature

get isInitialized(): boolean

Defined in: packages/agentos/src/cognition/memory/AgentMemory.ts:846

Returns

boolean

---

raw

Get Signature

get raw(): ICognitiveMemoryManager

Defined in: packages/agentos/src/cognition/memory/AgentMemory.ts:851

Access the underlying manager for advanced usage.

Returns

ICognitiveMemoryManager

---

rawMemory

Get Signature

get rawMemory(): StandaloneMemoryBackend | undefined

Defined in: packages/agentos/src/cognition/memory/AgentMemory.ts:862

Access the underlying standalone Memory facade for advanced usage.

Returns

StandaloneMemoryBackend | undefined

Methods

consolidate()

consolidate(): Promise<void>

Defined in: packages/agentos/src/cognition/memory/AgentMemory.ts:333

Run consolidation cycle.

Returns

Promise<void>

---

export()

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

Defined in: packages/agentos/src/cognition/memory/AgentMemory.ts:391

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/cognition/memory/AgentMemory.ts:731

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/cognition/memory/AgentMemory.ts:403

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/cognition/memory/AgentMemory.ts:696

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/cognition/memory/AgentMemory.ts:500

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/cognition/memory/AgentMemory.ts:632

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/cognition/memory/AgentMemory.ts:600

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/cognition/memory/AgentMemory.ts:297

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/cognition/memory/AgentMemory.ts:422

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/cognition/memory/AgentMemory.ts:663

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/cognition/memory/AgentMemory.ts:684

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/cognition/memory/AgentMemory.ts:547

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/cognition/memory/AgentMemory.ts:557

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/cognition/memory/AgentMemory.ts:526

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/cognition/memory/AgentMemory.ts:649

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/cognition/memory/AgentMemory.ts:343

Memory health diagnostics.

Returns

Promise<MemoryHealthReport>

---

importFrom()

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

Defined in: packages/agentos/src/cognition/memory/AgentMemory.ts:379

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/cognition/memory/AgentMemory.ts:797

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/cognition/memory/AgentMemory.ts:367

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/cognition/memory/AgentMemory.ts:173

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/cognition/memory/AgentMemory.ts:283

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/cognition/memory/AgentMemory.ts:246

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/cognition/memory/AgentMemory.ts:190

Store information in long-term memory.

Parameters

content

string

options?

entities?

string[]

importance?

number

perspectiveSource?

{ eventHash: string; eventId: string; }

Set when encoding a subjective trace produced by PerspectiveObserver. Threads the source-event identifiers into the trace's MechanismMetadata so Reconsolidation halves drift on perspective traces and audit queries can back-reference the objective source event.

perspectiveSource.eventHash

string

perspectiveSource.eventId

string

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/cognition/memory/AgentMemory.ts:311

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/cognition/memory/AgentMemory.ts:324

List active reminders.

Returns

Promise<ProspectiveMemoryItem[]>

---

search()

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

Defined in: packages/agentos/src/cognition/memory/AgentMemory.ts:270

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/cognition/memory/AgentMemory.ts:352

Shutdown and release resources.

Returns

Promise<void>

---

sqlite()

static sqlite(config?): Promise<AgentMemory>

Defined in: packages/agentos/src/cognition/memory/AgentMemory.ts:163

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/cognition/memory/AgentMemory.ts:147

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/cognition/memory/AgentMemory.ts:156

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

Parameters

memory

StandaloneMemoryBackend

Returns

AgentMemory