SwarmADE
Get started
← All posts

Memory as Your Queen's Brain

Antonio Nusco5 min read

  • memory
  • architecture

Most agent tools have amnesia. You explain your project's conventions, the session ends, and tomorrow you explain them again. The agent re-derives the same context from scratch on every task, paying for the rediscovery in tokens and in your patience.

A Queen that has to re-learn your codebase each morning can't plan well. So SwarmADE gives her a memory: SwarmMemory, a persistent knowledge graph that lives with your repo and that every agent — Queen and Workers — can read and write. This post is about what's in it and why the format is deliberately boring.

Markdown, not a vector blob

SwarmMemory is plain Markdown files with wikilinks. Each file holds one fact. A root MEMORY.md indexes them. That's the whole storage format:

---
name: auth-uses-better-auth
type: reference
---

Auth is handled by **better-auth** (not Passport, not a hand-rolled JWT layer).
Sessions are cookie-based; the API verifies via `requireSession()`.
Related: [[honey-billing-flow]], [[api-v1-conventions]].

The [[honey-billing-flow]] is a wikilink — a typed edge to another memory. The files plus their links form a graph: nodes are facts, edges are "related to."

Why Markdown instead of an opaque vector store? Three reasons, all practical:

  • You can read it. When the Queen plans something wrong, you can open the memory and see exactly what she believed. A vector blob is unauditable.
  • You can edit it. Fix a stale fact by editing a file, the way you'd fix any doc. No re-embedding ritual.
  • It diffs. Memory lives in the repo under .swarmade/, so it versions with your code. A memory written on a branch travels with that branch.

How the Queen uses it

When the Queen plans a spec, she doesn't start from a blank page. She retrieves the memories relevant to the task and folds them into the plan. Ask her to "add a billing endpoint" and the [[honey-billing-flow]] and [[api-v1-conventions]] nodes surface — so the plan already knows your Honey ledger invariants and your /v1 namespacing convention, instead of guessing and getting corrected later.

spec ─▶ Queen retrieves relevant memories ─▶ plan reflects them
          │                                      │
   [[api-v1-conventions]]               "POST /v1/billing/topup,
   [[honey-billing-flow]]                reserve→settle ledger,
   [[stripe-adapter]]                    Stripe via PaymentProvider"

The retrieval is the difference between a generic plan and a plan that fits your repo. Project-specific context that used to live only in your head — or in a chat transcript you closed — is now a durable input the planner reads every time.

Workers tap the same store

Here's the part that makes it more than a planner cache: Workers read and write the same graph. SwarmMemory exposes its operations as MCP (Model Context Protocol) tools, so any MCP-capable agent — your Worker CLIs, the Queen, a Drone — talks to one store through a uniform interface:

search_memory(query)      → the nodes relevant to a task
read_memory(name)         → one fact, with its links
write_memory(name, body)  → record something learned
link_memory(a, b)         → add a typed edge

A Worker that discovers, mid-task, that the migration generator is broken locally can write_memory that fact. The next task — on any Worker, in any session — finds it via search_memory instead of rediscovering the breakage the hard way. The graph compounds: every task can leave the project a little better-documented than it found it.

A worked example

You ask for a new Drone. The Queen plans it. Three things happen with memory:

  1. Retrieve. She pulls [[drone-base-class]] and [[drone-registry]] and plans the task to extend the base class and register the new Drone — matching how the other eight were built, because the memory recorded the pattern.
  2. Execute with shared context. The Worker building it reads [[drone-prompt-conventions]] through the MCP tools, so the system prompt it writes matches house style on the first try.
  3. Write back. When the Drone lands, a [[refactor-safety-drone]] memory is recorded and linked to [[drone-registry]]. The next person — or agent — to touch Drones inherits it.

No step required you to re-explain the Drone architecture. The graph remembered.

So what

Context that evaporates at the end of a session isn't context — it's a tax you pay again every morning. SwarmMemory turns it into an asset: a plain-Markdown graph that travels with your repo, that you can read and correct, and that the Queen and every Worker share through one MCP interface.

An orchestrator is only as good as what it knows about your project. This is where it keeps that.

Give your Queen a memory worth planning from. Start a Hive.