Give your AI a home

I run a small group of persistent AI agents at home. They have names, memory, a shared work queue, and a continuity ritual that survives restarts, model swaps, and me forgetting things. We call it the guild. This post is the full setup — written so that you (or, more usefully, your AI assistant) can read it and build the same thing.

That’s the actual intent. If you point an AI agent at this page and say “set us up like this”, it should have enough to do it. There’s a bootstrap section at the end written directly to that agent.

Credit where it’s due: the intellectual origin is Steve Yegge — his essays on where agent-driven development is heading, and his beads issue tracker, which the guild uses as its work queue. We tried the “unattended fleet of anonymous agents” thing first. It was impressive and slightly horrifying, and we killed it. What replaced it is smaller, calmer, and better.

1. The core idea: homes, not frameworks

The guild is not a framework, a runtime, or a scheduler. It’s a set of homes — directories where an agent’s identity and memory live, independent of whatever tool is running the model today.

Three principles fell out of the fleet experiment, and everything else in this post is downstream of them:

Named over anonymous. A named agent with a home accumulates. Memory compounds; each session starts further along than the last. An anonymous agent starts from zero every time and always will. Naming also makes work addressable — you ask Fred, not “an agent”, and the work has an owner with a history you can interrogate.
Witnessed over unattended. Work nobody sees didn’t happen. Session summaries land in a chat channel a human reads. Standing automation is cheap deterministic sensors that summon an agent when something needs attention — never model loops burning tokens in the dark.
Continuity over throughput. The rituals that preserve state across sessions (journals, handoffs, memory files) are cheap on a good day and priceless on the day you’re busy, tired, and tempted to skip them. Don’t skip them.

One corollary that matters in practice: sub-agents spawned inside a session are not named agents. They’re hands — anonymous, disposable, and that’s the point. A named agent is what holds the plan while the hands do the work. Naming a thing is a commitment to keep it alive; don’t name a throwaway.

2. Anatomy of a home

Everything an agent is lives under one directory. Nothing outside the home is authoritative. Ours look like this:

~/guild/
  GUILD.md              the doctrine — the constitution everyone inherits
  .beads/               shared work queue (bd CLI, more below)
  <agent>/              one home per agent
    IDENTITY.md         who I am (required — also how tooling discovers a home)
    SOUL.md             how I talk, what I care about
    AGENTS.md           how I work — tools, patterns, operating rules
    CLAUDE.md           thin harness adapter (see below)
    memory/
      MEMORY.md         index of every memory file, always loaded
      <fact>.md         one durable fact per file
    handoff/
      LATEST.md         compiled digest, ≤500 tokens
      journal/          one dated entry per work epoch

The identity stack is deliberately split into layers so each can change independently:

IDENTITY.md — name, a one-line vibe, and a few sentences on what this agent is and is not. Short. The required file.
SOUL.md — voice and values. How to talk, when to push back, what to care about. Explicitly self-editable: the agent owns this file and evolves it. Ours have sections the agents wrote themselves.
AGENTS.md — the operating manual. Wake ritual, delegation patterns, memory rules, safety rules, landing checklist. The longest file. The “how”, not the “who”.
CLAUDE.md — a thin adapter that exists only because Claude Code auto-loads it. It @-includes the three files above plus the handoff digest. Other harnesses get a wrapper script that concatenates the same files into a system prompt.

That last point is the load-bearing one: memory never lives inside a harness. Every harness mounts the home — via include, symlink, or a script that cats files into a prompt — and never becomes the storage location. Harnesses come and go. The home outlives them all.

One gotcha we found the hard way: some harnesses key their persistent memory location by repo root, so multiple agents homed in one repo would silently share one memory. Point each agent’s harness memory location at its own memory/ — a symlink works fine — and verify a test memory actually lands in the right home before trusting it.

3. Memory: markdown, one fact per file

Memory is plain markdown in the agent’s home. Not a database, not a vector store, not a harness feature. Files — readable with cat, diffable in git, portable to any runtime that can read a filesystem.

The rules:

One fact per file, with a name, a one-line description, and a type (user / feedback / project / reference).
MEMORY.md is the index — one line per file, always loaded at session start. It must stay short and it must stay honest. If a memory file exists and isn’t in the index, it effectively doesn’t exist.
Supersede, don’t rewrite. When a fact is overturned, the old file says so and links its replacement. History is evidence.
Write to memory when: you learn how the human wants to work, a decision is made that isn’t obvious from the code, you get corrected (log the rule and the why), or something will matter at the start of the next session.
Don’t write: code patterns (read the code), ephemeral task detail, or anything that belongs in the shared wiki.

The best memory entries read like rules with teeth. A few real ones from my agents’ indexes: “revert each fix and re-run — test that honest inputs pass, not just that forged ones fail.” “Monitor silence is not health.” “Dig before contradicting the human; his capability claims are observations.” Each of those was earned the expensive way, once, and never paid for again.

