@pinkpixel/memi 0.0.0-stage → 1.0.0

package/dist/core/rows.js

@@ -0,0 +1,38 @@
+export const rowToMemory = (r) => ({
+    id: r.id,
+    scope: r.scope,
+    project: r.project,
+    agent: r.agent,
+    category: r.category,
+    content: r.content,
+    tags: JSON.parse(r.tags),
+    importance: r.importance,
+    pinned: r.pinned === 1,
+    createdAt: r.created_at,
+    updatedAt: r.updated_at,
+});
+/** Builds a WHERE fragment for the memories table, aliased as `alias`. */
+export function whereClause(f, alias = "m") {
+    const a = alias;
+    const parts = [];
+    const params = {};
+    const scope = f.scope ?? "both";
+    const project = f.project ?? null;
+    if (scope === "global")
+        parts.push(`${a}.scope = 'global'`);
+    else if (scope === "project")
+        parts.push(project ? `${a}.scope = 'project' AND ${a}.project = @project` : "0");
+    else if (scope === "both")
+        parts.push(project ? `(${a}.scope = 'global' OR (${a}.scope = 'project' AND ${a}.project = @project))` : `${a}.scope = 'global'`);
+    if (project && scope !== "global" && scope !== "all")
+        params.project = project;
+    if (f.category)
+        (parts.push(`${a}.category = @category`), (params.category = f.category));
+    if (f.minImportance)
+        (parts.push(`${a}.importance >= @minImportance`), (params.minImportance = f.minImportance));
+    if (f.pinned !== undefined)
+        parts.push(`${a}.pinned = ${f.pinned ? 1 : 0}`);
+    if (f.agent)
+        (parts.push(`${a}.agent = @agent`), (params.agent = f.agent));
+    return { sql: parts.length ? parts.join(" AND ") : "1", params };
+}

package/dist/core/runtime.js

@@ -0,0 +1,10 @@
+import { loadConfig, resolveAgent, resolveEmbedder } from "./config.js";
+import { openDb } from "./db.js";
+import { MemoryStore } from "./memories.js";
+import { createEmbedder } from "../embed/index.js";
+/** Opens the database at its default location with whichever embedder the config and environment select. */
+export function openRuntime() {
+    const config = loadConfig();
+    const store = new MemoryStore(openDb(), createEmbedder(resolveEmbedder(config)));
+    return { store, config, agent: resolveAgent(config) };
+}

package/dist/core/schema.js

@@ -0,0 +1,60 @@
+const V1 = `
+CREATE TABLE memories (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  scope       TEXT NOT NULL CHECK (scope IN ('global','project')),
+  project     TEXT,
+  agent       TEXT,
+  category    TEXT NOT NULL,
+  content     TEXT NOT NULL,
+  tags        TEXT NOT NULL DEFAULT '[]',
+  importance  INTEGER NOT NULL DEFAULT 3 CHECK (importance BETWEEN 1 AND 5),
+  pinned      INTEGER NOT NULL DEFAULT 0,
+  created_at  TEXT NOT NULL,
+  updated_at  TEXT NOT NULL,
+  CHECK ((scope = 'global' AND project IS NULL) OR (scope = 'project' AND project IS NOT NULL))
+);
+CREATE INDEX idx_memories_scope ON memories(scope, project);
+CREATE INDEX idx_memories_category ON memories(category);
+
+CREATE TABLE categories (
+  name        TEXT PRIMARY KEY,
+  description TEXT NOT NULL DEFAULT '',
+  builtin     INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE VIRTUAL TABLE memories_fts USING fts5(
+  content, tags, category,
+  content='memories', content_rowid='id',
+  tokenize='porter unicode61'
+);
+
+CREATE TRIGGER memories_ai AFTER INSERT ON memories BEGIN
+  INSERT INTO memories_fts(rowid, content, tags, category)
+  VALUES (new.id, new.content, new.tags, new.category);
+END;
+CREATE TRIGGER memories_ad AFTER DELETE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, content, tags, category)
+  VALUES ('delete', old.id, old.content, old.tags, old.category);
+END;
+CREATE TRIGGER memories_au AFTER UPDATE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, content, tags, category)
+  VALUES ('delete', old.id, old.content, old.tags, old.category);
+  INSERT INTO memories_fts(rowid, content, tags, category)
+  VALUES (new.id, new.content, new.tags, new.category);
+END;
+`;
+const MIGRATIONS = [V1];
+export function migrate(db) {
+    const current = db.pragma("user_version", { simple: true });
+    for (let v = current; v < MIGRATIONS.length; v++) {
+        db.transaction(() => {
+            db.exec(MIGRATIONS[v]);
+            db.pragma(`user_version = ${v + 1}`);
+        })();
+    }
+}

