Follow-up to I run 9 parallel Claude Code sessions — the bottleneck wasn't the model, it was memory.
That post described the problem. This one is about the fix I shipped, and the
uncomfortable thing it taught me about "instructing" a model.
I build and run our products — a Swiss job platform, a handful of sites, the
infrastructure under them — with a cockpit that keeps ~9 Claude Code sessions
alive in parallel. Each session is a task: a kanban card you drag, and it
becomes a working agent.
The recurring failure was never intelligence. It was amnesia. Session #7 would
happily reimplement an error format we'd standardized weeks ago, because nothing
told it that decision existed. The decision was written down — in a markdown
note, in the project memory — but the session never looked.
My first fix was the obvious one. When a session spawns, append an instruction
to its first prompt:
{the task}
Start by calling the memory_search tool to load any relevant project context,
then propose a plan — don't execute anything without my go-ahead.
This is what most "give your agent memory" setups do: a system prompt, a tool,
and trust that the model uses them. And it mostly works. Mostly.
Here's the thing about "mostly" when you have nine of them running. One session
in nine ignoring the instruction isn't a 1-in-9 annoyance — it's a silent,
guaranteed defect generator. The model doesn't announce "I skipped the memory
this time." It just dives into the code, does something locally reasonable, and
violates a convention you'd forgotten you even needed to defend. You find out at
review, or worse, after merge.
I spent a while trying to make the instruction stickier — stronger wording,
putting it last, tool descriptions that begged. That's when it clicked: I was trying to make a non-deterministic thing reliable by asking harder. Wrong
The recall doesn't belong in the prompt. It belongs in the plumbing.
Now, when a session spawns, the server runs the semantic search — before the
model gets a single turn — and injects the results directly into the session's
first message:
def _memory_preseed(query: str, top_k: int = 5) -> str:
hits = memory_search(query, top_k=top_k) # server-side, deterministic
if not hits:
return "" # empty memory → fall back to the ritual
lines = ["=== Project memory (auto-recalled) ==="]
for h in hits:
star = "★ " if h.get("priority") else ""
lines.append(f"- {star}[{h['note_name']}] {h['description']} — {h['snippet']}")
return "\n".join(lines)
The task the model receives now looks like:
Fix the healthcheck flapping on staging.
=== Project memory (auto-recalled) ===
- ★ [staging-stack] Staging API is on port 6443, deploys land on host "callisto"
- [deploy-ritual] Deploys go exclusively through `make ship-v2`, never raw rsync
The notes above were auto-recalled from project memory for this task. Call
memory_get on any note you need in full… then propose a plan and wait for my go.
The model can't not have the context now. It's not a tool it might call. It's
in the first tokens it reads.
Crucially, the old ritual is still there — as a fallback. If the memory is
empty (fresh project) or the embedding backend is down, the injected block is
empty and the prompt reverts to "please go search." Determinism where it
matters, graceful degradation where it doesn't.
Claims about memory systems are cheap. So the release has an end-to-end test
that seeds a throwaway instance with two notes containing facts that exist
nowhere in the code: the staging port is 6443, deploys go to a host called
callisto, via make ship-v2. The workspace README is deliberately wrong
about all three.
Then it spawns a session asking: "what port does staging run on, which host do we deploy to, and with what command?"
A session that reads the code (or the lying README) fails. A session with
working recall answers 6443 / callisto / make ship-v2 — and, in the transcript,
literally says it answered "without needing to search the codebase." That's
the whole product in one assertion: the fact reached the model because the
server put it there, not because the model went looking.
description: that doubles as the
embedding text, optional priority: high.[[wikilinks]] are indexedmemory_links tool, and the cockpit draws it with type filters and connected
clusters.
This isn't an autopilot orchestrator. There's no "let the swarm run overnight."
Every irreversible action waits for a human click — the helm, not the autopilot. The point of the memory work isn't to remove me from the loop; it's
When you need a model to do something every single time, don't put it in the
prompt and hope. Move it to a layer that doesn't have opinions. Prompts are for
judgment. Plumbing is for guarantees. I keep having to relearn which is which.