memorix 1.9.0 → 1.9.2

package/docs/CONFIGURATION.md

@@ -195,6 +195,28 @@ OpenAI-only default. The equivalent env-var form is
 `MEMORIX_EMBEDDING=api`, `MEMORIX_EMBEDDING_BASE_URL=https://openrouter.ai/api/v1`,
 `MEMORIX_EMBEDDING_MODEL=qwen/qwen3-embedding-8b`.
 
+### Large-store retrieval
+
+Memorix does not cap the number of durable observations to make search fast.
+For a large store, the runtime keeps the complete records in SQLite and uses
+derived indexes for bounded candidate retrieval. The optional LanceDB package
+is installed with the package's optional dependencies and loaded only at
+runtime; if its native binary is unavailable, SQLite FTS5 and the Orama
+fallback continue to work.
+
+```text
+MEMORIX_ORAMA_HYDRATION_THRESHOLD=10000   # working-set switch, not a quota
+MEMORIX_SEMANTIC_INDEX=auto               # auto | off | orama
+MEMORIX_SEMANTIC_INDEX_THRESHOLD=10000    # train ANN index after this many vectors
+```
+
+`MEMORIX_SEMANTIC_INDEX=auto` enables the local LanceDB shadow index when the
+optional native package is available. It stores vector IDs and filter metadata,
+while full memory text remains in SQLite. The semantic index uses HNSW with
+scalar quantization after its threshold is reached; before that, its table is
+still searchable without a training step. The derived index can be deleted and
+recreated by the background vector backfill without affecting durable memories.
+
 ### `[rerank]`
 
 Optional HTTP rerank for thorough search. Off by default.

package/docs/DEVELOPMENT.md

@@ -8,12 +8,12 @@ Memorix is a TypeScript project built around:
 - memcode bundled terminal-agent runtime
 - CLI workflows
 - SQLite canonical persistence with compatibility/fallback layers
-- Orama search
+- layered retrieval: SQLite FTS5, optional LanceDB semantic index, and Orama fallback
 - dashboard and HTTP service
 
 ## Current Development Baseline
 
-The current release line is **1.9.0** and package metadata is kept synchronized
+The current release line is **1.9.1** and package metadata is kept synchronized
 with the root package and MCP Registry manifest.
 
 Contributors should assume the following areas are part of the current release line:

package/docs/INTEGRATIONS.md

@@ -122,6 +122,10 @@ If an agent only needs a raw stdio MCP entry:
 
 Avoid `npx` in persistent MCP configs. Use the globally installed `memorix` binary so startup is predictable.
 
