Skip to main content
Version: MVP

Connecting Stigmem

3 min readFor operatorsUpdated 2026-05-19

What you'll do

Point Craik at a Stigmem node, check compatibility, and learn the default posture for memory writes (proposals first, direct writes only under explicit grant).

Compatibility is detected, not assumed.

craik connect stigmem probes the minimum v0.1.0 endpoints and prints a backend-capabilities payload. The API key is never printed.

Configure the node​

Set the node URL and, when the node requires authentication, a bearer API key.

export CRAIK_STIGMEM_URL=http://127.0.0.1:18765
export CRAIK_STIGMEM_API_KEY=<api-key>

Check compatibility​

craik connect stigmem

The command probes the minimum endpoints:

GET /healthz

GET /.well-known/stigmem

GET /v1/facts?limit=1

It prints a craik.memory_backend_capabilities payload and never prints the API key.

Direct writes​

Proposals are the default.

Direct Stigmem fact writes require a matching memory.write policy grant and use POST /v1/facts. Without a grant, agent-created facts become local proposals.

Use local proposals when a task does not have direct write authority:

craik memory propose task_review_docs \
  --entity repo:example \
  --relation craik:current_state \
  --value "Documentation reconciliation requires evidence." \
  --source docs/guides/connecting-stigmem.md \
  --evidence-source docs/guides/connecting-stigmem.md \
  --evidence-locator docs/guides/connecting-stigmem.md \
  --evidence-summary "The connection guide documents Stigmem compatibility."

Environment variables​

Variable
Default
Purpose
CRAIK_STIGMEM_URL
unset
Base URL for the Stigmem node.
CRAIK_STIGMEM_API_KEY
unset
Bearer token for authenticated nodes.
CRAIK_STIGMEM_TIMEOUT
5.0
Request timeout in seconds.

Store API keys in the environment or local secret tooling — never commit them to project files.

Stigmem-backed credentials​

Craik can also resolve provider credentials from Stigmem facts through stigmem-ref auth profiles. The profile points at a Stigmem node, entity, scope, and relation such as craik:credential:value; credential material is resolved at request time and is not printed in receipts or logs.

This is useful when a team wants shared provider credentials with Stigmem provenance and revocation semantics. The auth profile metadata is file-backed in <CRAIK_HOME>/auth-profiles.json.

What's next​

GuideMemory proposalsThe default unprivileged path for agent-created facts.GuideAuthenticationProfile shape and audit behavior for stigmem-ref credentials.ReadStigmem integrationThe full boundary, endpoints, and fact-mapping reference.