Class AgentMemory

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.

Accessors

isInitialized

get isInitialized(): boolean
Returns boolean
- Defined in src/cognition/memory/AgentMemory.ts:901

raw

get raw(): ICognitiveMemoryManager
Access the underlying manager for advanced usage.

Returns ICognitiveMemoryManager
- Defined in src/cognition/memory/AgentMemory.ts:906

rawMemory

get rawMemory(): undefined | StandaloneMemoryBackend
Access the underlying standalone Memory facade for advanced usage.

Returns undefined | StandaloneMemoryBackend
- Defined in src/cognition/memory/AgentMemory.ts:917

Constructors

constructor

new AgentMemory(backend?): AgentMemory
Parameters
- Optional backend: ICognitiveMemoryManager | StandaloneMemoryBackend
Returns AgentMemory
- Defined in src/cognition/memory/AgentMemory.ts:140

Methods

`Static` wrap

wrap(manager): AgentMemory
Create an AgentMemory wrapping an existing CognitiveMemoryManager. Use this in wunderland where the manager is already constructed.
Parameters
- manager: ICognitiveMemoryManager
Returns AgentMemory
- Defined in src/cognition/memory/AgentMemory.ts:155

`Static` wrapMemory

wrapMemory(memory): AgentMemory
Create an AgentMemory wrapping the standalone SQLite-first Memory facade.
Parameters
- memory: StandaloneMemoryBackend
Returns AgentMemory
- Defined in src/cognition/memory/AgentMemory.ts:165

`Static` sqlite

sqlite(config?): Promise<AgentMemory>
Create an initialized SQLite-backed AgentMemory for standalone usage.
Parameters
- Optional config: MemoryConfig
Returns Promise<AgentMemory>
- Defined in src/cognition/memory/AgentMemory.ts:172

initialize

initialize(config): Promise<void>
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>
- Defined in src/cognition/memory/AgentMemory.ts:182

remember

