How the Git Snapshot Feature Versions AgentMemory State: Complete Technical Guide

The Git snapshot feature versions AgentMemory state by embedding the current VERSION constant from src/version.ts into every state.json file before committing it to a local Git repository, creating a permanent, immutable link between data state and code release.

The rohitg00/agentmemory repository implements a robust versioning mechanism that ties persistent state snapshots to specific software releases. Understanding how the Git snapshot feature versions AgentMemory state is essential for reproducible agent recoveries, debugging across deployments, and ensuring compatibility during rollbacks.

Core Implementation in snapshot.ts

The versioning logic resides primarily in src/functions/snapshot.ts (lines 28-77). When the mem::snapshot-create function is invoked, it executes a sequence of operations that ensures every persisted state carries explicit version metadata.

Repository Initialization

Before writing state, the code invokes ensureGitRepo to validate that a local Git repository exists at the configured snapshot directory. If the repository is absent, the function initializes a new Git repo to receive the versioned state files.

Embedding Version Metadata

The critical versioning step occurs when constructing the state object. The implementation imports VERSION from src/version.ts and embeds it directly into the JSON structure written to disk:

// src/functions/snapshot.ts (lines 28-77)
const state = {
  version: VERSION,          // Imported from src/version.ts
  timestamp: ts,
  sessions,
  memories,
  graphNodes,
  observations,
  accessLogs,
};

writeFileSync(
  join(snapshotDir, "state.json"),
  JSON.stringify(state, null, 2),
  "utf-8"
);

Commit and Metadata Generation

After persisting state.json, the function commits the file to the Git repository and returns a SnapshotMeta object containing the commit hash, timestamp, and statistics. This creates an immutable reference that ties the AgentMemory version string to a specific Git commit hash.

Configuration and Function Registration

The snapshot system is configured through environment variables defined in src/config.ts (lines 25-35) and registered with the III SDK in src/index.ts (lines 96-100).

Environment Variables:

• SNAPSHOT_ENABLED: Boolean flag to activate the feature
• SNAPSHOT_DIR: Filesystem path for the Git repository
• SNAPSHOT_INTERVAL: Seconds between automatic snapshots

In src/index.ts, the registerSnapshotFunction binds three core operations—mem::snapshot-create, mem::snapshot-list, and mem::snapshot-restore—to the SDK, making them available to agents and CLI tools.

Practical Usage Examples

Creating Versioned Snapshots Manually

To trigger a snapshot programmatically via the III SDK:

import { registerWorker } from "iii-sdk";
import { registerSnapshotFunction } from "./src/functions/snapshot.js";
import { StateKV } from "./src/state/kv.js";

const sdk = registerWorker("ws://localhost:49134", { workerName: "demo" });
const kv = new StateKV(sdk);

// Register functions with snapshot directory
registerSnapshotFunction(sdk, kv, "/tmp/agentmemory-snapshots");

const result = await sdk.trigger({
  function_id: "mem::snapshot-create",
  payload: { message: "Manual backup" },
});

console.log(result.snapshot.version); // "0.9.5" from src/version.ts

Listing Snapshots by Version

Retrieve historical snapshots to audit which AgentMemory versions created specific states:

const list = await sdk.trigger({
  function_id: "mem::snapshot-list",
});

console.log(list.snapshots);
/*
[
  { commitHash: "a1b2c3d", createdAt: "2026-05-10T12:34:56Z", message: "Manual backup" },
  { commitHash: "f4e5d6a", createdAt: "2026-05-09T09:21:41Z", message: "Automatic hourly snapshot" }
]
*/

Restoring and Validating Versions

Restore operations can inspect the embedded version to ensure compatibility:

const restore = await sdk.trigger({
  function_id: "mem::snapshot-restore",
  payload: { commitHash: "a1b2c3d..." },
});

if (restore.success) {
  // Read back the version from the restored state
  import { readFileSync } from "fs";
  import { join } from "path";
  
  const state = JSON.parse(
    readFileSync(join("/tmp/agentmemory-snapshots", "state.json"), "utf-8")
  );
  console.log("Snapshot created with AgentMemory version:", state.version);
}

Enabling Automatic Snapshots

Configure the background scheduler for periodic, versioned backups:

export SNAPSHOT_ENABLED=true
export SNAPSHOT_DIR=$HOME/.agentmemory/snapshots
export SNAPSHOT_INTERVAL=3600  # seconds (1 hour)

When these variables are set, src/index.ts initializes the automatic snapshot task in src/functions/snapshot.ts, which periodically invokes mem::snapshot-create and tags each commit with the current VERSION.

Summary

• The Git snapshot feature versions AgentMemory state by embedding the VERSION constant from src/version.ts into every state.json file written to disk.
• Each snapshot is committed to a local Git repository, creating an immutable audit trail linking data state to the specific AgentMemory release.
• Three SDK functions—mem::snapshot-create, mem::snapshot-list, and mem::snapshot-restore—provide the API surface for both manual and automated operations.
• Configuration via SNAPSHOT_ENABLED, SNAPSHOT_DIR, and SNAPSHOT_INTERVAL environment variables controls automatic snapshot behavior.
• The stored version field enables post-restore compatibility checks, ensuring that newer AgentMemory instances can identify snapshots created by older releases.

Frequently Asked Questions

Where is the version string defined in AgentMemory?

The version string is exported as VERSION from src/version.ts (line 1) and consumed by src/functions/snapshot.ts during the creation of every snapshot. This constant is hardcoded at build time and reflects the current package release.

Can I restore a snapshot created by a different AgentMemory version?

Yes. The mem::snapshot-restore function reads the committed state.json and deserializes the KV tables. While restoration is permitted regardless of version, the embedded version field allows your application logic to detect compatibility gaps between the creating and restoring AgentMemory releases.

How do I enable automatic hourly snapshots?

Set SNAPSHOT_ENABLED=true, specify a writable directory in SNAPSHOT_DIR, and set SNAPSHOT_INTERVAL=3600 (representing 3600 seconds) before starting the AgentMemory worker. The initialization logic in src/index.ts (lines 96-100) will then activate the background scheduler.

What data is included in a versioned snapshot?

The snapshot captures a complete dump of in-memory state including sessions, memories, graph nodes, observations, and access logs from the KV store. All entities are serialized into state.json alongside the version and timestamp metadata before the Git commit occurs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}