Markdown + wikilinks
SwarmMemory is a local-first knowledge graph. Instead of a database you cannot read, every fact lives in a plain Markdown file on your machine. Files connect to each other with wikilinks, and the whole graph is indexed in a hidden per-repo directory so the Queen and your Workers can query it.
One fact per file
The unit of memory is a single Markdown file capturing one fact, decision, or note. Files are small, focused, and human-editable. You can open any of them in your editor of choice, because there is no proprietary container around them.
To connect two files, reference another note by name in double square brackets, written here as [[the-other-note]]. SwarmMemory resolves the link, tracks it both ways, and keeps the graph navigable.
---
name: queen-orchestration
type: project
description: How the Queen plans a spec into tasks.
tags: [queen, orchestration]
---
The Queen decomposes a spec into tasks and dispatches them to the Swarm.
Each task result is audited before it counts as done — see [[drone-audits]].
Related context lives in [[hive-layout]].The MEMORY.md index
Every repo gets a root index file, MEMORY.md. It is the human-readable table of contents for the graph: the entry point you scan to see what the project knows. New memories are surfaced here so the index stays a faithful map rather than drifting out of date.
The .swarmade directory
A hidden .swarmade/ directory holds the memories plus per-repo configuration. This is where the index that powers fast keyword lookup and link resolution is built. You commit it (or not) per project preference, but the source of truth is always the Markdown files themselves.
Why local-first plain text matters
By default everything stays on your machine. Plain Markdown means your knowledge is portable, diffable, and yours — no lock-in, no required cloud account.
Because each memory is just text:
- Portable — open it anywhere, move it to any tool.
- Diffable — changes show up in
git difflike any other file, so history is auditable. - Yours — nothing leaves the machine unless you opt into sync.
The Queen and Workers read and write this graph through an MCP server. See MCP tools for the full tool surface.