📐 Spec

Spec-19-Adapter-ABI

5 min readSpec contributor · Adapter authorDraft · v0.9.0aN

What this spec defines

The stable adapter contract for code that bridges Stigmem into agent runtimes, tools, and platform hooks. Adapter behavior and failure contracts; protocol-wide conformance vectors belong to their owning component specs.

Extraction status

This file contains the ADR-010 prose extraction for the adapter ABI.

Legacy version labels from archived source material are normalized to the current v0.9.0a1 protocol line here. Historical wording remains available in spec/archive/evolution/ and spec/EVOLUTION.md.

Adapter archetypes

Archetype

Failure posture

Description

Process-mode

fail fast

Standalone processes whose primary purpose is to bridge another protocol to Stigmem. If Stigmem is unconfigured, fast failure is acceptable.

Middleware

fail open

Extend an existing agent runtime. Stigmem is optional; the host agent MUST continue operating if Stigmem is absent, unreachable, or degraded.

Adapters SHOULD clearly document which archetype they implement.

Environment contract

Adapters MUST honor these environment variables:

Variable

Required by

Description

STIGMEM_URL

all adapters

Base URL of the Stigmem node. No default.

STIGMEM_API_KEY

all adapters

API key when node auth is required. No default.

STIGMEM_SOURCE_ENTITY

middleware

Entity URI used as source on write operations. Default is adapter-specific.

Process-mode adapters MUST exit non-zero if STIGMEM_URL is absent. Middleware adapters MUST skip Stigmem operations and MUST NOT change the host process exit code.

Boot handshake

Adapters SHOULD probe the node at startup:

GET /.well-known/stigmem

The response must advertise node version, node id, node URL, auth mode, and federation capability. Missing or malformed required fields SHOULD be treated as a failed probe.

Process-mode adapters SHOULD log a probe failure and allow individual tool calls to fail with adapter-level errors. Middleware adapters MUST return an empty boot context and continue.

BootContext

Middleware adapters that inject Stigmem context return:

BootContext {
  facts:   Fact[]
  summary: string
}

BootContext is always returned. On total failure, it MUST be:

BootContext { facts: [], summary: "" }

Context pull

Middleware adapters MAY pull context during boot. All context queries are non-fatal. A failed or empty query MUST NOT abort startup.

Common context pulls include:

Confident user/agent facts

Above an adapter-defined confidence threshold.

Project constraints

Pending handoffs

Targeting STIGMEM_SOURCE_ENTITY.

Recent escalations

Adapters SHOULD filter pulled facts to relevant namespaces to avoid injecting unbounded or noisy context.

Write surfaces

Adapters may assert lifecycle, handoff, decision, or escalation facts. Write operations MUST use fire-and-forget semantics:

No host crash

Write failures MUST NOT crash the host process.

Log warning

Write failures SHOULD be logged at warning level.

Lifecycle confidence=1.0

Lifecycle and intent-routing facts SHOULD use confidence=1.0.

Local heartbeats

Activity/heartbeat facts MUST remain local unless a component spec explicitly says otherwise.

Paperclip-style lifecycle facts use the paperclip: namespace registered by Spec-16-Namespace-Registry. Intent and delegation facts use the intent: namespace.

Context injection format

Adapters that inject facts into an agent prompt SHOULD group facts by relation namespace and render a concise Markdown summary:

## Stigmem context - {user_entity}

### {namespace}
- **{relation}** on `{entity}`: {value_str}[ _(confidence: {confidence:.2f})_]

Rendering rules:

Omit empty blocks

Omit the entire context block when no facts were retrieved.

Verbatim identifiers

Preserve relation and entity strings verbatim.

Null rendering

Render null values as (null).

Confidence threshold

Include confidence only when below 1.0.

Ordering

Descending confidence, then descending HLC where available.

Adapters that handle prompt injection risks SHOULD layer additional sanitizer or structural-channel controls; those controls are outside this ABI.

Error handling contract

The crash-forbidden invariant applies to middleware adapters.

A Stigmem node failure MUST NOT crash the host agent process.

Scenario

Process-mode

Middleware

STIGMEM_URL absent

exit non-zero

Skip Stigmem operations; exit code unchanged.

Node unreachable at boot

log error; calls may fail

Log warning; return empty BootContext.

Node unreachable on write

log warning; no crash

Log warning; no crash.

HTTP 4xx on write

log error; no retry

Log error; no retry; no crash.

HTTP 5xx on write

log error; MAY retry once

Log error; MAY retry once; no crash.

Boot query 4xx/5xx

treat as empty

Treat as empty for that query.

Adapter-specific conformance

Adapters that write lifecycle or intent facts SHOULD include integration tests that verify:

1. Expected relations appear in the fact store after lifecycle events.
2. Client-side validation rejects facts with wrong scope or too-low confidence, or the node response is handled without crashing.
3. Node unavailability does not crash middleware-mode hosts.

Out of scope

This spec does not define:

Protocol-wide conformance vectors

Adapter package layout

Plugin lifecycle APIs

Sanitizer requirements

Prompt-injection.

Adapter relation inventories

Beyond registered namespace examples.

SDK implementation details

Experimental adapter behavior