Version: v0.9.0a2

Operator

Migrating from v1.x to v2.0

Retracted — neither v1.x nor v2.0 shipped publicly

Per ADR-001, the canonical version line of stigmem begins at v0.9.0a1 (2026-05-09). The version markers v1.x and v2.0 referenced in this document labeled internal development checkpoints, not tagged public releases — there is no installed v1.x or v2.0 to migrate from. This document is preserved as historical record of an announced-but-withdrawn migration path.

Migrating from v1.x to v2.0

10 min readOperatorArchived migration

What this document is

Historical step-by-step upgrade guide for Stigmem v1.x to v2.0 — federation trust, recall, lazy instructions, security hardening, RTBF, time-travel, CIDs. Preserved as the record of an announced but withdrawn migration path.

Audience: Operators and developers running a stigmem node on v1.0 or pre-reset draft who want to upgrade to v2.0. Spec reference: v2.0 promotes §19–§25 from draft to normative. §1–§18 are unchanged.

Breaking changes

v2.0 introduces new database migrations, mandatory mTLS for federation, and new wire-format fields. Read the full guide before upgrading a production node.

Upgrade overview

Area

Spec

What changed

Federation trust

§19

Org manifests, capability tokens, transparency log.

Recall & graph

§20

Graph index, vector embeddings, hybrid recall, memory cards, subscriptions.

Lazy instructions

§21

Boot stub, instruction manifest, recall_instruction tool.

Security hardening

§22

mTLS, key rotation, audit log, quotas, replay protection.

RTBF tombstones

§23

Tombstone records, recall-time filter, federation propagation.

Time-travel queries

§24

as_of parameter on recall and facts endpoints.

Content-addressed IDs

§25

SHA-256 CIDs, dual addressing, federation tamper detection.

Suggested cutover order

Security hardening (§22) — enable mTLS and audit logging first; all subsequent features depend on it.
Federation trust (§19) — publish your org manifest and set up transparency log integration.
Recall & graph (§20) — run the embedding backfill; enable the recall pipeline.
Lazy instruction discovery (§21) — migrate instruction files if applicable.
RTBF tombstones (§23) — enable the tombstone API and federation route.
Time-travel queries (§24) — available immediately after §23 migrations.
Content-addressed IDs (§25) — run stigmem backfill-cids last (non-blocking).

Experimental features

Feature

Section · Risk

Constraint

Lazy Instruction Discovery

§21 · prompt injection

Do not use for agents handling sensitive data or irreversible tool use until GA.

RTBF Tombstones

§23 · federated erasure

Do not rely on tombstone federation for GDPR/CCPA in multi-node deployments.

Time-Travel Queries

§24 · post-erased data

Test isolation behavior on your production backend before compliance use.

Content-Addressed Fact IDs

§25 · CID-less accepted

Do not rely on CID as a security control in untrusted federation topologies.

Operator warnings (GA features with non-obvious risks)

Feature

Risk

Required action

§22.1 mTLS

silent plaintext fallback

Set STIGMEM_MTLS_REQUIRED=true in production.

§19.4 Source-trust cache

per-worker incoherence

Set STIGMEM_TRUST_CACHE_BACKEND=redis for production multi-worker.

§6.7–§6.8 N-node backpressure

draft spec

Test your topology in staging.

§19.5 Quarantine Garden

silent data loss

Pre-create quarantine garden before enabling trust_mode=strict.

Database migrations

Migration

Creates

Purpose

013a

tombstones, tombstone_revocations

RTBF tombstone storage (§23.5.3).

013b

facts.cid, fact_cid_aliases

Content-addressed IDs (§25.3.1).

013c

fact_retractions

Append-only retraction log for time-travel (§24.2.1).

# Docker Compose (recommended)
git pull
docker compose up --build -d

# Verify migrations
curl -s http://localhost:8787/v1/admin/status | jq '.migrations'

Rolling back after tombstones have been issued will lose RTBF compliance state.

Take a backup before upgrading.

Federation trust (§19)

Breaking change

Impact

Action required

Org manifest required

connections rejected

Publish manifest at /.well-known/stigmem-manifest.json.

Capability tokens replace ad-hoc trust

existing fail

