Skip to main content

Class: Memory

Defined in: packages/agentos/src/memory/facade/Memory.ts:169

Unified public API for the AgentOS memory system.

One Memory instance manages the full lifecycle of an agent's memories: storing, retrieving, ingesting documents, building a knowledge graph, self-improving through consolidation, and importing/exporting data.

Quick start​

const mem = new Memory({ store: 'sqlite', path: './brain.sqlite' });

await mem.remember('The user prefers dark mode');
const results = await mem.recall('dark mode preference');
console.log(results[0].trace.content);

await mem.close();

Constructors​

Constructor​

new Memory(config?): Memory

Defined in: packages/agentos/src/memory/facade/Memory.ts:204

Create a new Memory instance and wire together all subsystems.

Initialization sequence:

  1. Merge config with defaults (store='sqlite', path=tmpdir, graph=true, selfImprove=true, decay=true).
  2. Create SqliteBrain(config.path).
  3. Check embedding dimension compatibility (warn on mismatch).
  4. Create SqliteKnowledgeGraph(brain).
  5. Create SqliteMemoryGraph(brain) and call .initialize().
  6. Create LoaderRegistry() (pre-registers all built-in loaders).
  7. Create FolderScanner(registry).
  8. Create ChunkingEngine().
  9. If selfImprove: create RetrievalFeedbackSignal(brain) and ConsolidationLoop(brain, memoryGraph).

Parameters​

config?​

MemoryConfig

Optional configuration; see MemoryConfig.

Returns​

Memory

Accessors​

graph​

Get Signature​

get graph(): IKnowledgeGraph

Defined in: packages/agentos/src/memory/facade/Memory.ts:626

Access the underlying IKnowledgeGraph implementation.

Useful for advanced queries (traversal, semantic search, neighbourhood lookups) that are not exposed on the facade directly.

Returns​

IKnowledgeGraph

Methods​

addEntity()​

addEntity(entity): Promise<KnowledgeEntity>

Defined in: packages/agentos/src/memory/facade/Memory.ts:565

Add or update an entity in the knowledge graph.

Delegates to SqliteKnowledgeGraph.upsertEntity(). Accepts a partial entity; id, createdAt, and updatedAt are auto-generated when omitted.

Parameters​

entity​

Partial<KnowledgeEntity>

Partial entity descriptor.

Returns​

Promise<KnowledgeEntity>

The complete, persisted entity.

addRelation()​

addRelation(relation): Promise<KnowledgeRelation>

Defined in: packages/agentos/src/memory/facade/Memory.ts:596

Add or update a relation (edge) in the knowledge graph.

Delegates to SqliteKnowledgeGraph.upsertRelation(). Accepts a partial relation; id and createdAt are auto-generated when omitted.

Parameters​

relation​

Partial<KnowledgeRelation>

Partial relation descriptor.

Returns​

Promise<KnowledgeRelation>

The complete, persisted relation.

close()​

close(): Promise<void>

Defined in: packages/agentos/src/memory/facade/Memory.ts:986

Close the Memory instance and release all resources.

Flushes the SQLite WAL and releases the file lock. Must be called when the agent shuts down.

Returns​

Promise<void>

consolidate()​

consolidate(options?): Promise<MemoryConsolidationResult>

Defined in: packages/agentos/src/memory/facade/Memory.ts:642

Run one consolidation cycle (prune, merge, strengthen, derive, compact, re-index).

Parameters​

options?​

Optional topic filter (reserved for future use).

topic?​

string

Returns​

Promise<MemoryConsolidationResult>

Statistics from the consolidation run.

Throws​

When selfImprove was set to false in the config.

createTools()​

createTools(options?): ITool<any, any>[]

Defined in: packages/agentos/src/memory/facade/Memory.ts:853

Create runtime ITool instances backed by this memory facade's SQLite brain.

This is the supported bridge from the standalone memory engine into AgentOS tool registration. The returned tools share this Memory instance's underlying SQLite database and consolidation loop.

