Show HN: Stigmergy, a Karpathy-style LLM wiki for a team, not one person

Stigmergy, a team-oriented LLM wiki inspired by Andrej Karpathy's single-user wiki, uses a librarian agent to maintain a Git-and-Markdown knowledge base from immutable source captures via Slack, Claude Code, and MCP tools, with visibility scoping and full audit trails. The open-source project, built on Postgres and Git, targets organizations needing shared, evidence-backed documentation without human approval workflows.

Stigmergy is the team version of the wiki in Karpathy's gist https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f . 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 why How it works how-it-works The write path the-write-path The knowledge model the-knowledge-model Using it using-it · Claude Code / Codex from-claude-code-or-codex · Slack from-slack · Backoffice from-the-backoffice · MCP tools mcp-tools Visibility and security visibility-and-security Models models Quality and tests quality-and-tests Quick start quick-start Deployment deployment Repository layout repository-layout Design principles design-principles Documentation documentation 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. Capture where the work happens | Agents through the MCP bridge, people through a :brain: reaction in Slack, the master through the backoffice. | Evidence you can trust | Exact bytes in a private store; one immutable source page per capture. | A librarian that files | Creates, rewrites, consolidates, and deletes pages without approval. | Answers with receipts | Hybrid search and ask with citations verified by code. | Visibility on writes too | Restricted evidence never shapes a page a broader audience can read. | Honest contradictions | Conflicting claims stay explicit, dated, and cited. | Self-healing corpus | A scheduled gardener repairs through the same gates. No human to-do list. | Full audit | One operation, one commit, one change record with the exact patch. | Capture. Thin adapters authenticate and acquire bytes. Local files and private Google Drive documents stay on your machine until uploaded through a presigned URL. Queue. Every adapter produces the same kind-free CaptureEnvelope . The Postgres queue is durable, leased, and idempotent per actor and client key. 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. Remember. The knowledge repository is plain Git and Markdown. Postgres is operational state and a rebuildable index, never a second wiki. Read. Five MCP tools for agents, @brain for people, one visibility policy. A webhook indexes incrementally; a nightly full rebuild guarantees convergence. 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. | Role | Location | Mutable by filing? | Meaning | |---|---|---|---| | Note | wiki/notes/ | yes | contextual conclusion, decision, or event | | Concept | wiki/concepts/ | yes | durable explanatory knowledge | | Entity identity | wiki/entities/ent <uuid .md | entity primitives only | opaque ID and scoped name claims | | Source | sources/YYYY/MM/<capture-id .md | no | immutable evidence for one capture | 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. 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 | You say | What happens | |---|---| "Save the conclusions to the brain." | brain submit text=… with a self-contained synthesis. | "File ~/Downloads/board-deck.pdf." | The bridge uploads the bytes; the worker extracts, OCRs scanned pages, files. | "Capture | Local Google OAuth, token in your keychain, DOCX export uploaded. | "What did we decide about the Aurora renewal?" | ask retrieves within your visibility and answers with verified citations. | 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 . 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 /sturlese/stigmergy/blob/main/deploy/slack-app-manifest.json . /admin on the app process, enabled by STIGMERGY ADMIN TOKEN HASH , one master identity. | View | | |---|---| | Captures | paste, upload, public URL; provenance, extraction, retries, commit, change | | Changes | plain-language summary, per-path diff, exact Git patch on demand | | Contradictions | live list from current Markdown, resolution form | | Entities | scoped claims and provenance, evidence-backed merge and delete | | Gardener | run history and a manual trigger | | Index health | repository HEAD vs indexed commit, dirty flag, last full rebuild | The cloud server and the local bridge expose the same surface: | Tool | | |---|---| search brain query, filters?, max results? | hybrid lexical + vector search | read page path | one visible page with links and citations | ask question | a cited, verified answer — or an honest refusal | list entities | identities with a name you may see | describe entity entity | knowledge composed from visible pages | brain submit text | path | url, title?, occurred at?, audience? | capture one input | brain submissions limit?, status? | capture progress | brain delete paths, why | explicit deletion with reference sweep | 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. - 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 /sturlese/stigmergy/blob/main/SECURITY.md . One OPENROUTER API KEY , a closed allowlist in kernel.llm , no provider fallback, zero-data retention. Direct Anthropic, OpenAI, or Gemini credentials are rejected. | Purpose | Model | |---|---| | filing and semantic repair | deepseek/deepseek-v4-flash | | cited answers | z-ai/glm-5.2 | | embeddings | qwen/qwen3-embedding-8b , 2560 dimensions | | OCR | qwen/qwen3-vl-8b-instruct | 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 /sturlese/stigmergy/blob/main/evals/history.ndjson . Latest run 2026-08-24 : | Measure | Result | Bar | |---|---|---| | Retrieval Recall@5 15 questions, 9 ACL-filtered | 1.00 | ≥ 0.80 | | Answer honesty | 1.00 | ≥ 0.90 | | Answer groundedness | 1.00 | ≥ 0.84 | | False-premise refutation | 1.00 | — | make retrieval-golden EMBEDDER=openrouter make qa-golden EMBEDDER=openrouter LLM=openrouter make gates Python 3.12+, uv https://docs.astral.sh/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 One image, three Fly process groups: | Process | Command | Role | |---|---|---| app | stigmergy-server --transport http | MCP over HTTP, uploads, index webhook, backoffice | worker | stigmergy-librarian-boot | the only writer and the scheduled gardener | slack | stigmergy-slack | Socket Mode adapter, one active instance | make deploy-staging make rebuild-staging | Area | Variables | |---|---| | Models | OPENROUTER API KEY , STIGMERGY LIBRARIAN MODEL , ANSWER MODEL , STIGMERGY OCR MODEL | | Database | STIGMERGY INDEX DSN | | Evidence store | STIGMERGY EVIDENCE ENDPOINT , BUCKET , ACCESS KEY ID , SECRET ACCESS KEY | | Server | STIGMERGY PUBLIC HOST , STIGMERGY TOKEN STORE or STIGMERGY TOKEN STORE FILE | | Backoffice | STIGMERGY ADMIN TOKEN HASH , STIGMERGY ADMIN ACTOR | | Writer | STIGMERGY REPO , STIGMERGY LIBRARIAN REPO URL , STIGMERGY LIBRARIAN APP ID , INSTALLATION ID , PRIVATE KEY , STIGMERGY LIBRARIAN GARDEN AT | | Index webhook | STIGMERGY GITHUB WEBHOOK SECRET , STIGMERGY GITHUB REPO , STIGMERGY GITHUB BRANCH | | Slack | SLACK APP TOKEN , SLACK BOT TOKEN , SLACK TEAM ID | 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 /sturlese/stigmergy/blob/main/docs/OPERATIONS.md ; reset: . /sturlese/stigmergy/blob/main/docs/RESET.md docs/RESET.md | Package | | |---|---| kernel | ACL flow, deadlines, the model boundary, normalization | capture | envelopes, evidence, uploads, extraction and OCR, queue, sources | bridge | the local stdio MCP client | knowledge | page contracts, FilingPlan , writer, linter, repair, contradictions, write guard | entities | opaque identities, claims, registry, merge, rename, delete | changes | exact patches and the change ledger | index | corpus selection, ranking, incremental updates, full rebuild, health | server · answer | MCP tools, HTTP transport, webhook, verified answers | slack | Socket Mode adapter | admin | the master backoffice | librarian | the writer process, bootstrap, Git and GitHub App transport, schedule | ops | the guarded non-production reset | - Git and Markdown are current knowledge; Postgres is a rebuildable index. - Every adapter produces the same kind-free CaptureEnvelope . - Original bytes and source pages are immutable except through explicit deletion. - One serialized writer: one commit and one change record per operation. - Visibility is a write constraint. - The librarian owns notes and concepts; entity pages hold identity only. - No write waits for a human. Uncertainty is represented honestly. - A health finding is preventable or autonomously repairable, or it is not a finding. - Every capability is reachable through Slack, MCP, or the backoffice. Rationale and acceptance criteria: specs/karpathy-team-wiki.md /sturlese/stigmergy/blob/main/specs/karpathy-team-wiki.md . Specification /sturlese/stigmergy/blob/main/specs/karpathy-team-wiki.md Architecture /sturlese/stigmergy/blob/main/docs/ARCHITECTURE.md Operations /sturlese/stigmergy/blob/main/docs/OPERATIONS.md Clean reset /sturlese/stigmergy/blob/main/docs/RESET.md Quality evaluations /sturlese/stigmergy/blob/main/evals/README.md Changelog /sturlese/stigmergy/blob/main/CHANGELOG.md · Contributing /sturlese/stigmergy/blob/main/CONTRIBUTING.md · Security /sturlese/stigmergy/blob/main/SECURITY.md Apache License 2.0.