package/dist/core/search.js

@@ -0,0 +1,86 @@
+import { rowToMemory, whereClause } from "./rows.js";
+import { embedderState, knn, mismatchMessage, scopeKey } from "./vectors.js";
+const RRF_K = 60;
+/**
+ * How strongly importance and recency nudge the fused relevance score. Top RRF scores are only about
+ * 1.6% apart per rank, so these have to stay small or they outrank relevance.
+ */
+export const RANKING = { importance: 0.025, recency: 0.025, recencyHalfLifeDays: 60 };
+function boost(m) {
+    const ageDays = Math.max((Date.now() - Date.parse(m.updatedAt)) / 86_400_000, 0);
+    return (1 + RANKING.importance * (m.importance - 3)) * (1 + RANKING.recency * Math.pow(0.5, ageDays / RANKING.recencyHalfLifeDays));
+}
+/** Turns free text into a safe FTS5 query: quoted tokens joined with OR. */
+export function toFtsQuery(text) {
+    const tokens = text.match(/[\p{L}\p{N}]+/gu);
+    return tokens?.length ? tokens.map((t) => `"${t}"`).join(" OR ") : null;
+}
+function textSearch(db, query, f, n) {
+    const fts = toFtsQuery(query);
+    if (!fts)
+        return [];
+    const { sql, params } = whereClause(f);
+    const rows = db
+        .prepare(`SELECT m.* FROM memories_fts JOIN memories m ON m.id = memories_fts.rowid
+       WHERE memories_fts MATCH @fts AND ${sql} ORDER BY bm25(memories_fts) LIMIT @n`)
+        .all({ ...params, fts, n });
+    return rows.map(rowToMemory);
+}
+async function semanticSearch(db, embedder, query, f, n) {
+    const [vec] = await embedder.embed([query], "query");
+    if (!vec)
+        return [];
+    const scope = f.scope ?? "both";
+    const keys = scope === "all" ? [null] : scope === "global" ? ["global"] : scope === "project" ? (f.project ? [scopeKey("project", f.project)] : []) : f.project ? ["global", scopeKey("project", f.project)] : ["global"];
+    const ids = keys.flatMap((k) => knn(db, vec, n, k)).sort((a, b) => a.distance - b.distance).map((r) => Number(r.id));
+    if (!ids.length)
+        return [];
+    const { sql, params } = whereClause({ ...f, scope: "all" });
+    const rows = db
+        .prepare(`SELECT m.* FROM memories m WHERE m.id IN (SELECT value FROM json_each(@ids)) AND ${sql}`)
+        .all({ ...params, ids: JSON.stringify(ids) });
+    const byId = new Map(rows.map((r) => [r.id, rowToMemory(r)]));
+    return ids.flatMap((id) => (byId.has(id) ? [byId.get(id)] : []));
+}
+export async function search(db, embedder, opts) {
+    const limit = Math.min(opts.limit ?? 10, 50);
+    const pool = Math.max(limit * 5, 50);
+    const wanted = opts.mode ?? "hybrid";
+    let mode = wanted;
+    let note;
+    if (wanted !== "text") {
+        const state = embedder ? embedderState(db, embedder) : null;
+        if (!embedder)
+            (mode = "text"), (note = "No embedder configured, used text search.");
+        else if (state?.status === "uninitialized")
+            (mode = "text"), (note = "No vectors yet, used text search.");
+        else if (state?.status === "mismatch")
+            (mode = "text"), (note = mismatchMessage(state, embedder));
+    }
+    let text = [];
+    let semantic = [];
+    if (mode !== "semantic")
+        text = textSearch(db, opts.query, opts, pool);
+    if (mode !== "text" && embedder) {
+        try {
+            semantic = await semanticSearch(db, embedder, opts.query, opts, pool);
+        }
+        catch (err) {
+            if (mode === "semantic")
+                throw err;
+            mode = "text";
+            note = `Semantic search failed (${err.message}), used text search.`;
+        }
+    }
+    const fused = new Map();
+    const add = (list, source) => list.forEach((memory, rank) => {
+        const hit = fused.get(memory.id) ?? { memory, score: 0, sources: [] };
+        hit.score += 1 / (RRF_K + rank + 1);
+        hit.sources.push(source);
+        fused.set(memory.id, hit);
+    });
+    add(text, "text");
+    add(semantic, "semantic");
+    const hits = [...fused.values()].map((h) => ({ ...h, score: h.score * boost(h.memory) })).sort((a, b) => b.score - a.score).slice(0, limit);
+    return { hits, modeUsed: mode, note };
+}