remember(content, options?): Promise<RememberResult>
Store information in long-term memory.
Parameters
- content: string
- Optional options: {
      type?: MemoryType;
      scope?: MemoryScope;
      scopeId?: string;
      sourceType?: MemorySourceType;
      tags?: string[];
      entities?: string[];
      importance?: number;
      currentMood?: PADState;
      contentSentiment?: number;
      perspectiveSource?: {
          eventId: string;
          eventHash: string;
      };
  }
  - Optional type?: MemoryType
  - Optional scope?: MemoryScope
  - Optional scopeId?: string
  - Optional sourceType?: MemorySourceType
  - Optional tags?: string[]
  - Optional entities?: string[]
  - Optional importance?: number
  - Optional currentMood?: PADState
    Live PAD mood for mood-congruent encoding. Omitted → neutral (no bias).
  - Optional contentSentiment?: number
    Content sentiment for the emotional-context tag. Omitted → falls back to importance (today's behavior).
  - Optional perspectiveSource?: {
    eventId: string;
    eventHash: 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.
    - eventId: string
    - eventHash: string
Returns Promise<RememberResult>
Example
```
await memory.remember("User prefers dark mode");
await memory.remember("Deploy by Friday", { type: 'prospective', tags: ['deadline'] });
```
- Defined in src/cognition/memory/AgentMemory.ts:212

recall

recall(query, options?): Promise<RecallResult>
Recall memories relevant to a query.
Parameters
- query: string
- Optional 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);
}
```
- Defined in src/cognition/memory/AgentMemory.ts:274

search

search(query, options?): Promise<ScoredMemoryTrace[]>
Search memories (alias for recall with simpler return).
Parameters
- query: string
- Optional options: SearchOptions
Returns Promise<ScoredMemoryTrace[]>
- Defined in src/cognition/memory/AgentMemory.ts:298

observe

observe(role, content, options?): Promise<null | ObservationNote[]>
Feed a conversation turn to the observational memory system. The Observer creates dense notes when the token threshold is reached.
Parameters
- role: "user" | "assistant" | "system" | "tool"
- content: string
- Optional options: {
  currentMood?: PADState;
  contentSentiment?: number;
  }
  - Optional currentMood?: PADState
  - Optional contentSentiment?: number
Returns Promise<null | ObservationNote[]>
Example
```
await memory.observe('user', "Can you help me debug this?");
await memory.observe('assistant', "Sure! The issue is in your useEffect...");
```
- Defined in src/cognition/memory/AgentMemory.ts:311

getContext

getContext(query, options?): Promise<AssembledMemoryContext>
Get assembled memory context for prompt injection within a token budget.
Parameters
- query: string
- Optional options: {
      tokenBudget?: number;
      currentMood?: PADState;
      maxTierRank?: number;
  }
  - Optional tokenBudget?: number
  - Optional currentMood?: PADState
  - Optional maxTierRank?: number
Returns Promise<AssembledMemoryContext>
- Defined in src/cognition/memory/AgentMemory.ts:330

remind

remind(input): Promise<null | ProspectiveMemoryItem>
Register a prospective memory (reminder/intention).
Parameters
- input: Omit<ProspectiveMemoryItem, "createdAt" | "id" | "triggered" | "cueEmbedding"> & {
  cueText?: string;
  }
Returns Promise<null | ProspectiveMemoryItem>
- Defined in src/cognition/memory/AgentMemory.ts:349

reminders

reminders(): Promise<ProspectiveMemoryItem[]>
List active reminders.

Returns Promise<ProspectiveMemoryItem[]>
- Defined in src/cognition/memory/AgentMemory.ts:362

consolidate

consolidate(): Promise<void>
Run consolidation cycle.

Returns Promise<void>
- Defined in src/cognition/memory/AgentMemory.ts:371

health

health(): Promise<MemoryHealthReport>
Memory health diagnostics.

Returns Promise<MemoryHealthReport>
- Defined in src/cognition/memory/AgentMemory.ts:381

shutdown

shutdown(): Promise<void>
Shutdown and release resources.

Returns Promise<void>
- Defined in src/cognition/memory/AgentMemory.ts:390

ingest

ingest(source, options?): Promise<IngestResult>
Ingest files, directories, or URLs. Available only when backed by the standalone SQLite-first Memory facade.
Parameters
- source: string
- Optional options: IngestOptions
Returns Promise<IngestResult>
- Defined in src/cognition/memory/AgentMemory.ts:418

importFrom

importFrom(source, options?): Promise<ImportResult>
Import previously exported memory data. Available only when backed by the standalone SQLite-first Memory facade.
Parameters
- source: string
- Optional options: ImportOptions
Returns Promise<ImportResult>
- Defined in src/cognition/memory/AgentMemory.ts:430

export

export(outputPath, options?): Promise<ExportResult>
Export memory data. Available only when backed by the standalone SQLite-first Memory facade.
Parameters
- outputPath: string
- Optional options: ExportOptions
Returns Promise<ExportResult>
The traces the export left out, with the reason for each (see Memory.export).
- Defined in src/cognition/memory/AgentMemory.ts:444

feedback

feedback(traceId, signal, query?): void
Record used/ignored retrieval feedback. Available only when backed by the standalone SQLite-first Memory facade.
Parameters
- traceId: string
- signal: "used" | "ignored"
- Optional query: string
Returns void
- Defined in src/cognition/memory/AgentMemory.ts:456

getGraph

getGraph(): Promise<MemoryGraphSnapshot>
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)
- Defined in src/cognition/memory/AgentMemory.ts:475

getAssociations

getAssociations(seedTraceIds, opts?): Promise<{
memoryId: string;
activation: number;
}[]>
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
- Optional opts: {
  maxDepth?: number;
  limit?: number;
  }
  Optional depth and limit controls
  - Optional maxDepth?: number
  - Optional limit?: number
Returns Promise<{
memoryId: string;
activation: number;
}[]>
Throws
When backed by standalone SQLite
- Defined in src/cognition/memory/AgentMemory.ts:553

getTracesByType

getTracesByType(type, opts?): Promise<ScoredMemoryTrace[]>
Get all traces filtered by memory type.
Parameters
- type: MemoryType
  Memory type to filter by (episodic, semantic, procedural, prospective, relational)
- Optional opts: {
  limit?: number;
  minStrength?: number;
  }
  Optional limit and minimum strength filter
  - Optional limit?: number
  - Optional minStrength?: number
Returns Promise<ScoredMemoryTrace[]>
Throws
When backed by standalone SQLite
- Defined in src/cognition/memory/AgentMemory.ts:579

getRelationalMemories

getRelationalMemories(opts?): Promise<ScoredMemoryTrace[]>
Get relational memory traces (trust signals, boundaries, emotional bonds). Convenience wrapper around getTracesByType('relational').
Parameters
- Optional opts: {
  limit?: number;
  }
  - Optional limit?: number
Returns Promise<ScoredMemoryTrace[]>
- Defined in src/cognition/memory/AgentMemory.ts:600

getStrengthDistribution

getStrengthDistribution(): Promise<Record<MemoryType, MemoryTypeStats>>
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
- Defined in src/cognition/memory/AgentMemory.ts:610

getConflicts

getConflicts(): Promise<{
    traceA: string;
    traceB: string;
    type: string;
}[]>
Get pairs of contradicting memory traces.

Returns Promise<{
    traceA: string;
    traceB: string;
    type: string;
}[]>
Throws
When backed by standalone SQLite
- Defined in src/cognition/memory/AgentMemory.ts:653

getClusters

getClusters(minSize?): Promise<{
    clusterId: string;
    memberIds: string[];
    density: number;
}[]>
Get clusters of strongly associated memories.
Parameters
- Optional minSize: number
  Minimum cluster size (default 3)
Returns Promise<{
    clusterId: string;
    memberIds: string[];
    density: number;
}[]>
Throws
When backed by standalone SQLite
- Defined in src/cognition/memory/AgentMemory.ts:685

getWorkingMemory

getWorkingMemory(): Promise<WorkingMemorySlot[]>
Get working memory slots — what's currently "in focus".

Returns Promise<WorkingMemorySlot[]>
Throws
When backed by standalone SQLite
- Defined in src/cognition/memory/AgentMemory.ts:702

getObservationStats

getObservationStats(): Promise<ObservationPipelineStats>
Get observation pipeline stats (pending notes, compression ratio, reflection count).

Returns Promise<ObservationPipelineStats>
Throws
When backed by standalone SQLite
- Defined in src/cognition/memory/AgentMemory.ts:716

getProspectiveItems

getProspectiveItems(): Promise<ProspectiveMemoryItem[]>
Get active prospective memory items (reminders/intentions). Alias for reminders() with a more descriptive name.

Returns Promise<ProspectiveMemoryItem[]>
- Defined in src/cognition/memory/AgentMemory.ts:737

forceReflection

forceReflection(): Promise<{
traces: number;
superseded: number;
}>
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<{
traces: number;
superseded: number;
}>
Reflection result with typed traces, or empty result if no observer

Throws
When backed by standalone SQLite
- Defined in src/cognition/memory/AgentMemory.ts:749

exportSnapshot

exportSnapshot(): Promise<CognitiveMemorySnapshot>
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
- Defined in src/cognition/memory/AgentMemory.ts:784

importSnapshot

importSnapshot(snapshot): Promise<{
imported: number;
conflicts: number;
}>
Import a memory snapshot (for character portability across worlds). Encodes each trace and registers prospective items.
Parameters
- snapshot: CognitiveMemorySnapshot
  Previously exported snapshot
Returns Promise<{
imported: number;
conflicts: number;
}>
Count of imported traces and conflicts detected

Throws
When backed by standalone SQLite
- Defined in src/cognition/memory/AgentMemory.ts:851

Class AgentMemory

Index

Accessors

Constructors

Methods

Accessors

isInitialized

Returns boolean

raw

Returns ICognitiveMemoryManager

rawMemory

Returns undefined | StandaloneMemoryBackend

Constructors

constructor

Parameters

Returns AgentMemory

Methods

Static wrap

Parameters

Returns AgentMemory

Static wrapMemory

Parameters

Returns AgentMemory

Static sqlite

Parameters

Returns Promise<AgentMemory>

initialize

Parameters

Returns Promise<void>

remember

Parameters

Optional type?: MemoryType

Optional scope?: MemoryScope

Optional scopeId?: string

Optional sourceType?: MemorySourceType

Optional tags?: string[]

Optional entities?: string[]

Optional importance?: number

Optional currentMood?: PADState

Optional contentSentiment?: number

Optional perspectiveSource?: { eventId: string; eventHash: string; }

eventId: string

eventHash: string

Returns Promise<RememberResult>

Example

recall

Parameters

Returns Promise<RecallResult>

Example

search

Parameters

Returns Promise<ScoredMemoryTrace[]>

observe

Parameters

Optional currentMood?: PADState

Optional contentSentiment?: number

Returns Promise<null | ObservationNote[]>

Example

getContext

Parameters

Optional tokenBudget?: number

Optional currentMood?: PADState

Optional maxTierRank?: number

Returns Promise<AssembledMemoryContext>

remind

Parameters

Returns Promise<null | ProspectiveMemoryItem>

reminders

Returns Promise<ProspectiveMemoryItem[]>

consolidate

Returns Promise<void>

health

Returns Promise<MemoryHealthReport>

shutdown

Returns Promise<void>

ingest

Parameters

Returns Promise<IngestResult>

importFrom

Parameters

`Static` wrap

`Static` wrapMemory

`Static` sqlite

`Optional` type?: MemoryType

`Optional` scope?: MemoryScope

`Optional` scopeId?: string

`Optional` sourceType?: MemorySourceType

`Optional` tags?: string[]

`Optional` entities?: string[]

`Optional` importance?: number

`Optional` currentMood?: PADState

`Optional` contentSentiment?: number

`Optional` perspectiveSource?: {
eventId: string;
eventHash: string;
}

`Optional` currentMood?: PADState

`Optional` contentSentiment?: number

`Optional` tokenBudget?: number

`Optional` currentMood?: PADState

`Optional` maxTierRank?: number

`Optional` maxDepth?: number

`Optional` limit?: number

Returns Promise<{
memoryId: string;
activation: number;
}[]>

`Optional` limit?: number

`Optional` minStrength?: number

`Optional` limit?: number

Returns Promise<{
traceA: string;
traceB: string;
type: string;
}[]>

Returns Promise<{
clusterId: string;
memberIds: string[];
density: number;
}[]>

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

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