diff --git a/README.md b/README.md index 290d56439e..6aa980441e 100644 --- a/README.md +++ b/README.md @@ -866,6 +866,8 @@ Fused with Reciprocal Rank Fusion (RRF, k=60) and session-diversified (max 3 res When a vector index is populated, `mem::search` (behind `memory_recall`) uses the hybrid BM25 + vector ranker. Without embeddings it uses BM25. `smart-search` can additionally fuse structural graph matches when graph data exists, including in keyless mode. Lesson recall runs on a dedicated in-memory BM25 index instead of scanning the whole corpus per query. Superseded memory versions are excluded from every recall path; the version chain keeps their history. +Filtered `memory_recall` expands its ranked candidate window until it fills the requested result limit, exhausts the candidate source, or reaches 1,000 candidates. This bound limits work for queries with many unrelated matches. Results can contain fewer items when qualifying records rank below that budget. + Vectors survive a crash or force-kill. The vector index is saved in buckets at most every `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 minutes). Every vector added or removed in between is also written right away to a small pending log in the state store, and the next start replays it without calling the embedding provider. Each successful save empties the log. For older documents without vectors, `AGENTMEMORY_VECTOR_BACKFILL=all` opts into a bounded backfill at startup, capped by `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500). Keep the opt-in set across restarts to process more documents. See [source and vector recovery](docs/reliability/source-and-vector-recovery.md). `/agentmemory/status` and the viewer show the pending log size and the backfill state. Keyless installs write nothing. BM25 tokenizes Greek, Cyrillic, Hebrew, Arabic, and accented Latin out of the box. For Chinese / Japanese / Korean memories, install the optional segmenters (`npm install @node-rs/jieba tiny-segmenter`) to split CJK runs into word-level tokens; without them, agentmemory soft-falls to whole-run tokenization and prints a one-time hint on stderr. diff --git a/src/functions/search.ts b/src/functions/search.ts index 2c24d076c9..0cf8b28a7a 100644 --- a/src/functions/search.ts +++ b/src/functions/search.ts @@ -1,5 +1,6 @@ import type { IIIClient } from 'iii-sdk' import type { GraphObservationAuthorization } from "./graph-retrieval.js"; +import type { HybridSearchRequest } from "../state/hybrid-search.js"; import type { IndexPersistenceStatus } from "../state/index-persistence.js"; import type { CompressedObservation, Memory, SearchResult, Session } from '../types.js' import { KV } from '../state/schema.js' @@ -33,6 +34,7 @@ type HybridRanker = ( limit: number, targetLayer?: SearchLayer, authorizeGraph?: GraphObservationAuthorization, + request?: HybridSearchRequest, ) => Promise> let hybridRanker: HybridRanker | null = null @@ -761,6 +763,7 @@ export function registerSearchFunction(sdk: IIIClient, kv: StateKV): void { } const targetLayer = data.targetLayer ?? 'all' const MAX_LIMIT = 100 + const MAX_CANDIDATES = 1000 let effectiveLimit = 20 if (data.limit !== undefined) { if (!Number.isInteger(data.limit) || data.limit < 1) { @@ -835,7 +838,7 @@ export function registerSearchFunction(sdk: IIIClient, kv: StateKV): void { // queries return underfilled pages when same-agent matches // rank lower than cross-agent ones in the hybrid score. const filtering = !!(projectFilter || cwdFilter || filterAgentId) - const fetchLimit = filtering ? Math.max(effectiveLimit * 10, 100) : effectiveLimit + let fetchLimit = filtering ? Math.max(effectiveLimit * 10, 100) : effectiveLimit // Hybrid results carry the observation the ranker already loaded, // so the load pass below doesn't refetch every record it just // enriched. @@ -858,33 +861,13 @@ export function registerSearchFunction(sdk: IIIClient, kv: StateKV): void { } return true } - if (hybridRanker) { - try { - const hybrid = await hybridRanker(query, fetchLimit, targetLayer, authorizeGraph) - results = hybrid.map((r) => ({ - obsId: r.observation.id, - sessionId: r.sessionId, - score: r.combinedScore, - observation: r.observation, - layer: r.layer, - })) - } catch (err) { - logger.warn("hybrid ranking failed, falling back to keyword search", { - error: err instanceof Error ? err.message : String(err), - }) - results = idx.search(query, fetchLimit, targetLayer) - } - } else { - results = idx.search(query, fetchLimit, targetLayer) - } - // Resolve session -> project/cwd once per sessionId we touch. - const sessionCache = new Map() + const sessionCache = new Map>() const loadSession = async (sessionId: string): Promise => { if (sessionCache.has(sessionId)) return sessionCache.get(sessionId)! - const s = await kv.get(KV.sessions, sessionId) - sessionCache.set(sessionId, s ?? null) - return s ?? null + const pending = kv.get(KV.sessions, sessionId).then((session) => session ?? null) + sessionCache.set(sessionId, pending) + return pending } const memoryProjectCache = new Map() @@ -896,62 +879,98 @@ export function registerSearchFunction(sdk: IIIClient, kv: StateKV): void { return proj } - // First pass: filter by session (sequential — benefits from session cache). - // Memory entries with a synthetic sessionId take a secondary KV.memories - // path so project filtering works correctly for them too. - // - // When agentId filtering is active we can't cap at effectiveLimit - // here — the second pass (post-load) is what drops cross-agent - // rows, and capping early would underfill the result page. Use - // fetchLimit as the upper bound in that case; the final - // truncation lives at the end of the second pass. - const earlyCap = filterAgentId ? fetchLimit : effectiveLimit - const candidates: typeof results = [] - for (const r of results) { - if (candidates.length >= earlyCap) break - const layer = r.layer ?? idx.layerOf(r.obsId) ?? getSearchResultLayer(r.obsId, r.sessionId) - if (!matchesSearchLayer(r.obsId, r.sessionId, targetLayer, layer)) continue - if (filtering) { - const memoryProject = projectFilter && layer === "memory" - ? await loadMemoryProject(r.obsId) - : null - if (projectFilter && memoryProject !== null && memoryProject !== projectFilter) continue - const session = await loadSession(r.sessionId) - if (session) { - if (projectFilter && memoryProject === null && session.project !== projectFilter) continue - if (cwdFilter && session.cwd !== cwdFilter) continue + const observationCache = new Map>() + const hybridRequest: HybridSearchRequest = {} + let enriched: SearchResult[] = [] + let useHybridRanker = hybridRanker !== null + while (true) { + hybridRequest.candidateCount = undefined + if (useHybridRanker && hybridRanker) { + try { + const hybrid = await hybridRanker(query, fetchLimit, targetLayer, authorizeGraph, hybridRequest) + results = hybrid.map((r) => ({ + obsId: r.observation.id, + sessionId: r.sessionId, + score: r.combinedScore, + observation: r.observation, + layer: r.layer, + })) + } catch (err) { + hybridRequest.candidateCount = undefined + logger.warn("hybrid ranking failed", { + error: err instanceof Error ? err.message : String(err), + }) + if (enriched.length > 0) break + useHybridRanker = false + results = idx.search(query, fetchLimit, targetLayer) } + } else { + results = idx.search(query, fetchLimit, targetLayer) } - candidates.push(r) - } - const obsResults = await Promise.all( - candidates.map(async (r) => { - if (r.observation) return { observation: r.observation, layer: r.layer ?? idx.layerOf(r.obsId) ?? getSearchResultLayer(r.obsId, r.sessionId) } - const obs = await kv - .get(KV.observations(r.sessionId), r.obsId) - .catch(() => null) - if (obs) return { observation: obs, layer: "observation" as const } - const mem = await kv - .get(KV.memories, r.obsId) - .catch(() => null) - return mem ? { observation: memoryToObservation(mem), layer: "memory" as const } : null - }) - ) - const enriched: SearchResult[] = [] - for (let i = 0; i < candidates.length; i++) { - const resolved = obsResults[i] - if (!resolved) continue - const obs = resolved.observation - if (!matchesSearchLayer(obs.id, obs.sessionId, targetLayer, resolved.layer)) continue - if (filterAgentId !== undefined && obs.agentId !== filterAgentId) continue - if (enriched.length >= effectiveLimit) break - enriched.push({ - observation: withoutObservationSource(obs), - layer: resolved.layer, - score: candidates[i].score, - sessionId: candidates[i].sessionId, - }) + enriched = [] + let batchSize = Math.min(10, effectiveLimit) + for (let offset = 0; offset < Math.min(results.length, fetchLimit) && enriched.length < effectiveLimit;) { + const batch = results.slice(offset, Math.min(offset + batchSize, fetchLimit)) + offset += batch.length + const obsResults = await Promise.all( + batch.map(async (r) => { + const layer = r.layer ?? idx.layerOf(r.obsId) ?? getSearchResultLayer(r.obsId, r.sessionId) + if (!matchesSearchLayer(r.obsId, r.sessionId, targetLayer, layer)) return null + if (filtering) { + const memoryProject = projectFilter && layer === "memory" + ? await loadMemoryProject(r.obsId) + : null + if (projectFilter && memoryProject !== null && memoryProject !== projectFilter) return null + const session = projectFilter || cwdFilter ? await loadSession(r.sessionId) : null + if (projectFilter && memoryProject === null && !session) return null + if (cwdFilter && layer === "observation" && !session) return null + if (session) { + if (projectFilter && memoryProject === null && session.project !== projectFilter) return null + if (cwdFilter && session.cwd !== cwdFilter) return null + } + } + + const key = JSON.stringify([r.obsId, r.sessionId]) + let pending = observationCache.get(key) + if (!pending) { + pending = (async () => { + if (r.observation) return { observation: r.observation, layer: r.layer ?? idx.layerOf(r.obsId) ?? getSearchResultLayer(r.obsId, r.sessionId) } + const obs = await kv + .get(KV.observations(r.sessionId), r.obsId) + .catch(() => null) + if (obs) return { observation: obs, layer: "observation" as const } + const mem = await kv + .get(KV.memories, r.obsId) + .catch(() => null) + return mem ? { observation: memoryToObservation(mem), layer: "memory" as const } : null + })() + observationCache.set(key, pending) + } + return pending + }) + ) + for (let i = 0; i < batch.length; i++) { + const resolved = obsResults[i] + if (!resolved) continue + const obs = resolved.observation + if (!matchesSearchLayer(obs.id, obs.sessionId, targetLayer, resolved.layer)) continue + if (filterAgentId !== undefined && obs.agentId !== filterAgentId) continue + if (enriched.length >= effectiveLimit) break + enriched.push({ + observation: withoutObservationSource(obs), + layer: resolved.layer, + score: batch[i].score, + sessionId: batch[i].sessionId, + }) + } + batchSize = Math.min(10, Math.max(effectiveLimit - enriched.length, batchSize * 2)) + } + if (!filtering || enriched.length >= effectiveLimit || (hybridRequest.candidateCount ?? results.length) < fetchLimit || fetchLimit >= MAX_CANDIDATES) break + fetchLimit = Math.min(fetchLimit * 2, MAX_CANDIDATES) } const response = buildRecallResponse(enriched, format as RecallFormat, tokenBudget) diff --git a/src/index.ts b/src/index.ts index e21f3bcfae..0a42b37190 100644 --- a/src/index.ts +++ b/src/index.ts @@ -449,8 +449,8 @@ async function main() { graphWeight, ); - const hybridRanker = (query: string, limit: number, targetLayer?: SearchLayer, authorizeGraph?: Parameters[3]) => - hybridSearch.search(query, limit, targetLayer, authorizeGraph); + const hybridRanker = (query: string, limit: number, targetLayer?: SearchLayer, authorizeGraph?: Parameters[3], request?: Parameters[4]) => + hybridSearch.search(query, limit, targetLayer, authorizeGraph, request); registerSmartSearchFunction(sdk, kv, hybridRanker); setHybridRanker(hybridRanker); registerRecentSearchesSweepFunction(sdk, kv); diff --git a/src/state/hybrid-search.ts b/src/state/hybrid-search.ts index 8a1ed46291..caeb8f03b8 100644 --- a/src/state/hybrid-search.ts +++ b/src/state/hybrid-search.ts @@ -24,6 +24,11 @@ import { logger } from "../logger.js"; const RRF_K = 60; const GRAPH_BUDGET_MS = 500; +export interface HybridSearchRequest { + embedding?: { query: string; value: Promise }; + candidateCount?: number; +} + export class HybridSearch { private graphRetrieval: GraphRetrieval; private lastGraphTimeoutWarningAt = -Infinity; @@ -41,8 +46,8 @@ export class HybridSearch { this.graphRetrieval = new GraphRetrieval(kv, (id) => this.bm25.layerOf(id), (id) => this.bm25.sessionOf(id)); } - async search(query: string, limit = 20, targetLayer: SearchLayer = "all", authorizeGraph?: GraphObservationAuthorization): Promise { - return this.tripleStreamSearch(query, limit, targetLayer, this.graphRetrieval.createQuery(authorizeGraph)); + async search(query: string, limit = 20, targetLayer: SearchLayer = "all", authorizeGraph?: GraphObservationAuthorization, request?: HybridSearchRequest): Promise { + return this.tripleStreamSearch(query, limit, targetLayer, this.graphRetrieval.createQuery(authorizeGraph), undefined, true, request); } async searchWithExpansion( @@ -95,6 +100,7 @@ export class HybridSearch { graphQuery: GraphQuery, entityHints?: string[], applyReranking = true, + request?: HybridSearchRequest, ): Promise { const retrievalLimit = this.rerankEnabled ? Math.max(limit, 20) : limit; const bm25Results = this.bm25.search(query, retrievalLimit * 2, targetLayer); @@ -108,7 +114,20 @@ export class HybridSearch { if (this.vector && this.embeddingProvider && this.vector.size > 0) { try { - queryEmbedding = await this.embeddingProvider.embed(query); + if (request) { + if (!request.embedding || request.embedding.query !== query) { + request.embedding = { query, value: this.embeddingProvider.embed(query) }; + } + const embedding = request.embedding; + try { + queryEmbedding = await embedding.value; + } catch (error) { + if (request.embedding === embedding) request.embedding = undefined; + throw error; + } + } else { + queryEmbedding = await this.embeddingProvider.embed(query); + } vectorResults = this.vector.search(queryEmbedding, retrievalLimit * 2, targetLayer, (id) => this.bm25.layerOf(id)); } catch { // fall through to BM25-only @@ -234,6 +253,7 @@ export class HybridSearch { combinedScore, })); + if (request) request.candidateCount = combined.length; const retrievalDepth = Math.max(limit, 20); const diversified = this.diversifyBySession(combined, retrievalDepth); const enriched = await this.enrichResults(diversified, retrievalDepth); diff --git a/test/hybrid-search.test.ts b/test/hybrid-search.test.ts index 4d921fd1cb..fde7aa2deb 100644 --- a/test/hybrid-search.test.ts +++ b/test/hybrid-search.test.ts @@ -1,5 +1,7 @@ -import { describe, it, expect, beforeEach } from "vitest"; +import { describe, it, expect, beforeEach, vi } from "vitest"; +import { VectorIndex } from "../src/state/vector-index.js"; import { HybridSearch } from "../src/state/hybrid-search.js"; +import { KV } from "../src/state/schema.js"; import { SearchIndex } from "../src/state/search-index.js"; import type { CompressedObservation, EmbeddingProvider } from "../src/types.js"; @@ -52,6 +54,46 @@ describe("HybridSearch", () => { kv = mockKV(); }); + it("reuses query embeddings only within a recall request", async () => { + const obs = makeObs(); + bm25.add(obs); + await kv.set(KV.observations(obs.sessionId), obs.id, obs); + const vector = new VectorIndex(); + vector.add(obs.id, obs.sessionId, new Float32Array([1, 0])); + const embed = vi.fn(async () => new Float32Array([1, 0])); + const provider = { name: "test", dimensions: 2, embed, embedBatch: vi.fn() }; + const hybrid = new HybridSearch(bm25, vector, provider, kv as never, 0.4, 0.6, 0); + const request = {}; + await hybrid.search("auth", 100, "all", undefined, request); + await hybrid.search("auth", 200, "all", undefined, request); + expect(embed).toHaveBeenCalledTimes(1); + await hybrid.search("auth", 100, "all", undefined, {}); + expect(embed).toHaveBeenCalledTimes(2); + }); + + it("retries a failed embedding and then reuses the recovered request embedding", async () => { + const bm25Obs = makeObs({ id: "obs_bm25" }); + const vectorObs = makeObs({ id: "obs_vector" }); + bm25.add(bm25Obs); + await kv.set(KV.observations(bm25Obs.sessionId), bm25Obs.id, bm25Obs); + await kv.set(KV.observations(vectorObs.sessionId), vectorObs.id, vectorObs); + const vector = new VectorIndex(); + vector.add(vectorObs.id, vectorObs.sessionId, new Float32Array([1, 0])); + const embed = vi.fn<() => Promise>() + .mockRejectedValueOnce(new Error("provider unavailable")) + .mockResolvedValue(new Float32Array([1, 0])); + const provider = { name: "test", dimensions: 2, embed, embedBatch: vi.fn() }; + const hybrid = new HybridSearch(bm25, vector, provider, kv as never, 0.4, 0.6, 0); + const request = {}; + const first = await hybrid.search("auth", 100, "all", undefined, request); + expect(first.map((hit) => hit.observation.id)).not.toContain(vectorObs.id); + const recovered = await hybrid.search("auth", 200, "all", undefined, request); + expect(recovered.map((hit) => hit.observation.id)).toContain(vectorObs.id); + expect(embed).toHaveBeenCalledTimes(2); + await hybrid.search("auth", 400, "all", undefined, request); + expect(embed).toHaveBeenCalledTimes(2); + }); + it("returns BM25-only results when no vector index is provided", async () => { const obs = makeObs({ id: "obs_1", sessionId: "ses_1" }); bm25.add(obs); diff --git a/test/recall-layer.test.ts b/test/recall-layer.test.ts index ae87827a67..37309555c7 100644 --- a/test/recall-layer.test.ts +++ b/test/recall-layer.test.ts @@ -11,7 +11,7 @@ import { setVectorIndex, } from "../src/functions/search.js"; import { registerSmartSearchFunction } from "../src/functions/smart-search.js"; -import { HybridSearch } from "../src/state/hybrid-search.js"; +import { HybridSearch, type HybridSearchRequest } from "../src/state/hybrid-search.js"; import { memoryToObservation } from "../src/state/memory-utils.js"; import { KV } from "../src/state/schema.js"; import { SearchIndex } from "../src/state/search-index.js"; @@ -60,7 +60,7 @@ function fixture() { const vector = new VectorIndex(); const embedding = { name: "fixed", dimensions: 2, embed: async () => new Float32Array([1, 0]), embedBatch: async () => [] }; const hybrid = new HybridSearch(index, vector, embedding, kv as never, 0.4, 0.6, 0); - const search = vi.fn((query: string, limit: number, targetLayer?: "all" | "memory" | "observation", authorizeGraph?: GraphObservationAuthorization) => hybrid.search(query, limit, targetLayer, authorizeGraph)); + const search = vi.fn((query: string, limit: number, targetLayer?: "all" | "memory" | "observation", authorizeGraph?: GraphObservationAuthorization, request?: HybridSearchRequest) => hybrid.search(query, limit, targetLayer, authorizeGraph, request)); registerSearchFunction(sdk as never, kv as never); registerSmartSearchFunction(sdk as never, kv as never, search); return { @@ -120,7 +120,7 @@ describe("recall layer selection", () => { setHybridRanker(f.search); const recall = await f.call("mem::search", { query: "quasar policy", limit: 1, targetLayer: "memory" }); expect(recall.results[0]).toMatchObject({ layer: "memory", observation: { id: "mem_decision" } }); - expect(f.search).toHaveBeenLastCalledWith("quasar policy", 1, "memory", expect.any(Function)); + expect(f.search).toHaveBeenLastCalledWith("quasar policy", 1, "memory", expect.any(Function), expect.any(Object)); const smart = await f.call("mem::smart-search", { query: "quasar policy", limit: 1, targetLayer: "memory" }); expect(smart.results).toEqual([expect.objectContaining({ obsId: "mem_decision", layer: "memory" })]); expect(smart).not.toHaveProperty("lessons"); diff --git a/test/search-project-isolation.test.ts b/test/search-project-isolation.test.ts new file mode 100644 index 0000000000..99069dd7eb --- /dev/null +++ b/test/search-project-isolation.test.ts @@ -0,0 +1,352 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, +})); +vi.mock("../src/functions/access-tracker.js", () => ({ + recordAccessBatch: vi.fn(), +})); + +import { + getSearchIndex, + registerSearchFunction, + setHybridRanker, +} from "../src/functions/search.js"; +import { HybridSearch } from "../src/state/hybrid-search.js"; +import { memoryToObservation } from "../src/state/memory-utils.js"; +import { KV } from "../src/state/schema.js"; +import type { Memory, SearchResult, Session } from "../src/types.js"; + +const timestamp = "2026-01-01T00:00:00Z"; + +describe.each(["keyword", "hybrid", "hybrid-fallback"] as const)( + "mem::search project isolation via %s", + (ranking) => { + let records: Map>; + let memories: Memory[]; + let hybridLimits: number[]; + let memoryReads: string[]; + let sessionReads: string[]; + let failSessionReads: boolean; + let activeObservationReads: number; + let maxObservationReads: number; + let search: (data: Record) => Promise<{ results: SearchResult[] }>; + + const put = (scope: string, key: string, value: unknown) => { + if (!records.has(scope)) records.set(scope, new Map()); + records.get(scope)!.set(key, value); + }; + + const addMemory = (overrides: Partial = {}) => { + const memory: Memory = { + id: "mem_unscoped", + createdAt: timestamp, + updatedAt: timestamp, + type: "fact", + title: "isolation marker", + content: "isolation marker", + concepts: ["isolation"], + files: [], + sessionIds: [], + strength: 7, + version: 1, + isLatest: true, + ...overrides, + }; + memories.push(memory); + put(KV.memories, memory.id, memory); + getSearchIndex().add(memoryToObservation(memory), "memory"); + return memory; + }; + + const addSession = (project: string) => { + const session: Session = { + id: "session_existing", + project, + cwd: "/test/project", + startedAt: timestamp, + status: "completed", + observationCount: 0, + }; + put(KV.sessions, session.id, session); + return session; + }; + + const recall = async (overrides: Record = {}) => { + const result = await search({ + query: "isolation", + project: "project-a", + targetLayer: "memory", + agentId: "*", + ...overrides, + }); + return result.results.map((hit) => hit.observation.id); + }; + + beforeEach(() => { + records = new Map(); + memories = []; + hybridLimits = []; + memoryReads = []; + sessionReads = []; + failSessionReads = false; + activeObservationReads = 0; + maxObservationReads = 0; + getSearchIndex().clear(); + setHybridRanker(null); + if (ranking !== "keyword") { + setHybridRanker(async (_query, limit) => { + hybridLimits.push(limit); + if (ranking === "hybrid-fallback") throw new Error("ranker unavailable"); + return memories.map((memory, index) => { + const observation = memoryToObservation(memory); + return { + observation, + sessionId: observation.sessionId, + combinedScore: 1 / (index + 1), + layer: "memory" as const, + }; + }).slice(0, limit); + }); + } + const kv = { + get: async (scope: string, key: string) => { + if (scope === KV.sessions) { + sessionReads.push(key); + if (failSessionReads) throw new Error("session store unavailable"); + } + if (scope === KV.observations("memory")) { + memoryReads.push(key); + activeObservationReads++; + maxObservationReads = Math.max(maxObservationReads, activeObservationReads); + await Promise.resolve(); + activeObservationReads--; + } + return records.get(scope)?.get(key) ?? null; + }, + list: async (scope: string) => [...(records.get(scope)?.values() ?? [])], + }; + const sdk = { + registerFunction: (_id: string, handler: typeof search) => { search = handler; }, + }; + registerSearchFunction(sdk as never, kv as never); + }); + + afterEach(() => { + setHybridRanker(null); + getSearchIndex().clear(); + vi.restoreAllMocks(); + }); + + it("excludes an unscoped memory with no session", async () => { + addMemory(); + expect(await recall()).toEqual([]); + }); + + it("excludes an unscoped memory with a dangling session reference", async () => { + addMemory({ sessionIds: ["session_missing"] }); + expect(await recall()).toEqual([]); + }); + + it("includes a legacy memory through its matching session", async () => { + const session = addSession("project-a"); + const memory = addMemory({ sessionIds: [session.id] }); + expect(await recall()).toEqual([memory.id]); + }); + + it("excludes a legacy memory belonging to another session project", async () => { + const session = addSession("project-b"); + addMemory({ sessionIds: [session.id] }); + expect(await recall()).toEqual([]); + }); + + it("includes an explicitly matching memory without a session", async () => { + const memory = addMemory({ project: "project-a" }); + expect(await recall()).toEqual([memory.id]); + }); + + it("rejects an explicit foreign project even when its session matches", async () => { + const session = addSession("project-a"); + addMemory({ project: "project-b", sessionIds: [session.id] }); + expect(await recall()).toEqual([]); + }); + + it("preserves unscoped memories when no project filter is requested", async () => { + const memory = addMemory(); + expect(await recall({ project: undefined })).toEqual([memory.id]); + }); + + const orderedKeywordResults = () => + vi.spyOn(getSearchIndex(), "search").mockImplementation((_query, limit) => + memories.slice(0, limit).map((memory, index) => ({ + obsId: memory.id, + sessionId: memory.sessionIds[0] ?? "memory", + score: 1 / (index + 1), + layer: "memory" as const, + })), + ); + + it.each(["project", "directory"])("stops session checks once a %s-filtered page is full", async (filter) => { + for (let i = 0; i < 100; i++) { + const session = { ...addSession("project-a"), id: `session_${i}` }; + put(KV.sessions, session.id, session); + addMemory({ id: `mem_${i}`, sessionIds: [session.id] }); + } + orderedKeywordResults(); + expect(await recall({ limit: 1, ...(filter === "directory" ? { project: undefined, cwd: "/test/project" } : {}) })).toEqual(["mem_0"]); + expect(sessionReads).toEqual(["session_0"]); + }); + + if (ranking === "hybrid") { + it("expands a real hybrid window shortened by a missing record", async () => { + for (let i = 0; i < 100; i++) { + addMemory({ id: `mem_foreign_${i.toString().padStart(3, "0")}`, project: "project-b" }); + } + records.get(KV.memories)!.delete("mem_foreign_000"); + const matching = addMemory({ id: "mem_matching", project: "project-a" }); + const hybrid = new HybridSearch(getSearchIndex(), null, null, { + get: async (scope: string, key: string) => records.get(scope)?.get(key) ?? null, + } as never, 0.4, 0.6, 0); + const ranker = vi.fn(hybrid.search.bind(hybrid)); + setHybridRanker(ranker); + expect(await recall({ limit: 1 })).toEqual([matching.id]); + expect(ranker.mock.calls.map((call) => call[1])).toEqual([100, 200]); + }); + } + + it("refills multiple full windows without returning excluded projects", async () => { + for (let i = 0; i < 205; i++) { + addMemory({ id: `mem_excluded_${i}`, project: i % 2 ? "project-b" : undefined }); + } + const matching = addMemory({ id: "mem_matching", project: "project-a" }); + orderedKeywordResults(); + expect(await recall({ limit: 1 })).toEqual([matching.id]); + }); + + it("refills after the loaded agent filter consumes a full window", async () => { + for (let i = 0; i < 100; i++) { + addMemory({ id: `mem_foreign_agent_${i}`, project: "project-a", agentId: "agent-b" }); + } + const matching = addMemory({ id: "mem_matching", project: "project-a", agentId: "agent-a" }); + orderedKeywordResults(); + expect(await recall({ limit: 1, agentId: "agent-a" })).toEqual([matching.id]); + if (ranking !== "hybrid") { + expect(memoryReads.filter((id) => id === "mem_foreign_agent_0")).toHaveLength(1); + expect(maxObservationReads).toBeLessThanOrEqual(10); + } + }); + + it("bounds candidate scanning even when every record is rejected", async () => { + for (let i = 0; i < 1001; i++) { + addMemory({ id: `mem_foreign_${i}`, project: "project-b" }); + } + addMemory({ id: "mem_beyond_budget", project: "project-a" }); + const keyword = orderedKeywordResults(); + expect(await recall({ limit: 1 })).toEqual([]); + const requestedLimits = ranking === "hybrid" + ? hybridLimits + : keyword.mock.calls.map((call) => call[1]); + expect(requestedLimits).toEqual([100, 200, 400, 800, 1000]); + }); + + it("stops refilling when the candidate source is exhausted", async () => { + for (let i = 0; i < 100; i++) addMemory({ id: `mem_unscoped_${i}` }); + const keyword = orderedKeywordResults(); + expect(await recall({ limit: 1 })).toEqual([]); + const requestedLimits = ranking === "hybrid" + ? hybridLimits + : keyword.mock.calls.map((call) => call[1]); + expect(requestedLimits).toEqual([100, 200]); + }); + + it("stops session filtering after a bounded batch fills the page", async () => { + const observations = []; + for (let i = 0; i < 100; i++) { + const session = { ...addSession("project-a"), id: `session_${i}` }; + put(KV.sessions, session.id, session); + const memory = addMemory({ id: `obs_valid_${i}`, sessionIds: [session.id] }); + const observation = memoryToObservation(memory); + observations.push(observation); + getSearchIndex().add(observation, "observation"); + put(KV.observations(session.id), observation.id, observation); + } + vi.spyOn(getSearchIndex(), "search").mockImplementation((_query, limit) => + observations.slice(0, limit).map((observation, i) => ({ + obsId: observation.id, sessionId: observation.sessionId, score: 1 / (i + 1), layer: "observation" as const, + })), + ); + if (ranking === "hybrid") { + setHybridRanker(async (_query, limit) => observations.slice(0, limit).map((observation, i) => ({ + observation, sessionId: observation.sessionId, combinedScore: 1 / (i + 1), layer: "observation" as const, + }))); + } + expect(await recall({ limit: 1, targetLayer: "observation" })).toEqual(["obs_valid_0"]); + expect(sessionReads.length).toBeLessThanOrEqual(10); + expect(sessionReads).not.toContain("session_10"); + }); + + it("does not read sessions for agent-only filtering", async () => { + const memory = addMemory({ project: "project-a", agentId: "agent-a" }); + failSessionReads = true; + expect(await recall({ project: undefined, agentId: "agent-a" })).toEqual([memory.id]); + expect(sessionReads).toEqual([]); + }); + + if (ranking === "hybrid") { + it("preserves accepted hybrid hits when a later refill fails", async () => { + const matching = addMemory({ id: "mem_vector_only", project: "project-a" }); + for (let i = 0; i < 99; i++) addMemory({ id: `mem_foreign_${i}`, project: "project-b" }); + let calls = 0; + setHybridRanker(async () => { + if (++calls > 1) throw new Error("refill unavailable"); + return memories.map((memory, i) => ({ + observation: memoryToObservation(memory), sessionId: "memory", combinedScore: 1 / (i + 1), layer: "memory" as const, + })); + }); + const keyword = vi.spyOn(getSearchIndex(), "search").mockReturnValue([]); + expect(await recall({ limit: 2 })).toEqual([matching.id]); + expect(keyword).not.toHaveBeenCalled(); + }); + } + + it("rejects orphaned observations when a directory filter is requested", async () => { + const orphan = addMemory({ id: "obs_orphan", sessionIds: ["session_missing"] }); + const observation = memoryToObservation(orphan); + getSearchIndex().add(observation, "observation"); + put(KV.observations("session_missing"), orphan.id, observation); + if (ranking === "hybrid") { + setHybridRanker(async () => [{ observation, sessionId: "session_missing", combinedScore: 1, layer: "observation" }]); + } + expect(await recall({ project: undefined, cwd: "/test/project", targetLayer: "all" })).toEqual([]); + }); + + it("preserves sessionless memories when a directory filter is requested", async () => { + const memory = addMemory({ project: "project-a" }); + expect(await recall({ project: undefined, cwd: "/test/project" })).toEqual([memory.id]); + }); + + it("does not let an unloadable observation consume the result limit", async () => { + const session = addSession("project-a"); + const matching = addMemory({ id: "mem_matching", project: "project-a" }); + vi.spyOn(getSearchIndex(), "search").mockImplementation((_query, limit) => [ + { obsId: "obs_missing", sessionId: session.id, score: 2, layer: "observation" as const }, + { obsId: matching.id, sessionId: "memory", score: 1, layer: "memory" as const }, + ].slice(0, limit)); + expect(await recall({ limit: 1, targetLayer: "all" })).toEqual([matching.id]); + }); + + it("fills the result limit after excluding an unscoped first candidate", async () => { + const unscoped = addMemory(); + const matching = addMemory({ id: "mem_matching", project: "project-a" }); + vi.spyOn(getSearchIndex(), "search").mockImplementation((_query, limit) => + [unscoped, matching].slice(0, limit).map((memory, index) => ({ + obsId: memory.id, + sessionId: "memory", + score: 1 / (index + 1), + layer: "memory" as const, + })), + ); + expect(await recall({ limit: 1 })).toEqual([matching.id]); + }); + }, +);