Stigmem Integration

9 min readFor integratorsUpdated 2026-05-19

What you'll find here

How Craik integrates with Stigmem as its reference memory and truth substrate — the boundary, the memory-store interface, the minimum compatibility target, endpoint mapping, capability detection, fact mapping, source identity, the local proposal model, contradiction and memory-diff strategies, error mapping, and the local backend.

Stigmem is the truth substrate. Craik is the runtime.

Stigmem owns durable facts, provenance, scopes, trust, and conflict detection. Craik owns case files, policy, capability grants, receipts, handoffs, and the orchestration loop. The interface between them is a small, versioned set of HTTP calls.

Boundary

Stigmem owns

• Facts
• Provenance
• Scopes
• Trust metadata
• Contradiction tracking
• Federation
• Auth
• Memory plugin hooks

Craik owns

• Task orchestration
• Project case files
• Agent role assignment
• Capability grants
• Receipts
• Handoffs
• Work graph state
• Operator workflows

Memory-store interface

Craik defines a capability-based memory interface so non-Stigmem backends remain feasible.

Required base

Read facts · propose facts · write facts · search facts · list by entity · attach provenance · record handoff references.

Advanced

Contradiction detection · trust tiers · scoped visibility · memory diff · expiration / stale-risk markers · federation.

Minimum compatibility target

The first Stigmem backend targets the current reference-node HTTP API.

Required endpoints

HTTP

GET /healthz · GET /.well-known/stigmem · POST /v1/facts · GET /v1/facts · GET /v1/facts/{fact_id} · GET /v1/facts/{fact_id}/provenance

Required auth

behavior

Bearer API keys via Authorization: Bearer <key>. Detect requirement from /.well-known/stigmem. Surface 401/403 as configuration errors. Never log raw API keys.

Fact-model fields

required

id · entity · relation · value · source · timestamp · confidence · scope

Assertion fields

required

entity · relation · value · source · confidence · scope · optional valid_until · optional garden_id · optional attestation

Query filters

required

entity · relation · source · scope · min_confidence · include_contradicted · include_expired · after · cursor · limit

Scopes

required

local · team · company · public

Federation, gardens, source attestation, quarantine, tombstones, vector recall, and plugins are not required. Craik uses them when the backend advertises them and falls back gracefully when it doesn't.

Endpoint mapping

Craik memory method	Stigmem endpoint	Required	Notes
health()	GET /healthz	Yes	Confirms node is reachable.
discover()	GET /.well-known/stigmem	Yes	Reads node id, URL, auth mode, federation, attestation, namespaces.
write_fact(fact)	POST /v1/facts	Yes	Used only when policy grants direct memory write.
propose_fact(proposal)	Local Craik store, optional later Stigmem fact	Yes	Stigmem has immutable facts, not a proposal queue; Craik keeps proposals locally until approved.
search_facts(query, scope)	Prefer POST /v1/recall; fallback to GET /v1/facts	Optional recall, required fallback	Recall gives ranked results; query is the minimum reliable path.
list_facts(entity, relation, scope)	GET /v1/facts	Yes	Paginate with cursor and limit.
get_fact(fact_id)	GET /v1/facts/{fact_id}	Yes	UUID or CID where node supports CID addressing.
get_provenance(fact_id)	GET /v1/facts/{fact_id}/provenance	Yes	Used to populate evidence and case files.
list_contradictions()	GET /v1/conflicts	Optional	Use if available; otherwise local contradiction reports.
resolve_contradiction()	POST /v1/conflicts/{conflict_id}/resolve	Optional	Requires explicit memory-write grant.
memory_diff(run_id)	Craik local store	Yes	Stigmem does not provide run-scoped diffs; Craik computes from proposals/writes.

Capability detection

At connect time, Craik probes the backend.

1. GET /healthz returns success.
2. GET /.well-known/stigmem returns metadata.
3. If auth is required, authenticated GET /v1/facts?limit=1 succeeds.
4. If writes are configured, Craik validates permissions by policy and surfaces the first write failure clearly (no dry-run available).

Optional probes — used when available, never required.

POST /v1/recall

Ranked retrieval.

GET /v1/conflicts

Stigmem-level contradictions.

GET /v1/auth/keys

Key inspection.

Provenance endpoint

