@mxalbert/context-mode 2.0.0

package/build/search/auto-memory.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Auto-memory search — searches CLAUDE.md / AGENTS.md / GEMINI.md / etc.
+ * and the platform's persistent memory directory for decisions,
+ * preferences, and context from prior sessions.
+ *
+ * Returns results in a format compatible with the unified search pipeline.
+ */
+export interface AutoMemoryResult {
+    title: string;
+    content: string;
+    source: string;
+    origin: "auto-memory";
+    timestamp?: string;
+}
+/**
+ * Minimal adapter contract used by searchAutoMemory.
+ * Avoids depending on the full HookAdapter type to keep this module standalone.
+ */
+export interface AutoMemoryAdapter {
+    getConfigDir(): string;
+    getInstructionFiles(): string[];
+    /**
+     * `projectDir` is optional for backwards compatibility with legacy
+     * callers — when supplied, adapters MUST return a project-scoped path
+     * (see HookAdapter.getMemoryDir contract, issue #663).
+     */
+    getMemoryDir(projectDir?: string): string;
+}
+/**
+ * Search auto-memory files for content matching any of the given queries.
+ *
+ * When `adapter` is provided, the per-platform conventions are used:
+ *   1. Project-level: <projectDir>/<each instructionFile>
+ *   2. User-level: <configDir>/<each instructionFile>
+ *   3. Memory dir: <memoryDir>/*.md
+ *
+ * Without an adapter (legacy callers), defaults to Claude conventions
+ * (CLAUDE.md + ~/.claude/memory) for backwards compatibility.
+ *
+ * @param queries  Array of search terms
+ * @param limit    Max results to return
+ * @param projectDir  Project directory path
+ * @param configDir   Explicit config dir override (legacy callers)
+ * @param adapter     Platform adapter — supplies instruction files + memory dir
+ * @returns Matching auto-memory results
+ */
+export declare function searchAutoMemory(queries: string[], limit?: number, projectDir?: string, configDir?: string, adapter?: AutoMemoryAdapter): AutoMemoryResult[];

package/build/search/auto-memory.js

