#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
perf(context,search): per-project session index and observation lookup index (#1418)
Rohit Ghumarec314c7bf6a59
diff --git a/src/functions/auto-forget.ts b/src/functions/auto-forget.tsindex d8f6ac70..bb778625 100644--- a/src/functions/auto-forget.ts+++ b/src/functions/auto-forget.ts@@ -2,6 +2,7 @@ import type { IIIClient } from "iii-sdk";import type { Memory, CompressedObservation, Session } from "../types.js";import { KV } from "../state/schema.js";import { StateKV } from "../state/kv.js";+import { unindexObservationSession } from "../state/obs-index.js";import { recordAudit } from "./audit.js";import { deleteAccessLog } from "./access-tracker.js";import { getSearchIndex, vectorIndexRemove, flushIndexSave } from "./search.js";@@ -172,6 +173,7 @@ export function registerAutoForgetFunction(sdk: IIIClient, kv: StateKV): void {deletedOk = false;}if (deletedOk) {+ await unindexObservationSession(kv, obs.id).catch(() => {});if (obs.imageData) await decrementImageRef(kv, sdk, obs.imageData);if (obs.imageRef && obs.imageRef !== obs.imageData) {await decrementImageRef(kv, sdk, obs.imageRef);diff --git a/src/functions/context.ts b/src/functions/context.tsindex 668ac61b..7a5a7b5e 100644--- a/src/functions/context.ts+++ b/src/functions/context.ts@@ -10,6 +10,10 @@ import type {} from "../types.js";import { KV } from "../state/schema.js";import { StateKV } from "../state/kv.js";+import {+ ensureProjectSessionIndex,+ getProjectSessionIndex,+} from "../state/session-index.js";import { recordAccessBatch } from "./access-tracker.js";import { logger } from "../logger.js";import {@@ -164,8 +168,44 @@ export function registerContextFunction(});}- const allSessions = await kv.list<Session>(KV.sessions);- const sessions = allSessions+ const indexEntries = await getProjectSessionIndex(kv, data.project);+ let projectSessions: Session[];+ if (indexEntries !== null) {+ const fetched = await Promise.all(+ indexEntries.map((entry) =>+ kv.get<Session>(KV.sessions, entry.id).catch(() => null),+ ),+ );+ projectSessions = fetched.filter(+ (s): s is Session => s !== null,+ );+ } else {+ const allSessions = await kv.list<Session>(KV.sessions);+ const scanned = allSessions.filter((s) => s.project === data.project);+ const ensuredIndex = await ensureProjectSessionIndex(+ kv,+ data.project,+ scanned.map((s) => ({+ id: s.id,+ startedAt: s.startedAt,+ ...(s.agentId ? { agentId: s.agentId } : {}),+ })),+ ).catch(() => null);+ if (ensuredIndex) {+ const fetched = await Promise.all(+ ensuredIndex.map((entry) =>+ kv.get<Session>(KV.sessions, entry.id).catch(() => null),+ ),+ );+ projectSessions = fetched.filter(+ (s): s is Session => s !== null,+ );+ } else {+ projectSessions = scanned;+ }+ }++ const sessions = projectSessions.filter((s) =>s.project === data.project &&diff --git a/src/functions/evict.ts b/src/functions/evict.tsindex b7afb202..1fe2b121 100644--- a/src/functions/evict.ts+++ b/src/functions/evict.ts@@ -8,6 +8,8 @@ import type {} from "../types.js";import { KV } from "../state/schema.js";import { StateKV } from "../state/kv.js";+import { removeSessionFromProjectIndex } from "../state/session-index.js";+import { unindexObservationSession } from "../state/obs-index.js";import { isConsolidationEnabled } from "../config.js";import { recordAudit } from "./audit.js";import { deleteAccessLog } from "./access-tracker.js";@@ -180,6 +182,14 @@ export function registerEvictFunction(sdk: IIIClient, kv: StateKV): void {});continue;}+ for (const o of observations) {+ await unindexObservationSession(kv, o.id).catch(() => {});+ }+ await removeSessionFromProjectIndex(+ kv,+ session.project,+ session.id,+ ).catch(() => {});await recordAudit(kv, "delete", "mem::evict", [session.id], {resource: "session",reason: recovered@@ -225,6 +235,7 @@ export function registerEvictFunction(sdk: IIIClient, kv: StateKV): void {});continue;}+ await unindexObservationSession(kv, o.id).catch(() => {});if (o.imageData) await decrementImageRef(kv, sdk, o.imageData);if (o.imageRef && o.imageRef !== o.imageData) await decrementImageRef(kv, sdk, o.imageRef);await recordAudit(kv, "delete", "mem::evict", [o.id], {@@ -268,6 +279,7 @@ export function registerEvictFunction(sdk: IIIClient, kv: StateKV): void {});continue;}+ await unindexObservationSession(kv, o.id).catch(() => {});if (o.imageData) await decrementImageRef(kv, sdk, o.imageData);if (o.imageRef && o.imageRef !== o.imageData) await decrementImageRef(kv, sdk, o.imageRef);await recordAudit(kv, "delete", "mem::evict", [o.id], {diff --git a/src/functions/export-import.ts b/src/functions/export-import.tsindex 747cdd53..bef2b9ef 100644--- a/src/functions/export-import.ts+++ b/src/functions/export-import.ts@@ -29,6 +29,14 @@ import { normalizeAccessLog } from "./access-tracker.js";import { KV } from "../state/schema.js";import { checkPayloadFrameSize } from "../state/frame-guard.js";import { StateKV } from "../state/kv.js";+import {+ addSessionToProjectIndex,+ removeSessionFromProjectIndex,+} from "../state/session-index.js";+import {+ indexObservationSession,+ unindexObservationSession,+} from "../state/obs-index.js";import { withKeyedLock } from "../state/keyed-mutex.js";import { VERSION } from "../version.js";import { recordAudit } from "./audit.js";@@ -312,6 +320,11 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): voidconst obsDeletes: Array<{ sessionId: string; obsId: string }> = [];await runChunked(existing, async (session) => {await kv.delete(KV.sessions, session.id);+ await removeSessionFromProjectIndex(+ kv,+ session.project,+ session.id,+ ).catch(() => {});const obs = await kv.list<CompressedObservation>(KV.observations(session.id)).catch(() => []);@@ -319,9 +332,10 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): voidobsDeletes.push({ sessionId: session.id, obsId: o.id });}});- await runChunked(obsDeletes, (d) =>- kv.delete(KV.observations(d.sessionId), d.obsId),- );+ await runChunked(obsDeletes, async (d) => {+ await kv.delete(KV.observations(d.sessionId), d.obsId);+ await unindexObservationSession(kv, d.obsId).catch(() => {});+ });await runChunked(await kv.list<Memory>(KV.memories), (m) =>kv.delete(KV.memories, m.id),);@@ -412,6 +426,7 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): voidconst indexMems: Memory[] = [];await runChunked(importData.sessions, async (session) => {+ let wrote = false;await withKeyedLock(`obs:${session.id}`, async () => {if (strategy === "skip") {const existing = await kv@@ -424,7 +439,15 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void}await kv.set(KV.sessions, session.id, session);stats.sessions++;+ wrote = true;});+ if (wrote) {+ await addSessionToProjectIndex(kv, session.project, {+ id: session.id,+ startedAt: session.startedAt,+ ...(session.agentId ? { agentId: session.agentId } : {}),+ }).catch(() => {});+ }});for (const [sessionId, obs] of Object.entries(importData.observations)) {@@ -440,6 +463,7 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void}o.origin = importOrigin(o.origin, o.timestamp);await kv.set(KV.observations(sessionId), o.id, o);+ await indexObservationSession(kv, o.id, sessionId).catch(() => {});stats.observations++;indexObs.push(o);});diff --git a/src/functions/migrate.ts b/src/functions/migrate.tsindex 350a5332..ba4fe4fd 100644--- a/src/functions/migrate.ts+++ b/src/functions/migrate.ts@@ -3,6 +3,7 @@ import { resolve } from "node:path";import { homedir } from "node:os";import { KV, generateId } from "../state/schema.js";import { StateKV } from "../state/kv.js";+import { addSessionToProjectIndex } from "../state/session-index.js";import { withKeyedLock } from "../state/keyed-mutex.js";import type {Memory,@@ -154,6 +155,11 @@ export function registerMigrateFunction(sdk: IIIClient, kv: StateKV): void {await withKeyedLock(`obs:${session.id}`, () =>kv.set(KV.sessions, session.id, session),);+ await addSessionToProjectIndex(kv, session.project, {+ id: session.id,+ startedAt: session.startedAt,+ ...(session.agentId ? { agentId: session.agentId } : {}),+ }).catch(() => {});sessionCount++;}diff --git a/src/functions/observe.ts b/src/functions/observe.tsindex fa45f68f..366dca7e 100644--- a/src/functions/observe.ts+++ b/src/functions/observe.ts@@ -4,6 +4,8 @@ import type { RawObservation, HookPayload, Origin } from "../types.js";const TOOL_HOOKS = new Set(["pre_tool_use", "post_tool_use", "post_tool_failure"]);import { KV, STREAM, generateId } from "../state/schema.js";import { StateKV } from "../state/kv.js";+import { addSessionToProjectIndex } from "../state/session-index.js";+import { indexObservationSession } from "../state/obs-index.js";import { stripPrivateData } from "./privacy.js";import { DedupMap } from "./dedup.js";import { withKeyedLock } from "../state/keyed-mutex.js";@@ -196,6 +198,15 @@ export function registerObserveFunction(try {await kv.set(KV.observations(payload.sessionId), obsId, raw);+ await indexObservationSession(kv, obsId, payload.sessionId).catch(+ (err) => {+ logger.warn("observation index update failed", {+ obsId,+ sessionId: payload.sessionId,+ error: err instanceof Error ? err.message : String(err),+ });+ },+ );} catch (error) {if (raw.imageData) {@@ -284,11 +295,12 @@ export function registerObserveFunction(? raw.userPrompt.replace(/\s+/g, " ").trim().slice(0, 200): undefined;const ts = new Date().toISOString();+ const startedAt = payload.timestamp ?? ts;await kv.set(KV.sessions, payload.sessionId, {id: payload.sessionId,project: payload.project,cwd: payload.cwd,- startedAt: payload.timestamp ?? ts,+ startedAt,updatedAt: ts,status: "active",observationCount: 1,@@ -297,6 +309,16 @@ export function registerObserveFunction(? { firstPrompt: trimmedPrompt }: {}),});+ await addSessionToProjectIndex(kv, payload.project, {+ id: payload.sessionId,+ startedAt,+ ...(inheritedAgentId ? { agentId: inheritedAgentId } : {}),+ }).catch((err) => {+ logger.warn("session index update failed", {+ sessionId: payload.sessionId,+ error: err instanceof Error ? err.message : String(err),+ });+ });}// Per-observation LLM compression is opt-in as of 0.8.8.diff --git a/src/functions/remember.ts b/src/functions/remember.tsindex e3a7e8ea..4e0fcbf6 100644--- a/src/functions/remember.ts+++ b/src/functions/remember.ts@@ -1,8 +1,10 @@import { TriggerAction, type IIIClient } from "iii-sdk";-import type { Memory } from "../types.js";+import type { Memory, Session } from "../types.js";import { KV, generateId, jaccardSimilarity } from "../state/schema.js";import { StateKV } from "../state/kv.js";import { withKeyedLock } from "../state/keyed-mutex.js";+import { removeSessionFromProjectIndex } from "../state/session-index.js";+import { unindexObservationSession } from "../state/obs-index.js";import { memoryToObservation } from "../state/memory-utils.js";import { deleteAccessLog } from "./access-tracker.js";import { recordAudit } from "./audit.js";@@ -296,6 +298,7 @@ export function registerRememberFunction(sdk: IIIClient, kv: StateKV): void {obsId,);await kv.delete(KV.observations(data.sessionId), obsId);+ await unindexObservationSession(kv, obsId).catch(() => {});if (obs?.imageData) await decrementImageRef(kv, sdk, obs.imageData);if (obs?.imageRef && obs.imageRef !== obs.imageData) {await decrementImageRef(kv, sdk, obs.imageRef);@@ -317,6 +320,7 @@ export function registerRememberFunction(sdk: IIIClient, kv: StateKV): void {);for (const obs of observations) {await kv.delete(KV.observations(data.sessionId), obs.id);+ await unindexObservationSession(kv, obs.id).catch(() => {});if (obs.imageData) await decrementImageRef(kv, sdk, obs.imageData);if (obs.imageRef && obs.imageRef !== obs.imageData) {await decrementImageRef(kv, sdk, obs.imageRef);@@ -326,8 +330,18 @@ export function registerRememberFunction(sdk: IIIClient, kv: StateKV): void {deletedObservationIds.push(obs.id);deleted++;}+ const sessionToDelete = await kv+ .get<Session>(KV.sessions, data.sessionId)+ .catch(() => null);await kv.delete(KV.sessions, data.sessionId);await kv.delete(KV.summaries, data.sessionId);+ if (sessionToDelete) {+ await removeSessionFromProjectIndex(+ kv,+ sessionToDelete.project,+ data.sessionId,+ ).catch(() => {});+ }deletedSession = true;deleted += 2;}diff --git a/src/functions/replay.ts b/src/functions/replay.tsindex d158b913..95629653 100644--- a/src/functions/replay.ts+++ b/src/functions/replay.ts@@ -12,6 +12,7 @@ import type {import { importOrigin } from "../types.js";import type { StateKV } from "../state/kv.js";import { KV, generateId, fingerprintId } from "../state/schema.js";+import { addSessionToProjectIndex } from "../state/session-index.js";import { withKeyedLock } from "../state/keyed-mutex.js";import { parseJsonlText } from "../replay/jsonl-parser.js";import { resetLessonIndex } from "./lessons.js";@@ -395,7 +396,7 @@ export function registerReplayFunctions(sdk: IIIClient, kv: StateKV): void {? firstPromptObs.userPrompt.replace(/\s+/g, " ").trim().slice(0, 200): undefined;- await withKeyedLock(`obs:${parsed.sessionId}`, async () => {+ const sessionRow = await withKeyedLock(`obs:${parsed.sessionId}`, async (): Promise<Session> => {const existing = await kv.get<Session>(KV.sessions, parsed.sessionId);if (existing) {existing.observationCount =@@ -422,6 +423,7 @@ export function registerReplayFunctions(sdk: IIIClient, kv: StateKV): void {// fallback) and is what we just used to read the row.if (!existing.id) existing.id = parsed.sessionId;await kv.set(KV.sessions, parsed.sessionId, existing);+ return existing;} else {const session: Session = {id: parsed.sessionId,@@ -435,9 +437,16 @@ export function registerReplayFunctions(sdk: IIIClient, kv: StateKV): void {firstPrompt,};await kv.set(KV.sessions, session.id, session);+ return session;}});+ await addSessionToProjectIndex(kv, sessionRow.project, {+ id: sessionRow.id,+ startedAt: sessionRow.startedAt,+ ...(sessionRow.agentId ? { agentId: sessionRow.agentId } : {}),+ }).catch(() => {});+const compressed: CompressedObservation[] = [];await Promise.all(parsed.observations.map(async (obs) => {diff --git a/src/functions/session-index-maintenance.ts b/src/functions/session-index-maintenance.tsnew file mode 100644index 00000000..8420cb3d--- /dev/null+++ b/src/functions/session-index-maintenance.ts@@ -0,0 +1,20 @@+import type { IIIClient } from "iii-sdk";+import type { StateKV } from "../state/kv.js";+import { rebuildAllProjectSessionIndexes } from "../state/session-index.js";++export function registerSessionIndexMaintenanceFunction(+ sdk: IIIClient,+ kv: StateKV,+): void {+ sdk.registerFunction(+ "mem::diagnostic::session-index-rebuild",+ async (): Promise<{+ success: true;+ projects: number;+ sessions: number;+ }> => {+ const result = await rebuildAllProjectSessionIndexes(kv);+ return { success: true, ...result };+ },+ );+}diff --git a/src/functions/smart-search.ts b/src/functions/smart-search.tsindex 1db87ff4..c8c74d49 100644--- a/src/functions/smart-search.ts+++ b/src/functions/smart-search.ts@@ -9,6 +9,10 @@ import type {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,@@ -371,6 +375,14 @@ async function findObservation(if (obs) return obs;}+ const indexedSessionId = await lookupObservationSession(kv, obsId);+ if (indexedSessionId) {+ const obs = await kv+ .get<CompressedObservation>(KV.observations(indexedSessionId), obsId)+ .catch(() => null);+ if (obs) return obs;+ }+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);@@ -379,8 +391,14 @@ async function findObservation(kv.get<CompressedObservation>(KV.observations(s.id), obsId).catch(() => null),),);- const found = results.find((r) => r !== null);- if (found) return found;+ 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 found;+ }}return null;}diff --git a/src/functions/snapshot.ts b/src/functions/snapshot.tsindex 06673845..532c448a 100644--- a/src/functions/snapshot.ts+++ b/src/functions/snapshot.ts@@ -12,6 +12,7 @@ import type {} from "../types.js";import { KV, generateId } from "../state/schema.js";import type { StateKV } from "../state/kv.js";+import { addSessionToProjectIndex } from "../state/session-index.js";import { withKeyedLock } from "../state/keyed-mutex.js";import { recordAudit } from "./audit.js";import { VERSION } from "../version.js";@@ -199,6 +200,16 @@ export function registerSnapshotFunction(await withKeyedLock(`obs:${session.id}`, () =>kv.set(KV.sessions, session.id, session),);+ const project = session.project;+ const startedAt = session.startedAt;+ if (typeof project === "string" && typeof startedAt === "string") {+ const agentId = session.agentId;+ await addSessionToProjectIndex(kv, project, {+ id: session.id,+ startedAt,+ ...(typeof agentId === "string" ? { agentId } : {}),+ }).catch(() => {});+ }}}if (state.memories) {diff --git a/src/index.ts b/src/index.tsindex c043a31f..9affa68d 100644--- a/src/index.ts+++ b/src/index.ts@@ -44,6 +44,8 @@ import {setPendingVectorBackfillCount,} from "./functions/search.js";import { registerContextFunction } from "./functions/context.js";+import { registerSessionIndexMaintenanceFunction } from "./functions/session-index-maintenance.js";+import { rebuildSessionIndexIfStale } from "./state/session-index.js";import { registerSummarizeFunction } from "./functions/summarize.js";import { registerMigrateFunction } from "./functions/migrate.js";import { registerFileIndexFunction } from "./functions/file-index.js";@@ -246,6 +248,18 @@ async function main() {registerCompressFunction(sdk, kv, provider, metricsStore);registerSearchFunction(sdk, kv);registerContextFunction(sdk, kv, config.tokenBudget);+ registerSessionIndexMaintenanceFunction(sdk, kv);+ void rebuildSessionIndexIfStale(kv)+ .then((result) => {+ if (result) {+ bootLog(+ `Session index rebuilt: ${result.projects} projects, ${result.sessions} sessions`,+ );+ }+ })+ .catch((err) => {+ console.warn(`[agentmemory] Failed to rebuild session index at boot:`, err);+ });registerSummarizeFunction(sdk, kv, provider, metricsStore);registerMigrateFunction(sdk, kv);registerFileIndexFunction(sdk, kv);diff --git a/src/state/obs-index.ts b/src/state/obs-index.tsnew file mode 100644index 00000000..bf3728af--- /dev/null+++ b/src/state/obs-index.ts@@ -0,0 +1,36 @@+import { KV } from "./schema.js";+import { StateKV } from "./kv.js";++const OBS_INDEX_SHARDS = 64;++function shardFor(obsId: string): number {+ let hash = 5381;+ for (let i = 0; i < obsId.length; i++) {+ hash = ((hash << 5) + hash + obsId.charCodeAt(i)) | 0;+ }+ return Math.abs(hash) % OBS_INDEX_SHARDS;+}++export async function indexObservationSession(+ kv: StateKV,+ obsId: string,+ sessionId: string,+): Promise<void> {+ await kv.set(KV.obsSessionIndex(shardFor(obsId)), obsId, sessionId);+}++export async function unindexObservationSession(+ kv: StateKV,+ obsId: string,+): Promise<void> {+ await kv.delete(KV.obsSessionIndex(shardFor(obsId)), obsId);+}++export async function lookupObservationSession(+ kv: StateKV,+ obsId: string,+): Promise<string | null> {+ return kv+ .get<string>(KV.obsSessionIndex(shardFor(obsId)), obsId)+ .catch(() => null);+}diff --git a/src/state/schema.ts b/src/state/schema.tsindex 773f147c..e044f280 100644--- a/src/state/schema.ts+++ b/src/state/schema.ts@@ -73,6 +73,8 @@ export const KV = {// #771: tracks the most recent smart-search call per session, used by// the followup-rate diagnostic. Key = sessionId. TTL-swept hourly.recentSearches: "mem:recent-searches",+ projectSessionsIndex: "mem:idx:project-sessions",+ obsSessionIndex: (shard: number) => `mem:idx:obs:${shard}`,} as const;export const STREAM = {diff --git a/src/state/session-index.ts b/src/state/session-index.tsnew file mode 100644index 00000000..617ac2f2--- /dev/null+++ b/src/state/session-index.ts@@ -0,0 +1,205 @@+import type { ProjectSessionIndexEntry, Session } from "../types.js";+import { KV } from "./schema.js";+import { StateKV } from "./kv.js";+import { withKeyedLock } from "./keyed-mutex.js";++const PROJECT_SESSION_INDEX_CAP = 50;+const MIN_ENTRIES_PER_AGENT = 10;++type RebuildChanges = {+ added: Map<string, ProjectSessionIndexEntry>;+ removed: Set<string>;+};++const activeRebuilds = new Set<Map<string, RebuildChanges>>();++function recordRebuildChange(+ project: string,+ apply: (changes: RebuildChanges) => void,+): void {+ for (const rebuild of activeRebuilds) {+ let changes = rebuild.get(project);+ if (!changes) {+ changes = { added: new Map(), removed: new Set() };+ rebuild.set(project, changes);+ }+ apply(changes);+ }+}++function sortByStartedAtDesc(+ entries: ProjectSessionIndexEntry[],+): ProjectSessionIndexEntry[] {+ return [...entries].sort(+ (a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime(),+ );+}++function capWithAgentFairness(+ entries: ProjectSessionIndexEntry[],+): ProjectSessionIndexEntry[] {+ const sorted = sortByStartedAtDesc(entries);+ if (sorted.length <= PROJECT_SESSION_INDEX_CAP) return sorted;++ const perAgentSeen = new Map<string, number>();+ const kept: ProjectSessionIndexEntry[] = [];+ const overflow: ProjectSessionIndexEntry[] = [];+ for (const entry of sorted) {+ if (kept.length >= PROJECT_SESSION_INDEX_CAP) {+ overflow.push(entry);+ continue;+ }+ const agentKey = entry.agentId ?? "";+ const seen = perAgentSeen.get(agentKey) ?? 0;+ if (seen < MIN_ENTRIES_PER_AGENT) {+ kept.push(entry);+ perAgentSeen.set(agentKey, seen + 1);+ } else {+ overflow.push(entry);+ }+ }++ const remainingSlots = PROJECT_SESSION_INDEX_CAP - kept.length;+ if (remainingSlots > 0) kept.push(...overflow.slice(0, remainingSlots));+ return sortByStartedAtDesc(kept);+}++async function loadStoredProjectSessionEntries(+ kv: StateKV,+ project: string,+): Promise<ProjectSessionIndexEntry[]> {+ const sessions = await kv.list<Session>(KV.sessions);+ return sessions+ .filter((s) => s.project === project)+ .map((s) => ({+ id: s.id,+ startedAt: s.startedAt,+ ...(s.agentId ? { agentId: s.agentId } : {}),+ }));+}++export async function getProjectSessionIndex(+ kv: StateKV,+ project: string,+): Promise<ProjectSessionIndexEntry[] | null> {+ return kv+ .get<ProjectSessionIndexEntry[]>(KV.projectSessionsIndex, project)+ .catch(() => null);+}++export async function addSessionToProjectIndex(+ kv: StateKV,+ project: string,+ entry: ProjectSessionIndexEntry,+): Promise<void> {+ await withKeyedLock(`project-session-index:${project}`, async () => {+ const existing = await getProjectSessionIndex(kv, project);+ const base = existing ?? (await loadStoredProjectSessionEntries(kv, project));+ const merged = base.filter((e) => e.id !== entry.id);+ merged.push(entry);+ recordRebuildChange(project, (changes) => {+ changes.removed.delete(entry.id);+ changes.added.set(entry.id, entry);+ });+ try {+ await kv.set(KV.projectSessionsIndex, project, capWithAgentFairness(merged));+ } catch (err) {+ await kv.delete(KV.projectSessionsIndex, project).catch(() => {});+ throw err;+ }+ });+}++export async function removeSessionFromProjectIndex(+ kv: StateKV,+ project: string,+ sessionId: string,+): Promise<void> {+ await withKeyedLock(`project-session-index:${project}`, async () => {+ recordRebuildChange(project, (changes) => {+ changes.added.delete(sessionId);+ changes.removed.add(sessionId);+ });+ const existing = await getProjectSessionIndex(kv, project);+ if (!existing) return;+ const next = existing.filter((e) => e.id !== sessionId);+ if (next.length === existing.length) return;+ await kv.set(KV.projectSessionsIndex, project, next);+ });+}++export function buildProjectSessionIndex(+ sessions: ProjectSessionIndexEntry[],+): ProjectSessionIndexEntry[] {+ return capWithAgentFairness(sessions);+}++export async function ensureProjectSessionIndex(+ kv: StateKV,+ project: string,+ fallbackSessions: ProjectSessionIndexEntry[],+): Promise<ProjectSessionIndexEntry[]> {+ return withKeyedLock(`project-session-index:${project}`, async () => {+ const existing = await getProjectSessionIndex(kv, project);+ if (existing !== null) return existing;+ const next = buildProjectSessionIndex(fallbackSessions);+ await kv.set(KV.projectSessionsIndex, project, next).catch(() => {});+ return next;+ });+}++export async function rebuildAllProjectSessionIndexes(+ kv: StateKV,+): Promise<{ projects: number; sessions: number }> {+ const changesSinceListing = new Map<string, RebuildChanges>();+ activeRebuilds.add(changesSinceListing);+ try {+ const sessions = await kv.list<Session>(KV.sessions);+ const byProject = new Map<string, ProjectSessionIndexEntry[]>();+ for (const session of sessions) {+ if (!session.project) continue;+ const entry: ProjectSessionIndexEntry = {+ id: session.id,+ startedAt: session.startedAt,+ ...(session.agentId ? { agentId: session.agentId } : {}),+ };+ const bucket = byProject.get(session.project);+ if (bucket) bucket.push(entry);+ else byProject.set(session.project, [entry]);+ }+ for (const [project, entries] of byProject) {+ await withKeyedLock(`project-session-index:${project}`, () => {+ const changes = changesSinceListing.get(project);+ const next = changes+ ? [+ ...entries.filter(+ (e) => !changes.removed.has(e.id) && !changes.added.has(e.id),+ ),+ ...changes.added.values(),+ ]+ : entries;+ return kv.set(+ KV.projectSessionsIndex,+ project,+ buildProjectSessionIndex(next),+ );+ });+ }+ return { projects: byProject.size, sessions: sessions.length };+ } finally {+ activeRebuilds.delete(changesSinceListing);+ }+}++const SESSION_INDEX_GENERATION_KEY = "session-index-generation";+const SESSION_INDEX_GENERATION = 1;++export async function rebuildSessionIndexIfStale(+ kv: StateKV,+): Promise<{ projects: number; sessions: number } | null> {+ const marker = await kv.get<number>(KV.config, SESSION_INDEX_GENERATION_KEY);+ if (marker === SESSION_INDEX_GENERATION) return null;+ const result = await rebuildAllProjectSessionIndexes(kv);+ await kv.set(KV.config, SESSION_INDEX_GENERATION_KEY, SESSION_INDEX_GENERATION);+ return result;+}diff --git a/src/triggers/api.ts b/src/triggers/api.tsindex 752ec03c..d8831057 100644--- a/src/triggers/api.ts+++ b/src/triggers/api.ts@@ -6,6 +6,7 @@ import { withKeyedLock } from "../state/keyed-mutex.js";import { KV } from "../state/schema.js";import { checkPayloadFrameSize } from "../state/frame-guard.js";import { StateKV } from "../state/kv.js";+import { addSessionToProjectIndex } from "../state/session-index.js";import { getLatestHealth } from "../health/monitor.js";import type { MetricsStore } from "../eval/metrics-store.js";import type { ResilientProvider } from "../providers/resilient.js";@@ -754,6 +755,16 @@ export function registerApiTriggers(await kv.set(KV.sessions, sessionId, merged);return merged;});+ await addSessionToProjectIndex(kv, project, {+ id: sessionId,+ startedAt: session.startedAt,+ ...(session.agentId ? { agentId: session.agentId } : {}),+ }).catch((err) => {+ logger.warn("session index update failed", {+ sessionId,+ error: err instanceof Error ? err.message : String(err),+ });+ });const contextResult = await sdk.trigger<{ sessionId: string; project: string; agentId?: string },{ context: string }diff --git a/src/triggers/events.ts b/src/triggers/events.tsindex c3187ce5..88ee2433 100644--- a/src/triggers/events.ts+++ b/src/triggers/events.ts@@ -2,6 +2,7 @@ import { TriggerAction, type IIIClient } from "iii-sdk";import type { CompressedObservation, HookPayload, Memory, Session } from "../types.js";import { KV, STREAM } from "../state/schema.js";import { StateKV } from "../state/kv.js";+import { addSessionToProjectIndex } from "../state/session-index.js";import { withKeyedLock } from "../state/keyed-mutex.js";import { isReflectEnabled } from "../functions/slots.js";import {@@ -78,6 +79,16 @@ export function registerEventTriggers(sdk: IIIClient, kv: StateKV): void {await kv.set(KV.sessions, data.sessionId, merged);return merged;});+ await addSessionToProjectIndex(kv, session.project, {+ id: session.id,+ startedAt: session.startedAt,+ ...(session.agentId ? { agentId: session.agentId } : {}),+ }).catch((err) => {+ logger.warn("session index update failed", {+ sessionId: session.id,+ error: err instanceof Error ? err.message : String(err),+ });+ });const contextResult = await sdk.trigger<{ sessionId: string; project: string; agentId?: string },{ context: string }diff --git a/src/types.ts b/src/types.tsindex 4ee305bc..7b3a312a 100644--- a/src/types.ts+++ b/src/types.ts@@ -14,6 +14,12 @@ export interface Session {agentId?: string;}+export interface ProjectSessionIndexEntry {+ id: string;+ startedAt: string;+ agentId?: string;+}+export interface CommitLink {sha: string;shortSha: string;diff --git a/test/evict.test.ts b/test/evict.test.tsindex 690e8a7c..69786cbd 100644--- a/test/evict.test.ts+++ b/test/evict.test.ts@@ -6,6 +6,10 @@ import type {} from "../src/types.js";import { registerEvictFunction } from "../src/functions/evict.js";import { KV } from "../src/state/schema.js";+import {+ indexObservationSession,+ lookupObservationSession,+} from "../src/state/obs-index.js";vi.mock("../src/logger.js", () => ({logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },@@ -167,6 +171,40 @@ describe("mem::evict stale sessions", () => {);});+ it("drops the reverse-index entries of an evicted session's observations", async () => {+ const sessionId = "ses_stale_indexed";+ const store = storeForObservedSession(sessionId);+ const kv = mockKV(store);+ const { sdk } = mockSdk();++ registerEvictFunction(sdk as never, kv as never);+ sdk.registerFunction("event::session::stopped", async () => ({+ success: true,+ }));+ sdk.registerFunction("mem::consolidate-pipeline", () => ({+ success: true,+ }));+ sdk.registerFunction("mem::auto-crystallize", () => ({ success: true }));++ const observations = await kv.list<CompressedObservation>(+ KV.observations(sessionId),+ );+ expect(observations.length).toBeGreaterThan(0);+ for (const o of observations) {+ await indexObservationSession(kv as never, o.id, sessionId);+ }++ const result = (await sdk.trigger({+ function_id: "mem::evict",+ payload: {},+ })) as { staleSessions: number };++ expect(result.staleSessions).toBe(1);+ for (const o of observations) {+ expect(await lookupObservationSession(kv as never, o.id)).toBeNull();+ }+ });+it("bounds consolidation to one pass regardless of how many stale sessions are recovered", async () => {// Regression (P1): before the skipConsolidation guard, N recovered// sessions each triggered a forced full-corpus consolidate + crystallizediff --git a/test/obs-index.test.ts b/test/obs-index.test.tsnew file mode 100644index 00000000..80dcc2b7--- /dev/null+++ b/test/obs-index.test.ts@@ -0,0 +1,187 @@+import { describe, it, expect, beforeEach, vi } from "vitest";++vi.mock("../src/logger.js", () => ({+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },+}));++import { registerSmartSearchFunction } from "../src/functions/smart-search.js";+import {+ indexObservationSession,+ unindexObservationSession,+ lookupObservationSession,+} from "../src/state/obs-index.js";+import { KV } from "../src/state/schema.js";+import type { CompressedObservation, HybridSearchResult } from "../src/types.js";++function mockKV() {+ const store = new Map<string, Map<string, unknown>>();+ return {+ get: vi.fn(async <T>(scope: string, key: string): Promise<T | null> => {+ return (store.get(scope)?.get(key) as T) ?? null;+ }),+ set: vi.fn(async <T>(scope: string, key: string, data: T): Promise<T> => {+ if (!store.has(scope)) store.set(scope, new Map());+ store.get(scope)!.set(key, data);+ return data;+ }),+ delete: vi.fn(async (scope: string, key: string): Promise<void> => {+ store.get(scope)?.delete(key);+ }),+ list: vi.fn(async <T>(scope: string): Promise<T[]> => {+ const entries = store.get(scope);+ return entries ? (Array.from(entries.values()) as T[]) : [];+ }),+ };+}++function mockSdk() {+ const functions = new Map<string, Function>();+ return {+ registerFunction: (+ idOrOpts: string | { id: string },+ handler: Function,+ ) => {+ const id = typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id;+ functions.set(id, handler);+ },+ registerTrigger: () => {},+ trigger: async (+ idOrInput: string | { function_id: string; payload: unknown },+ data?: unknown,+ ) => {+ const id =+ typeof idOrInput === "string" ? idOrInput : idOrInput.function_id;+ const payload = typeof idOrInput === "string" ? data : idOrInput.payload;+ const fn = functions.get(id);+ if (!fn) throw new Error(`No function: ${id}`);+ return fn(payload);+ },+ };+}++function makeObs(+ overrides: Partial<CompressedObservation> = {},+): CompressedObservation {+ return {+ id: "obs_1",+ sessionId: "ses_1",+ timestamp: "2026-02-01T10:00:00Z",+ type: "file_edit",+ title: "Edit auth handler",+ facts: [],+ narrative: "Modified auth",+ concepts: ["auth"],+ files: ["src/auth.ts"],+ importance: 7,+ ...overrides,+ };+}++describe("obs-session reverse index — maintenance (kv-access finding 6)", () => {+ let kv: ReturnType<typeof mockKV>;++ beforeEach(() => {+ kv = mockKV();+ });++ it("indexObservationSession writes a lookup entry", async () => {+ await indexObservationSession(kv as never, "obs_a", "ses_a");+ expect(await lookupObservationSession(kv as never, "obs_a")).toBe("ses_a");+ });++ it("unindexObservationSession removes the entry", async () => {+ await indexObservationSession(kv as never, "obs_a", "ses_a");+ await unindexObservationSession(kv as never, "obs_a");+ expect(await lookupObservationSession(kv as never, "obs_a")).toBeNull();+ });++ it("lookupObservationSession returns null for an unknown id", async () => {+ expect(await lookupObservationSession(kv as never, "obs_never_seen")).toBeNull();+ });++ it("shards writes across multiple KV scopes rather than one giant scope", async () => {+ const ids = Array.from({ length: 40 }, (_, i) => `obs_${i}_${"x".repeat(i % 5)}`);+ for (const id of ids) {+ await indexObservationSession(kv as never, id, "ses_shared");+ }++ const scopesTouched = new Set(+ kv.set.mock.calls+ .map(([scope]) => scope as string)+ .filter((scope) => scope.startsWith("mem:idx:obs:")),+ );+ expect(scopesTouched.size).toBeGreaterThan(1);+ for (const scope of scopesTouched) {+ expect(scope).toMatch(/^mem:idx:obs:\d+$/);+ }+ });+});++describe("mem::smart-search expandIds — uses the reverse index (kv-access finding 6)", () => {+ let sdk: ReturnType<typeof mockSdk>;+ let kv: ReturnType<typeof mockKV>;++ beforeEach(async () => {+ sdk = mockSdk();+ kv = mockKV();+ const searchFn = async (+ _query: string,+ _limit: number,+ ): Promise<HybridSearchResult[]> => [];+ registerSmartSearchFunction(sdk as never, kv as never, searchFn);+ });++ it("finds an observation via the reverse index without scanning every session", async () => {+ const obs = makeObs({ id: "obs_indexed", sessionId: "ses_target" });+ await kv.set(KV.observations("ses_target"), "obs_indexed", obs);+ await indexObservationSession(kv as never, "obs_indexed", "ses_target");++ const decoySessions = Array.from({ length: 8 }, (_, i) => ({+ id: `ses_decoy_${i}`,+ }));+ await Promise.all(+ decoySessions.map((s) => kv.set(KV.sessions, s.id, s)),+ );+ kv.list.mockClear();++ const result = (await sdk.trigger("mem::smart-search", {+ expandIds: ["obs_indexed"],+ })) as { mode: string; results: Array<{ observation: CompressedObservation }> };++ expect(result.results.length).toBe(1);+ expect(result.results[0].observation.title).toBe("Edit auth handler");+ expect(+ kv.list.mock.calls.some(([scope]) => scope === KV.sessions),+ ).toBe(false);+ });++ it("falls back to scanning sessions when the reverse index has no entry, then backfills it", async () => {+ const obs = makeObs({ id: "obs_unindexed", sessionId: "ses_fallback" });+ await kv.set(KV.sessions, "ses_fallback", { id: "ses_fallback" });+ await kv.set(KV.observations("ses_fallback"), "obs_unindexed", obs);++ expect(+ await lookupObservationSession(kv as never, "obs_unindexed"),+ ).toBeNull();++ const result = (await sdk.trigger("mem::smart-search", {+ expandIds: ["obs_unindexed"],+ })) as { mode: string; results: Array<{ observation: CompressedObservation }> };++ expect(result.results.length).toBe(1);+ expect(result.results[0].observation.id).toBe("obs_unindexed");++ expect(+ await lookupObservationSession(kv as never, "obs_unindexed"),+ ).toBe("ses_fallback");+ });++ it("returns nothing for an id that exists nowhere, without throwing", async () => {+ const result = (await sdk.trigger("mem::smart-search", {+ expandIds: ["obs_does_not_exist"],+ })) as { mode: string; results: unknown[] };++ expect(result.mode).toBe("expanded");+ expect(result.results.length).toBe(0);+ });+});diff --git a/test/session-index-self-heal.test.ts b/test/session-index-self-heal.test.tsnew file mode 100644index 00000000..064433ae--- /dev/null+++ b/test/session-index-self-heal.test.ts@@ -0,0 +1,244 @@+import { describe, it, expect, vi, beforeEach } from "vitest";+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++vi.mock("../src/logger.js", () => ({+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },+}));++vi.mock("../src/config.js", async (importOriginal) => ({+ ...(await importOriginal<typeof import("../src/config.js")>()),+ isConsolidationEnabled: () => false,+}));++import { registerEvictFunction } from "../src/functions/evict.js";+import { registerRememberFunction } from "../src/functions/remember.js";+import { registerExportImportFunction } from "../src/functions/export-import.js";+import { registerReplayFunctions } from "../src/functions/replay.js";+import {+ getProjectSessionIndex,+ rebuildAllProjectSessionIndexes,+} from "../src/state/session-index.js";+import { KV } from "../src/state/schema.js";+import type { Session, ExportData } from "../src/types.js";++function mockKV() {+ const store = new Map<string, Map<string, unknown>>();+ return {+ get: vi.fn(async <T>(scope: string, key: string): Promise<T | null> => {+ return (store.get(scope)?.get(key) as T) ?? null;+ }),+ set: vi.fn(async <T>(scope: string, key: string, data: T): Promise<T> => {+ if (!store.has(scope)) store.set(scope, new Map());+ store.get(scope)!.set(key, data);+ return data;+ }),+ delete: vi.fn(async (scope: string, key: string): Promise<void> => {+ store.get(scope)?.delete(key);+ }),+ list: vi.fn(async <T>(scope: string): Promise<T[]> => {+ if (!store.has(scope)) return [];+ return Array.from(store.get(scope)!.values()) as T[];+ }),+ };+}++function mockSdk() {+ const functions = new Map<string, Function>();+ return {+ registerFunction: (idOrOpts: string | { id: string }, handler: Function) => {+ const id = typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id;+ functions.set(id, handler);+ },+ registerTrigger: () => {},+ trigger: async (+ idOrInput: string | { function_id: string; payload: unknown },+ data?: unknown,+ ) => {+ const id =+ typeof idOrInput === "string" ? idOrInput : idOrInput.function_id;+ const payload = typeof idOrInput === "string" ? data : idOrInput.payload;+ const fn = functions.get(id);+ if (!fn) throw new Error(`No function: ${id}`);+ return fn(payload);+ },+ };+}++function daysAgo(days: number): string {+ return new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();+}++function makeStaleSession(id: string, project: string): Session {+ return {+ id,+ project,+ cwd: `/repo/${project}`,+ startedAt: daysAgo(31),+ status: "active",+ observationCount: 0,+ };+}++describe("mem::forget self-heals the project session index", () => {+ it("removes the forgotten session from its project's index", async () => {+ const sdk = mockSdk();+ const kv = mockKV();+ registerRememberFunction(sdk as never, kv as never);++ const session = makeStaleSession("ses_forget", "proj-forget");+ await kv.set(KV.sessions, session.id, session);+ await rebuildAllProjectSessionIndexes(kv as never);+ expect(+ (await getProjectSessionIndex(kv as never, "proj-forget"))?.map((e) => e.id),+ ).toEqual(["ses_forget"]);++ await sdk.trigger({+ function_id: "mem::forget",+ payload: { sessionId: "ses_forget" },+ });++ expect(await getProjectSessionIndex(kv as never, "proj-forget")).toEqual([]);+ });+});++describe("mem::evict bulk removal", () => {+ it("removes 100 stale sessions from one project with at most one sessions listing", async () => {+ const sdk = mockSdk();+ const kv = mockKV();+ registerEvictFunction(sdk as never, kv as never);++ const ids: string[] = [];+ for (let i = 0; i < 100; i++) {+ const id = `ses_bulk_${i}`;+ ids.push(id);+ await kv.set(KV.sessions, id, makeStaleSession(id, "proj-bulk"));+ }+ await rebuildAllProjectSessionIndexes(kv as never);+ expect(+ (await getProjectSessionIndex(kv as never, "proj-bulk"))?.length,+ ).toBe(50);++ kv.list.mockClear();+ kv.get.mockClear();+ kv.set.mockClear();+ kv.delete.mockClear();++ const result = (await sdk.trigger({+ function_id: "mem::evict",+ payload: {},+ })) as { staleSessions: number };++ expect(result.staleSessions).toBe(100);+ expect(+ kv.list.mock.calls.filter((c) => c[0] === KV.sessions),+ ).toHaveLength(1);+ expect(await getProjectSessionIndex(kv as never, "proj-bulk")).toEqual([]);+ for (const id of ids) {+ expect(await kv.get(KV.sessions, id)).toBeNull();+ }+ });+});++describe("mem::import replace strategy bulk removal", () => {+ it("clears 100 sessions from one project with at most one sessions listing", async () => {+ const sdk = mockSdk();+ const kv = mockKV();+ registerExportImportFunction(sdk as never, kv as never);++ for (let i = 0; i < 100; i++) {+ const id = `ses_old_${i}`;+ await kv.set(KV.sessions, id, makeStaleSession(id, "proj-old"));+ }+ await rebuildAllProjectSessionIndexes(kv as never);+ expect(+ (await getProjectSessionIndex(kv as never, "proj-old"))?.length,+ ).toBe(50);++ kv.list.mockClear();++ const exportData: ExportData = {+ version: "0.9.28",+ exportedAt: new Date().toISOString(),+ sessions: [+ {+ id: "ses_new",+ project: "proj-old",+ cwd: "/repo/proj-old",+ startedAt: new Date().toISOString(),+ status: "active",+ observationCount: 0,+ },+ ],+ observations: {},+ memories: [],+ summaries: [],+ };++ const result = (await sdk.trigger({+ function_id: "mem::import",+ payload: { exportData, strategy: "replace" },+ })) as { success: boolean; sessions: number };++ expect(result.success).toBe(true);+ expect(result.sessions).toBe(1);+ expect(+ kv.list.mock.calls.filter((c) => c[0] === KV.sessions),+ ).toHaveLength(1);++ const newIndex = await getProjectSessionIndex(kv as never, "proj-old");+ expect(newIndex?.map((e) => e.id)).toEqual(["ses_new"]);+ });+});++describe("mem::replay::import-jsonl self-heals the project session index", () => {+ let tmpRoot: string;++ beforeEach(() => {+ tmpRoot = mkdtempSync(join(tmpdir(), "replay-session-index-"));+ });++ it("adds a newly imported session to its project's index", async () => {+ const dir = join(tmpRoot, "proj");+ mkdirSync(dir, { recursive: true });+ const sessionId = "sess-replay-heal";+ const ts = "2026-04-17T10:00:00.000Z";+ const lines = [+ JSON.stringify({+ type: "user",+ uuid: "u1",+ sessionId,+ timestamp: ts,+ cwd: tmpRoot,+ message: { role: "user", content: [{ type: "text", text: "hello" }] },+ }),+ JSON.stringify({+ type: "assistant",+ uuid: "a1",+ sessionId,+ timestamp: ts,+ message: { role: "assistant", content: [{ type: "text", text: "world" }] },+ }),+ ];+ writeFileSync(join(dir, `${sessionId}.jsonl`), lines.join("\n") + "\n");++ const sdk = mockSdk();+ const kv = mockKV();+ registerReplayFunctions(sdk as never, kv as never);++ const result = (await sdk.trigger({+ function_id: "mem::replay::import-jsonl",+ payload: { path: tmpRoot },+ })) as { success: boolean; imported?: number; sessionIds?: string[] };++ expect(result.success).toBe(true);+ expect(result.imported).toBe(1);+ const importedSessionId = result.sessionIds?.[0];+ expect(importedSessionId).toBeDefined();++ const session = await kv.get<Session>(KV.sessions, importedSessionId!);+ const index = await getProjectSessionIndex(kv as never, session!.project);+ expect(index?.map((e) => e.id)).toContain(importedSessionId);+ });+});diff --git a/test/session-index.test.ts b/test/session-index.test.tsnew file mode 100644index 00000000..ba9ec739--- /dev/null+++ b/test/session-index.test.ts@@ -0,0 +1,532 @@+import { describe, it, expect, beforeEach, vi } from "vitest";+import { registerContextFunction } from "../src/functions/context.js";+import {+ addSessionToProjectIndex,+ removeSessionFromProjectIndex,+ getProjectSessionIndex,+ buildProjectSessionIndex,+ ensureProjectSessionIndex,+ rebuildAllProjectSessionIndexes,+ rebuildSessionIndexIfStale,+} from "../src/state/session-index.js";+import { KV } from "../src/state/schema.js";+import type { Session } from "../src/types.js";++function mockKV(listFailures: Set<string> = new Set()) {+ const store = new Map<string, Map<string, unknown>>();+ return {+ get: vi.fn(async <T>(scope: string, key: string): Promise<T | null> => {+ return (store.get(scope)?.get(key) as T) ?? null;+ }),+ set: vi.fn(async <T>(scope: string, key: string, data: T): Promise<T> => {+ if (!store.has(scope)) store.set(scope, new Map());+ store.get(scope)!.set(key, data);+ return data;+ }),+ delete: vi.fn(async (scope: string, key: string): Promise<void> => {+ store.get(scope)?.delete(key);+ }),+ list: vi.fn(async <T>(scope: string): Promise<T[]> => {+ if (listFailures.has(scope)) {+ throw new Error(`list failed for ${scope}`);+ }+ if (!store.has(scope)) return [];+ return Array.from(store.get(scope)!.values()) as T[];+ }),+ };+}++type ContextHandler = (data: {+ sessionId: string;+ project: string;+ budget?: number;+}) => Promise<{ context: string; blocks: number; tokens: number }>;++function wireContext(kv: ReturnType<typeof mockKV>, budget = 4000) {+ let handler: ContextHandler | undefined;+ const sdk = {+ registerFunction: vi.fn((id: string, cb: ContextHandler) => {+ if (id === "mem::context") handler = cb;+ }),+ } as unknown as import("iii-sdk").IIIClient;+ registerContextFunction(sdk, kv as never, budget);+ if (!handler) throw new Error("mem::context not registered");+ return handler;+}++function makeSession(over: Partial<Session> = {}): Session {+ return {+ id: over.id ?? `ses_${Math.random().toString(36).slice(2)}`,+ project: over.project ?? "/tmp/proj",+ cwd: over.cwd ?? "/tmp/proj",+ startedAt: over.startedAt ?? new Date().toISOString(),+ status: over.status ?? "completed",+ observationCount: over.observationCount ?? 0,+ agentId: over.agentId,+ };+}++describe("project session index — maintenance (kv-access finding 3)", () => {+ let kv: ReturnType<typeof mockKV>;++ beforeEach(() => {+ kv = mockKV();+ });++ it("addSessionToProjectIndex creates the index for a new project", async () => {+ await addSessionToProjectIndex(kv as never, "proj-a", {+ id: "ses_1",+ startedAt: "2026-01-01T00:00:00Z",+ });++ const index = await getProjectSessionIndex(kv as never, "proj-a");+ expect(index).toEqual([{ id: "ses_1", startedAt: "2026-01-01T00:00:00Z" }]);+ });++ it("drops the project index when an add cannot be written, so the next read rebuilds it", async () => {+ await addSessionToProjectIndex(kv as never, "proj-a", {+ id: "ses_1",+ startedAt: "2026-01-01T00:00:00Z",+ });+ kv.set.mockRejectedValueOnce(new Error("write failed"));++ await expect(+ addSessionToProjectIndex(kv as never, "proj-a", {+ id: "ses_2",+ startedAt: "2026-01-02T00:00:00Z",+ }),+ ).rejects.toThrow("write failed");++ expect(await getProjectSessionIndex(kv as never, "proj-a")).toBeNull();+ });++ it("keeps entries sorted most-recent-first and dedups by id", async () => {+ await addSessionToProjectIndex(kv as never, "proj-a", {+ id: "ses_1",+ startedAt: "2026-01-01T00:00:00Z",+ });+ await addSessionToProjectIndex(kv as never, "proj-a", {+ id: "ses_2",+ startedAt: "2026-01-03T00:00:00Z",+ });+ await addSessionToProjectIndex(kv as never, "proj-a", {+ id: "ses_1",+ startedAt: "2026-01-05T00:00:00Z",+ });++ const index = await getProjectSessionIndex(kv as never, "proj-a");+ expect(index?.map((e) => e.id)).toEqual(["ses_1", "ses_2"]);+ expect(index?.length).toBe(2);+ });++ it("caps the index at 50 entries, dropping the oldest", async () => {+ for (let i = 0; i < 55; i++) {+ await addSessionToProjectIndex(kv as never, "proj-cap", {+ id: `ses_${i}`,+ startedAt: new Date(2026, 0, 1, 0, 0, i).toISOString(),+ });+ }++ const index = await getProjectSessionIndex(kv as never, "proj-cap");+ expect(index?.length).toBe(50);+ expect(index?.map((e) => e.id)).not.toContain("ses_0");+ expect(index?.map((e) => e.id)).not.toContain("ses_4");+ expect(index?.map((e) => e.id)).toContain("ses_54");+ });++ it("removeSessionFromProjectIndex drops the entry", async () => {+ await addSessionToProjectIndex(kv as never, "proj-a", {+ id: "ses_1",+ startedAt: "2026-01-01T00:00:00Z",+ });+ await addSessionToProjectIndex(kv as never, "proj-a", {+ id: "ses_2",+ startedAt: "2026-01-02T00:00:00Z",+ });++ await removeSessionFromProjectIndex(kv as never, "proj-a", "ses_1");++ const index = await getProjectSessionIndex(kv as never, "proj-a");+ expect(index?.map((e) => e.id)).toEqual(["ses_2"]);+ });++ it("removeSessionFromProjectIndex is a no-op when no index exists yet", async () => {+ await expect(+ removeSessionFromProjectIndex(kv as never, "proj-never-seen", "ses_x"),+ ).resolves.toBeUndefined();+ expect(await getProjectSessionIndex(kv as never, "proj-never-seen")).toBeNull();+ });++ it("buildProjectSessionIndex sorts and caps a raw session list", () => {+ const entries = buildProjectSessionIndex(+ Array.from({ length: 5 }, (_, i) => ({+ id: `ses_${i}`,+ startedAt: new Date(2026, 0, i + 1).toISOString(),+ })),+ );+ expect(entries.map((e) => e.id)).toEqual([+ "ses_4",+ "ses_3",+ "ses_2",+ "ses_1",+ "ses_0",+ ]);+ });++ it("addSessionToProjectIndex builds the initial index from stored sessions, not just the new entry", async () => {+ await kv.set(KV.sessions, "ses_old_1", {+ id: "ses_old_1",+ project: "proj-cold",+ startedAt: "2026-01-01T00:00:00Z",+ });+ await kv.set(KV.sessions, "ses_old_2", {+ id: "ses_old_2",+ project: "proj-cold",+ startedAt: "2026-01-02T00:00:00Z",+ });+ await kv.set(KV.sessions, "ses_other_project", {+ id: "ses_other_project",+ project: "proj-unrelated",+ startedAt: "2026-01-03T00:00:00Z",+ });++ await addSessionToProjectIndex(kv as never, "proj-cold", {+ id: "ses_new",+ startedAt: "2026-01-04T00:00:00Z",+ });++ const index = await getProjectSessionIndex(kv as never, "proj-cold");+ expect(index?.map((e) => e.id).sort()).toEqual([+ "ses_new",+ "ses_old_1",+ "ses_old_2",+ ]);+ });++ it("ensureProjectSessionIndex recheck-under-lock never discards a concurrently added session", async () => {+ await addSessionToProjectIndex(kv as never, "proj-race", {+ id: "ses_concurrent",+ startedAt: "2026-01-02T00:00:00Z",+ });++ const stale = await ensureProjectSessionIndex(kv as never, "proj-race", [+ { id: "ses_stale_scan", startedAt: "2026-01-01T00:00:00Z" },+ ]);++ expect(stale.map((e) => e.id)).toEqual(["ses_concurrent"]);+ const index = await getProjectSessionIndex(kv as never, "proj-race");+ expect(index?.map((e) => e.id)).toEqual(["ses_concurrent"]);+ });++ it("keeps a low-volume agent's sessions in the index alongside a high-volume agent", async () => {+ for (let i = 0; i < 60; i++) {+ await addSessionToProjectIndex(kv as never, "proj-fair", {+ id: `busy_${i}`,+ startedAt: new Date(2026, 0, 1, 0, 0, i).toISOString(),+ agentId: "agent-busy",+ });+ }+ for (let i = 0; i < 3; i++) {+ await addSessionToProjectIndex(kv as never, "proj-fair", {+ id: `quiet_${i}`,+ startedAt: new Date(2025, 0, 1, 0, 0, i).toISOString(),+ agentId: "agent-quiet",+ });+ }++ const index = await getProjectSessionIndex(kv as never, "proj-fair");+ expect(index?.length).toBe(50);+ const quietIds = index?.filter((e) => e.agentId === "agent-quiet").map((e) => e.id);+ expect(quietIds?.sort()).toEqual(["quiet_0", "quiet_1", "quiet_2"]);+ });++ it("drops the entry at the cap boundary without rescanning stored sessions", async () => {+ for (let i = 0; i < 51; i++) {+ const id = `ses_${i}`;+ const startedAt = new Date(2026, 0, 1, 0, 0, i).toISOString();+ await kv.set(KV.sessions, id, { id, project: "proj-replenish", startedAt });+ await addSessionToProjectIndex(kv as never, "proj-replenish", { id, startedAt });+ }++ const before = await getProjectSessionIndex(kv as never, "proj-replenish");+ expect(before?.length).toBe(50);+ expect(before?.map((e) => e.id)).not.toContain("ses_0");++ const newest = before![0].id;+ kv.list.mockClear();+ await removeSessionFromProjectIndex(kv as never, "proj-replenish", newest);++ expect(kv.list.mock.calls.filter((c) => c[0] === KV.sessions)).toHaveLength(0);+ const after = await getProjectSessionIndex(kv as never, "proj-replenish");+ expect(after?.length).toBe(49);+ expect(after?.map((e) => e.id)).not.toContain("ses_0");+ expect(after?.map((e) => e.id)).not.toContain(newest);+ });++ it("does not rescan stored sessions when the index was below the cap", async () => {+ for (let i = 0; i < 5; i++) {+ const id = `small_${i}`;+ const startedAt = new Date(2026, 0, 1, 0, 0, i).toISOString();+ await kv.set(KV.sessions, id, { id, project: "proj-small", startedAt });+ await addSessionToProjectIndex(kv as never, "proj-small", { id, startedAt });+ }+ kv.list.mockClear();+ await removeSessionFromProjectIndex(kv as never, "proj-small", "small_4");+ expect(kv.list.mock.calls.filter((c) => c[0] === KV.sessions)).toHaveLength(0);+ const after = await getProjectSessionIndex(kv as never, "proj-small");+ expect(after?.map((e) => e.id)).toEqual(["small_3", "small_2", "small_1", "small_0"]);+ });++ it("removing 100 sessions one at a time never lists the sessions scope", async () => {+ const ids: string[] = [];+ for (let i = 0; i < 100; i++) {+ const id = `bulk_${i}`;+ const startedAt = new Date(2026, 0, 1, 0, 0, i).toISOString();+ ids.push(id);+ await kv.set(KV.sessions, id, { id, project: "proj-bulk", startedAt });+ await addSessionToProjectIndex(kv as never, "proj-bulk", { id, startedAt });+ }+ kv.list.mockClear();++ for (const id of ids) {+ await removeSessionFromProjectIndex(kv as never, "proj-bulk", id);+ }++ expect(kv.list.mock.calls.filter((c) => c[0] === KV.sessions)).toHaveLength(0);+ const after = await getProjectSessionIndex(kv as never, "proj-bulk");+ expect(after).toEqual([]);+ });++ it("does not persist an index when the cold-seed list fails", async () => {+ const failingKv = mockKV(new Set([KV.sessions]));++ await expect(+ addSessionToProjectIndex(failingKv as never, "proj-fail", {+ id: "ses_new",+ startedAt: "2026-01-01T00:00:00Z",+ }),+ ).rejects.toThrow();++ expect(await getProjectSessionIndex(failingKv as never, "proj-fail")).toBeNull();+ expect(+ failingKv.set.mock.calls.some(([scope]) => scope === KV.projectSessionsIndex),+ ).toBe(false);+ });+});++describe("rebuildAllProjectSessionIndexes / rebuildSessionIndexIfStale", () => {+ let kv: ReturnType<typeof mockKV>;++ beforeEach(() => {+ kv = mockKV();+ });++ it("rebuilds every project's index from a single sessions listing", async () => {+ await kv.set(KV.sessions, "a1", { id: "a1", project: "proj-a", startedAt: "2026-01-01T00:00:00Z" });+ await kv.set(KV.sessions, "a2", { id: "a2", project: "proj-a", startedAt: "2026-01-02T00:00:00Z" });+ await kv.set(KV.sessions, "b1", { id: "b1", project: "proj-b", startedAt: "2026-01-01T00:00:00Z" });+ kv.list.mockClear();++ const result = await rebuildAllProjectSessionIndexes(kv as never);++ expect(result).toEqual({ projects: 2, sessions: 3 });+ expect(kv.list.mock.calls.filter((c) => c[0] === KV.sessions)).toHaveLength(1);++ const indexA = await getProjectSessionIndex(kv as never, "proj-a");+ expect(indexA?.map((e) => e.id).sort()).toEqual(["a1", "a2"]);+ const indexB = await getProjectSessionIndex(kv as never, "proj-b");+ expect(indexB?.map((e) => e.id)).toEqual(["b1"]);+ });++ it("rejects and writes nothing when the sessions listing fails", async () => {+ const failingKv = mockKV(new Set([KV.sessions]));++ await expect(rebuildAllProjectSessionIndexes(failingKv as never)).rejects.toThrow();+ expect(+ failingKv.set.mock.calls.some(([scope]) => scope === KV.projectSessionsIndex),+ ).toBe(false);+ });++ it("rebuilds once per generation and skips a matching marker", async () => {+ await kv.set(KV.sessions, "a1", { id: "a1", project: "proj-a", startedAt: "2026-01-01T00:00:00Z" });++ const first = await rebuildSessionIndexIfStale(kv as never);+ expect(first).toEqual({ projects: 1, sessions: 1 });++ kv.list.mockClear();+ const second = await rebuildSessionIndexIfStale(kv as never);+ expect(second).toBeNull();+ expect(kv.list.mock.calls.filter((c) => c[0] === KV.sessions)).toHaveLength(0);+ });++ function gateNextSessionsListing(target: ReturnType<typeof mockKV>): () => void {+ const listAll = target.list.getMockImplementation()!;+ let release!: () => void;+ const gate = new Promise<void>((resolve) => {+ release = resolve;+ });+ target.list.mockImplementationOnce(async (scope: string) => {+ const snapshot = await listAll(scope);+ await gate;+ return snapshot;+ });+ return release;+ }++ it("keeps a session added to the index while the rebuild was listing", async () => {+ const a1 = { id: "a1", project: "proj-a", startedAt: "2026-01-01T00:00:00Z" };+ await kv.set(KV.sessions, "a1", a1);+ await kv.set(KV.projectSessionsIndex, "proj-a", [{ id: "a1", startedAt: a1.startedAt }]);+ const release = gateNextSessionsListing(kv);++ const rebuild = rebuildAllProjectSessionIndexes(kv as never);+ const a2 = { id: "a2", project: "proj-a", startedAt: "2026-01-02T00:00:00Z" };+ await kv.set(KV.sessions, "a2", a2);+ await addSessionToProjectIndex(kv as never, "proj-a", { id: "a2", startedAt: a2.startedAt });+ release();+ await rebuild;++ const index = await getProjectSessionIndex(kv as never, "proj-a");+ expect(index?.map((e) => e.id).sort()).toEqual(["a1", "a2"]);+ });++ it("does not restore a session removed from the index while the rebuild was listing", async () => {+ const a1 = { id: "a1", project: "proj-a", startedAt: "2026-01-01T00:00:00Z" };+ const a2 = { id: "a2", project: "proj-a", startedAt: "2026-01-02T00:00:00Z" };+ await kv.set(KV.sessions, "a1", a1);+ await kv.set(KV.sessions, "a2", a2);+ await kv.set(KV.projectSessionsIndex, "proj-a", [+ { id: "a2", startedAt: a2.startedAt },+ { id: "a1", startedAt: a1.startedAt },+ ]);+ const release = gateNextSessionsListing(kv);++ const rebuild = rebuildAllProjectSessionIndexes(kv as never);+ await kv.delete(KV.sessions, "a2");+ await removeSessionFromProjectIndex(kv as never, "proj-a", "a2");+ release();+ await rebuild;++ const index = await getProjectSessionIndex(kv as never, "proj-a");+ expect(index?.map((e) => e.id)).toEqual(["a1"]);+ });++ it("does not set the generation marker when the listing fails", async () => {+ const failingKv = mockKV(new Set([KV.sessions]));++ await expect(rebuildSessionIndexIfStale(failingKv as never)).rejects.toThrow();+ expect(+ failingKv.set.mock.calls.some(([scope]) => scope === KV.config),+ ).toBe(false);+ });+});++describe("mem::context — uses the project session index (kv-access finding 3)", () => {+ let kv: ReturnType<typeof mockKV>;+ let handler: ContextHandler;++ beforeEach(() => {+ kv = mockKV();+ handler = wireContext(kv);+ });++ it("does not call kv.list(KV.sessions) when the project index already exists", async () => {+ const other = makeSession({+ id: "ses_other",+ project: "/tmp/proj",+ startedAt: "2026-01-01T00:00:00Z",+ });+ await kv.set(KV.sessions, other.id, other);+ await addSessionToProjectIndex(kv as never, "/tmp/proj", {+ id: other.id,+ startedAt: other.startedAt,+ });+ kv.list.mockClear();++ const result = await handler({+ sessionId: "ses_new",+ project: "/tmp/proj",+ });++ expect(+ kv.list.mock.calls.some(([scope]) => scope === KV.sessions),+ ).toBe(false);+ expect(result).toBeDefined();+ });++ it("falls back to a full list and backfills the index when it is missing", async () => {+ const s1 = makeSession({+ id: "ses_1",+ project: "/tmp/proj",+ startedAt: "2026-01-01T00:00:00Z",+ });+ const s2 = makeSession({+ id: "ses_2",+ project: "/tmp/proj",+ startedAt: "2026-01-02T00:00:00Z",+ });+ const otherProject = makeSession({+ id: "ses_other_proj",+ project: "/tmp/other",+ startedAt: "2026-01-03T00:00:00Z",+ });+ await kv.set(KV.sessions, s1.id, s1);+ await kv.set(KV.sessions, s2.id, s2);+ await kv.set(KV.sessions, otherProject.id, otherProject);++ expect(await getProjectSessionIndex(kv as never, "/tmp/proj")).toBeNull();++ await handler({ sessionId: "ses_new", project: "/tmp/proj" });++ expect(+ kv.list.mock.calls.some(([scope]) => scope === KV.sessions),+ ).toBe(true);++ const index = await getProjectSessionIndex(kv as never, "/tmp/proj");+ expect(index?.map((e) => e.id).sort()).toEqual(["ses_1", "ses_2"]);+ });++ it("includes recent sessions from the index in the rendered context", async () => {+ const s1 = makeSession({+ id: "ses_recent",+ project: "/tmp/proj",+ startedAt: "2026-01-01T00:00:00Z",+ observationCount: 3,+ });+ await kv.set(KV.sessions, s1.id, s1);+ await kv.set(KV.observations(s1.id), "obs_1", {+ id: "obs_1",+ sessionId: s1.id,+ title: "index-visible-marker",+ narrative: "did a thing",+ importance: 8,+ type: "task",+ });+ await addSessionToProjectIndex(kv as never, "/tmp/proj", {+ id: s1.id,+ startedAt: s1.startedAt,+ });++ const result = await handler({+ sessionId: "ses_new",+ project: "/tmp/proj",+ });++ expect(result.context).toContain("index-visible-marker");+ });++ it("skips index entries whose session record was since deleted", async () => {+ await addSessionToProjectIndex(kv as never, "/tmp/proj", {+ id: "ses_gone",+ startedAt: "2026-01-01T00:00:00Z",+ });++ const result = await handler({+ sessionId: "ses_new",+ project: "/tmp/proj",+ });++ expect(result).toBeDefined();+ expect(result.context).not.toContain("ses_gone");+ });+});diff --git a/test/snapshot.test.ts b/test/snapshot.test.tsindex 6a052cd5..4f11751e 100644--- a/test/snapshot.test.ts+++ b/test/snapshot.test.ts@@ -32,7 +32,9 @@ vi.mock("node:fs", () => ({.mockReturnValue('{"version":"0.4.0","sessions":[],"memories":[]}'),}));+import { readFileSync } from "node:fs";import { registerSnapshotFunction } from "../src/functions/snapshot.js";+import { getProjectSessionIndex } from "../src/state/session-index.js";import type { Session, Memory, SnapshotMeta } from "../src/types.js";function mockKV() {@@ -157,6 +159,36 @@ describe("Snapshot Functions", () => {expect(result.commitHash).toBe("abc1234");});+ it("snapshot-restore self-heals the project session index for restored sessions", async () => {+ const restoredSession: Session = {+ id: "ses_restored",+ project: "proj-restored",+ cwd: "/tmp/restored",+ startedAt: "2026-02-01T00:00:00Z",+ status: "completed",+ observationCount: 0,+ };+ vi.mocked(readFileSync).mockReturnValueOnce(+ JSON.stringify({+ version: "0.4.0",+ sessions: [restoredSession],+ memories: [],+ }),+ );++ expect(+ await getProjectSessionIndex(kv as never, "proj-restored"),+ ).toBeNull();++ const result = (await sdk.trigger("mem::snapshot-restore", {+ commitHash: "abc1234",+ })) as { success: boolean };++ expect(result.success).toBe(true);+ const index = await getProjectSessionIndex(kv as never, "proj-restored");+ expect(index?.map((e) => e.id)).toEqual(["ses_restored"]);+ });+it("snapshot-create records an audit entry", async () => {await sdk.trigger("mem::snapshot-create", { message: "Audit test" });