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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,7 @@
# AGENTMEMORY_REFLECT=true # Periodically auto-synthesize lessons from memories
# AGENTMEMORY_DROP_STALE_INDEX=true # Drop on-disk BM25 / vector index on startup if dim guard fires (#248). Recovery toggle for stuck-state debugging.
# AGENTMEMORY_IMAGE_EMBEDDINGS=true # Enable image embeddings when an image provider is present (experimental).
# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves; shutdown and deletes still save immediately.

# -----------------------------------------------------------------------------
# 6. CLI / runtime knobs
Expand Down
3 changes: 2 additions & 1 deletion plugin/skills/agentmemory-config/REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded.

<!-- AUTOGEN:env START - generated by scripts/skills/generate.ts, do not edit by hand -->
Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 43 recognized variables:
Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 44 recognized variables:

- `AGENTMEMORY_AGENT_SCOPE`
- `AGENTMEMORY_ALLOW_AGENT_SDK`
Expand All @@ -27,6 +27,7 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e
- `AGENTMEMORY_III_VERSION`
- `AGENTMEMORY_IMAGE_EMBEDDINGS`
- `AGENTMEMORY_IMAGE_STORE_MAX_BYTES`
- `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS`
- `AGENTMEMORY_INJECT_CONTEXT`
- `AGENTMEMORY_LLM_NOTHINK`
- `AGENTMEMORY_LLM_TIMEOUT_MS`
Expand Down
10 changes: 10 additions & 0 deletions src/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -467,6 +467,16 @@ export function getConsolidationCooldownMs(): number {
return raw >= 0 ? raw : CONSOLIDATION_COOLDOWN_DEFAULT_MS;
}

export const INDEX_SAVE_INTERVAL_DEFAULT_MS = 600_000;

export function getIndexSaveIntervalMs(): number {
const raw = safeParseInt(
getMergedEnv()["AGENTMEMORY_INDEX_SAVE_INTERVAL_MS"],
INDEX_SAVE_INTERVAL_DEFAULT_MS,
);
return raw > 0 ? raw : INDEX_SAVE_INTERVAL_DEFAULT_MS;
}

