memtrails 0.0.0-stage → 0.2.0

package/dist/memory.js

@@ -0,0 +1,262 @@
+/**
+ * memtrails: open a memory, add anything with text, ask it things.
+ *
+ *   const memory = await openMemory({ home: './memory' });
+ *   await memory.add({ id: 'mail-1', kind: 'email', title: 'Gateway certificate', author: 'Ana',
+ *                      text: 'It expired on the 1st; the renewal job had been removed.', at: '2026-04-02' });
+ *   await memory.search({ query: 'why did the certificate stop renewing?' });
+ *
+ * What is added is searchable at once, with no language model and no server: the embedding model runs here (fetched
+ * on first use) and orders results word by word (words.ts). A language model is needed only for `consolidate`,
+ * `sleep` and `gather`, which turn records into typed knowledge, dated observations and profiles — and memory works
+ * without them.
+ *
+ * The JSONL logs in `home` are the truth. The Qdrant index and the word vectors are derived: lost or out of date, they
+ * are written again from the logs.
+ */
+import { join, resolve } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { Consolidator } from './core/consolidate.js';
+import { remoteEmbedder } from './core/embedder.js';
+import { memoryGather } from './core/gather.js';
+import { loadLocalEmbedder } from './core/local-embedder.js';
+import { ensureModel } from './core/model.js';
+import { ensureQdrant } from './core/qdrant-binary.js';
+import { COLLECTION, QdrantClient } from './core/qdrant-client.js';
+import { QdrantProcess } from './core/qdrant-process.js';
+import { memoryExplore, memoryOpen, memorySearch } from './core/recall.js';
+import { RecallBook } from './core/recall-log.js';
+import { episodeBody } from './core/episodes.js';
+import { MemoryRebuild } from './core/rebuild.js';
+import { remoteReranker } from './core/reranker.js';
+import { sentenceRoom, sentenceSpans } from './core/room.js';
+import { Sleep } from './core/sleep.js';
+import { ltmLog, stmLog, UsageBook } from './core/store.js';
+import { WordStore, packWords, wordReranker } from './core/words.js';
+import { rawKey, stmItem, stmTitle, writeLtm, writeStm } from './core/writer.js';
+import { defaultAsk, openAiAsk } from './llm.js';
+import { conversationEntries, entryOf, invalidRecord, recordUid } from './records.js';
+import { buildAgentTools, lastedText, readableDate, searchText } from './tools/agent-tools.js';
+const BATCH = 32;
+const ROOM_TEXT = 1500;
+const ROOM_CHARS = 6000;
+const RECORD_LIMIT = 2_000_000;
+export async function openMemory(o) {
+    const dir = resolve(o.home);
+    mkdirSync(dir, { recursive: true });
+    const log = o.log ?? (() => { });
+    // Embedding: here, or on a server.
+    const e = o.embedding ?? {};
+    const local = !e.server || e.modelDir
+        ? await loadLocalEmbedder(e.modelDir ?? await ensureModel({ log }), { threads: e.threads ?? 2 })
+        : null;
+    const embed = e.server ? remoteEmbedder({ route: () => e.server }) : local.embed;
+    const encode = local?.words ?? null;
+    const words = new WordStore(join(dir, 'words.bin'));
+    await words.load();
+    // The index: a Qdrant of its own, or yours.
+    const q = o.qdrant;
+    let proc = null;
+    let endpoint;
+    if (q && 'url' in q) {
+        const fixed = { url: q.url.replace(/\/+$/, ''), apiKey: q.apiKey ?? '' };
+        endpoint = () => fixed;
+    }
+    else {
+        proc = new QdrantProcess({ binary: q && 'binary' in q ? q.binary : await ensureQdrant({ log }), dir: join(dir, 'qdrant'), log });
+        await proc.start();
+        endpoint = () => proc.current();
+    }
+    const client = new QdrantClient(endpoint, 10_000, { collection: q && 'url' in q ? q.collection ?? COLLECTION : COLLECTION });
+    await client.ensureCollection();
+    const stm = stmLog(join(dir, 'records.jsonl'));
+    const ltm = ltmLog(join(dir, 'knowledge.jsonl'));
+    await stm.load();
+    await ltm.load();
+    const usage = new UsageBook(join(dir, 'usage.json'));
+    const book = new RecallBook(join(dir, 'recall.jsonl'));
+    const ask = typeof o.llm === 'function' ? o.llm : o.llm ? openAiAsk(o.llm) : defaultAsk;
+    const base = { client, embed, stm, ltm, log, aborted: () => false, ask };
+    const rerank = o.rerank === false ? undefined
+        : typeof o.rerank === 'function' ? o.rerank
+            : o.rerank && typeof o.rerank === 'object' ? remoteReranker({ route: () => o.rerank })
+                : encode ? wordReranker(encode, words) : undefined;
+    const deps = { client, embed, rerank, used: (ids, what) => usage.note(ids, what), record: (ev) => book.record(ev) };
+    // The index is derived: empty while the logs are not (a new Qdrant, a deleted folder), it is written again.
+    const rebuild = new MemoryRebuild({
+        path: join(dir, 'rebuild.json'), stm, ltm, aborted: () => false,
+        writeStm: (xs) => writeStm(base, xs), writeLtm: (xs) => writeLtm(base, xs),
+    });
+    if (rebuild.pending() || (!(await client.count()) && (stm.size() || ltm.size()))) {
+        log('[memtrails] writing the index from the logs');
+        if (!rebuild.pending())
+            rebuild.begin();
+        await rebuild.run();
+    }
+    /** The text word by word scores an item by: its key, as search returns it. */
+    const keyText = (title, summary) => `${title}\n${summary}`;
+    /** A found item's whole text for the room: a record's own, or what consolidation wrote. */
+    const roomItem = (h) => {
+        const r = h.id.startsWith('stm:') ? stm.get(h.id.slice(4)) : null;
+        const it = r ? null : ltm.get(h.id);
+        const text = r ? `${r.request}\n${r.reply}` : it ? `${it.title}\n${it.summary}\n${it.body}` : `${h.title}\n${h.summary}`;
+        const told = h.ts ? new Date(h.ts).toISOString().slice(0, 10) : '';
+        const lasted = lastedText(h);
+        const happened = [h.eventAt ? readableDate(h.eventAt) : '', lasted].filter(Boolean).join(', ');
+        const when = happened ? `${happened}${h.eventAt !== told || lasted ? `; told ${readableDate(told)}` : ''}` : readableDate(told);
+        return { id: h.id, head: `(${when} · ${h.kind})`, text: text.slice(0, ROOM_TEXT), ts: h.eventAt ? Date.parse(h.eventAt) : h.ts };
+    };
+    const encodeMissing = async (texts) => {
+        if (!encode)
+            return 0;
+        const todo = [...new Set(texts)].filter((t) => t.trim() && !words.get(t));
+        for (let i = 0; i < todo.length; i += BATCH) {
+            const part = todo.slice(i, i + BATCH);
+            const encoded = await encode(part, 'document');
+            await words.put(part.map((t, n) => [t, packWords(encoded[n])]));
+        }
+        return todo.length;
+    };
+    const wordsOfEntries = (es) => es.flatMap((x) => {
+        const room = `${x.request}\n${x.reply}`.slice(0, ROOM_TEXT);
+        return [keyText(stmTitle(x), rawKey(x)), ...sentenceSpans(room).map(([a, b]) => room.slice(a, b))];
+    });
+    const write = async (entries, total) => {
+        const fresh = entries.filter((x) => stm.meta(x.uid)?.fp !== x.fingerprint);
+        for (let i = 0; i < fresh.length; i += BATCH) {
+            const part = fresh.slice(i, i + BATCH);
+            await writeStm(base, part);
+            stm.put(part);
+            await encodeMissing(wordsOfEntries(part));
+        }
+        stm.compact();
+        return { added: fresh.length, unchanged: total - fresh.length };
+    };
+    const memory = {
+        async add(records) {
+            const list = Array.isArray(records) ? records : [records];
+            const now = Date.now();
+            for (const r of list) {
+                const bad = invalidRecord(r);
+                if (bad)
+                    throw new TypeError(bad);
+                if (r.text.length > RECORD_LIMIT)
+                    throw new TypeError(`record ${r.id}: longer than ${RECORD_LIMIT} characters; split it`);
+            }
+            return write(list.map((r) => entryOf(r, now)), list.length);
+        },
+        async addConversation(c) {
+            if (!c?.id || !Array.isArray(c.turns))
+                throw new TypeError('a conversation needs an id and turns');
+            const entries = conversationEntries(c, Date.now());
+            return write(entries, entries.length);
+        },
+        async import(records, opts = {}) {
+            const size = opts.batch ?? 256;
+            let batch = [];
+            const total = { added: 0, unchanged: 0 };
+            const flush = async () => {
+                if (!batch.length)
+                    return;
+                const r = await memory.add(batch);
+                total.added += r.added;
+                total.unchanged += r.unchanged;
+                opts.onProgress?.(total.added + total.unchanged);
+                batch = [];
+            };
+            for await (const r of records) {
+                batch.push(r);
+                if (batch.length >= size)
+                    await flush();
+            }
+            await flush();
+            return total;
+        },
+        async remove(ids) {
+            const uids = ids.map((x) => recordUid(typeof x === 'string' ? { id: x } : x)).filter((u) => stm.meta(u));
+            if (!uids.length)
+                return 0;
+            await client.deleteItems(uids.flatMap((u) => [stmItem(u), `ep:${u}`]));
+            stm.remove(uids);
+            return uids.length;
+        },
+        search: (s) => memorySearch(deps, s),
+        searchText: async (s) => searchText(await memorySearch(deps, s), s.order ?? 'relevance'),
+        async room(s) {
+            if (!encode)
+                throw new Error('the room needs the local embedding model (embedding.modelDir, or no embedding.server)');
+            const found = await memorySearch(deps, { ...s, limit: s.limit ?? 20 });
+            return sentenceRoom(s.query, found.map(roomItem), encode, words, s.chars ?? ROOM_CHARS);
+        },
+        async open(id) {
+            const p = await memoryOpen(deps, id);
+            if (!p)
+                return null;
+            // A record: its kind as given. Something learned: the records it was learned from, whole.
+            if (p.tier === 'stm')
+                return { ...p, kind: p.engine };
+            const it = ltm.get(id);
+            const sources = (it?.provenance ?? []).map((u) => stm.get(u)).filter((x) => !!x)
+                .map((x) => ({ id: stmItem(x.uid), when: x.ts, title: x.title, body: episodeBody(x), ...(x.record ? { record: x.record } : {}) }));
+            return sources.length ? { ...p, sources } : p;
+        },
+        explore: (s) => memoryExplore(deps, s),
+        gather: (s) => memoryGather(deps, s, { ask, ...(s.limit ? { limit: s.limit } : {}) }),
+        async consolidate() {
+            const worker = new Consolidator({ ...base, concurrency: o.concurrency ?? 4 });
+            const total = { windows: 0, added: 0, merged: 0, updated: 0, superseded: 0, linked: 0, dropped: 0, episodes: 0, observed: 0, cued: 0 };
+            for (let round = 0; round < 1000 && worker.pending().length; round++) {
+                const r = await worker.run(64);
+                for (const k of Object.keys(total))
+                    if (typeof r[k] === 'number')
+                        total[k] += r[k];
+                if (r.paused !== undefined) {
+                    total.paused = r.paused;
+                    break;
+                }
+                if (!r.windows)
+                    break;
+            }
+            await memory.indexWords();
+            return total;
+        },
+        async sleep() {
+            const r = await new Sleep({ ...base, usage, statePath: join(dir, 'sleep.json') }).run();
+            await memory.indexWords();
+            return r;
+        },
+        async indexWords() {
+            if (!encode)
+                return 0;
+            const texts = [...stm.all()].flatMap((x) => wordsOfEntries([x]));
+            for (const [uid, m] of ltm.entries()) {
+                if (m.status !== 'active')
+                    continue;
+                const it = ltm.get(uid);
+                if (!it)
+                    continue;
+                const room = `${it.title}\n${it.summary}\n${it.body}`.slice(0, ROOM_TEXT);
+                texts.push(keyText(it.title, it.summary), ...sentenceSpans(room).map(([a, b]) => room.slice(a, b)));
+            }
+            return encodeMissing(texts);
+        },
+        async rebuild() {
+            await client.dropCollection();
+            await client.ensureCollection();
+            rebuild.begin();
+            await rebuild.run();
+        },
+        tools: () => buildAgentTools({
+            search: (s) => memorySearch(deps, s),
+            open: (id) => memory.open(id),
+            explore: (s) => memoryExplore(deps, s),
+        }),
+        stats: () => ({ records: stm.size(), items: [...ltm.entries()].filter(([, m]) => m.status === 'active').length, words: words.size }),
+        async close() {
+            usage.flush();
+            await proc?.stopAndWait();
+            await local?.close();
+        },
+    };
+    return memory;
+}

