@pinkpixel/memi 0.0.0-stage → 1.0.0

package/dist/cli/commands/memories.js

@@ -0,0 +1,146 @@
+import { formatHits, formatMemories, formatMemory } from "../../core/format.js";
+import { pickScope, resolveProject } from "../../core/project.js";
+import { openRuntime } from "../../core/runtime.js";
+import { MemiError } from "../../core/types.js";
+import { action, confirm, printJson, splitTags, toInt } from "../util.js";
+const SCOPES = ["both", "project", "global", "all"];
+const checkScope = (v) => {
+    if (!SCOPES.includes(v))
+        throw new MemiError(`Scope must be one of: ${SCOPES.join(", ")}`);
+    return v;
+};
+const currentProject = (rt, project) => resolveProject({ project, agent: rt.agent })?.project ?? null;
+export const registerMemories = (program) => {
+    program
+        .command("add <content...>")
+        .description("Save a memory")
+        .option("-c, --category <name>", "category (default: context)")
+        .option("-i, --importance <1-5>", "importance", toInt("Importance"))
+        .option("-t, --tags <a,b>", "comma-separated tags")
+        .option("--pin", "load this at the start of every session")
+        .option("--global", "save globally instead of for this project")
+        .option("-p, --project <name>", "project name (default: git repo or agent name)")
+        .option("--agent <name>", "agent name to record")
+        .action(action(async (content, o) => {
+        const rt = openRuntime();
+        const agent = o.agent ?? rt.agent;
+        const target = pickScope({ scope: o.global ? "global" : undefined, project: o.project, agent });
+        const r = await rt.store.add({
+            content: content.join(" "),
+            ...target,
+            agent,
+            category: o.category,
+            importance: o.importance,
+            tags: splitTags(o.tags),
+            pinned: o.pin,
+        });
+        console.log(`Saved #${r.memory.id} (${target.scope === "global" ? "global" : `project ${target.project}`}, ${r.memory.category}, importance ${r.memory.importance}).`);
+        if (r.similar.length)
+            console.log(`\nSimilar memories already exist:\n\n${formatMemories(r.similar.map((s) => s.memory))}`);
+        if (r.warning)
+            console.error(`\nNote: ${r.warning}`);
+    }));
+    program
+        .command("search <query...>")
+        .description("Search memories by meaning and keyword")
+        .option("--mode <mode>", "hybrid, semantic or text", "hybrid")
+        .option("--scope <scope>", "both, project, global or all", checkScope, "both")
+        .option("-p, --project <name>", "project name")
+        .option("-c, --category <name>")
+        .option("--min-importance <1-5>", "", toInt("Importance"))
+        .option("-n, --limit <n>", "", toInt("Limit"), 10)
+        .option("--json", "print JSON")
+        .action(action(async (query, o) => {
+        const rt = openRuntime();
+        const r = await rt.store.search({
+            query: query.join(" "),
+            mode: o.mode,
+            scope: o.scope,
+            project: currentProject(rt, o.project),
+            category: o.category,
+            minImportance: o.minImportance,
+            limit: o.limit,
+        });
+        if (o.json)
+            return printJson(r);
+        console.log(r.hits.length ? formatHits(r.hits) : "No matching memories.");
+        if (r.note)
+            console.error(`\nNote: ${r.note}`);
+    }));
+    program
+        .command("list")
+        .description("List memories")
+        .option("--scope <scope>", "both, project, global or all", checkScope, "both")
+        .option("-p, --project <name>", "project name")
+        .option("-c, --category <name>")
+        .option("--min-importance <1-5>", "", toInt("Importance"))
+        .option("--pinned", "only pinned memories")
+        .option("--order <order>", "recent, oldest or importance", "recent")
+        .option("-n, --limit <n>", "", toInt("Limit"), 50)
+        .option("--offset <n>", "", toInt("Offset"), 0)
+        .option("--json", "print JSON")
+        .action(action(async (o) => {
+        const rt = openRuntime();
+        const r = rt.store.list({
+            scope: o.scope,
+            project: currentProject(rt, o.project),
+            category: o.category,
+            minImportance: o.minImportance,
+            pinned: o.pinned ? true : undefined,
+            order: o.order,
+            limit: o.limit,
+            offset: o.offset,
+        });
+        if (o.json)
+            return printJson(r);
+        console.log(r.items.length ? `${r.items.length} of ${r.total}\n\n${formatMemories(r.items)}` : "No memories found.");
+    }));
+    program
+        .command("update <id>")
+        .description("Change a memory")
+        .option("--content <text>")
+        .option("-c, --category <name>")
+        .option("-i, --importance <1-5>", "", toInt("Importance"))
+        .option("-t, --tags <a,b>", "replaces existing tags")
+        .option("--pin")
+        .option("--unpin")
+        .option("--global", "move to global")
+        .option("-p, --project <name>", "move to this project")
+        .action(action(async (id, o) => {
+        const rt = openRuntime();
+        const scope = o.global ? "global" : o.project ? "project" : undefined;
+        const r = await rt.store.update(toInt("Id")(id), {
+            content: o.content,
+            category: o.category,
+            importance: o.importance,
+            tags: splitTags(o.tags),
+            pinned: o.pin ? true : o.unpin ? false : undefined,
+            scope,
+            project: o.project,
+        });
+        if (!r)
+            throw new MemiError(`No memory with id ${id}.`);
+        console.log(`Updated.\n\n${formatMemory(r.memory)}`);
+        if (r.warning)
+            console.error(`\nNote: ${r.warning}`);
+    }));
+    program
+        .command("forget <id>")
+        .description("Delete a memory")
+        .option("-y, --yes", "skip the confirmation")
+        .action(action(async (id, o) => {
+        const rt = openRuntime();
+        const memory = rt.store.get(toInt("Id")(id));
+        if (!memory)
+            throw new MemiError(`No memory with id ${id}.`);
+        console.error(formatMemory(memory) + "\n");
+        if (!(await confirm("Delete this memory permanently?", o.yes)))
+            return console.error("Kept.");
+        rt.store.remove(memory.id);
+        console.log(`Deleted #${memory.id}.`);
+    }));
+    program
+        .command("categories")
+        .description("List categories and how many memories each holds")
+        .action(action(() => console.log(openRuntime().store.categories().map((c) => `${c.name} (${c.count})${c.description ? `: ${c.description}` : ""}`).join("\n"))));
+};

