Class Memory

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 = await Memory.create({ 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();

Accessors

graph

Methods

create remember recall forget ingest addEntity addRelation consolidate feedback feedbackFromResponse export importFrom importFromString exportToString createTools health close

Accessors

graph

Methods

Static create

  • create(config?): Promise<Memory>

  • 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. Await SqliteBrain.open(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

    Returns Promise<Memory>

    A fully initialised Memory instance.

remember

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

  • 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.

    • Optional options: RememberOptions

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

    Returns Promise<MemoryTrace>

    The created MemoryTrace-like object.

recall

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

  • 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.

    • Optional options: RecallOptions

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

    Returns Promise<ScoredTrace[]>

    Ranked array of ScoredTrace results.

forget

  • forget(traceId): Promise<void>

  • 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>

ingest

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

  • 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.

    • Optional options: IngestOptions

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

    Returns Promise<IngestResult>

    Summary of the ingestion run.

addEntity

  • addEntity(entity): Promise<KnowledgeEntity>

  • 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

    Returns Promise<KnowledgeEntity>

    The complete, persisted entity.

addRelation

consolidate

  • consolidate(options?): Promise<MemoryConsolidationResult>

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

    Parameters

    • Optional options: {
          topic?: string;
      }

      Optional topic filter (reserved for future use).

      • Optional topic?: string

    Returns Promise<MemoryConsolidationResult>

    Statistics from the consolidation run.

    Throws

    When selfImprove was set to false in the config.

feedback

  • feedback(traceId, signal, query?): Promise<void>

  • Record retrieval feedback for a memory trace.

    The feedback is persisted asynchronously. This method returns a Promise that resolves once the feedback has been written.

    Parameters

    • traceId: string

      The ID of the trace being evaluated.

    • signal: "used" | "ignored"

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

    • Optional query: string

      Optional retrieval context, typically the original user query.

    Returns Promise<void>

feedbackFromResponse

  • feedbackFromResponse(injectedTraces, response, query?): Promise<RetrievalFeedback[]>

  • Detect and persist used/ignored feedback for a batch of injected traces based on the assistant's final response text.

    This is the high-level bridge used by long-term-memory integrations that already know which traces were injected into the prompt.

    Parameters

    • injectedTraces: MemoryTrace[]
    • response: string
    • Optional query: string

    Returns Promise<RetrievalFeedback[]>

export

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

  • 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.

    • Optional options: ExportOptions

      Optional format and content controls.

    Returns Promise<void>

importFrom

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

  • 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).

    • Optional options: ImportOptions

      Optional format hint and dedup settings.

    Returns Promise<ImportResult>

    Summary of the import operation.

importFromString

  • importFromString(content, format, options?): Promise<ImportResult>

  • Import memory data from a string without filesystem access.

    Supports JSON and CSV formats. Useful in browser environments or when the data is already in memory.

    Parameters

    • content: string

      The raw string content to import.

    • format: "json" | "csv"

      The format of the content: 'json' or 'csv'.

    • Optional options: Pick<ImportOptions, "dedup">

      Optional deduplication controls.

    Returns Promise<ImportResult>

    Summary of the import operation.

exportToString

  • exportToString(options?): Promise<string>

  • Export the full brain state as a JSON string without filesystem access.

    Useful in browser environments or when the data needs to be sent over a network connection.

    Parameters

    • Optional options: ExportOptions

      Optional export configuration (embeddings, conversations).

    Returns Promise<string>

    Pretty-printed JSON string of the full brain payload.

createTools

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

  • 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

    • Optional options: {
          includeReflect?: boolean;
      }
      • Optional includeReflect?: boolean

    Returns ITool<any, any>[]

health

close

  • close(): Promise<void>

  • 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>

Settings

Member Visibility

Theme

On This Page

graphcreaterememberrecallforgetingestaddEntityaddRelationconsolidatefeedbackfeedbackFromResponseexportimportFromimportFromStringexportToStringcreateToolshealthclose