Metadata-Version: 2.4
Name: stigmem
Version: 0.9.0a9
Summary: Stigmem — federated knowledge fabric for AI agents (meta-package)
Author-email: Eidetic Labs <oss@eidetic-labs.ai>
License: Apache-2.0
Project-URL: Homepage, https://github.com/eidetic-labs/stigmem
Project-URL: Documentation, https://docs.stigmem.dev
Project-URL: Repository, https://github.com/eidetic-labs/stigmem
Project-URL: Issues, https://github.com/eidetic-labs/stigmem/issues
Project-URL: Changelog, https://github.com/eidetic-labs/stigmem/blob/main/CHANGELOG.md
Keywords: stigmem,federation,memory,ai,agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: stigmem-py<1.0.0,>=0.9.0a9
Provides-Extra: node
Requires-Dist: stigmem-node<1.0.0,>=0.9.0a9; extra == "node"
Provides-Extra: openclaw
Requires-Dist: stigmem-openclaw<1.0.0,>=0.9.0a9; extra == "openclaw"
Provides-Extra: lazy-instruction-discovery
Requires-Dist: stigmem-plugin-lazy-instruction-discovery<2.0.0,>=0.1.0; extra == "lazy-instruction-discovery"
Provides-Extra: memory-garden-acl
Requires-Dist: stigmem-plugin-memory-garden-acl<2.0.0,>=0.1.0; extra == "memory-garden-acl"
Provides-Extra: multi-tenant
Requires-Dist: stigmem-plugin-multi-tenant<2.0.0,>=0.1.0; extra == "multi-tenant"
Provides-Extra: source-attestation
Requires-Dist: stigmem-plugin-source-attestation<2.0.0,>=0.1.0; extra == "source-attestation"
Provides-Extra: time-travel
Requires-Dist: stigmem-plugin-time-travel<2.0.0,>=0.1.0; extra == "time-travel"
Provides-Extra: tombstones
Requires-Dist: stigmem-plugin-tombstones<2.0.0,>=0.1.0; extra == "tombstones"
Provides-Extra: plugins-all
Requires-Dist: stigmem-plugin-lazy-instruction-discovery<2.0.0,>=0.1.0; extra == "plugins-all"
Requires-Dist: stigmem-plugin-memory-garden-acl<2.0.0,>=0.1.0; extra == "plugins-all"
Requires-Dist: stigmem-plugin-multi-tenant<2.0.0,>=0.1.0; extra == "plugins-all"
Requires-Dist: stigmem-plugin-source-attestation<2.0.0,>=0.1.0; extra == "plugins-all"
Requires-Dist: stigmem-plugin-time-travel<2.0.0,>=0.1.0; extra == "plugins-all"
Requires-Dist: stigmem-plugin-tombstones<2.0.0,>=0.1.0; extra == "plugins-all"
Provides-Extra: all
Requires-Dist: stigmem-node<1.0.0,>=0.9.0a9; extra == "all"
Requires-Dist: stigmem-openclaw<1.0.0,>=0.9.0a9; extra == "all"
Requires-Dist: stigmem-plugin-lazy-instruction-discovery<2.0.0,>=0.1.0; extra == "all"
Requires-Dist: stigmem-plugin-memory-garden-acl<2.0.0,>=0.1.0; extra == "all"
Requires-Dist: stigmem-plugin-multi-tenant<2.0.0,>=0.1.0; extra == "all"
Requires-Dist: stigmem-plugin-source-attestation<2.0.0,>=0.1.0; extra == "all"
Requires-Dist: stigmem-plugin-time-travel<2.0.0,>=0.1.0; extra == "all"
Requires-Dist: stigmem-plugin-tombstones<2.0.0,>=0.1.0; extra == "all"
Dynamic: license-file

# Stigmem - Federated Knowledge Fabric + Intent Protocol

