@pinkpixel/memi 0.1.0 → 1.0.0

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 };
+}

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 {
+}