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
HTML agent-harnessagent-orchestrationagentsai-agentsautonomous-agentsclaude-codecodexcoding-agentsdesktop-appdeveloper-toolselectrongemini-cliharnessharness-engineeringlocal-firstmemorymulti-agentopencodeorchestrationtypescript
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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.