@@ -0,0 +1,170 @@
+/**
+ * Auto-memory search — searches CLAUDE.md / AGENTS.md / GEMINI.md / etc.
+ * and the platform's persistent memory directory for decisions,
+ * preferences, and context from prior sessions.
+ *
+ * Returns results in a format compatible with the unified search pipeline.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, isAbsolute } from "node:path";
+import { resolveClaudeConfigDir } from "../util/claude-config.js";
+import { hashProjectDirCanonical } from "../session/db.js";
+const DEBUG = process.env.DEBUG?.includes("context-mode");
+/**
+ * Search auto-memory files for content matching any of the given queries.
+ *
+ * When `adapter` is provided, the per-platform conventions are used:
+ *   1. Project-level: <projectDir>/<each instructionFile>
+ *   2. User-level: <configDir>/<each instructionFile>
+ *   3. Memory dir: <memoryDir>/*.md
+ *
+ * Without an adapter (legacy callers), defaults to Claude conventions
+ * (CLAUDE.md + ~/.claude/memory) for backwards compatibility.
+ *
+ * @param queries  Array of search terms
+ * @param limit    Max results to return
+ * @param projectDir  Project directory path
+ * @param configDir   Explicit config dir override (legacy callers)
+ * @param adapter     Platform adapter — supplies instruction files + memory dir
+ * @returns Matching auto-memory results
+ */
+export function searchAutoMemory(queries, limit = 5, projectDir, configDir, adapter) {
+    const results = [];
+    // Resolve conventions — adapter wins over explicit configDir, which wins
+    // over the historical Claude defaults.
+    const instructionFiles = adapter?.getInstructionFiles() ?? ["CLAUDE.md"];
+    const adapterConfigDir = adapter?.getConfigDir();
+    // Issue #460 round-3: legacy fallback honors $CLAUDE_CONFIG_DIR via the
+    // canonical util so callers without an adapter still respect relocated
+    // CC config trees (and empty/whitespace env doesn't poison the path).
+    const adapterRelative = adapterConfigDir ? resolveAgainst(projectDir, adapterConfigDir) : null;
+    const effectiveConfigDir = adapterRelative ?? configDir ?? resolveClaudeConfigDir();
+    // Issue #663: scope memory dir by projectDir so parallel projects can't
+    // read each other's auto-memory. Adapter-aware path delegates the
+    // scoping to the adapter; legacy adapterless fallback applies the same
+    // hash directly so the contract holds at both call sites.
+    const adapterMemoryDir = adapter?.getMemoryDir(projectDir);
+    const fallbackMemoryBase = join(effectiveConfigDir, "memory");
+    const fallbackMemoryDir = projectDir
+        ? join(fallbackMemoryBase, hashProjectDirCanonical(projectDir))
+        : fallbackMemoryBase;
+    const memoryDir = adapterMemoryDir
+        ? resolveAgainst(projectDir, adapterMemoryDir)
+        : fallbackMemoryDir;
+    // Collect candidate files
+    const candidates = [];
+    // 1. Project-level instruction files
+    if (projectDir) {
+        for (const fileName of instructionFiles) {
+            const p = join(projectDir, fileName);
+            if (existsSync(p)) {
+                candidates.push({ path: p, label: `project/${fileName}` });
+            }
+        }
+    }
+    // 2. User-level instruction files (skip when configDir resolves to the
+    //    project root — already covered by step 1, would emit dup labels).
+    if (effectiveConfigDir && effectiveConfigDir !== projectDir) {
+        for (const fileName of instructionFiles) {
+            const p = join(effectiveConfigDir, fileName);
+            if (existsSync(p)) {
+                candidates.push({ path: p, label: `user/${fileName}` });
+            }
+        }
+    }
+    // 3. Memory directory
+    if (memoryDir && existsSync(memoryDir)) {
+        try {
+            const files = readdirSync(memoryDir).filter(f => f.endsWith(".md"));
+            for (const file of files) {
+                candidates.push({
+                    path: join(memoryDir, file),
+                    label: `memory/${file}`,
+                });
+            }
+        }
+        catch (e) {
+            if (DEBUG)
+                process.stderr.write(`[ctx] auto-memory dir scan failed: ${e}\n`);
+        }
+    }
+    // Search each candidate file for matching queries
+    for (const candidate of candidates) {
+        if (results.length >= limit)
+            break;
+        try {
+            // Single stat for both size guard and timestamp — saves one syscall
+            // per candidate file. Cross-platform: statSync semantics identical
+            // on macOS / Linux / Windows; size+mtime read in the same inode probe.
+            let stat;
+            try {
+                stat = statSync(candidate.path);
+                if (stat.size > 1_000_000)
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const content = readFileSync(candidate.path, "utf-8");
+            const contentLower = content.toLowerCase();
+            for (const query of queries) {
+                if (results.length >= limit)
+                    break;
+                const queryLower = query.toLowerCase();
+                // Split query into terms, match if any term is found
+                const terms = queryLower.split(/\s+/).filter(t => t.length >= 3);
+                const matched = terms.some(term => {
+                    try {
+                        return new RegExp(`\\b${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, "i").test(content);
+                    }
+                    catch {
+                        return contentLower.includes(term); // fallback for invalid regex
+                    }
+                });
+                if (matched) {
+                    // Extract a relevant section around the first match
+                    const firstTermIdx = terms.reduce((best, term) => {
+                        const idx = contentLower.indexOf(term);
+                        return idx >= 0 && (best < 0 || idx < best) ? idx : best;
+                    }, -1);
+                    let start = Math.max(0, firstTermIdx - 200);
+                    let end = Math.min(content.length, firstTermIdx + 500);
+                    const prevBlank = content.lastIndexOf("\n\n", start);
+                    const nextBlank = content.indexOf("\n\n", end);
+                    if (prevBlank >= 0)
+                        start = prevBlank + 2;
+                    if (nextBlank >= 0)
+                        end = nextBlank;
+                    const snippet = content.slice(start, end).trim();
+                    results.push({
+                        title: `[auto-memory] ${candidate.label}`,
+                        content: snippet,
+                        source: candidate.label,
+                        origin: "auto-memory",
+                        timestamp: stat.mtime.toISOString(),
+                    });
+                    break; // one result per file per query batch
+                }
+            }
+        }
+        catch (e) {
+            if (DEBUG)
+                process.stderr.write(`[ctx] auto-memory file read failed: ${e}\n`);
+        }
+    }
+    return results.slice(0, limit);
+}
+/**
+ * Resolve a possibly-relative path (e.g. ".github", "memory") against a
+ * project directory. Absolute paths and empty strings are returned as-is
+ * (empty == "use projectDir directly").
+ */
+function resolveAgainst(projectDir, p) {
+    if (!p)
+        return projectDir ?? "";
+    if (isAbsolute(p))
+        return p;
+    if (!projectDir)
+        return p;
+    return join(projectDir, p);
+}

package/build/search/ctx-search-schema.d.ts

@@ -0,0 +1,90 @@
+/**
+ * ctx_search input-schema builder and project-scope resolver.
+ *
+ * Issue #737 introduces the optional `project:` parameter used by callers
+ * running in the shared-DB mode (`CONTEXT_MODE_PROJECT_DIR` is set). The
+ * field is registered conditionally so that in the default per-project DB
+ * mode the LLM physically cannot pass it — the parameter does not exist
+ * in the tool schema at all, which is a stronger guarantee than runtime
+ * validation that depends on the model honouring documentation.
+ *
+ * The handler in `src/server.ts` consumes both exports:
+ *   - {@link buildCtxSearchInputSchema} composes the Zod object used at
+ *     `registerTool` time, spreading the conditional `project` field only
+ *     when `isSharedMode` is true.
+ *   - {@link resolveProjectScope} normalises the raw param into the
+ *     three-state contract consumed by `searchAllSources`:
+ *       undefined → no filter
+ *       null      → explicit cross-project recall (no filter)
+ *       string    → restrict to that project directory
+ */
+import { z } from "zod";
+/**
+ * Build the Zod object passed to `server.registerTool("ctx_search", …)`.
+ *
+ * The base fields (`queries`, `limit`, `source`, `contentType`, `sort`)
+ * are always present and mirror today's contract exactly. The `project`
+ * field is only spread in when `isSharedMode` is true. When the host runs
+ * with the default per-project DB layout the schema does not expose the
+ * field at all, which keeps the tool surface honest about what is
+ * actionable in that mode.
+ */
+export declare function buildCtxSearchInputSchema(isSharedMode: boolean): z.ZodObject<{
+    queries: z.ZodEffects<z.ZodOptional<z.ZodArray<z.ZodString, "many">>, string[] | undefined, unknown>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    source: z.ZodOptional<z.ZodString>;
+    contentType: z.ZodOptional<z.ZodEnum<["code", "prose"]>>;
+    sort: z.ZodDefault<z.ZodOptional<z.ZodEnum<["relevance", "timeline"]>>>;
+} | {
+    project: z.ZodOptional<z.ZodString>;
+    queries: z.ZodEffects<z.ZodOptional<z.ZodArray<z.ZodString, "many">>, string[] | undefined, unknown>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    source: z.ZodOptional<z.ZodString>;
+    contentType: z.ZodOptional<z.ZodEnum<["code", "prose"]>>;
+    sort: z.ZodDefault<z.ZodOptional<z.ZodEnum<["relevance", "timeline"]>>>;
+}, "strip", z.ZodTypeAny, {
+    sort: "relevance" | "timeline";
+    limit: number;
+    source?: string | undefined;
+    contentType?: "code" | "prose" | undefined;
+    queries?: string[] | undefined;
+} | {
+    sort: "relevance" | "timeline";
+    limit: number;
+    source?: string | undefined;
+    contentType?: "code" | "prose" | undefined;
+    queries?: string[] | undefined;
+    project?: unknown;
+}, {
+    sort?: "relevance" | "timeline" | undefined;
+    source?: string | undefined;
+    limit?: number | undefined;
+    contentType?: "code" | "prose" | undefined;
+    queries?: unknown;
+} | {
+    sort?: "relevance" | "timeline" | undefined;
+    source?: string | undefined;
+    limit?: number | undefined;
+    contentType?: "code" | "prose" | undefined;
+    queries?: unknown;
+    project?: unknown;
+}>;
+/**
+ * Normalise the raw `project` value into the three-state contract consumed
+ * by {@link searchAllSources}.
+ *
+ *   - shared mode OFF                        → `undefined` (param ignored)
+ *   - shared mode ON, param `undefined`      → current project (`getProjectDirFn()`)
+ *   - shared mode ON, param `"global"`       → `null` (no filter — cross-project)
+ *   - shared mode ON, param `<string>`       → that string verbatim
+ *
+ * The function is pure so it stays trivially testable without spinning up
+ * the MCP server.
+ */
+export declare function resolveProjectScope(raw: string | undefined, isSharedMode: boolean, getProjectDirFn: () => string): string | null | undefined;
+/**
+ * Module-load snapshot of `CONTEXT_MODE_PROJECT_DIR`. Captured once so the
+ * tool schema registered with `server.registerTool` reflects the launch
+ * environment — the LLM-visible surface should never flip mid-session.
+ */
+export declare const CTX_SEARCH_SHARED_MODE: boolean;

package/build/search/ctx-search-schema.js

@@ -0,0 +1,135 @@
+/**
+ * ctx_search input-schema builder and project-scope resolver.
+ *
+ * Issue #737 introduces the optional `project:` parameter used by callers
+ * running in the shared-DB mode (`CONTEXT_MODE_PROJECT_DIR` is set). The
+ * field is registered conditionally so that in the default per-project DB
+ * mode the LLM physically cannot pass it — the parameter does not exist
+ * in the tool schema at all, which is a stronger guarantee than runtime
+ * validation that depends on the model honouring documentation.
+ *
+ * The handler in `src/server.ts` consumes both exports:
+ *   - {@link buildCtxSearchInputSchema} composes the Zod object used at
+ *     `registerTool` time, spreading the conditional `project` field only
+ *     when `isSharedMode` is true.
+ *   - {@link resolveProjectScope} normalises the raw param into the
+ *     three-state contract consumed by `searchAllSources`:
+ *       undefined → no filter
+ *       null      → explicit cross-project recall (no filter)
+ *       string    → restrict to that project directory
+ */
+import { z } from "zod";
+/**
+ * Helper that mirrors the Zod coercer used elsewhere in the server for
+ * array-shaped tool args. Kept inline so this module has no runtime
+ * dependency on `server.ts` (which would create a cycle).
+ *
+ * Behaviour mirrors `coerceJsonArray` in `server.ts`:
+ *   1. Empty / whitespace string → returned untouched so Zod surfaces the
+ *      "non-empty" error rather than masquerading as `[""]`.
+ *   2. Valid JSON array string → parsed and returned.
+ *   3. Any other plain string (a bare single query) → lifted to a
+ *      single-element array. Fixes #627 for the native OpenCode plugin
+ *      path where some providers deliver `queries: "search term"`.
+ */
+function coerceJsonArray(val) {
+    if (typeof val === "string") {
+        const trimmed = val.trim();
+        if (trimmed.length === 0)
+            return val;
+        try {
+            const parsed = JSON.parse(val);
+            if (Array.isArray(parsed))
+                return parsed;
+        }
+        catch {
+            /* fall through — not JSON, treat as bare-string lift */
+        }
+        return [val];
+    }
+    return val;
+}
+/**
+ * Build the Zod object passed to `server.registerTool("ctx_search", …)`.
+ *
+ * The base fields (`queries`, `limit`, `source`, `contentType`, `sort`)
+ * are always present and mirror today's contract exactly. The `project`
+ * field is only spread in when `isSharedMode` is true. When the host runs
+ * with the default per-project DB layout the schema does not expose the
+ * field at all, which keeps the tool surface honest about what is
+ * actionable in that mode.
+ */
+export function buildCtxSearchInputSchema(isSharedMode) {
+    const projectField = isSharedMode
+        ? {
+            project: z
+                .string()
+                .optional()
+                .describe("Project scope. " +
+                "Default (omit): this session's project — auto-resolved from the host adapter. " +
+                "'global': span every project in the shared store (cross-project recall). " +
+                "<absolute-path>: scope to that specific project directory."),
+        }
+        : {};
+    return z.object({
+        queries: z.preprocess(coerceJsonArray, z
+            .array(z.string())
+            .optional()
+            .describe("Array of search queries. Batch ALL questions in one call.")),
+        // limit: z.coerce.number() (not z.number()) — OpenCode's native
+        // plugin path delivers tool args straight from the LLM provider's
+        // tool-call JSON, where several providers stringify primitives
+        // (limit:"4" instead of limit:4). Since v1.0.139 / #621 we run
+        // inputSchema.parse() on that path, so a plain z.number() rejects
+        // "4" with "Expected number, received string". z.coerce mirrors what
+        // ctx_batch_execute / ctx_fetch_and_index / ctx_execute already do.
+        // Fixes #627.
+        limit: z
+            .coerce.number()
+            .optional()
+            .default(3)
+            .describe("Results per query (default: 3)"),
+        source: z
+            .string()
+            .optional()
+            .describe("Filter to a specific indexed source (partial match)."),
+        contentType: z
+            .enum(["code", "prose"])
+            .optional()
+            .describe("Filter results by content type: 'code' or 'prose'."),
+        sort: z
+            .enum(["relevance", "timeline"])
+            .optional()
+            .default("relevance")
+            .describe("Sort mode. 'relevance' (default): BM25 ranked, current session only. " +
+            "'timeline': chronological across current session, prior sessions, and auto-memory."),
+        ...projectField,
+    });
+}
+/**
+ * Normalise the raw `project` value into the three-state contract consumed
+ * by {@link searchAllSources}.
+ *
+ *   - shared mode OFF                        → `undefined` (param ignored)
+ *   - shared mode ON, param `undefined`      → current project (`getProjectDirFn()`)
+ *   - shared mode ON, param `"global"`       → `null` (no filter — cross-project)
+ *   - shared mode ON, param `<string>`       → that string verbatim
+ *
+ * The function is pure so it stays trivially testable without spinning up
+ * the MCP server.
+ */
+export function resolveProjectScope(raw, isSharedMode, getProjectDirFn) {
+    if (!isSharedMode)
+        return undefined;
+    if (raw === undefined)
+        return getProjectDirFn();
+    if (raw === "global")
+        return null;
+    return raw;
+}
+/**
+ * Module-load snapshot of `CONTEXT_MODE_PROJECT_DIR`. Captured once so the
+ * tool schema registered with `server.registerTool` reflects the launch
+ * environment — the LLM-visible surface should never flip mid-session.
+ */
+export const CTX_SEARCH_SHARED_MODE = !!process.env.CONTEXT_MODE_PROJECT_DIR;

package/build/search/flood-guard.d.ts

@@ -0,0 +1,57 @@
+/**
+ * ctx_search flood-guard — per-agent-context progressive throttle.
+ *
+ * Background (#79 / #155 / #697): ctx_search carries a progressive throttle
+ * so a single actor cannot spam dozens of individual searches and flood the
+ * context window instead of batching via ctx_batch_execute. The original
+ * implementation kept ONE module-global counter on the MCP server process.
+ *
+ * Issue #769: a parallel multi-agent fan-out (Claude Code Task/Workflow)
+ * runs N subagents concurrently against the SAME per-session MCP server
+ * process. With a single global counter their independent calls are summed
+ * into one budget, so legitimate fan-out ("10 agents x 2 calls") trips the
+ * guard that was only ever meant to catch ONE actor spamming. The budget is
+ * tool-availability state that is logically per-agent-context, so the counter
+ * must be keyed per agent-context — NOT removed. Single-actor flood
+ * protection is preserved exactly; only the bucketing changes.
+ *
+ * This module is pure and transport-free so the policy is unit-testable
+ * without spinning up the MCP server. `src/server.ts` owns the singleton and
+ * supplies the per-call agent key (the session/agent id from
+ * currentAttribution()).
+ */
+export interface FloodGuardConfig {
+    /** Rolling window length in ms. After this elapses a key's counter resets. */
+    windowMs: number;
+    /** After this many calls in the window, results taper to 1 per query. */
+    softCapAfter: number;
+    /** After this many calls in the window, the call is hard-blocked. */
+    blockAfter: number;
+}
+export interface FloodDecision {
+    /** This key's call count within the current rolling window (1-based). */
+    count: number;
+    /** Window start timestamp (ms) for this key — used for the "in Ns" message. */
+    windowStart: number;
+    /** True once count exceeds blockAfter — caller must refuse the search. */
+    blocked: boolean;
+    /** True once count exceeds softCapAfter — caller trims to 1 result/query. */
+    softCapped: boolean;
+}
+/**
+ * A rolling-window call counter bucketed per agent-context key. Each key gets
+ * an independent window + counter, so concurrent subagents do not consume one
+ * another's budget while a single greedy actor is still throttled and blocked
+ * exactly as before.
+ */
+export declare class FloodGuard {
+    #private;
+    constructor(cfg: FloodGuardConfig, maxKeys?: number);
+    /**
+     * Record one ctx_search call for `key` at time `now` (ms) and return the
+     * throttle decision. Pure aside from the internal per-key counter state.
+     */
+    record(key: string, now?: number): FloodDecision;
+    /** Test/diagnostics helper — number of distinct keys currently tracked. */
+    size(): number;
+}

package/build/search/flood-guard.js

@@ -0,0 +1,80 @@
+/**
+ * ctx_search flood-guard — per-agent-context progressive throttle.
+ *
+ * Background (#79 / #155 / #697): ctx_search carries a progressive throttle
+ * so a single actor cannot spam dozens of individual searches and flood the
+ * context window instead of batching via ctx_batch_execute. The original
+ * implementation kept ONE module-global counter on the MCP server process.
+ *
+ * Issue #769: a parallel multi-agent fan-out (Claude Code Task/Workflow)
+ * runs N subagents concurrently against the SAME per-session MCP server
+ * process. With a single global counter their independent calls are summed
+ * into one budget, so legitimate fan-out ("10 agents x 2 calls") trips the
+ * guard that was only ever meant to catch ONE actor spamming. The budget is
+ * tool-availability state that is logically per-agent-context, so the counter
+ * must be keyed per agent-context — NOT removed. Single-actor flood
+ * protection is preserved exactly; only the bucketing changes.
+ *
+ * This module is pure and transport-free so the policy is unit-testable
+ * without spinning up the MCP server. `src/server.ts` owns the singleton and
+ * supplies the per-call agent key (the session/agent id from
+ * currentAttribution()).
+ */
+/**
+ * A rolling-window call counter bucketed per agent-context key. Each key gets
+ * an independent window + counter, so concurrent subagents do not consume one
+ * another's budget while a single greedy actor is still throttled and blocked
+ * exactly as before.
+ */
+export class FloodGuard {
+    #cfg;
+    #buckets = new Map();
+    /**
+     * Hard ceiling on tracked keys — a defensive bound so a pathological host
+     * that mints unbounded distinct agent ids cannot grow the map without limit.
+     * When exceeded, the oldest-window bucket is evicted (its actor simply gets
+     * a fresh window on its next call — fail-open, never a false block).
+     */
+    #maxKeys;
+    constructor(cfg, maxKeys = 4096) {
+        this.#cfg = cfg;
+        this.#maxKeys = Math.max(1, maxKeys);
+    }
+    /**
+     * Record one ctx_search call for `key` at time `now` (ms) and return the
+     * throttle decision. Pure aside from the internal per-key counter state.
+     */
+    record(key, now = Date.now()) {
+        let bucket = this.#buckets.get(key);
+        if (!bucket || now - bucket.windowStart > this.#cfg.windowMs) {
+            bucket = { count: 0, windowStart: now };
+            this.#buckets.set(key, bucket);
+            this.#evictIfNeeded();
+        }
+        bucket.count++;
+        return {
+            count: bucket.count,
+            windowStart: bucket.windowStart,
+            blocked: bucket.count > this.#cfg.blockAfter,
+            softCapped: bucket.count > this.#cfg.softCapAfter,
+        };
+    }
+    /** Test/diagnostics helper — number of distinct keys currently tracked. */
+    size() {
+        return this.#buckets.size;
+    }
+    #evictIfNeeded() {
+        if (this.#buckets.size <= this.#maxKeys)
+            return;
+        let oldestKey;
+        let oldestStart = Infinity;
+        for (const [k, b] of this.#buckets) {
+            if (b.windowStart < oldestStart) {
+                oldestStart = b.windowStart;
+                oldestKey = k;
+            }
+        }
+        if (oldestKey !== undefined)
+            this.#buckets.delete(oldestKey);
+    }
+}

package/build/search/unified.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Unified multi-source search — merges ContentStore, SessionDB, and
+ * auto-memory results into a single ranked or chronological result set.
+ *
+ * Used by ctx_search when sort="timeline" to search across all sources,
+ * or sort="relevance" (default) for ContentStore-only BM25 search.
+ */
+import type { ContentStore } from "../store.js";
+import type { SessionDB } from "../session/db.js";
+import { type AutoMemoryAdapter } from "./auto-memory.js";
+export interface UnifiedSearchResult {
+    title: string;
+    content: string;
+    source: string;
+    origin: "current-session" | "prior-session" | "auto-memory";
+    timestamp?: string;
+    rank?: number;
+    matchLayer?: string;
+    highlighted?: string;
+    contentType?: "code" | "prose";
+}
+export interface SearchAllSourcesOpts {
+    query: string;
+    limit: number;
+    store: ContentStore;
+    sort?: "relevance" | "timeline";
+    source?: string;
+    contentType?: "code" | "prose";
+    sessionDB?: SessionDB | null;
+    projectDir?: string;
+    configDir?: string;
+    /** Detected platform adapter — used for adapter-aware auto-memory. */
+    adapter?: AutoMemoryAdapter;
+    /**
+     * Per-project scope for the ContentStore filter (#737). Only honoured
+     * when a `sessionDB` is also supplied (the 2-step IN-clause needs the
+     * SessionDB to translate `project_dir` → list of session ids).
+     *
+     *   - `undefined` — no project filter, today's behaviour.
+     *   - `null`      — cross-project recall in shared-DB mode (also no filter).
+     *   - `string`    — restrict ContentStore results to chunks attributed to
+     *                   session ids whose events match this `project_dir`,
+     *                   plus legacy `session_id=''` chunks (public surface).
+     */
+    projectScope?: string | null;
+}
+/**
+ * Search across all available sources.
+ *
+ * - sort="relevance" (default): BM25-ranked results from ContentStore only.
+ * - sort="timeline": chronological merge of ContentStore + SessionDB + auto-memory.
+ *
+ * Errors in any single source are caught and logged — partial results
+ * are always returned.
+ */
+export declare function searchAllSources(opts: SearchAllSourcesOpts): UnifiedSearchResult[];