+For npm-based MCP clients or registry testers, the complete package command is
+`npx -y memorix serve`. Do not omit `serve`: bare `memorix` is the interactive
+memcode entry in a human terminal.
+
 For HTTP mode:
 
 ```bash

package/docs/PERFORMANCE.md

@@ -12,7 +12,10 @@ Memorix is designed to be light for everyday memory use and explicit about heavi
 | `memorix` | Interactive terminal UI | Human operator workbench |
 | `memorix orchestrate` | Supervisor plus spawned CLI agent workers | Orchestrated subagent loops |
 
-The default memory path uses local SQLite as the canonical store and Orama for search/indexing. No cloud service is required.
+The default memory path uses local SQLite as the canonical store. Orama remains
+the in-process compatibility/semantic fallback; large corpora use SQLite FTS5
+and, when available, the local LanceDB semantic shadow index. No cloud service
+is required.
 
 ## Resource Safety Model
 
@@ -66,11 +69,11 @@ project-scoped tools (`memorix_project_context`, `memorix_context_pack`,
 CodeGraph Memory directly, so a new agent can get a useful brief without
 waiting for unrelated historical records to hydrate into Orama.
 
-Search, writes, and session operations still wait for the in-process retrieval
-runtime when they need it. Corpus-scale retention, consolidation, and Code
-Memory refresh are queued durably and run in an isolated child process. Vector
-backfill stays with the owning process because the Orama index is local to that
-process.
+Search and ordinary writes use the durable SQLite path directly when the
+persistent indexes are available. Corpus-scale retention, consolidation, and
+Code Memory refresh are queued durably and run in an isolated child process.
+Vector backfill updates the persistent semantic shadow index and keeps Orama as
+the compatibility fallback.
 
 ## What Is Lightweight
 
@@ -105,6 +108,9 @@ On the release development machine used for this check, the healthy HTTP service
 | `MEMORIX_RERANK_PROVIDER` | `off` | Set `http` to enable optional HTTP rerank |
 | `MEMORIX_RERANK_BASE_URL` | `[memory.llm].base_url` | Compatible `/rerank` API root (path `/rerank` is appended) |
 | `MEMORIX_EMBEDDING_CACHE_MAX_BYTES` | `268435456` | Disposable in-process API-vector cache budget; raise for large warm caches, or lower when the host is memory constrained |
+| `MEMORIX_ORAMA_HYDRATION_THRESHOLD` | `10000` | Above this durable corpus size, skip full Orama hydration and use persistent SQLite/semantic indexes; this is a working-set threshold, not a memory quota |
+| `MEMORIX_SEMANTIC_INDEX` | `auto` | `auto` uses the optional local LanceDB shadow index when installed; `off` or `orama` keeps the legacy semantic path |
+| `MEMORIX_SEMANTIC_INDEX_THRESHOLD` | `10000` | Minimum vectors before the optional HNSW/SQ index is trained; vectors remain searchable before training |
 | `memorix memory search --quality fast` | n/a | Force a fully local retrieval path for a latency-sensitive call |
 | `npm run benchmark:retrieval -- --records 1000 --runs 100` | n/a | Reproduce hot in-process lexical retrieval latency; not an end-to-end claim |
 | `npm run gate:large-store -- --records 40000` | n/a | Exercise SDK, HTTP MCP, hook persistence, cache integrity, and reopen behavior against a large isolated store |
@@ -130,6 +136,10 @@ On the release development machine used for this check, the healthy HTTP service
   rising `rss` with stable heap, or rising V8 `heapUsed`; those indicate
   different classes of problem and should not be “fixed” by lowering the
   memory corpus limit.
+- When a corpus crosses `MEMORIX_ORAMA_HYDRATION_THRESHOLD`, the complete
+  durable corpus remains in SQLite. Only the per-query candidate set is loaded
+  into the agent process. Management actions such as export, retention, and
+  detail views may intentionally load the requested full/project slice.
 
 ## Large-Store Release Gate
 
@@ -143,22 +153,69 @@ report fails when an interactive path exceeds its release budget. It also
 verifies that the personal hook candidate remains durable on disk without
 becoming visible to an unbound SDK reader.
 
-Startup hydration uses bounded Orama batches. This keeps HTTP health responsive
-while avoiding a full index rebalance for every persisted observation. The MCP
-search number is intentionally a cold control-plane measurement: it includes
-any lexical hydration the fresh service still owes before its first search.
+Small stores may use bounded Orama batches. Large stores skip that hydration and
+use the persistent FTS5 path immediately; the optional semantic shadow index is
+opened independently. The MCP search number is intentionally a cold
+control-plane measurement and includes only the work still owed by the selected
+derived indexes.
 
 Results are machine-specific and should be compared on the same OS and Node
 version. The release gate is an integrity and regression check, not a public
 latency guarantee.
 
-## Current Optimization Opportunities
-
-These are not release blockers, but they are reasonable future improvements:
-
-- Extend the retrieval benchmark with separately labelled cold CLI, MCP, and remote-provider cases when a release needs those comparisons.
-- Add dashboard-side performance telemetry for API latency and payload sizes.
-- Document recommended retention schedules for large projects.
-- Evaluate a persistent cross-process retrieval index only as a major-version
-  architecture change; Orama is intentionally process-local today.
-- Explore slimmer Docker layers if image size becomes a common pain point.
+## 1.9.1 Large-Scale Retrieval Contract
+
+The 1.9.1 line improves retrieval latency without shrinking the user's durable
+memory corpus. SQLite remains the source of truth. Search indexes are derived,
+rebuildable working structures, following the same boundary used by mature
+memory systems that keep human-readable or durable records separate from their
+vector/lexical indexes.
+
+The release contract is:
+
+1. A normal lexical or exact-identifier query must be able to use a persistent
+   SQLite FTS5 index and fetch only bounded candidates. It must not require
+   hydrating every observation into Orama first.
+2. FTS5 must be feature-detected. Older or degraded SQLite runtimes fall back
+   to the existing Orama path without losing data or changing write semantics.
+3. Inserts, updates, deletes, imports, and sync applies must keep the derived
+   lexical index current. A rebuild command/test path must repair it after an
+   interrupted migration or manual database recovery.
+4. Candidate generation, graph/code references, and optional reranking must be
+   separately measurable. Reranking is applied only to a small candidate set;
+   it must never scan or send the whole corpus to a provider.
+5. No durable observation count, retention rule, or user-facing memory quota is
+   introduced by this work. Limits apply only to per-query candidates, caches,
+   and concurrent maintenance work.
+6. Large-store acceptance must report cold start, warm search, MCP search, RSS,
+   heap, index mode, result integrity, and recall of planted records at 1k,
+   10k, 40k, and 100k records. A slower machine is evidence to report, not a
+   reason to quietly lower the corpus size.
+
+The implementation target is SQLite FTS5 plus an optional local LanceDB shadow
+index. LanceDB stores only vector IDs and filter metadata, and is loaded at
+runtime so the main package still builds on platforms where its native binary
+is unavailable. HNSW with scalar quantization is trained only after the vector
+table crosses the semantic-index threshold; before that, the table remains
+queryable without paying a large training spike. Orama remains the compatibility
+fallback. A server-only vector database is not a default dependency for the
+local-first product.
+
+The retrieval shape is:
+
+```text
+SQLite observations (durable truth)
+  -> FTS5 exact/lexical candidates
+  -> optional vector candidates
+  -> optional CodeGraph/knowledge candidates
+  -> rank fusion
+  -> optional rerank on the short list
+  -> compact result IDs, then detail on demand
+```
+
+Measured Windows/Node 22 evidence for this implementation: 1k, 10k, 40k, and
+100k records all passed the large-store gate. At 100k, peak RSS was about
+419MB, SDK reopen was about 131ms, and the cold HTTP MCP search was about
+296ms. These are same-machine acceptance numbers, not universal latency
+promises. The release is complete only when the measurements and fallback
+behavior remain recorded alongside the implementation.

package/docs/README.md

@@ -125,7 +125,7 @@ Historical/deep-reference documents may describe older designs. If they conflict
 
 ## Current Product Line
 
-The current product line is **1.9.0**. Multi-device store sync is opt-in and
+The current product line is **1.9.1**. Multi-device store sync is opt-in and
 keeps local SQLite canonical; existing users do not upload anything until they
 configure a relay provider explicitly.
 The authoritative acceptance contract for the current implementation is

package/docs/SETUP.md

@@ -170,6 +170,11 @@ Generic stdio MCP config:
 
 Avoid `npx` in persistent MCP configs. Use the globally installed `memorix` binary so startup is predictable.
 
+When an npm-based MCP client or registry tester must launch the package
+directly, use `npx -y memorix serve`. The explicit `serve` argument selects
+the stdio MCP server; a human running bare `memorix` in a terminal gets the
+bundled memcode agent instead.
+
 ### Option C: memcode terminal agent
 
 ```bash

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorix",
   "mcpName": "io.github.AVIDS2/memorix",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "Local-first shared memory layer for AI coding agents across MCP clients, Git history, reasoning context, and project sessions.",
   "type": "module",
   "sideEffects": false,