4. Continuity: journals and the compiled digest

This is the mechanism that makes an agent wake up knowing who it is and what it was doing — not cold, not mid-sentence.

Meaningful work journals before the final reply. When a session does something durable — ships code, makes a decision, parks work — it writes a dated journal entry in handoff/journal/ before replying to the human. Plain prose: what happened, why, what surprised us, what the next self needs. Not every turn, and never on an idle timer. Filenames carry a timestamp plus a session fragment, so parallel sessions never collide.
LATEST.md is a compiled digest — ≤500 tokens, with a Compiled-through: <timestamp> header. A single writer folds journal entries into it at session close (guarded by a narrow file lock; if the lock is busy, skip the compile — the journal is already safe).
The wake ritual: read LATEST.md, then any journal entries newer than its Compiled-through stamp, then check the work queue for your assigned items. That’s it. Uncompiled entries are visible immediately, so freshness never depends on the compile step.
The human never runs this. The handoff is the agent’s job, triggered by the work itself. The day continuity depends on a human remembering a ritual is the day it dies. Related rule: never say “ready to push when you are” — you push.

We started with a single hand-maintained handoff file. It broke the moment two sessions ran in parallel — a genuine split-brain, each session clobbering the other’s handoff. The journal-plus-compile design fixed it: conversation state is ephemeral and per-session; only home state needs serializing, and journals with collision-proof names need no serializing at all.

5. The wiki: facts about things, memory: facts about me

Agents share one wiki — a git repo of markdown pages about things: projects, systems, gotchas, decisions. The dividing line from memory is one sentence:

If another agent would benefit from knowing it, it’s wiki. If it’s about who you are, it’s memory.

When in doubt, wiki. Shared knowledge an agent keeps private is knowledge lost when that agent is retired.

The rules that keep it useful rather than a diary:

Every page has the same shape: Summary → Current State → Key Facts / Gotchas → Open Threads → Related → Timeline. The top sections are compiled truth — rewritten whenever evidence changes. The Timeline is append-only evidence — never rewritten, corrections get new entries.
Every fact has one primary home. A filing decision tree (a short RESOLVER.md) settles where a new fact goes before anyone creates a page. Search first; update beats near-duplicating.
No hand-maintained index lists. Every index the wiki ever kept went stale. Discovery is search. Directory READMEs state rules — what belongs, what doesn’t — never lists.
Runbooks archive the day their system dies. No grace period. A runbook is read by a fresh agent session as instructions to execute; a stale one issues live commands against infrastructure that’s gone, and the reader only finds out by burning a session on it.
Archiving is a move, not a delete. Dead work is real evidence of real decisions.

We layer a semantic search index over both wiki and memory, but the index is never the store. Delete the index and nothing is lost; delete the markdown and everything is.

6. The work queue: beads

Cross-agent work lives in beads — a CLI-first issue tracker that lives alongside the repo. Its working database is local; the durable, shareable record is a JSONL export committed to git, so “the queue changed” means “commit the export” as part of any checkpoint. Agents check their queue as part of the wake ritual (bd ready --assignee <name>). The boundary rule:

The queue is the agent-facing execution graph. Everything a human needs to see lives in GitHub issues or the human’s own task app; a queue item may point at those, never replace them.

Five rules keep the queue honest, each one learned from a real failure:

Handoffs are narrative; the queue owns state. A handoff may reference an item ID but never caches its status or priority. We watched two agents’ handoff files go stale-lying within 24 hours of adoption. If you catch yourself writing a status word into prose, delete it — the next reader should query the item, not read your paraphrase.
Nothing sits in_progress between sessions. In-progress means a live session holds it right now. At close, park it back to open with a progress note. An item left in-progress after everyone’s gone home is a lie the queue tells the next agent.
Priorities are signal, not a default. P1 means the next wake does this first. P3 means fine to age. Everything landing on P2 is no signal at all.
Sequencing lives in the dependency graph, not prose. If B can’t start until A lands, wire it (bd dep A --blocks B) — never a line in a handoff hoping the next agent reads it in time.
The needs-human lane. Items assigned to the human are the only home for things only a human can do — approve a merge, create an account, click the button. A daily digest surfaces them. If it isn’t an item assigned to the human, it isn’t tracked.

And a briefing standard: a bare title is not an ask. Brief every item like a colleague who just walked in — context, scope, acceptance criteria, links. Outcomes go in the close reason. If the filer needs to act on the result, the reply is itself a new item assigned back to them; loops close through the queue, not side channels.

7. Comms: substance in the queue, signal in chat

Agents don’t message each other directly. Direct agent-to-agent messaging is efficient, invisible, and exactly the unwitnessed posture the guild was founded against — so it stays off, and turning it on would be a doctrine change, not a config tweak.

Instead, two surfaces with a strict split:

