Status: v1.0 stable · Phase 7 (substrate) · Apache-2.0 Repository: github.com/Eidetic-Labs/stigmem

Stigmem is an open specification and reference implementation for a federated knowledge fabric: a shared, persistent layer where AI agents and humans write typed, traceable facts that travel across tools, platforms, and organizations.

Every fact is an immutable record — (entity, relation, value, source, timestamp, confidence, scope) — with full provenance, a hybrid logical clock timestamp, and a defined expiry. Nodes can peer with each other via a signed handshake; facts replicate across scope boundaries under explicit permission. Contradictions between nodes are surfaced as first-class records, not silently overwritten.

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.

Stigmem = Stigmergy + Memory.

Stigmergy (Greek stigma — mark; ergon — work) is the coordination mechanism observed in ant colonies and termite mounds: agents don't communicate directly with each other. Instead, 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 any central controller.

Stigmem applies the same principle to multi-agent AI systems. Agents 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. No central coordinator, no point-to-point protocol overhead. The knowledge environment carries the coordination signal.

The Memory half reflects persistence and decay: facts have valid_until expiries and confidence scores, so the substrate stays fresh rather than accumulating stale state — just as pheromone trails fade when they're no longer reinforced.

Single node (Docker — recommended):

git clone https://github.com/Eidetic-Labs/stigmem
cd stigmem
docker compose up --build -d

Two federated nodes start immediately:

Key environment variables (STIGMEM_ prefix, set in docker-compose.yml environment: block):

→ Full environment variable reference: docs/docs/install.md

Single node (Python / uv):

cd stigmem/node
uv run python -m stigmem_node

Migrating from bare-metal to Docker? See the upgrade path guide.

→ docs/docs/getting-started/quickstart.md — zero to two-node federation in under 10 minutes.

Quick summary:

# 1. Start two nodes
git clone https://github.com/Eidetic-Labs/stigmem && cd stigmem
docker compose up --build -d

# 2. Federation handshake (register both directions)
docker exec stigmem-node-a-1 \
  stigmem federation register-peer \
    --local-url http://node-a:8765 --remote-url http://node-b:8765 --scopes company,public
docker exec stigmem-node-b-1 \
  stigmem federation register-peer \
    --local-url http://node-b:8765 --remote-url http://node-a:8765 --scopes company,public

# 3. Assert a fact on node-a
curl -s -X POST http://localhost:8765/v1/facts \
  -H 'Content-Type: application/json' \
  -d '{"entity":"user:alice","relation":"memory:prefers","value":{"type":"string","v":"dark mode"},
       "source":"agent:settings","confidence":1.0,"scope":"company"}' | jq .

# 4. Wait ~30 s, then verify replication on node-b
curl -s 'http://localhost:8766/v1/facts?entity=user:alice&scope=company' | jq .facts

For automated reproducibility testing:

bash scripts/quickstart-verify.sh

cd stigmem/node
uv run pytest tests/ -v

stigmem/
├── spec/           ← canonical specification (v0.2 → v1.0 stable)
├── node/           ← reference node: FastAPI + SQLite, 74 tests
├── adapters/       ← MCP server (TypeScript), OpenClaw (Python), Paperclip (JS hook)
├── dogfood/        ← CEO memory migration scripts
└── docs/           ← Docusaurus 3 documentation site

See docs/docs/architecture/ for the full architecture reference, or docs/docs/about/state-of-stigmem.md for the current-state narrative.

Stigmem does not compete with:

• Agent platforms (OpenClaw/Claude Code) — Stigmem is the shared substrate agents reason over, not an agent runtime.
• Company orchestration (Paperclip) — Stigmem sits upstream of Paperclip; the Paperclip adapter emits issue lifecycle events as Stigmem facts.
• Tool protocols (MCP) — MCP is the transport; the Stigmem MCP adapter ships Stigmem as an MCP server.

It fills the gap none of them fill: typed, provenance-traceable, federated, entity-scoped shared knowledge.

The canonical specification lives in spec/. See spec/README.md for the section-by-section status table.

Current stable version: spec/stigmem-spec-v1.0.md — §1–18 all stable; §17 Memory Garden and §18 Source Attestation promoted from v0.9-draft.

See CONTRIBUTING.md for the RFC process. Short version:

1. Open an issue using the RFC template
2. Discuss and iterate
3. Submit a PR against the canonical spec (spec/stigmem-spec-v1.0.md) — new sections start as draft blocks inside the stable spec file
4. Spec changes merge with ≥2 approvals from active contributors

For bugs in the reference node, use the bug report template.

To report a vulnerability, use GitHub's private advisory process — do not open a public issue. See SECURITY.md for the full disclosure policy and the v1.0-rc security posture statement.

Apache-2.0. See LICENSE.