Memory And Stigmem

6 min readCore conceptUpdated 2026-05-19

What you'll learn

• Why Craik treats memory as governed project state, not a transcript cache.
• The proposal-first contract for agent-created memory updates.
• The split of responsibility between Craik and Stigmem.
• What Craik v0.1.0 actually does with memory today.

Proposal-first

Agent-created memory updates default to proposals — durable, evidence- backed candidate facts that remain reviewable until a human (or a policy grant) promotes them. Direct durable writes are a separate, explicit capability.

Why "proposal-first"?

Memory that gets written silently corrupts the runtime. Once a fact lands without evidence or review, every downstream case file that loads it inherits an unverifiable claim — and the contradiction surfaces weeks later as a mysterious disagreement nobody can attribute.

The proposal-first contract makes the failure mode loud instead. Every agent-initiated update is a craik.memory_proposal record with:

Evidence

References back to the source — repo file, GitHub issue, prior handoff, upstream fact, run receipt.

Scope

The memory scope the proposal targets. Narrow scopes are easier to approve and easier to retire.

Reason

Why this proposal exists. The reviewer's first question.

Visibility

Approved local proposals become searchable local facts. Rejected and pending proposals remain visible for audit.

Direct writes are a separate capability

Direct durable memory writes require an explicit memory.write policy authority. This applies to local and Stigmem-backed workflows alike.

When a runner attempts a memory write without that authority, Craik:

1. Refuses the write.
2. Creates a memory proposal with the would-be fact and an evidence reference to the attempt.
3. Records a receipt naming the missing capability so the operator can decide whether to grant it.

This pattern is intentional. Memory writes ride the same approval flow as any other privileged capability. No special path lets a runner widen its authority by virtue of "the agent said so."

Craik vs Stigmem: who owns what

Craik owns

• Orchestration: tasks, case files, handoffs, runners.
• Receipts and the work graph.
• Policy, capability grants, redaction, immutable paths.
• Operator workflows: review, approval, contradiction handling.
• Local memory state in degraded / offline mode.

Stigmem owns

• Durable facts and provenance.
• Memory scopes and trust metadata.
• Contradiction tracking across scopes.
• Federation between Stigmem nodes.
• Auth and plugin hooks for the memory substrate itself.

Craik can run in degraded local mode without Stigmem — proposals, diffs, previews, and read paths all work against the local SQLite store. For real team-scale memory, Stigmem is the reference substrate.

What v0.1.0 actually does

The current MVP behaviour is precise and conservative:

• Detects minimum Stigmem compatibility through a versioned API negotiation.
• Reads facts through the Stigmem HTTP API.
• Gets fact provenance so case files can cite where memory came from.
• Keeps local memory proposals regardless of whether Stigmem is reachable.
• Builds memory diffs and impact previews for every task that touched memory.
• Denies direct writes without grants — proposals are the fallback.
• Creates demo memory proposals through craik demo stigmem-docs so the contract is exercised end-to-end in CI.

Case files currently mark missing memory facts as assumptions. As the case-file assembler grows a Stigmem fact loader, those assumptions get replaced by actual evidence references — the schema doesn't change, just the completeness.

The memory lifecycle in one diagram

agent run ──proposal──▶ memory_proposal (pending)
                              │
                              ├── reviewer approves ──▶ fact (local)
                              ├── reviewer rejects  ──▶ stays as audit
                              └── promotion expires ──▶ stays pending

Memory diffs (craik memory diff <task>) and impact previews (craik memory preview <task>) are the operator surfaces that drive this lifecycle.

A pragmatic checklist

When you're deciding what to do with a pending proposal:

1. Read the evidence. Every proposal cites at least one evidence reference. If the reference doesn't actually support the claim, reject.

2. Check the scope. A proposal that wants to land in a wide scope (org:*) deserves more skepticism than one scoped to a single project.

3. Look at contradictions. The impact preview surfaces collisions with existing approved facts. Resolve before approving.

4. Promote, reject, or carry forward. All three are legitimate outcomes — the wrong move is to leave proposals stale and untriaged.

What's next

DoManage memory proposalsThe proposal lifecycle from creation to approval to retirement.DoResolve contradictionsHow conflicting facts surface and how the inbox tracks resolutions.ReferenceMemory backendsConfiguration for local memory and Stigmem-backed memory.