package/dist/records.d.ts

@@ -0,0 +1,62 @@
+import type { StmEntry } from './core/store.js';
+/** One piece of information to remember. */
+export interface MemoryRecord {
+    /** Stable and unique within its `source`: the same id added again replaces the record (unchanged: nothing is done). */
+    id: string;
+    /** The content. */
+    text: string;
+    /** A subject, headline or name; when absent, the first line of the text. */
+    title?: string;
+    /** What it is, in one word of your choosing: `email`, `message`, `note`, `memo`, `article`, `commit`, `ticket`, … */
+    kind?: string;
+    /** Where it came from: a mailbox, a workspace, a feed, a repository. Part of the record's identity. */
+    source?: string;
+    /** What it belongs to, for searches scoped to one collection: a project, a team, a customer, a person. */
+    collection?: string;
+    /** Records that belong together share a thread (an e-mail thread, a chat thread, a repository's history). */
+    thread?: string;
+    /** Who wrote it. */
+    author?: string;
+    /** When it was written: milliseconds since the epoch, an ISO date, or a Date. Default: when it was added. */
+    at?: number | string | Date;
+    /** Where to open it. */
+    url?: string;
+    /** Anything else, kept with the record and returned with it. Not searched. */
+    metadata?: Record<string, string | number | boolean | null>;
+}
+/** A conversation: turns between a person and an assistant (or any two parties), in order. */
+export interface Conversation {
+    /** Stable: the same id added again is read again, not doubled. */
+    id: string;
+    collection?: string;
+    source?: string;
+    /** When it began (each turn may carry its own `at`). */
+    at?: number | string | Date;
+    turns: Array<{
+        role: 'user' | 'assistant';
+        text: string;
+        author?: string;
+        at?: number | string | Date;
+    }>;
+}
+/** The collection records without one belong to. */
+export declare const DEFAULT_COLLECTION = "default";
+/** A time as milliseconds; undefined for nothing or something unreadable. */
+export declare function timeOf(at: number | string | Date | undefined): number | undefined;
+/** A collection as the index keys it: one path segment, any script kept. */
+export declare function collectionKey(collection: string | undefined): string;
+/** A record's id in memory: its source and id, hashed (any characters may be in either). */
+export declare function recordUid(r: Pick<MemoryRecord, 'id' | 'source'>): string;
+/** Checks a record and says what is wrong with it, or null. */
+export declare function invalidRecord(r: MemoryRecord): string | null;
+/**
+ * A record as memory keeps it: the title is what it is about (the first line when there is none), the text after the
+ * author is the content. Searchable as written: its start is its key, and every word of it is in a chunk.
+ */
+export declare function entryOf(r: MemoryRecord, now: number, turn?: number): StmEntry;
+/**
+ * A conversation's turns as records: each time the person speaks, what they said is the request and what the other
+ * side answered until they speak again is its reply — one record a request, so a question finds the exchange it was in.
+ * Turns before the first request (an assistant that opened) are the first record's own.
+ */
+export declare function conversationEntries(c: Conversation, now: number): StmEntry[];

