Skip to content

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

fix: release blockers for export, forget accounting and shutdown flush (#1449)

Rohit Ghumare63c54d9d4973
diff --git a/src/cli.ts b/src/cli.ts
index 2b9fbad6..7d4b72e9 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -55,6 +55,8 @@ import {
type ConnectManifest,
type RemoveOptions,
} from "./cli/remove-plan.js";
+import { portFlagSuffix } from "./cli/ready-hint.js";
+import { describeInstallFailure, iiiInstallShellCommand, iiiManualInstallCommand, III_INSTALL_SPAWN_TIMEOUT_MS } from "./cli/engine-install.js";
import {
dockerComposeArgs,
dockerProjectName,
@@ -71,6 +73,8 @@ import { runtimeMetadataPath } from "./runtime-paths.js";
import { createStartupStderrCapture } from "./cli/startup-stderr.js";
import {
clearPersistedBuiltinConfig,
+ engineFlushWaitMs,
+ persistedBuiltinConfigDirs,
renderEngineConfig,
} from "./cli/engine-config.js";
import { SHUTDOWN_HARD_EXIT_MS } from "./shutdown.js";
@@ -1326,21 +1330,25 @@ async function runIiiInstaller(): Promise<{ ok: boolean; binPath: string | null
const binDir = agentmemoryBinDir();
const binPath = privateIiiPath();
- const installCmd = [
- `mkdir -p "${binDir}"`,
- `curl -fsSL "${releaseUrl}" | tar -xz -C "${binDir}"`,
- `chmod +x "${binPath}"`,
- ].join(" && ");
- const installerOk = runCommand(shBin, ["-c", installCmd], {
- label: `Installing iii-engine v${IIPINNED_VERSION} (pinned)`,
- optional: true,
- });
- if (!installerOk) {
+ const label = `Installing iii-engine v${IIPINNED_VERSION} (pinned)`;
+ const spinner = p.spinner();
+ spinner.start(label);
+ const result = spawnSync(
+ shBin,
+ ["-c", iiiInstallShellCommand(releaseUrl, binDir, binPath)],
+ { stdio: "pipe", encoding: "utf-8", timeout: III_INSTALL_SPAWN_TIMEOUT_MS },
+ );
+ if (result.status !== 0) {
+ spinner.stop(`${label} ${pc.red("✗")}`);
p.log.warn(
- `iii-engine installer failed. Fallbacks: Docker (\`docker pull iiidev/iii:${IIPINNED_VERSION}\`) or download manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}.`,
+ `iii-engine download failed: ${describeInstallFailure(result).slice(0, 300)}\n` +
+ `Install it manually, then re-run agentmemory:\n` +
+ ` ${iiiManualInstallCommand(releaseUrl, binDir, binPath)}\n` +
+ `Or use Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`,
);
return { ok: false, binPath: null };
}
+ spinner.stop(`${label} ${pc.green("✓")}`);
return { ok: true, binPath };
}
@@ -1906,8 +1914,9 @@ function printReadyHint(): void {
const engineUrl = `ws://${engineHost}:${getEnginePort()}`;
const invocation = isInvokedViaNpx() ? "npx @agentmemory/agentmemory" : "agentmemory";
const consolePort = defaultConsolePort(getConfiguredViewerPort());
+ const portFlags = portFlagSuffix(getRestPort(), selectedInstance);
- const consoleLine = `${c.label("iii console")} ${c.cmd(`${invocation} console`)} ${c.dim(`(serves on :${consolePort}; first run downloads the console next to the pinned iii)`)}`;
+ const consoleLine = `${c.label("iii console")} ${c.cmd(`${invocation} console${portFlags}`)} ${c.dim(`(serves on :${consolePort}; first run downloads the console next to the pinned iii)`)}`;
const lines = [
`${c.label("REST API")} ${c.url(restUrl)}`,
@@ -1926,7 +1935,7 @@ function printReadyHint(): void {
// (unless they accepted the global-install prompt and the npm bin
// dir was already on PATH in this shell), so we suggest the npx
// form for them; everyone else gets the global form.
- const demoCommand = `${invocation} demo`;
+ const demoCommand = `${invocation} demo${portFlags}`;
process.stdout.write(`\n${c.dim("Try:")} ${c.cmd(demoCommand)}\n`);
}
@@ -3269,6 +3278,29 @@ async function signalAndWait(
// Shared worker-reap: SIGTERM with a grace window sized for the worker's
// shutdown flush (index snapshots land via the engine, so the worker must
// die before the engine does, with time to commit).
+async function waitForEngineFlush(): Promise<void> {
+ let stateBackend: "file" | "redis" = "file";
+ try {
+ stateBackend = getStateBackend();
+ } catch {}
+ const runtimePath = runtimeConfigPath(dataDirResolution.dataDir);
+ const configTexts: string[] = [];
+ for (const path of [
+ ...persistedBuiltinConfigDirs(join(homedir(), ".agentmemory"), runtimePath).map((dir) => join(dir, "iii-state.yaml")),
+ runtimePath,
+ ]) {
+ try {
+ configTexts.push(readFileSync(path, "utf-8"));
+ } catch {}
+ }
+ const waitMs = engineFlushWaitMs(stateBackend, configTexts);
+ if (waitMs <= 0) return;
+ const s = p.spinner();
+ s.start(`Waiting ${(waitMs / 1000).toFixed(1)}s for iii-engine to write state to disk...`);
+ await new Promise((r) => setTimeout(r, waitMs));
+ s.stop("iii-engine state flush window passed");
+}
+
async function stopWorkerPid(pid: number, graceMs: number): Promise<boolean> {
const s = p.spinner();
s.start(`Stopping agentmemory worker (pid ${pid})... [flushing state]`);
@@ -3585,7 +3617,10 @@ async function runStop(): Promise<void> {
// persists. Worker SIGTERM grace bumped 3s -> 5s to give a large
// index a real chance to commit before the engine goes away.
for (const pid of workerCandidates) {
- if (!(await stopWorkerPid(pid, 5000))) allStopped = false;
+ if (!(await stopWorkerPid(pid, SHUTDOWN_HARD_EXIT_MS + 1000))) allStopped = false;
+ }
+ if (workerCandidates.size > 0 && [...candidates].some((pid) => !workerCandidates.has(pid))) {
+ await waitForEngineFlush();
}
const skippedForeign: Array<{ pid: number; comm: string }> = [];
for (const pid of candidates) {
diff --git a/src/cli/engine-config.ts b/src/cli/engine-config.ts
index 4982b4ef..e873494c 100644
--- a/src/cli/engine-config.ts
+++ b/src/cli/engine-config.ts
@@ -33,6 +33,21 @@ export function configuredSaveIntervalMs(renderedConfig: string): number | null
return match ? parseInt(match[1]!, 10) : null;
}
+export const ENGINE_DEFAULT_SAVE_INTERVAL_MS = 5000;
+export const ENGINE_FLUSH_MARGIN_MS = 1500;
+export const ENGINE_FLUSH_WAIT_CAP_MS = 15_000;
+
+export function engineFlushWaitMs(
+ stateBackend: "file" | "redis",
+ configTexts: readonly string[],
+): number {
+ if (stateBackend === "redis") return 0;
+ const interval =
+ configTexts.map(configuredSaveIntervalMs).find((ms) => ms !== null) ??
+ ENGINE_DEFAULT_SAVE_INTERVAL_MS;
+ return Math.min(interval + ENGINE_FLUSH_MARGIN_MS, ENGINE_FLUSH_WAIT_CAP_MS);
+}
+
export function persistedBuiltinConfigDirs(
engineCwd: string,
configPath: string,
diff --git a/src/cli/engine-install.ts b/src/cli/engine-install.ts
new file mode 100644
index 00000000..db1b38b4
--- /dev/null
+++ b/src/cli/engine-install.ts
@@ -0,0 +1,50 @@
+export const III_INSTALL_CONNECT_TIMEOUT_S = 15;
+export const III_INSTALL_MAX_TIME_S = 300;
+export const III_INSTALL_SPAWN_TIMEOUT_MS =
+ (III_INSTALL_CONNECT_TIMEOUT_S + III_INSTALL_MAX_TIME_S + 30) * 1000;
+
+function curlTimeoutFlags(): string {
+ return `--connect-timeout ${III_INSTALL_CONNECT_TIMEOUT_S} --max-time ${III_INSTALL_MAX_TIME_S}`;
+}
+
+export function iiiInstallShellCommand(
+ releaseUrl: string,
+ binDir: string,
+ binPath: string,
+): string {
+ const archive = `${binDir}/.iii-download.tar.gz`;
+ return [
+ `mkdir -p "${binDir}"`,
+ `rm -f "${archive}"`,
+ `if curl -fsSL ${curlTimeoutFlags()} -o "${archive}" "${releaseUrl}" && tar -xzf "${archive}" -C "${binDir}"; then rm -f "${archive}"; else code=$?; rm -f "${archive}"; exit $code; fi`,
+ `chmod +x "${binPath}"`,
+ ].join(" && ");
+}
+
+export function iiiManualInstallCommand(
+ releaseUrl: string,
+ binDir: string,
+ binPath: string,
+): string {
+ return `mkdir -p "${binDir}" && archive="$(mktemp "${binDir}/.iii-download.XXXXXX")" && { curl -fL --connect-timeout ${III_INSTALL_CONNECT_TIMEOUT_S} -o "$archive" "${releaseUrl}" && tar -xzf "$archive" -C "${binDir}"; code=$?; rm -f "$archive"; (exit $code); } && chmod +x "${binPath}"`;
+}
+
+export function describeInstallFailure(result: {
+ error?: Error & { code?: string };
+ signal?: NodeJS.Signals | null;
+ status?: number | null;
+ stderr?: string | null;
+ stdout?: string | null;
+}): string {
+ if (result.error?.code === "ETIMEDOUT") {
+ return `timed out after ${Math.round(III_INSTALL_SPAWN_TIMEOUT_MS / 1000)} s`;
+ }
+ const output = (result.stderr || result.stdout || "").toString().trim();
+ if (output) return output;
+ if (result.status === 28) {
+ return `download timed out (no connection within ${III_INSTALL_CONNECT_TIMEOUT_S} s or not finished within ${III_INSTALL_MAX_TIME_S} s)`;
+ }
+ if (result.signal) return `installer stopped by ${result.signal}`;
+ if (result.error) return result.error.message;
+ return `installer exited with status ${result.status ?? "unknown"}`;
+}
diff --git a/src/cli/ready-hint.ts b/src/cli/ready-hint.ts
new file mode 100644
index 00000000..12bb0be6
--- /dev/null
+++ b/src/cli/ready-hint.ts
@@ -0,0 +1,8 @@
+const DEFAULT_REST_PORT = 3111;
+
+export function portFlagSuffix(restPort: number, instance: number): string {
+ if (instance > 0 && restPort === DEFAULT_REST_PORT + instance * 100) {
+ return ` --instance ${instance}`;
+ }
+ return restPort === DEFAULT_REST_PORT ? "" : ` --port ${restPort}`;
+}
diff --git a/src/config.ts b/src/config.ts
index 7601a3a1..7fc5a655 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -21,6 +21,13 @@ const DATA_DIR = join(homedir(), ".agentmemory");
const ENV_FILE = join(DATA_DIR, ".env");
let warnPremiumModelShown = false;
+let providerNoticeShown = false;
+
+function writeProviderNoticeOnce(text: string): void {
+ if (providerNoticeShown) return;
+ providerNoticeShown = true;
+ process.stderr.write(text);
+}
// Parsed ~/.agentmemory/.env, memoized for the process lifetime. getMergedEnv()
// runs on every config getter (~20 of them), so without this cache a single
@@ -158,10 +165,10 @@ function detectProvider(env: Record<string, string>): ProviderConfig {
const allowAgentSdk = env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true";
if (!allowAgentSdk) {
- process.stderr.write(
+ writeProviderNoticeOnce(
pc.dim(
- "[agentmemory] No LLM provider key set — running zero-LLM with BM25 search. " +
- "Set EMBEDDING_PROVIDER=local for on-device semantic embeddings. " +
+ "[agentmemory] No LLM provider key set — running zero-LLM: no LLM compression or summaries; search uses BM25 plus any configured embedding provider. " +
+ "Set EMBEDDING_PROVIDER=local for on-device semantic embeddings if none is configured. " +
"Set ANTHROPIC_API_KEY (or GEMINI/OPENAI/OPENROUTER/MINIMAX) in ~/.agentmemory/.env for LLM compression and summaries. " +
"Agent-SDK fallback stays off by default to avoid a Stop-hook recursion loop; opt in with AGENTMEMORY_AUTO_COMPRESS=true + AGENTMEMORY_ALLOW_AGENT_SDK=true.\n",
),
@@ -173,7 +180,7 @@ function detectProvider(env: Record<string, string>): ProviderConfig {
};
}
- process.stderr.write(
+ writeProviderNoticeOnce(
"[agentmemory] WARNING: agent-sdk fallback enabled via AGENTMEMORY_ALLOW_AGENT_SDK=true. " +
"This spawns @anthropic-ai/claude-agent-sdk child sessions that can trigger the Stop-hook " +
"recursion loop. A SDK-child env marker is set to block re-entry, " +
diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts
index 1cdd977c..1758a94c 100644
--- a/src/functions/export-import.ts
+++ b/src/functions/export-import.ts
@@ -6,10 +6,6 @@ import type {
SessionSummary,
ProjectProfile,
ExportData,
- GraphNode,
- GraphEdge,
- SemanticMemory,
- ProceduralMemory,
Action,
ActionEdge,
Routine,
@@ -27,7 +23,7 @@ import type {
import { importOrigin } from "../types.js";
import { normalizeAccessLog } from "./access-tracker.js";
import { KV } from "../state/schema.js";
-import { checkPayloadFrameSize } from "../state/frame-guard.js";
+import { checkPayloadFrameSize, oversizedPayloadError, payloadByteLength, SAFE_PAYLOAD_BYTES } from "../state/frame-guard.js";
import { StateKV } from "../state/kv.js";
import {
addSessionToProjectIndex,
@@ -68,34 +64,85 @@ async function runChunked<T>(
}
}
+const EXPORT_OVERSIZE_HINT =
+ "narrow the range with ?maxSessions / ?offset, or export fewer collections; the non-session collections (memories, graph, semantic, actions, lessons, ...) are not yet paginated";
+
+const EXPORT_COLLECTIONS: ReadonlyArray<readonly [keyof ExportData, string]> = [
+ ["graphNodes", KV.graphNodes],
+ ["graphEdges", KV.graphEdges],
+ ["semanticMemories", KV.semantic],
+ ["proceduralMemories", KV.procedural],
+ ["actions", KV.actions],
+ ["actionEdges", KV.actionEdges],
+ ["sentinels", KV.sentinels],
+ ["sketches", KV.sketches],
+ ["crystals", KV.crystals],
+ ["facets", KV.facets],
+ ["lessons", KV.lessons],
+ ["insights", KV.insights],
+ ["routines", KV.routines],
+ ["signals", KV.signals],
+ ["checkpoints", KV.checkpoints],
+ ["accessLogs", KV.accessLog],
+];
+
+export class ExportBudget {
+ bytes = 0;
+
+ constructor(private readonly limit = SAFE_PAYLOAD_BYTES) {}
+
+ fits(items: readonly unknown[], key = ""): boolean {
+ this.bytes += key.length + 6;
+ for (const item of items) {
+ this.bytes += payloadByteLength(item) + 1;
+ if (this.bytes > this.limit) return false;
+ }
+ return this.bytes <= this.limit;
+ }
+}
+
export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void {
- sdk.registerFunction("mem::export",
+ sdk.registerFunction("mem::export",
async (data?: { maxSessions?: number; offset?: number }) => {
const rawMax = Number(data?.maxSessions);
const maxSessions = Number.isFinite(rawMax) && rawMax > 0 ? Math.min(Math.floor(rawMax), 1000) : undefined;
const rawOffset = Number(data?.offset);
const offset = Number.isFinite(rawOffset) && rawOffset >= 0 ? Math.floor(rawOffset) : 0;
+ const budget = new ExportBudget();
+ const refuse = (collection: string) => {
+ logger.warn("Export exceeds transport frame limit", {
+ bytesSoFar: budget.bytes,
+ collection,
+ });
+ return {
+ ...oversizedPayloadError(budget.bytes, EXPORT_OVERSIZE_HINT),
+ stoppedAt: collection,
+ };
+ };
+ const optional = async <T>(scope: string): Promise<T[]> =>
+ kv.list<T>(scope).catch(() => [] as T[]);
+
const allSessions = await kv.list<Session>(KV.sessions);
const paginatedSessions = maxSessions !== undefined
? allSessions.slice(offset, offset + maxSessions)
: allSessions;
+ if (!budget.fits(paginatedSessions)) return refuse("sessions");
+
const memories = await kv.list<Memory>(KV.memories);
+ if (!budget.fits(memories)) return refuse("memories");
+
const summaries = await kv.list<SessionSummary>(KV.summaries);
+ if (!budget.fits(summaries)) return refuse("summaries");
const observations: Record<string, CompressedObservation[]> = {};
- const obsResults = await Promise.all(
- paginatedSessions.map((session) =>
- kv
- .list<CompressedObservation>(KV.observations(session.id))
- .catch(() => [] as CompressedObservation[])
- .then((obs) => ({ sessionId: session.id, obs })),
- ),
- );
- for (const { sessionId, obs } of obsResults) {
- if (obs.length > 0) {
- observations[sessionId] = obs;
- }
+ for (const session of paginatedSessions) {
+ const obs = await optional<CompressedObservation>(
+ KV.observations(session.id),
+ );
+ if (obs.length === 0) continue;
+ if (!budget.fits(obs, session.id)) return refuse("observations");
+ observations[session.id] = obs;
}
const profiles: ProjectProfile[] = [];
@@ -108,42 +155,15 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void
for (const profile of profileResults) {
if (profile) profiles.push(profile);
}
+ if (!budget.fits(profiles)) return refuse("profiles");
- const [
- graphNodes,
- graphEdges,
- semanticMemories,
- proceduralMemories,
- actions,
- actionEdges,
- sentinels,
- sketches,
- crystals,
- facets,
- lessons,
- insights,
- routines,
- signals,
- checkpoints,
- accessLogs,
- ] = await Promise.all([
- kv.list<GraphNode>(KV.graphNodes).catch(() => []),
- kv.list<GraphEdge>(KV.graphEdges).catch(() => []),
- kv.list<SemanticMemory>(KV.semantic).catch(() => []),
- kv.list<ProceduralMemory>(KV.procedural).catch(() => []),
- kv.list<Action>(KV.actions).catch(() => []),
- kv.list<ActionEdge>(KV.actionEdges).catch(() => []),
- kv.list<Sentinel>(KV.sentinels).catch(() => []),
- kv.list<Sketch>(KV.sketches).catch(() => []),
- kv.list<Crystal>(KV.crystals).catch(() => []),
- kv.list<Facet>(KV.facets).catch(() => []),
- kv.list<Lesson>(KV.lessons).catch(() => []),
- kv.list<Insight>(KV.insights).catch(() => []),
- kv.list<Routine>(KV.routines).catch(() => []),
- kv.list<Signal>(KV.signals).catch(() => []),
- kv.list<Checkpoint>(KV.checkpoints).catch(() => []),
- kv.list<AccessLogExport>(KV.accessLog).catch(() => []),
- ]);
+ const collections: Partial<ExportData> = {};
+ for (const [field, scope] of EXPORT_COLLECTIONS) {
+ const items = await optional<unknown>(scope);
+ if (items.length === 0) continue;
+ if (!budget.fits(items, field)) return refuse(field);
+ (collections as Record<string, unknown>)[field] = items;
+ }
const exportData: ExportData = {
version: VERSION,
@@ -153,24 +173,7 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void
memories,
summaries,
profiles: profiles.length > 0 ? profiles : undefined,
- graphNodes: graphNodes.length > 0 ? graphNodes : undefined,
- graphEdges: graphEdges.length > 0 ? graphEdges : undefined,
- semanticMemories:
- semanticMemories.length > 0 ? semanticMemories : undefined,
- proceduralMemories:
- proceduralMemories.length > 0 ? proceduralMemories : undefined,
- actions: actions.length > 0 ? actions : undefined,
- actionEdges: actionEdges.length > 0 ? actionEdges : undefined,
- sentinels: sentinels.length > 0 ? sentinels : undefined,
- sketches: sketches.length > 0 ? sketches : undefined,
- crystals: crystals.length > 0 ? crystals : undefined,
- facets: facets.length > 0 ? facets : undefined,
- lessons: lessons.length > 0 ? lessons : undefined,
- insights: insights.length > 0 ? insights : undefined,
- routines: routines.length > 0 ? routines : undefined,
- signals: signals.length > 0 ? signals : undefined,
- checkpoints: checkpoints.length > 0 ? checkpoints : undefined,
- accessLogs: accessLogs.length > 0 ? accessLogs : undefined,
+ ...collections,
};
if (maxSessions !== undefined) {
@@ -182,6 +185,14 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void
};
}
+ const oversized = checkPayloadFrameSize(exportData, EXPORT_OVERSIZE_HINT);
+ if (oversized) {
+ logger.warn("Export exceeds transport frame limit", {
+ bytes: oversized.bytes,
+ });
+ return oversized;
+ }
+
const totalObs = Object.values(observations).reduce(
(sum, arr) => sum + arr.length,
0,
@@ -194,19 +205,6 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void
summaries: summaries.length,
});
- // Only session collections page on ?maxSessions/?offset, so a large
- // store can exceed the transport cap even at ?maxSessions=1.
- const oversized = checkPayloadFrameSize(
- exportData,
- "narrow the range with ?maxSessions / ?offset, or export fewer collections; the non-session collections (memories, graph, semantic, actions, lessons, ...) are not yet paginated",
- );
- if (oversized) {
- logger.warn("Export exceeds transport frame limit", {
- bytes: oversized.bytes,
- });
- return oversized;
- }
-
return exportData;
},
);
diff --git a/src/functions/governance.ts b/src/functions/governance.ts
index 2b225a86..cde04314 100644
--- a/src/functions/governance.ts
+++ b/src/functions/governance.ts
@@ -7,8 +7,30 @@ import { deleteAccessLog } from "./access-tracker.js";
import { getSearchIndex, vectorIndexRemove, flushIndexSave } from "./search.js";
import { logger } from "../logger.js";
+const BULK_FILTER_KEYS = ["type", "dateFrom", "dateTo", "project", "qualityBelow"];
+const BULK_CONTROL_KEYS = ["dryRun", "reason"];
+
+type DeleteFailure = { id: string; error: string };
+
+function errorMessage(err: unknown): string {
+ return err instanceof Error ? err.message : String(err);
+}
+
+async function deleteMemoryRecord(
+ kv: StateKV,
+ id: string,
+): Promise<"deleted" | "missing"> {
+ const mem = await kv.get<Memory>(KV.memories, id);
+ if (!mem) return "missing";
+ await kv.delete(KV.memories, id);
+ await deleteAccessLog(kv, id);
+ getSearchIndex().remove(id);
+ vectorIndexRemove(id);
+ return "deleted";
+}
+
export function registerGovernanceFunction(sdk: IIIClient, kv: StateKV): void {
- sdk.registerFunction("mem::governance-delete",
+ sdk.registerFunction("mem::governance-delete",
async (data: { memoryIds: string[]; reason?: string }) => {
if (
!data.memoryIds ||
@@ -18,51 +40,91 @@ export function registerGovernanceFunction(sdk: IIIClient, kv: StateKV): void {
return { success: false, error: "memoryIds array is required" };
}
- let deleted = 0;
+ const deletedIds: string[] = [];
+ const notFound: string[] = [];
+ const failures: DeleteFailure[] = [];
for (const id of data.memoryIds) {
- const mem = await kv.get<Memory>(KV.memories, id);
- if (mem) {
- await kv.delete(KV.memories, id);
- await deleteAccessLog(kv, id);
- getSearchIndex().remove(id);
- vectorIndexRemove(id);
- deleted++;
+ try {
+ if ((await deleteMemoryRecord(kv, id)) === "deleted") {
+ deletedIds.push(id);
+ } else {
+ notFound.push(id);
+ }
+ } catch (err) {
+ logger.warn("Governance delete failed", {
+ memoryId: id,
+ error: errorMessage(err),
+ });
+ failures.push({ id, error: "delete_failed" });
}
}
+ const deleted = deletedIds.length;
if (deleted > 0) await flushIndexSave();
- await recordAudit(
- kv,
- "delete",
- "mem::governance-delete",
- data.memoryIds,
- {
- reason: data.reason || "manual deletion",
- deleted,
- },
- );
+ if (deleted > 0 || failures.length > 0) {
+ await recordAudit(
+ kv,
+ "delete",
+ "mem::governance-delete",
+ deletedIds,
+ {
+ reason: data.reason || "manual deletion",
+ deleted,
+ requested: data.memoryIds.length,
+ notFound: notFound.length,
+ failed: failures.length,
+ failures: failures.length > 0 ? failures : undefined,
+ },
+ );
+ }
logger.info("Governance delete", {
requested: data.memoryIds.length,
deleted,
+ notFound: notFound.length,
+ failed: failures.length,
});
- return { success: true, deleted, total: data.memoryIds.length };
+ return {
+ success: failures.length === 0,
+ deleted,
+ total: data.memoryIds.length,
+ notFound,
+ failed: failures.length,
+ failures: failures.length > 0 ? failures : undefined,
+ };
},
);
- sdk.registerFunction("mem::governance-bulk",
- async (data: GovernanceFilter & { dryRun?: boolean }) => {
+ sdk.registerFunction("mem::governance-bulk",
+ async (input: GovernanceFilter & { dryRun?: boolean; reason?: string }) => {
+ const data = input ?? {};
+ const unsupported = Object.keys(data).filter(
+ (key) => !BULK_FILTER_KEYS.includes(key) && !BULK_CONTROL_KEYS.includes(key),
+ );
+ if (unsupported.length > 0) {
+ return {
+ success: false,
+ error: `Unsupported bulk delete filter: ${unsupported.join(", ")}. Supported filters: ${BULK_FILTER_KEYS.join(", ")}`,
+ };
+ }
+ if (
+ data.project !== undefined &&
+ (typeof data.project !== "string" || data.project.trim().length === 0)
+ ) {
+ return { success: false, error: "project must be a non-empty string" };
+ }
const hasFilter =
(data.type && data.type.length > 0) ||
data.dateFrom ||
data.dateTo ||
+ (typeof data.project === "string" && data.project.length > 0) ||
data.qualityBelow !== undefined;
- if (!hasFilter && !data.dryRun) {
+ if (!hasFilter) {
return {
success: false,
- error: "At least one filter is required for non-dryRun bulk delete",
+ error: `At least one filter is required for bulk delete (${BULK_FILTER_KEYS.join(", ")})`,
};
}
@@ -90,6 +152,9 @@ export function registerGovernanceFunction(sdk: IIIClient, kv: StateKV): void {
(m) => new Date(m.createdAt).getTime() <= to,
);
}
+ if (typeof data.project === "string" && data.project.length > 0) {
+ candidates = candidates.filter((m) => m.project === data.project);
+ }
if (data.qualityBelow !== undefined) {
candidates = candidates.filter((m) => m.strength < data.qualityBelow!);
}
@@ -105,66 +170,63 @@ export function registerGovernanceFunction(sdk: IIIClient, kv: StateKV): void {
const BATCH_SIZE = 50;
const successfulIds: string[] = [];
- const failures: Array<{ id: string; error: string }> = [];
+ const notFound: string[] = [];
+ const failures: DeleteFailure[] = [];
for (let i = 0; i < candidates.length; i += BATCH_SIZE) {
const batch = candidates.slice(i, i + BATCH_SIZE);
const results = await Promise.allSettled(
- batch.map(async (mem) => {
- await kv.delete(KV.memories, mem.id);
- await deleteAccessLog(kv, mem.id);
- getSearchIndex().remove(mem.id);
- vectorIndexRemove(mem.id);
- }),
+ batch.map((mem) => deleteMemoryRecord(kv, mem.id)),
);
results.forEach((result, j) => {
const mem = batch[j];
- if (result.status === "fulfilled") {
- successfulIds.push(mem.id);
- } else {
+ if (result.status === "rejected") {
logger.warn("Governance bulk delete failed", {
memoryId: mem.id,
- error:
- result.reason instanceof Error
- ? result.reason.message
- : String(result.reason),
- });
- failures.push({
- id: mem.id,
- error: "delete_failed",
+ error: errorMessage(result.reason),
});
+ failures.push({ id: mem.id, error: "delete_failed" });
+ } else if (result.value === "deleted") {
+ successfulIds.push(mem.id);
+ } else {
+ notFound.push(mem.id);
}
});
}
if (successfulIds.length > 0) await flushIndexSave();
- await safeAudit(
- kv,
- "delete",
- "mem::governance-bulk",
- successfulIds,
- {
- filter: data,
- deleted: successfulIds.length,
- failed: failures.length,
- failures: failures.length > 0 ? failures : undefined,
- },
- );
+ if (successfulIds.length > 0 || failures.length > 0) {
+ await safeAudit(
+ kv,
+ "delete",
+ "mem::governance-bulk",
+ successfulIds,
+ {
+ filter: data,
+ deleted: successfulIds.length,
+ notFound: notFound.length,
+ failed: failures.length,
+ failures: failures.length > 0 ? failures : undefined,
+ },
+ );
+ }
logger.info("Governance bulk delete", {
deleted: successfulIds.length,
+ notFound: notFound.length,
failed: failures.length,
});
return {
success: failures.length === 0,
deleted: successfulIds.length,
+ notFound,
failed: failures.length,
failures: failures.length > 0 ? failures : undefined,
};
},
);
- sdk.registerFunction("mem::audit-query",
+ sdk.registerFunction("mem::audit-query",
async (data?: {
operation?: AuditEntry["operation"];
dateFrom?: string;
diff --git a/src/functions/remember.ts b/src/functions/remember.ts
index 7acb7e59..89c47f4e 100644
--- a/src/functions/remember.ts
+++ b/src/functions/remember.ts
@@ -270,25 +270,78 @@ export function registerRememberFunction(sdk: IIIClient, kv: StateKV): void {
observationIds?: string[];
memoryId?: string;
}) => {
+ type ObservationRef = { id?: string; imageData?: string; imageRef?: string };
let deleted = 0;
const deletedMemoryIds: string[] = [];
const deletedObservationIds: string[] = [];
+ const notFound: string[] = [];
+ const failures: Array<{ id: string; error: string }> = [];
let deletedSession = false;
+ let deletedSummary = false;
+ let indexCleaned = false;
const { decrementImageRef } = await import("./image-refs.js");
- if (data.memoryId) {
- const mem = await kv.get<Memory>(KV.memories, data.memoryId);
- if (mem) {
- await kv.delete(KV.memories, data.memoryId);
- if (mem.imageRef) {
- await decrementImageRef(kv, sdk, mem.imageRef);
+ const recordFailure = (id: string, err: unknown) => {
+ logger.warn("Forget failed", {
+ id,
+ error: err instanceof Error ? err.message : String(err),
+ });
+ failures.push({ id, error: "delete_failed" });
+ };
+
+ const attempt = async (id: string, remove: () => Promise<boolean>) => {
+ try {
+ if (await remove()) deleted++;
+ else notFound.push(id);
+ } catch (err) {
+ recordFailure(id, err);
+ }
+ };
+
+ const forgetObservation = async (
+ sessionId: string,
+ obsId: string,
+ known?: ObservationRef,
+ ): Promise<boolean> => {
+ const obs =
+ known ??
+ (await kv.get<ObservationRef>(KV.observations(sessionId), obsId));
+ if (!obs) return false;
+ await kv.delete(KV.observations(sessionId), obsId);
+ await unindexObservationSession(kv, obsId).catch(() => {});
+ try {
+ if (obs.imageData) await decrementImageRef(kv, sdk, obs.imageData);
+ if (obs.imageRef && obs.imageRef !== obs.imageData) {
+ await decrementImageRef(kv, sdk, obs.imageRef);
}
- await deleteAccessLog(kv, data.memoryId);
- getSearchIndex().remove(data.memoryId);
- vectorIndexRemove(data.memoryId);
- deletedMemoryIds.push(data.memoryId);
- deleted++;
+ } finally {
+ getSearchIndex().remove(obsId);
+ vectorIndexRemove(obsId);
+ indexCleaned = true;
}
+ deletedObservationIds.push(obsId);
+ return true;
+ };
+
+ if (data.memoryId) {
+ const memoryId = data.memoryId;
+ await attempt(memoryId, async () => {
+ const mem = await kv.get<Memory>(KV.memories, memoryId);
+ if (!mem) return false;
+ await kv.delete(KV.memories, memoryId);
+ try {
+ if (mem.imageRef) {
+ await decrementImageRef(kv, sdk, mem.imageRef);
+ }
+ } finally {
+ getSearchIndex().remove(memoryId);
+ vectorIndexRemove(memoryId);
+ indexCleaned = true;
+ }
+ await deleteAccessLog(kv, memoryId);
+ deletedMemoryIds.push(memoryId);
+ return true;
+ });
}
if (
@@ -296,21 +349,9 @@ export function registerRememberFunction(sdk: IIIClient, kv: StateKV): void {
data.observationIds &&
data.observationIds.length > 0
) {
+ const sessionId = data.sessionId;
for (const obsId of data.observationIds) {
- const obs = await kv.get<{ imageData?: string; imageRef?: string }>(
- KV.observations(data.sessionId),
- 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);
- }
- getSearchIndex().remove(obsId);
- vectorIndexRemove(obsId);
- deletedObservationIds.push(obsId);
- deleted++;
+ await attempt(obsId, () => forgetObservation(sessionId, obsId));
}
}
@@ -319,39 +360,40 @@ export function registerRememberFunction(sdk: IIIClient, kv: StateKV): void {
(!data.observationIds || data.observationIds.length === 0) &&
!data.memoryId
) {
- const observations = await kv.list<{ id: string; imageData?: string; imageRef?: string }>(
- KV.observations(data.sessionId),
+ const sessionId = data.sessionId;
+ const observations = await kv.list<ObservationRef & { id: string }>(
+ KV.observations(sessionId),
);
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);
- }
- getSearchIndex().remove(obs.id);
- vectorIndexRemove(obs.id);
- deletedObservationIds.push(obs.id);
- deleted++;
+ await attempt(obs.id, () => forgetObservation(sessionId, obs.id, obs));
}
- 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 attempt(sessionId, async () => {
+ const session = await kv.get<Session>(KV.sessions, sessionId);
+ if (!session) return false;
+ await kv.delete(KV.sessions, sessionId);
await removeSessionFromProjectIndex(
kv,
- sessionToDelete.project,
- data.sessionId,
+ session.project,
+ sessionId,
).catch(() => {});
+ deletedSession = true;
+ return true;
+ });
+ try {
+ const summary = await kv.get(KV.summaries, sessionId);
+ if (summary) {
+ await kv.delete(KV.summaries, sessionId);
+ deletedSummary = true;
+ deleted++;
+ }
+ } catch (err) {
+ recordFailure(`summary:${sessionId}`, err);
}
- deletedSession = true;
- deleted += 2;
}
- if (deleted > 0) {
- await flushIndexSave();
+ if (deleted > 0 || indexCleaned) await flushIndexSave();
+
+ if (deleted > 0 || failures.length > 0) {
await recordAudit(
kv,
"forget",
@@ -363,13 +405,27 @@ export function registerRememberFunction(sdk: IIIClient, kv: StateKV): void {
memoriesDeleted: deletedMemoryIds.length,
observationsDeleted: deletedObservationIds.length,
sessionDeleted: deletedSession,
+ summaryDeleted: deletedSummary,
+ notFound: notFound.length,
+ failed: failures.length,
+ failures: failures.length > 0 ? failures : undefined,
reason: "user-initiated forget",
},
);
}
- logger.info("Memory forgotten", { deleted });
- return { success: true, deleted };
+ logger.info("Memory forgotten", {
+ deleted,
+ notFound: notFound.length,
+ failed: failures.length,
+ });
+ return {
+ success: failures.length === 0,
+ deleted,
+ notFound,
+ failed: failures.length,
+ failures: failures.length > 0 ? failures : undefined,
+ };
},
);
}
diff --git a/src/functions/search.ts b/src/functions/search.ts
index 0493e23a..0130d0d7 100644
--- a/src/functions/search.ts
+++ b/src/functions/search.ts
@@ -56,6 +56,19 @@ export function isBm25RebuildIncomplete(): boolean {
return bm25RebuildIncomplete
}
+let keywordRebuildPending = false
+let keywordRebuildsRunning = 0
+let keywordRebuildEpoch = 0
+export function getKeywordRebuildEpoch(): number {
+ return keywordRebuildEpoch
+}
+export function markKeywordRebuildPending(): void {
+ keywordRebuildPending = true
+}
+export function isKeywordRebuildInProgress(): boolean {
+ return keywordRebuildPending || keywordRebuildsRunning > 0
+}
+
let pendingVectorBackfill = 0
export type VectorBackfillState = "idle" | "running" | "waiting-for-opt-in"
let vectorBackfillState: VectorBackfillState = "idle"
@@ -516,10 +529,26 @@ async function listSessionsWithRetry(kv: StateKV): Promise<Session[] | null> {
return null
}
+type KeywordRebuildResult = { documents: number; vectorJobs: VectorBackfillJob[]; fullBackfillPending: number }
+
export async function rebuildKeywordIndex(
kv: StateKV,
vectorBackfillSince?: string | null,
-): Promise<{ documents: number; vectorJobs: VectorBackfillJob[]; fullBackfillPending: number }> {
+): Promise<KeywordRebuildResult> {
+ keywordRebuildsRunning++
+ try {
+ return await runKeywordRebuild(kv, vectorBackfillSince)
+ } finally {
+ keywordRebuildsRunning--
+ keywordRebuildPending = false
+ keywordRebuildEpoch++
+ }
+}
+
+async function runKeywordRebuild(
+ kv: StateKV,
+ vectorBackfillSince?: string | null,
+): Promise<KeywordRebuildResult> {
const idx = getSearchIndex()
idx.clear()
memoryIndexReady = false
diff --git a/src/functions/status.ts b/src/functions/status.ts
index 19fb07d7..3e4d8af6 100644
--- a/src/functions/status.ts
+++ b/src/functions/status.ts
@@ -65,6 +65,7 @@ export interface StatusInputs {
missingObservations: number | null;
sessions: number | null;
bm25Incomplete: boolean;
+ keywordRebuildRunning?: boolean;
pendingVectorBackfill: number;
vectorBackfillState?: VectorBackfillState;
};
@@ -281,7 +282,7 @@ export function evaluateStatus(input: StatusInputs): StatusReport {
}
const missingObservations = input.index.missingObservations;
- if (missingObservations !== null && missingObservations > 0) {
+ if (!input.index.keywordRebuildRunning && missingObservations !== null && missingObservations > 0) {
problems.push({
level: "warn",
code: "index-missing-observations",
@@ -289,7 +290,14 @@ export function evaluateStatus(input: StatusInputs): StatusReport {
fix: "Restart agentmemory: the boot reconcile re-indexes observations missing from the snapshot.",
});
}
- if (missingObservations === null) {
+ if (input.index.keywordRebuildRunning) {
+ problems.push({
+ level: "info",
+ code: "keyword-index-rebuilding",
+ message: "The keyword index is still rebuilding from stored data, so the check for observations missing from search waits until it finishes.",
+ fix: "No action needed. The check runs on the next health update after the rebuild.",
+ });
+ } else if (missingObservations === null) {
problems.push({
level: "info",
code: "index-check-unavailable",
diff --git a/src/index.ts b/src/index.ts
index 16dfd396..1025bf9d 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -40,6 +40,7 @@ import {
registerSearchFunction,
backfillVectors,
rebuildKeywordIndex,
+ markKeywordRebuildPending,
getSearchIndex,
setVectorIndex,
setEmbeddingProvider,
@@ -415,6 +416,7 @@ async function main() {
setHybridRanker(hybridRanker);
registerRecentSearchesSweepFunction(sdk, kv);
+ markKeywordRebuildPending();
registerApiTriggers(sdk, kv, secret, metricsStore, provider);
registerEventTriggers(sdk, kv);
registerViewerStreamTriggers(sdk, kv, { secret, metricsStore, provider });
diff --git a/src/triggers/api.ts b/src/triggers/api.ts
index 55f2c599..f60e61fa 100644
--- a/src/triggers/api.ts
+++ b/src/triggers/api.ts
@@ -16,6 +16,8 @@ import { CONSOLIDATION_COUNTS_REUSE_MS, CONSOLIDATION_LAST_RUN_KEY, PROCEDURAL_M
import { UNINDEXED_SCAN_REUSE_MS, evaluateStatus, prefersHtml, renderStatusHtml, singleFlight, type GraphStatsInput, type StatusReport } from "../functions/status.js";
import {
findUnindexedObservations,
+ getKeywordRebuildEpoch,
+ isKeywordRebuildInProgress,
getIndexPersistenceStatus,
getEmbeddingProvider,
getPendingVectorBackfillCount,
@@ -304,12 +306,14 @@ async function probeStateStore(kv: StateKV): Promise<{ ok: boolean; latencyMs?:
}
type UnindexedScan = Awaited<ReturnType<typeof findUnindexedObservations>>;
-const unindexedScans = new WeakMap<StateKV, { run: () => Promise<UnindexedScan>; last: { at: number; value: UnindexedScan } | null }>();
+type UnindexedScanEntry = { epoch: number; run: () => Promise<UnindexedScan>; last: { at: number; value: UnindexedScan } | null };
+const unindexedScans = new WeakMap<StateKV, UnindexedScanEntry>();
function unindexedScanFor(kv: StateKV) {
let entry = unindexedScans.get(kv);
- if (!entry) {
- const created: { run: () => Promise<UnindexedScan>; last: { at: number; value: UnindexedScan } | null } = {
+ if (!entry || entry.epoch !== getKeywordRebuildEpoch()) {
+ const created: UnindexedScanEntry = {
+ epoch: getKeywordRebuildEpoch(),
run: singleFlight(async () => {
const value = await findUnindexedObservations(kv);
created.last = { at: Date.now(), value };
@@ -329,9 +333,10 @@ export interface StatusReporterDeps {
}
export function createStatusReporter(sdk: IIIClient, kv: StateKV, deps: StatusReporterDeps) {
- const scan = unindexedScanFor(kv);
return async function statusReport(options: { health?: HealthSnapshot | null; scanMaxAgeMs?: number } = {}): Promise<StatusReport> {
const idx = getSearchIndex();
+ const keywordRebuildRunning = isKeywordRebuildInProgress();
+ const scan = unindexedScanFor(kv);
const cached = scan.last && options.scanMaxAgeMs !== undefined && Date.now() - scan.last.at < options.scanMaxAgeMs
? scan.last.value
: null;
@@ -342,7 +347,7 @@ export function createStatusReporter(sdk: IIIClient, kv: StateKV, deps: StatusRe
sdk.trigger({ function_id: "mem::graph-stats", payload: {} }) as Promise<GraphStatsInput>,
STATUS_CHECK_TIMEOUT_MS,
),
- cached ? Promise.resolve(cached) : valueWithin(scan.run(), STATUS_CHECK_TIMEOUT_MS),
+ keywordRebuildRunning ? Promise.resolve(null) : cached ? Promise.resolve(cached) : valueWithin(scan.run(), STATUS_CHECK_TIMEOUT_MS),
valueWithin(
kv.get<AuditMigrationState>(KV.auditMonths, AUDIT_MIGRATION_STATE_KEY),
STATUS_CHECK_TIMEOUT_MS,
@@ -355,6 +360,7 @@ export function createStatusReporter(sdk: IIIClient, kv: StateKV, deps: StatusRe
deps.provider && "circuitState" in deps.provider
? (deps.provider.circuitState as { state?: string; failures?: number } | null)
: null;
+ const config = loadConfig();
return evaluateStatus({
now: new Date(),
version: VERSION,
@@ -362,8 +368,8 @@ export function createStatusReporter(sdk: IIIClient, kv: StateKV, deps: StatusRe
uptimeSeconds: Math.round(process.uptime()),
stateBackend: kv.backend === "redis" ? "redis" : "file",
ports: {
- rest: loadConfig().restPort ?? null,
- streams: loadConfig().streamsPort ?? null,
+ rest: config.restPort ?? null,
+ streams: config.streamsPort ?? null,
viewer: getViewerSkipped() ? null : (getBoundViewerPort() ?? null),
},
health: health
@@ -391,6 +397,7 @@ export function createStatusReporter(sdk: IIIClient, kv: StateKV, deps: StatusRe
missingObservations: unindexed ? unindexed.missing.length : null,
sessions: unindexed ? unindexed.sessions : null,
bm25Incomplete: isBm25RebuildIncomplete(),
+ keywordRebuildRunning,
pendingVectorBackfill: getPendingVectorBackfillCount(),
vectorBackfillState: getVectorBackfillState(),
},
@@ -2303,6 +2310,7 @@ export function registerApiTriggers(
type?: string[];
dateFrom?: string;
dateTo?: string;
+ project?: string;
qualityBelow?: number;
dryRun?: boolean;
}>,
diff --git a/test/cli-ready-hint.test.ts b/test/cli-ready-hint.test.ts
new file mode 100644
index 00000000..cbb4d351
--- /dev/null
+++ b/test/cli-ready-hint.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { portFlagSuffix } from "../src/cli/ready-hint.js";
+
+describe("ready hint port flags", () => {
+ it("adds nothing on the default port", () => {
+ expect(portFlagSuffix(3111, 0)).toBe("");
+ });
+
+ it("carries a custom --port into the suggested commands", () => {
+ expect(portFlagSuffix(4321, 0)).toBe(" --port 4321");
+ });
+
+ it("uses --instance when the port comes from an instance block", () => {
+ expect(portFlagSuffix(3211, 1)).toBe(" --instance 1");
+ });
+
+ it("prefers the live port when --port overrides an instance block", () => {
+ expect(portFlagSuffix(4321, 1)).toBe(" --port 4321");
+ });
+});
diff --git a/test/engine-flush-wait.test.ts b/test/engine-flush-wait.test.ts
new file mode 100644
index 00000000..c5b3cb75
--- /dev/null
+++ b/test/engine-flush-wait.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { ENGINE_FLUSH_WAIT_CAP_MS, engineFlushWaitMs } from "../src/cli/engine-config.js";
+
+const persistedState = [
+ "id: iii-state",
+ "value:",
+ " adapter:",
+ " config:",
+ " file_path: /data/state_store.db",
+ " store_method: file_based",
+ " name: kv",
+].join("\n");
+
+describe("engine flush wait on stop", () => {
+ it("waits one default save interval plus margin for the file store", () => {
+ expect(engineFlushWaitMs("file", [persistedState])).toBe(6500);
+ });
+
+ it("falls back to the default window when no config can be read", () => {
+ expect(engineFlushWaitMs("file", [])).toBe(6500);
+ });
+
+ it("follows a configured save interval", () => {
+ const custom = `${persistedState}\n save_interval_ms: 2000`;
+ expect(engineFlushWaitMs("file", [custom, "save_interval_ms: 9000"])).toBe(3500);
+ });
+
+ it("caps a very long save interval", () => {
+ expect(engineFlushWaitMs("file", ["save_interval_ms: 600000"])).toBe(ENGINE_FLUSH_WAIT_CAP_MS);
+ });
+
+ it("does not wait for the redis state backend", () => {
+ expect(engineFlushWaitMs("redis", [persistedState])).toBe(0);
+ });
+});
diff --git a/test/engine-install.test.ts b/test/engine-install.test.ts
new file mode 100644
index 00000000..04fb4605
--- /dev/null
+++ b/test/engine-install.test.ts
@@ -0,0 +1,97 @@
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+ III_INSTALL_CONNECT_TIMEOUT_S,
+ III_INSTALL_MAX_TIME_S,
+ describeInstallFailure,
+ iiiInstallShellCommand,
+ iiiManualInstallCommand,
+} from "../src/cli/engine-install.js";
+
+const sandboxes: string[] = [];
+
+function sandbox(): string {
+ const dir = mkdtempSync(join(tmpdir(), "agentmemory-install-"));
+ sandboxes.push(dir);
+ return dir;
+}
+
+afterEach(() => {
+ for (const dir of sandboxes.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function fakeCurl(dir: string, script: string): string {
+ const bin = join(dir, "fakebin");
+ mkdirSync(bin, { recursive: true });
+ const path = join(bin, "curl");
+ writeFileSync(path, `#!/bin/sh\n${script}\n`);
+ chmodSync(path, 0o755);
+ return bin;
+}
+
+function runInstall(dir: string, bin: string) {
+ const binDir = join(dir, "bin");
+ const binPath = join(binDir, "iii");
+ const result = spawnSync(
+ "sh",
+ ["-c", iiiInstallShellCommand("https://example.invalid/iii.tar.gz", binDir, binPath)],
+ { encoding: "utf-8", env: { ...process.env, PATH: `${bin}:${process.env.PATH}` } },
+ );
+ return { result, binDir, binPath };
+}
+
+describe("iii engine auto-installer", () => {
+ it("passes connect and overall timeouts to curl", () => {
+ const cmd = iiiInstallShellCommand("https://x/iii.tar.gz", "/b", "/b/iii");
+ expect(cmd).toContain(`--connect-timeout ${III_INSTALL_CONNECT_TIMEOUT_S}`);
+ expect(cmd).toContain(`--max-time ${III_INSTALL_MAX_TIME_S}`);
+ });
+
+ it("leaves no partial binary or archive behind when the download times out", () => {
+ const dir = sandbox();
+ const bin = fakeCurl(
+ dir,
+ 'out=""; while [ $# -gt 0 ]; do if [ "$1" = "-o" ]; then out="$2"; fi; shift; done; printf partial > "$out"; echo "curl: (28) Operation timed out" >&2; exit 28',
+ );
+ const { result, binDir, binPath } = runInstall(dir, bin);
+
+ expect(result.status).toBe(28);
+ expect(existsSync(binPath)).toBe(false);
+ expect(readdirSync(binDir)).toEqual([]);
+ expect(describeInstallFailure(result)).toContain("timed out");
+ });
+
+ it("installs the binary when the download completes", () => {
+ const dir = sandbox();
+ const staging = join(dir, "staging");
+ mkdirSync(staging);
+ writeFileSync(join(staging, "iii"), "#!/bin/sh\necho iii\n");
+ const tarball = join(dir, "iii.tar.gz");
+ spawnSync("tar", ["-czf", tarball, "-C", staging, "iii"]);
+ const bin = fakeCurl(
+ dir,
+ `out=""; while [ $# -gt 0 ]; do if [ "$1" = "-o" ]; then out="$2"; fi; shift; done; cp "${tarball}" "$out"`,
+ );
+ const { result, binDir, binPath } = runInstall(dir, bin);
+
+ expect(result.status).toBe(0);
+ expect(existsSync(binPath)).toBe(true);
+ expect(readdirSync(binDir)).toEqual(["iii"]);
+ });
+
+ it("explains a timeout without stderr and prints a copyable manual command", () => {
+ expect(describeInstallFailure({ status: 28, stderr: "" })).toContain("download timed out");
+ expect(
+ describeInstallFailure({ status: null, error: Object.assign(new Error("x"), { code: "ETIMEDOUT" }) }),
+ ).toContain("timed out after");
+ const manual = iiiManualInstallCommand("https://x/iii.tar.gz", "/b", "/b/iii");
+ expect(manual).toContain('curl -fL --connect-timeout');
+ expect(manual).toContain('chmod +x "/b/iii"');
+ expect(manual).toContain('mktemp "/b/.iii-download.XXXXXX"');
+ expect(manual).not.toContain("/tmp/");
+ expect(manual).toContain('rm -f "$archive"; (exit $code)');
+ });
+});
diff --git a/test/export-incremental-budget.test.ts b/test/export-incremental-budget.test.ts
new file mode 100644
index 00000000..4b47e09a
--- /dev/null
+++ b/test/export-incremental-budget.test.ts
@@ -0,0 +1,177 @@
+import { describe, it, expect, vi } from "vitest";
+
+vi.mock("../src/logger.js", () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+import {
+ registerExportImportFunction,
+ ExportBudget,
+} from "../src/functions/export-import.js";
+import { registerApiTriggers } from "../src/triggers/api.js";
+import { KV } from "../src/state/schema.js";
+import { SAFE_PAYLOAD_BYTES, payloadByteLength } from "../src/state/frame-guard.js";
+
+const BEARER = "export-budget-bearer";
+const MIB = 1024 * 1024;
+
+function countingKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ const listCalls: string[] = [];
+ return {
+ listCalls,
+ seed(scope: string, key: string, value: unknown) {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, value);
+ },
+ get: async <T>(scope: string, key: string): Promise<T | null> =>
+ (store.get(scope)?.get(key) as T) ?? null,
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => data,
+ delete: async (): Promise<void> => {},
+ update: async () => {},
+ list: async <T>(scope: string): Promise<T[]> => {
+ listCalls.push(scope);
+ return Array.from(store.get(scope)?.values() ?? []) as T[];
+ },
+ };
+}
+
+function mockSdk() {
+ const fns = new Map<string, Function>();
+ return {
+ registerFunction: (idOrOpts: string | { id: string }, handler: Function) => {
+ const id = typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id;
+ fns.set(id, handler);
+ },
+ registerTrigger: () => {},
+ trigger: async (input: { function_id: string; payload?: unknown }) =>
+ fns.get(input.function_id)?.(input.payload),
+ fns,
+ };
+}
+
+function seedSessions(kv: ReturnType<typeof countingKV>, count: number, obsBytes: number) {
+ for (let i = 0; i < count; i++) {
+ const id = `ses_${i}`;
+ kv.seed(KV.sessions, id, { id, project: "p", startedAt: "2026-09-01T00:00:00Z" });
+ kv.seed(KV.observations(id), `obs_${i}`, {
+ id: `obs_${i}`,
+ sessionId: id,
+ narrative: "n".repeat(obsBytes),
+ });
+ }
+}
+
+describe("mem::export stops assembling once the frame budget is exceeded (#1334)", () => {
+ it("never lists observations or the graph when memories alone exceed the limit", async () => {
+ const kv = countingKV();
+ const sdk = mockSdk();
+ registerExportImportFunction(sdk as never, kv as never);
+ seedSessions(kv, 3, 10);
+ kv.seed(KV.memories, "m_big", { id: "m_big", content: "z".repeat(SAFE_PAYLOAD_BYTES + 1024) });
+ kv.seed(KV.graphNodes, "n_1", { id: "n_1" });
+
+ const result = (await sdk.trigger({ function_id: "mem::export", payload: {} })) as {
+ success: boolean;
+ oversized: boolean;
+ stoppedAt: string;
+ };
+
+ expect(result.success).toBe(false);
+ expect(result.oversized).toBe(true);
+ expect(result.stoppedAt).toBe("memories");
+ expect(kv.listCalls).toEqual([KV.sessions, KV.memories]);
+ });
+
+ it("stops listing session observations at the session that crosses the limit", async () => {
+ const kv = countingKV();
+ const sdk = mockSdk();
+ registerExportImportFunction(sdk as never, kv as never);
+ seedSessions(kv, 10, 6 * MIB);
+ kv.seed(KV.graphNodes, "n_1", { id: "n_1" });
+
+ const result = (await sdk.trigger({ function_id: "mem::export", payload: {} })) as {
+ oversized: boolean;
+ stoppedAt: string;
+ bytes: number;
+ };
+
+ expect(result.oversized).toBe(true);
+ expect(result.stoppedAt).toBe("observations");
+ const obsLists = kv.listCalls.filter((s) => s.startsWith("mem:obs:"));
+ expect(obsLists).toHaveLength(3);
+ expect(kv.listCalls).not.toContain(KV.graphNodes);
+ expect(result.bytes).toBeGreaterThan(SAFE_PAYLOAD_BYTES);
+ expect(result.bytes).toBeLessThan(19 * MIB);
+ });
+
+ it("never lists later collections once the graph exceeds the limit", async () => {
+ const kv = countingKV();
+ const sdk = mockSdk();
+ registerExportImportFunction(sdk as never, kv as never);
+ for (let i = 0; i < 20; i++) {
+ kv.seed(KV.graphNodes, `n_${i}`, { id: `n_${i}`, name: "g".repeat(MIB) });
+ }
+
+ const result = (await sdk.trigger({ function_id: "mem::export", payload: {} })) as {
+ stoppedAt: string;
+ };
+
+ expect(result.stoppedAt).toBe("graphNodes");
+ expect(kv.listCalls).not.toContain(KV.graphEdges);
+ expect(kv.listCalls).not.toContain(KV.lessons);
+ });
+
+ it("still pages sessions with maxSessions so a narrowed export fits", async () => {
+ const kv = countingKV();
+ const sdk = mockSdk();
+ registerExportImportFunction(sdk as never, kv as never);
+ seedSessions(kv, 10, 6 * MIB);
+
+ const result = (await sdk.trigger({
+ function_id: "mem::export",
+ payload: { maxSessions: 2, offset: 4 },
+ })) as {
+ sessions: Array<{ id: string }>;
+ observations: Record<string, unknown[]>;
+ pagination: { offset: number; limit: number; total: number; hasMore: boolean };
+ };
+
+ expect(result.sessions.map((s) => s.id)).toEqual(["ses_4", "ses_5"]);
+ expect(Object.keys(result.observations)).toEqual(["ses_4", "ses_5"]);
+ expect(result.pagination).toEqual({ offset: 4, limit: 2, total: 10, hasMore: true });
+ });
+
+ it("returns 413 through the REST endpoint without assembling the rest", async () => {
+ const kv = countingKV();
+ const sdk = mockSdk();
+ registerExportImportFunction(sdk as never, kv as never);
+ registerApiTriggers(sdk as never, kv as never, BEARER);
+ seedSessions(kv, 10, 6 * MIB);
+
+ const resp = (await sdk.fns.get("api::export")!({
+ headers: { authorization: `Bearer ${BEARER}` },
+ query_params: {},
+ })) as { status_code: number; body: { oversized?: boolean } };
+
+ expect(resp.status_code).toBe(413);
+ expect(resp.body.oversized).toBe(true);
+ expect(kv.listCalls.filter((s) => s.startsWith("mem:obs:"))).toHaveLength(3);
+ });
+});
+
+describe("ExportBudget", () => {
+ it("tracks a collection's serialized size to within its framing", () => {
+ const items = [{ a: 1 }, { b: "two" }, { c: [3, 4] }];
+ const budget = new ExportBudget();
+ expect(budget.fits(items, "things")).toBe(true);
+ const exact = payloadByteLength({ things: items });
+ expect(budget.bytes).toBeGreaterThanOrEqual(exact - 2);
+ });
+
+ it("reports false as soon as the limit is crossed", () => {
+ const budget = new ExportBudget(100);
+ expect(budget.fits(["x".repeat(40)])).toBe(true);
+ expect(budget.fits(["x".repeat(80)])).toBe(false);
+ });
+});
diff --git a/test/governance.test.ts b/test/governance.test.ts
index 76334ee3..43c622aa 100644
--- a/test/governance.test.ts
+++ b/test/governance.test.ts
@@ -256,3 +256,142 @@ describe("Governance Functions", () => {
expect(entries[0].functionId).toBe("mem::governance-delete");
});
});
+
+describe("governance deletes count only what was really deleted (#1427, #1428)", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+ let kv: ReturnType<typeof mockKV>;
+
+ beforeEach(async () => {
+ sdk = mockSdk();
+ kv = mockKV();
+ registerGovernanceFunction(sdk as never, kv as never);
+ await kv.set("mem:memories", "mem_1", { ...makeMemory("mem_1", "pattern"), project: "alpha" });
+ await kv.set("mem:memories", "mem_2", { ...makeMemory("mem_2", "pattern"), project: "beta" });
+ });
+
+ async function auditRows() {
+ const { entries } = (await sdk.trigger("mem::audit-query", {})) as {
+ entries: AuditEntry[];
+ };
+ return entries;
+ }
+
+ it("governance-delete writes no audit row when no id existed", async () => {
+ const result = (await sdk.trigger("mem::governance-delete", {
+ memoryIds: ["missing_1"],
+ })) as { deleted: number; notFound: string[] };
+
+ expect(result.deleted).toBe(0);
+ expect(result.notFound).toEqual(["missing_1"]);
+ expect(await auditRows()).toHaveLength(0);
+ });
+
+ it("governance-delete audits only the ids it deleted", async () => {
+ const result = (await sdk.trigger("mem::governance-delete", {
+ memoryIds: ["mem_1", "missing_1"],
+ })) as { deleted: number; notFound: string[]; failed: number };
+
+ expect(result.deleted).toBe(1);
+ expect(result.notFound).toEqual(["missing_1"]);
+ expect(result.failed).toBe(0);
+ const rows = await auditRows();
+ expect(rows).toHaveLength(1);
+ expect(rows[0].targetIds).toEqual(["mem_1"]);
+ });
+
+ it("governance-delete reports a failed delete separately", async () => {
+ const realDelete = kv.delete;
+ kv.delete = async (scope: string, key: string) => {
+ if (key === "mem_2") throw new Error("disk full");
+ return realDelete(scope, key);
+ };
+
+ const result = (await sdk.trigger("mem::governance-delete", {
+ memoryIds: ["mem_1", "mem_2"],
+ })) as { success: boolean; deleted: number; failed: number };
+
+ expect(result.success).toBe(false);
+ expect(result.deleted).toBe(1);
+ expect(result.failed).toBe(1);
+ expect((await auditRows())[0].targetIds).toEqual(["mem_1"]);
+ });
+
+ it("governance-bulk dry run applies the same project filter as the live call", async () => {
+ const dry = (await sdk.trigger("mem::governance-bulk", {
+ project: "alpha",
+ dryRun: true,
+ })) as { wouldDelete: number; ids: string[] };
+ expect(dry.wouldDelete).toBe(1);
+ expect(dry.ids).toEqual(["mem_1"]);
+
+ const live = (await sdk.trigger("mem::governance-bulk", {
+ project: "alpha",
+ })) as { success: boolean; deleted: number };
+ expect(live.success).toBe(true);
+ expect(live.deleted).toBe(1);
+ const remaining = await kv.list<Memory>("mem:memories");
+ expect(remaining.map((m) => m.id)).toEqual(["mem_2"]);
+ });
+
+ it("governance-bulk rejects an empty filter in dry run and live alike", async () => {
+ for (const body of [{ dryRun: true }, {}]) {
+ const result = (await sdk.trigger("mem::governance-bulk", body)) as {
+ success: boolean;
+ error: string;
+ };
+ expect(result.success).toBe(false);
+ expect(result.error).toContain("At least one filter");
+ }
+ expect(await kv.list("mem:memories")).toHaveLength(2);
+ });
+
+ it("governance-bulk rejects an empty or non-string project in dry run and live alike", async () => {
+ for (const body of [
+ { project: "", type: ["pattern"], dryRun: true },
+ { project: " ", type: ["pattern"] },
+ { project: 42, type: ["pattern"] },
+ ]) {
+ const result = (await sdk.trigger("mem::governance-bulk", body)) as {
+ success: boolean;
+ error: string;
+ };
+ expect(result.success).toBe(false);
+ expect(result.error).toContain("project must be a non-empty string");
+ }
+ expect(await kv.list("mem:memories")).toHaveLength(2);
+ });
+
+ it("governance-bulk rejects unsupported filter keys in dry run and live alike", async () => {
+ for (const body of [
+ { ids: ["mem_1"], dryRun: true },
+ { ids: ["mem_1"] },
+ { concepts: ["test"], type: ["pattern"], dryRun: true },
+ ]) {
+ const result = (await sdk.trigger("mem::governance-bulk", body)) as {
+ success: boolean;
+ error: string;
+ };
+ expect(result.success).toBe(false);
+ expect(result.error).toContain("Unsupported bulk delete filter");
+ }
+ expect(await kv.list("mem:memories")).toHaveLength(2);
+ });
+
+ it("governance-bulk does not count or audit a candidate that vanished before delete", async () => {
+ const realGet = kv.get;
+ kv.get = async <T>(scope: string, key: string): Promise<T | null> => {
+ if (key === "mem_2") return null;
+ return realGet<T>(scope, key);
+ };
+
+ const result = (await sdk.trigger("mem::governance-bulk", {
+ type: ["pattern"],
+ })) as { deleted: number; notFound: string[] };
+
+ expect(result.deleted).toBe(1);
+ expect(result.notFound).toEqual(["mem_2"]);
+ const rows = await auditRows();
+ expect(rows).toHaveLength(1);
+ expect(rows[0].targetIds).toEqual(["mem_1"]);
+ });
+});
diff --git a/test/provider-notice-once.test.ts b/test/provider-notice-once.test.ts
new file mode 100644
index 00000000..68851b55
--- /dev/null
+++ b/test/provider-notice-once.test.ts
@@ -0,0 +1,48 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const fakeHome = mkdtempSync(join(tmpdir(), "agentmemory-notice-"));
+
+vi.mock("node:os", async (importOriginal) => {
+ const actual = await importOriginal<typeof import("node:os")>();
+ return { ...actual, homedir: () => fakeHome };
+});
+
+const PROVIDER_ENV = /(API_KEY|_KEY$|_TOKEN$|PROVIDER|_BASE_URL$|^AGENTMEMORY_ALLOW_AGENT_SDK$|^OLLAMA)/;
+
+describe("zero-LLM provider notice", () => {
+ const saved: Record<string, string | undefined> = {};
+
+ beforeEach(() => {
+ vi.resetModules();
+ for (const key of Object.keys(process.env)) {
+ if (PROVIDER_ENV.test(key)) {
+ saved[key] = process.env[key];
+ delete process.env[key];
+ }
+ }
+ });
+
+ afterEach(() => {
+ for (const [key, value] of Object.entries(saved)) {
+ if (value !== undefined) process.env[key] = value;
+ }
+ vi.restoreAllMocks();
+ });
+
+ it("is printed once per process however often the config is loaded", async () => {
+ const write = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+ const { loadConfig } = await import("../src/config.js");
+
+ for (let i = 0; i < 4; i++) {
+ expect(loadConfig().provider.provider).toBe("noop");
+ }
+
+ const notices = write.mock.calls.filter((call) =>
+ String(call[0]).includes("No LLM provider key set"),
+ );
+ expect(notices).toHaveLength(1);
+ });
+});
diff --git a/test/remember-forget-audit.test.ts b/test/remember-forget-audit.test.ts
index f87ae474..e8fc5a4c 100644
--- a/test/remember-forget-audit.test.ts
+++ b/test/remember-forget-audit.test.ts
@@ -8,6 +8,9 @@ vi.mock("../src/state/keyed-mutex.js", () => ({
withKeyedLock: <T>(_key: string, fn: () => Promise<T>) => fn(),
}));
+const decrementImageRef = vi.fn(async () => {});
+vi.mock("../src/functions/image-refs.js", () => ({ decrementImageRef }));
+
import { registerRememberFunction } from "../src/functions/remember.js";
import {
getSearchIndex,
@@ -138,7 +141,12 @@ describe("mem::forget audit coverage (issue #125)", () => {
payload: { memoryId: "lsn_4f9cb07017a7c8ac" },
});
- expect(result).toEqual({ success: true, deleted: 0 });
+ expect(result).toMatchObject({
+ success: true,
+ deleted: 0,
+ notFound: ["lsn_4f9cb07017a7c8ac"],
+ failed: 0,
+ });
// No-op path must not touch the memories keyspace or search index.
expect(deleteSpy).not.toHaveBeenCalled();
expect(getSearchIndex().has("lsn_4f9cb07017a7c8ac")).toBe(false);
@@ -227,6 +235,27 @@ describe("mem::forget search-index cleanup", () => {
expect(getSearchIndex().has("obs_b")).toBe(true);
});
+ it("still unindexes and flushes an observation whose image cleanup fails", async () => {
+ const sdk = mockSdk();
+ const kv = mockKV();
+ registerRememberFunction(sdk as never, kv as never);
+ const persistence = { scheduleSave: vi.fn(), save: vi.fn(async () => {}) };
+ setIndexPersistence(persistence);
+ decrementImageRef.mockRejectedValueOnce(new Error("image store down"));
+
+ await kv.set("mem:obs:ses_1", "obs_img", { id: "obs_img", imageRef: "img_1" });
+ getSearchIndex().add(memoryToObservation(makeMemory("obs_img")));
+
+ await sdk.trigger({
+ function_id: "mem::forget",
+ payload: { sessionId: "ses_1", observationIds: ["obs_img"] },
+ });
+
+ expect(await kv.get("mem:obs:ses_1", "obs_img")).toBeNull();
+ expect(getSearchIndex().has("obs_img")).toBe(false);
+ expect(persistence.save).toHaveBeenCalled();
+ });
+
it("flushes persistence immediately when a memory is forgotten", async () => {
const sdk = mockSdk();
const kv = mockKV();
@@ -244,3 +273,117 @@ describe("mem::forget search-index cleanup", () => {
expect(persistence.save).toHaveBeenCalled();
});
});
+
+describe("mem::forget counts only records that were really deleted (#1428)", () => {
+ type ForgetResult = {
+ success: boolean;
+ deleted: number;
+ notFound: string[];
+ failed: number;
+ failures?: Array<{ id: string; error: string }>;
+ };
+
+ it("reports nothing and writes no audit row for an absent session", async () => {
+ const sdk = mockSdk();
+ const kv = mockKV();
+ registerRememberFunction(sdk as never, kv as never);
+
+ const result = (await sdk.trigger({
+ function_id: "mem::forget",
+ payload: { sessionId: "sess_ABSENT" },
+ })) as ForgetResult;
+
+ expect(result.success).toBe(true);
+ expect(result.deleted).toBe(0);
+ expect(result.notFound).toEqual(["sess_ABSENT"]);
+ expect(result.failed).toBe(0);
+ expect(await kv.list(currentAuditScope())).toHaveLength(0);
+ });
+
+ it("reports nothing and writes no audit row for absent observation ids", async () => {
+ const sdk = mockSdk();
+ const kv = mockKV();
+ registerRememberFunction(sdk as never, kv as never);
+
+ const result = (await sdk.trigger({
+ function_id: "mem::forget",
+ payload: { sessionId: "sess_ABSENT", observationIds: ["obs_ABSENT"] },
+ })) as ForgetResult;
+
+ expect(result.deleted).toBe(0);
+ expect(result.notFound).toEqual(["obs_ABSENT"]);
+ expect(await kv.list(currentAuditScope())).toHaveLength(0);
+ });
+
+ it("audits only the observation ids that existed", async () => {
+ const sdk = mockSdk();
+ const kv = mockKV();
+ registerRememberFunction(sdk as never, kv as never);
+ await kv.set("mem:obs:sess_1", "obs_a", { id: "obs_a" });
+
+ const result = (await sdk.trigger({
+ function_id: "mem::forget",
+ payload: { sessionId: "sess_1", observationIds: ["obs_a", "obs_missing"] },
+ })) as ForgetResult;
+
+ expect(result.deleted).toBe(1);
+ expect(result.notFound).toEqual(["obs_missing"]);
+ const rows = await kv.list<{
+ targetIds: string[];
+ details: Record<string, unknown>;
+ }>(currentAuditScope());
+ expect(rows).toHaveLength(1);
+ expect(rows[0].targetIds).toEqual(["obs_a"]);
+ expect(rows[0].details.observationsDeleted).toBe(1);
+ expect(rows[0].details.notFound).toBe(1);
+ });
+
+ it("does not count a missing summary for an existing session", async () => {
+ const sdk = mockSdk();
+ const kv = mockKV();
+ registerRememberFunction(sdk as never, kv as never);
+ await kv.set("mem:sessions", "sess_1", { id: "sess_1", project: "p" });
+
+ const result = (await sdk.trigger({
+ function_id: "mem::forget",
+ payload: { sessionId: "sess_1" },
+ })) as ForgetResult;
+
+ expect(result.deleted).toBe(1);
+ const rows = await kv.list<{ details: Record<string, unknown> }>(
+ currentAuditScope(),
+ );
+ expect(rows[0].details.sessionDeleted).toBe(true);
+ expect(rows[0].details.summaryDeleted).toBe(false);
+ });
+
+ it("reports a failed delete separately and keeps it out of the deleted count", async () => {
+ const sdk = mockSdk();
+ const kv = mockKV();
+ registerRememberFunction(sdk as never, kv as never);
+ await kv.set("mem:obs:sess_1", "obs_a", { id: "obs_a" });
+ await kv.set("mem:obs:sess_1", "obs_b", { id: "obs_b" });
+ const realDelete = kv.delete;
+ kv.delete = async (scope: string, key: string) => {
+ if (key === "obs_b") throw new Error("disk full");
+ return realDelete(scope, key);
+ };
+
+ const result = (await sdk.trigger({
+ function_id: "mem::forget",
+ payload: { sessionId: "sess_1", observationIds: ["obs_a", "obs_b"] },
+ })) as ForgetResult;
+
+ expect(result.success).toBe(false);
+ expect(result.deleted).toBe(1);
+ expect(result.failed).toBe(1);
+ expect(result.failures).toEqual([{ id: "obs_b", error: "delete_failed" }]);
+ const rows = await kv.list<{
+ targetIds: string[];
+ details: Record<string, unknown>;
+ }>(currentAuditScope());
+ expect(rows).toHaveLength(1);
+ expect(rows[0].targetIds).toEqual(["obs_a"]);
+ expect(rows[0].details.failed).toBe(1);
+ });
+});
diff --git a/test/status-rebuild-overlap.test.ts b/test/status-rebuild-overlap.test.ts
new file mode 100644
index 00000000..4f332b3f
--- /dev/null
+++ b/test/status-rebuild-overlap.test.ts
@@ -0,0 +1,102 @@
+import { describe, it, expect, vi } from "vitest";
+
+vi.mock("../src/logger.js", () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+import { createStatusReporter } from "../src/triggers/api.js";
+import {
+ getSearchIndex,
+ markKeywordRebuildPending,
+ rebuildKeywordIndex,
+} from "../src/functions/search.js";
+import { KV } from "../src/state/schema.js";
+
+function storeKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ const listCalls: string[] = [];
+ return {
+ backend: "file" as const,
+ listCalls,
+ seed(scope: string, key: string, value: unknown) {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, value);
+ },
+ get: async <T>(scope: string, key: string): Promise<T | null> =>
+ (store.get(scope)?.get(key) as T) ?? null,
+ set: async <T>(_scope: string, _key: string, data: T): Promise<T> => data,
+ delete: async (): Promise<void> => {},
+ list: async <T>(scope: string): Promise<T[]> => {
+ listCalls.push(scope);
+ return Array.from(store.get(scope)?.values() ?? []) as T[];
+ },
+ };
+}
+
+const sdk = { trigger: async () => null };
+
+function seedStore() {
+ const kv = storeKV();
+ kv.seed(KV.sessions, "ses_1", {
+ id: "ses_1",
+ project: "p",
+ startedAt: "2026-09-30T00:00:00Z",
+ observationCount: 3,
+ });
+ for (let i = 0; i < 3; i++) {
+ kv.seed(KV.observations("ses_1"), `obs_${i}`, {
+ id: `obs_${i}`,
+ sessionId: "ses_1",
+ title: `title ${i}`,
+ narrative: `narrative ${i}`,
+ type: "decision",
+ facts: [],
+ concepts: [],
+ files: [],
+ importance: 5,
+ timestamp: "2026-09-30T00:00:00Z",
+ });
+ }
+ return kv;
+}
+
+function codes(report: { problems: Array<{ code: string }> }): string[] {
+ return report.problems.map((p) => p.code);
+}
+
+describe("status while the boot keyword rebuild runs", () => {
+ it("does not report missing observations before the rebuild finishes", async () => {
+ getSearchIndex().clear();
+ const kv = seedStore();
+ markKeywordRebuildPending();
+ const statusReport = createStatusReporter(sdk as never, kv as never, {});
+
+ const during = await statusReport({ health: null, scanMaxAgeMs: 30_000 });
+ expect(during.index.missingObservations).toBeNull();
+ expect(codes(during)).toContain("keyword-index-rebuilding");
+ expect(codes(during)).not.toContain("index-missing-observations");
+ expect(codes(during)).not.toContain("index-check-unavailable");
+ expect(kv.listCalls).not.toContain(KV.sessions);
+
+ await rebuildKeywordIndex(kv as never);
+
+ const after = await statusReport({ health: null, scanMaxAgeMs: 30_000 });
+ expect(after.index.missingObservations).toBe(0);
+ expect(codes(after)).not.toContain("keyword-index-rebuilding");
+ expect(codes(after)).not.toContain("index-missing-observations");
+ });
+
+ it("drops a cached scan taken before a rebuild completed", async () => {
+ getSearchIndex().clear();
+ const kv = seedStore();
+ const statusReport = createStatusReporter(sdk as never, kv as never, {});
+
+ const before = await statusReport({ health: null, scanMaxAgeMs: 30_000 });
+ expect(before.index.missingObservations).toBe(3);
+
+ await rebuildKeywordIndex(kv as never);
+
+ const after = await statusReport({ health: null, scanMaxAgeMs: 30_000 });
+ expect(after.index.missingObservations).toBe(0);
+ });
+});
diff --git a/test/status.test.ts b/test/status.test.ts
index 7e621de5..c3ed308e 100644
--- a/test/status.test.ts
+++ b/test/status.test.ts
@@ -50,6 +50,14 @@ function codes(report: ReturnType<typeof evaluateStatus>): string[] {
}
describe("evaluateStatus", () => {
+ it("holds the missing-observations warning while the keyword index rebuilds", () => {
+ const report = evaluateStatus(
+ inputs({ index: { ...inputs().index, missingObservations: 7, keywordRebuildRunning: true } }),
+ );
+ expect(codes(report)).not.toContain("index-missing-observations");
+ expect(codes(report)).toContain("keyword-index-rebuilding");
+ });
+
it("reports ok with no problems on a healthy install", () => {
const report = evaluateStatus(inputs());
expect(report.status).toBe("ok");