oortmem 0.0.0-stage → 0.1.0

package/dist/commands/doctor.js

@@ -0,0 +1,410 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { filterFor, hookStatus } from '@oortmem/claude-code';
+import { resolveConfig, resolveHome, localGrant } from '@oortmem/core';
+import { HOSTS, HOST_LABEL, detectHosts, inspectHost } from '../connectors.js';
+import { ROLES, ROLE_VENDOR, keyLookup, routeFor } from '../credentials.js';
+import { describeProblem, inspectCredentialsFile } from '../credentials-file.js';
+import { PROVIDER_ENV } from '../keychain.js';
+import { RELAY_MODELS, relayUrl } from '../relay.js';
+import { uiFor } from '../ui.js';
+import { Refusal, echo, tilde, withWired } from '../util.js';
+import { hostContext } from './connect.js';
+import { hookCommandPath, settingsFile } from './install.js';
+const ROLE_NEED = {
+    embed: 'recall is lexical-only',
+    rerank: 'recall is not reranked',
+    decide: 'nothing new is saved',
+    write: 'nothing new is saved',
+};
+const CONFIG_KEY = {
+    embed: 'embed',
+    rerank: 'rerank',
+    decide: 'decide',
+    write: 'writer',
+};
+/** Keys: which one serves each role (presence only), and whether the relay can serve it. */
+async function keyChecks(ctx) {
+    const env = ctx.io.env;
+    const lookup = keyLookup(env, ctx.keychain.read);
+    let config;
+    try {
+        config = resolveConfig(ctx.io.cwd, env);
+    }
+    catch {
+        config = undefined; // the store check reports an invalid config
+    }
+    const checks = [];
+    let relayed = false;
+    for (const role of ROLES) {
+        const r = await routeFor(role, lookup);
+        const where = (source, provider) => source === 'env'
+            ? PROVIDER_ENV[provider]
+            : ctx.keychain.where(provider);
+        if (r.via === 'vendor') {
+            checks.push({
+                group: 'keys',
+                name: role,
+                status: 'ok',
+                detail: `own ${r.provider} key (${where(r.source, r.provider)})`,
+            });
+            continue;
+        }
+        if (r.via === 'none') {
+            checks.push({
+                group: 'keys',
+                name: role,
+                status: 'warn',
+                detail: `no ${r.provider} key and no Oort key, so ${ROLE_NEED[role]}`,
+                fix: ctx.keychain.supported
+                    ? `oort keys set ${r.provider}, or oort login (Oort Pro)`
+                    : `export ${PROVIDER_ENV[r.provider]}=..., or OORT_API_KEY=... from oortcloud.dev/account (Oort Pro)`,
+            });
+            continue;
+        }
+        relayed = true;
+        const allowed = RELAY_MODELS[role];
+        const model = config?.[CONFIG_KEY[role]];
+        if (allowed !== undefined && model?.model !== undefined && !allowed.includes(model.model)) {
+            checks.push({
+                group: 'keys',
+                name: role,
+                status: 'fail',
+                detail: `${CONFIG_KEY[role]}.model ${echo(model.model)} is not served by Oort Pro (it serves ${allowed.join(', ')})`,
+                fix: `use ${allowed[0]} in ~/.oort/config.json, or set ${PROVIDER_ENV[ROLE_VENDOR[role]]}`,
+            });
+            continue;
+        }
+        checks.push({
+            group: 'keys',
+            name: role,
+            status: 'ok',
+            detail: `Oort Pro (${where(r.source, 'oort')}), through the relay`,
+        });
+    }
+    if (ctx.keychain.kind === 'file') {
+        const file = ctx.keychain.where('oort');
+        const state = inspectCredentialsFile(file);
+        const problem = describeProblem(file, state);
+        if (problem !== undefined) {
+            checks.push({
+                group: 'keys',
+                name: 'credentials',
+                status: 'fail',
+                detail: problem.split(' Fix:')[0] ?? problem,
+                fix: state.state === 'wide' ? `chmod 600 ${file}` : `fix or delete ${file}`,
+            });
+        }
+    }
+    return { checks, relayed };
+}
+/** The Claude Code hooks in the user settings file. */
+function hookChecks(ctx, cmd, home) {
+    const file = settingsFile(false, ctx);
+    const show = tilde(file, home);
+    if (!fs.existsSync(path.join(home, '.claude'))) {
+        return [
+            {
+                group: 'hooks',
+                name: 'claude-code',
+                status: 'info',
+                detail: 'Claude Code not found (~/.claude)',
+            },
+        ];
+    }
+    let status;
+    try {
+        status = hookStatus(file, cmd);
+    }
+    catch (e) {
+        return [
+            {
+                group: 'hooks',
+                name: 'claude-code',
+                status: 'fail',
+                detail: e.message.split('\n')[0] ?? 'unreadable settings',
+                fix: `fix the JSON in ${show}, then oort install claude-code`,
+            },
+        ];
+    }
+    const found = status.events.filter((e) => e.state !== 'missing');
+    if (found.length === 0) {
+        return [
+            {
+                group: 'hooks',
+                name: 'claude-code',
+                status: 'info',
+                detail: `not installed in ${show}`,
+                fix: 'oort install claude-code',
+            },
+        ];
+    }
+    const broken = found.filter((e) => e.command !== undefined && !isExecutable(e.command) && e.command !== 'oort');
+    const missing = status.events.filter((e) => e.state === 'missing').map((e) => e.event);
+    const stale = found.filter((e) => e.state === 'stale');
+    if (broken.length > 0) {
+        return [
+            {
+                group: 'hooks',
+                name: 'claude-code',
+                status: 'fail',
+                detail: `${broken.map((e) => e.event).join(', ')} run ${broken[0]?.command ?? ''}, which is not an executable file`,
+                fix: 'oort install claude-code',
+            },
+        ];
+    }
+    if (missing.length > 0 || stale.length > 0) {
+        return [
+            {
+                group: 'hooks',
+                name: 'claude-code',
+                status: 'warn',
+                detail: missing.length > 0
+                    ? `${missing.join(', ')} missing in ${show}`
+                    : `installed from another path (${stale[0]?.command ?? ''})`,
+                fix: 'oort install claude-code',
+            },
+        ];
+    }
+    return [
+        {
+            group: 'hooks',
+            name: 'claude-code',
+            status: 'ok',
+            detail: `${found.map((e) => e.event).join(', ')} in ${show}`,
+        },
+    ];
+}
+function isExecutable(file) {
+    try {
+        fs.accessSync(file, fs.constants.X_OK);
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** The MCP entry in every host's config. */
+function mcpChecks(ctx, cmd) {
+    const hc = hostContext(ctx);
+    const detected = new Set(detectHosts(hc));
+    return HOSTS.map((host) => {
+        const s = inspectHost(host, hc, cmd);
+        const show = tilde(s.file, hc.home);
+        const base = { group: 'mcp', name: host };
+        switch (s.state) {
+            case 'connected':
+                return { ...base, status: 'ok', detail: `${HOST_LABEL[host]} starts oort mcp (${show})` };
+            case 'outdated':
+                return {
+                    ...base,
+                    status: 'warn',
+                    detail: `Oort's entry in ${show} is from another install path or an older version`,
+                    fix: `oort connect ${host}`,
+                };
+            case 'broken':
+                return {
+                    ...base,
+                    status: 'fail',
+                    detail: `Oort's entry in ${show} runs a command that is not an executable file`,
+                    fix: `oort connect ${host}`,
+                };
+            case 'foreign':
+                return {
+                    ...base,
+                    status: 'info',
+                    detail: `${show} has an "oort" server Oort did not write; left alone`,
+                };
+            case 'invalid':
+                return {
+                    ...base,
+                    status: 'fail',
+                    detail: (s.message ?? `${show} cannot be read`).replace(s.file, show),
+                    fix: `fix ${show} by hand (Oort will not edit it until it parses)`,
+                };
+            case 'absent':
+                return detected.has(host)
+                    ? {
+                        ...base,
+                        status: 'info',
+                        detail: host === 'claude-code'
+                            ? 'MCP server not added (the hooks work without it)'
+                            : `${HOST_LABEL[host]} found, not connected`,
+                        fix: `oort connect ${host}`,
+                    }
+                    : { ...base, status: 'info', detail: `${HOST_LABEL[host]} not found` };
+        }
+    });
+}
+/** The local store: present, private, and readable. It is never created here. */
+async function storeChecks(ctx) {
+    const home = resolveHome(ctx.io.env);
+    const userHome = ctx.io.env['HOME'] ?? '';
+    const show = tilde(home, userHome);
+    const db = path.join(home, 'oort.sqlite');
+    if (!fs.existsSync(db)) {
+        return [
+            {
+                group: 'store',
+                name: 'store',
+                status: 'info',
+                detail: `no store yet in ${show}; the first memory (or oort setup) creates it`,
+            },
+        ];
+    }
+    const checks = [];
+    try {
+        const count = await withWired(ctx, async (w) => {
+            const all = await w.store.list(localGrant(filterFor(w.scope)), { validOnly: false });
+            return all.length;
+        });
+        checks.push({
+            group: 'store',
+            name: 'store',
+            status: 'ok',
+            detail: `${tilde(db, userHome)} opens; ${count} ${count === 1 ? 'memory' : 'memories'} visible from here`,
+        });
+    }
+    catch (e) {
+        checks.push({
+            group: 'store',
+            name: 'store',
+            status: 'fail',
+            detail: `${tilde(db, userHome)} does not open: ${e.message.split('\n')[0] ?? ''}`,
+            fix: `close other oort processes and run oort stats; if it still fails, move ${show} aside`,
+        });
+    }
+    if (process.platform !== 'win32') {
+        const mode = fs.statSync(home).mode & 0o777;
+        if ((mode & 0o077) !== 0) {
+            checks.push({
+                group: 'store',
+                name: 'permissions',
+                status: 'warn',
+                detail: `${show} is mode ${mode.toString(8)}, so other users can read your memories`,
+                fix: `chmod 700 ${show}`,
+            });
+        }
+    }
+    return checks;
+}
+const PROBE_TIMEOUT_MS = 3000;
+/** GET `<relay>/health` with no credentials; true only for 200 `{"ok":true}`. */
+async function probeRelay(url, doFetch) {
+    const abort = new AbortController();
+    const timer = setTimeout(() => abort.abort(), PROBE_TIMEOUT_MS);
+    try {
+        const res = await doFetch(`${url}/health`, { signal: abort.signal, redirect: 'error' });
+        if (!res.ok) {
+            void res.body?.cancel().catch(() => undefined);
+            return false;
+        }
+        const body = await res.json();
+        return body?.ok === true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The relay: its URL, and, when a role goes through it, whether `/health` answers within 3 s. */
+async function relayChecks(ctx, relayed) {
+    const r = relayUrl(ctx.io.env);
+    if ('error' in r) {
+        return [
+            {
+                group: 'relay',
+                name: 'relay',
+                status: relayed ? 'fail' : 'warn',
+                detail: r.error,
+                fix: 'unset OORT_RELAY_URL (or set it to an https URL, or http://localhost for wrangler dev)',
+            },
+        ];
+    }
+    if (!relayed) {
+        return [
+            {
+                group: 'relay',
+                name: 'relay',
+                status: 'info',
+                detail: `not used: every role has its own key or none (${r.url})`,
+            },
+        ];
+    }
+    const up = await probeRelay(r.url, ctx.fetch ?? globalThis.fetch);
+    return [
+        up
+            ? { group: 'relay', name: 'relay', status: 'ok', detail: `${r.url} reachable` }
+            : {
+                group: 'relay',
+                name: 'relay',
+                status: 'warn',
+                detail: `${r.url} unreachable (no healthy answer from /health within 3 s)`,
+                fix: 'check your network and proxy; if it persists, see status at oortcloud.dev, or set your own keys with oort keys set <provider>',
+            },
+    ];
+}
+const GLYPH = {
+    ok: '✓',
+    warn: '!',
+    fail: '✗',
+    info: '·',
+    unknown: '?',
+};
+function paint(ui, status, s) {
+    return status === 'ok'
+        ? ui.green(s)
+        : status === 'warn'
+            ? ui.yellow(s)
+            : status === 'fail'
+                ? ui.red(s)
+                : ui.dim(s);
+}
+/** `oort doctor [--json]`: every check, with a one-line fix per problem. Exits 1 if one fails. */
+export async function doctorCommand(opts, ctx) {
+    const home = ctx.io.env['HOME'] ?? '';
+    let cmd;
+    try {
+        cmd = hookCommandPath(ctx.io.entry);
+    }
+    catch (e) {
+        if (!(e instanceof Refusal))
+            throw e;
+        cmd = undefined; // not the installed bin: entries are judged on their own paths
+    }
+    const keys = await keyChecks(ctx);
+    const checks = [
+        ...keys.checks,
+        ...hookChecks(ctx, cmd, home),
+        ...mcpChecks(ctx, cmd),
+        ...(await storeChecks(ctx)),
+        ...(await relayChecks(ctx, keys.relayed)),
+    ];
+    const ok = !checks.some((c) => c.status === 'fail');
+    if (opts.json === true) {
+        ctx.io.out(`${JSON.stringify({ ok, checks }, null, 2)}\n`);
+        return ok ? 0 : 1;
+    }
+    const ui = uiFor(ctx.io);
+    const problems = checks.filter((c) => c.status === 'warn' || c.status === 'fail').length;
+    ctx.io.out(ui.header('doctor', problems === 0 ? 'no problems' : `${problems} to fix`));
+    for (const group of ['keys', 'hooks', 'mcp', 'store', 'relay']) {
+        const rows = checks.filter((c) => c.group === group);
+        ctx.io.out(`${ui.bold(group)}\n`);
+        ctx.io.out(ui.kv(rows.flatMap((c) => [
+            [`${paint(ui, c.status, GLYPH[c.status])} ${c.name}`, c.detail],
+            ...(c.fix !== undefined
+                ? [
+                    [
+                        '',
+                        ui.dim(`${c.status === 'warn' || c.status === 'fail' ? 'fix' : 'try'}: ${c.fix}`),
+                    ],
+                ]
+                : []),
+        ]), { indent: 2 }));
+    }
+    return ok ? 0 : 1;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/commands/explain.d.ts

@@ -0,0 +1,5 @@
+import { type Ctx } from '../util.js';
+/** `oort explain "<query>" [--json]`: recall, with each stage's rank and score per memory. */
+export declare function explainCommand(query: string, opts: {
+    json?: boolean;
+}, ctx: Ctx): Promise<number>;

package/dist/commands/explain.js

@@ -0,0 +1,67 @@
+import { uiFor } from '../ui.js';
+import { age, clip, degradedHint, fixed, scopeLabel, short, withWired } from '../util.js';
+import { runRecall } from './recall.js';
+/** `oort explain "<query>" [--json]`: recall, with each stage's rank and score per memory. */
+export async function explainCommand(query, opts, ctx) {
+    return withWired(ctx, async (w) => {
+        const now = new Date();
+        const result = await runRecall(w, query, undefined, now);
+        degradedHint(ctx.io, w, result.degraded);
+        if (opts.json === true) {
+            const memories = result.memories.map((m, i) => ({
+                rank: i + 1,
+                id: m.id,
+                type: m.type,
+                tier: m.tier,
+                validFrom: m.validFrom,
+                text: m.text,
+                explanation: m.explanation,
+            }));
+            const out = {
+                memories,
+                timings: result.timings,
+                ...(result.degraded !== undefined && { degraded: result.degraded }),
+            };
+            ctx.io.out(`${JSON.stringify(out, null, 2)}\n`);
+            return 0;
+        }
+        const ui = uiFor(ctx.io);
+        const rows = result.memories.map((m, i) => {
+            const e = m.explanation;
+            return [
+                String(i + 1),
+                short(m.id),
+                m.type,
+                ui.tier(m.tier),
+                age(m.validFrom, now),
+                e.lexicalRank === undefined ? '-' : String(e.lexicalRank),
+                e.denseRank === undefined ? '-' : String(e.denseRank),
+                fixed(e.rrf, 4),
+                fixed(e.fused, 4),
+                fixed(e.reranked, 3),
+                fixed(e.activation),
+                e.hydrated ? 'yes' : 'no',
+                clip(m.text, 80),
+            ];
+        });
+        const t = result.timings;
+        ctx.io.out(ui.header('explain', `${result.memories.length} memories in ${fixed(t['totalMs'], 1)} ms`, scopeLabel(w), ...(result.degraded !== undefined ? [`degraded: ${result.degraded.join(', ')}`] : [])));
+        ctx.io.out(ui.table([
+            'rank',
+            'id',
+            'type',
+            'tier',
+            'age',
+            'lexical',
+            'dense',
+            'rrf',
+            'fused',
+            'reranked',
+            'activation',
+            'hydrated',
+            'text',
+        ], rows));
+        return 0;
+    });
+}
+//# sourceMappingURL=explain.js.map

package/dist/commands/export.d.ts

@@ -0,0 +1,19 @@
+import { type Scope } from '@oortmem/core';
+import { type Ctx } from '../util.js';
+/** Version of the export format documented in docs/export-format.md. */
+export declare const EXPORT_VERSION = 1;
+export interface ExportManifest {
+    oort: 'export';
+    version: typeof EXPORT_VERSION;
+    exportedAt: string;
+    memories: number;
+    scopes: Scope[];
+}
+/**
+ * `oort export [--out <file>]`: the v1 export format, a manifest line and one
+ * JSON line per memory (every tier and validity state) visible from the cwd.
+ */
+export declare function exportCommand(opts: {
+    out?: string;
+    force?: boolean;
+}, ctx: Ctx): Promise<number>;

package/dist/commands/export.js

@@ -0,0 +1,69 @@
+import * as path from 'node:path';
+import { filterFor } from '@oortmem/claude-code';
+import { localGrant } from '@oortmem/core';
+import { shapeLinks, toJson, withWired, writeOwnerOnly } from '../util.js';
+/** Version of the export format documented in docs/export-format.md. */
+export const EXPORT_VERSION = 1;
+/** A cold memory's main record has only its stub indexed; the cold copy holds the full text and embedding. */
+async function decoded(m, store, grant, ctx) {
+    if (m.tier !== 'cold')
+        return m;
+    let blob;
+    try {
+        blob = await store.coldGet(grant, m.id);
+    }
+    catch (e) {
+        // One unreadable blob must not block a backup: export what the main record holds.
+        ctx.io.err(`oort: cold copy of ${m.id} is unreadable (${e.name}); exported its stub only.\n`);
+        return m;
+    }
+    if (blob === null)
+        return m;
+    const { embedding: _none, ...live } = m;
+    return {
+        ...live,
+        text: blob.text,
+        stub: blob.stub,
+        entities: blob.entities,
+        ...(blob.embedding !== undefined && { embedding: blob.embedding }),
+    };
+}
+const scopeKey = (s) => JSON.stringify(Object.entries(s).sort());
+/**
+ * `oort export [--out <file>]`: the v1 export format, a manifest line and one
+ * JSON line per memory (every tier and validity state) visible from the cwd.
+ */
+export async function exportCommand(opts, ctx) {
+    return withWired(ctx, async (w) => {
+        const filter = filterFor(w.scope);
+        const grant = localGrant(filter);
+        const listed = await w.store.list(grant, { validOnly: false });
+        // Oldest first, so an importer replays supersede chains in order.
+        listed.sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt) || (a.id < b.id ? -1 : 1));
+        const memories = [];
+        for (const m of listed) {
+            memories.push(await shapeLinks(w.store, filter, await decoded(m, w.store, grant, ctx)));
+        }
+        const scopes = new Map();
+        for (const m of memories)
+            scopes.set(scopeKey(m.scope), m.scope);
+        const manifest = {
+            oort: 'export',
+            version: EXPORT_VERSION,
+            exportedAt: new Date().toISOString(),
+            memories: memories.length,
+            scopes: [...scopes.values()],
+        };
+        const data = [manifest, ...memories.map(toJson)].map((x) => `${JSON.stringify(x)}\n`).join('');
+        if (opts.out === undefined) {
+            ctx.io.out(data);
+        }
+        else {
+            const file = path.resolve(ctx.io.cwd, opts.out);
+            writeOwnerOnly(file, data, opts.force === true);
+            ctx.io.out(`Exported ${memories.length} memories to ${file}\n`);
+        }
+        return 0;
+    });
+}
+//# sourceMappingURL=export.js.map

package/dist/commands/forget.d.ts

@@ -0,0 +1,5 @@
+import { type Ctx } from '../util.js';
+/** `oort forget <id> [--yes]`: deletes a memory everywhere (main record and cold copy). */
+export declare function forgetCommand(id: string, opts: {
+    yes?: boolean;
+}, ctx: Ctx): Promise<number>;

package/dist/commands/forget.js

@@ -0,0 +1,17 @@
+import { filterFor, grantFor } from '@oortmem/claude-code';
+import { clip, confirm, findMemory, short, withWired } from '../util.js';
+/** `oort forget <id> [--yes]`: deletes a memory everywhere (main record and cold copy). */
+export async function forgetCommand(id, opts, ctx) {
+    return withWired(ctx, async (w) => {
+        const m = await findMemory(w.store, filterFor(w.scope), id);
+        const ok = await confirm(ctx.io, `Forget ${short(m.id)} "${clip(m.text, 60)}"?`, opts.yes === true, 'forget it');
+        if (!ok) {
+            ctx.io.out('Kept.\n');
+            return 0;
+        }
+        await w.store.forget(grantFor(w.scope), m.id);
+        ctx.io.out(`Forgot ${m.id}.\n`);
+        return 0;
+    });
+}
+//# sourceMappingURL=forget.js.map

package/dist/commands/hook.d.ts

@@ -0,0 +1,12 @@
+import { type HookEvent } from '@oortmem/claude-code';
+import { type Ctx } from '../util.js';
+export declare const HOOK_COMMAND_EVENTS: readonly HookEvent[];
+/** Stdin is read for at most this long; Claude Code writes it at once and closes it. */
+export declare const HOOK_STDIN_CAP_MS = 1000;
+/**
+ * A hook waits at most this long for the store's write lock (held, say, by a
+ * drain). SQLite's busy wait is synchronous: it freezes the event loop, the
+ * deadline timer included, so it must stay short. The drain keeps the default.
+ */
+export declare const HOOK_BUSY_TIMEOUT_MS = 250;
+export declare function hookCommand(event: string, ctx: Ctx): Promise<void>;