Typical usage:

for (const tool of memory.createTools()) {
  await agentos.getToolOrchestrator().registerTool(tool);
}

When self-improvement is disabled, memory_reflect is omitted because there is no backing ConsolidationLoop instance.

Parameters​

options?​
includeReflect?​

boolean

Returns​

ITool<any, any>[]

export()​

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

Defined in: packages/agentos/src/memory/facade/Memory.ts:753

Export the memory store to a file or directory.

Format is detected from options.format or the file extension:

  • .json -> JSON
  • .sqlite / .db -> SQLite file copy
  • directory path -> Markdown or Obsidian (based on options.format)

Parameters​

outputPath​

string

Path to write the export to.

options?​

ExportOptions

Optional format and content controls.

Returns​

Promise<void>

feedback()​

feedback(traceId, signal): void

Defined in: packages/agentos/src/memory/facade/Memory.ts:664

Record retrieval feedback for a memory trace.

Fire-and-forget: the feedback is persisted asynchronously and this method returns immediately without waiting for the write to complete.

Parameters​

traceId​

string

The ID of the trace being evaluated.

signal​

Whether the trace was 'used' or 'ignored' by the LLM.

"used" | "ignored"

Returns​

void

forget()​

forget(traceId): Promise<void>

Defined in: packages/agentos/src/memory/facade/Memory.ts:446

Soft-delete a memory trace by setting deleted = 1.

The trace remains in the database for audit/recovery purposes but is excluded from all recall queries and health reports.

Parameters​

traceId​

string

The ID of the trace to forget.

Returns​

Promise<void>

health()​

health(): Promise<MemoryHealth>

Defined in: packages/agentos/src/memory/facade/Memory.ts:880

Return a health snapshot of the memory store.

Queries aggregate statistics from all tables and returns a MemoryHealth report.

Returns​

Promise<MemoryHealth>

importFrom()​

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

Defined in: packages/agentos/src/memory/facade/Memory.ts:795

Import memory data from a file or directory.

Format is detected from options.format, the file extension, or by inspecting the content.

Parameters​

source​

string

Path to the import source (file or directory).

options?​

ImportOptions

Optional format hint and dedup settings.

Returns​

Promise<ImportResult>

Summary of the import operation.

ingest()​

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

Defined in: packages/agentos/src/memory/facade/Memory.ts:472

Ingest documents from a file, directory, or URL.

Workflow:

  1. Detect source type (file, directory, or URL).
  2. Load document(s) using the appropriate loader.
  3. Chunk each document using the configured strategy.
  4. For each chunk: insert into document_chunks, create a memory trace.
  5. Record the document in the documents table.

Parameters​

source​

string

File path, directory path, or URL.

options?​

IngestOptions

Optional ingestion settings (recursive, include/exclude globs).

Returns​

Promise<IngestResult>

Summary of the ingestion run.

recall()​

recall(query, options?): Promise<ScoredTrace[]>

Defined in: packages/agentos/src/memory/facade/Memory.ts:368

Search for memory traces matching a natural-language query.

Uses FTS5 full-text search with the Porter tokenizer. Results are ranked by strength * abs(fts_rank) and filtered by optional type/scope/strength criteria.

Parameters​

query​

string

Natural-language search query.

options?​

RecallOptions

Optional filters (limit, type, scope, minStrength).

Returns​

Promise<ScoredTrace[]>

Ranked array of ScoredTrace results.

remember()​

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

Defined in: packages/agentos/src/memory/facade/Memory.ts:278

Store a new memory trace.

Creates a trace in the memory_traces table with a unique ID, content hash for deduplication, and optional type/scope/tags metadata. If the memory graph is available the trace is also added as a graph node.

Parameters​

content​

string

The text content to remember.

options?​

RememberOptions

Optional metadata (type, scope, tags, importance, etc.).

Returns​

Promise<MemoryTrace>

The created MemoryTrace-like object.