package/dist/cli/commands/reindex.js

@@ -0,0 +1,34 @@
+import { openRuntime } from "../../core/runtime.js";
+import { MemiError } from "../../core/types.js";
+import { action, confirm } from "../util.js";
+export const registerReindex = (program) => {
+    program
+        .command("reindex")
+        .description("Rebuild the vector index with the current embedder")
+        .option("--missing", "only embed memories that have no vector yet, nothing is dropped")
+        .option("-y, --yes", "skip the confirmation")
+        .action(action(async (o) => {
+        const { store } = openRuntime();
+        const status = store.status();
+        if (!status.embedder)
+            throw new MemiError("No embedder configured.");
+        const name = `${status.embedder.provider}/${status.embedder.model}`;
+        if (o.missing) {
+            if (status.state.status === "mismatch")
+                throw new MemiError(status.warning ?? "The embedder changed. Run a full reindex.");
+            console.log(`Embedded ${await store.backfill()} memories with ${name}.`);
+            return;
+        }
+        if (status.state.status === "mismatch") {
+            const { provider, model, dimensions } = status.state.stored;
+            console.error(`The embedder changed from ${provider}/${model} (${dimensions} dims) to ${name}.\n`);
+        }
+        console.error(`This drops the vector table and rebuilds it for ${name}, re-embedding all ${status.total} memories.\n` +
+            "The memories themselves are kept. If the embedder is unreachable, nothing is changed.\n");
+        if (!(await confirm("Rebuild the vector index?", o.yes)))
+            return console.error("Nothing changed.");
+        const result = await store.reindex((done, total) => process.stderr.write(`\rEmbedding ${done}/${total}`));
+        process.stderr.write("\n");
+        console.log(`Rebuilt ${result.count} vectors with ${name} (${result.dimensions} dimensions).`);
+    }));
+};

package/dist/cli/commands/serve.js

