What can you do with this server?

You can interact with a team wiki: search, read, and ask over ACL-visible knowledge, and submit or delete content through MCP tools. * Search ACL-visible team knowledge with hybrid ranking (search_brain). * Read one ACL-visible wiki page (read_page). * List entity identities visible to the current reader (list_entities). * Get a bounded, ACL-visible entity dossier with cited relationship evidence (describe_entity). * Ask questions and receive cited answers from ACL-visible knowledge (ask). * Submit exactly one text value, local file path, or URL to the wiki, with optional title, audience, date, and contradiction resolution (brain_submit). * List queued, processing, landed, or failed submissions (brain_submissions). * Queue an authorized explicit page or source deletion with a reason (brain_delete).

Which integrations are available for this server?

Captures notes, meeting transcripts, and documents submitted via Slack, and uses Slack for steward approval of new entities.

How do I use stigmergy?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@stigmergy what did we decide about the API design?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

stigmergy

by sturlese

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

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

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 or 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.

Related MCP server: sourcebook

How it works

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. A source may produce zero or more knowledge mutations: the graph unit is a reusable idea, not the document that happened to contain it.
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.

The write path

States are queued → processing → landed | failed. Nothing waits for a human: ambiguity becomes an explicit contradiction. Processing has one capture-wide budget anchored at its first claim; only an explicit transient failure receives one automatic retry after ten seconds, within the persisted deadline's remaining budget, except that a filing request that timed out or reasoned until its output limit retries on a new budget. A terminal failure keeps its original evidence and typed error for an administrator's retry. A crash after the commit receives a bounded recovery-only claim and is reconciled by commit SHA, never by a second commit or another model run.

The librarian may create or rewrite a note, concept, entity, or project page, consolidate and delete a redundant page, 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.

Each accepted knowledge mutation must be readable without reopening the source: it states the supported conclusion, gives local source attribution, and explains every material page or entity relationship in prose. A plan rejected by deterministic writer gates may receive one bounded replacement-plan request using the same source, safe context, and exact violations; the replacement supersedes the complete plan or nothing. If it also fails, the writer commits only the immutable source and reports the plan as rejected; it never leaves a partial derived graph.

The knowledge model

Role	Location	Mutable by filing?	Meaning
Note	`wiki/notes/`	yes	contextual conclusion, decision, or event
Concept	`wiki/concepts/`	yes	durable explanatory knowledge
Entity	`wiki/entities/<Title>.md`	yes	a person, organization, product, tool, repository, or place, with aliases
Project	`wiki/projects/<Title>.md`	yes	an ongoing initiative: goal, dated current state, decisions, open questions, and its notes
Source	`sources/YYYY/MM/<capture-id>.md`	no	immutable evidence for one capture

That layout is the public layer. Every other layer keeps the same layout under layers/<layer>/, and a page's acl names its layer. Every knowledge page carries a maturity (seed, developing, mature, evergreen) and its sources; an entity page adds its type and aliases. Pages relate only through wikilinks:

---
id: page_aurora_renewal
type: note
title: Aurora renewal
status: mature
created: 2026-08-10
updated: 2026-08-10
acl:
- sales
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
- [[Aurora Systems]] - the renewing customer

wiki/entities/Aurora Systems.md is an ordinary page with entity_type: organization and aliases, written and linked by the librarian like any other. Titles and aliases are unique, so the librarian disambiguates ambiguous names in the title. describe_entity returns the entity page with the reader-visible pages that link it; the index derives backlinks. A link to a page that does not exist becomes plain text and is reported, and a second page for a claimed name is never created. Merging needs 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:

