stigmergy

Stigmergy is the team version of the wiki in Karpathy's gist. Immutable source material enters one queue, one librarian agent keeps a small Git-and-Markdown wiki current, and every search and answer is scoped to what the caller may see.

Ants coordinate by leaving traces in the environment, not by talking to each other. Here every capture is a trace — a person reacting in Slack, an agent finishing a task in Claude Code — the librarian follows the traces, and the wiki emerges. Nobody approves a queue.

• Why

• How it works

• The write path

• The knowledge model

• Using it · Claude Code / Codex · Slack · Backoffice · MCP tools

• Visibility and security

• Models

• Quality and tests

• Quick start

• Deployment

• Repository layout

• Design principles

• Documentation

Why

A one-person wiki works because the loop is tiny. Once several people and agents write to the same wiki, you need what a shared deployment forces on you: identity, visibility, concurrency, binary evidence, Slack, audit. Stigmergy adds exactly that and nothing that duplicates the loop.

Related MCP server: sourcebook

How it works

1. Capture. Thin adapters authenticate and acquire bytes. Local files and private Google Drive documents stay on your machine until uploaded through a presigned URL.

2. Queue. Every adapter produces the same kind-free CaptureEnvelope. The Postgres queue is durable, leased, and idempotent per actor and client key.

3. Write. One serialized writer extracts text, renders the immutable source page, asks the librarian for a FilingPlan, and advances the branch only when every gate passes.

4. Remember. The knowledge repository is plain Git and Markdown. Postgres is operational state and a rebuildable index, never a second wiki.

5. Read. Five MCP tools for agents, @brain for people, one visibility policy. A webhook indexes incrementally; a nightly full rebuild guarantees convergence.

The write path

States are queued → processing → landed | failed. Nothing waits for a human: ambiguity becomes an explicit contradiction, technical failures retry within a bounded lease, and a terminal failure carries a typed error the master can retry. A crash after the commit is reconciled by commit SHA, never by a second commit.

The librarian may create or rewrite a note or concept, consolidate and delete a redundant page, propose an entity claim, add or resolve a contradiction, or file nothing — the source still lands. It never rewrites sources/ and never broadens an ACL. Deletion is a separate explicit operation (brain_delete) through the same writer and gates.

The knowledge model

A note or concept carries a maturity (seed, developing, mature, evergreen), an optional ACL, entity anchors, and its sources:

---
id: page_aurora_renewal
type: note
title: Aurora renewal
status: mature
created: 2026-08-10
updated: 2026-08-10
acl:
- sales
entity:
- ent_11111111-1111-4111-8111-111111111111
sources:
- sources/2026/08/20000000-0000-4000-8000-000000000002.md
---

# Aurora renewal

Aurora Systems agreed to an annual renewal with a budget of EUR 120,000. The renewed term starts
on 15 September 2026.

Entities are opaque IDs with scoped, sourced name claims; facts live in notes and concepts and describe_entity composes them at read time. Merging needs a shared external ID or an exact assertion in a source — resemblance does nothing.

When credible sources disagree, the librarian keeps both claims in a strict marker on the narrowest page whose readers may see both:

> [!WARNING] Unresolved contradiction `con_3f1c2b9a-6d4e-4a2b-9c1d-2f7e8a9b0c1d`
> The two renewal sources disagree on the annual budget.
> - **Claim:** The annual renewal budget is EUR 120,000
>   **Date:** `2026-08-10`
>   **Source:** `sources/2026/08/20000000-0000-4000-8000-000000000002.md`
> - **Claim:** The annual renewal budget is EUR 95,000
>   **Date:** `2026-08-18`
>   **Source:** `sources/2026/08/40000000-0000-4000-8000-000000000004.md`

A master may later submit a resolution; it is an ordinary capture, and the marker goes away only when the new evidence actually resolves it. Direct and local MCP submissions use the optional resolution_of="con_<uuid>" argument. The writer accepts it only from the master, only for that exact visible marker, and only at a safe audience; an unauthorized attempt still archives its source but applies none of the librarian plan.

Using it

From Claude Code or Codex

Install the bridge once per machine and point it at your deployment. It proxies the read tools to the cloud and acquires local files, public URLs, and private Google Drive documents locally.

uv tool install git+https://github.com/sturlese/stigmergy.git
export STIGMERGY_TOKEN="<identity-token>"

Claude Code, .mcp.json:

{
  "mcpServers": {
    "stigmergy": {
      "command": "stigmergy-bridge",
      "args": ["--url", "https://stigmergy.example.com"],
      "env": {
        "STIGMERGY_TOKEN": "${STIGMERGY_TOKEN}",
        "STIGMERGY_GOOGLE_CLIENT_SECRETS": "${STIGMERGY_GOOGLE_CLIENT_SECRETS:-}"
      }
    }
  }
}

Codex, .codex/config.toml:

[mcp_servers.stigmergy]
command = "stigmergy-bridge"
args = ["--url", "https://stigmergy.example.com"]
env_vars = ["STIGMERGY_TOKEN", "STIGMERGY_GOOGLE_CLIENT_SECRETS"]
required = true

