#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
import type { GraphObservationAuthorization } from "./graph-retrieval.js";
import type { IIIClient } from "iii-sdk";
import type {
CompactLessonResult,
CompactSearchResult,
CompressedObservation,
HybridSearchResult,
Lesson,
Memory,
} from "../types.js";
import { getSearchResultLayer, isSearchLayer, matchesSearchLayer, type SearchLayer, type SearchResultLayer } from "../state/search-layer.js";
import { KV } from "../state/schema.js";
import { StateKV } from "../state/kv.js";
import { withKeyedLock } from "../state/keyed-mutex.js";
import {
indexObservationSession,
lookupObservationSession,
} from "../state/obs-index.js";
import { recordAccessBatch } from "./access-tracker.js";
import {
getAgentId,
isAgentScopeIsolated,
getFollowupWindowSeconds,
} from "../config.js";
import { logger } from "../logger.js";
import { withoutObservationSource } from "./observation-source.js";
import { getCounters } from "../telemetry/setup.js";
import { memoryToObservation } from "../state/memory-utils.js";
import { getSearchIndex } from "./search.js";
export interface RecentSearch {
sessionId: string;
query: string;
resultIds: string[];
at: number;
}
// Module-scope counter mirror so `mem::diagnostic::followup-stats` can
// read the rate back without going through the OTEL collector. The
// OTEL counter is still the canonical export; this is an in-process
// convenience for `agentmemory status` + tests.
const followupStats = {
followupWithinWindow: 0,
agentInitiatedSearches: 0,
};
// Tracks the in-flight detection promises so tests (and shutdown
// flushes) can wait for all queued lock bodies to drain. The Set adds
// when a detection is queued and removes when it settles; size === 0
// means no pending detections.
const pendingFollowups = new Set<Promise<void>>();
export function getFollowupStats(): {
followupWithinWindow: number;
agentInitiatedSearches: number;
rate: number;
} {
const total = followupStats.agentInitiatedSearches;
return {
...followupStats,
rate: total > 0 ? followupStats.followupWithinWindow / total : 0,
};
}
export async function flushPendingFollowups(): Promise<void> {
// Snapshot the current pending set; new detections queued after the
// snapshot run in a fresh batch.
await Promise.all(Array.from(pendingFollowups));
}
export function resetFollowupStatsForTests(): void {
followupStats.followupWithinWindow = 0;
followupStats.agentInitiatedSearches = 0;
}
// Compact mode trims each lesson's content for at-a-glance display. The
// full content is fetched via memory_lesson_recall when the caller needs it.
const LESSON_CONTENT_PREVIEW_CHARS = 240;
export function registerSmartSearchFunction(
sdk: IIIClient,
kv: StateKV,
searchFn: (query: string, limit: number, targetLayer?: SearchLayer, authorizeGraph?: GraphObservationAuthorization) => Promise<HybridSearchResult[]>,
): void {
sdk.registerFunction("mem::smart-search",
async (data: {
query?: string;
expandIds?: Array<string | { obsId: string; sessionId: string }>;
limit?: number;
project?: string;
includeLessons?: boolean;
targetLayer?: SearchLayer;
// optional per-call agent filter for runtimes routing many
// roles through one server. "*" opts out of the env-default
// scope and returns hits from every agent.
agentId?: string;
sessionId?: string;
source?: string;
}) => {
if (data.targetLayer !== undefined && !isSearchLayer(data.targetLayer)) {
throw new Error("mem::smart-search: targetLayer must be one of 'all', 'memory', or 'observation'");
}
const targetLayer = data.targetLayer ?? "all";
const isolated = isAgentScopeIsolated();
const explicitAgentId =
typeof data.agentId === "string" && data.agentId.trim().length > 0
? data.agentId.trim()
: undefined;
const wildcardAgent = explicitAgentId === "*";
const envAgentId = isolated ? getAgentId() : undefined;
const filterAgentId = wildcardAgent
? undefined
: explicitAgentId ?? envAgentId;
const project =
typeof data.project === "string" && data.project.trim()
? data.project.trim()
: undefined;
if (
isolated &&
!wildcardAgent &&
!explicitAgentId &&
!envAgentId
) {
throw new Error(
"mem::smart-search: AGENTMEMORY_AGENT_SCOPE=isolated is set but " +
"no agent id is available (env AGENT_ID unset and no explicit " +
"agentId in the call). Refusing to read cross-agent rows. " +
'Pass agentId: "*" to opt in to a wildcard read.',
);
}
const matchesProject = project ? makeProjectMatcher(kv, project) : undefined;
if (data.expandIds && data.expandIds.length > 0) {
const raw = data.expandIds.slice(0, 100);
const items = raw.map((entry) => {
if (typeof entry === "string") return { obsId: entry, sessionId: undefined as string | undefined };
if (entry && typeof entry === "object" && typeof entry.obsId === "string") {
return { obsId: entry.obsId, sessionId: typeof entry.sessionId === "string" ? entry.sessionId : undefined };
}
return null;
}).filter((item): item is NonNullable<typeof item> => item !== null);
const expanded: Array<{
obsId: string;
sessionId: string;
observation: CompressedObservation;
layer: SearchResultLayer;
}> = [];
let attempted = 0;
for (let offset = 0; offset < items.length && expanded.length < 20; offset += 10) {
const batch = items.slice(offset, offset + 10);
const results = await Promise.all(batch.map(({ obsId, sessionId }) => findObservation(kv, obsId, sessionId)));
attempted += batch.length;
for (const result of results) {
if (!result) continue;
const { observation, layer } = result;
if (!matchesSearchLayer(observation.id, observation.sessionId, targetLayer, layer)) continue;
if (filterAgentId && observation.agentId !== filterAgentId) continue;
if (matchesProject && !await matchesProject(observation.id, observation.sessionId)) continue;
expanded.push({
obsId: observation.id,
sessionId: observation.sessionId,
observation: withoutObservationSource(observation),
layer,
});
}
}
const scoped = expanded.slice(0, 20);
void recordAccessBatch(
kv,
scoped.map((e) => e.observation.id),
);
const truncated = data.expandIds.length > raw.length || attempted < items.length || expanded.length > scoped.length;
logger.info("Smart search expanded", {
requested: data.expandIds.length,
attempted,
returned: scoped.length,
truncated,
});
return { mode: "expanded", results: scoped, truncated };
}
if (!data.query || typeof data.query !== "string" || !data.query.trim()) {
return { mode: "compact", results: [], error: "query is required" };
}
const limit = Math.max(1, Math.min(data.limit ?? 20, 100));
// Lesson recall stays capped: lessons are denser than raw
// observations so 10 covers most recall flows.
const lessonLimit = Math.min(limit, 10);
const includeLessons = targetLayer === "all" && data.includeLessons !== false;
const overFetchLimit = filterAgentId || project
? Math.max(Math.min(limit * 10, 300), 100)
: limit;
const authorizeGraph: GraphObservationAuthorization = async (record, sessionId, read) => {
if (filterAgentId !== undefined && record.agentId !== filterAgentId) return false;
if (!project) return true;
if ("content" in record && record.project !== undefined) return record.project === project;
return (await read<{ project?: string }>(KV.sessions, sessionId))?.project === project;
};
const [hybridResults, lessons] = await Promise.all([
searchFn(data.query, overFetchLimit, targetLayer, authorizeGraph),
includeLessons
? recallLessons(sdk, data.query, lessonLimit, project)
: Promise.resolve([]),
]);
const layerResults = hybridResults.filter((result) => matchesSearchLayer(
result.observation.id,
result.sessionId,
targetLayer,
result.layer ?? getSearchIndex().layerOf(result.observation.id),
));
const projectResults = matchesProject
? await filterProjectResults(layerResults, (result) => matchesProject(result.observation.id, result.sessionId))
: layerResults;
const filteredHybrid = filterAgentId
? projectResults
.filter((r) => r.observation.agentId === filterAgentId)
.slice(0, limit)
: projectResults.slice(0, limit);
const compact: CompactSearchResult[] = filteredHybrid.map((r) => ({
obsId: r.observation.id,
layer: r.layer ?? getSearchIndex().layerOf(r.observation.id) ?? getSearchResultLayer(r.observation.id, r.sessionId),
sessionId: r.sessionId,
title: r.observation.title,
type: r.observation.type,
score: r.combinedScore,
timestamp: r.observation.timestamp,
}));
void recordAccessBatch(
kv,
compact.map((r) => r.obsId),
);
if (
data.sessionId &&
typeof data.sessionId === "string" &&
data.source !== "viewer" &&
compact.length > 0
) {
// Skip detection when retrieval returned nothing: an empty
// result set is a retrieval failure, not a reader-failure
// signal. Counting it as "disjoint from prior" would inflate
// the rate every time search returns no hits.
followupStats.agentInitiatedSearches++;
// Off the critical response path. The withKeyedLock(sessionId)
// call serializes detection per session, so two rapid
// back-to-back searches from the same agent still see ordered
// prior-row writes — the second call's lock body queues
// behind the first's. Other sessions run in parallel.
const sessionIdForFollowup = data.sessionId;
const queryForFollowup = data.query;
const compactForFollowup = compact;
const detection = withKeyedLock(
`recent-searches:${sessionIdForFollowup}`,
() =>
detectFollowup(
kv,
sessionIdForFollowup,
queryForFollowup,
compactForFollowup,
),
)
.catch((err) => {
logger.warn("Smart search followup detection failed", {
sessionId: sessionIdForFollowup,
error: err instanceof Error ? err.message : String(err),
});
})
.finally(() => {
pendingFollowups.delete(detection);
});
pendingFollowups.add(detection);
}
logger.info("Smart search compact", {
query: data.query,
results: compact.length,
lessons: lessons.length,
});
const response: {
mode: "compact";
results: CompactSearchResult[];
lessons?: CompactLessonResult[];
} = { mode: "compact", results: compact };
if (includeLessons) response.lessons = lessons;
return response;
},
);
}
async function recallLessons(
sdk: IIIClient,
query: string,
limit: number,
project?: string,
): Promise<CompactLessonResult[]> {
try {
const result = (await sdk.trigger({
function_id: "mem::lesson-recall",
payload: { query, limit, project },
})) as { success?: boolean; lessons?: Array<Lesson & { score?: number }> };
if (!result?.success || !Array.isArray(result.lessons)) return [];
return result.lessons.map((l) => ({
lessonId: l.id,
content:
l.content.length > LESSON_CONTENT_PREVIEW_CHARS
? l.content.slice(0, LESSON_CONTENT_PREVIEW_CHARS) + "…"
: l.content,
confidence: l.confidence,
score: l.score ?? l.confidence,
createdAt: l.createdAt,
project: l.project,
tags: l.tags ?? [],
}));
} catch (err) {
logger.warn("Smart search: mem::lesson-recall failed; returning empty lesson list", {
error: err instanceof Error ? err.message : String(err),
});
return [];
}
}
async function detectFollowup(
kv: StateKV,
sessionId: string,
query: string,
compact: CompactSearchResult[],
): Promise<void> {
const now = Date.now();
const windowMs = Math.max(1, getFollowupWindowSeconds()) * 1000;
const currentIds = compact.map((r) => r.obsId);
const current: RecentSearch = { sessionId, query, resultIds: currentIds, at: now };
const prior = await kv
.get<RecentSearch>(KV.recentSearches, sessionId)
.catch(() => null);
await kv.set(KV.recentSearches, sessionId, current);
if (!prior || typeof prior.at !== "number") return;
if (now - prior.at > windowMs) return;
// Same query inside the window is a retry, not a follow-up; skip so a
// duplicate request from a flaky client doesn't inflate the metric.
if (typeof prior.query === "string" && prior.query === query) return;
const priorIds = Array.isArray(prior.resultIds) ? prior.resultIds : [];
const priorSet = new Set(priorIds);
const hasOverlap = currentIds.some((id) => priorSet.has(id));
if (hasOverlap) return;
getCounters().smartSearchFollowupWithinWindow.add(1);
followupStats.followupWithinWindow++;
logger.info("Smart search followup detected", {
sessionId,
windowSeconds: Math.round(windowMs / 1000),
priorQuery: prior.query,
nextQuery: query,
priorResultCount: priorIds.length,
nextResultCount: currentIds.length,
});
}
async function findObservation(
kv: StateKV,
obsId: string,
sessionIdHint?: string,
): Promise<{ observation: CompressedObservation; layer: SearchResultLayer } | null> {
const memory = await kv.get<Memory>(KV.memories, obsId);
if (memory) return { observation: memoryToObservation(memory), layer: "memory" };
if (sessionIdHint) {
const obs = await kv
.get<CompressedObservation>(KV.observations(sessionIdHint), obsId)
.catch(() => null);
if (obs) return { observation: obs, layer: "observation" };
}
const indexedSessionId = await lookupObservationSession(kv, obsId);
if (indexedSessionId) {
const obs = await kv
.get<CompressedObservation>(KV.observations(indexedSessionId), obsId)
.catch(() => null);
if (obs) return { observation: obs, layer: "observation" };
}
const sessions = await kv.list<{ id: string }>(KV.sessions);
for (let i = 0; i < sessions.length; i += 5) {
const batch = sessions.slice(i, i + 5);
const results = await Promise.all(
batch.map((s) =>
kv.get<CompressedObservation>(KV.observations(s.id), obsId).catch(() => null),
),
);
const foundIndex = results.findIndex((r) => r !== null);
if (foundIndex !== -1) {
const found = results[foundIndex] as CompressedObservation;
await indexObservationSession(kv, obsId, batch[foundIndex].id).catch(
() => {},
);
return { observation: found, layer: "observation" };
}
}
return null;
}
function makeProjectMatcher(kv: StateKV, project: string): (obsId: string, sessionId: string) => Promise<boolean> {
const memories = new Map<string, Promise<Memory | null>>();
const sessions = new Map<string, Promise<{ project?: string } | null>>();
return async (obsId, sessionId) => {
let memoryRead = memories.get(obsId);
if (!memoryRead) {
memoryRead = kv.get<Memory>(KV.memories, obsId);
memories.set(obsId, memoryRead);
}
const memory = await memoryRead;
if (memory?.project !== undefined) return memory.project === project;
let sessionRead = sessions.get(sessionId);
if (!sessionRead) {
sessionRead = kv.get<{ project?: string }>(KV.sessions, sessionId);
sessions.set(sessionId, sessionRead);
}
return (await sessionRead)?.project === project;
};
}
async function filterProjectResults<T>(items: T[], matches: (item: T) => Promise<boolean>): Promise<T[]> {
const scoped: T[] = [];
for (let offset = 0; offset < items.length; offset += 10) {
const batch = items.slice(offset, offset + 10);
const selected = await Promise.all(batch.map(matches));
scoped.push(...batch.filter((_, index) => selected[index]));
}
return scoped;
}