Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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): void
const 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): void
obsDeletes.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): void
const 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 + crystallize
diff --git a/test/obs-index.test.ts b/test/obs-index.test.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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" });