TypeScript SDK

Install

$ npm i oortmem

• Node.js 22.15 or newer. The package is ESM only. require('oortmem') works too, through Node's require(esm).
• oortmem 0.6.0 or newer. The SDK is the package's root export, next to the oort command.
• Types included. Every option, result and error is typed.

Quick start

On your machine

Where oort setup has run, createOort() with no options uses what setup chose: local or cloud, and the keys. await using closes the handle at the end of the block (or call close()).

import { createOort, formatForPrompt } from 'oortmem';

// What `oort setup` chose on this machine (local by default), with its keys.
await using oort = await createOort();

await oort.observe({ user: 'We deploy on Fridays now.', assistant: 'Noted.' });

// Put this block in your model's system prompt: it is escaped, so a memory cannot break out.
const memory = formatForPrompt(await oort.recall('how do we deploy?'));
console.log(memory);

In Oort Cloud

With your Oort key in OORT_API_KEY. Cloud mode needs Oort Pro. Make a key for a server with oort keys create, which prints it once.

import { createOort } from 'oortmem';

// Oort Cloud, with the Oort key from the environment (OORT_API_KEY).
await using oort = await createOort({ mode: 'cloud', keySources: ['env'] });

await oort.remember('The user lives in Lund.');
const { memories } = await oort.recall('where does the user live?');
console.log(memories.map((m) => m.text));

Put memory in a prompt

formatForPrompt(result) builds the <oort-memory> block the hooks inject. Put it in your model's system prompt, and call observe with the finished turn after you answer. From the serverless example:

const memory = formatForPrompt(await oort.recall(event.question, { speed: 'fast' }));
const answer = await answerWith(memory, event.question);
// Await before returning: the runtime freezes after the response. `turnRef` makes a retried
// invocation save the turn once.
await oort.observe({ user: event.question, assistant: answer, turnRef: event.requestId });

Modes

'auto'

Where the engine runsThe default. What oort setup chose on this machine, else local.

What it needsAs the chosen mode.

'local'

Where the engine runsIn your process, with SQLite in OORT_HOME (~/.oort by default).

What it needsModel keys, or the Oort key through the Oort Pro relay. Without keys, recall falls back to keyword search and writes throw OortNeedsKeyError.

'cloud'

Where the engine runsIn Oort Cloud, over HTTPS. Loads no native module and writes nothing to disk.

What it needsThe Oort key only. Without one, createOort throws OortNeedsLoginError.

createOort() never makes a network request: local mode opens SQLite and reads the keys. A few calls differ by mode:

• judge.record, judge.apply, judge.list, judge.confirm and consolidate are local only. Cloud mode refuses them (local-only).
• forget(id, { everywhere: true }) is cloud only.
• An end user (user) is local only for now. See Multi-user apps.

What costs usage

No model is called when you create a handle, by whoami, or by any read of stored records. In local mode, a model call is billed by the vendor of your own key, or metered on your Oort account through the Oort Pro relay. whoami().routes says which applies to each role.

recall

Local modeA Voyage embed and rerank, each skipped when the answer is already confident. speed: 'fast' skips the rerank, speed: 'lexical' calls no model.

Cloud modeOne metered recall.

observe

Local modeA TypeSafe gate, always. If the turn is kept: one Anthropic writer call, one Voyage embed, and a TypeSafe reconcile per fact.

Cloud modeOne metered observe.

remember

Local modeOne observe per fact.

Cloud modeOne metered observe per fact.

judge.record

Local modeOne Voyage embed.

Cloud modeRefused.

judge.apply

Local modeOne Voyage embed and one TypeSafe judge call.

Cloud modeRefused.

forget, pin, unpin, explain, recent, whoami, judge.list, judge.confirm, consolidate

Local modeNo model call.

Cloud modeNo model call.

With local models (oort models pull), embedding and reranking cost nothing, but saving a memory still calls the gate, writer and reconcile models. keySources: ['explicit'] turns off every key you did not pass in code, the relay included.

Versions and stability

• Before 1.0, a breaking change lands only in a minor release (0.6 to 0.7), listed under "Breaking" in the release notes. A patch release only adds or fixes.
• oortmem/ai-sdk, RecalledMemory.why and JudgeResult.decisions are experimental and may change in any minor release.
• New result fields, reason strings and warnings can arrive in any release. Ignore fields you do not know.
• Use oortmem. @oortmem/core carries no stability promise.

Next

• Multi-user apps: one memory per end user.
• SDK in agent frameworks: the Vercel AI SDK, LangGraph.js and OpenAI Agents JS.
• Running in your own infrastructure: serverless and containers.
• SDK errors and the API reference.