om-memory-system 4.24.0-next.147 → 4.25.1

package/dist/services/turso/keyword-search.js

@@ -0,0 +1,153 @@
+/**
+ * Exact-word matching for memory search (openspec change
+ * hook-search-keywords-and-profile). The pure parts take their settings as
+ * arguments: do not import CONFIG here, many tests stub src/config.js.
+ */
+import { log } from "../logger.js";
+const MAX_TERMS = 24;
+// Words that carry no search value. With the OR query below, one of them
+// would pull most of a shard in as candidates.
+const STOP_WORDS = new Set([
+    "the",
+    "and",
+    "or",
+    "not",
+    "of",
+    "to",
+    "in",
+    "on",
+    "at",
+    "by",
+    "for",
+    "is",
+    "it",
+    "an",
+    "be",
+    "are",
+    "was",
+    "we",
+    "i",
+    "me",
+    "my",
+    "you",
+    "do",
+    "did",
+    "does",
+    "why",
+    "how",
+    "what",
+    "with",
+    "this",
+    "that",
+]);
+/**
+ * FTS5 query for the words of a prompt: lower-case terms from letters and
+ * digits only ("ADR-023" gives `adr` and `023`), each in quotes, joined by OR.
+ * Quoting and the character filter keep prompt text from becoming index
+ * syntax. Returns null when no usable term is left.
+ */
+export function buildKeywordQuery(queryText) {
+    const terms = new Set();
+    for (const word of (queryText ?? "").toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+        if (word.length < 2 || STOP_WORDS.has(word))
+            continue;
+        terms.add(word);
+        if (terms.size === MAX_TERMS)
+            break;
+    }
+    if (terms.size === 0)
+        return null;
+    return [...terms].map((term) => `"${term}"`).join(" OR ");
+}
+/**
+ * Similarity after the keyword boost: `base + keywordBoost × score ÷ best`,
+ * where `score` is the memory's match strength and `best` the strongest in the
+ * same search. The share is capped at 1 so the boost never passes
+ * `keywordBoost`, and the result never passes 1.
+ */
+export function applyKeywordBoost(base, score, bestScore, keywordBoost) {
+    if (!(keywordBoost > 0) || !(score > 0) || !(bestScore > 0))
+        return base;
+    return Math.min(1, base + keywordBoost * Math.min(1, score / bestScore));
+}
+// The index is derived data: external content (no second copy of the text),
+// kept in step by triggers, and rebuilt whenever it is missing or short.
+const INDEX_OBJECTS = ["memories_fts", "memories_fts_ai", "memories_fts_ad", "memories_fts_au"];
+const INDEX_SETUP = [
+    `CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+     content, tags, content='memories', content_rowid='rowid', tokenize='unicode61'
+   )`,
+    `CREATE TRIGGER IF NOT EXISTS memories_fts_ai AFTER INSERT ON memories BEGIN
+     INSERT INTO memories_fts(rowid, content, tags) VALUES (new.rowid, new.content, new.tags);
+   END`,
+    `CREATE TRIGGER IF NOT EXISTS memories_fts_ad AFTER DELETE ON memories BEGIN
+     INSERT INTO memories_fts(memories_fts, rowid, content, tags)
+     VALUES ('delete', old.rowid, old.content, old.tags);
+   END`,
+    `CREATE TRIGGER IF NOT EXISTS memories_fts_au AFTER UPDATE OF content, tags ON memories BEGIN
+     INSERT INTO memories_fts(memories_fts, rowid, content, tags)
+     VALUES ('delete', old.rowid, old.content, old.tags);
+     INSERT INTO memories_fts(rowid, content, tags) VALUES (new.rowid, new.content, new.tags);
+   END`,
+];
+async function indexIsCurrent(db) {
+    const names = INDEX_OBJECTS.map(() => "?").join(",");
+    const present = await db.all(`SELECT name FROM sqlite_schema WHERE name IN (${names})`, [
+        ...INDEX_OBJECTS,
+    ]);
+    if (present.length !== INDEX_OBJECTS.length)
+        return false;
+    // COUNT(*) on an external-content table reads the memories table, so the
+    // number of documents the index really holds comes from its docsize table.
+    const row = await db.get(`SELECT (SELECT COUNT(*) FROM memories_fts_docsize) AS indexed,
+            (SELECT COUNT(*) FROM memories) AS stored`);
+    return Number(row?.indexed) === Number(row?.stored);
+}
+/** Create or rebuild the keyword index of a shard. Idempotent. */
+export async function ensureKeywordIndex(db) {
+    if (await indexIsCurrent(db))
+        return;
+    // One transaction: a failed rebuild leaves no triggers behind that would
+    // write to a broken index on every save.
+    await db.transaction("write", async (tx) => {
+        for (const sql of INDEX_SETUP)
+            await tx.execute(sql);
+        await tx.execute(`INSERT INTO memories_fts(memories_fts) VALUES ('rebuild')`);
+    });
+}
+/**
+ * Memories of one shard that contain a word of the prompt, strongest first.
+ * Returns null when there is nothing to match or the index fails: search then
+ * continues with vector and tag results. The log holds a code and an error
+ * name only, never the prompt or memory text.
+ */
+export async function searchKeywords(db, queryText, containerTag, limit) {
+    const match = buildKeywordQuery(queryText);
+    if (!match)
+        return null;
+    try {
+        await ensureKeywordIndex(db);
+        const rows = await db.all(`SELECT m.id AS id, -bm25(memories_fts) AS score
+       FROM memories_fts JOIN memories m ON m.rowid = memories_fts.rowid
+       WHERE memories_fts MATCH ?${containerTag === "" ? "" : " AND m.container_tag = ?"}
+       ORDER BY score DESC LIMIT ?`, containerTag === "" ? [match, limit] : [match, containerTag, limit]);
+        const scores = new Map(rows.map((row) => [String(row.id), Number(row.score)]));
+        return { scores, best: Math.max(0, ...scores.values()) };
+    }
+    catch (error) {
+        log("Keyword search failed; using vector results", {
+            code: "keyword_index_failed",
+            error: error instanceof Error ? error.name : "unknown",
+        });
+        return null;
+    }
+}
+/**
+ * `base` with the boost for memory `id`; `base` itself when it has no keyword hit
+ * or the mode is `rrf` (rank fusion keeps each memory's own similarity).
+ */
+export function boostedSimilarity(base, hits, id, keywordBoost, mode = "boost") {
+    if (mode === "rrf")
+        return base;
+    return applyKeywordBoost(base, hits?.scores.get(id) ?? 0, hits?.best ?? 0, keywordBoost);
+}