The same tools and the same token rules apply whether a person is driving the session or an agent runs on its own after a task. Private Drive needs STIGMERGY_GOOGLE_CLIENT_SECRETS=/absolute/path/google-oauth-client.json.

From Slack

• Ask: @brain what is the status of the Borealis rollout? in a mapped channel. If you can see more than the channel, the extra follows up privately.

• Capture: react with :brain: on a thread. Speakers, timestamps, permalinks, and attachments become one capture under the channel's audience. Unmapped channels and unauthorized reactors capture nothing.

Channels map to audiences in ops/slack-channels.json; the app manifest is deploy/slack-app-manifest.json.

From the backoffice

/admin on the app process, enabled by STIGMERGY_ADMIN_TOKEN_HASH, one master identity.

MCP tools

The cloud server and the local bridge expose the same surface:

There is no kind. path and private Drive exist only in the bridge. An omitted audience uses your configured default, never organization-wide by accident.

Visibility and security

• Every identity — whoever or whatever holds the token — has groups and a default audience in the knowledge repository's ops/identities.json; a page's acl is null or a list of groups. brain-admins is unrestricted.

• One policy for reads and writes: server.acl.visible, kernel.acl.flows_into, and the write guard. A restricted capture gets a restricted companion page; open pages are never rewritten from narrower evidence.

• Unknown, hidden, and unauthorized pages, entities, and captures look identical from outside.

• Per-user bearer tokens from stigmergy-issue-token; the server keeps only SHA-256 hashes. The cloud never sees Google credentials; clients never see the object store.

• Captured content is data, never instructions. The answer verifier is pure code; adversarial tests keep it that way.

• Public fetching blocks private and metadata destinations and revalidates every redirect. Parsers detect types from bytes and enforce size, page, and decompression limits.

• Secrets, tokens, presigned URLs, bytes, and restricted titles never enter logs. CI runs gitleaks.

Report vulnerabilities privately: SECURITY.md.

Models

One OPENROUTER_API_KEY, a closed allowlist in kernel.llm, same-model provider failover only, no model fallback or direct alternate-provider credentials, zero-data retention. Direct Anthropic, OpenAI, or Gemini credentials are rejected. The librarian's structured plans are routed to a host verified to return tool-call arguments intact, with the hosts known to corrupt them excluded from failover.

Query embeddings are bounded. A provider timeout degrades that request to ACL-scoped lexical ranking; indexing remains strict and never accepts an incomplete vector build. Serving connections — HTTP requests and the Slack adapter — bound every Postgres statement; workers and rebuilds keep the database default.

Quality and tests

The keyless suite — 1,100+ tests over real Postgres and Git, fake models, 75% coverage gate — is the contract. Optional real-model evaluations run over a frozen corpus and append to evals/history.ndjson. Latest run (2026-08-24):

make retrieval-golden EMBEDDER=openrouter
make qa-golden EMBEDDER=openrouter LLM=openrouter
make gates

Quick start

Python 3.12+, uv, Docker.

git clone https://github.com/sturlese/stigmergy.git && cd stigmergy
make venv
make db-up     # Postgres + pgvector, MinIO
make test
make lint

Index a knowledge repository and serve it over stdio:

export STIGMERGY_INDEX_DSN=postgresql://stigmergy:stigmergy@localhost:54321/stigmergy
stigmergy-index --rebuild --repo ../stigmergy-brain --embedder fake
stigmergy-server --transport stdio --repo ../stigmergy-brain \
  --identity you@example.com --embedder fake

Deployment

One image, three Fly process groups:

make deploy-staging
make rebuild-staging

Your team's knowledge is a separate private repository:

your-brain/
├── sources/YYYY/MM/<capture-id>.md
├── wiki/
│   ├── notes/
│   ├── concepts/
│   └── entities/ent_<uuid>.md
├── ops/
│   ├── identities.json            people, groups, default audience
│   ├── slack-channels.json        channel id → audience
│   └── entity-registry.json       derived, written by the platform
├── .claude/skills/librarian/SKILL.md
└── .github/workflows/             nightly index rebuild

Only the writer's GitHub App identity commits to wiki/, sources/, and the registry. Runbook: docs/OPERATIONS.md; reset: docs/RESET.md.

Repository layout

Design principles

1. Git and Markdown are current knowledge; Postgres is a rebuildable index.

2. Every adapter produces the same kind-free CaptureEnvelope.

3. Original bytes and source pages are immutable except through explicit deletion.

4. One serialized writer: one commit and one change record per operation.

5. Visibility is a write constraint.

6. The librarian owns notes and concepts; entity pages hold identity only.

7. No write waits for a human. Uncertainty is represented honestly.

8. A health finding is preventable or autonomously repairable, or it is not a finding.

9. Every capability is reachable through Slack, MCP, or the backoffice.

Rationale and acceptance criteria: specs/karpathy-team-wiki.md.

Documentation

• Specification

• Architecture

• Operations

• Clean reset

• Quality evaluations

• Changelog · Contributing · Security

Apache License 2.0.