Memory Cold Store

The cold store exports periodic snapshots of all three durable memory tiers — daily memory, knowledge graph entities, and procedural memory — to S3, Google Cloud Storage, or the local filesystem. Snapshots provide a point-in-time backup independent of the Postgres database.

What is snapshotted

Memory tier	Table	Included
Tier 2 — Daily memory	`daily_memories`	All entries for the user
Tier 4 — Knowledge graph	`graph_entities`	All entities and their properties
Tier 5 — Procedural memory	`procedural_memory`	All workflows, rules, and templates

User profiles (Tier 3) are excluded from cold store snapshots — they are lightweight enough to keep only in Postgres.

Configuration

Set the backend and bucket via environment variables:

bash

# Local filesystem (default, no extra deps)
COLD_STORE_BACKEND=local
COLD_STORE_BUCKET=/var/backups/openastra

# S3
COLD_STORE_BACKEND=s3
COLD_STORE_BUCKET=my-astra-backups
COLD_STORE_REGION=us-east-1
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

# Google Cloud Storage
COLD_STORE_BACKEND=gcs
COLD_STORE_BUCKET=my-astra-backups
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

Snapshot format

Each snapshot is a single JSON file stored at:

text

snapshots/{date}/memory-{uid}-{timestamp}.json
# e.g. snapshots/2026-02-26/memory-uid_alice-1740621600000.json
# or   snapshots/2026-02-26/memory-all-1740621600000.json  (all users)

The file contains a top-level snapshotAt timestamp, the uid (null for all-user snapshots), and arrays for each tier.

Automatic schedule

The cold store does not run on a built-in cron schedule — you trigger it by calling snapshotMemory() from a scheduled agent or an external cron job. A typical setup runs a nightly all-user snapshot:

sql

INSERT INTO scheduled_agents
  (workspace_id, agent_id, cron_expression, input_message, surface, surface_id, created_by)
VALUES
  (NULL, 'admin-agent', '0 2 * * *',
   'Run a full memory cold-store snapshot for all users.',
   'chat', 'cold-store-cron', 'system');

Manual snapshot

bash

# Trigger a manual snapshot for a specific user
curl -X POST http://localhost:3000/admin/memory/snapshot \
  -H "x-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "uid": "uid_alice" }'

# Snapshot all users
curl -X POST http://localhost:3000/admin/memory/snapshot \
  -H "x-api-key: ${API_KEY}"

ℹCold store snapshots are append-only — each run creates a new file rather than overwriting an existing one. Prune old snapshots from your storage bucket to manage costs.