export function isStandaloneMcp(): boolean {
return getMergedEnv()["STANDALONE_MCP"] === "true";
}
Expand Down
16 changes: 11 additions & 5 deletions src/functions/search.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import type { IIIClient } from 'iii-sdk'
import type { IndexPersistenceStatus } from "../state/index-persistence.js";
import type { CompactSearchResult, CompressedObservation, Memory, SearchResult, Session } from '../types.js'
import { KV } from '../state/schema.js'
import { StateKV } from '../state/kv.js'
Expand Down Expand Up @@ -75,17 +76,22 @@ export function vectorIndexRemove(id: string): void {
// Wired by src/index.ts after IndexPersistence is constructed; no-op
// until then so unit tests that exercise the delete paths in
// isolation don't need to wire persistence.
let indexPersistence: {
type IndexPersistenceHook = {
scheduleSave: () => void;
save: () => Promise<void>;
} | null = null;
status?: () => IndexPersistenceStatus;
};

export function setIndexPersistence(
p: { scheduleSave: () => void; save: () => Promise<void> } | null,
): void {
let indexPersistence: IndexPersistenceHook | null = null;

export function setIndexPersistence(p: IndexPersistenceHook | null): void {
indexPersistence = p;
}

export function getIndexPersistenceStatus(): IndexPersistenceStatus | null {
return indexPersistence?.status?.() ?? null;
}

export function scheduleIndexSave(): void {
indexPersistence?.scheduleSave();
}
Expand Down
67 changes: 67 additions & 0 deletions src/functions/status.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
import { V8_MAX_STRING_CHARS, type IndexLegStatus, type IndexPersistenceStatus } from "../state/index-persistence.js";

export type StatusLevel = "ok" | "info" | "warn" | "error";

export interface StatusProblem {
Expand Down Expand Up @@ -58,6 +60,7 @@ export interface StatusInputs {
};
graph: GraphStatsInput | null;
graphExtractionEnabled: boolean;
indexPersistence?: IndexPersistenceStatus | null;
}

export interface StatusReport {
Expand All @@ -72,6 +75,7 @@ export interface StatusReport {
health: StatusInputs["health"];
provider: { llm: string; embeddings: string; circuitBreaker: StatusInputs["circuitBreaker"] };
index: StatusInputs["index"];
indexPersistence: IndexPersistenceStatus | null;
graph: (GraphStatsInput & { ageSeconds: number | null; extractionEnabled: boolean }) | null;
functions: Array<FunctionMetricInput & { failureRate: number }>;
flags: StatusFlag[];
Expand All @@ -81,6 +85,7 @@ export interface StatusReport {
const FAILURE_RATE_THRESHOLD = 0.2;
const FAILURE_MIN_CALLS = 5;
const GRAPH_SNAPSHOT_STALE_SECONDS = 24 * 60 * 60;
const VECTOR_STRING_WARN_RATIO = 0.8;
const LEVEL_RANK: Record<StatusLevel, number> = { ok: 0, info: 1, warn: 2, error: 3 };

const FUNCTION_FIXES: Record<string, string> = {
Expand Down Expand Up @@ -168,6 +173,43 @@ export function evaluateStatus(input: StatusInputs): StatusReport {
});
}

const persistence = input.indexPersistence ?? null;
if (persistence) {
const legs: Array<[string, IndexLegStatus | null]> = [
["BM25", persistence.bm25],
["vector", persistence.vector],
];
for (const [label, leg] of legs) {
if (!leg) continue;
if (leg.lastError) {
problems.push({
level: "error",
code: "index-save-failing",
message: `The ${label} search index could not be saved: ${leg.lastError}. Search keeps working from memory, but changes since the last save are lost on restart.`,
fix: "Check the server log for the failing state write. The next save retries automatically.",
});
}
const dirtyAge = secondsBetween(input.now, leg.dirtySince ?? undefined);
if (!leg.lastError && dirtyAge !== null && dirtyAge * 1000 > 2 * persistence.saveIntervalMs) {
problems.push({
level: "warn",
code: "index-save-stale",
message: `The ${label} search index has unsaved changes from ${formatDuration(dirtyAge)} ago.`,
fix: "Saves run at most once per AGENTMEMORY_INDEX_SAVE_INTERVAL_MS. Check the server log for save errors or a save that never finishes.",
});
}
}
const vectorChars = persistence.vector?.serializedChars ?? null;
if (vectorChars !== null && vectorChars > V8_MAX_STRING_CHARS * VECTOR_STRING_WARN_RATIO) {
problems.push({
level: "warn",
code: "vector-index-near-string-limit",
message: `The saved vector index is ${Math.round((vectorChars / V8_MAX_STRING_CHARS) * 100)}% of the largest string Node.js can hold. Past that limit it can no longer be saved or loaded.`,
fix: "Upgrade agentmemory once bucketed vector storage ships, or reduce the index (a smaller embedding model, or forget unused observations) before it reaches the limit.",
});
}
}

let graph: StatusReport["graph"] = null;
if (input.graph) {
const ageSeconds = secondsBetween(input.now, input.graph.updatedAt);
Expand Down Expand Up @@ -218,6 +260,7 @@ export function evaluateStatus(input: StatusInputs): StatusReport {
circuitBreaker: input.circuitBreaker,
},
index: input.index,
indexPersistence: persistence,
graph,
functions,
flags: input.flags,
Expand Down Expand Up @@ -248,6 +291,29 @@ function row(label: string, value: string): string {
return `<tr><th>${escapeHtml(label)}</th><td>${value}</td></tr>`;
}

function legSummary(report: StatusReport, leg: IndexLegStatus): string {
if (leg.lastError) return `failing: ${leg.lastError}`;
const saved = leg.lastSavedAt ? `saved ${formatDuration(secondsBetween(new Date(report.checkedAt), leg.lastSavedAt))} ago` : "not saved since start";
return leg.dirtySince ? `${saved}, unsaved changes pending` : saved;
}

function indexPersistenceRows(report: StatusReport): string {
const persistence = report.indexPersistence;
if (!persistence) return "";
let rows = row("BM25 save", escapeHtml(legSummary(report, persistence.bm25)));
if (persistence.vector) {
rows += row("Vector save", escapeHtml(legSummary(report, persistence.vector)));
const chars = persistence.vector.serializedChars;
if (chars !== null) {
rows += row(
"Vector index size",
escapeHtml(`${chars.toLocaleString("en-US")} characters (${Math.round((chars / V8_MAX_STRING_CHARS) * 100)}% of the Node.js string limit)`),
);
}
}
return rows;
}

export function renderStatusHtml(report: StatusReport, styleNonce: string): string {
const problems = report.problems.length
? report.problems
Expand Down Expand Up @@ -330,6 +396,7 @@ ${row("Vector documents", escapeHtml(idx.vectorDocuments ?? "vector search off")
${row("Observations indexed", escapeHtml(idx.observationsIndexed))}
${row("Missing from index", escapeHtml(idx.missingObservations ?? "not checked"))}
${row("Sessions", escapeHtml(idx.sessions ?? "unknown"))}
${indexPersistenceRows(report)}
</table>
<h2>Knowledge graph</h2><table>
${graph
Expand Down
Loading
Loading