api-reference.md

title	api reference

API Reference

EngramClient

The main entry point for the Open-Engram memory architecture. Construct via the async factory EngramClient.create().

Factory

EngramClient.create(config: EngramConfig): Promise<EngramClient>

Creates and initializes a client. Validates configuration, connects storage, applies defaults, and starts connectivity monitoring.

Required fields:

• config.storage — A StorageAdapter implementation (e.g., InMemoryAdapter, SQLiteAdapter, PostgresAdapter)
• config.agentId — Unique identifier for the agent

Optional fields: See Configuration for the full reference.

import { InMemoryAdapter, EngramClient } from '@open-engram/core';

const client = await EngramClient.create({
  storage: new InMemoryAdapter(),
  agentId: 'my-agent',
});

---

Core Methods

sense(input): Promise<SensoryEvent>

Ingests a raw event into the sensory buffer. Events are evaluated by the attention gate on the next focus() call.

Parameter	Type	Required	Description
input.content	string	Yes	Text content of the event
input.source	string	Yes	Origin (e.g., 'user', 'tool', 'system')
input.contentType	ContentType	No	'text' (default), 'json', 'image', 'audio', 'fhir'
input.media	MediaAttachment	No	Attached media (image/audio)
input.tags	string[]	No	Tags for categorization
input.metadata	Record<string, unknown>	No	Arbitrary metadata

const event = await client.sense({
  content: 'User prefers dark mode',
  source: 'user',
  tags: ['preference'],
});

focus(query?: string): Promise<WorkingMemorySnapshot>

Runs the attention gate. Promotes high-scoring sensory events into working memory. Evicted entries are demoted to episodic store.

const snapshot = await client.focus('What are the user preferences?');
console.log(snapshot.entries); // promoted entries
console.log(snapshot.tokenUsage); // current token usage

recall(query: string, opts?: RetrievalOptions): Promise<RetrievalResult>

Retrieves memories via tiered retrieval. Returns ranked results with a RetrievalTrace.

Option	Type	Default	Description
threshold	number	0.7	Minimum similarity score
limit	number	10	Maximum results (capped at 1000)
tier	'T0' | 'T1' | 'T2'	'T1'	Detail level
stores	StoreName[]	['semantic']	Which stores to search

const result = await client.recall('dark mode preference');
for (const { record, score } of result.records) {
  console.log(`[${score.toFixed(2)}] ${record.content}`);
}

remember(content: string, meta?): Promise<SemanticRecord>

Writes a fact directly to the semantic store, bypassing consolidation.

const fact = await client.remember('User prefers dark mode', {
  confidence: 0.95,
  domain: 'user_preference',
  tags: ['ui', 'theme'],
});

checkpoint(label?: string): Promise<EpisodicRecord>

Serializes current working memory state as an episodic record.

const record = await client.checkpoint('end-of-onboarding');

consolidate(): Promise<ConsolidationReport>

Runs the 7-stage consolidation pipeline. Requires an LLM adapter for distillation; without one, batches are queued for offline retry.

const report = await client.consolidate();
console.log(`Extracted ${report.factsExtracted} facts`);

---

Memory Management

forget(id: string): Promise<void>

Soft-deletes a record (marks with deletedAt).

purge(id: string): Promise<void>

Permanently deletes a record from all stores. Irreversible.

pin(id: string): Promise<void>

Pins a working memory entry, protecting it from eviction.

unpin(id: string): Promise<void>

Unpins a working memory entry.

---

Data Portability

export(store?): Promise<MemoryExport>

Exports all records. Optionally filter to 'episodic' or 'semantic'.

import(data: MemoryExport): Promise<ImportReport>

Imports records from a MemoryExport.

---

Observability

status(): Promise<MemoryStatus>

Returns connectivity state, store record counts, and working memory usage.

auditLog(query?: AuditLogQuery): Promise<AuditLogEntry[]>

Queries the audit log. Returns empty if auditing is disabled.

events: EngramEventBus

The event bus for subscribing to memory lifecycle events.

static diff(before, after): MemoryDiff

Computes the difference between two memory exports.

---

Lifecycle

destroy(): Promise<void>

Gracefully shuts down. Stops monitoring, flushes events, disconnects storage.