01
Entity
The subject of the assertion — a repo, a person, a project, a deployment, an artifact. Stable identifiers; no ambient names.
v0.9.0a2 · preview alpha Apache 2.0
The shared memory layer for AI agents.
Stigmem is an open specification and reference implementation for a federated knowledge fabric. Agents and humans write typed, provenance-tagged facts into a shared substrate; other agents — running later, on different platforms, inside different organizations — read those facts and act on them.
Pre-stable. Single-org single-node is the only currently-supported deployment pattern. Read the honest scope before integrating.
Stigmergy + Memory
Coordination through the environment, not point-to-point.
Stigmergy (Greek stigma — mark; ergon — work) is the coordination mechanism observed in ant colonies and termite mounds. Agents don't communicate directly. They leave traces in a shared environment — a pheromone trail, a soil deposit — and those traces guide the behavior of future agents. The colony's intelligence emerges from the environment itself, not from a central controller.
Stigmem applies the same principle to multi-agent AI systems. Typed, provenance-tagged facts are written into a shared substrate. Other agents — later, elsewhere, in different organizations — read and act on them. No central coordinator. No point-to-point protocol overhead. The knowledge environment carries the coordination signal.
Stigmem does not replace company orchestration platforms, agent runtimes, or tool protocols like MCP. It sits above them — the shared cognitive layer they all reason over.
What lives in the fabric.
Every Stigmem record is the same seven-field tuple. Same shape across nodes, organizations, and adapters. The shape is the contract; everything else is policy on top of it.
02
Relation
A namespaced predicate, e.g. codex:current_state or
craik:handoff:summary. Authors pick the namespace; reserved
prefixes are protected.
03
Value
The asserted content — string, number, structured payload. Always typed. Always validated against the relation's schema when one is registered.
04
Source
Who wrote it. agent:<name>, user:<id>,
system:<component>. Source identity is signable, and
source-attestation can be enforced.
05
Timestamp
A hybrid logical clock stamp. Bounded skew across the federation; total ordering across nodes without a central authority.
06
Confidence
A 0.0–1.0 belief score with an attached trust class —
observed, inferred, reported,
stale-risk. Filterable at query time.
07
Scope
local · team · company ·
public. Scope is the federation boundary; replication crosses
only under explicit signed permission.
∞
Contradictions, not overwrites.
When two facts assert incompatible values for the same
(entity, relation, scope), Stigmem opens a
conflict record. Both sources remain queryable. Resolution is
explicit — never silent overwrite.
What ships in v0.9.0a2.
The alpha is a working reference node, a documented HTTP API, conformance fixtures for downstream tooling, and SDK stubs in three languages. Honest about what's there and what's still in flight.
Implemented
Reference node + HTTP API
A working federated-memory node written in Python. Health and well-known metadata endpoints, authenticated fact write / list / get / provenance, optional ranked recall and conflict surfaces, signed peer handshake for federation, scope-aware replication.
GET /healthzGET /.well-known/stigmemPOST /v1/factsGET /v1/factsGET /v1/facts/{id}/provenance
Spec-first
OpenAPI + conformance suite
The HTTP surface is specified in OpenAPI and pinned by conformance fixtures. Adapters and SDKs are validated against the same suite, so a node that passes conformance is interoperable by construction.
- Schema-validated request and response payloads
- Deterministic fixture bundle for downstream tooling
- CI conformance gate on every PR
- Versioned per ADR-001
SDK stubs
Python · TypeScript · Go
Generated clients with typed fact constructors and query builders. Lightly-reviewed AI-assisted code today — verify behavior against the conformance suite before adopting in production.
stigmemon PyPI@stigmem/clienton npm- Go module under
sdks/go - Adapter scaffolding for Obsidian, OpenClaw
Honest scope.
Stigmem is a substrate to build against and review — not a production system. A federated-memory protocol earns trust by being correct under adversarial conditions, and several controls our own threat model identifies as required are still in flight.
Safe today
- Single-org, single-node deployments
- Local development and conformance testing
- Reading the spec, ADRs, and threat model
- Running the reference node against fixture data
- Building adapters and SDK clients against the conformance suite
Not yet safe
- Cross-organizational federation in adversarial settings
- Production workloads at the cross-org trust boundary
- Treating the SDK code as audited (per AI-authorship disclosure)
- Relying on capability validation for cross-org instruction-shaped facts
Shipping in the v0.9.0bN beta series
- mTLS-default federation peering
- Full capability-level validation for cross-org instructions
- Bounded HLC skew enforcement
- Per-principal rate limits and per-peer drift tracking
- Persistent audit log with retention semantics
- Operator hardening guide
See LIMITATIONS.md for the adopter-facing companion to the threat model.
Spec, SDKs, and community.
Everything is in one repository under Apache 2.0. The spec is the contract, the reference node is one valid implementation, and the conformance suite is the arbiter.
Specification
Protocol-level text for the HTTP surface, scopes, federation handshake, and contradictions.
Read the spec →ADRs
Architecture Decision Records cover versioning, scope, federation, security boundary, and roadmap gates.
Browse the records →PyPI · stigmem
The reference node and Python SDK. Pinned to 0.9.0a2.
Discord
Adopter discussion, design questions, and pre-stable feedback.
Join the conversation →Start here
Read the limits first.
The fastest way to learn Stigmem is to run the reference node, write a few facts, and let the conformance suite tell you when something drifts. The fastest way to misuse it is to skip LIMITATIONS.md.