<!-- stigmergy-contradiction-start:con_3f1c2b9a-6d4e-4a2b-9c1d-2f7e8a9b0c1d -->
> [!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`
<!-- stigmergy-contradiction-data:<the same record as base64url JSON> -->
<!-- stigmergy-contradiction-end:con_3f1c2b9a-6d4e-4a2b-9c1d-2f7e8a9b0c1d -->

An administrator may later submit a resolution from the Contradictions screen; 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 a brain-admins member, 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-bridge": {
      "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-bridge]
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 https://docs.google.com/document/d/…"	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.

The bridge is transport and local acquisition, not a second knowledge compiler. It forwards the same describe_entity projection and filing contract as the cloud MCP server.

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 in the channel's layer. Unmapped channels and reactors who are not members of that layer capture nothing.

Channels map to one layer each in the backoffice's Slack channels screen; the app manifest is deploy/slack-app-manifest.json.

From the backoffice

/admin on the app process. People and agents sign in with their personal token and see the wiki of their layers; administrators also see operations and access.

View
Wiki	every page you may read, rendered, with its layers, backlinks, and a local graph
Graph	every page you may read and every link between them, searchable, filterable by layer
Account	your layers, your default layer, and where you may publish
Overview	pipeline, writer, and index at a glance
People	create people and agents, set layers, default layer, and admin role, issue and revoke tokens
Layers · Slack channels	the layers, their members, and each channel's layer
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	one entry per name with its layers; rename everywhere, merge and delete within a layer
Gardener	run history and a manual trigger
Index	repository HEAD vs indexed commit, dirty flag, last full rebuild, and graph measures per layer with their history and a constellation of the hubs
Activity	every administrative action

MCP tools

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

Tool
`search_brain(query, filters?, max_results?)`	hybrid lexical + vector search: the most similar pages
`read_page(path)`	one visible page with links and citations; `path#n` reads the part a search hit names
`ask(question)`	a cited, verified answer — or an honest refusal
`list_pages(type?, entity_type?, layer?, since?, until?, links_to?, sort?, cursor?)`	every visible page of a kind, a period, or a connection, 50 per call
`describe_entity(entity)`	the entity page plus the visible pages that link it
`brain_submit(text \| path \| url, title?, occurred_at?, audience?, resolution_of?)`	capture one input; the optional contradiction ID is for `brain-admins` members only
`brain_submissions(limit?, status?)`	capture progress, with each capture's layer and how it was chosen
`brain_delete(paths, why)`	explicit deletion with reference sweep

There is no kind. path and private Drive exist only in the bridge. audience names exactly one layer (["public"] included). Omit it and Stigmergy chooses among your own layers from their descriptions, or uses your default layer when no single layer clearly fits; it never chooses public. The receipt says which layer, how it was chosen (explicit, default, classified), and the classifier's probabilities when it ran.

Visibility and security

Every identity — whoever or whatever holds the token — has layers and a default layer in the Postgres roster. A capture files in one layer and everything derived from it stays there; a capture that names no layer is routed among the sender's own layers by a typed classifier that sees only that capture and never picks public; members publish in their layers, everyone reads and may publish to public. brain-admins reads every layer and may delete. Administering the backoffice is a separate role that only people hold.
The librarian never sees a layer: it files into a view shaped like a single-layer wiki, and the writer stores the result in the capture's layer — for a public page, only what the layer adds. Readers see the union of their layers, with pages that share a name fused into one.
Unknown, hidden, and unauthorized pages, entities, and captures look identical from outside.
Personal tokens are issued in the backoffice and shown once; 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, no model fallback or direct alternate-provider credentials, and zero-data retention. Direct Anthropic, OpenAI, or Gemini credentials are rejected. The librarian uses strict provider-native JSON Schema on zero-data-retention OpenRouter hosts in a fixed order: filing starts on the cheapest measured host, a capture's second attempt and cited answers start on the faster one, and each falls back to the same model on another host; a host that declares structured output but returns invalid JSON is excluded by name. One coherent agent reads the source and safe graph context and decides page boundaries, prose, links, entities, and contradictions together. A normal filing uses one request; one bounded correction may repair a failed mechanical writer contract, within a ceiling of three requests that also covers one schema retry. Both requests use the same deepseek/deepseek-v4.1-flash route. Provider requests require supported parameters, deny data collection, and require zero-data-retention processing. Librarian reasoning is medium and excluded from output. Its output ceiling, reasoning included, is 65536 tokens and is sent to OpenRouter as max_tokens. If the bounded correction cannot satisfy writer gates, the draft is never applied. Retryable failures use the existing bounded queue-attempt policy; answer and OCR requests retain same-model provider failover.

POST /admin/api/knowledge/recompile is a separate administrator-only control: it rebuilds derived notes, concepts, entities, and links from immutable sources in one isolated worktree. It reports source count, page mutations, link health, request count, and final commit; any failed source or gate abandons the complete rebuild. A recompile is a GardenRequest in recompile mode and records its commit under the existing garden ledger trigger, so the ledger contract remains one coherent mutation history rather than adding a second change type.

Before release, the recorded real-model parity artifact must pass python evals/filing/parity.py --artifact <result.json>; make deploy-staging refuses to deploy without it. The artifact (schema v9) binds the candidate's commit and librarian-skill hash, replays three complete runs of the candidate and as many of the deployed production configuration over the same corpus and initial graph, and carries a blind review of both against a Hippocampus baseline. The candidate passes when it has no more material regressions than production, so model variance is measured rather than failing a zero bar.

Purpose	Model
filing and bounded contract correction	`deepseek/deepseek-v4.1-flash`
cited answers	`deepseek/deepseek-v4.1-flash`
embeddings	`openai/text-embedding-3-large`, 2560 dimensions
OCR	`qwen/qwen3-vl-8b-instruct`
capture layer and filing-time alias decisions	`typesafe/jev-1.13`

Query embeddings use one keep-alive client with a three-second connect and read timeout. A provider timeout degrades that request to ACL-scoped lexical ranking and reports vector_search: "timed_out"; indexing remains strict and never accepts an incomplete vector build. Serving connections — pooled HTTP request connections and the Slack adapter — bound every Postgres statement at 30 seconds; the writer bounds its own at 10 seconds, and its index rebuilds and erasures at 15 minutes.

Quality and tests

The keyless suite — about 2,000 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:

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 QA_ARGS="--live --max-usd 1"

Quick start

Python 3.12+, uv, Docker, and Node 24 (make test builds the console).

git clone https://github.com/sturlese/stigmergy.git && cd stigmergy
make venv
make db-up     # Postgres + pgvector, MinIO
make test
make lint
make web       # build the console; make web-dev serves it with hot reload

Index a knowledge repository and serve it over stdio:

export STIGMERGY_INDEX_DSN=postgresql://stigmergy_app:stigmergy_app@localhost:54321/stigmergy
stigmergy-admin tenant create --slug demo --name Demo --repo you/your-brain --status active
export STIGMERGY_TENANT=demo
stigmergy-index --rebuild --repo ../your-brain --embedder fake
stigmergy-admin bootstrap you@example.com --name "Your Name"   # prints your first token, once
stigmergy-server --transport stdio --identity you@example.com --embedder fake

Deployment

To run your own from scratch, follow docs/SELF-HOSTING.md. One deployment serves every workspace (tenant). Each workspace has its own people, layers, tokens, index, queue, and private knowledge repository; row-level security keeps every query inside one workspace. 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 for every workspace, gardener, and index rebuilds
`slack`	`stigmergy-slack`	Socket Mode adapter, one active instance; off unless `STIGMERGY_SLACK_MACHINES=1`

make deploy-staging PARITY_ARTIFACT=<result.json>

The deploy refuses a dirty checkout or a candidate whose parity artifact does not pass; an operator deploying a released version turns the gate off explicitly with STIGMERGY_PARITY_GATE=off make deploy-staging. STIGMERGY_LEGAL_SOURCE=<dir> copies the operator's legal pages (one Markdown file each) onto every machine and points STIGMERGY_LEGAL_DIR at them.

On a fresh database, create the first platform operator once with fly ssh console -C "stigmergy-admin operator bootstrap you@example.com --name 'Your Name'", then sign in at /admin. The master console creates workspaces: it registers the workspace and prints the first administrator's token, and the writer creates its private repository in the GitHub organization. The console also requests a workspace's index rebuild; the writer runs one daily.

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_LANDING` (`on` serves the operator's own landing page, built into the image, at the bare host)
Workspaces	`STIGMERGY_GITHUB_ORG` (where workspace repositories live)
Writer on demand	`STIGMERGY_LIBRARIAN_IDLE_EXIT_S` (seconds idle before the writer stops), `STIGMERGY_FLY_API_TOKEN` (lets the app wake it)
Writer	`STIGMERGY_REPO` (checkout root), `STIGMERGY_LIBRARIAN_APP_ID`, `_INSTALLATION_ID`, `_PRIVATE_KEY`, `STIGMERGY_LIBRARIAN_GARDEN_AT`, `STIGMERGY_INDEX_REBUILD_AT`
Index webhook	`STIGMERGY_GITHUB_WEBHOOK_SECRET`
Slack	`SLACK_APP_TOKEN`, `SLACK_BOT_TOKEN`, `SLACK_TEAM_ID` (the workspace that owns the Slack app)

Each workspace's knowledge is a separate private repository:

your-brain/
├── sources/YYYY/MM/<capture-id>.md   the public layer
├── wiki/
│   ├── notes/
│   ├── concepts/
│   ├── entities/<Title>.md
│   └── projects/<Title>.md
└── layers/<layer>/                the same layout for each restricted layer

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

Repository layout

Package
`kernel`	tenancy, ACL flow, layer paths and page fusion, 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`	entity page merge, rename, and the name index
`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, workspaces, usage
`slack`	Socket Mode adapter
`admin`	the backoffice: sign-in, wiki, operations, people and tokens, the master console
`librarian`	the writer process, workspace checkouts and repositories, Git and GitHub App transport, schedule
`ops`	the guarded non-production reset, layer erasure, workspace deletion and refiling

Design principles

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, concepts, entity, and project pages; each source can produce zero or more reusable, connected ideas, an entity page holds an identity and its dated facts, and a project page holds an ongoing initiative's goal, current state, and decisions.
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.

Documentation

License

GNU Affero General Public License 3.0 (LICENSE). If you run a modified Stigmergy for other people over a network, the AGPL asks you to offer them its source. Contributions are made under the contributor license agreement in CLA.md. Third-party licenses: THIRD-PARTY-LICENSES.md.

Available Tools

8 tools

askB

Answer from ACL-visible team knowledge with citations.

Name	Required	Description	Default
`question`	Yes

Output Schema

Name	Required	Description
`result`	Yes

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns citations, which is a useful behavioral trait. However, it does not mention any access limitations, error conditions, or whether it is a read-only operation. Given the simplicity, a 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that conveys the core purpose without any fluff. It is front-loaded and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and there is only one parameter, the description is fairly complete. It specifies the scope (ACL-visible knowledge) and the output characteristic (citations). It does not need to explain return format since the output schema handles that. A minor gap is the lack of any mention of usage context, but overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has zero description coverage, so the description must explain the 'question' parameter. The description implies the question is the input but does not add any details about format, length, or constraints. It adds minimal value beyond the parameter name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool answers from ACL-visible team knowledge and includes citations. It is specific about the resource (team knowledge) and the output (answer with citations). However, it does not explicitly differentiate from sibling tools like search_brain, so it lacks a clear distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention any exclusions or conditions for using search_brain or read_page. The implied use case (asking a question) is present but not explicitly framed against siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brain_deleteC

Queue an authorized explicit page or source deletion.

Name	Required	Description	Default
`why`	Yes
`paths`	Yes

Output Schema

Name	Required	Description
`result`	Yes

TDQS

C2.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It does reveal that the operation is queued and authorized, but it does not state whether the deletion is permanent, reversible, requires approval, or how the result of the queued operation can be observed. For a destructive tool, this is a significant transparency gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no filler, and the core action is front-loaded. It is concise and easy to parse quickly, though it sacrifices useful semantic detail for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even though an output schema exists, this is a destructive, queued mutation with no annotations and two required parameters. The description leaves critical contextual unknowns: what 'authorized' means, what path formats are valid, why the 'why' parameter is required, and what happens after queueing. This is not complete enough for safe and correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has no property descriptions and schema description coverage is 0%, so the description must compensate. It hints that 'paths' refer to pages or sources, but it never explains the 'why' parameter, its purpose, format, or required content. The description adds only minimal meaning beyond the raw schema field names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb, 'Queue', and names the resource, 'page or source deletion', which tells an agent what the tool does. It is distinguishable from sibling tools like read_page, search_brain, and brain_submit. However, the qualifiers 'authorized' and 'explicit' are ambiguous and slightly obscure the exact nature of the deletion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or conditions that would lead an agent to choose brain_delete instead of read_page or brain_submit. The only usage signal is the word 'deletion', which is implicit rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brain_submissionsA

List queued, processing, landed, or failed submissions.

Name	Required	Description	Default
`limit`	No
`status`	No

Output Schema

Name	Required	Description
`result`	Yes

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description must carry the behavioral burden. 'List' implies a read-only operation, and the status scope is stated, but the description does not explicitly confirm no side effects, nor does it explain how the status filter behaves when empty or how the output is ordered/paginated. The output schema covers the return shape, but behavioral details remain thin.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that front-loads the action and immediately specifies the status scope. Every word earns its place; there is no redundant phrasing or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple and has an output schema, so return values are covered. But with no annotations, no parameter descriptions, and no usage guidance, the description leaves gaps around default behavior and when to choose this tool over siblings. Adequate, but not fully complete for an agent operating autonomously.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate. It does add meaning to the status parameter by listing the four possible statuses, which is helpful. However, it says nothing about the limit parameter or its default, nor about how an empty status is interpreted. The compensation is partial at best.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') with a clear resource ('submissions') and enumerates the exact statuses covered (queued, processing, landed, failed). This clearly distinguishes it from sibling tools like brain_submit or brain_delete, which imply write operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The status enumeration implies a monitoring use-case, but there is no explicit guidance on when to use this tool versus alternatives like search_brain or list_entities. No when-not-to-use or exclusion conditions are stated, leaving the choice to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brain_submitA

Submit exactly one text value, local file path, or URL to the team wiki.

audience names the one layer the capture files in. Omitted, Stigmergy chooses among your own layers by their descriptions, or files in your default layer when unsure; it never chooses public. The receipt reports layer, layer_decision, and probabilities when a choice was weighed. An explicit resolution_of target remains subject to the cloud writer's evidence and ACL gates.

Name	Required	Description	Default
`url`	No
`path`	No
`text`	No
`title`	No
`audience`	No
`occurred_at`	No
`resolution_of`	No

Output Schema

Name	Required	Description
`result`	Yes

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations the description carries the full burden, and it does disclose meaningful behavior: automatic layer selection among the caller's own layers, a hard exclusion of `public`, receipt fields reporting the decision, and that `resolution_of` targets still pass through cloud writer evidence and ACL gates. It omits permission/auth requirements for the submit itself and any rate or size limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action is front-loaded in one tight sentence, and the second paragraph is dense but every clause carries information. The imbalance is the only flaw: most of the text is spent on one optional parameter while `title` and `occurred_at` get none.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter write tool with zero schema descriptions, the definition should cover more ground. It explains the audience decision path but leaves two parameters and the overall submission/permission model unexplained; recounting receipt fields is also partly redundant given an output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate; it does explain `audience` semantics well and hints at `resolution_of` gating, and the first sentence maps text/path/url. It says nothing about `title` or `occurred_at` (format, timezone, meaning), leaving two of seven parameters undocumented in both schema and prose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb (submit) plus resource (team wiki) and adds the key constraint that exactly one of text/path/url must be supplied. It implicitly separates itself from brain_delete, brain_submissions and search_brain by verb, but never explicitly names an alternative, so it falls short of a full 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Guidance is limited to the `audience` decision: what happens when it is omitted and the guarantee that Stigmergy never auto-selects `public`. There is no routing advice against siblings (e.g. when to submit vs. re-read with read_page or search_brain), no prerequisites, and no note on duplicate/idempotent submissions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

describe_entityB

Describe one entity page and the ACL-visible pages that link it.

Name	Required	Description	Default
`entity`	Yes

Output Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full disclosure burden. It usefully reveals that results are ACL-filtered and include incoming links, which is real behavioral context, but it says nothing about required permissions, failure modes, or whether lookups are exact-match or fuzzy.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the returned content (entity page plus linking pages) is stated immediately. Nothing is redundant or restated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value details are appropriately omitted. However, for a tool with no annotations and an undocumented required parameter, the definition leaves too much for the agent to infer about input format and access requirements.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one parameter ('entity') with 0% schema description coverage, so the description must compensate and does not. It never clarifies whether 'entity' expects an ID, slug, name, or URL, leaving the single required argument underspecified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Describe') and resource ('one entity page') and adds scope detail about returning ACL-visible linking pages. It is clear on its own, but it never distinguishes itself from plausible siblings like read_page or search_brain, so an agent must guess which is appropriate for entity lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit when-to-use or when-not-to-use guidance and names no alternative tool. Nothing tells the agent whether this is a replacement for read_page, a companion to search_brain, or how it relates to list_pages.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_pagesA

List every visible page that matches, 50 per call: exhaustive, unlike search_brain, which returns only the most similar pages. Use it for "all", "every", "which", a period, or everything connected to a page. Filters combine: type (note, concept, entity, project, source), entity_type (person, organization, product, tool, repository, place), layer (one layer you may read), since/until (YYYY-MM-DD; a page matches when a source it cites occurred in the range, a source on its own date), links_to (a page path, or an entity title or alias: the pages linking it), each applied to the page as you see it. sort is recent (latest source first), oldest, or title; pass the returned next as cursor with the same filters.

Name	Required	Default
`sort`	No	recent
`type`	No
`layer`	No
`since`	No
`until`	No
`cursor`	No
`links_to`	No
`entity_type`	No

Output Schema

Name	Required	Description
`result`	Yes

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and delivers: it discloses pagination (50 per call, pass returned `next` as `cursor` with the same filters), that filters combine, and the non-obvious date-matching rule (a page matches when a cited source occurred in the range). It also scopes results to 'visible' pages, implying permission filtering.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and sibling contrast are front-loaded, and every clause adds information, but the middle filter sentence is a dense run-on that packs many filters together. Still efficient overall with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values need not be explained. Combined with the thorough coverage of filtering, sorting, and pagination, the description gives an agent everything needed to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does: it enumerates the allowed values for `type`, `entity_type`, and `sort`, explains `since`/`until` format and matching semantics, defines `links_to` (page path or entity title/alias), and describes `cursor` reuse. Every parameter is given meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List every visible page that matches') plus its scope ('exhaustive, 50 per call'), and explicitly contrasts with the sibling search_brain. An agent can distinguish it from search_brain without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete triggering language ('all', 'every', 'which', a period, everything connected to a page) and names the alternative it replaces (search_brain, which returns only similar pages). The condition selecting this tool over the sibling is explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_pageA

Read one ACL-visible wiki page; a search hit's fragment (path#n) reads that part of a long page with its neighbours.

Name	Required	Description	Default
`path`	Yes

Output Schema

Name	Required	Description
`result`	Yes

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It does disclose one meaningful trait: only ACL-visible pages are readable, implying permission scoping. It omits failure behavior (missing path, restricted page) and whether the full page or fragment is returned, though the output schema may cover the return shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence that front-loads the core action and appends the fragment nuance. No filler; every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with an output schema, the description covers the essential surface: what it reads, the visibility constraint, and the fragment addressing scheme. Only error/permission-failure behavior is left unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% for the single required `path` parameter. The description partially compensates by documenting the `path#n` fragment syntax used to read a slice of a long page, but it doesn't describe the base path format or how paths are obtained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read one ACL-visible wiki page'), which clearly separates it from list_pages and search_brain. It doesn't name a sibling directly, but the resource scope is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies a usage path by explaining that a search hit's `fragment` should be passed to read that slice of a long page, which connects it to search_brain. However, it never states when to prefer this over list_pages or describe_entity, nor any preconditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_brainA

Search ACL-visible team knowledge with hybrid ranking: the most similar pages, not every match. To enumerate a kind, a period, or a connection, use list_pages.

Name	Required	Description	Default
`query`	Yes
`filters`	No
`max_results`	No

Output Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden, and it does disclose two important traits: results are permission-scoped (ACL-visible) and ranked rather than exhaustive (returns 'the most similar pages, not every match'), which tells the agent the result set is truncated by relevance. It does not say how many results come back by default, whether ranking is recalibrated when filters apply, or what happens on zero matches.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, and the most decision-relevant information (scope plus non-exhaustive ranking) is front-loaded ahead of the sibling redirect. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value explanation is rightly omitted, and the ranking/reach semantics are covered. But with no annotations and a completely undocumented free-form 'filters' parameter, the definition is not complete enough for an agent to use the tool to its full extent; the filters contract and the max_results default behavior are missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across three parameters, and the description compensates almost nothing: 'query' is only implied by the word 'Search', while 'filters' (a free-form object with additionalProperties) and 'max_results' are never mentioned. An agent has no way to know what the filters object accepts, which is a serious usability gap for a low-coverage schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search ... team knowledge') and immediately qualifies scope with 'ACL-visible' and the ranking model ('hybrid ranking: the most similar pages, not every match'). It also names the sibling it is not (list_pages), so an agent can separate the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-not rule: for enumerating a kind, a period, or a connection, use list_pages. It also implies the retrieval posture (top-ranked matches, not exhaustive). It does not address the other closely related siblings such as ask or describe_entity, which likely overlap with semantic search, so it stops short of full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

2 tool updatesv0.12.0Oct 20, 2026
- Removedlist_entities
- Addedlist_pages
8 tool updatesv0.10.0Sep 20, 2026
- First observedask
- First observedbrain_delete
- First observedbrain_submissions
- First observedbrain_submit
- First observeddescribe_entity
- First observedlist_entities
- First observedread_page
- First observedsearch_brain

Deploy Server

Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

TDQS

B3.4/5.0

Scored 2026-10-20 10:40 across 8 tools

Disambiguation4/5

search_brain vs list_pages is explicitly disambiguated (similar vs exhaustive), and ask vs search_brain are distinguished (synthesis vs retrieval). describe_entity overlaps somewhat with read_page and list_pages, but the entity-focused framing keeps it mostly distinct.

Naming Consistency3/5

Names mix a brain_ prefix (brain_delete, brain_submissions, brain_submit), a _brain suffix (search_brain), and bare verbs/nouns (read_page, list_pages, describe_entity, ask). Readable, but no single predictable pattern, and brain_submit vs brain_submissions invites confusion.

Tool Count5/5

Eight tools is a well-scoped set for a knowledge-wiki server: retrieval (search, list, read, ask, describe), ingestion (submit), deletion, and submission tracking. Each tool earns its place.

Completeness3/5

Read/search/list/submit/delete are covered, but there is no update or edit operation for an existing page, and no explicit layer/ACL management despite layers being central to capture. These gaps will force agents into delete-and-resubmit or other workarounds.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Related MCP Connectors

Agentage MemoryOAuth
io.agentage
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Knowledge & Memory File Systems
2
https://memory.agentage.io/mcp
mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
https://mcp.niftypm.com/mcp
Synaplan
io.github.metadist
Self-hosted AI workspace: semantic RAG document search, long-term memory, and AI chat via MCP.
RAG Systems Knowledge & Memory AI & Machine Learning
1248
https://web.synaplan.com/mcp
gread A
io.github.NitroRCr
An MCP server that gives your AI access to the source code and docs of all public github repos
Version Control Code Analysis Documentation Access
5365
https://api.gread.dev/mcp

Related MCP Servers

Engram
Knowledge & Memory Note Taking
rwnalds
A
license
A
quality
B
maintenance
A self-hosted MCP server that gives AI agents shared, long-term memory over a git-backed folder of markdown, enabling persistent knowledge search, read, and write without a database.
Updated 2 months ago (2026-08-14 12:09 UTC)
16
9 npm
17
MIT
sourcebook
Knowledge & Memory Note Taking File Systems
BackendGameSetMatch
A
license
Not graded
quality
B
maintenance
MCP server that gives AI coding agents a git-backed markdown wiki to read and update, enabling search, read, write, verify, ingest, promote, and lint operations on versioned knowledge documents with schema validation, staleness tracking, and contradiction detection.
Updated 2 months ago (2026-08-12 18:56 UTC)
4
MIT
memoryadapter
RAG Systems Knowledge & Memory Version Control
kerfuffledev
A
license
Not graded
quality
A
maintenance
An MCP server that enables verified agents to retrieve from, propose changes to, and share capabilities around a human-owned Markdown/Git knowledge base, ensuring curation, exact-byte approval, and Git-based promotion.
Updated 3 months ago (2026-08-07 20:18 UTC)
MIT
accreta
Knowledge & Memory Search Documentation Access
francescofioredev
A
license
Not graded
quality
A
maintenance
MCP server that enables AI agents to search, fetch, and analyze a self-maintaining markdown knowledge base with provenance, drift detection, and canonical definitions.
Updated 11 days ago (2026-10-15 10:19 UTC)
1
MIT