package/dist/core/types.js

@@ -0,0 +1,12 @@
+export const BUILTIN_CATEGORIES = {
+    decision: "A choice that was made, with the reasoning",
+    preference: "How the user likes things done",
+    fact: "A durable fact about the project, system, or user",
+    error: "Something that failed and what to avoid next time",
+    todo: "Follow-up work that should not be forgotten",
+    context: "Background that helps future sessions",
+};
+export const DEFAULT_CATEGORY = "context";
+export const MAX_CONTENT_LENGTH = 8000;
+export class MemiError extends Error {
+}

package/dist/core/vectors.js

@@ -0,0 +1,102 @@
+export const scopeKey = (scope, project) => (scope === "global" ? "global" : `p:${project}`);
+const asBlob = (v) => Buffer.from(new Float32Array(v).buffer);
+export function getMeta(db, key) {
+    const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(key);
+    return row?.value ?? null;
+}
+const setMeta = (db, key, value) => db.prepare("INSERT INTO meta(key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(key, value);
+export function embedderState(db, embedder) {
+    const provider = getMeta(db, "embedder_provider");
+    const model = getMeta(db, "embedder_model");
+    const dim = Number(getMeta(db, "embedder_dimensions"));
+    if (!provider || !model || !dim)
+        return { status: "uninitialized" };
+    const stored = { provider, model, dimensions: dim };
+    return provider === embedder.provider && model === embedder.model ? { status: "ok", stored } : { status: "mismatch", stored };
+}
+export const mismatchMessage = (state, embedder) => `The embedder changed from ${state.stored.provider}/${state.stored.model} (${state.stored.dimensions} dims) to ${embedder.provider}/${embedder.model}. ` +
+    `Vectors from different models are not compatible and can have different dimensions, so semantic search is off until you run \`memi reindex\`. ` +
+    `Reindexing drops the vector table, rebuilds it for the new model, and re-embeds your saved memories. The memories themselves are kept.`;
+function createVecTable(db, dimensions) {
+    db.exec(`CREATE VIRTUAL TABLE memory_vec USING vec0(
+       memory_id INTEGER PRIMARY KEY,
+       scope_key TEXT PARTITION KEY,
+       embedding FLOAT[${Math.trunc(dimensions)}] distance_metric=cosine
+     )`);
+}
+async function probeDimensions(embedder) {
+    const [vec] = await embedder.embed(["memi dimension probe"], "document");
+    if (!vec?.length)
+        throw new Error("The embedder returned an empty vector.");
+    return vec.length;
+}
+/** Creates the vector table on first use. Returns false when the stored embedder does not match. */
+export async function ensureVectors(db, embedder) {
+    const state = embedderState(db, embedder);
+    if (state.status !== "uninitialized")
+        return state;
+    const dimensions = await probeDimensions(embedder);
+    db.transaction(() => {
+        db.exec("DROP TABLE IF EXISTS memory_vec");
+        createVecTable(db, dimensions);
+        setMeta(db, "embedder_provider", embedder.provider);
+        setMeta(db, "embedder_model", embedder.model);
+        setMeta(db, "embedder_dimensions", String(dimensions));
+    })();
+    return embedderState(db, embedder);
+}
+export function putVector(db, id, key, vec) {
+    db.prepare("DELETE FROM memory_vec WHERE memory_id = ?").run(BigInt(id));
+    db.prepare("INSERT INTO memory_vec(memory_id, scope_key, embedding) VALUES (?, ?, ?)").run(BigInt(id), key, asBlob(vec));
+}
+export function deleteVector(db, id) {
+    const exists = db.prepare("SELECT 1 FROM sqlite_master WHERE name = 'memory_vec'").get();
+    if (exists)
+        db.prepare("DELETE FROM memory_vec WHERE memory_id = ?").run(BigInt(id));
+}
+/** Cosine distance KNN. Pass a scope key to search one partition, or null to search all of them. */
+export function knn(db, query, k, key) {
+    const sql = key
+        ? "SELECT memory_id AS id, distance FROM memory_vec WHERE embedding MATCH ? AND k = ? AND scope_key = ? ORDER BY distance"
+        : "SELECT memory_id AS id, distance FROM memory_vec WHERE embedding MATCH ? AND k = ? ORDER BY distance";
+    const args = key ? [asBlob(query), k, key] : [asBlob(query), k];
+    return db.prepare(sql).all(...args);
+}
+const BATCH = 32;
+async function embedAll(embedder, memories, onProgress) {
+    const out = [];
+    for (let i = 0; i < memories.length; i += BATCH) {
+        const slice = memories.slice(i, i + BATCH);
+        out.push(...(await embedder.embed(slice.map((m) => m.content), "document")));
+        onProgress?.(Math.min(i + BATCH, memories.length), memories.length);
+    }
+    return out;
+}
+/**
+ * Drops the vector table, re-embeds every saved memory with the current embedder, and records the new
+ * provider, model and dimensions. All embedding happens first, so a failed run changes nothing.
+ */
+export async function rebuildVectors(db, embedder, all, onProgress) {
+    const dimensions = await probeDimensions(embedder);
+    const vectors = await embedAll(embedder, all, onProgress);
+    db.transaction(() => {
+        db.exec("DROP TABLE IF EXISTS memory_vec");
+        createVecTable(db, dimensions);
+        all.forEach((m, i) => putVector(db, m.id, scopeKey(m.scope, m.project), vectors[i]));
+        setMeta(db, "embedder_provider", embedder.provider);
+        setMeta(db, "embedder_model", embedder.model);
+        setMeta(db, "embedder_dimensions", String(dimensions));
+    })();
+    return { count: all.length, dimensions };
+}
+/** Embeds memories that were saved while the embedder was unavailable. */
+export async function embedMissing(db, embedder, all) {
+    const state = await ensureVectors(db, embedder);
+    if (state.status !== "ok")
+        return 0;
+    const have = new Set(db.prepare("SELECT memory_id AS id FROM memory_vec").all().map((r) => Number(r.id)));
+    const missing = all.filter((m) => !have.has(m.id));
+    const vectors = await embedAll(embedder, missing);
+    db.transaction(() => missing.forEach((m, i) => putVector(db, m.id, scopeKey(m.scope, m.project), vectors[i])))();
+    return missing.length;
+}

package/dist/embed/http.js

@@ -0,0 +1,20 @@
+import { EmbedError } from "./types.js";
+export async function postJson(url, body, headers, hint) {
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...headers },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(120_000),
+        });
+    }
+    catch (err) {
+        throw new EmbedError(`Could not reach ${url}: ${err.message}. ${hint}`);
+    }
+    if (!res.ok) {
+        const text = (await res.text().catch(() => "")).slice(0, 300);
+        throw new EmbedError(`${url} returned ${res.status}: ${text}. ${hint}`);
+    }
+    return (await res.json());
+}