package/dist/records.js

@@ -0,0 +1,107 @@
+/**
+ * What memtrails stores: records. Anything with text is a record — an e-mail, a chat message, a note, a memo, a news
+ * article, a commit message, a ticket, a page of a document. Records that belong together (an e-mail thread, a chat
+ * thread, a meeting's notes) share a `thread`; a conversation between a person and an assistant is a thread of turns.
+ *
+ * Every record is searchable the moment it is added, with no model asked. Consolidation (optional, with a language
+ * model) reads threads in windows and keeps typed knowledge from them; the records themselves are never lost.
+ */
+import { createHash } from 'node:crypto';
+/** The collection records without one belong to. */
+export const DEFAULT_COLLECTION = 'default';
+/** A time as milliseconds; undefined for nothing or something unreadable. */
+export function timeOf(at) {
+    if (at === undefined || at === null || at === '')
+        return undefined;
+    const t = at instanceof Date ? at.getTime() : typeof at === 'number' ? at : Date.parse(at);
+    return Number.isFinite(t) ? t : undefined;
+}
+/** A collection as the index keys it: one path segment, any script kept. */
+export function collectionKey(collection) {
+    const c = (collection ?? '').trim();
+    return c ? c.replace(/[\s/\\:]+/g, '-') : DEFAULT_COLLECTION;
+}
+function hash(...parts) {
+    return createHash('sha256').update(parts.map((p) => p ?? '').join('\u0000')).digest('hex');
+}
+/** A record's id in memory: its source and id, hashed (any characters may be in either). */
+export function recordUid(r) {
+    return hash(r.source ?? '', r.id).slice(0, 32);
+}
+/** Checks a record and says what is wrong with it, or null. */
+export function invalidRecord(r) {
+    if (!r || typeof r !== 'object')
+        return 'a record must be an object';
+    if (typeof r.id !== 'string' || !r.id.trim())
+        return 'a record needs an id';
+    if (typeof r.text !== 'string')
+        return `record ${r.id}: text must be a string`;
+    if (!r.text.trim() && !r.title?.trim())
+        return `record ${r.id}: it has no text and no title`;
+    if (r.at !== undefined && timeOf(r.at) === undefined)
+        return `record ${r.id}: its time cannot be read (${String(r.at)})`;
+    return null;
+}
+/**
+ * A record as memory keeps it: the title is what it is about (the first line when there is none), the text after the
+ * author is the content. Searchable as written: its start is its key, and every word of it is in a chunk.
+ */
+export function entryOf(r, now, turn = 0) {
+    const text = r.text.trim();
+    const firstLine = text.split('\n').map((l) => l.trim()).find(Boolean) ?? '';
+    const title = r.title?.trim() || firstLine;
+    // Without a title its first line is the title, and not said twice.
+    const body = r.title?.trim() ? text : text.slice(text.indexOf(firstLine) + firstLine.length).trim();
+    const by = r.author?.trim() ? `${r.author.trim()}: ` : '';
+    const uid = recordUid(r);
+    const reply = `${by}${body}`;
+    return {
+        uid, fingerprint: hash(title, reply, r.url, r.kind, r.collection, r.thread, String(timeOf(r.at) ?? ''), JSON.stringify(r.metadata ?? {})),
+        engine: r.kind?.trim() || 'record', session: r.thread?.trim() || uid, turn, cwd: null, project: collectionKey(r.collection),
+        title, ts: timeOf(r.at) ?? now, synthetic: false, typed: 'human', request: title, reply, said: reply, steps: [],
+        files: r.url ? [r.url] : [], done: false,
+        record: { id: r.id, ...(r.source ? { source: r.source } : {}), ...(r.author ? { author: r.author } : {}), ...(r.url ? { url: r.url } : {}),
+            ...(r.metadata ? { metadata: r.metadata } : {}) },
+    };
+}
+/**
+ * A conversation's turns as records: each time the person speaks, what they said is the request and what the other
+ * side answered until they speak again is its reply — one record a request, so a question finds the exchange it was in.
+ * Turns before the first request (an assistant that opened) are the first record's own.
+ */
+export function conversationEntries(c, now) {
+    const start = timeOf(c.at) ?? now;
+    const out = [];
+    let request = [];
+    let reply = [];
+    let at;
+    const flush = () => {
+        if (!request.length && !reply.length)
+            return;
+        const n = out.length;
+        const e = entryOf({ id: `${c.id}#${n}`, source: c.source, collection: c.collection, thread: c.id, kind: 'conversation',
+            title: request.join('\n').split('\n').find((l) => l.trim())?.trim() || reply.join('\n').split('\n').find((l) => l.trim())?.trim() || c.id,
+            text: request.join('\n'), at: at ?? start + n * 60_000 }, now, n);
+        out.push({ ...e, request: request.join('\n') || e.title, reply: reply.join('\n'), said: reply.join('\n') });
+        request = [];
+        reply = [];
+        at = undefined;
+    };
+    for (const t of c.turns) {
+        const text = `${t.author?.trim() ? `${t.author.trim()}: ` : ''}${t.text.trim()}`;
+        if (!t.text.trim())
+            continue;
+        if (t.role === 'user') {
+            if (reply.length)
+                flush();
+            request.push(text);
+            at ??= timeOf(t.at);
+        }
+        else {
+            reply.push(text);
+            at ??= timeOf(t.at);
+        }
+    }
+    flush();
+    return out.map((e) => ({ ...e, fingerprint: hash(e.fingerprint, e.request, e.reply) }));
+}

