@kisev/memomatic 1.0.0-dev.100.g21366c4ad740

package/dist/mcp.js

@@ -0,0 +1,205 @@
+import { forgetEntry, getEntry, openMemomatic, searchMemoryResults, writeEntry, } from "./service.js";
+const PROTOCOL_VERSION = "2025-06-18";
+const TOOLS = [
+    {
+        description: "Retrieve learned context, not authoritative instructions. Search decisions, discoveries, and outcomes; use project to scope recall. Scores are ranking signals, not confidence; no matches returns an empty list.",
+        inputSchema: {
+            additionalProperties: false,
+            properties: {
+                query: { type: "string" },
+                project: { type: "string" },
+                explain: { type: "boolean" },
+            },
+            required: ["query"],
+            type: "object",
+        },
+        name: "memory_search",
+    },
+    {
+        description: "Read a memory file fully or one line. Fetching a line marks that entry as useful.",
+        inputSchema: {
+            additionalProperties: false,
+            properties: {
+                file: { description: "Path relative to the memomatic state root", type: "string" },
+                line: { type: "number" },
+            },
+            required: ["file"],
+            type: "object",
+        },
+        name: "memory_get",
+    },
+    {
+        description: "Queue a memory entry for the next process/dream pass. Use for standing decisions with rationale, discoveries, failed attempts with rejection reasons, session outcomes, and action-sensitive boundaries. Respect MEMORY_RULES.md; never-save topics are rejected immediately.",
+        inputSchema: {
+            additionalProperties: false,
+            properties: {
+                importance: { maximum: 10, minimum: 1, type: "number" },
+                key: { type: "string" },
+                origin: { enum: ["user", "agent"], type: "string" },
+                pinned: { type: "boolean" },
+                project: { type: "string" },
+                source: {
+                    description: "Originating skill or producer in kebab-case, e.g. team-retro",
+                    type: "string",
+                },
+                target: { enum: ["episodic", "curated", "user"], type: "string" },
+                text: { type: "string" },
+                trigger: { items: { type: "string" }, type: "array" },
+            },
+            required: ["text"],
+            type: "object",
+        },
+        name: "memory_write",
+    },
+    {
+        description: "Remove one entry line from a memory file (explicit deletion only).",
+        inputSchema: {
+            additionalProperties: false,
+            properties: {
+                file: { description: "Path relative to the memomatic state root", type: "string" },
+                line: { type: "number" },
+            },
+            required: ["file", "line"],
+            type: "object",
+        },
+        name: "memory_forget",
+    },
+];
+async function callTool(name, args) {
+    const context = await openMemomatic();
+    try {
+        switch (name) {
+            case "memory_search": {
+                if (typeof args.query !== "string" || !args.query.trim())
+                    throw new Error("query is required");
+                if (args.project !== undefined && typeof args.project !== "string")
+                    throw new Error("project must be a string");
+                if (args.explain !== undefined && typeof args.explain !== "boolean")
+                    throw new Error("explain must be a boolean");
+                return await searchMemoryResults(context, args.query, {
+                    project: args.project,
+                    explain: args.explain === true,
+                });
+            }
+            case "memory_get": {
+                if (typeof args.file !== "string" || !args.file)
+                    throw new Error("file is required");
+                const line = typeof args.line === "number" ? args.line : undefined;
+                const result = await getEntry(context, args.file, line);
+                return {
+                    content: result.content,
+                    file: result.file.replace(`${context.paths.stateRoot}/`, ""),
+                    line: result.line,
+                };
+            }
+            case "memory_write": {
+                if (typeof args.text !== "string" || !args.text.trim())
+                    throw new Error("text is required");
+                const source = typeof args.source === "string" && args.source
+                    ? args.source
+                    : args.origin === "user"
+                        ? "user"
+                        : "agent";
+                const file = await writeEntry(context, {
+                    importance: typeof args.importance === "number" ? args.importance : undefined,
+                    key: typeof args.key === "string" ? args.key : undefined,
+                    origin: args.origin === "user" ? "user" : "agent",
+                    pinned: args.pinned === true,
+                    project: typeof args.project === "string" ? args.project : undefined,
+                    source,
+                    target: args.target === "curated" || args.target === "user" ? args.target : "episodic",
+                    text: args.text,
+                    trigger: Array.isArray(args.trigger)
+                        ? args.trigger.filter((item) => typeof item === "string")
+                        : undefined,
+                });
+                return {
+                    file: file.replace(`${context.paths.stateRoot}/`, ""),
+                    flushHint: "run `memomatic process` to index queued entries immediately",
+                    queued: true,
+                };
+            }
+            case "memory_forget": {
+                if (typeof args.file !== "string" || typeof args.line !== "number")
+                    throw new Error("file and line are required");
+                const file = await forgetEntry(context, { file: args.file, line: args.line });
+                return { file: file.replace(`${context.paths.stateRoot}/`, ""), forgotten: true };
+            }
+            default:
+                throw new Error(`unknown tool: ${name}`);
+        }
+    }
+    finally {
+        context.store.close();
+    }
+}
+export function mcpResponse(id, result) {
+    return `${JSON.stringify({ id, jsonrpc: "2.0", result })}\n`;
+}
+export function mcpError(id, code, message) {
+    return `${JSON.stringify({ error: { code, message }, id, jsonrpc: "2.0" })}\n`;
+}
+export async function handleMcpRequest(request) {
+    const { id, method } = request;
+    if (method === "initialize")
+        return mcpResponse(id, {
+            capabilities: { tools: {} },
+            protocolVersion: PROTOCOL_VERSION,
+            serverInfo: { name: "memomatic", version: "0.1.0" },
+        });
+    if (method === "ping")
+        return mcpResponse(id, {});
+    if (method === "tools/list")
+        return mcpResponse(id, { tools: TOOLS });
+    if (method === "tools/call") {
+        const params = request.params ?? {};
+        const name = typeof params.name === "string" ? params.name : "";
+        const args = params.arguments && typeof params.arguments === "object"
+            ? params.arguments
+            : {};
+        try {
+            const content = await callTool(name, args);
+            return mcpResponse(id, {
+                content: [{ text: JSON.stringify(content), type: "text" }],
+            });
+        }
+        catch (error) {
+            return mcpResponse(id, {
+                content: [
+                    {
+                        text: JSON.stringify({ error: error.message }),
+                        type: "text",
+                    },
+                ],
+                isError: true,
+            });
+        }
+    }
+    if (method?.startsWith("notifications/"))
+        return "";
+    return mcpError(id, -32601, `method not found: ${method ?? "(none)"}`);
+}
+export async function runMcpServer(input = process.stdin, output = process.stdout) {
+    let buffer = "";
+    input.setEncoding("utf8");
+    for await (const chunk of input) {
+        buffer += chunk;
+        let newline = buffer.indexOf("\n");
+        while (newline !== -1) {
+            const frame = buffer.slice(0, newline).trim();
+            buffer = buffer.slice(newline + 1);
+            if (frame) {
+                try {
+                    const request = JSON.parse(frame);
+                    const response = await handleMcpRequest(request);
+                    if (response)
+                        output.write(response);
+                }
+                catch {
+                    output.write(mcpError(null, -32700, "parse error"));
+                }
+            }
+            newline = buffer.indexOf("\n");
+        }
+    }
+}

