memtrails 0.0.0-stage → 0.2.0

package/dist/importers/text.js

@@ -0,0 +1,191 @@
+const NAMED = {
+    amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', ensp: ' ', emsp: ' ', thinsp: ' ', shy: '',
+    zwnj: '‌', zwj: '‍', lrm: '‎', rlm: '‏',
+    copy: '©', reg: '®', trade: '™', hellip: '…', mdash: '—', ndash: '–', minus: '−',
+    lsquo: '‘', rsquo: '’', sbquo: '‚', ldquo: '“', rdquo: '”', bdquo: '„', laquo: '«', raquo: '»', lsaquo: '‹', rsaquo: '›',
+    euro: '€', pound: '£', yen: '¥', cent: '¢', curren: '¤', deg: '°', middot: '·', bull: '•', times: '×', divide: '÷',
+    sect: '§', para: '¶', iexcl: '¡', iquest: '¿', szlig: 'ß', aelig: 'æ', AElig: 'Æ', oelig: 'œ', OElig: 'Œ',
+    oslash: 'ø', Oslash: 'Ø', eth: 'ð', ETH: 'Ð', thorn: 'þ', THORN: 'Þ', ordf: 'ª', ordm: 'º', micro: 'µ', plusmn: '±',
+    frac12: '½', frac14: '¼', frac34: '¾', sup1: '¹', sup2: '²', sup3: '³', dagger: '†', Dagger: '‡', permil: '‰',
+    prime: '′', Prime: '″', le: '≤', ge: '≥', ne: '≠', infin: '∞', asymp: '≈', larr: '←', rarr: '→', uarr: '↑', darr: '↓',
+    harr: '↔', hearts: '♥', not: '¬', brvbar: '¦', uml: '¨', acute: '´', cedil: '¸', macr: '¯', circ: 'ˆ', tilde: '˜',
+};
+// Greek letters by name (Alpha … Omega, alpha … omega, sigmaf).
+const GREEK = ['Alpha', 'Beta', 'Gamma', 'Delta', 'Epsilon', 'Zeta', 'Eta', 'Theta', 'Iota', 'Kappa', 'Lambda', 'Mu', 'Nu', 'Xi',
+    'Omicron', 'Pi', 'Rho', 'Sigma', 'Tau', 'Upsilon', 'Phi', 'Chi', 'Psi', 'Omega'];
+GREEK.forEach((name, i) => {
+    const offset = i + (i >= 17 ? 1 : 0);
+    NAMED[name] = String.fromCodePoint(0x391 + offset);
+    NAMED[name.toLowerCase()] = String.fromCodePoint(0x3b1 + offset);
+});
+NAMED.sigmaf = 'ς';
+// A Latin letter with a mark: &eacute; &Uuml; &ccedil; &scaron; … composed from the letter and a combining mark.
+const MARKS = {
+    acute: '́', grave: '̀', circ: '̂', tilde: '̃', uml: '̈', ring: '̊', cedil: '̧',
+    caron: '̌', macr: '̄', breve: '̆', ogon: '̨', dot: '̇', dblac: '̋',
+};
+const win1252 = new TextDecoder('windows-1252');
+function namedEntity(name) {
+    if (name in NAMED)
+        return NAMED[name];
+    const m = /^([a-zA-Z])(acute|grave|circ|tilde|uml|ring|cedil|caron|macr|breve|ogon|dot|dblac)$/.exec(name);
+    if (!m)
+        return undefined;
+    const composed = (m[1] + MARKS[m[2]]).normalize('NFC');
+    return [...composed].length === 1 ? composed : undefined;
+}
+function codePoint(n) {
+    if (n >= 0x80 && n <= 0x9f)
+        return win1252.decode(new Uint8Array([n])); // what browsers do with &#150; and the like
+    if (!Number.isFinite(n) || n <= 0 || n > 0x10ffff || (n >= 0xd800 && n <= 0xdfff))
+        return '�';
+    return String.fromCodePoint(n);
+}
+/** `&amp;`, `&#233;`, `&#x1F600;`, `&eacute;` and the other common names, decoded; unknown names are left as written. */
+export function decodeEntities(s) {
+    if (!s.includes('&'))
+        return s;
+    return s.replace(/&(#[xX][0-9a-fA-F]{1,6}|#\d{1,7}|[a-zA-Z][a-zA-Z0-9]{1,31});/g, (whole, ref) => {
+        if (ref[0] === '#')
+            return codePoint(ref[1] === 'x' || ref[1] === 'X' ? parseInt(ref.slice(2), 16) : parseInt(ref.slice(1), 10));
+        return namedEntity(ref) ?? whole;
+    });
+}
+const BLOCK = 'address|article|aside|blockquote|caption|center|dd|details|dialog|div|dl|dt|fieldset|figcaption|figure|footer|form|' +
+    'h[1-6]|header|hr|main|nav|ol|p|pre|section|summary|table|tbody|thead|tfoot|tr|ul';
+/** Removes every `<tag …>…</tag>` (nested ones too), for `blockquote`: the quoted earlier message in an HTML reply. */
+function dropElements(html, tag) {
+    const re = new RegExp(`<(/?)${tag}\\b[^>]*>`, 'gi');
+    let out = '';
+    let depth = 0;
+    let from = 0;
+    for (let m = re.exec(html); m; m = re.exec(html)) {
+        if (!m[1]) {
+            if (depth === 0)
+                out += html.slice(from, m.index);
+            depth++;
+        }
+        else if (depth > 0) {
+            depth--;
+            if (depth === 0)
+                from = m.index + m[0].length;
+        }
+    }
+    return depth === 0 ? out + html.slice(from) : out;
+}
+/** The `<title>` of an HTML page, else its first `<h1>`, as text; undefined when it has neither. */
+export function htmlTitle(html) {
+    for (const re of [/<title\b[^>]*>([\s\S]*?)<\/title\s*>/i, /<h1\b[^>]*>([\s\S]*?)<\/h1\s*>/i]) {
+        const m = re.exec(html);
+        const t = m ? decodeEntities(m[1].replace(/<[^>]*>/g, ' ')).replace(/\s+/g, ' ').trim() : '';
+        if (t)
+            return t;
+    }
+    return undefined;
+}
+/**
+ * HTML as plain text: scripts, styles, comments and the head dropped, blocks and line breaks kept as lines, list items
+ * as `- `, tags removed, entities decoded, `<pre>` kept as written. `dropQuotes` also drops `<blockquote>`s.
+ */
+export function htmlToText(html, opts = {}) {
+    let s = html
+        .replace(/<!--[\s\S]*?(-->|$)/g, ' ')
+        .replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, '$1')
+        .replace(/<(script|style|head|noscript|template|svg|math|iframe|object)\b[\s\S]*?<\/\1\s*>/gi, ' ')
+        .replace(/<(script|style)\b[\s\S]*$/i, ' '); // one left open runs to the end
+    if (opts.dropQuotes)
+        s = dropElements(s, 'blockquote');
+    // Whitespace in the source is one space, except inside <pre>.
+    s = s.split(/(<pre\b[\s\S]*?<\/pre\s*>)/i)
+        .map((piece, i) => (i % 2 ? piece.replace(/\r\n?/g, '\n') : piece.replace(/\s+/g, ' ')))
+        .join('');
+    s = s
+        .replace(/<br\b[^>]*>/gi, '\n')
+        .replace(/<li\b[^>]*>/gi, '\n- ')
+        .replace(new RegExp(`</?(?:${BLOCK})\\b[^>]*>`, 'gi'), '\n')
+        .replace(/<\/t[dh]\s*>/gi, '\t')
+        .replace(/<\/?[a-zA-Z][^>]*>/g, '')
+        .replace(/<[!?][^>]*>/g, '');
+    s = decodeEntities(s);
+    return tidy(s);
+}
+/** Lines trimmed at the end, spaces and tabs inside a line kept to one, at most one empty line in a row. */
+export function tidy(s) {
+    return s
+        .replace(/\r\n?/g, '\n')
+        .split('\n')
+        .map((l) => l.replace(/[ \t ]+/g, ' ').replace(/^ (?=\S)/, '').trimEnd())
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+/** Bytes as text in the charset named (any the platform knows); unnamed, ASCII or unknown: UTF-8, else Windows-1252. */
+export function decodeBytes(bytes, charset) {
+    const label = (charset ?? '').trim().replace(/^["']|["']$/g, '').replace(/\*.*$/, '').toLowerCase();
+    if (label && !/^(us-?ascii|ascii|ansi_x3\.4-1968|utf-?8|unicode-1-1-utf-8|x-unknown|unknown(-8bit)?|default)$/.test(label)) {
+        try {
+            return new TextDecoder(label).decode(bytes);
+        }
+        catch {
+            // A charset the platform does not know: read it as below.
+        }
+    }
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        return win1252.decode(bytes);
+    }
+}
+/**
+ * A long text in parts of at most `maxChars`, each cut at a paragraph, else a line, else a sentence's end (in any
+ * script), else a space; never inside a character.
+ */
+export function splitText(text, maxChars) {
+    const max = Math.max(100, Math.floor(maxChars));
+    if (text.length <= max)
+        return [text];
+    const parts = [];
+    let rest = text;
+    while (rest.length > max) {
+        const window = rest.slice(0, max);
+        const half = Math.floor(max / 2);
+        let cut = window.lastIndexOf('\n\n');
+        if (cut < half)
+            cut = window.lastIndexOf('\n');
+        if (cut < half) {
+            const ends = [...window.slice(half).matchAll(/\p{Sentence_Terminal}+/gu)].at(-1);
+            cut = ends ? half + ends.index + ends[0].length : -1;
+        }
+        if (cut < half)
+            cut = window.search(/\s\S*$/);
+        if (cut < half)
+            cut = max;
+        const code = rest.charCodeAt(cut - 1);
+        if (code >= 0xd800 && code <= 0xdbff)
+            cut--; // keep a surrogate pair together
+        const part = rest.slice(0, cut).trim();
+        if (part)
+            parts.push(part);
+        rest = rest.slice(cut);
+    }
+    if (rest.trim())
+        parts.push(rest.trim());
+    return parts;
+}
+/** A record without its empty fields. */
+export function record(r) {
+    const out = {};
+    for (const [k, v] of Object.entries(r)) {
+        if (v === undefined || (v === '' && k !== 'text'))
+            continue;
+        if (k === 'metadata' && v && typeof v === 'object') {
+            const m = Object.fromEntries(Object.entries(v).filter(([, x]) => x !== undefined && x !== ''));
+            if (Object.keys(m).length)
+                out.metadata = m;
+            continue;
+        }
+        out[k] = v;
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * memtrails — retrieval and exploration for any text: e-mail, chat, notes, documents, news, commits, conversations.
+ *
+ *   add          records, conversations, or a stream from an importer — searchable at once, no model asked
+ *   search       dense + keyword, fused; reordered word by word on this machine; dates first when asked
+ *   room         the best sentences of what was found, for a small context
+ *   open         one item whole, with the records it was learned from
+ *   explore      the concept graph from a topic or items to what search does not find
+ *   consolidate  (with a language model) typed knowledge, dated observations, kept episodes
+ *   sleep        (with a language model) merge, supersede, link, profiles
+ *   gather       (with a language model) every instance a counting or listing question needs
+ *   tools        memory_search / memory_open / memory_explore for an agent
+ */
+export { openMemory, type Memory, type MemoryOptions, type SearchOptions } from './memory.js';
+export { DEFAULT_COLLECTION, recordUid, timeOf, type Conversation, type MemoryRecord } from './records.js';
+export type { RecalledItem, RecordRef, SearchQuery, Explored } from './core/recall.js';
+export type { Gathered } from './core/gather.js';
+export type { ConsolidationReport } from './core/consolidate.js';
+export type { SleepReport } from './core/sleep.js';
+export { openAiAsk, type Ask, type LlmRequest, type LlmAnswer, type LlmUsage, type OpenAiAskOptions } from './llm.js';
+export { buildAgentTools, searchText, type AgentTool, type ToolProvider } from './tools/agent-tools.js';
+export { ensureModel, defaultModelDir, MODEL_REPO, MODEL_REVISION } from './core/model.js';
+export { ensureQdrant, QDRANT_VERSION } from './core/qdrant-binary.js';
+export type { EmbedRoute } from './core/embedder.js';
+export type { RerankRoute } from './core/reranker.js';
+export { sentenceRoom, sentenceSpans } from './core/room.js';
+export { maxSim, packWords, WordStore, WORD_LIMIT, type WordEncoder, type WordVectors, type PackedWords } from './core/words.js';
+export { cacheDir } from './core/paths.js';

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * memtrails — retrieval and exploration for any text: e-mail, chat, notes, documents, news, commits, conversations.
+ *
+ *   add          records, conversations, or a stream from an importer — searchable at once, no model asked
+ *   search       dense + keyword, fused; reordered word by word on this machine; dates first when asked
+ *   room         the best sentences of what was found, for a small context
+ *   open         one item whole, with the records it was learned from
+ *   explore      the concept graph from a topic or items to what search does not find
+ *   consolidate  (with a language model) typed knowledge, dated observations, kept episodes
+ *   sleep        (with a language model) merge, supersede, link, profiles
+ *   gather       (with a language model) every instance a counting or listing question needs
+ *   tools        memory_search / memory_open / memory_explore for an agent
+ */
+export { openMemory } from './memory.js';
+export { DEFAULT_COLLECTION, recordUid, timeOf } from './records.js';
+export { openAiAsk } from './llm.js';
+export { buildAgentTools, searchText } from './tools/agent-tools.js';
+export { ensureModel, defaultModelDir, MODEL_REPO, MODEL_REVISION } from './core/model.js';
+export { ensureQdrant, QDRANT_VERSION } from './core/qdrant-binary.js';
+export { sentenceRoom, sentenceSpans } from './core/room.js';
+export { maxSim, packWords, WordStore, WORD_LIMIT } from './core/words.js';
+export { cacheDir } from './core/paths.js';

package/dist/llm.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The language model memory asks, for consolidation, sleep and gathering — never for adding or searching. One structured
+ * ask: a system text, a prompt and a JSON Schema the answer must follow (strict structured output).
+ *
+ * `openAiAsk` speaks the OpenAI Responses API, so any provider or local server that serves it works (`baseUrl`). Bring
+ * any other model by passing your own `Ask`. Every call's tokens can be counted (`onUsage`).
+ */
+export interface LlmRequest {
+    /** What this is for, in a word (`memory`). */
+    purpose: string;
+    system: string;
+    prompt: string;
+    /** The answer's JSON Schema. */
+    schema: Record<string, unknown>;
+    /** What the structured answer is called. */
+    name?: string;
+    model?: string;
+    maxTokens?: number;
+    timeoutMs?: number;
+    /** What a failure cost, said after its reason ("so no summary was written"). */
+    consequence?: string;
+}
+export type LlmAnswer = {
+    answer: Record<string, unknown>;
+    model?: string;
+}
+/** Why it could not be asked, or did not answer, in words a person can read. */
+ | {
+    unavailable: string;
+}
+/** One for this purpose is already being asked. */
+ | {
+    busy: true;
+};
+export type Ask = (req: LlmRequest) => Promise<LlmAnswer>;
+export interface LlmUsage {
+    model: string;
+    name?: string;
+    inputTokens: number;
+    cachedTokens: number;
+    outputTokens: number;
+}
+export interface OpenAiAskOptions {
+    /** Default: $MEMTRAILS_LLM_API_KEY, else $OPENAI_API_KEY. */
+    apiKey?: string;
+    /** Default: $MEMTRAILS_MODEL. */
+    model?: string;
+    /** Default: $MEMTRAILS_LLM_BASE_URL, else https://api.openai.com/v1. */
+    baseUrl?: string;
+    /** For reasoning models: how hard to think. Not sent when not given. */
+    reasoningEffort?: 'minimal' | 'low' | 'medium' | 'high';
+    /** Each answered call's tokens. */
+    onUsage?: (u: LlmUsage) => void;
+    /** Tries after a rate limit, a server error or a dropped connection (default 5), waiting longer each time. */
+    retries?: number;
+    fetchImpl?: typeof fetch;
+}
+export declare function openAiAsk(o?: OpenAiAskOptions): Ask;
+/** The model the environment names (MEMTRAILS_MODEL and a key), asked when no `ask` is given. */
+export declare const defaultAsk: Ask;

package/dist/llm.js

@@ -0,0 +1,60 @@
+/**
+ * The language model memory asks, for consolidation, sleep and gathering — never for adding or searching. One structured
+ * ask: a system text, a prompt and a JSON Schema the answer must follow (strict structured output).
+ *
+ * `openAiAsk` speaks the OpenAI Responses API, so any provider or local server that serves it works (`baseUrl`). Bring
+ * any other model by passing your own `Ask`. Every call's tokens can be counted (`onUsage`).
+ */
+const why = (reason, req) => `${reason}${req.consequence ? `, ${req.consequence}` : ''}`;
+export function openAiAsk(o = {}) {
+    return async (req) => {
+        const model = req.model ?? o.model ?? process.env.MEMTRAILS_MODEL?.trim();
+        const key = o.apiKey ?? (process.env.MEMTRAILS_LLM_API_KEY?.trim() || process.env.OPENAI_API_KEY?.trim());
+        if (!model)
+            return { unavailable: why('no model is set (the model option, or MEMTRAILS_MODEL)', req) };
+        if (!key)
+            return { unavailable: why('no API key is set (the apiKey option, MEMTRAILS_LLM_API_KEY or OPENAI_API_KEY)', req) };
+        const base = (o.baseUrl ?? (process.env.MEMTRAILS_LLM_BASE_URL?.trim() || 'https://api.openai.com/v1')).replace(/\/+$/, '');
+        const body = JSON.stringify({
+            model, instructions: req.system, input: req.prompt, max_output_tokens: req.maxTokens ?? 12_000,
+            ...(o.reasoningEffort ? { reasoning: { effort: o.reasoningEffort } } : {}),
+            text: { format: { type: 'json_schema', name: req.name ?? 'memory', strict: true, schema: req.schema } },
+        });
+        const tries = Math.max(1, (o.retries ?? 5) + 1);
+        let last = '';
+        for (let attempt = 0; attempt < tries; attempt++) {
+            if (attempt)
+                await new Promise((ok) => setTimeout(ok, Math.min(60_000, 1000 * 2 ** (attempt - 1)) * (0.5 + Math.random())));
+            let res;
+            try {
+                res = await (o.fetchImpl ?? fetch)(`${base}/responses`, {
+                    method: 'POST', body, signal: AbortSignal.timeout(req.timeoutMs ?? 180_000),
+                    headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json' },
+                });
+            }
+            catch (err) {
+                last = err.message || err.name;
+                continue;
+            }
+            if (res.status === 429 || res.status >= 500) {
+                last = `HTTP ${res.status}`;
+                continue;
+            }
+            if (!res.ok)
+                return { unavailable: why(`the model answered HTTP ${res.status}`, req) };
+            try {
+                const r = (await res.json());
+                o.onUsage?.({ model: r.model ?? model, name: req.name, inputTokens: r.usage?.input_tokens ?? 0,
+                    cachedTokens: r.usage?.input_tokens_details?.cached_tokens ?? 0, outputTokens: r.usage?.output_tokens ?? 0 });
+                const text = (r.output ?? []).flatMap((x) => x.content ?? []).map((c) => c.text ?? '').join('');
+                return { model: r.model ?? model, answer: JSON.parse(text) };
+            }
+            catch (err) {
+                return { unavailable: why(`the model's answer could not be read (${err.message})`, req) };
+            }
+        }
+        return { unavailable: why(`the model did not answer (${last})`, req) };
+    };
+}
+/** The model the environment names (MEMTRAILS_MODEL and a key), asked when no `ask` is given. */
+export const defaultAsk = (req) => openAiAsk()(req);

package/dist/memory.d.ts

@@ -0,0 +1,106 @@
+import { type ConsolidationReport } from './core/consolidate.js';
+import { type EmbedRoute } from './core/embedder.js';
+import { type Gathered } from './core/gather.js';
+import { type Explored, type RecallDeps, type RecalledItem, type SearchQuery } from './core/recall.js';
+import { type RerankRoute } from './core/reranker.js';
+import { type SleepReport } from './core/sleep.js';
+import { type Ask, type OpenAiAskOptions } from './llm.js';
+import { type Conversation, type MemoryRecord } from './records.js';
+import { type AgentTool } from './tools/agent-tools.js';
+export interface MemoryOptions {
+    /** Where this memory lives: its logs, its index, its word vectors. */
+    home: string;
+    /** How texts are embedded (EmbeddingGemma-300m in every case: the index, prompts and measured thresholds are its):
+     *  - default: on this machine, the model fetched on first use into the cache (218 MB);
+     *  - `{ modelDir }`: on this machine, from a directory you provide;
+     *  - `{ server }`: a server that serves it over the OpenAI embeddings API (text-embeddings-inference, Ollama, …).
+     *    Word by word then needs `{ modelDir }` too, or it is off. */
+    embedding?: {
+        modelDir?: string;
+        server?: EmbedRoute;
+        threads?: number;
+    };
+    /** How the best 30 of a search are reordered: `'words'` (default with a local model: word by word, no server), a
+     *  cross-encoder server (`RerankRoute`), your own function, or `false` for the search's own order. */
+    rerank?: 'words' | RerankRoute | RecallDeps['rerank'] | false;
+    /** The language model for consolidate, sleep and gather: your own `Ask`, or options for the OpenAI-compatible one.
+     *  Default: the one the environment names (MEMTRAILS_MODEL and a key). */
+    llm?: Ask | OpenAiAskOptions;
+    /** Qdrant: default, a process of its own (the pinned binary, fetched on first use); or a server you run. */
+    qdrant?: {
+        url: string;
+        apiKey?: string;
+        collection?: string;
+    } | {
+        binary: string;
+    };
+    /** Windows the language model reads at once during consolidation (default 4). */
+    concurrency?: number;
+    log?: (line: string) => void;
+}
+export interface SearchOptions extends SearchQuery {
+    /** `relevance` (default) or `time` (oldest first) — for searchText. */
+    order?: 'relevance' | 'time';
+}
+export interface Memory {
+    /** Add or update records. Unchanged ones cost nothing. Searchable when this resolves. */
+    add(records: MemoryRecord | MemoryRecord[]): Promise<{
+        added: number;
+        unchanged: number;
+    }>;
+    /** Add or update a conversation: one record for each time the person speaks, with what was answered. */
+    addConversation(conversation: Conversation): Promise<{
+        added: number;
+        unchanged: number;
+    }>;
+    /** Add records from any source (an importer, a database cursor) in batches, streaming. */
+    import(records: AsyncIterable<MemoryRecord> | Iterable<MemoryRecord>, opts?: {
+        batch?: number;
+        onProgress?: (done: number) => void;
+    }): Promise<{
+        added: number;
+        unchanged: number;
+    }>;
+    /** Forget records: gone from search. What consolidation learned from them stays until sleep finds it unsupported. */
+    remove(ids: Array<string | {
+        id: string;
+        source?: string;
+    }>): Promise<number>;
+    /** Best first: records and what consolidation learned, each with its key text, dates, and the passage that matched. */
+    search(q: SearchOptions): Promise<RecalledItem[]>;
+    /** The same search as a reader is shown it: one line a memory, best first or oldest first. */
+    searchText(q: SearchOptions): Promise<string>;
+    /** What a small room should hold for a question: the best sentences of what search found, oldest first, in `chars`. */
+    room(q: SearchQuery & {
+        chars?: number;
+    }): Promise<string>;
+    /** One item whole, by the id search returned. */
+    open(id: string): Promise<Record<string, unknown> | null>;
+    /** Around a topic, or around items you found: what the concept graph reaches that search did not, and its concepts. */
+    explore(q: {
+        topic?: string;
+        from?: string[];
+        collections?: string[];
+        limit?: number;
+    }): Promise<Explored>;
+    /** A set for a question that counts, lists or totals: a wide search, then the language model keeps every instance. */
+    gather(q: SearchQuery): Promise<Gathered>;
+    /** Read what was added since last time and keep typed knowledge, dated observations and kept episodes. Needs a
+     *  language model. Returns how many windows were read. */
+    consolidate(): Promise<ConsolidationReport>;
+    /** The offline pass: merge near-duplicates, retire what was superseded, link, write profiles. Needs a language model. */
+    sleep(): Promise<SleepReport>;
+    /** Encode what word by word and the room do not hold yet (done after every add, consolidate and sleep). */
+    indexWords(): Promise<number>;
+    /** Write the index again from the logs. */
+    rebuild(): Promise<void>;
+    /** Tool definitions an agent can be handed: memory_search, memory_open, memory_explore. */
+    tools(): AgentTool[];
+    stats(): {
+        records: number;
+        items: number;
+        words: number;
+    };
+    close(): Promise<void>;
+}
+export declare function openMemory(o: MemoryOptions): Promise<Memory>;