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

> Discover how the Git snapshot feature versions AgentMemory state by embedding code version into state.json. Learn this complete technical guide for rohitg00/agentmemory.

- Repository: [Rohit Ghumare/agentmemory](https://github.com/rohitg00/agentmemory)
- Tags: deep-dive
- Published: 2026-05-10

---

**The Git snapshot feature versions AgentMemory state by embedding the current `VERSION` constant from [`src/version.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/version.ts) into every [`state.json`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/src/version.ts) and embeds it directly into the JSON structure written to disk:

```typescript
// 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`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/src/config.ts) (lines 25-35) and registered with the III SDK in [`src/index.ts`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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:

```bash
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`](https://github.com/rohitg00/agentmemory/blob/main/src/index.ts) initializes the automatic snapshot task in [`src/functions/snapshot.ts`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/src/version.ts) into every [`state.json`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/src/version.ts) (line 1) and consumed by [`src/functions/snapshot.ts`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/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`](https://github.com/rohitg00/agentmemory/blob/main/state.json) alongside the `version` and `timestamp` metadata before the Git commit occurs.