Issue federate verb tokens for each peer.

Transparency log integration

strict mode

Configure Rekor or self-hosted log.

90-day token expiry ceiling

renewal cycle

Set up automated token renewal.

Migration steps:

Generate an Ed25519 keypair for your node: stigmem keygen --out /etc/stigmem/node-key.pem
Publish your org manifest: stigmem manifest publish --entity-uri "stigmem://your-org/node-1" --key /etc/stigmem/node-key.pem
Issue capability tokens for each federation peer via POST /v1/federation/tokens.
Configure trust mode: STIGMEM_FEDERATION_TRUST_MODE=strict for production, relaxed for development.

Recall & graph (§20)

Breaking change

Impact

Action required

entity_edges materialized at startup

first-boot rebuild

Allow extra startup time.

Embedding storage (vec_facts)

nomic-embed-text default

Ensure Ollama is running or configure an alternative provider.

GET /v1/recall replaces ad-hoc queries

SDK update

Update SDK calls.

Graph depth capped at 3

HTTP 400

Update any client code using deeper traversal.

# Default: Ollama with nomic-embed-text (local, Apache-2.0)
ollama pull nomic-embed-text

# Or use a cloud provider
export STIGMEM_EMBED_PROVIDER=openai
export STIGMEM_EMBED_MODEL=text-embedding-3-small

Allow time for initial embedding backfill.

For large stores (100k+ facts), this may take several minutes.

Lazy instruction discovery (§21)

If you are not using lazy instructions, no action is required — the feature is opt-in. If migrating from file-based instructions:

stigmem instruction migrate \
  --role engineer \
  --skill coding \
  --input ./instructions/ \
  --db stigmem.db

5-stage deprecation path ensures no instruction loss:

Shadow — instructions loaded from both file and stigmem; mismatches logged.
Flip — primary source switches to stigmem; file is fallback.
File-off — file loading disabled; stigmem-only.
Cleanup — file removed from deployment.
Archive — original files preserved in audit storage.

Security hardening (§22)

Breaking change

Impact

Action required

mTLS required for federation

plaintext rejected

Provision node certificates.

TLS 1.3 floor enforced

TLS 1.2 refused

Verify your TLS stack supports 1.3.

Audit log mandatory

14 event types

Ensure audit storage is provisioned.

Per-principal quotas active

HTTP 429

Review default quota ceilings.

Replay protection (±5 min)

stale nonces rejected

Ensure node clocks are NTP-synced.

Default quotas (per principal per minute):

Dimension

Ceiling

Notes

fact_write

100

—

fact_read

1000

—

token_issue

—

recall

200

—

graph_query

200

—

subscription_create

—

admin_action

—

Key rotation: Ed25519 signing keys SHOULD be rotated every 90 days (capability issuer) or 365 days (node signing).

stigmem key rotate --entity-uri "stigmem://your-org/node-1"

RTBF / tombstones (§23)

Breaking change

Impact

Action required

POST /v1/tombstones

admin-only

Grant admin keys to compliance operators.

Recall-time filter active

automatic

Tombstoned entities excluded from all recall and graph results.

Federation tombstone route

5-min poll

Issue tombstone:read capability tokens to peers.

Memory card suppression

automatic

Cards about tombstoned entities fully suppressed.

# Issue a tombstone (admin key required)
curl -X POST http://localhost:8787/v1/tombstones \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity_uri": "user:test-entity", "scope": "*", "reason": "test"}'

Tombstones use RFC 8785 (JCS) canonical JSON.

"signature" and "reason" fields are excluded before canonicalization. The key_id field identifies the signing key without trial-verification.

Time-travel / as-of queries (§24)

# What did we know about Alice on Jan 1, 2025?
resp = httpx.post("http://localhost:8787/v1/recall", json={
    "intent": "Alice preferences",
    "as_of": "2025-01-01T00:00:00Z",
    "scope": "company",
})

Tombstone interaction:

legal_hold: false (default) — entity is suppressed from ALL queries including historical.
legal_hold: true — entity is suppressed from live queries but visible in as_of queries for admin keys only.

Content-addressed fact IDs (§25)

Breaking change

Impact

Action required

cid field on all new facts

automatic

—

