Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
175 changes: 97 additions & 78 deletions src/functions/search.ts
Original file line number Diff line number Diff line change
@@ -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'
Expand Down Expand Up @@ -33,6 +34,7 @@ type HybridRanker = (
limit: number,
targetLayer?: SearchLayer,
authorizeGraph?: GraphObservationAuthorization,
request?: HybridSearchRequest,
) => Promise<Array<{ observation: CompressedObservation; sessionId: string; combinedScore: number; layer?: SearchResultLayer }>>
let hybridRanker: HybridRanker | null = null

Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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.
Expand All @@ -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<string, Session | null>()
const sessionCache = new Map<string, Promise<Session | null>>()
const loadSession = async (sessionId: string): Promise<Session | null> => {
if (sessionCache.has(sessionId)) return sessionCache.get(sessionId)!
const s = await kv.get<Session>(KV.sessions, sessionId)
sessionCache.set(sessionId, s ?? null)
return s ?? null
const pending = kv.get<Session>(KV.sessions, sessionId).then((session) => session ?? null)
sessionCache.set(sessionId, pending)
return pending
}

const memoryProjectCache = new Map<string, string | null>()
Expand All @@ -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<string, Promise<{
observation: CompressedObservation
layer: SearchResultLayer
} | null>>()
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
Comment thread
rohitg00 marked this conversation as resolved.
Resolved
useHybridRanker = false
results = idx.search(query, fetchLimit, targetLayer)
Comment thread
rohitg00 marked this conversation as resolved.
Resolved
}
} 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<CompressedObservation>(KV.observations(r.sessionId), r.obsId)
.catch(() => null)
if (obs) return { observation: obs, layer: "observation" as const }
const mem = await kv
.get<Memory>(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 = []
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
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<CompressedObservation>(KV.observations(r.sessionId), r.obsId)
.catch(() => null)
if (obs) return { observation: obs, layer: "observation" as const }
const mem = await kv
.get<Memory>(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)
Expand Down
4 changes: 2 additions & 2 deletions src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -449,8 +449,8 @@ async function main() {
graphWeight,
);

const hybridRanker = (query: string, limit: number, targetLayer?: SearchLayer, authorizeGraph?: Parameters<HybridSearch["search"]>[3]) =>
hybridSearch.search(query, limit, targetLayer, authorizeGraph);
const hybridRanker = (query: string, limit: number, targetLayer?: SearchLayer, authorizeGraph?: Parameters<HybridSearch["search"]>[3], request?: Parameters<HybridSearch["search"]>[4]) =>
hybridSearch.search(query, limit, targetLayer, authorizeGraph, request);
registerSmartSearchFunction(sdk, kv, hybridRanker);
setHybridRanker(hybridRanker);
registerRecentSearchesSweepFunction(sdk, kv);
Expand Down
26 changes: 23 additions & 3 deletions src/state/hybrid-search.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<Float32Array> };
candidateCount?: number;
}

export class HybridSearch {
private graphRetrieval: GraphRetrieval;
private lastGraphTimeoutWarningAt = -Infinity;
Expand All @@ -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<HybridSearchResult[]> {
return this.tripleStreamSearch(query, limit, targetLayer, this.graphRetrieval.createQuery(authorizeGraph));
async search(query: string, limit = 20, targetLayer: SearchLayer = "all", authorizeGraph?: GraphObservationAuthorization, request?: HybridSearchRequest): Promise<HybridSearchResult[]> {
return this.tripleStreamSearch(query, limit, targetLayer, this.graphRetrieval.createQuery(authorizeGraph), undefined, true, request);
}

async searchWithExpansion(
Expand Down Expand Up @@ -95,6 +100,7 @@ export class HybridSearch {
graphQuery: GraphQuery,
entityHints?: string[],
applyReranking = true,
request?: HybridSearchRequest,
): Promise<HybridSearchResult[]> {
const retrievalLimit = this.rerankEnabled ? Math.max(limit, 20) : limit;
const bm25Results = this.bm25.search(query, retrievalLimit * 2, targetLayer);
Expand All @@ -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
Expand Down Expand Up @@ -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);
Expand Down
44 changes: 43 additions & 1 deletion test/hybrid-search.test.ts
Original file line number Diff line number Diff line change
@@ -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";

Expand Down Expand Up @@ -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<Float32Array>>()
.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);
Expand Down
Loading