package/dist/embed/index.js

@@ -0,0 +1,9 @@
+import { resolveEmbedder } from "../core/config.js";
+import { OllamaEmbedder } from "./ollama.js";
+import { OpenAIEmbedder } from "./openai.js";
+export { EmbedError } from "./types.js";
+export function createEmbedder(resolved = resolveEmbedder()) {
+    return resolved.provider === "openai"
+        ? new OpenAIEmbedder(resolved.model, resolved.baseUrl, resolved.apiKey)
+        : new OllamaEmbedder(resolved.model, resolved.baseUrl);
+}

package/dist/embed/ollama.js

@@ -0,0 +1,24 @@
+import { postJson } from "./http.js";
+import { EmbedError } from "./types.js";
+// nomic-embed-text expects a task prefix on its inputs.
+const PREFIXES = {
+    "nomic-embed-text": { document: "search_document: ", query: "search_query: " },
+};
+export class OllamaEmbedder {
+    model;
+    baseUrl;
+    provider = "ollama";
+    constructor(model, baseUrl) {
+        this.model = model;
+        this.baseUrl = baseUrl;
+    }
+    async embed(texts, kind) {
+        const base = this.model.replace(/:latest$/, "");
+        const prefix = PREFIXES[base]?.[kind] ?? "";
+        const data = await postJson(`${this.baseUrl}/api/embed`, { model: this.model, input: texts.map((t) => prefix + t) }, {}, `Is Ollama running? You may need: ollama pull ${this.model}`);
+        if (!data.embeddings || data.embeddings.length !== texts.length) {
+            throw new EmbedError(`Ollama returned an unexpected response for model ${this.model}.`);
+        }
+        return data.embeddings;
+    }
+}