package/dist/services/turso/rank-fusion.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Reciprocal rank fusion of the meaning list and the word list (openspec change
+ * hook-search-keywords-and-profile, design decision 9). Pure: the threshold and
+ * the limits are passed in, so do not import CONFIG here.
+ */
+/** The published constant of reciprocal rank fusion. */
+export declare const RRF_K = 60;
+/** Same size as the word-hit limit of one shard search (max(limit × 4, 32), limit 10). */
+export declare const RRF_WORD_LIMIT = 40;
+export interface FusionRow {
+    id: string;
+    similarity: number;
+    /** Match strength of a word hit; missing or 0 means the memory has no word match. */
+    keywordScore?: number;
+}
+export interface FusionOptions {
+    /** Lowest similarity for the meaning list. */
+    threshold: number;
+    limit: number;
+    wordLimit?: number;
+}
+/**
+ * Merge two ranked lists by rank only. The meaning list holds the rows at or
+ * above the threshold, ranked by similarity. The word list holds the rows with
+ * a word match, ranked by match strength. A row that is only in the word list
+ * can be returned although its similarity is below the threshold. Ties break by
+ * id so repeated searches agree. Each row keeps its own similarity.
+ */
+export declare function rankFusion<T extends FusionRow>(rows: T[], options: FusionOptions): T[];
+/**
+ * Fuse the candidates of all shards and drop the internal word score, so the
+ * results have the same shape as in `boost` mode.
+ */
+export declare function fuseShardResults<T extends FusionRow>(rows: T[], threshold: number, limit: number): Omit<T, "keywordScore">[];

package/dist/services/turso/rank-fusion.js