package/dist/tools/agent-tools.d.ts

@@ -0,0 +1,52 @@
+/**
+ * An agent's tools over a memory: `memory_search` (find), `memory_open` (read one whole, with the records it was learned
+ * from) and `memory_explore` (from a topic or items to what is related but not found by search). Defined with zod
+ * schemas, as MCP servers declare tools; `jsonSchema` gives the same input schema for function calling APIs.
+ *
+ *   const tools = memory.tools();   // hand them to an MCP server, or to a model's tool calling
+ */
+import { z } from 'zod';
+import type { Explored, RecalledItem, SearchQuery } from '../core/recall.js';
+type ToolResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+};
+export interface AgentTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, z.ZodType>;
+    /** The input schema as JSON Schema, for function calling. */
+    jsonSchema: Record<string, unknown>;
+    handler: (args: any, extra?: unknown) => Promise<ToolResult>;
+}
+/** What the tools read: a memory (openMemory) gives these. */
+export interface ToolProvider {
+    search(q: SearchQuery): Promise<RecalledItem[]>;
+    open(id: string): Promise<Record<string, unknown> | null>;
+    explore?(q: {
+        topic?: string;
+        from?: string[];
+        collections?: string[];
+        limit?: number;
+    }): Promise<Explored>;
+}
+type CrossMemoryHit = RecalledItem;
+/** A date as a reader reckons with it — the weekday too ("the Friday before …"): 2023-07-14 → "Fri 14 Jul 2023". */
+export declare function readableDate(d: string): string;
+/** How long something lasted, as a reader reckons with it: "since Feb 2022", "Nov 2021 – May 2022". */
+export declare function lastedText(h: {
+    startAt?: unknown;
+    endAt?: unknown;
+}): string;
+/** All of a profile — what memory knows about one subject, one dated fact a line (core/profiles.ts) — up to this:
+ *  measured, a profile cut like any other item lost most of its gain. */
+export declare const PROFILE_SHOWN = 1500;
+/** What memory_search shows: an observation as one dated line (when it happened, and when it was told when that
+ *  differs), a profile whole (up to PROFILE_SHOWN), anything else as its title line and summary — shorter when many
+ *  are asked for. Best first, or by time. */
+export declare function searchText(hits: CrossMemoryHit[], order?: 'relevance' | 'time'): string;
+export declare function buildAgentTools(p: ToolProvider): AgentTool[];
+export {};