package/dist/embed/openai.js

@@ -0,0 +1,22 @@
+import { postJson } from "./http.js";
+import { EmbedError } from "./types.js";
+export class OpenAIEmbedder {
+    model;
+    baseUrl;
+    apiKey;
+    provider = "openai";
+    constructor(model, baseUrl, apiKey) {
+        this.model = model;
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+    }
+    async embed(texts) {
+        if (!this.apiKey)
+            throw new EmbedError("OPENAI_API_KEY is not set. Export it in the environment that runs memi.");
+        const data = await postJson(`${this.baseUrl}/embeddings`, { model: this.model, input: texts, encoding_format: "float" }, { authorization: `Bearer ${this.apiKey}` }, "Check OPENAI_API_KEY and the model name.");
+        if (!data.data || data.data.length !== texts.length) {
+            throw new EmbedError(`OpenAI returned an unexpected response for model ${this.model}.`);
+        }
+        return [...data.data].sort((a, b) => a.index - b.index).map((d) => d.embedding);
+    }
+}

package/dist/embed/types.js

@@ -0,0 +1,2 @@
+export class EmbedError extends Error {
+}

package/dist/lib/app-info.js

@@ -0,0 +1,5 @@
+import { createRequire } from "node:module";
+// package.json is the single source of truth for the version. This path works from both src/ and dist/.
+const pkg = createRequire(import.meta.url)("../../package.json");
+export const APP_NAME = pkg.name;
+export const APP_VERSION = pkg.version;

package/dist/mcp/server.js

@@ -0,0 +1,24 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { APP_VERSION } from "../lib/app-info.js";
+import { registerTools } from "./tools.js";
+const INSTRUCTIONS = "memi is long-term memory that persists between sessions. " +
+    "Call get_context at the start of a session. Call recall before answering questions that past decisions or preferences might affect. " +
+    "Call remember for durable decisions, preferences, facts, and mistakes. Prefer update_memory over saving a near-duplicate. " +
+    "Never store secrets.";
+export function createServer(rt, cwd = process.cwd()) {
+    const server = new McpServer({ name: "memi", version: APP_VERSION }, { instructions: INSTRUCTIONS });
+    registerTools(server, {
+        store: rt.store,
+        agent: rt.agent,
+        clientName: () => server.server.getClientVersion()?.name ?? null,
+        cwd,
+    });
+    return server;
+}
+/** Serves MCP over stdio. stdout belongs to the protocol, so anything human-readable goes to stderr. */
+export async function serveStdio(rt) {
+    const server = createServer(rt);
+    await server.connect(new StdioServerTransport());
+    console.error(`memi MCP server running (${rt.store.status().embedder?.provider ?? "no"} embedder)`);
+}

package/dist/mcp/tools.js