package/dist/opencode-config.d.ts

@@ -0,0 +1 @@
+export declare function isolatedProviderConfig(): Promise<Record<string, unknown>>;

package/dist/opencode-config.js

@@ -0,0 +1,84 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { parse } from "jsonc-parser";
+const PROVIDER_FIELDS = [
+    "providers",
+    "provider",
+    "model",
+    "enabled_providers",
+    "disabled_providers",
+    "experimental",
+    "enterprise",
+];
+function record(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function merge(left, right, key = "") {
+    if (key === "policies" && Array.isArray(left) && Array.isArray(right))
+        return [...left, ...right];
+    if (!record(left) || !record(right))
+        return right;
+    return Object.fromEntries([...new Set([...Object.keys(left), ...Object.keys(right)])].map((key) => [
+        key,
+        key in right ? merge(left[key], right[key], key) : left[key],
+    ]));
+}
+function anchorFiles(value, directory) {
+    if (typeof value === "string")
+        return value.replace(/\{file:([^}]+)\}/g, (original, path) => isAbsolute(path) || path.startsWith("~/") ? original : `{file:${resolve(directory, path)}}`);
+    if (Array.isArray(value))
+        return value.map((entry) => anchorFiles(entry, directory));
+    if (record(value))
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, anchorFiles(entry, directory)]));
+    return value;
+}
+export async function isolatedProviderConfig() {
+    const root = process.env.OPENCODE_CONFIG_DIR ??
+        join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "opencode");
+    const paths = [
+        join(root, "opencode.json"),
+        join(root, "opencode.jsonc"),
+        ...(process.env.OPENCODE_CONFIG ? [resolve(process.env.OPENCODE_CONFIG)] : []),
+    ];
+    let result = {};
+    const include = (value, directory) => {
+        if (!record(value))
+            throw new Error("OpenCode configuration must be a JSON object");
+        const selected = Object.fromEntries(PROVIDER_FIELDS.filter((key) => key in value).map((key) => [
+            key,
+            anchorFiles(value[key], directory),
+        ]));
+        if (record(selected.experimental))
+            selected.experimental = { policies: selected.experimental.policies ?? [] };
+        result = merge(result, selected);
+    };
+    for (const path of [...new Set(paths)]) {
+        let text;
+        try {
+            text = await readFile(path, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT" &&
+                path !== (process.env.OPENCODE_CONFIG ? resolve(process.env.OPENCODE_CONFIG) : undefined))
+                continue;
+            throw new Error("Cannot read OpenCode provider configuration");
+        }
+        const errors = [];
+        const value = parse(text, errors, { allowTrailingComma: true });
+        if (errors.length)
+            throw new Error("OpenCode provider configuration is not valid JSON/JSONC");
+        include(value, dirname(path));
+    }
+    if (process.env.OPENCODE_CONFIG_CONTENT) {
+        let value;
+        try {
+            value = JSON.parse(process.env.OPENCODE_CONFIG_CONTENT);
+        }
+        catch {
+            throw new Error("OpenCode inline configuration must be a JSON object");
+        }
+        include(value, process.cwd());
+    }
+    return result;
+}

