Repository navigation
Description
User problem
I cannot use a Git Snapshot as a reliable recovery point. Restoring Snapshot commit C1 does not make the live store match the durable state captured at C1.
Records created after C1 remain. Many durable stores are not present in state.json. Search and Graph indexes are not reconciled. A successful restore can therefore produce mixed state and incorrect recall.
Environment
- Published agentmemory:
@agentmemory/agentmemory@0.9.28 - Upstream
main: package version0.9.29, commit2973e4e - Node:
v26.4.0 - OS: macOS
26.6.1arm64
Reproduction
- Create a Session, Observation, Memory, Session Summary, Graph relationship, Action, Crystal, Lesson, and Semantic Memory through supported operations.
- Create a Snapshot and save its commit hash as
C1. - Create additional records after
C1. - Restore
C1throughmem::snapshot-restoreorPOST /agentmemory/snapshot/restore. - List the durable stores and run search and Graph queries.
- Inspect
state.jsonin SnapshotC1.
Actual result
Snapshot creation exports only:
sessions
memories
graphNodes
observations
accessLogs
See src/functions/snapshot.ts#L61-L86.
The canonical KV schema contains many other durable stores, including Session Summaries, Graph relationships and side indexes, Semantic Memory, Procedural Memory, Actions, Action relationships, Crystals, Lessons, Insights, image references, slots, and commit links:
Snapshot restore uses additive kv.set calls for only the five exported groups. It does not clear current records first:
As a result:
- Records created after
C1remain. - Omitted durable stores cannot be restored from
C1. - BM25, vector, Graph, and Graph-side indexes are not restored or rebuilt.
- The result is not checked against per-store counts or hashes.
- Restore can run while Sessions are active.
- The Snapshot uses the package
version; it has no independentschemaVersionfor the Snapshot contract.
Expected result
The Snapshot API needs an explicit durable-state contract.
For replace restore:
- The live canonical state after restore must equal the state captured in
C1. - Every canonical durable store must be included or explicitly classified as derived and rebuilt.
- Records created after
C1must not remain. - BM25, vector, Graph, and Graph-side indexes must be restored or rebuilt from canonical data.
- A manifest must record an independent
schemaVersion, included stores, counts, and hashes. - Restore must validate the manifest before mutation and verify the resulting state before reporting success.
- Restore must refuse active Sessions by default.
- Partial application or failed verification must return failure.
If additive import is required, it should be an explicit separate mode. snapshot-restore must not appear to provide complete recovery while it performs a partial merge.
Related work
- Bug: SNAPSHOT_INTERVAL config is read and logged but no setInterval timer triggers mem::snapshot-create #1006 and merged PR fix: env hydration, indexing, consolidation lifecycle, connector activation, hardening #1136 cover Snapshot scheduling, not Snapshot contents or restore correctness.
- Scheduled Git snapshots grow without a retention policy #1158 covers Git Snapshot history retention.
- Feature request: auto-restore from latest snapshot on daemon startup #1007 requests automatic startup restore. Automatic restore depends on a correct restore contract.
- import "replace" wipes KV but leaves search indices stale #938 covers stale search indexes after replace import. Snapshot restore has the same index-consistency class but a separate implementation.
Activity
fix: drain upstream bug backlog (28 issues)
docs(triage): mark rohitg00#1190 fixed by #127
fix: address review of #127