rohitg00/agentmemory · warning

[agentmemory] Failed to load persisted index:

Error message

[agentmemory] Failed to load persisted index:

What it means

Startup warning from the agentmemory daemon's `main()`. `indexPersistence.load()` reads the persisted BM25/vector index snapshot; if it rejects (corrupt file, unreadable state, deserialization error), the promise is caught, the error is logged with `console.warn`, and load resolves to `null` so boot continues with an empty index. The daemon still starts; only search recall is degraded until a rebuild.

Source

Thrown at src/index.ts:404

  registerSmartSearchFunction(sdk, kv, hybridRanker);
  setHybridRanker(hybridRanker);
  registerRecentSearchesSweepFunction(sdk, kv);

  registerApiTriggers(sdk, kv, secret, metricsStore, provider);
  registerEventTriggers(sdk, kv);
  registerMcpEndpoints(sdk, kv, secret);

  const healthMonitor = registerHealthMonitor(sdk, kv);

  const indexPersistence = new IndexPersistence(kv, bm25Index, vectorIndex);
  // Wire the persistence hook so delete paths can flush BM25/vector
  // index mutations to disk. Without this, an in-memory remove can be
  // lost across a hard process exit and the persisted snapshot
  // restores the deleted entry at next boot.
  setIndexPersistence(indexPersistence);

  const loaded = await indexPersistence.load().catch((err) => {
    console.warn(`[agentmemory] Failed to load persisted index:`, err);
    return null;
  });
  if (loaded?.bm25 && loaded.bm25.size > 0) {
    bm25Index.restoreFrom(loaded.bm25);
    bootLog(
      `Loaded persisted BM25 index (${bm25Index.size} docs)`,
    );
  }
  if (loaded?.vector && vectorIndex && loaded.vector.size > 0) {
    // Persisted vectors carry whatever dimension the provider had when
    // they were written. If the active provider declares a different
    // dimension — or if the on-disk index contains a mix of dimensions
    // (legacy indexes written before the live-API guard in this PR) —
    // restoring would silently corrupt search: cosineSimilarity returns
    // 0 on cross-dim pairs, so affected observations stop matching
    // anything and recall degrades without an error. Walk every stored
    // vector instead of trusting the first; refuse to load if anything
    // is off.

View on GitHub (pinned to e04ba88819)

Solutions

1. Read the logged `err` to see the concrete cause (deserialization vs permissions vs I/O)
2. Back up and remove/rename the persisted index/state files (./data) so a fresh snapshot is written, accepting a rebuild
3. Check file permissions/ownership of ./data and fix them
4. If triggered by a version upgrade, either downgrade or let the index rebuild from live data
5. Verify disk space and that no other process holds the SQLite file locked

Example fix

// before
[agentmemory] Failed to load persisted index: Error: file is not a database
// after
$ mv data/state_store.db data/state_store.db.bak
$ agentmemory start
Loaded persisted BM25 index (0 docs)  # rebuilds from live observations

// before boot, sanity-check state files
import { existsSync, statSync } from "node:fs";
if (existsSync("./data/state_store.db") && statSync("./data/state_store.db").size === 0) {
  console.warn("Empty/corrupt state file — move it aside before starting");
}

function isLoadedIndex(x: unknown): x is { bm25: { size: number }; vector?: { size: number; validateDimensions(d: number): { mismatches: unknown[] } } } {
  return typeof x === "object" && x !== null && "bm25" in x;
}

try {
  const loaded = await indexPersistence.load();
} catch (err) {
  console.warn(`[agentmemory] Failed to load persisted index:`, err);
  // proceed with empty index; schedule a rebuild
}

When it happens

Trigger: Boot with a corrupted or partially-written `state_store.db` / index snapshot; state file permissions changed; schema change after an upgrade makes the old snapshot unparsable; disk I/O error while reading state.

Common situations: Upgrading agentmemory across versions with an old on-disk index; killing the process mid-save leaving a truncated snapshot; running as a different user so ./data is unreadable; disk-full conditions during previous saves.

Related errors

• [agentmemory] Failed to backfill memories into BM25:
• [agentmemory] Failed to save index on shutdown:
• [agentmemory] Refusing to start: persisted vector index has
• [agentmemory] Failed to rebuild search index:

AI-assisted analysis of rohitg00/agentmemory@e04ba88819 (2026-08-30). Data as JSON: /api/errors/45f9ecf56592f5d5. Report an issue: GitHub.