Class: AgentMemory

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

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

Parameters

backend?

ICognitiveMemoryManager | StandaloneMemoryBackend

Returns

AgentMemory

Accessors

isInitialized

Get Signature

get isInitialized(): boolean

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

Returns

boolean

---

raw

Get Signature

get raw(): ICognitiveMemoryManager

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

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

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

Run consolidation cycle.

Returns

Promise<void>

---

export()

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

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

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

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

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

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

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

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

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

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

Parameters

query

string

options?

currentMood?

PADState

maxTierRank?

number

tokenBudget?

number

Returns

Promise<AssembledMemoryContext>

---

getGraph()

getGraph(): Promise<MemoryGraphSnapshot>

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

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

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

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

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

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

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

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

Memory health diagnostics.

Returns

Promise<MemoryHealthReport>

---

importFrom()

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

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

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

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

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

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, options?): Promise<ObservationNote[] | null>

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

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

options?

contentSentiment?

number

currentMood?

PADState

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

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

Store information in long-term memory.

Parameters

content

string

options?

contentSentiment?

number

Content sentiment for the emotional-context tag. Omitted → falls back to importance (today's behavior).

currentMood?

PADState

Live PAD mood for mood-congruent encoding. Omitted → neutral (no bias).

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

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

List active reminders.

Returns

Promise<ProspectiveMemoryItem[]>

---

search()

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

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

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

Shutdown and release resources.

Returns

Promise<void>

---

sqlite()

static sqlite(config?): Promise<AgentMemory>

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

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

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

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

Parameters

memory

StandaloneMemoryBackend

Returns

AgentMemory