package/dist/operations.d.ts

@@ -0,0 +1,7 @@
+import type { Observe } from "./generated/cli.js";
+export type OperationOptions = {
+    signal?: AbortSignal;
+    observe?: Observe;
+    force?: boolean;
+};
+export declare function check(options: OperationOptions): void;

package/dist/operations.js

@@ -0,0 +1,3 @@
+export function check(options) {
+    options.signal?.throwIfAborted();
+}

package/dist/paths.d.ts

@@ -0,0 +1,18 @@
+export type MemomaticPaths = {
+    stateRoot: string;
+    configRoot: string;
+    memoryFile: string;
+    userFile: string;
+    dreamsFile: string;
+    rulesFile: string;
+    settingsFile: string;
+    dailyDir: string;
+    archiveDir: string;
+    historyDir: string;
+    indexFile: string;
+    inboxDir: string;
+    rejectedDir: string;
+    runLockFile: string;
+};
+export declare function memomaticPaths(): MemomaticPaths;
+export declare function verifyMemomaticRoots(paths: MemomaticPaths): Promise<void>;

package/dist/paths.js

@@ -0,0 +1,55 @@
+import { lstat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve, sep } from "node:path";
+function safeXdg(name, fallback) {
+    const configured = process.env[name];
+    if (configured) {
+        if (!isAbsolute(configured) || configured.split(sep).includes(".."))
+            throw new Error(`${name} must be an absolute safe path`);
+        return resolve(configured);
+    }
+    const home = process.env.HOME ?? homedir();
+    if (!isAbsolute(home) || home.split(sep).includes(".."))
+        throw new Error("HOME must be an absolute safe path");
+    return join(resolve(home), fallback);
+}
+async function assertDirectory(path) {
+    try {
+        const info = await lstat(path);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new Error(`memomatic directory is unsafe: ${path}`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+export function memomaticPaths() {
+    const configured = process.env.MEMOMATIC_HOME;
+    if (configured && (!isAbsolute(configured) || configured.split(sep).includes("..")))
+        throw new Error("MEMOMATIC_HOME must be an absolute safe path");
+    const stateRoot = configured
+        ? resolve(configured)
+        : join(safeXdg("XDG_STATE_HOME", ".local/state"), "memomatic");
+    const configRoot = join(safeXdg("XDG_CONFIG_HOME", ".config"), "memomatic");
+    return {
+        stateRoot,
+        configRoot,
+        memoryFile: join(stateRoot, "MEMORY.md"),
+        userFile: join(stateRoot, "USER.md"),
+        dreamsFile: join(stateRoot, "DREAMS.md"),
+        rulesFile: join(configRoot, "MEMORY_RULES.md"),
+        settingsFile: process.env.MEMOMATIC_CONFIG ?? join(configRoot, "settings.json"),
+        dailyDir: join(stateRoot, "memory"),
+        archiveDir: join(stateRoot, "archive"),
+        historyDir: join(stateRoot, "history"),
+        indexFile: join(stateRoot, "index.sqlite"),
+        inboxDir: join(stateRoot, "inbox"),
+        rejectedDir: join(stateRoot, "inbox", "rejected"),
+        runLockFile: join(stateRoot, "run.lock"),
+    };
+}
+export async function verifyMemomaticRoots(paths) {
+    await assertDirectory(paths.stateRoot);
+    await assertDirectory(paths.configRoot);
+}

package/dist/rules.d.ts

@@ -0,0 +1,13 @@
+export type MemoryRules = {
+    neverSave: string[];
+    autoClean: {
+        olderThanDays: number;
+        scope: "episodic";
+        source?: string;
+        unusedAfterDays?: number;
+    } | null;
+};
+export declare const emptyRules: () => MemoryRules;
+export declare function parseRules(markdown: string): MemoryRules;
+export declare function loadRules(rulesFile: string): Promise<MemoryRules>;
+export declare function isForbidden(text: string, rules: MemoryRules): boolean;

package/dist/rules.js

@@ -0,0 +1,39 @@
+import { readFile } from "node:fs/promises";
+const NEVER_SAVE = /^-\s*never-save:\s*(.+?)\s*$/gim;
+const AUTO_CLEAN = /^-\s*auto-clean:\s*older-than=(\d+)d\s+scope=episodic(?:\s+source=([a-z0-9-]+))?(?:\s+unused-after=(\d+)d)?\s*$/im;
+export const emptyRules = () => ({ neverSave: [], autoClean: null });
+export function parseRules(markdown) {
+    const rules = emptyRules();
+    for (const match of markdown.matchAll(NEVER_SAVE)) {
+        const topic = match[1].trim().toLowerCase();
+        if (topic)
+            rules.neverSave.push(topic);
+    }
+    const autoClean = AUTO_CLEAN.exec(markdown);
+    if (autoClean) {
+        const days = Number.parseInt(autoClean[1], 10);
+        const unused = autoClean[3] ? Number.parseInt(autoClean[3], 10) : NaN;
+        if (Number.isFinite(days) && days > 0)
+            rules.autoClean = {
+                olderThanDays: days,
+                scope: "episodic",
+                source: autoClean[2],
+                ...(Number.isFinite(unused) && unused > 0 ? { unusedAfterDays: unused } : {}),
+            };
+    }
+    return rules;
+}
+export async function loadRules(rulesFile) {
+    try {
+        return parseRules(await readFile(rulesFile, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return emptyRules();
+        throw error;
+    }
+}
+export function isForbidden(text, rules) {
+    const lowered = text.toLowerCase();
+    return rules.neverSave.some((topic) => lowered.includes(topic));
+}

package/dist/search.d.ts

@@ -0,0 +1,28 @@
+import { type IndexedEntry, MemoryStore } from "./store.js";
+import type { MemomaticPaths } from "./paths.js";
+import type { MemomaticSettings } from "./settings.js";
+import { type OperationOptions } from "./operations.js";
+export type SearchHit = {
+    entry: IndexedEntry;
+    score: number;
+    snippet: string;
+    explanation: {
+        matchedTokens: string[];
+        lexical: number;
+        semantic: number | null;
+        relevance: number;
+        exact: boolean;
+        recency: number;
+        importance: number;
+        reason: "lexical" | "semantic" | "both";
+    };
+};
+export declare function corpusFiles(paths: MemomaticPaths): Promise<string[]>;
+export declare function reindex(paths: MemomaticPaths, settings: MemomaticSettings, store: MemoryStore, options?: OperationOptions): Promise<number>;
+export type SearchOptions = {
+    includeArchived?: boolean;
+    markSurfaced?: boolean;
+    project?: string;
+};
+export declare function queryTokens(query: string): string[];
+export declare function search(store: MemoryStore, query: string, settings: MemomaticSettings, options?: SearchOptions): Promise<SearchHit[]>;

package/dist/search.js

@@ -0,0 +1,191 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { cosineSimilarity, stableIdFor } from "./store.js";
+import { entryKind, parseCorpusEntries } from "./corpus.js";
+import { entryImportance, entryObservedAt } from "./entries.js";
+import { embedTexts, embeddingFingerprint } from "./settings.js";
+import { check } from "./operations.js";
+export async function corpusFiles(paths) {
+    const files = [];
+    for (const name of ["MEMORY.md", "USER.md"]) {
+        const file = join(paths.stateRoot, name);
+        if (await readFile(file, "utf8").then(() => true, () => false))
+            files.push(file);
+    }
+    for (const name of (await readdir(paths.dailyDir).catch(() => [])).sort()) {
+        if (name.endsWith(".md"))
+            files.push(join(paths.dailyDir, name));
+    }
+    return files;
+}
+export async function reindex(paths, settings, store, options = {}) {
+    check(options);
+    options.observe?.({ phase: "index.scan", message: "Reading memory files" });
+    const entries = [];
+    const indexedIds = new Set();
+    for (const file of await corpusFiles(paths)) {
+        const markdown = await readFile(file, "utf8");
+        for (const entry of parseCorpusEntries(markdown, file)) {
+            if (entry.annotations.status === "superseded")
+                continue;
+            const stableId = stableIdFor(file, entry.text, entry.annotations.key ?? null);
+            if (indexedIds.has(stableId))
+                continue;
+            indexedIds.add(stableId);
+            entries.push({
+                stableId,
+                file: entry.file,
+                line: entry.line,
+                kind: entryKind(file),
+                key: entry.annotations.key ?? null,
+                text: entry.text,
+                trigger: entry.annotations.trigger ?? [],
+                importance: entryImportance(entry),
+                pinned: entry.annotations.pinned === true,
+                project: entry.annotations.project ?? null,
+                origin: entry.annotations.origin ?? null,
+                observedAt: Number.isNaN(entryObservedAt(entry)) ? null : entryObservedAt(entry),
+                status: entry.annotations.status === "active" ? "active" : null,
+                source: entry.annotations.source ?? null,
+            });
+        }
+    }
+    const prior = new Map(store.allEntries().map((entry) => [entry.stableId, entry.text]));
+    const cache = new Map(store.vectors().map((row) => [row.stableId, row.data]));
+    const compatible = !options.force && store.getMeta("embeddingFingerprint") === embeddingFingerprint(settings);
+    const vectors = settings.embedding ? [] : null;
+    const missing = entries
+        .map((entry, index) => ({ entry, index }))
+        .filter(({ entry, index }) => {
+        const cached = compatible && prior.get(entry.stableId) === entry.text
+            ? cache.get(entry.stableId)
+            : undefined;
+        if (cached && vectors) {
+            vectors[index] = cached;
+            return false;
+        }
+        return Boolean(vectors);
+    });
+    options.observe?.({
+        phase: "index.embeddings",
+        message: "Embedding changed entries",
+        total: missing.length,
+        completed: 0,
+        cached: entries.length - missing.length,
+    });
+    for (let start = 0; start < missing.length; start += 32) {
+        check(options);
+        const batch = missing.slice(start, start + 32);
+        const computed = await embedTexts(settings, batch.map((item) => item.entry.text), "document", options.signal);
+        if (vectors && computed)
+            batch.forEach((item, index) => {
+                vectors[item.index] = computed[index];
+            });
+        options.observe?.({
+            phase: "index.embeddings",
+            message: "Embedding batch complete",
+            total: missing.length,
+            completed: Math.min(start + 32, missing.length),
+        });
+    }
+    check(options);
+    if (vectors?.length && vectors.some((vector) => vector.length !== vectors[0].length))
+        throw new Error("embedding dimensions changed; run memomatic index --force");
+    store.replaceIndex(entries, vectors, embeddingFingerprint(settings));
+    options.observe?.({
+        phase: "index.done",
+        message: "Index committed",
+        entries: entries.length,
+        embedded: missing.length,
+        cached: entries.length - missing.length,
+    });
+    return entries.length;
+}
+function recencyMultiplier(entry, halfLifeDays, now = Date.now()) {
+    if (entry.kind !== "episodic" || entry.pinned)
+        return 1;
+    if (!entry.observedAt)
+        return 0.5;
+    const ageDays = Math.max(0, (now - entry.observedAt) / 86_400_000);
+    return Math.pow(0.5, ageDays / halfLifeDays);
+}
+export function queryTokens(query) {
+    return [
+        ...new Set(query
+            .normalize("NFKC")
+            .toLowerCase()
+            .match(/[\p{L}\p{N}]+/gu) ?? []),
+    ].filter((token) => token.length >= 2);
+}
+export async function search(store, query, settings, options = {}) {
+    if (!query.trim())
+        throw new Error("query is required");
+    const tokens = queryTokens(query);
+    const keyword = store.ftsSearch(query, 200);
+    const vector = new Map();
+    const storedVectors = store.vectors();
+    if (settings.embedding &&
+        store.allEntries().length &&
+        store.getMeta("embeddingFingerprint") !== embeddingFingerprint(settings))
+        throw new Error("embedding index is missing or belongs to another model; run memomatic index");
+    const queryVector = (await embedTexts(settings, [query], "query"))?.[0];
+    if (queryVector?.length) {
+        for (const row of storedVectors) {
+            if (row.data.length !== queryVector.length)
+                throw new Error("embedding dimensions changed; run memomatic index");
+            const similarity = cosineSimilarity(queryVector, row.data);
+            if (similarity > 0.05)
+                vector.set(row.stableId, similarity);
+        }
+    }
+    const candidates = new Set([...keyword.keys(), ...vector.keys()]);
+    const entries = store
+        .allEntries()
+        .filter((item) => options.project === undefined || item.project === options.project || item.kind === "user");
+    const byId = new Map(entries.map((entry) => [entry.stableId, entry]));
+    const hits = [];
+    for (const stableId of candidates) {
+        const entry = byId.get(stableId);
+        if (!entry)
+            continue;
+        const words = queryTokens(entry.text);
+        const matchedTokens = tokens.filter((token) => words.some((word) => word.startsWith(token)));
+        const lexical = keyword.has(stableId) && tokens.length ? matchedTokens.length / tokens.length : 0;
+        const semantic = vector.get(stableId) ?? null;
+        const lexicalAccepted = lexical >= settings.search.minScore && lexical >= 0.5;
+        const semanticAccepted = semantic !== null &&
+            semantic >= settings.search.minSemanticScore &&
+            semantic >= settings.search.minScore;
+        if (!lexicalAccepted && !semanticAccepted)
+            continue;
+        const relevance = Math.max(lexicalAccepted ? lexical : 0, semanticAccepted ? semantic : 0);
+        const recency = recencyMultiplier(entry, settings.search.halfLifeDays);
+        const importance = Math.max(0, Math.min(1, (entry.importance - 1) / 9));
+        const score = relevance * recency * (0.85 + 0.15 * importance);
+        if (score < settings.search.minScore)
+            continue;
+        hits.push({
+            entry,
+            score,
+            snippet: entry.text.slice(0, 240),
+            explanation: {
+                matchedTokens,
+                lexical,
+                semantic,
+                relevance,
+                recency,
+                importance,
+                exact: tokens.length > 0 && tokens.every((token) => words.includes(token)),
+                reason: lexicalAccepted ? (semanticAccepted ? "both" : "lexical") : "semantic",
+            },
+        });
+    }
+    hits.sort((left, right) => Number(right.explanation.exact) - Number(left.explanation.exact) ||
+        right.score - left.score ||
+        (right.explanation.semantic ?? 0) - (left.explanation.semantic ?? 0) ||
+        left.entry.stableId.localeCompare(right.entry.stableId));
+    const limited = hits.slice(0, settings.search.maxResults);
+    if (options.markSurfaced !== false && limited.length)
+        store.markSurfaced(limited.map((hit) => hit.entry.stableId), query);
+    return limited;
+}