Class: AgentMemory

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

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

Parameters

backend?

ICognitiveMemoryManager | StandaloneMemoryBackend

Returns

AgentMemory

Accessors

isInitialized

Get Signature

get isInitialized(): boolean

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

Returns

boolean

---

raw

Get Signature

get raw(): ICognitiveMemoryManager

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

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

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

Run consolidation cycle.

Returns

Promise<void>

---

export()

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

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

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

Parameters

outputPath

string

options?

ExportOptions

Returns

Promise<ExportResult>

The traces the export left out, with the reason for each (see Memory.export).

---

exportSnapshot()

exportSnapshot(): Promise<CognitiveMemorySnapshot>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Memory health diagnostics.

Returns

Promise<MemoryHealthReport>

---

importFrom()

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

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

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

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

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

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

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

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

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 (@framers/agentos/memory/pipeline/observation/PerspectiveObserver). When this memory wraps a cognitive memory manager, the manager writes the source event's identifier and hash into the trace's MechanismMetadata and marks the trace perspective-encoded, so Reconsolidation halves its drift rate. A memory that wraps the standalone Memory facade ignores it.

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

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

List active reminders.

Returns

Promise<ProspectiveMemoryItem[]>

---

search()

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

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

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

Shutdown and release resources.

Returns

Promise<void>

---

sqlite()

static sqlite(config?): Promise<AgentMemory>

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

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

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

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

Parameters

memory

StandaloneMemoryBackend

Returns

AgentMemory