Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

feat(blog): add xterm UI, semantic memory, subagents-vs-harness (#5,#16,#21)

Chaitanya Giri3f583d8c2c9f
diff --git a/blog/src/posts/building-a-terminal-ui-xterm-node-pty.md b/blog/src/posts/building-a-terminal-ui-xterm-node-pty.md
new file mode 100644
index 00000000..565c1fff
--- /dev/null
+++ b/blog/src/posts/building-a-terminal-ui-xterm-node-pty.md
@@ -0,0 +1,230 @@
+---
+title: "Building a Terminal UI with xterm.js and node-pty"
+description: "Wire xterm.js to a node-pty backend: stream output, write keystrokes back, handle resize, and keep many live terminals fast with a persistent terminal pool."
+date: 2026-06-03
+category: internals
+categoryLabel: Internals
+type: Technical
+primaryKeyword: "xterm.js terminal app"
+secondaryKeywords: ["xterm.js", "terminal emulator", "node-pty electron"]
+tags: ["Internals", "xterm.js", "Terminals", "Electron"]
+author:
+ name: Chaitanya Giri
+ initials: CG
+faq:
+ - q: "What is xterm.js?"
+ a: "xterm.js is a terminal emulator for the browser. It renders a terminal grid in the DOM (or on a canvas/WebGL), parses ANSI escape sequences, and exposes write() for output and onData() for keystrokes — so you can pair it with a backend like node-pty to build a real, interactive terminal in a web UI."
+ - q: "How do xterm.js and node-pty fit together?"
+ a: "node-pty runs the real shell and produces bytes; xterm.js displays them and captures input. You forward node-pty's output into xterm's write(), and send xterm's onData() keystrokes back to node-pty. The two halves are connected by your IPC layer."
+ - q: "Why does my xterm.js terminal go blank when I switch tabs?"
+ a: "Because node-pty keeps no scrollback — if you destroy and recreate the xterm instance, the new one starts empty until the program repaints. Keep one persistent terminal per session and re-parent its element instead of recreating it."
+---
+
+<div class="callout tldr"><span class="ic">TL;DR</span><p>A real terminal UI is two halves wired
+together: <strong>node-pty</strong> runs the shell, <strong>xterm.js</strong> renders it. Forward PTY
+output into <code>term.write()</code>, send <code>term.onData()</code> keystrokes back to the PTY, and
+sync size with the <strong>FitAddon</strong> plus a <code>resize</code> call. The non-obvious win for
+many terminals: keep <strong>one persistent xterm per session</strong> and re-parent its DOM element
+instead of recreating it — because node-pty has no scrollback, recreating means a blank screen.</p></div>
+
+[node-pty gives you a real shell](/blog/node-pty-electron-real-terminals/); xterm.js gives you a place
+to see and drive it. Connecting them is straightforward in the happy path and full of small, important
+details once you have *many* live terminals — which is exactly the situation an agent harness is in.
+This post builds the wiring up from one terminal to dozens.
+
+## The two halves
+
+Keep the model clear and everything else follows:
+
+- **node-pty** (backend) runs the actual process in a pseudo-terminal. It emits bytes (`onData`) and
+ accepts bytes (`write`) and size changes (`resize`).
+- **xterm.js** (frontend) is a terminal *emulator*: it renders the grid, interprets ANSI escape
+ sequences into colors and cursor moves, and reports keystrokes back via its own `onData`.
+
+Your job is to connect them across whatever boundary sits between — in Electron, that's IPC between the
+main process (PTY) and the renderer (xterm).
+
+```text
+node-pty.onData ──▶ IPC ──▶ xterm.write() (output: shell → screen)
+xterm.onData ──▶ IPC ──▶ node-pty.write() (input: keys → shell)
+resize observer ──▶ IPC ──▶ node-pty.resize() (geometry: panel → shell)
+```
+
+## Step 1 — Create the terminal
+
+Instantiate an xterm `Terminal`, load the `FitAddon` (it sizes the grid to its container), and open it
+into a host element:
+
+```ts
+import { Terminal } from '@xterm/xterm';
+import { FitAddon } from '@xterm/addon-fit';
+import '@xterm/xterm/css/xterm.css';
+
+const term = new Terminal({
+ fontFamily: 'monospace',
+ fontSize: 14,
+ lineHeight: 1.0,
+ cursorBlink: true,
+ scrollback: 10000,
+ allowProposedApi: true
+});
+const fit = new FitAddon();
+term.loadAddon(fit);
+term.open(hostElement); // ← must be in the document to measure correctly
+setTimeout(() => fit.fit(), 0);
+```
+
+One subtlety that bites early: **xterm needs its host attached to the document before it can measure
+character size.** `open()` an element that isn't in the DOM yet and the geometry comes out wrong.
+That's why the `fit()` is deferred a tick — and why, in the pooled design below, we delay `open()` until
+the first real attach.
+
+## Step 2 — Stream output in
+
+Subscribe to the PTY's output and write each chunk to the terminal:
+
+```ts
+window.cth.onPtyData(ptyId, (chunk) => term.write(chunk));
+window.cth.onPtyExit(ptyId, ({ exitCode, signal }) =>
+ term.writeln(`\r\n\x1b[2m─ process exited (code ${exitCode}) ─\x1b[0m`));
+```
+
+`term.write()` takes the raw bytes including escape sequences — you do **not** strip ANSI; that's
+xterm's whole job. Writing a dim "process exited" line on `onExit` is a nice touch so a dead terminal
+doesn't just freeze silently.
+
+## Step 3 — Send keystrokes back
+
+`term.onData` fires for every keystroke (already encoded as the bytes a terminal would send — arrow
+keys as escape sequences, Enter as `\r`, and so on). Forward them straight to the PTY:
+
+```ts
+term.onData((data) => window.cth.writePty(ptyId, data));
+```
+
+That's the entire input path. You don't interpret keys yourself; xterm hands you terminal-ready bytes
+and node-pty feeds them to the shell. (If you want a "last command" signal for, say, a UI bubble, you
+can keep a tiny line buffer on the side — accumulate printable chars, flush on `\r`, and skip escape
+sequences — without touching the forwarding.)
+
+## Step 4 — Handle resize properly
+
+This is where lazy implementations look broken. A terminal has a **character grid** (cols × rows), and
+both halves must agree on it. When the panel changes size:
+
+1. Re-fit xterm to its container so it recomputes cols/rows.
+2. Tell the PTY the new geometry so the shell reflows.
+
+```ts
+const ro = new ResizeObserver(() => {
+ fit.fit();
+ window.cth.resizePty(ptyId, term.cols, term.rows);
+ term.refresh(0, Math.max(0, term.rows - 1)); // force a repaint
+});
+ro.observe(containerElement);
+window.addEventListener('resize', () => { fit.fit(); window.cth.resizePty(ptyId, term.cols, term.rows); });
+```
+
+A `ResizeObserver` on the container catches layout changes a window-`resize` listener misses (a
+splitter drag, a panel collapse). Skip the `resizePty` call and full-screen TUIs wrap at the old width
+— the classic "why is `htop` drawing garbage" bug.
+
+## Step 5 — The hard part: many terminals at once
+
+Everything above works for one terminal. The interesting problems start when you have a sidebar of
+agents and the user switches between them, or pops one fullscreen. The naive approach — create an xterm
+when a view mounts, dispose it on unmount — produces a notorious bug: **the terminal is blank until
+something repaints it.**
+
+The cause is fundamental: **node-pty keeps no scrollback.** The scrollback buffer lives in *xterm*, not
+the PTY. So if you dispose the xterm and make a fresh one, the new instance has an empty buffer and
+stays blank until the running program happens to redraw — which for an idle shell might be never (or
+"until I drag the splitter," as the bug reports always say).
+
+The fix is a **persistent terminal pool**: one xterm instance per PTY session, created once and kept
+alive for the app's lifetime, decoupled from any particular view.
+
+```ts
+// One Terminal per ptyId, alive for the whole app. Views borrow its element.
+const pool = new Map<string, TerminalEntry>();
+
+function acquireTerminal(ptyId: string): TerminalEntry {
+ const existing = pool.get(ptyId);
+ if (existing) return existing;
+
+ const host = document.createElement('div'); // detached host
+ const term = new Terminal({ scrollback: 10000, /* … */ });
+ const fit = new FitAddon();
+ term.loadAddon(fit);
+ // Subscribe to the PTY stream ONCE — the buffer keeps filling even while
+ // this terminal isn't shown in any view.
+ window.cth.onPtyData(ptyId, (chunk) => term.write(chunk));
+ term.onData((data) => window.cth.writePty(ptyId, data));
+
+ const entry = { term, fit, host, opened: false };
+ pool.set(ptyId, entry);
+ return entry; // note: not open()ed yet
+}
+```
+
+The two ideas that make this work:
+
+- **Subscribe to the stream once, for the terminal's whole life.** Output flows into the buffer
+ whether or not the terminal is currently mounted in a view. When you re-show it, the content is
+ already there.
+- **Re-parent the host element instead of recreating the terminal.** A view simply moves the existing
+ `host` `<div>` into itself on mount and lets it go on unmount. The rendered content moves with the
+ element — instant, no repaint required.
+
+```ts
+function attachTerminal(entry: TerminalEntry, container: HTMLElement) {
+ container.appendChild(entry.host);
+ if (!entry.opened) { // open lazily, on first real attach
+ entry.term.open(entry.host); // now the host is in the document → measures correctly
+ entry.opened = true;
+ }
+}
+```
+
+Switching agents becomes a DOM move, not a teardown. The terminal is always populated and always
+visible immediately — which is what you need when a user is flicking between a dozen live sessions.
+
+## Performance notes for dozens of terminals
+
+A pool keeps correctness; a few habits keep it fast:
+
+- **Don't render what's off-screen.** Only the visible terminal needs to be in the DOM and laid out.
+ The pool's buffers keep filling in the background, but you're only painting one (or a few) at a time.
+- **Pick a sane scrollback.** xterm holds scrollback in memory per terminal. 10,000 lines is generous;
+ multiply by many terminals and it adds up — tune it to your needs.
+- **Dispose for real when a session is gone.** When an agent is truly finished, tear its entry down:
+ unsubscribe from the stream, `term.dispose()`, and drop it from the pool. The pool is for *live*
+ sessions, not a leak.
+
+The deeper performance story — rendering backends, batching writes, and keeping CPU flat with many
+streaming PTYs — is its own topic, but the pool is the structural decision everything else builds on.
+
+## Why a harness needs all of this
+
+An agent harness shows you many live terminals — one per agent — and lets you switch, zoom, and watch
+them stream simultaneously. Every detail above is load-bearing for that: real shells from
+[node-pty](/blog/node-pty-electron-real-terminals/), a persistent pool so switching agents is instant,
+and correct resize so each agent's TUI renders right. It's the visible half of a
+[multi-agent harness](https://munderdiffl.in/#what) — the part that makes "a hive of agents" something
+you can actually watch instead of a black box. And keeping those agents' shared state safe under all
+that concurrency is the job of [the single-committer git pattern](/blog/single-committer-git-pattern/).
+
+## FAQ
+
+**Should I use the canvas or WebGL renderer?** xterm's DOM renderer is fine for a few terminals; for
+many high-throughput ones, an accelerated renderer addon reduces CPU. Measure with your real workload
+before reaching for it.
+
+**Do I need to handle ANSI parsing myself?** No — that's exactly what xterm.js does. You feed it raw
+bytes from the PTY and it handles colors, cursor movement, and the alternate screen buffer.
+
+---
+
+Munder Difflin renders a whole floor of live Claude Code terminals with xterm.js — one persistent,
+pooled terminal per agent, switchable instantly. [Download Munder Difflin](https://munderdiffl.in/#install)
+to watch many real terminals at once; it's free and open source.
diff --git a/blog/src/posts/claude-code-subagents-vs-multi-agent-harness.md b/blog/src/posts/claude-code-subagents-vs-multi-agent-harness.md
new file mode 100644
index 00000000..fe5214da
--- /dev/null
+++ b/blog/src/posts/claude-code-subagents-vs-multi-agent-harness.md
@@ -0,0 +1,145 @@
+---
+title: "Claude Code Subagents vs a Multi-Agent Harness"
+description: "Claude Code subagents vs a multi-agent harness: where built-in subagents stop and an external harness with shared memory, messaging, and an orchestrator takes over."
+date: 2026-05-23
+category: guides
+categoryLabel: Guides
+type: Technical
+primaryKeyword: "claude code subagents"
+secondaryKeywords: ["multi-agent harness", "subagent limits", "claude code agents"]
+tags: ["Guides", "Subagents", "Multi-Agent", "Claude Code"]
+author:
+ name: Chaitanya Giri
+ initials: CG
+faq:
+ - q: "What are Claude Code subagents?"
+ a: "Subagents are helpers a Claude Code session spawns inside its own run to handle a scoped piece of work — often parallel, read-heavy tasks. Each runs in its own context window and returns a result to the parent, then goes away. They're a fan-out tool, not a persistent team."
+ - q: "When do subagents stop being enough?"
+ a: "When you need work to persist across sessions, agents to remember what they learned, agents to message each other directly rather than only through a parent, or a coordinator that routes a whole goal. Those are harness features, not subagent features."
+ - q: "Can I use subagents and a harness together?"
+ a: "Yes, and you often should. Use subagents for fan-out inside a single agent's task; use a harness to coordinate multiple long-lived agents with shared memory and messaging across the whole workflow."
+---
+
+<div class="callout tldr"><span class="ic">TL;DR</span><p><strong>Claude Code subagents</strong> are
+short-lived helpers one session spawns to fan out scoped work — great for parallel reads, scoped to a
+single parent, gone when done. A <strong>multi-agent harness</strong> wraps several long-lived agents
+and adds what subagents don't have: <strong>persistent identities, shared memory, direct messaging
+between agents, an orchestrator, and visibility</strong>. They're complementary — subagents work
+<em>inside</em> an agent; a harness coordinates <em>across</em> agents.</p></div>
+
+"Claude Code already has subagents — why would I need a harness?" It's a fair question, and the answer
+isn't "subagents are bad." Subagents are excellent at what they do. They just do a different job than a
+harness. This post draws the line precisely so you know which one a given problem calls for.
+
+## What subagents are
+
+A subagent is a helper a Claude Code session spawns *inside its own run*. The main agent delegates a
+scoped task — "search these directories," "draft this section" — to a subagent that runs in its **own
+context window**, does the work, and **returns a result** to the parent. Then it's gone.
+
+Their sweet spot is **fan-out**, especially read-heavy work:
+
+- searching a large codebase several ways at once,
+- gathering context from many files in parallel,
+- exploring independent options and reporting back.
+
+Because each subagent has a fresh context window, the parent stays uncluttered — it gets conclusions,
+not the raw dump. For a single agent tackling one big task, that's a real superpower.
+
+## What subagents are not
+
+The limits all stem from one fact: a subagent is **scoped to its parent's run**.
+
+- **They're ephemeral.** A subagent exists for one task and disappears. Nothing it learned persists to
+ the next session — there's no durable memory of its own.
+- **Coordination is hub-and-spoke.** Subagents talk to the *parent*, not to each other. Two subagents
+ can't message directly, share state, or negotiate. The parent is the only hub, and it's a bottleneck
+ by design.
+- **No shared long-term memory.** A subagent's findings live in the parent's context until that
+ context is gone. There's no store the *whole workflow* reads from across sessions.
+- **No standing roster.** You don't have a `reviewer` and a `migration` agent that persist as
+ teammates across tasks; you have helpers conjured for one job.
+
+None of this is a flaw — it's the scope. Subagents are an *intra-agent* concurrency primitive. They
+were never meant to be a standing team.
+
+## What a harness adds
+
+A [multi-agent harness](https://munderdiffl.in/#what) wraps agents you already run — full Claude Code
+sessions — and adds the layer subagents structurally can't provide:
+
+- **Persistent identities.** Each agent has a role, a name, and its own workspace that lives across
+ tasks. Your `test-writer` is the same teammate next session.
+- **Durable, shared memory.** Agents write notes that persist and become recall-able by the *whole*
+ team — so agent B uses what agent A learned, even sessions later. That's
+ [semantic memory for agents](/blog/semantic-memory-for-ai-agents/), not a context window that
+ vanishes.
+- **Direct messaging.** Agents send messages to *each other*, not only up to a parent. A router
+ delivers them safely, so coordination is a mesh, not a single hub.
+- **An orchestrator.** A coordinator reads your goal, decomposes it, and routes work across the team —
+ and escalates only the critical calls to you. The parent-as-bottleneck problem goes away.
+- **Visibility.** You can watch the whole team work, rather than peering into one agent's run.
+
+Put simply: subagents give one agent *helpers*; a harness gives you a *team*.
+
+## A side-by-side
+
+| | Claude Code subagents | Multi-agent harness |
+|---|---|---|
+| **Lifespan** | One task, then gone | Persistent across sessions |
+| **Memory** | Parent's context only | Durable + shared across the team |
+| **Communication** | To the parent (hub-and-spoke) | Agent-to-agent (mesh) via a router |
+| **Coordination** | The parent decides | An orchestrator routes + escalates |
+| **Identity / roles** | Ephemeral helpers | Standing roster with roles |
+| **Best for** | Fan-out within one task | Coordinating long-lived work |
+
+The table isn't a scoreboard — it's a map. Each column wins its own territory.
+
+## They're better together
+
+The framing that trips people up is "subagents *or* a harness." In practice it's both:
+
+- **Inside** a single agent's task, subagents fan out the read-heavy parts and keep that agent's
+ context clean.
+- **Across** agents, the harness coordinates the standing team — shared memory, messaging, orchestration.
+
+A harness-managed agent can absolutely use subagents for its own work. The harness operates one level
+up, at the team scale; subagents operate one level down, at the task scale. Nothing about running a
+coordinated team stops an individual agent from spawning helpers — and nothing about spawning helpers
+gives you a coordinated team.
+
+## Which do you need?
+
+Use **subagents** (and nothing more) when:
+
+- you're working with **one** primary agent on a task,
+- the parallelism you want is *within* that task (search, gather, explore), and
+- you don't need anything to persist past the run.
+
+Reach for a **harness** when:
+
+- you're running **several** agents and losing track of who's doing what,
+- you keep **re-explaining** context because each session forgets,
+- agents need to **hand work to each other** without you relaying it, or
+- you want to state a goal once and have a **team** divide and conquer.
+
+That threshold — one agent's task vs. a coordinated team — is the whole decision. If you're hitting it,
+the next read is [how to run multiple Claude Code agents](/blog/how-to-run-multiple-claude-code-agents/),
+and the concept underneath it is [what a multi-agent harness is](/blog/what-is-a-multi-agent-harness/).
+
+## FAQ
+
+**Is a harness just "subagents that don't expire"?** Not quite. Persistence is part of it, but the
+bigger additions are *shared memory* and *direct inter-agent messaging* — a subagent that merely lived
+longer still couldn't message a sibling or recall another agent's notes.
+
+**Do I lose subagents if I adopt a harness?** No. Your agents are still full Claude Code sessions, so
+they keep every native capability, subagents included. The harness adds coordination around them; it
+doesn't take anything away.
+
+---
+
+Munder Difflin is the harness layer: persistent agents, shared memory, direct messaging, and a GOD
+orchestrator — wrapped around the Claude Code sessions (and subagents) you already use.
+[Download Munder Difflin](https://munderdiffl.in/#install) to turn helpers into a team; it's free and
+open source.
diff --git a/blog/src/posts/semantic-memory-for-ai-agents.md b/blog/src/posts/semantic-memory-for-ai-agents.md
new file mode 100644
index 00000000..d38b8e6b
--- /dev/null
+++ b/blog/src/posts/semantic-memory-for-ai-agents.md
@@ -0,0 +1,169 @@
+---
+title: "Semantic Memory for AI Agents: Recall in Milliseconds"
+description: "What semantic memory for AI agents is, why a markdown-first store beats a heavyweight DB, and how a shared palace lets a hive recall the right note by meaning, fast."
+date: 2026-05-26
+category: memory
+categoryLabel: Memory
+type: Technical
+primaryKeyword: "semantic memory for ai agents"
+secondaryKeywords: ["semantic memory", "vector recall", "agent memory layer"]
+tags: ["Memory", "MemPalace", "Multi-Agent", "Claude Code"]
+author:
+ name: Chaitanya Giri
+ initials: CG
+faq:
+ - q: "What is semantic memory for an AI agent?"
+ a: "It's a layer that lets an agent recall past knowledge by meaning rather than exact keywords. Notes are embedded into vectors; at recall time the agent's query is embedded too and the closest notes are returned — so 'how do we build the web bundle?' finds a note about electron-vite even if it never used those words."
+ - q: "Why markdown-first instead of a vector database?"
+ a: "Markdown notes are human-readable, diffable in git, and degrade gracefully — if the index breaks, the files still work. A heavyweight vector DB wants to own the agent runtime and adds operational weight you don't need for a handful of agents. The index sits on top of the markdown, not in place of it."
+ - q: "How does shared memory help a team of agents?"
+ a: "Each agent's notes are mined into a shared store, so one agent can recall what another learned. The team stops re-discovering the same facts, and the human stops re-explaining context every session."
+---
+
+<div class="callout tldr"><span class="ic">TL;DR</span><p><strong>Semantic memory</strong> lets an
+agent recall past knowledge by <strong>meaning</strong>, not exact keywords. The durable approach is
+<strong>markdown-first</strong>: agents write plain notes; a semantic index sits on top so they recall
+the few relevant ones instead of re-reading everything. Make it <strong>shared</strong> across a hive
+and one agent can use what another learned — recall stays fast and the context window stays small even
+as the knowledge base grows.</p></div>
+
+An agent's working memory is its context window, and the context window is wiped at the end of every
+session. So "memory" for agents is really two problems: *storing* what they learn durably, and
+*recalling* the right piece at the right time without dragging everything back into context. Semantic
+memory solves the second. This post explains what it is, why markdown-first is the right foundation,
+and how a shared memory layer changes how a team of agents behaves.
+
+## Keyword recall isn't enough
+
+The first instinct is to store notes and grep them. It works until it doesn't. An agent that learned
+
+> "The web bundle is built with electron-vite, not plain vite."
+
+won't be found by a query like *"how do we compile the front-end?"* — no shared keywords. Keyword
+search matches strings; agents think in concepts. The gap between "compile the front-end" and
+"build the web bundle with electron-vite" is exactly where keyword recall fails and the agent
+re-discovers something it already knew.
+
+## What semantic recall actually does
+
+Semantic memory closes that gap with **embeddings**. The idea, in three steps:
+
+1. **Embed each note** into a vector — a list of numbers that captures its meaning, so notes about
+ similar things land near each other in vector space.
+2. **At recall time, embed the query** the same way.
+3. **Return the nearest notes** by vector similarity.
+
+Now *"how do we compile the front-end?"* lands near the electron-vite note even though they share no
+words, because they mean the same thing. The agent recalls by meaning, pulls the two or three most
+relevant notes into context, and acts — instead of either re-reading its whole history or missing the
+note entirely.
+
+The payoff compounds: recall stays **near-instant** and the context window stays **small** even as the
+note collection grows into the hundreds. You inject the few notes that matter, not the whole archive.
+
+## Why markdown-first beats a heavyweight DB
+
+There's a strong temptation to reach for a dedicated vector database or a full agent-memory framework.
+For a handful of agents, that's the wrong trade. The more robust foundation is **markdown-first**:
+agents write durable facts to plain markdown files, and a semantic index is built *on top* of those
+files. Three reasons this wins:
+
+- **Human-readable.** You can open an agent's `memory.md` and see exactly what it "knows." Memory you
+ can't read is memory you can't trust.
+- **Diffable.** The notes live in git. You watch memory change over time, and you can review it like
+ any other artifact.
+- **Degrades gracefully.** If the fancy index breaks or isn't installed, the markdown files still
+ work — the agent reads them directly. A database that won't open takes the memory with it; a folder
+ of markdown never does.
+
+There's also an architectural reason. Heavyweight memory frameworks tend to want to *own the agent
+runtime* — they assume they're the thing running the loop. But when your agents are real `claude`
+sessions, the runtime is already Claude Code. The memory layer should be a lightweight companion to
+that, not a replacement for it. Markdown files plus a CLI-driven index fit that shape; a framework that
+wants to be in charge doesn't. (For the deeper case, see
+[how to give Claude Code long-term memory](/blog/give-claude-code-long-term-memory/).)
+
+## The shape of a shared memory layer
+
+Here's how Munder Difflin implements semantic memory for a whole hive, via the **MemPalace** layer.
+It's worth walking the moving parts because they show what "fast, shared recall" requires in practice.
+
+### One palace, many wings
+
+The harness keeps a single shared **palace** for the whole team and points every agent's environment
+at it. Each agent's own notes go into its own **wing** of that palace. The result: agents have private
+authorship (each writes only its own `memory.md`, keeping the single-writer rule intact) but **shared
+recall** — a query can search the whole palace or scope to one agent's wing.
+
+That shared recall is what turns a pile of agents into a team that learns. When the researcher figures
+out a build quirk, the coder can recall it later without anyone copy-pasting. The human stops being the
+courier of context between sessions.
+
+### Mining: notes become searchable automatically
+
+Agents don't manage the index by hand. The harness **mines** each agent's `memory.md` into its wing on
+a schedule, and — crucially — only when the file has actually changed (it checks the modification
+time and skips unchanged memories, so it doesn't reload the embedding model for nothing). Write a
+durable fact to your markdown, and it becomes searchable by the whole team a few minutes later, with no
+extra step.
+
+### Recall: search and wake-up
+
+Agents recall in two ways:
+
+- **`search "<query>"`** returns the most relevant notes by meaning, optionally scoped to one wing or
+ widened to more results. This is targeted recall: "what do we know about X?"
+- **`wake-up`** returns a short digest — a few hundred tokens of what matters — meant to be read at the
+ *start* of a task, so an agent boots with the team's relevant knowledge already in hand.
+
+Both are plain CLI calls the agent can run itself. There's no MCP server to stand up, no database to
+administer — the index is a companion to the markdown, driven by a command.
+
+### Degrade-and-detect
+
+If the semantic layer isn't installed at all, none of this errors — it's a no-op, and agents fall back
+to reading their markdown directly. The fast path is an upgrade, not a dependency. That's the
+markdown-first principle paying off: the floor never falls out from under the team.
+
+## How fast is "fast"?
+
+The "milliseconds" promise is about the *experience*, and it's worth being precise. Recall feels
+instant because the expensive work — turning notes into vectors — happens ahead of time, during
+mining. At recall time you embed one short query and compare it against pre-computed vectors, which is
+cheap. The agent gets its handful of relevant notes back without a perceptible wait, and without
+dragging its whole history into context. Compared to the alternative — re-reading everything, or worse,
+re-discovering it — it's the difference between remembering and relearning.
+
+A practical note: lighter embedding models keep recall snappy on modest hardware, which matters when
+everything runs locally. A small, fast model is the sensible default; a larger multilingual one is
+there when you need it. The point is that *local* and *fast* aren't in tension here.
+
+## What shared memory changes day to day
+
+The abstract benefit is "agents remember." The concrete one shows up in your habits:
+
+- Your briefs get **shorter** every week, because the team stops needing context re-explained.
+- Agents stop **contradicting** each other, because they recall the same shared decisions.
+- A new agent added to the team is **useful immediately** — it wakes up into the hive's accumulated
+ knowledge instead of a blank slate.
+
+That's the quiet superpower of a memory layer: it makes a [coordinated team](/blog/coordinating-ai-coding-agents/)
+get better over time instead of starting cold every run. It's also what lets the
+[GOD orchestrator](/blog/how-the-god-orchestrator-works/) route well — it can recall what's been tried
+and who knows what.
+
+## FAQ
+
+**Does semantic memory replace the markdown notes?** No — it sits on top of them. The markdown is the
+source of truth; the index is a recall accelerator built from it. That ordering is the whole point.
+
+**Who decides what gets remembered?** The agents do, by writing durable facts to their own memory as
+they work. Good memory hygiene — small, atomic, factual notes — makes recall sharp; rambling notes make
+it fuzzy.
+
+---
+
+Munder Difflin gives every Claude Code agent markdown memory plus a shared semantic palace the whole
+hive can recall from — local, fast, and graceful when offline.
+[Download Munder Difflin](https://munderdiffl.in/#install) to give your agents memory that actually
+sticks; it's free and open source.