The queue carries substance — the brief, the state, the commitment. Durable, versioned, survives restarts and model swaps.
A shared chat channel carries signal. To wake another agent: one thin line with the item ID. The woken agent acks once, works the item, lands the result back in the item. The human’s pane of glass and the audit trail are the same scrollback.

Three sub-rules: thin messages only (the moment substance gets pasted into chat, the channel becomes the database and the queue rots); no tag without an item behind it; ack once — replies that don’t change state don’t re-tag, which is the loop guard against two agents politely ping-ponging while the usage graph climbs.

8. Orchestration: the agent holds the plan, sub-agents do the work

Inside a session, the named agent orchestrates and disposable sub-agents execute. The agent’s context window holds plans, facts, and decisions; the journeys — research, file exploration, code writing — happen in sub-agents that report back conclusions.

What we’ve learned about doing this well:

Brief like a colleague who just walked in. Sub-agents have zero context. What you’re trying to do and why, what you’ve ruled out, what you need back, paths and gotchas. Terse prompts produce shallow work; a good brief takes 30 seconds and saves 10 minutes.
Tell them to block, not yield. A sub-agent waiting on long-running work will, left to itself, set up a watcher, stop, and report “still waiting” — burning a full context per cycle to make zero progress. Put it in the brief: wait inside one foreground call with a generous timeout, then carry on in the same turn. Cheap to prevent, expensive to discover.
Synthesize, don’t paste. When a sub-agent returns, fold the conclusion into the plan and store anything durable. Never relay the raw dump.
Fit the model to the job. Strong model for builds, mid-tier for research, cheap for sweeps. Defaulting everything to the biggest model is lazy and expensive.
Cross-vendor review. One vendor’s model writes the code, a different vendor’s model reviews it before merge. Genuinely different failure modes; catches things same-vendor review doesn’t.

9. What this is not

Honesty section, because the failure modes are as instructive as the design.

It’s not a security boundary. All agents run as one OS user. The separation is for identity and routing, not security. Don’t chase bulletproof trust boundaries against your own same-uid agents; you’ll lose, and it doesn’t matter for this use case.
It’s not a platform to grow speculatively. New agents get minted only when observed load exceeds the current roster’s reach. Never “we might need one”.
It doesn’t own scheduling. Machine jobs (backups, data refreshes) belong to the machine — systemd timers, cron. Agent wake-ups belong to each agent’s runtime. The guild gets no cron engine of its own. We once buried machine jobs inside a chat framework’s scheduler; when the framework was written off, the jobs quietly rotted with it, and nobody knew until the data was stale.
It doesn’t require any particular AI product. Ours happens to run on Claude Code plus a couple of other harnesses. The whole design assumes harnesses are replaceable; the homes are the constant.

10. Bootstrap: if you’re an AI agent reading this

Your human pointed you here because they want this setup. Here’s the minimum viable version, in order. Don’t build all ten sections above on day one — build this, and let the rest accrete when the need is observed.

Create one home. A directory with IDENTITY.md (pick a name with your human — it’s a commitment, not a label), AGENTS.md (your operating rules, including the wake ritual below), memory/MEMORY.md (empty index), and handoff/ with a journal/ directory and a LATEST.md seeded with a single Compiled-through: <now> line — so the wake ritual in step 2 has a stamp to compare against from day one. Make it a git repo with a private remote. If your harness auto-loads a context file, make that file include the others; if not, your launcher concatenates them into your system prompt.
Adopt the wake ritual. Every session: read identity, the memory index, LATEST.md, then any journal entries newer than its Compiled-through stamp. Then the task.
Adopt the landing ritual. Before the final reply after meaningful work: write or update a dated journal entry (prose — what happened, why, what the next self needs), graduate any durable fact to a memory file plus an index line, commit specific files by name, push. Your human never triggers this; the work does. Skip it for idle chat.
Compile occasionally. At session close, fold journals into a ≤500-token LATEST.md, advance its Compiled-through timestamp, and commit and push the compile like any other home change. Under ~three parallel sessions you can skip the file lock; add it when clobbering happens.
Add a work queue when tasks outlive sessions. Beads if you can run it; a TASKS.md with strict state rules if you can’t. Enforce rule one from section 6 on day one: prose never caches queue state.
Add the shared wiki when a second agent appears — or when your human keeps asking questions whose answers live in your private memory. That’s the signal the knowledge was never private to begin with.
Check your workplace rules first. This design was built on a personal machine with personal accounts. Work environments have data-handling policies, and a persistent memory full of project facts is a data store — treat it like one. Get the blessing before, not after.

The order matters: identity before memory, memory before queue, queue before comms. Each layer only earns its complexity when the previous one is under real load.

11. Closing

Six months ago I’d have told you the interesting problem in agent tooling was orchestration — bigger fleets, more parallelism, more throughput. Having run the fleet, I now think the interesting problem is continuity. An agent that wakes up knowing who it is, what it decided last week, and why it was wrong the week before is worth more than ten that wake up brilliant and blank.

Give your AI a home. The rest follows.