package/dist/tools/agent-tools.js

@@ -0,0 +1,142 @@
+/**
+ * An agent's tools over a memory: `memory_search` (find), `memory_open` (read one whole, with the records it was learned
+ * from) and `memory_explore` (from a topic or items to what is related but not found by search). Defined with zod
+ * schemas, as MCP servers declare tools; `jsonSchema` gives the same input schema for function calling APIs.
+ *
+ *   const tools = memory.tools();   // hand them to an MCP server, or to a model's tool calling
+ */
+import { z } from 'zod';
+function tool(name, description, inputSchema, handler) {
+    return { name, description, inputSchema, jsonSchema: z.toJSONSchema(z.object(inputSchema)), handler: handler };
+}
+const DESCRIPTIONS = {
+    memory_search: 'Search memory: everything it was given (e-mails, messages, notes, documents, conversations, commits, …) and '
+        + 'what was learned from them — facts, decisions, dated events, profiles of people and things. Best first; each result '
+        + 'with its date and id. Ask in plain words, as you would ask a colleague who read it all. Name dates when the question '
+        + 'names a time. Open a result with memory_open for all of it.',
+    memory_open: 'Read one memory item whole, by the id memory_search or memory_explore gave: everything it holds, when it '
+        + 'happened, and for something learned, the records it was learned from.',
+    memory_explore: 'Explore memory around a topic, or around items you already found: it follows what they share — the same '
+        + 'people, places, systems, names — and links between memories, to what a search for the words does not find. Returns '
+        + 'what search found, what is related, and the concepts around it to explore next.',
+};
+const day = (ts) => (ts ? new Date(ts).toISOString().slice(0, 10) : '');
+const hitLine = (h, n) => `${n + 1}. ${h.title} (${h.kind === 'episode' ? 'earlier work' : h.kind} · ${day(h.ts)}${h.record?.author ? ` · ${h.record.author}` : ''} · id ${h.id})`;
+const WEEKDAY = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const MONTH = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+/** A date as a reader reckons with it — the weekday too ("the Friday before …"): 2023-07-14 → "Fri 14 Jul 2023". */
+export function readableDate(d) {
+    const [y, m, dd] = d.split('-').map(Number);
+    if (!y)
+        return '';
+    if (!m)
+        return String(y);
+    if (!dd)
+        return `${MONTH[m - 1]} ${y}`;
+    return `${WEEKDAY[new Date(Date.UTC(y, m - 1, dd)).getUTCDay()]} ${dd} ${MONTH[m - 1]} ${y}`;
+}
+/** How long something lasted, as a reader reckons with it: "since Feb 2022", "Nov 2021 – May 2022". */
+export function lastedText(h) {
+    const [from, to] = [h.startAt, h.endAt].map((d) => (typeof d === 'string' && d ? readableDate(d) : ''));
+    if (from && to)
+        return `${from} – ${to}`;
+    return from ? `since ${from}` : to ? `until ${to}` : '';
+}
+/** When a hit happened, for ordering by time: an observation's own date, else when it was learned. */
+const when = (h) => h.eventAt || day(h.ts);
+/** All of a profile — what memory knows about one subject, one dated fact a line (core/profiles.ts) — up to this:
+ *  measured, a profile cut like any other item lost most of its gain. */
+export const PROFILE_SHOWN = 1500;
+const cutAt = (s, n) => (s.length > n ? `${s.slice(0, n)}…` : s);
+/** What memory_search shows: an observation as one dated line (when it happened, and when it was told when that
+ *  differs), a profile whole (up to PROFILE_SHOWN), anything else as its title line and summary — shorter when many
+ *  are asked for. Best first, or by time. */
+export function searchText(hits, order = 'relevance') {
+    const list = order === 'time' ? [...hits].sort((a, b) => when(a).localeCompare(when(b))) : hits;
+    // Many hits: one line each — the date, what it is, its summary — so a list question sees every one of them clearly.
+    const compact = list.length > 20;
+    const lines = list.map((h, n) => {
+        if (h.kind === 'profile')
+            return `${hitLine(h, n)}\n   ${cutAt(h.summary, PROFILE_SHOWN).replace(/\n/g, '\n   ')}`;
+        if (h.kind !== 'observation') {
+            // The passage that matched, when it was not the start: a fact said deep in a long request is what was found.
+            const matched = h.match ? ` … ${h.match.replace(/\s+/g, ' ')}` : '';
+            if (!compact)
+                return `${hitLine(h, n)}\n   ${h.summary.slice(0, h.match ? 200 : 500)}${matched}`;
+            const what = h.kind === 'episode' ? 'earlier work' : h.kind;
+            return `${n + 1}. (${readableDate(day(h.ts))} · ${what}) ${h.summary.replace(/\s+/g, ' ').slice(0, h.match ? 150 : 300)}${matched} (id ${h.id})`;
+        }
+        const told = day(h.ts);
+        const lasted = lastedText(h);
+        const happened = [h.eventAt ? readableDate(h.eventAt) : '', lasted].filter(Boolean).join(', ');
+        const at = happened ? `${happened}${h.eventAt !== told || lasted ? `; told ${readableDate(told)}` : ''}` : `told ${readableDate(told)}`;
+        return `${n + 1}. (${at}) ${h.summary} (id ${h.id})`;
+    });
+    return `${order === 'time' ? 'Oldest first — the date is when it happened (and when it was told, when that differs).\n' : ''}${lines.join('\n')}`;
+}
+function memoryTools(p) {
+    return [
+        tool('memory_search', DESCRIPTIONS.memory_search, {
+            query: z.string().describe('What you need to know, in plain words.'),
+            collections: z.array(z.string()).optional().describe('Only these collections (default: all).'),
+            limit: z.number().int().min(1).max(200).optional().describe('How many of each to return — dated observations, and other memories (default 20; 100 to 200 when you gather everything on a topic, list or count things, or need their dates).'),
+            order: z.enum(['relevance', 'time']).optional().describe('Best first (default), or oldest first — for what happened when, and in what order.'),
+            from: z.string().regex(/^\d{4}(-\d{2}(-\d{2})?)?$/).optional().describe('Only what happened on or after this date (YYYY-MM-DD, YYYY-MM or YYYY) — when the request names a time ("in June 2023", "last week").'),
+            to: z.string().regex(/^\d{4}(-\d{2}(-\d{2})?)?$/).optional().describe('Only what happened on or before this date (YYYY-MM-DD, YYYY-MM or YYYY).'),
+        }, async (args) => {
+            try {
+                const hits = await p.search({ query: args.query, collections: args.collections, limit: args.limit ?? 20, from: args.from, to: args.to });
+                if (!hits.length)
+                    return text('Nothing in memory matches that.');
+                return text(`${searchText(hits, args.order)}\n\nOpen one with memory_open and its id. It can be stale: check it against the current state before relying on it.`);
+            }
+            catch (err) {
+                return text(err.message, true);
+            }
+        }),
+        tool('memory_open', DESCRIPTIONS.memory_open, { id: z.string().describe('The memory id, as memory_search or memory_explore gave it.') }, async (args) => {
+            const it = await p.open(args.id).catch(() => null);
+            if (!it)
+                return text(`There is no memory "${args.id}" (it may have been merged or cleared).`, true);
+            const files = Array.isArray(it.files) && it.files.length ? `\nFiles: ${it.files.join(', ')}` : '';
+            const told = day(Number(it.ts ?? 0));
+            const happened = [typeof it.eventAt === 'string' && it.eventAt ? readableDate(it.eventAt) : '', lastedText(it)].filter(Boolean).join(', ');
+            const when = happened ? `happened ${happened}; told ${readableDate(told)}` : told;
+            // The raw requests it was learned from, whole (the truth it is a key to), and the texts a merge folded into it.
+            const sources = Array.isArray(it.sources) && it.sources.length
+                ? `\n\n## Where it came from\n${it.sources.map((x) => `### ${day(x.when)} · ${x.title} (id ${x.id})\n${x.body}`).join('\n\n')}` : '';
+            const absorbed = Array.isArray(it.absorbed) && it.absorbed.length
+                ? `\n\n## Texts merged into it\n${it.absorbed.map((x) => `### ${x.title}\n${x.summary}\n${x.body}`).join('\n\n')}` : '';
+            return text(`# ${String(it.title ?? '')}\n(${String(it.kind ?? '')} · ${when} · ${String(it.project ?? '')})\n\n${String(it.summary ?? '')}\n\n${String(it.body ?? '')}${files}${sources}${absorbed}`);
+        }),
+        ...(p.explore ? [tool('memory_explore', DESCRIPTIONS.memory_explore, {
+                topic: z.string().optional().describe('What to explore, in plain words — a system, a project, a problem, a name.'),
+                from: z.array(z.string()).max(5).optional().describe('Memory ids to explore from, as memory_search or memory_explore gave them.'),
+                collections: z.array(z.string()).optional().describe('Only these collections (default: all).'),
+                limit: z.number().int().min(1).max(20).optional().describe('How many related items to return (default 10).'),
+            }, async (args) => {
+                if (!args.topic?.trim() && !args.from?.length)
+                    return text('Give a topic, or memory ids to explore from.', true);
+                try {
+                    const r = await p.explore({ topic: args.topic, from: args.from, collections: args.collections, limit: args.limit ?? 10 });
+                    const parts = [];
+                    if (r.found.length)
+                        parts.push(`Found by search:\n${r.found.map(hitLine).join('\n')}`);
+                    if (r.related.length)
+                        parts.push(`Related — not found by search, reached through what they share:\n${r.related.map((h, n) => `${hitLine(h, n)} — ${h.via}\n   ${h.summary.slice(0, 300)}`).join('\n')}`);
+                    if (r.concepts.length)
+                        parts.push(`Concepts around it: ${r.concepts.join(', ')}`);
+                    if (!parts.length)
+                        return text('Nothing in memory reaches that.');
+                    return text(`${parts.join('\n\n')}\n\nOpen one with memory_open; explore further from an item (from: [its id]) or with one of the concepts as the topic. It can be stale: check it against the current state before relying on it.`);
+                }
+                catch (err) {
+                    return text(err.message, true);
+                }
+            })] : []),
+    ];
+}
+const text = (t, isError = false) => ({ content: [{ type: 'text', text: t }], ...(isError ? { isError: true } : {}) });
+export function buildAgentTools(p) {
+    return memoryTools(p);
+}