@@ -0,0 +1,9 @@
+import { openRuntime } from "../../core/runtime.js";
+import { serveStdio } from "../../mcp/server.js";
+import { action } from "../util.js";
+export const registerServe = (program) => {
+    program
+        .command("serve")
+        .description("Run the MCP server over stdio")
+        .action(action(async () => serveStdio(openRuntime())));
+};

package/dist/cli/commands/ui.js

@@ -0,0 +1,26 @@
+import { spawn } from "node:child_process";
+import { openRuntime } from "../../core/runtime.js";
+import { startUi } from "../../ui/server.js";
+import { action, toInt } from "../util.js";
+function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+    spawn(cmd, args, { detached: true, stdio: "ignore" })
+        .on("error", () => console.error(`Could not open a browser. Visit ${url}`))
+        .unref();
+}
+export const registerUi = (program) => {
+    program
+        .command("ui")
+        .description("Run the local memory manager")
+        .option("-p, --port <n>", "port (default: ui.port from config, 4747)", toInt("Port"))
+        .option("--open", "open it in your browser")
+        .action(action(async (o) => {
+        const rt = openRuntime();
+        const ui = await startUi(rt, { port: o.port ?? rt.config.ui.port });
+        console.log(`memi UI running at ${ui.url}\nPress Ctrl+C to stop.`);
+        if (o.open)
+            openBrowser(ui.url);
+        process.once("SIGINT", () => ui.close().then(() => process.exit(0)));
+        process.once("SIGTERM", () => ui.close().then(() => process.exit(0)));
+    }));
+};

package/dist/cli/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { APP_VERSION } from "../lib/app-info.js";
+import { registerConfig } from "./commands/config.js";
+import { registerDoctor } from "./commands/doctor.js";
+import { registerMemories } from "./commands/memories.js";
+import { registerReindex } from "./commands/reindex.js";
+import { registerServe } from "./commands/serve.js";
+import { registerUi } from "./commands/ui.js";
+import { exitOnKnownError } from "./util.js";
+const program = new Command().name("memi").description("Local-first memory for AI agents").version(APP_VERSION);
+for (const register of [registerServe, registerMemories, registerReindex, registerConfig, registerDoctor, registerUi])
+    register(program);
+try {
+    // Option parsers such as --scope and --importance throw while parsing, before any command action runs.
+    await program.parseAsync();
+}
+catch (err) {
+    exitOnKnownError(err);
+}

package/dist/cli/util.js