GET /v1/facts/{fact_id}/provenance availability.

Source attestation

Mode from well-known metadata.

Federation

Status from well-known metadata.

Detected capabilities live in Craik local state and surface in case files when relevant.

Fact mapping

Craik field	Stigmem field
entity	entity
relation	relation
value	value
source	source
confidence	confidence
scope	scope
expires_at	valid_until
garden_id	garden_id
attestation	attestation

Craik uses stable relation namespaces and avoids the reserved stigmem: prefix for ordinary product facts.

Recommended prefixes: craik:task:* · craik:handoff:* · craik:receipt:* · craik:docs:* · craik:policy:* · codex:* only for Codex-specific automation or team-fact compatibility.

Source and identity

Source form

When to use

Notes

agent:craik

generic

Anonymous runtime source.

agent:craik:<runner>

runner-scoped

Identifies the executing runner adapter.

agent:craik:<runner>:<stable-agent-id>

identity-scoped

Identifies a stable agent identity within the runner.

user:<id>

human

When the operator is the source of the assertion.

Attestation modes.

If Stigmem source attestation runs in enforce mode, Craik either sets source to the authenticated entity URI or attaches a valid Stigmem agent-key attestation. In warn mode, Craik surfaces warnings through receipts and handoffs.

Local proposal model

Craik does not treat every proposed fact as an immediate Stigmem write.

Agent-created facts

Default to local memory proposals.

Direct Stigmem writes

Require an explicit memory-write grant.

Approval flow

User approval promotes proposals to Stigmem facts.

Rejected proposals

Stay local for audit unless retention policy removes them.

This preserves Craik's strict-by-default posture while keeping Stigmem as the durable truth substrate.

Contradiction strategy

Stigmem exposes conflicts when facts with the same entity, relation, and scope disagree. Craik uses Stigmem conflicts where the backend provides them, but always keeps its own local contradiction reports.

Stigmem conflicts

When available, list with GET /v1/conflicts?status=unresolved. Link conflict facts into case files. Require explicit memory-write grant before POST /v1/conflicts/{conflict_id}/resolve.

Local contradiction reports

Not every Craik contradiction is a Stigmem-level conflict. Examples: docs say a task is planned but GitHub shows it merged · public docs contain internal-only labels · a handoff contradicts later branch state · a runner result conflicts with a verifier result.

Local contradiction reports may later produce Stigmem fact proposals.

Memory diff

Craik owns run-scoped memory diffs.

Local proposals created

Proposals approved

Stigmem facts written

Stigmem write failures

Facts read into case file

Contradictions opened

Contradictions resolved

Handoff summary fact writes

Stigmem facts are referenced by id and cid when available.

Error mapping

HTTP status	Craik meaning
400	Invalid request or unsupported query shape.
401	Missing or invalid API key.
403	Insufficient Stigmem permission.
404	Missing fact, endpoint, or tombstone-hidden fact.
409	Duplicate or already-resolved lifecycle conflict.
422	Schema validation failure.
5xx	Node unavailable or internal node error.

Error redaction is mandatory.

Error messages must be redacted before they are persisted in receipts, logs, handoffs, or case files.

Stigmem fact usage

Craik uses Stigmem facts to assemble case files.

Repo current state

Branch and PR status

Docs policy

ADR policy

Implementation decisions

Known gaps

Stale-risk docs

Agent handoffs

Capability constraints

Project conventions

Stigmem fact writes

Craik writes facts when agents learn reusable project state.

Doc policy

That future agents must respect.

Recurring validation command

Implementation constraint

Repository convention

Stale documentation warning

Completed migration status

Contradiction needing resolution

Handoff storage

Handoffs live as structured artifacts; summary facts go to Stigmem.

The full handoff may live in Craik storage or the repository. Stigmem receives enough metadata for discovery: task id · repository · branch · agent identity · summary · changed artifacts · facts learned · unresolved questions · handoff URI.

Local development

Local memory is for dev and tests — not a product thesis.

A local memory backend exists to lower setup friction and keep tests deterministic. Stigmem remains the production-grade reference backend.

What's next

GuideConnecting StigmemConcrete connection steps, capability detection, and troubleshooting.ReadGovernanceHow memory writes are policy-gated and receipt-backed.ReadRuntime contractsThe fact-proposal and memory-backend contract shapes.