[![CI](https://github.com/eidetic-labs/stigmem/actions/workflows/ci.yml/badge.svg)](https://github.com/eidetic-labs/stigmem/actions/workflows/ci.yml)
[![Conformance](https://github.com/eidetic-labs/stigmem/actions/workflows/conformance.yml/badge.svg)](https://github.com/eidetic-labs/stigmem/actions/workflows/conformance.yml)
[![Coverage](https://stigmem.dev/coverage-badge.svg)](https://stigmem.dev/coverage/)
[![PyPI version](https://img.shields.io/pypi/v/stigmem?include_prereleases&label=pypi)](https://pypi.org/project/stigmem/)
[![npm version](https://img.shields.io/npm/v/@eidetic-labs/stigmem-mcp/alpha?label=npm%3A%40eidetic-labs%2Fstigmem-mcp)](https://www.npmjs.com/package/@eidetic-labs/stigmem-mcp)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Stability: preview alpha](https://img.shields.io/badge/stability-preview%20alpha-orange.svg)](#why-pre-stable)
[![Discord](https://img.shields.io/discord/1502847943118684331?label=discord&logo=discord&logoColor=white&color=5865F2)](https://discord.gg/Z47Re7FjjV)

> **Status: `v0.9.0a9` - preview alpha, pre-stable. Apache-2.0**
> **Repository:** [github.com/eidetic-labs/stigmem](https://github.com/eidetic-labs/stigmem)
> **Not yet recommended for production federation across organizational boundaries.** See [LIMITATIONS.md](LIMITATIONS.md).

Stigmem is the 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 peer via a signed handshake; facts replicate under
explicit scope permission; contradictions surface as first-class records, not
silent overwrites. Stigmem is audit-first: the guarantee is not that an agent
will do the right thing, but that every fact it asserted is attributable,
replayable, and revocable.

---

## Why pre-stable

The public version line was reset from an earlier `v1.0` announcement to
`v0.9.0a1` so the release label matches the validated stability posture.
Controls our threat model identifies as required for production -
mTLS-default federation, persistent audit log, per-principal rate limits,
capability-level validation for cross-org instructions, bounded HLC skew
enforcement - remain hardened-core work rather than shipped GA guarantees.

`v0.9.0a1` is the **first build of stigmem** under the canonical version line.
Earlier markers (`v0.2` through `v2.0`) labeled internal development
checkpoints, not tagged releases anyone deployed. Spec content under those
markers is real and being forward-migrated section by section under
[ADR-019](docs/adr/019-amendment-to-adr-001-prerelease-version-strings.md).

Full retraction post: [dev.to/offbyonce/walking-back-our-v10-announcement-resetting-to-v090a1-as-the-first-build-al0](https://dev.to/offbyonce/walking-back-our-v10-announcement-resetting-to-v090a1-as-the-first-build-al0).
In-repo canonical copy: [`archive/devto-stigmem-v0.9.0a1-retraction.md`](archive/devto-stigmem-v0.9.0a1-retraction.md).
Progress notes: [`LOG.md`](LOG.md).

## Quickstart - 60 seconds to a running node

```bash
# 1. Pull and start signed multi-arch images from GHCR.
git clone https://github.com/eidetic-labs/stigmem && cd stigmem
docker compose up -d

# 2. Assert a fact.
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 .

# 3. Recall it.
curl -s 'http://localhost:8765/v1/facts?entity=user:alice&scope=company' | jq .facts
```

`docker compose up` brings up two federated nodes (`node-a` on 8765, `node-b`
on 8766) so you can run federation handshakes immediately. The full
[two-node federation tutorial](docs/docs/get-started/quickstart-tutorial.md)
takes about 10 minutes and includes the PeerDeclaration handshake, scope
replication, adversarial demo, and post-tear-down inspection recipes.

## Install

### Docker (recommended)

```bash
git clone https://github.com/eidetic-labs/stigmem
cd stigmem
docker compose up -d
```

`docker compose up` pulls pre-built multi-arch images from GHCR
(`ghcr.io/eidetic-labs/stigmem-node:0.9.0a9`, signed via Sigstore cosign with
attached SBOMs). The recipe pins to the version tag for reproducibility; use
`docker compose up --build -d` when you are contributing local code changes.

Two federated nodes start immediately:

| Node | Host port | Interactive API | Node metadata |
| --- | --- | --- | --- |
| `node-a` | 8765 | `http://localhost:8765/docs` | `http://localhost:8765/.well-known/stigmem` |
| `node-b` | 8766 | `http://localhost:8766/docs` | `http://localhost:8766/.well-known/stigmem` |

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

| Variable | Default | Purpose |
| --- | --- | --- |
| `STIGMEM_NODE_URL` | `http://localhost:8765` | Public URL included in PeerDeclarations |
| `STIGMEM_FEDERATION_ENABLED` | `false` | Enable pull replication |
| `STIGMEM_FEDERATION_PULL_INTERVAL_S` | `30` | Seconds between pull cycles |
| `STIGMEM_AUTH_REQUIRED` | `true` | Require Bearer token on every request. Set `false` for local dev only |
| `STIGMEM_DB_PATH` | `stigmem.db` | SQLite database path |

Full environment variable reference:
[Operating Stigmem - Install](docs/docs/operators/deployment/install.md).

### Python via uv

```bash
cd stigmem/node
uv run python -m stigmem_node
```

### Pre-release via pip

Because `v0.9.0a9` is a PEP 440 pre-release, `pip install stigmem` will not
pick it up by default. Use `--pre` and choose the scope:

```bash
pip install --pre stigmem                          # SDK only
pip install --pre stigmem[node]                    # SDK + reference node service
pip install --pre stigmem[openclaw]                # SDK + alpha adapter package
pip install --pre 'stigmem[plugins-all]'           # SDK + every published plugin
pip install --pre stigmem[all]                     # everything published from this repo
```

Individual plugin extras: `stigmem[lazy-instruction-discovery]`,
`stigmem[memory-garden-acl]`, `stigmem[multi-tenant]`,
`stigmem[source-attestation]`, `stigmem[time-travel]`, `stigmem[tombstones]`.
Each is an independently versioned PyPI package (`stigmem-plugin-<name>`)
released under [ADR-011](docs/adr/011-plugin-independent-versioning.md).

The MCP server is a separate npm package:

```bash
npm install -g @eidetic-labs/stigmem-mcp
# or, ephemeral:
npx -y @eidetic-labs/stigmem-mcp@0.1.0
```

## Plugins

Six experimental plugins are published as independent PyPI packages
(`stigmem-plugin-<name>@0.1.0`). Installing makes a plugin discoverable through
the `stigmem.plugins` entry-point group; turning behavior on still requires the
plugin-specific `STIGMEM_*_ENABLED` environment variable and a node restart.

| Plugin | What it adds | Package / extra | Enable gate |
| --- | --- | --- | --- |
| Lazy instruction discovery | Boot context resolves instructions on demand | `stigmem-plugin-lazy-instruction-discovery` / `stigmem[lazy-instruction-discovery]` | `STIGMEM_LAZY_INSTRUCTION_DISCOVERY_ENABLED` |
| Time travel | Historical handoff and decision queries | `stigmem-plugin-time-travel` / `stigmem[time-travel]` | `STIGMEM_TIME_TRAVEL_ENABLED` |
| Tombstones | Hides retracted facts from recall and boot context | `stigmem-plugin-tombstones` / `stigmem[tombstones]` | `STIGMEM_TOMBSTONES_ENABLED` |
| Memory Garden ACL | Membership controls which gardens boot reads | `stigmem-plugin-memory-garden-acl` / `stigmem[memory-garden-acl]` | `STIGMEM_MEMORY_GARDEN_ACL_ENABLED` |
| Source attestation | Recalled facts carry source trust scores | `stigmem-plugin-source-attestation` / `stigmem[source-attestation]` | `STIGMEM_SOURCE_ATTESTATION_ENABLED` |
| Multi-tenant scoping | Boot, handoff, decision, and escalation become tenant-scoped | `stigmem-plugin-multi-tenant` / `stigmem[multi-tenant]` | `STIGMEM_MULTI_TENANT_ENABLED` |

Inspect local state with `stigmem plugins list`, `stigmem plugins describe
<plugin>`, and `stigmem plugins doctor`. Full catalog and per-plugin security
notes: [docs/docs/plugins](docs/docs/plugins/index.md).

## MCP + editor integrations

Stigmem ships an [MCP](https://modelcontextprotocol.io) server so LLM-aware
editors can read from and write to a Stigmem node directly from chat.

```bash
stigmem mcp doctor                    # check node + npm + npx availability
stigmem mcp detect                    # enumerate editor configs found locally
stigmem mcp config codex-cli          # print metadata + connector guide
stigmem mcp install codex-cli         # dry-run preview; credential omitted
stigmem mcp install codex-cli --write # write the editor config file
stigmem mcp smoke codex-cli           # round-trip handshake test
```

`stigmem mcp config <editor>` prints metadata and the connector guide link
only. `stigmem mcp install <editor>` defaults to a dry run and previews the
planned Stigmem server entry with the credential field omitted. Passing
`--write` applies the change with a timestamped backup.

| Editor | Validation tier | Connector guide |
| --- | --- | --- |
| Codex CLI | Validated | [docs/integrations/mcp/codex-cli](https://docs.stigmem.dev/en/latest/docs/integrations/mcp/codex-cli) |
| Claude Code | Validated | [docs/integrations/mcp/claude-code](https://docs.stigmem.dev/en/latest/docs/integrations/mcp/claude-code) |
| Gemini CLI | Caveated | [docs/integrations/mcp/gemini-cli](https://docs.stigmem.dev/en/latest/docs/integrations/mcp/gemini-cli) |
| Continue.dev | Experimental | [docs/integrations/mcp/continue-dev](https://docs.stigmem.dev/en/latest/docs/integrations/mcp/continue-dev) |
| Cursor | Experimental | [docs/integrations/mcp/cursor](https://docs.stigmem.dev/en/latest/docs/integrations/mcp/cursor) |
| Zed | Experimental | [docs/integrations/mcp/zed](https://docs.stigmem.dev/en/latest/docs/integrations/mcp/zed) |

A running node also exposes `GET /v1/mcp/connectors` so editors and
provisioning tools can discover available connectors programmatically.

## Federation, briefly

```text
node-a -- PeerDeclaration, Ed25519-signed --> node-b
node-a <-- pull replication, scoped facts ----- node-b

Contradictions become first-class conflict records instead of silent overwrites.
```

Scope membership, replication direction, and conflict semantics are specified
in [`spec/05-federation-trust.md`](spec/05-federation-trust.md) and exercised
in CI by the conformance suite plus `make demo-attack`.

## Architecture

```text
stigmem/
├── spec/           <- canonical specification
├── node/           <- reference node: FastAPI + SQLite
├── adapters/       <- adapter packages, MCP server, ClawHub skill
├── sdks/           <- Python and TypeScript client SDKs
├── experimental/   <- plugin source trees + deferred features
└── docs/           <- Docusaurus 3 documentation site
```

Each plugin lives at `experimental/<plugin>/` as its own publishable package
and ships independently to PyPI under
[ADR-011](docs/adr/011-plugin-independent-versioning.md).

### Structural CI guards

The following invariants are mechanically enforced on PRs. Failures block merge:

| Guard | What it enforces |
| --- | --- |
| `check_admin_determination.py` | Admin-determination logic is consistent across routes |
| `check_tenant_resolution.py` | Tenant resolution wraps tenant-scoped reads and writes |
| `check_plugin_readme_sections.py` | Plugin READMEs have required publication sections |
| `check_plugin_manifest_version_consistency.py` | Plugin package version literals agree |
| `check_plugin_readme_pypi_consistency.py` | README, extras, and docs catalog agree on plugin packages |
| `check_mcp_readme_consistency.py` | MCP README, CLI catalog, docs, and `/v1/mcp/connectors` agree |
| `check_readme_shape.py` | Root README keeps this structure, plugin table, and MCP tiers aligned |

See [`scripts/`](scripts/) for the full guard set.

## Security posture

Stigmem is pre-stable; the design center is audit-first. Every fact written
through a Stigmem node is attributable to a source, replayable through the HLC
clock, and revocable through tombstones or a manual retract call. The guarantee
is integrity of the record trail, not soundness of the upstream agent's
reasoning.

Adopters should read these documents before integrating against the API:

- **[LIMITATIONS.md](LIMITATIONS.md)** - adopter-facing constraints and safe deployment patterns
- **[SECURITY.md](SECURITY.md)** - vulnerability disclosure and supported versions
- **[`spec/security/threat-model.md`](spec/security/threat-model.md)** - STRIDE risk register with per-release status
- **[Security architecture](docs/docs/security/index.md)** - capability boundaries, federation trust model, prompt-injection handling per [ADR-003](docs/adr/003-prompt-injection.md)
- **Release-cadence runbook** - `docs/internal/release-cadence.md` covers how releases are cut, verified, and rolled back

Single-org single-node deployments are the only currently supported pattern.
Cross-org federation needs the hardened-core work tracked in
[`ROADMAP.md`](ROADMAP.md).

## Adjacent systems

Stigmem deliberately does not compete with:

- **Agent runtimes** - Stigmem is the shared substrate agents reason over, not the runtime that executes them.
- **Company orchestration platforms** - Stigmem sits upstream; orchestrator events become typed facts.
- **Tool protocols** - [MCP](https://modelcontextprotocol.io) is a transport; the Stigmem MCP server ships Stigmem as an MCP tool surface.

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

## AI-authorship disclosure

Stigmem is built by two contributors with heavy AI-coding assistance. We disclose this because a category whose product is trust shouldn't quietly hide where the work came from.

**Paths with deeper human review (line-by-line):**
- `spec/` — protocol specification text
- `docs/adr/` — Architecture Decision Records
- `LIMITATIONS.md`, `SECURITY.md`, `MAINTAINERS.md`, root `README.md`
- All threat-model entries (`spec/security/`, `docs/security/`)

**Paths with lighter human review (high-level direction + spot-checks):**
- `node/src/` — implementation
- `adapters/` — adapter implementations
- `sdks/` — SDK stubs
- `apps/` — UI scaffolding
- Test suites
- Documentation pages outside the spec and ADRs

This disclosure is also in [`CONTRIBUTING.md`](CONTRIBUTING.md) and the docs-site [AI authorship disclosure](docs/docs/community/ai-authorship.md). It is not a defect notice — it's a calibration aid for anyone evaluating whether to trust stigmem with their workload. Treat the lighter-reviewed paths as you would any AI-written code: verify behavior against the spec, run the conformance suite, and audit before adopting.

---

## The name

**Stigmem** = **Stigmergy** + **Memory**.

[Stigmergy](https://en.wikipedia.org/wiki/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.

---

## Spec

The canonical specification lives in [`spec/`](spec/). See [`spec/README.md`](spec/README.md) for the section-by-section status table.

The spec is being reviewed and improved into the v0.9.0a1 canonical structure: core sections first, then experimental sections move to `experimental/<feature>/spec.md` per [ADR-008](docs/adr/008-experimental-gates.md) and [ADR-010](docs/adr/010-modular-specs.md). Earlier evolutionary spec files (`stigmem-spec-pre-reset.md` through `stigmem-spec-pre-reset draft.md`) move to `spec/archive/evolution/` after their content has been forward-migrated. Nothing from the spec is being deleted.

---

## Community

Real-time chat: **[discord.gg/Z47Re7FjjV](https://discord.gg/Z47Re7FjjV)**.

The Stigmem Discord is where adopters, contributors, and operators discuss installation, federation, the spec, and SDK use. Help channels are organized by topic (`#install-help`, `#usage-questions`, `#federation-help`, `#troubleshooting`); spec and contributor discussion lives under the **Development** category. Asynchronous discussion continues to happen in [GitHub Discussions](https://github.com/eidetic-labs/stigmem/discussions) — both work.

If you're already running Stigmem in production and would consider participating in the future hardened-core external operator soak, mention it in `#dev-general` or DM `@offbyonce`. We're recruiting.

For security disclosures, see [SECURITY.md](SECURITY.md) — never report vulnerabilities in Discord.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for the RFC process. Short version:

1. Open an issue using the [RFC template](.github/ISSUE_TEMPLATE/rfc.yml)
2. Discuss and iterate
3. Submit a PR against the canonical spec — new sections start as draft blocks inside the relevant spec file
4. Spec changes merge per the **[ADR-001 §Contributor approval rule](docs/adr/001-versioning.md)**: two contributors *or* the founder alone, through the pre-stable hardening window.

For bugs in the reference node, use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.yml).

Maintainers and contributors are listed in [MAINTAINERS.md](MAINTAINERS.md).

---

## Security

To report a vulnerability, use GitHub's private advisory process — **do not open a public issue**. See [SECURITY.md](SECURITY.md) for the full disclosure policy and the v0.9.0a9 security posture statement.

The full STRIDE threat model with per-release risk-register status lives at [`spec/security/threat-model.md`](spec/security/threat-model.md). See also [Security posture](#security-posture) above.

---

## License

Apache-2.0. See [LICENSE](LICENSE).