@@ -0,0 +1,46 @@
+import { createInterface } from "node:readline/promises";
+import { MemiError } from "../core/types.js";
+import { EmbedError } from "../embed/types.js";
+/** Prints expected failures as one clean line and exits 1. Anything else is a real bug and is rethrown. */
+export function exitOnKnownError(err) {
+    const e = err;
+    if (e instanceof MemiError || e instanceof EmbedError || e.name === "ZodError") {
+        console.error(`memi: ${e.message}`);
+        process.exit(1);
+    }
+    throw err;
+}
+/** Wraps a command action so expected failures print one clean line instead of a stack trace. */
+export function action(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (err) {
+            exitOnKnownError(err);
+        }
+    };
+}
+export async function confirm(question, yes) {
+    if (yes)
+        return true;
+    if (!process.stdin.isTTY)
+        throw new MemiError("This needs confirmation and there is no terminal to ask in. Pass --yes to continue.");
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return /^y(es)?$/i.test((await rl.question(`${question} [y/N] `)).trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+export const splitTags = (v) => (v ? v.split(",").map((t) => t.trim()).filter(Boolean) : undefined);
+export function toInt(name) {
+    return (v) => {
+        const n = Number(v);
+        if (!Number.isInteger(n))
+            throw new MemiError(`${name} must be a whole number.`);
+        return n;
+    };
+}
+export const printJson = (v) => console.log(JSON.stringify(v, null, 2));

package/dist/core/config.js

@@ -0,0 +1,89 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+export const ProviderSchema = z.enum(["ollama", "openai"]);
+const ConfigSchema = z.object({
+    embedder: z
+        .object({
+        provider: ProviderSchema.default("ollama"),
+        model: z.string().optional(),
+        baseUrl: z.string().optional(),
+    })
+        .default({ provider: "ollama" }),
+    agent: z.string().optional(),
+    ui: z.object({ port: z.number().int().default(4747) }).default({ port: 4747 }),
+});
+export function memiHome() {
+    return process.env.MEMI_HOME || join(homedir(), ".memi");
+}
+export const dbPath = () => join(memiHome(), "memi.db");
+export const configPath = () => join(memiHome(), "config.json");
+export function loadConfig() {
+    let raw = {};
+    if (existsSync(configPath())) {
+        try {
+            raw = JSON.parse(readFileSync(configPath(), "utf8"));
+        }
+        catch (err) {
+            throw new Error(`Could not read ${configPath()}: ${err.message}`);
+        }
+    }
+    return ConfigSchema.parse(raw);
+}
+export function saveConfig(config) {
+    mkdirSync(memiHome(), { recursive: true });
+    writeFileSync(configPath(), JSON.stringify(config, null, 2) + "\n");
+}
+const DEFAULTS = {
+    ollama: { model: "nomic-embed-text", baseUrl: "http://localhost:11434" },
+    openai: { model: "text-embedding-3-small", baseUrl: "https://api.openai.com/v1" },
+};
+/** Config file first, then env overrides. The OpenAI key only ever comes from the environment. */
+export function resolveEmbedder(config = loadConfig()) {
+    const provider = ProviderSchema.parse(process.env.MEMI_EMBED_PROVIDER ?? config.embedder.provider);
+    const defaults = DEFAULTS[provider];
+    const configured = config.embedder.provider === provider ? config.embedder : undefined;
+    const envBase = provider === "ollama" ? process.env.MEMI_OLLAMA_URL : process.env.OPENAI_BASE_URL;
+    return {
+        provider,
+        model: process.env.MEMI_EMBED_MODEL ?? configured?.model ?? defaults.model,
+        baseUrl: (envBase ?? configured?.baseUrl ?? defaults.baseUrl).replace(/\/+$/, ""),
+        apiKey: provider === "openai" ? process.env.OPENAI_API_KEY : undefined,
+    };
+}
+export function resolveAgent(config = loadConfig()) {
+    return process.env.MEMI_AGENT?.trim() || config.agent?.trim() || null;
+}
+export const CONFIG_KEYS = ["embedder.provider", "embedder.model", "embedder.baseUrl", "agent", "ui.port"];
+/** Returns a copy of the config with one key changed. Switching provider clears the old provider's model and URL. */
+export function setConfigValue(config, key, value) {
+    const next = structuredClone(config);
+    switch (key) {
+        case "embedder.provider": {
+            const provider = ProviderSchema.safeParse(value);
+            if (!provider.success)
+                throw new Error(`embedder.provider must be one of: ${ProviderSchema.options.join(", ")}`);
+            next.embedder = { provider: provider.data };
+            return next;
+        }
+        case "embedder.model":
+            next.embedder.model = value;
+            return next;
+        case "embedder.baseUrl":
+            next.embedder.baseUrl = value;
+            return next;
+        case "agent":
+            next.agent = value;
+            return next;
+        case "ui.port": {
+            const port = Number(value);
+            if (!Number.isInteger(port) || port < 1 || port > 65535)
+                throw new Error("ui.port must be a number from 1 to 65535");
+            next.ui.port = port;
+            return next;
+        }
+        default:
+            throw new Error(`Unknown key "${key}". Keys: ${CONFIG_KEYS.join(", ")}`);
+    }
+}

package/dist/core/db.js

@@ -0,0 +1,21 @@
+import Database from "better-sqlite3";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import * as sqliteVec from "sqlite-vec";
+import { dbPath } from "./config.js";
+import { migrate } from "./schema.js";
+import { BUILTIN_CATEGORIES } from "./types.js";
+export function openDb(path = dbPath()) {
+    if (path !== ":memory:")
+        mkdirSync(dirname(path), { recursive: true });
+    const db = new Database(path);
+    db.pragma("journal_mode = WAL");
+    db.pragma("foreign_keys = ON");
+    db.pragma("busy_timeout = 5000");
+    sqliteVec.load(db);
+    migrate(db);
+    const seed = db.prepare("INSERT OR IGNORE INTO categories(name, description, builtin) VALUES (?, ?, 1)");
+    for (const [name, description] of Object.entries(BUILTIN_CATEGORIES))
+        seed.run(name, description);
+    return db;
+}

package/dist/core/format.js

@@ -0,0 +1,16 @@
+export function formatMemory(m, score) {
+    const where = m.scope === "global" ? "global" : `project ${m.project}`;
+    const meta = [
+        m.category,
+        `importance ${m.importance}`,
+        m.pinned ? "pinned" : null,
+        where,
+        m.tags.length ? `tags ${m.tags.join(", ")}` : null,
+        m.updatedAt.slice(0, 10),
+        m.agent ? `by ${m.agent}` : null,
+        score !== undefined ? `score ${score.toFixed(4)}` : null,
+    ].filter(Boolean);
+    return `#${m.id} | ${meta.join(" | ")}\n${m.content}`;
+}
+export const formatMemories = (list) => list.map((m) => formatMemory(m)).join("\n\n");
+export const formatHits = (hits) => hits.map((h) => formatMemory(h.memory, h.score)).join("\n\n");

package/dist/core/memories.js

@@ -0,0 +1,192 @@
+import { rowToMemory, whereClause } from "./rows.js";
+import { DEFAULT_CATEGORY, MAX_CONTENT_LENGTH, MemiError, } from "./types.js";
+import { search } from "./search.js";
+import { deleteVector, embedMissing, embedderState, ensureVectors, knn, mismatchMessage, putVector, rebuildVectors, scopeKey } from "./vectors.js";
+/** Cosine distance under which a new memory is reported as similar to an existing one. */
+export const SIMILAR_DISTANCE = 0.15;
+const ORDER = {
+    recent: "m.updated_at DESC, m.id DESC",
+    oldest: "m.created_at ASC, m.id ASC",
+    importance: "m.importance DESC, m.updated_at DESC",
+};
+export function normalizeCategory(raw) {
+    const name = raw.trim().toLowerCase().replace(/\s+/g, "-");
+    if (!/^[a-z0-9][a-z0-9_-]{0,31}$/.test(name)) {
+        throw new MemiError(`Invalid category "${raw}". Use up to 32 letters, numbers, dashes or underscores.`);
+    }
+    return name;
+}
+const normalizeTags = (tags = []) => [...new Set(tags.map((t) => t.trim().toLowerCase()).filter(Boolean))].slice(0, 10);
+function checkImportance(n) {
+    if (!Number.isInteger(n) || n < 1 || n > 5)
+        throw new MemiError("Importance must be a whole number from 1 to 5.");
+    return n;
+}
+function checkContent(content) {
+    const text = content.trim();
+    if (!text)
+        throw new MemiError("Memory content cannot be empty.");
+    if (text.length > MAX_CONTENT_LENGTH)
+        throw new MemiError(`Memory content is too long (max ${MAX_CONTENT_LENGTH} characters).`);
+    return text;
+}
+export class MemoryStore {
+    db;
+    embedder;
+    constructor(db, embedder = null) {
+        this.db = db;
+        this.embedder = embedder;
+    }
+    ensureCategory(name) {
+        this.db.prepare("INSERT OR IGNORE INTO categories(name, description, builtin) VALUES (?, '', 0)").run(name);
+    }
+    resolveScope(scope, project) {
+        const s = scope ?? (project ? "project" : "global");
+        if (s === "project" && !project)
+            throw new MemiError("A project memory needs a project name.");
+        return { scope: s, project: s === "project" ? project : null };
+    }
+    get(id) {
+        const row = this.db.prepare("SELECT * FROM memories WHERE id = ?").get(id);
+        return row ? rowToMemory(row) : null;
+    }
+    getMany(ids) {
+        if (!ids.length)
+            return [];
+        const rows = this.db.prepare(`SELECT * FROM memories WHERE id IN (${ids.map(() => "?").join(",")})`).all(...ids);
+        return rows.map(rowToMemory);
+    }
+    /** Embeds text if possible. Never throws: a memory is saved even when the embedder is down. */
+    async tryEmbed(text) {
+        if (!this.embedder)
+            return { vec: null, warning: "No embedder configured, saved for text search only." };
+        try {
+            const state = await ensureVectors(this.db, this.embedder);
+            if (state.status === "mismatch")
+                return { vec: null, warning: mismatchMessage(state, this.embedder) };
+            const [vec] = await this.embedder.embed([text], "document");
+            return { vec: vec ?? null };
+        }
+        catch (err) {
+            return { vec: null, warning: `Saved without a vector (${err.message}). Run \`memi reindex --missing\` later to backfill.` };
+        }
+    }
+    async add(input) {
+        const content = checkContent(input.content);
+        const { scope, project } = this.resolveScope(input.scope, input.project);
+        const category = normalizeCategory(input.category ?? DEFAULT_CATEGORY);
+        const importance = checkImportance(input.importance ?? 3);
+        const now = new Date().toISOString();
+        const { vec, warning } = await this.tryEmbed(content);
+        const key = scopeKey(scope, project);
+        const similarHits = vec ? knn(this.db, vec, 5, key).filter((n) => n.distance <= SIMILAR_DISTANCE) : [];
+        const id = this.db.transaction(() => {
+            this.ensureCategory(category);
+            const res = this.db
+                .prepare(`INSERT INTO memories(scope, project, agent, category, content, tags, importance, pinned, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(scope, project, input.agent ?? null, category, content, JSON.stringify(normalizeTags(input.tags)), importance, input.pinned ? 1 : 0, now, now);
+            const newId = Number(res.lastInsertRowid);
+            if (vec)
+                putVector(this.db, newId, key, vec);
+            return newId;
+        })();
+        const byId = new Map(this.getMany(similarHits.map((h) => h.id)).map((m) => [m.id, m]));
+        return {
+            memory: this.get(id),
+            similar: similarHits.flatMap((h) => (byId.has(h.id) ? [{ memory: byId.get(h.id), distance: h.distance }] : [])),
+            embedded: vec !== null,
+            warning,
+        };
+    }
+    async update(id, patch) {
+        const current = this.get(id);
+        if (!current)
+            return null;
+        const content = patch.content !== undefined ? checkContent(patch.content) : current.content;
+        const target = this.resolveScope(patch.scope ?? current.scope, patch.project !== undefined ? patch.project : current.project);
+        const category = patch.category !== undefined ? normalizeCategory(patch.category) : current.category;
+        const importance = patch.importance !== undefined ? checkImportance(patch.importance) : current.importance;
+        const tags = patch.tags !== undefined ? normalizeTags(patch.tags) : current.tags;
+        const pinned = patch.pinned ?? current.pinned;
+        const needsVector = content !== current.content || target.scope !== current.scope || target.project !== current.project;
+        const embedded = needsVector ? await this.tryEmbed(content) : { vec: null, warning: undefined };
+        this.db.transaction(() => {
+            this.ensureCategory(category);
+            this.db
+                .prepare("UPDATE memories SET scope=?, project=?, category=?, content=?, tags=?, importance=?, pinned=?, updated_at=? WHERE id=?")
+                .run(target.scope, target.project, category, content, JSON.stringify(tags), importance, pinned ? 1 : 0, new Date().toISOString(), id);
+            if (needsVector) {
+                deleteVector(this.db, id);
+                if (embedded.vec)
+                    putVector(this.db, id, scopeKey(target.scope, target.project), embedded.vec);
+            }
+        })();
+        return { memory: this.get(id), warning: embedded.warning };
+    }
+    remove(id) {
+        return this.db.transaction(() => {
+            deleteVector(this.db, id);
+            return this.db.prepare("DELETE FROM memories WHERE id = ?").run(id).changes > 0;
+        })();
+    }
+    list(opts = {}) {
+        const { sql, params } = whereClause(opts);
+        const total = this.db.prepare(`SELECT COUNT(*) AS n FROM memories m WHERE ${sql}`).get(params).n;
+        const rows = this.db
+            .prepare(`SELECT m.* FROM memories m WHERE ${sql} ORDER BY ${ORDER[opts.order ?? "recent"]} LIMIT @limit OFFSET @offset`)
+            .all({ ...params, limit: Math.min(opts.limit ?? 50, 200), offset: opts.offset ?? 0 });
+        return { items: rows.map(rowToMemory), total };
+    }
+    search(opts) {
+        return search(this.db, this.embedder, opts);
+    }
+    /** Pinned and high-importance memories: what an agent should load at the start of a session. */
+    context(opts = {}) {
+        const { sql, params } = whereClause({ scope: "both", project: opts.project });
+        const rows = this.db
+            .prepare(`SELECT m.* FROM memories m WHERE ${sql} AND (m.pinned = 1 OR m.importance >= 4)
+         ORDER BY m.pinned DESC, m.importance DESC, m.updated_at DESC LIMIT @limit`)
+            .all({ ...params, limit: opts.limit ?? 20 });
+        return rows.map(rowToMemory);
+    }
+    categories() {
+        const rows = this.db
+            .prepare(`SELECT c.name, c.description, c.builtin, COUNT(m.id) AS count
+         FROM categories c LEFT JOIN memories m ON m.category = c.name
+         GROUP BY c.name ORDER BY c.builtin DESC, c.name`)
+            .all();
+        return rows.map((r) => ({ ...r, builtin: r.builtin === 1 }));
+    }
+    projects() {
+        return this.db
+            .prepare("SELECT project, COUNT(*) AS count FROM memories WHERE scope = 'project' GROUP BY project ORDER BY project")
+            .all();
+    }
+    everything() {
+        return this.db.prepare("SELECT * FROM memories ORDER BY id").all().map(rowToMemory);
+    }
+    /** Drops and rebuilds the vector table with the current embedder. Memories are kept. */
+    async reindex(onProgress) {
+        if (!this.embedder)
+            throw new MemiError("No embedder configured.");
+        return rebuildVectors(this.db, this.embedder, this.everything(), onProgress);
+    }
+    async backfill() {
+        if (!this.embedder)
+            throw new MemiError("No embedder configured.");
+        return embedMissing(this.db, this.embedder, this.everything());
+    }
+    status() {
+        const total = this.db.prepare("SELECT COUNT(*) AS n FROM memories").get().n;
+        const state = this.embedder ? embedderState(this.db, this.embedder) : { status: "uninitialized" };
+        const vectors = state.status === "uninitialized" ? 0 : this.db.prepare("SELECT COUNT(*) AS n FROM memory_vec").get().n;
+        return {
+            total,
+            vectors,
+            embedder: this.embedder ? { provider: this.embedder.provider, model: this.embedder.model } : null,
+            state,
+            warning: this.embedder && state.status === "mismatch" ? mismatchMessage(state, this.embedder) : undefined,
+        };
+    }
+}

package/dist/core/project.js

@@ -0,0 +1,53 @@
+import { existsSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { MemiError } from "./types.js";
+export function findGitRoot(start) {
+    let dir = resolve(start);
+    for (;;) {
+        if (existsSync(join(dir, ".git")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Project id order: explicit argument, MEMI_PROJECT, git root folder name, then the agent name.
+ * Returns null when nothing identifies a project, so callers can fall back to global or ask.
+ */
+export function resolveProject(opts) {
+    const explicit = opts.project?.trim();
+    if (explicit)
+        return { project: explicit, source: "explicit" };
+    const env = process.env.MEMI_PROJECT?.trim();
+    if (env)
+        return { project: env, source: "env" };
+    const root = findGitRoot(opts.cwd ?? process.cwd());
+    if (root)
+        return { project: basename(root), source: "git" };
+    const agent = opts.agent?.trim();
+    if (agent)
+        return { project: `agent:${agent}`, source: "agent" };
+    return null;
+}
+export function requireProject(opts) {
+    const info = resolveProject(opts);
+    if (!info) {
+        throw new MemiError("Could not work out which project this is. There is no git repo here and no agent name set. " +
+            "Pass a project name, set MEMI_PROJECT, or set an agent name with MEMI_AGENT.");
+    }
+    return info;
+}
+/**
+ * Where a new memory goes. With no explicit scope it lands in the current project when one can be
+ * worked out, and in global otherwise.
+ */
+export function pickScope(opts) {
+    if (opts.scope === "global")
+        return { scope: "global", project: null };
+    if (opts.scope === "project")
+        return { scope: "project", project: requireProject(opts).project };
+    const info = resolveProject(opts);
+    return info ? { scope: "project", project: info.project } : { scope: "global", project: null };
+}