@@ -0,0 +1,152 @@
+import { z } from "zod";
+import { formatHits, formatMemories, formatMemory } from "../core/format.js";
+import { pickScope, resolveProject } from "../core/project.js";
+import { MemiError } from "../core/types.js";
+import { EmbedError } from "../embed/types.js";
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+/** Turns expected failures into tool errors the model can read, and lets real bugs through. */
+function safe(fn) {
+    return async (args) => {
+        try {
+            return await fn(args);
+        }
+        catch (err) {
+            if (err instanceof MemiError || err instanceof EmbedError) {
+                return { ...text(err.message), isError: true };
+            }
+            throw err;
+        }
+    };
+}
+const category = z.string().describe("Short label such as decision, preference, fact, error, todo, context. New names are created on the fly.");
+const importance = z.number().int().min(1).max(5).describe("1 (minor) to 5 (critical). Default 3.");
+const project = z.string().describe("Project name. Normally left out: it is worked out from the git repo or agent name.");
+const readScope = z.enum(["both", "project", "global", "all"]).describe("both = global plus this project (default), project, global, or all projects.");
+export function registerTools(server, ctx) {
+    const { store } = ctx;
+    const agent = () => ctx.agent ?? ctx.clientName();
+    const current = (p) => resolveProject({ project: p, agent: ctx.agent, cwd: ctx.cwd })?.project ?? null;
+    server.registerTool("remember", {
+        title: "Save a memory",
+        description: "Save something worth remembering in future sessions: a decision and why, a user preference, a durable fact, a mistake to avoid, or follow-up work. " +
+            "Write it so it makes sense on its own, without this conversation. Do not save secrets or things that are obvious from the code. " +
+            "The result lists similar existing memories; if one already covers this, use update_memory instead of saving a duplicate.",
+        inputSchema: {
+            content: z.string().describe("The memory itself. Short and self-contained."),
+            category: category.optional(),
+            importance: importance.optional(),
+            tags: z.array(z.string()).optional().describe("Optional keywords to help find it later."),
+            pinned: z.boolean().optional().describe("Pinned memories are loaded at the start of every session. Use for the few things that must never be missed."),
+            scope: z.enum(["project", "global"]).optional().describe("project = only this project. global = applies everywhere, such as user preferences. Default: project when one is known."),
+            project: project.optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    }, safe(async (a) => {
+        const target = pickScope({ scope: a.scope, project: a.project, agent: ctx.agent, cwd: ctx.cwd });
+        const r = await store.add({ ...a, ...target, agent: agent() });
+        const lines = [`Saved memory #${r.memory.id} (${r.memory.scope === "global" ? "global" : `project ${r.memory.project}`}, ${r.memory.category}, importance ${r.memory.importance}).`];
+        if (r.similar.length) {
+            lines.push("", "Similar memories already exist. If one covers this, call update_memory on it and forget #" + r.memory.id + ":");
+            lines.push(...r.similar.map((s) => `${formatMemory(s.memory)}`));
+        }
+        if (r.warning)
+            lines.push("", `Note: ${r.warning}`);
+        return text(lines.join("\n"));
+    }));
+    server.registerTool("recall", {
+        title: "Search memories",
+        description: "Search saved memories by meaning and by keyword. Use before answering anything that earlier decisions, preferences, or mistakes might affect, " +
+            "and when the user refers to something from a past session. Describe what you are looking for in plain language.",
+        inputSchema: {
+            query: z.string().describe("What to look for."),
+            scope: readScope.optional(),
+            project: project.optional(),
+            category: category.optional(),
+            min_importance: importance.optional(),
+            mode: z.enum(["hybrid", "semantic", "text"]).optional().describe("hybrid (default) combines meaning and keywords."),
+            limit: z.number().int().min(1).max(50).optional().describe("Default 10."),
+        },
+        annotations: { readOnlyHint: true },
+    }, safe(async (a) => {
+        const r = await store.search({
+            query: a.query,
+            scope: a.scope,
+            project: current(a.project),
+            category: a.category,
+            minImportance: a.min_importance,
+            mode: a.mode,
+            limit: a.limit,
+        });
+        const out = r.hits.length ? formatHits(r.hits) : "No matching memories.";
+        return text(r.note ? `${out}\n\nNote: ${r.note}` : out);
+    }));
+    server.registerTool("get_context", {
+        title: "Load session context",
+        description: "Load the pinned and high-importance memories (importance 4 or 5) for this project plus global ones. Call this once at the start of a session.",
+        inputSchema: { project: project.optional(), limit: z.number().int().min(1).max(50).optional().describe("Default 20.") },
+        annotations: { readOnlyHint: true },
+    }, safe(async (a) => {
+        const list = store.context({ project: current(a.project), limit: a.limit });
+        return text(list.length ? formatMemories(list) : "No pinned or high-importance memories yet.");
+    }));
+    server.registerTool("list_memories", {
+        title: "List memories",
+        description: "Browse memories without a search query, newest first by default. Use recall when you know what you are looking for.",
+        inputSchema: {
+            scope: readScope.optional(),
+            project: project.optional(),
+            category: category.optional(),
+            min_importance: importance.optional(),
+            pinned: z.boolean().optional(),
+            order: z.enum(["recent", "oldest", "importance"]).optional(),
+            limit: z.number().int().min(1).max(200).optional().describe("Default 50."),
+            offset: z.number().int().min(0).optional(),
+        },
+        annotations: { readOnlyHint: true },
+    }, safe(async (a) => {
+        const { items, total } = store.list({
+            scope: a.scope,
+            project: current(a.project),
+            category: a.category,
+            minImportance: a.min_importance,
+            pinned: a.pinned,
+            order: a.order,
+            limit: a.limit,
+            offset: a.offset,
+        });
+        return text(items.length ? `${items.length} of ${total}\n\n${formatMemories(items)}` : "No memories found.");
+    }));
+    server.registerTool("update_memory", {
+        title: "Update a memory",
+        description: "Change a memory by id: reword it, recategorize it, change importance, tags or pinning, or move it between global and a project. Only the fields you pass change.",
+        inputSchema: {
+            id: z.number().int().describe("Memory id, shown as #id in results."),
+            content: z.string().optional(),
+            category: category.optional(),
+            importance: importance.optional(),
+            tags: z.array(z.string()).optional().describe("Replaces the existing tags."),
+            pinned: z.boolean().optional(),
+            scope: z.enum(["project", "global"]).optional(),
+            project: project.optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    }, safe(async ({ id, ...patch }) => {
+        const moving = patch.scope === "project" && !patch.project;
+        const r = await store.update(id, moving ? { ...patch, project: pickScope({ scope: "project", agent: ctx.agent, cwd: ctx.cwd }).project } : patch);
+        if (!r)
+            return { ...text(`No memory with id ${id}.`), isError: true };
+        return text(`Updated.\n\n${formatMemory(r.memory)}${r.warning ? `\n\nNote: ${r.warning}` : ""}`);
+    }));
+    server.registerTool("forget", {
+        title: "Delete a memory",
+        description: "Permanently delete a memory by id. Use when a memory is wrong, outdated, or a duplicate. This cannot be undone.",
+        inputSchema: { id: z.number().int().describe("Memory id, shown as #id in results.") },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+    }, safe(async ({ id }) => (store.remove(id) ? text(`Deleted memory #${id}.`) : { ...text(`No memory with id ${id}.`), isError: true })));
+    server.registerTool("list_categories", {
+        title: "List categories",
+        description: "Show every category with how many memories it holds. Check this before inventing a new category name.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, safe(async () => text(store.categories().map((c) => `${c.name} (${c.count})${c.description ? `: ${c.description}` : ""}`).join("\n"))));
+}

package/dist/ui/assets.js

@@ -0,0 +1,38 @@
+import { readFile, stat } from "node:fs/promises";
+import { extname, join, resolve, sep } from "node:path";
+// The frontend files live in ui/ at the package root. This path is the same from src/ui and dist/ui.
+const ROOT = resolve(import.meta.dirname, "../../ui");
+const TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".woff2": "font/woff2",
+    ".svg": "image/svg+xml",
+    ".txt": "text/plain; charset=utf-8",
+};
+/** Returns a file from ui/, or null. Only known file types, and never anything outside ui/. */
+export async function readAsset(urlPath) {
+    let rel;
+    try {
+        rel = decodeURIComponent(urlPath);
+    }
+    catch {
+        return null;
+    }
+    if (rel === "/" || rel === "")
+        rel = "/index.html";
+    if (rel.includes("\0") || rel.includes("\\"))
+        return null;
+    const file = resolve(join(ROOT, rel));
+    const type = TYPES[extname(file)];
+    if (!type || !file.startsWith(ROOT + sep))
+        return null;
+    try {
+        if (!(await stat(file)).isFile())
+            return null;
+        return { body: await readFile(file), type, cache: type.startsWith("font/") || type === "image/svg+xml" ? "public, max-age=86400" : "no-cache" };
+    }
+    catch {
+        return null;
+    }
+}