@@ -0,0 +1,45 @@
+/**
+ * Reciprocal rank fusion of the meaning list and the word list (openspec change
+ * hook-search-keywords-and-profile, design decision 9). Pure: the threshold and
+ * the limits are passed in, so do not import CONFIG here.
+ */
+/** The published constant of reciprocal rank fusion. */
+export const RRF_K = 60;
+/** Same size as the word-hit limit of one shard search (max(limit × 4, 32), limit 10). */
+export const RRF_WORD_LIMIT = 40;
+const byIdAfter = (compare) => (a, b) => compare(a, b) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+/**
+ * Merge two ranked lists by rank only. The meaning list holds the rows at or
+ * above the threshold, ranked by similarity. The word list holds the rows with
+ * a word match, ranked by match strength. A row that is only in the word list
+ * can be returned although its similarity is below the threshold. Ties break by
+ * id so repeated searches agree. Each row keeps its own similarity.
+ */
+export function rankFusion(rows, options) {
+    const meaning = rows
+        .filter((row) => row.similarity >= options.threshold)
+        .sort(byIdAfter((a, b) => b.similarity - a.similarity));
+    const words = rows
+        .filter((row) => (row.keywordScore ?? 0) > 0)
+        .sort(byIdAfter((a, b) => (b.keywordScore ?? 0) - (a.keywordScore ?? 0)))
+        .slice(0, options.wordLimit ?? RRF_WORD_LIMIT);
+    const fused = new Map();
+    for (const list of [meaning, words]) {
+        list.forEach((row, index) => {
+            const entry = fused.get(row.id) ?? { row, score: 0 };
+            entry.score += 1 / (RRF_K + index + 1);
+            fused.set(row.id, entry);
+        });
+    }
+    return [...fused.values()]
+        .sort((a, b) => b.score - a.score || (a.row.id < b.row.id ? -1 : a.row.id > b.row.id ? 1 : 0))
+        .slice(0, Math.max(0, options.limit))
+        .map((entry) => entry.row);
+}
+/**
+ * Fuse the candidates of all shards and drop the internal word score, so the
+ * results have the same shape as in `boost` mode.
+ */
+export function fuseShardResults(rows, threshold, limit) {
+    return rankFusion(rows, { threshold, limit }).map(({ keywordScore: _word, ...rest }) => rest);
+}

package/dist/services/turso/tag-match.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Share of query words that name one of a memory's tags, from 0 to 1. A word
+ * matches when it equals a whole tag or one part of a tag ("code" matches
+ * "claude-code"). Plain substring matching let short tags such as "ui" match
+ * words like "build" or "guide", which pushed weak results up.
+ */
+export declare function tagMatchBoost(queryText: string | undefined, tagsCsv: string): number;

package/dist/services/turso/tag-match.js

@@ -0,0 +1,29 @@
+// Scripts written without spaces between words. A query in one of these is a
+// single token, so a tag can only be found inside it.
+const UNSPACED_SCRIPT = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Thai}]/u;
+function tokens(text) {
+    return text
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((token) => token.length > 0);
+}
+/**
+ * Share of query words that name one of a memory's tags, from 0 to 1. A word
+ * matches when it equals a whole tag or one part of a tag ("code" matches
+ * "claude-code"). Plain substring matching let short tags such as "ui" match
+ * words like "build" or "guide", which pushed weak results up.
+ */
+export function tagMatchBoost(queryText, tagsCsv) {
+    const tags = tagsCsv
+        .split(",")
+        .map((tag) => tag.trim().toLowerCase())
+        .filter((tag) => tag.length > 0);
+    // A one-character word counts only when it is a whole tag ("C language", tag "c").
+    const words = tokens(queryText ?? "").filter((word) => word.length > 1 || tags.includes(word));
+    if (words.length === 0 || tags.length === 0)
+        return 0;
+    const tagParts = new Set(tags.flatMap((tag) => [tag, ...tokens(tag)]));
+    const unspacedTags = [...tagParts].filter((part) => UNSPACED_SCRIPT.test(part));
+    const matches = words.filter((word) => tagParts.has(word) || unspacedTags.some((tag) => word.includes(tag))).length;
+    return matches / words.length;
+}

package/dist/services/turso/types.d.ts