@@ -77,7 +77,6 @@
     "benchmark:codegraph:scale": "node scripts/benchmark-codegraph-scale.mjs",
     "benchmark:retrieval": "npm run build && node scripts/benchmark-retrieval.mjs",
     "gate:large-store": "npm run build && node scripts/large-store-gate.mjs",
-    "generate:star-history": "node scripts/generate-star-history.mjs",
     "sync:mcp-registry": "node scripts/sync-mcp-registry-manifest.mjs",
     "check:mcp-registry": "node scripts/check-mcp-registry-manifest.mjs",
     "sync:plugin-release": "node scripts/sync-plugin-release-manifests.mjs",
@@ -155,6 +154,7 @@
     "zod": "^3.24.0"
   },
   "optionalDependencies": {
+    "@lancedb/lancedb": "^0.38.0",
     "better-sqlite3": "^12.11.1"
   },
   "overrides": {

package/plugins/antigravity/memorix/plugin.json

@@ -1,4 +1,4 @@
 {
   "name": "memorix",
-  "version": "1.9.0"
+  "version": "1.9.2"
 }

package/plugins/claude/memorix/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "memorix",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "Shared workspace memory for Claude Code and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codebuddy/memorix/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "Local-first project memory for CodeBuddy Code and other coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codex/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "Shared workspace memory for Codex and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/copilot/memorix/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "Shared local workspace memory for GitHub Copilot CLI and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/gemini/memorix/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "mcpServers": {
     "memorix": {
       "command": "memorix",

package/plugins/hermes/memorix/plugin.yaml

@@ -1,5 +1,5 @@
 name: memorix
-version: "1.9.0"
+version: "1.9.2"
 description: Shared workspace memory bridge for Hermes Agent.
 author: AVIDS2
 license: Apache-2.0

package/plugins/omp/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-omp-package",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "Memorix shared workspace memory package for Oh-my-Pi.",
   "license": "Apache-2.0",
   "keywords": [

package/plugins/openclaw/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "Shared workspace memory for OpenClaw and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/pi/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-pi-package",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "Memorix shared workspace memory package for Pi coding agent.",
   "license": "Apache-2.0",
   "keywords": [

package/server.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/AVIDS2/memorix",
     "source": "github"
   },
-  "version": "1.9.0",
+  "version": "1.9.2",
   "websiteUrl": "https://mem.rglens.com",
   "icons": [
     {
@@ -22,7 +22,7 @@
     {
       "registryType": "npm",
       "identifier": "memorix",
-      "version": "1.9.0",
+      "version": "1.9.2",
       "runtimeHint": "npx",
       "packageArguments": [
         {

package/src/cli/commands/memory.ts

@@ -280,7 +280,8 @@ export default defineCommand({
         case 'deduplicate': {
           const query = asStringArg(args.query);
           const dryRun = !!args.dryRun || !!args['dry-run'];
-          const { isLLMEnabled } = await import('../../llm/provider.js');
+          const { initLLM, isLLMEnabled } = await import('../../llm/provider.js');
+          initLLM({ scope: 'memory', projectRoot: project.rootPath });
           if (!isLLMEnabled()) {
             emitResult(
               { project, available: false, usedLLM: false },

package/src/cli/default-mode.ts

@@ -0,0 +1,15 @@
+export interface CliInteractivity {
+  stdinIsTTY?: boolean;
+  stdoutIsTTY?: boolean;
+}
+
+/**
+ * MCP hosts start package commands with piped stdio, while a human terminal
+ * has TTYs on both streams. Keep the friendly memcode default for humans and
+ * make the package safe for registry probes and generic MCP launchers.
+ */
+export function shouldDefaultToMcp(options: CliInteractivity = {}): boolean {
+  const stdinIsTTY = options.stdinIsTTY ?? process.stdin.isTTY;
+  const stdoutIsTTY = options.stdoutIsTTY ?? process.stdout.isTTY;
+  return stdinIsTTY !== true || stdoutIsTTY !== true;
+}

package/src/cli/index.ts

@@ -20,6 +20,7 @@ import { importBundledMemcode } from './memcode-bootstrap.js';
 import { installCliPipeErrorGuard } from './pipe-errors.js';
 import { normalizeCliInvocation } from './invocation.js';
 import { printCliGuideForHelp, renderCliGuide } from './command-guide.js';
+import { shouldDefaultToMcp } from './default-mode.js';
 
 installCliPipeErrorGuard();
 
@@ -327,8 +328,16 @@ const main = defineCommand({
       'background', 'bg', 'bs', 'doctor', 'repair', 'dashboard', 'cleanup', 'purge', 'uninstall', 'orchestrate'];
     if (firstArg && knownSubs.includes(firstArg)) return;
 
-    // No subcommand provided — enter memcode TUI (native coding agent)
+    // No subcommand provided — keep the interactive memcode default for a
+    // human terminal, but make piped package launches an MCP server. Generic
+    // MCP directories and clients commonly execute `npx memorix` without
+    // reading server.json's package arguments.
     if (!firstArg) {
+      if (shouldDefaultToMcp()) {
+        const serve = await import('./commands/serve.js');
+        await serve.default.run?.({ args: {}, rawArgs: [], cmd: serve.default } as any);
+        return;
+      }
       try {
         const { runCli } = await importBundledMemcode();
         await runCli(process.argv.slice(2));

package/src/codegraph/lite-provider.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { readdirSync, readFileSync, statSync, type Dirent } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync, type Dirent } from 'node:fs';
 import { join, relative } from 'node:path';
 import type { CodeEdge, CodeFile, CodeStateSnapshot, CodeSymbol } from './types.js';
 import { collectCodeStateSnapshot } from './code-state.js';
@@ -210,6 +210,14 @@ function resolveMaxFileBytes(value: number | undefined): number {
   return Math.max(1, Math.floor(value!));
 }
 
+function isPythonVirtualenvDir(dir: string): boolean {
+  // PEP 405 virtualenvs place a `pyvenv.cfg` at their root regardless of the
+  // directory name (`.venv`, `.venv-leann`, `env`, uv/poetry envs, ...). Their
+  // `site-packages` trees are large and generated; descending into one can stall
+  // `codegraph refresh`, so skip virtualenvs by this marker rather than by name.
+  return existsSync(join(dir, 'pyvenv.cfg'));
+}
+
 function walk(root: string, exclude: string[], maxFiles: number): string[] {
   const out: string[] = [];
   const visit = (dir: string) => {
@@ -228,6 +236,7 @@ function walk(root: string, exclude: string[], maxFiles: number): string[] {
       if (entry.isDirectory()) {
         if (entry.name === '.git' || entry.name === '.worktrees' || entry.name === '.tmp' || entry.name === 'node_modules') continue;
         if (rel === '.claude/worktrees' || rel.startsWith('.claude/worktrees/')) continue;
+        if (isPythonVirtualenvDir(abs)) continue;
         visit(abs);
         if (out.length >= maxFiles) return;
         continue;

package/src/compact/engine.ts

@@ -71,7 +71,7 @@ export async function compactSearch(options: SearchOptions, surface: RetrievalSu
   formatted: string;
   totalTokens: number;
 }> {
-  await ensureFreshIndex();
+  await ensureFreshIndex({ loadCorpus: false });
   const searchOptions = { ...options, query: normalizeMemoryBrowseQuery(options.query) };
   let entries = (await searchObservations(searchOptions)).map((entry) =>
     entry.projectId || !options.projectId ? entry : { ...entry, projectId: options.projectId },
@@ -102,9 +102,19 @@ export async function compactSearch(options: SearchOptions, surface: RetrievalSu
   let formatted = formatIndexTable(entries, searchOptions.query, !options.projectId, surface);
 
   if (entries.length === 0 && options.projectId) {
-    const allObservations = filterReadableObservations(getAllObservations(), options.reader);
     const projectAliases = new Set(await resolveAliases(options.projectId).catch(() => [options.projectId]));
-    const projectHasStoredMemory = allObservations.some((obs) => obs.projectId && projectAliases.has(obs.projectId));
+    let projectHasStoredMemory = false;
+    try {
+      const store = getObservationStore();
+      projectHasStoredMemory = (await Promise.all(
+        [...projectAliases].filter((projectId): projectId is string => Boolean(projectId)).map((projectId) => store.countByProject(projectId, { status: 'active' })),
+      )).some((count) => count > 0);
+    } catch {
+      const allObservations = filterReadableObservations(getAllObservations(), options.reader);
+      projectHasStoredMemory = allObservations.some((observation) =>
+        observation.projectId !== undefined && projectAliases.has(observation.projectId),
+      );
+    }
     if (!projectHasStoredMemory) {
       formatted =
         options.reader
@@ -115,7 +125,7 @@ export async function compactSearch(options: SearchOptions, surface: RetrievalSu
             `Memories will start appearing after observations, session summaries, hook captures, or git-memory are written.`;
     } else {
       formatted =
-        `No memories found matching "${options.query}".\n\n` +
+        `No memories found for the current query.\n\n` +
         `This project does have stored Memorix memories, but none matched the current query/filter. ` +
         `Try a more specific topic, use /memory status for runtime diagnostics, or ask for recent memory if you want a broad overview.`;
     }

package/src/dashboard/maintenance.ts

@@ -221,6 +221,7 @@ export async function previewConsolidate(context: DashboardMaintenanceContext) {
   const clusters = await findConsolidationCandidates(
     context.projectRoot ?? context.dataDir,
     context.projectId,
+    { store: context.store },
   );
   const payload: ConsolidateTokenPayload = { clusterIds: normalizeClusters(clusters.map((cluster) => cluster.ids)) };
   return {
@@ -248,11 +249,19 @@ export async function executeConsolidate(
   const clusterIds = record.clusterIds.map((ids, index) => payloadIds(ids, `clusterIds[${index}]`));
   const normalized: ConsolidateTokenPayload = { clusterIds: normalizeClusters(clusterIds) };
   verify('consolidate', context.projectId, normalized, token);
-  const current = await findConsolidationCandidates(context.projectRoot ?? context.dataDir, context.projectId);
+  const current = await findConsolidationCandidates(
+    context.projectRoot ?? context.dataDir,
+    context.projectId,
+    { store: context.store },
+  );
   if (JSON.stringify(normalized.clusterIds) !== JSON.stringify(normalizeClusters(current.map((cluster) => cluster.ids)))) {
     throw new DashboardMaintenanceError('Memory changed after the preview. Refresh before consolidating.', 409);
   }
-  const result = await executeConsolidation(context.projectRoot ?? context.dataDir, context.projectId);
+  const result = await executeConsolidation(
+    context.projectRoot ?? context.dataDir,
+    context.projectId,
+    { store: context.store },
+  );
   return { action: 'consolidate', projectId: context.projectId, ...result };
 }
 

package/src/memory/consolidation.ts

@@ -16,7 +16,7 @@
  */
 
 import type { Observation } from '../types.js';
-import { getObservationStore } from '../store/obs-store.js';
+import { getObservationStore, type ObservationStore } from '../store/obs-store.js';
 import { isEligibleForAutomaticDelivery } from './admission.js';
 import { resolveObservationVisibility } from './visibility.js';
 
@@ -108,6 +108,14 @@ interface ConsolidationPage {
   nextCursor?: number;
 }
 
+export interface ConsolidationOptions {
+  threshold?: number;
+  limit?: number;
+  afterId?: number;
+  /** Use a request-scoped store when running inside a multi-project host. */
+  store?: ObservationStore;
+}
+
 function clampBatchSize(limit: number | undefined): number {
   if (!Number.isFinite(limit)) return MAX_BATCH_SIZE;
   return Math.min(MAX_BATCH_SIZE, Math.max(1, Math.floor(limit!)));
@@ -120,10 +128,11 @@ function clampCursor(afterId: number | undefined): number {
 
 async function loadConsolidationPage(
   projectId: string,
-  options: { limit?: number; afterId?: number },
+  options: ConsolidationOptions,
 ): Promise<ConsolidationPage> {
   const limit = clampBatchSize(options.limit);
-  const page = await getObservationStore().loadByProject(projectId, {
+  const store = options.store ?? getObservationStore();
+  const page = await store.loadByProject(projectId, {
     status: 'active',
     afterId: clampCursor(options.afterId),
     limit: limit + 1,
@@ -205,7 +214,7 @@ function findClusters(observations: Observation[], threshold: number): Consolida
 export async function findConsolidationCandidates(
   _projectDir: string,
   projectId: string,
-  opts?: { threshold?: number; limit?: number; afterId?: number },
+  opts?: ConsolidationOptions,
 ): Promise<ConsolidationCluster[]> {
   const threshold = opts?.threshold ?? DEFAULT_SIMILARITY_THRESHOLD;
   const page = await loadConsolidationPage(projectId, opts ?? {});
@@ -224,9 +233,9 @@ export async function findConsolidationCandidates(
 export async function executeConsolidation(
   _projectDir: string,
   projectId: string,
-  opts?: { threshold?: number; limit?: number; afterId?: number },
+  opts?: ConsolidationOptions,
 ): Promise<ConsolidationResult> {
-  const store = getObservationStore();
+  const store = opts?.store ?? getObservationStore();
   const page = await loadConsolidationPage(projectId, opts ?? {});
   const clusters = findClusters(page.observations, opts?.threshold ?? DEFAULT_SIMILARITY_THRESHOLD);
 

package/src/memory/freshness.ts

@@ -90,9 +90,9 @@ export async function reindexMiniSkills(): Promise<number> {
  * Ensure both observations and mini-skills are fresh in the Orama index.
  * Returns true if any data source was refreshed.
  */
-export async function ensureFreshIndex(): Promise<boolean> {
+export async function ensureFreshIndex(options: { loadCorpus?: boolean } = {}): Promise<boolean> {
   let anyStale = false;
-  const obsStale = await ensureFreshObservations();
+  const obsStale = await ensureFreshObservations(options);
   if (obsStale) anyStale = true;
   const skillsStale = await ensureFreshMiniSkills();
   if (skillsStale) anyStale = true;
@@ -108,8 +108,11 @@ export async function ensureFreshIndex(): Promise<boolean> {
  *
  * Phase 3a: replaces withFreshObservations() at all retrieval call sites.
  */
-export async function withFreshIndex<T>(fn: () => T | Promise<T>): Promise<T> {
-  await ensureFreshIndex();
+export async function withFreshIndex<T>(
+  fn: () => T | Promise<T>,
+  options: { loadCorpus?: boolean } = {},
+): Promise<T> {
+  await ensureFreshIndex(options);
   return fn();
 }