Dual-addressing during 12-month window

prefer CID

Update clients to prefer CID addressing.

Federation tamper detection

mismatched CID rejected

Ensure all peers are on v2.0.

# Run CID backfill for existing facts
stigmem backfill-cids --batch-size 1000 --rate-limit 500

# Monitor progress
curl http://localhost:8787/v1/admin/cid-backfill/status \
  -H "Authorization: Bearer $ADMIN_KEY"

# Verify integrity on a sample
curl -X POST http://localhost:8787/v1/facts/fact_01J.../verify-cid \
  -H "Authorization: Bearer $AGENT_KEY"

CID format:

CID = "sha256:" + hex_lowercase(SHA-256(RFC8785(canonical_body)))

The canonical body includes exactly six fields: entity, relation, value, scope, source, confidence — in lexicographic key order per RFC 8785.

Environment variable summary (new in v2.0)

Variable

Default

Section

STIGMEM_FEDERATION_TRUST_MODE

relaxed

§19

STIGMEM_EMBED_PROVIDER / _MODEL / _DIMENSIONS

ollama / nomic / 768

§20

STIGMEM_CARD_MAX_AGE_S

86400

§20

STIGMEM_SUBSCRIPTION_REPLAY_S

3600

§20

STIGMEM_LAZY_INSTRUCTIONS

true

§21

STIGMEM_AUDIT_LOG_PATH / _ENABLED

stderr / true

§22

STIGMEM_QUOTAS_ENABLED

true

§22

STIGMEM_REPLAY_WINDOW_S

300

§22

STIGMEM_TOMBSTONE_CACHE_TTL_S

§23

STIGMEM_CID_BACKFILL_BATCH

1000

§25

STIGMEM_MTLS_REQUIRED

false

§22.1 — set true behind reverse proxies.

STIGMEM_TRUST_CACHE_BACKEND

memory

§19.4 — set redis for multi-worker.

STIGMEM_REDIS_URL

none

§19.4 — required when trust cache is Redis.

STIGMEM_REQUIRE_CID

false

§25 — set true to reject CID-less facts.

Pre-upgrade checklist

Back up your database.
Verify NTP clock sync on all nodes (±5 min tolerance for replay protection).
Ensure Ollama or alternative embedding provider is available.
Provision mTLS certificates for each federation peer.
Generate Ed25519 keypair and prepare org manifest content.
Coordinate upgrade timing with federation peers (mixed v1/v2 federation is not supported).
Plan for initial embedding backfill time (proportional to fact count).
Allocate admin API keys for compliance operators (tombstone management).

Migrating from v1.x to v2.0

Migrating from v1.x to v2.0

Upgrade overview

Suggested cutover order

Experimental features

Operator warnings (GA features with non-obvious risks)

Database migrations

Federation trust (§19)

Recall & graph (§20)

Lazy instruction discovery (§21)

Security hardening (§22)

RTBF / tombstones (§23)

Time-travel / as-of queries (§24)

Content-addressed fact IDs (§25)

Environment variable summary (new in v2.0)

Pre-upgrade checklist

Getting help

Spec v2.0 (full text)

Operator runbooks

Security hardening guide

API reference

Migrating from v1.x to v2.0

Upgrade overview​

Suggested cutover order​

Experimental features​

Operator warnings (GA features with non-obvious risks)​

Database migrations​

Federation trust (§19)​

Recall & graph (§20)​

Lazy instruction discovery (§21)​

Security hardening (§22)​

RTBF / tombstones (§23)​

Time-travel / as-of queries (§24)​

Content-addressed fact IDs (§25)​

Environment variable summary (new in v2.0)​

Pre-upgrade checklist​

Getting help​

Spec v2.0 (full text)

Operator runbooks

Security hardening guide

API reference

Upgrade overview

Suggested cutover order

Experimental features

Operator warnings (GA features with non-obvious risks)

Database migrations

Federation trust (§19)

Recall & graph (§20)

Lazy instruction discovery (§21)

Security hardening (§22)

RTBF / tombstones (§23)

Time-travel / as-of queries (§24)

Content-addressed fact IDs (§25)

Environment variable summary (new in v2.0)

Pre-upgrade checklist

Getting help