@@ -30,6 +30,8 @@ export interface SearchResult {
     id: string;
     memory: string;
     similarity: number;
+    /** Internal: match strength of a word hit. Removed before results leave search. */
+    keywordScore?: number;
     createdAt?: number;
     tags?: string[];
     type?: string;

package/dist/services/turso/vector-search.d.ts

@@ -1,13 +1,13 @@
 import type { MemoryRecord, SearchResult, ShardInfo } from "./types.js";
+import type { KeywordMode } from "../../utils/keyword-boost.js";
 import type { TursoDb } from "./turso-db.js";
 import type { Transaction } from "@libsql/client";
 export declare class TursoVectorSearch {
     insertVectorInTransaction(tx: Transaction, record: MemoryRecord): Promise<void>;
     insertVector(db: TursoDb, record: MemoryRecord): Promise<void>;
-    searchInShard(shard: ShardInfo, queryVector: Float32Array, containerTag: string, limit: number, queryText?: string): Promise<SearchResult[]>;
+    searchInShard(shard: ShardInfo, queryVector: Float32Array, containerTag: string, limit: number, queryText?: string, keywordBoost?: number, keywordMode?: KeywordMode): Promise<SearchResult[]>;
     private searchKind;
-    private exactScanKind;
-    searchAcrossShards(shards: ShardInfo[], queryVector: Float32Array, containerTag: string, limit: number, similarityThreshold: number, queryText?: string): Promise<{
+    searchAcrossShards(shards: ShardInfo[], queryVector: Float32Array, containerTag: string, limit: number, similarityThreshold: number, queryText?: string, keywordBoost?: number, keywordMode?: KeywordMode): Promise<{
         results: SearchResult[];
         warnings: string[];
     }>;

package/dist/services/turso/vector-search.js

@@ -1,6 +1,10 @@
 import { tursoConnectionManager } from "./connection-manager.js";
 import { log } from "../logger.js";
 import { distanceToSimilarity, vectorToJson } from "./vector-utils.js";
+import { tagMatchBoost } from "./tag-match.js";
+import { exactScanKind } from "./exact-scan.js";
+import { boostedSimilarity, searchKeywords } from "./keyword-search.js";
+import { fuseShardResults } from "./rank-fusion.js";
 function parseMetadata(value) {
     if (!value || typeof value !== "string")
         return undefined;
@@ -88,7 +92,7 @@ export class TursoVectorSearch {
       ) VALUES (?, ?, vector32(?), NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `, [record.id, record.content, contentVector, ...commonArgs]);
     }
-    async searchInShard(shard, queryVector, containerTag, limit, queryText) {
+    async searchInShard(shard, queryVector, containerTag, limit, queryText, keywordBoost = 0, keywordMode = "boost") {
         const db = await tursoConnectionManager.getConnection(shard.dbPath);
         const queryJson = vectorToJson(queryVector);
         // Over-fetch aggressively when filtering by container_tag after ANN,
@@ -101,6 +105,11 @@ export class TursoVectorSearch {
             candidateIds.add(result.id);
         for (const result of tagsResults)
             candidateIds.add(result.id);
+        const kwHits = keywordBoost > 0
+            ? await searchKeywords(db, queryText, containerTag, Math.max(limit * 4, 32))
+            : null;
+        for (const id of kwHits?.scores.keys() ?? [])
+            candidateIds.add(id);
         const ids = Array.from(candidateIds);
         if (ids.length === 0)
             return [];
@@ -132,30 +141,21 @@ export class TursoVectorSearch {
     `, containerTag === ""
             ? [queryJson, queryJson, ...ids]
             : [queryJson, queryJson, ...ids, containerTag]);
-        const queryWords = queryText
-            ? queryText
-                .toLowerCase()
-                .split(/[\s,]+/)
-                .filter((word) => word.length > 1)
-            : [];
         const hydratedResults = rows.map((row) => {
             const contentSim = distanceToSimilarity(Number(row.content_dist));
             const tagsSim = row.tags_dist == null || row.tags_dist === undefined
                 ? 0
                 : distanceToSimilarity(Number(row.tags_dist));
             const memoryTagsStr = String(row.tags || "");
-            const memoryTags = memoryTagsStr.split(",").map((tag) => tag.trim().toLowerCase());
-            let exactMatchBoost = 0;
-            if (queryWords.length > 0 && memoryTags.length > 0) {
-                const matches = queryWords.filter((word) => memoryTags.some((tag) => tag.includes(word) || word.includes(tag))).length;
-                exactMatchBoost = matches / Math.max(queryWords.length, 1);
-            }
+            const exactMatchBoost = tagMatchBoost(queryText, memoryTagsStr);
             const finalTagsSim = Math.max(tagsSim, exactMatchBoost);
-            const similarity = contentSim * 0.6 + finalTagsSim * 0.4;
+            const base = contentSim * 0.6 + finalTagsSim * 0.4;
+            const similarity = boostedSimilarity(base, kwHits, String(row.id), keywordBoost, keywordMode);
             return {
                 id: String(row.id),
                 memory: String(row.content),
                 similarity,
+                keywordScore: kwHits?.scores.get(String(row.id)),
                 createdAt: Number(row.created_at),
                 tags: memoryTagsStr ? memoryTagsStr.split(",") : [],
                 type: row.type ? String(row.type) : undefined,
@@ -171,7 +171,9 @@ export class TursoVectorSearch {
             };
         });
         hydratedResults.sort((a, b) => b.similarity - a.similarity);
-        return hydratedResults.slice(0, Math.max(0, limit));
+        // Rank fusion needs the word-only candidates too; it applies the limit itself.
+        const fusing = keywordMode === "rrf" && keywordBoost > 0;
+        return fusing ? hydratedResults : hydratedResults.slice(0, Math.max(0, limit));
     }
     async searchKind(db, queryJson, k, containerTag, indexName, columnName) {
         try {
@@ -198,35 +200,14 @@ export class TursoVectorSearch {
                 indexName,
                 error: String(error),
             });
-            return this.exactScanKind(db, queryJson, k, containerTag, columnName);
+            return exactScanKind(db, queryJson, k, containerTag, columnName);
         }
     }
-    async exactScanKind(db, queryJson, k, containerTag, columnName) {
-        const rows = await db.all(containerTag === ""
-            ? `
-        SELECT m.id AS id, vector_distance_cos(m.${columnName}, vector32(?)) AS dist
-        FROM memories m
-        WHERE m.${columnName} IS NOT NULL
-        ORDER BY dist ASC
-        LIMIT ?
-      `
-            : `
-        SELECT m.id AS id, vector_distance_cos(m.${columnName}, vector32(?)) AS dist
-        FROM memories m
-        WHERE m.${columnName} IS NOT NULL AND m.container_tag = ?
-        ORDER BY dist ASC
-        LIMIT ?
-      `, containerTag === "" ? [queryJson, k] : [queryJson, containerTag, k]);
-        return rows.map((row) => ({
-            id: String(row.id),
-            similarity: distanceToSimilarity(Number(row.dist)),
-        }));
-    }
-    async searchAcrossShards(shards, queryVector, containerTag, limit, similarityThreshold, queryText) {
+    async searchAcrossShards(shards, queryVector, containerTag, limit, similarityThreshold, queryText, keywordBoost = 0, keywordMode = "boost") {
         const shardErrors = [];
         const shardPromises = shards.map(async (shard) => {
             try {
-                return await this.searchInShard(shard, queryVector, containerTag, limit, queryText);
+                return await this.searchInShard(shard, queryVector, containerTag, limit, queryText, keywordBoost, keywordMode);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -253,6 +234,9 @@ export class TursoVectorSearch {
             });
         }
         const allResults = resultsArray.flat();
+        if (keywordMode === "rrf" && keywordBoost > 0) {
+            return { results: fuseShardResults(allResults, similarityThreshold, limit), warnings };
+        }
         allResults.sort((a, b) => b.similarity - a.similarity);
         return {
             results: allResults

package/dist/services/user-profile/profile-context.d.ts

@@ -1 +1,6 @@
-export declare function getUserProfileContext(userId: string): Promise<string | null>;
+/**
+ * The profile block for the prompt. With `queryVector`, half of each section
+ * (rounded up) follows the prompt; without it the block is the same for every
+ * prompt, as before.
+ */
+export declare function getUserProfileContext(userId: string, queryVector?: ArrayLike<number>): Promise<string | null>;

package/dist/services/user-profile/profile-context.js

@@ -2,6 +2,7 @@ import { userProfileManager } from "./user-profile-manager.js";
 import { CONFIG } from "../../config.js";
 import { sortProfileItems } from "../../utils/profile.js";
 import { log } from "../logger.js";
+import { selectProfileItems } from "./profile-relevance.js";
 function dedupByCategory(items, topN) {
     if (items.length <= topN)
         return items;
@@ -33,7 +34,12 @@ function escapeContextText(value) {
         .replace(/</g, "&lt;")
         .replace(/>/g, "&gt;");
 }
-export async function getUserProfileContext(userId) {
+/**
+ * The profile block for the prompt. With `queryVector`, half of each section
+ * (rounded up) follows the prompt; without it the block is the same for every
+ * prompt, as before.
+ */
+export async function getUserProfileContext(userId, queryVector) {
     const profile = await userProfileManager.getActiveProfile(userId);
     if (!profile) {
         return null;
@@ -60,9 +66,35 @@ export async function getUserProfileContext(userId) {
     const sortedWfs = profileData.workflows.length > 0
         ? sortProfileItems(profileData.workflows, "frequency")
         : [];
-    const topPrefs = dedupByCategory(scoreByRecency(sortedPrefs.slice(0, injectPrefs * 2)), injectPrefs);
-    const topPats = dedupByCategory(sortedPats, injectPats);
-    const topWfs = sortedWfs.slice(0, injectWfs);
+    // The prompt must be about as close to an item as it is to a memory.
+    const minCloseness = CONFIG.similarityThreshold;
+    const prefs = selectProfileItems({
+        baseline: dedupByCategory(scoreByRecency(sortedPrefs.slice(0, injectPrefs * 2)), injectPrefs),
+        candidates: sortedPrefs,
+        count: injectPrefs,
+        queryVector,
+        minCloseness,
+        onePerCategory: true,
+    });
+    const pats = selectProfileItems({
+        baseline: dedupByCategory(sortedPats, injectPats),
+        candidates: sortedPats,
+        count: injectPats,
+        queryVector,
+        minCloseness,
+        onePerCategory: true,
+    });
+    const wfs = selectProfileItems({
+        baseline: sortedWfs.slice(0, injectWfs),
+        candidates: sortedWfs,
+        count: injectWfs,
+        queryVector,
+        minCloseness,
+        onePerCategory: false,
+    });
+    const topPrefs = prefs.items;
+    const topPats = pats.items;
+    const topWfs = wfs.items;
     if (topPrefs.length > 0) {
         parts.push("User Preferences:");
         topPrefs.forEach((pref) => {
@@ -96,9 +128,13 @@ export async function getUserProfileContext(userId) {
     const text = parts.join("\n");
     if (topPrefs.length + topPats.length + topWfs.length > 0) {
         log("profile inject", {
-            prefs: topPrefs.map((p) => `[${p.category}] ${p.description}`.substring(0, 80)),
-            pats: topPats.map((p) => `[${p.category}] ${p.description}`.substring(0, 80)),
-            wfs: topWfs.map((w) => w.description.substring(0, 80)),
+            // Counts only: the log never holds the prompt.
+            relevanceSlots: {
+                prefs: prefs.relevanceSlots,
+                pats: pats.relevanceSlots,
+                wfs: wfs.relevanceSlots,
+            },
+            counts: { prefs: topPrefs.length, pats: topPats.length, wfs: topWfs.length },
         });
     }
     return text;

package/dist/services/user-profile/profile-relevance.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Choose profile items for the injected block by relevance to the prompt
+ * (openspec change hook-search-keywords-and-profile). Pure functions: the
+ * vector, the items, the counts, and the minimum closeness are arguments, so
+ * callers and tests need no store and no CONFIG.
+ */
+export interface VectorItem {
+    category?: string;
+    anchor?: number[];
+    centroid?: number[];
+}
+export interface SelectProfileItemsInput<T extends VectorItem> {
+    /** Today's selection for the section, in today's order. */
+    baseline: T[];
+    /** Every eligible item, in today's order. Relevance may pick from all of them. */
+    candidates: T[];
+    /** Injected items for the section. */
+    count: number;
+    /** The embedded prompt. Without it the section keeps today's selection. */
+    queryVector: ArrayLike<number> | undefined;
+    /** Items with a lower cosine similarity never take a relevance slot. */
+    minCloseness: number;
+    /** Sections that group by category keep one item per category. */
+    onePerCategory: boolean;
+}
+export interface SelectProfileItemsResult<T> {
+    items: T[];
+    /** How many items came in through relevance, for the log. */
+    relevanceSlots: number;
+}
+export declare function cosineSimilarity(a: ArrayLike<number>, b: ArrayLike<number>): number;
+/**
+ * Half of the slots, rounded up, go to the items closest to the prompt. The
+ * other slots keep today's order. With no prompt vector, or no item close
+ * enough, the result is `baseline` unchanged.
+ */
+export declare function selectProfileItems<T extends VectorItem>(input: SelectProfileItemsInput<T>): SelectProfileItemsResult<T>;

package/dist/services/user-profile/profile-relevance.js

@@ -0,0 +1,75 @@
+/**
+ * Choose profile items for the injected block by relevance to the prompt
+ * (openspec change hook-search-keywords-and-profile). Pure functions: the
+ * vector, the items, the counts, and the minimum closeness are arguments, so
+ * callers and tests need no store and no CONFIG.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        const x = a[i];
+        const y = b[i];
+        dot += x * y;
+        normA += x * x;
+        normB += y * y;
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    return dot / Math.sqrt(normA * normB);
+}
+/**
+ * Half of the slots, rounded up, go to the items closest to the prompt. The
+ * other slots keep today's order. With no prompt vector, or no item close
+ * enough, the result is `baseline` unchanged.
+ */
+export function selectProfileItems(input) {
+    const { baseline, candidates, count, queryVector, minCloseness, onePerCategory } = input;
+    const unchanged = { items: baseline, relevanceSlots: 0 };
+    if (!queryVector || queryVector.length === 0 || count <= 0)
+        return unchanged;
+    const ranked = candidates
+        .map((item) => {
+        const vector = item.anchor ?? item.centroid;
+        return { item, closeness: vector ? cosineSimilarity(queryVector, vector) : 0 };
+    })
+        .filter((entry) => entry.closeness >= minCloseness && entry.closeness > 0)
+        .sort((a, b) => b.closeness - a.closeness);
+    const chosen = [];
+    const categories = new Set();
+    const take = (item) => {
+        if (chosen.includes(item))
+            return false;
+        if (onePerCategory && categories.has(item.category))
+            return false;
+        chosen.push(item);
+        categories.add(item.category);
+        return true;
+    };
+    const relevanceCap = Math.ceil(count / 2);
+    let relevanceSlots = 0;
+    for (const { item } of ranked) {
+        if (relevanceSlots >= relevanceCap)
+            break;
+        if (take(item))
+            relevanceSlots++;
+    }
+    if (relevanceSlots === 0)
+        return unchanged;
+    for (const item of baseline) {
+        if (chosen.length >= count)
+            break;
+        take(item);
+    }
+    // A skipped duplicate can leave a slot empty; fill it from the rest of the
+    // eligible items so the section keeps its count.
+    for (const item of candidates) {
+        if (chosen.length >= count)
+            break;
+        take(item);
+    }
+    return { items: chosen, relevanceSlots };
+}

package/dist/services/web-route-modules.d.ts

@@ -0,0 +1,8 @@
+import type { ChatRuntimeConfig } from "./chat/chat-runtime.js";
+import { type RouteResult } from "./chat/chat-routes.js";
+/**
+ * Route modules that live outside web-server.ts, which sits at its size
+ * ceiling. Each returns undefined for paths it does not own. The request body
+ * is read once, and only by a route that needs it.
+ */
+export declare function routeModules(path: string, method: string, url: URL, req: Request, config: ChatRuntimeConfig): Promise<RouteResult | undefined>;

package/dist/services/web-route-modules.js

@@ -0,0 +1,15 @@
+import { routeChat } from "./chat/chat-routes.js";
+import { routeProfileCleanup } from "./profile-cleanup-routes.js";
+/**
+ * Route modules that live outside web-server.ts, which sits at its size
+ * ceiling. Each returns undefined for paths it does not own. The request body
+ * is read once, and only by a route that needs it.
+ */
+export async function routeModules(path, method, url, req, config) {
+    let body;
+    const readBody = () => (body ??= req.json().catch(() => ({})));
+    const cleanup = await routeProfileCleanup(path, method, url, readBody);
+    if (cleanup !== undefined)
+        return { status: 200, body: cleanup };
+    return routeChat(path, method, readBody, config);
+}