Memory backends

3 min readReferenceUpdated 2026-05-19

What you'll find here

The proposal-first memory-backend interface, the three shipped backends (ephemeral · local · Stigmem), how case files load memory facts, the hygiene workflow, proposal status, and the diff/preview helpers.

Proposals are the default unprivileged path.

Direct writes require a policy grant. Local memory writes are denied until a granted write path exists.

Required behavior

Create reviewable proposals

List proposals

By task or status.

Approve proposals

Reject proposals

Search approved local facts

Require evidence

Before promotion.

Backends

Backend

Use for

Notes

EphemeralMemoryStore

tests / demos

Keeps proposals in process memory.

LocalMemoryStore

dev / local

Persists craik.memory_proposal records in SQLite. Approved local proposals are searchable as local facts. Rejected and pending proposals remain visible for audit but are not returned by fact search.

StigmemMemoryStore

production

Uses Stigmem HTTP API for shared durable memory; keeps proposals in Craik local state. Stigmem facts are immutable assertions, so Craik still uses local proposals until approved and policy grants a direct write.

Stigmem minimum endpoint mapping

GET /healthz

GET /.well-known/stigmem

POST /v1/facts

GET /v1/facts

GET /v1/facts/{fact_id}

GET /v1/facts/{fact_id}/provenance

Use craik connect stigmem to detect compatibility. Configure the node with CRAIK_STIGMEM_URL and authenticated nodes with CRAIK_STIGMEM_API_KEY.

Case-file context

Case files load queryable memory facts when a memory search backend is configured. They also include recent handoff summaries and open local contradiction reports so runner prompts carry current continuity and known conflicts forward.

If no facts are available, the case file keeps the explicit missing-memory assumption. Loaded facts remove that assumption and are counted in the context budget alongside recent handoff and contradiction ids.

Hygiene

craik.runtime.memory_hygiene.memory_hygiene_report summarizes pending memory proposals, approved proposals, open contradictions, recent handoffs, and release warnings.

Pre-release hygiene.

MVP release work treats pending proposals and unresolved contradictions as hygiene items to review before packaging.

Proposal status

Status

Visible to

Notes

pending

audit

Awaiting review.

approved

fact search

Searchable as local facts.

rejected

audit

Retained for audit; not searchable.

Approval records reviewer identity, decision reason, and decision timestamp.

Diff and preview

craik.memory_diff

Task-scoped memory activity: proposals created · proposals approved or rejected · facts written · write failures · facts read.

craik.memory_impact_preview

Expected impact before promotion or direct writes: facts to add · facts to invalidate · likely contradictions · missing evidence · scope counts.

craik memory diff <task-id>
craik memory preview <task-id>

What's next

GuideMemory proposalsThe operator-facing flow this backend serves.GuideConnecting StigmemConfigure the production backend.ReadStigmem integrationThe full boundary and endpoint mapping.