Skip to main content
Version: v0.9.0a2
Integrator

Stigmem in OpenClaw

5 min readOpenClaw developer · Node operatorAlpha connector

What this guide covers

Evaluate persistent, federated memory for OpenClaw agents via the stigmem-node ClawHub skill. The skill provides four surfaces: a boot handshake that injects prior context into the system prompt, plus write surfaces for handoffs, decisions, and escalations.

Audience: OpenClaw skill developers and node operators deploying Stigmem as a shared knowledge store across agents.

Alpha connector

The OpenClaw connector is available in the v0.9.0aN alpha line for evaluation, not as a recommended production integration. The adapter now separates retrieved content from instruction-channel recall output and exports a required system prompt directive, with audit-mapped C1-C4/H1-H5 regression coverage. See LIMITATIONS.md §9.

Installation​

ClawHub (alpha evaluation)​

skill install stigmem-node

OpenClaw reads the skill's env-var manifest and prompts for STIGMEM_URL on first use. adapter.py is bundled in the skill directory.

pip​

uv add "stigmem-py>=0.9.0a2,<1.0.0"
# or
pip install --pre "stigmem-py>=0.9.0a2,<1.0.0"

Environment variables​

Variable
Required
Description
STIGMEM_URL
yes
Base URL of your Stigmem node.
STIGMEM_API_KEY
yes
Least-privilege API key. OpenClawStigmemAdapter.from_env() fails closed when missing.
STIGMEM_SOURCE_ENTITY
no
Entity URI identifying this agent. Default: agent:openclaw.
STIGMEM_OPENCLAW_ALLOWED_HANDOFF_TARGETS
no
Comma-separated agent: entity URI allowlist for handoff and escalation targets. The source entity is always allowed.

Usage​

from adapter import OpenClawStigmemAdapter, SYSTEM_PROMPT_DIRECTIVE   # ClawHub bundled path
# or: from stigmem_openclaw.adapter import OpenClawStigmemAdapter  # pip install

adapter = OpenClawStigmemAdapter.from_env()

Boot handshake​

ctx = adapter.boot(
    user_entity="user:alice",
    project_entities=["project:my-roadmap"],
)
system_prompt = base_prompt + (
    "\n\n" + SYSTEM_PROMPT_DIRECTIVE + "\n\n" + ctx.summary if ctx else ""
)

boot() raises OpenClawBootError when the node is unreachable.

Treat that as a failed boot, not as a healthy empty context. A successful query with no matching facts still returns an empty BootContext.

Emit a decision​

adapter.emit_decision(
    entity="decision:auth-provider",
    summary="Chose Clerk over Auth0: simpler Next.js integration, lower per-seat cost.",
)

Decisions are append-only; dedupe externally before calling if your workflow needs at-most-once semantics.

Emit an escalation​

adapter.emit_escalation(
    to_entity="agent:cto",
    goal="Approve increased Stripe webhook rate limit for the pre-reset design work load.",
    priority="high",
)

priority accepts "low", "medium", "high", or "critical". Escalations carry a 24-hour expiry.

Emit a handoff​

adapter.emit_handoff(
    from_entity="agent:openclaw",
    to_entity="agent:assistant",
    summary="Auth provider chosen; Stripe limit escalation pending.",
    fact_refs=["fact-auth-decision", "fact-esc-stripe"],
    continuation="Resume from the Stripe rate-limit discussion.",
    idempotency_key="session-2026-05-02-abc",
)

fact_refs are persisted as ref-typed fact values. If you pass a non-empty fact_refs list and none validate, the adapter raises before writing a provenance-free handoff. Use idempotency_key for retries.

Security​

Property
Behavior
Notes
Source binding
construction-time
STIGMEM_SOURCE_ENTITY cannot be overridden per call. Use a per-deployment entity URI.
Untrusted retrieved context
channel-separated
boot() wraps retrieved facts in UNTRUSTED STIGMEM CONTENT delimiters. Put SYSTEM_PROMPT_DIRECTIVE above ctx.summary so the model treats retrieved memory as data.
API key scope
least privilege
Scope to the nodes this agent reads/writes. Do not share across unrelated deployments. Rotate regularly.
Fact persistence
across sessions
Facts persist across sessions and agents. Retract stale facts explicitly rather than relying on expiry.

Running your own Stigmem node​

docker run --rm -p 8765:8765 \
  -e STIGMEM_NODE_URL=http://localhost:8765 \
  ghcr.io/eidetic-labs/stigmem-node:latest

:latest is fine for trying things out; for production swap to a pinned version tag or a digest pin — see the tag-selection guide.

Smoke test​

from adapter import OpenClawStigmemAdapter

adapter = OpenClawStigmemAdapter.from_env()
ctx = adapter.boot(user_entity="user:test", project_entities=[])
print("boot ok:", ctx.summary[:80] if ctx else "(no prior context)")

See also​

adapters/openclaw README

Package source, changelog, full security model.

Federation guide

External node onboarding and multi-node topology.

Paperclip / Claude Code

MCP-based integration.

Authentication

API key setup and OIDC options.