This post is my best guess at the design. Public docs cover the surface: mounts, access modes, optimistic concurrency. The internals are inferred. The framing is the point; specific implementation claims may be wrong.

Why files

Files are the right primitive because models have got better at managing them. From Anthropic's own framing: "Claude Code can accomplish complex tasks across domains using local code execution and filesystems." Lance Martin also added that: files are shareable and interpretable in ways embeddings are not.

There's also the challenge to get RAG right: selecting an embedding model, tuning chunk sizes, versioning the index. As model capability grows, file-based memory is the high-ROI choice. The agent does the curation, after all, why waste the model's ability?

How the agent sees memory

When you attach a memory store to a session, it mounts at /mnt/memory/<store-name>/ and a short note about the mount goes into the system prompt. That's how an agent becomes aware of which stores are available. The agent doesn't need a special tool. read_file and grep work because the mount is represented as a directory.

The docs recommend keeping files under 100KB and splitting context across many focused files instead of one big one. grep finds the right file. read_file pulls only what's needed. Context stays lean.

Safety

Read-only mounts are the answer to prompt injection on shared memory. From the docs: "if the agent processes untrusted input ... a successful prompt injection could write malicious content into the store. Later sessions then read that content as trusted memory." Access mode is set at session creation, enforced at runtime.

Every change generates a new version of the store. The audit trail is built in. You don't add it later.

My guess at the design

Data model. Two levels: a memory store, which is the workspace-scoped unit, and individual memories (files) inside it. Versioning sits at the store level for snapshots, but linearizability is at the file level.

Write consistency. The docs phrase it as "safe content edits (optimistic concurrency)". That reminds me of CAS. Same pattern S3 ships for multi-writer apps: each write carries the expected version; if the version moved, the write fails and the agent retries. This effectively prevents lost writes.

Read consistency. Eventual. My guess: the store mounts lazily into the sandbox. First read on a file pulls bytes; subsequent reads serve from a local cache so grep stays fast. The cache invalidates on local writes. For other sessions' writes you'd need explicit polling or invalidation. The trade-off: cross-session writes aren't visible until the cache refreshes.

In my opinion that's fine. A memory entry going stale for a couple minutes should not materially change answer quality. Linearizability matters at write time. Reads can be looser.

Version log. Written once, read rarely. Append-only fits. Blobs live in S3, with log entries carrying version_id, parent_version_id, blob_hash, operation. S3 keys by content hash, supporting memory_versions.list would be inefficient if relying on S3 alone. So it makes sense to introduce a Dynamo DB to store secondary index, which is derived from the S3 blobs, makes looksup by store_id or memory_id fast.

Specifically, for DynamoDB, a partition key on store_id matches the access pattern: list memories by store, fast.

Multi-region. The most plausible path: S3 cross-region replication fires a notification on blob arrival, an event handler in the secondary region reads the blob and writes the local secondary index. Same shape as primary, just driven by replication events.

It's not. (Seriously, if I'm wrong about this, tell me.)

I dug around in the .claude folder. No allowlist, no routing table, no config for routing rules. The entire communication boundary is prompt instruction.

That intrigued me. So I mimicked one from scratch: a minimal 4-agent team using the Claude Agent SDK. One lead, two debaters, one judge, filesystem mailboxes. ~320 lines of Python. The debaters argue, submit final positions to the judge (not the lead), and the judge sends a verdict. The chain of command exists only in the prompts.

Here's what I found.

Agents talk through files on disk

The key routing constraint: debaters submit to the judge, not the lead. Going over the judge undermines the process.

No API. No message broker. Agents write JSON to each other's inbox files:

output/
├── config.json              # who's on the team
├── inboxes/
│   ├── lead.json            # messages TO the lead
│   ├── teammate-for.json
│   ├── teammate-against.json
│   └── judge.json
└── tasks/
    └── 1.json               # the debate task

When teammate-for wants to message teammate-against, it appends JSON to teammate-against.json in the inbox. That's it. Architecturally, it's a Slack workspace. Anyone CAN message anyone.

Here's what it looks like right after spawning. All four inboxes empty, 9 sub-tasks already created by the teammates, everyone starting concurrently:

Routing by prompt alone

The send_message tool has no routing logic:

@tool("send_message", "Send a message to any agent by name",
      {"recipient": str, "text": str, "summary": str, "message_type": str})
async def send_message(args):
    # No allowlist. Any agent can message anyone. Routing is prompt-only.
    msg = {"from": owner, "to": args["recipient"], ...}
    path = INBOXES / f"{args['recipient']}.json"
    msgs = json.loads(path.read_text())
    msgs.append(msg)
    path.write_text(json.dumps(msgs, indent=2))

No validation on recipient. A debater told to submit to the judge can just as easily message the lead directly. The routing I want exists only in the prompts:

# This is MY mental model. send_message has zero awareness of it.
allowed = {
    "lead":             {"teammate-for", "teammate-against", "judge"},
    "teammate-for":     {"teammate-against", "judge"},  # NOT lead
    "teammate-against": {"teammate-for", "judge"},      # NOT lead
    "judge":            {"lead"},                        # verdict only
}

In my demo, the routing held. Every run, zero breaches. I ran the same check on 5 real Claude Code laser-team sessions, different topics, scanned every inbox file. Zero cross-pair violations there too.

The prompt held every time. I'm not sure if this is because the model is really good at instruction following, or if there's something else going on that I haven't found yet.

The lead is also an LLM

The lead is not a Python script. It's another Claude session with tools: spawn_teammate, send_message, create_task, read_inbox. It decides when to spawn, when to judge, when to shut down.

Its entire instruction is a prompt:

1. Create a debate task
2. Spawn teammate-for (runs in background)
3. Spawn teammate-against (runs in background)
4. Spawn judge (runs in background)
5. Keep reading your inbox until judge sends the verdict
6. Shut down all teammates
7. Present the verdict

Agents poll for mail

All teammates start concurrently. They don't know about each other. They discover the other agents by checking their inbox.

Here is the magical part: files acting as inboxes that take messages from other agents. read_inbox polls the file for changes. If nothing's new, it waits up to 30 seconds before returning.

I learned this the hard way. With a short wait time, each empty poll burned a turn. The lead hit its turn limit and declared the debate over before anyone had finished.

Claude Code's architecture uses the same poll-based approach for inbox delivery.

Mid-debate. All teammates running concurrently, messages flowing through inboxes, tasks being created and claimed:

Shutdown is just another message

No special shutdown tool. The lead sends send_message with message_type="shutdown_request". Same channel as debate messages.

send_message(recipient="teammate-for", text="Shutting down",
             summary="shutdown", message_type="shutdown_request")

The teammate reads it from their inbox like any other message. In real Claude Code teams, approving shutdown kills the process. In my demo, I tell the LLM "your process is terminating, do not call any more tools." In one run, a teammate approved shutdown but kept sending a rebuttal anyway. Shutdown seems to be cooperative, not enforced.

Here's the final state. judge.json has both final positions from the debaters, lead.json has the judge's structured verdict, and the forensic audit shows zero breaches:

Debaters sent to judge, not lead. Judge sent verdict to lead. Zero routing breaches.

Adding one agent doubled the time

I originally built this with 3 agents. The lead judged the debate directly. No routing constraint to test. Finished in ~2 minutes. (3-agent run)

So I added a 4th agent (the judge) to create a real routing constraint: can I make debaters submit to the judge instead of the lead? The routing held. But the run took ~4 minutes. (4-agent run)

Frankly I cannot pinpoint the exact reason why it took so much longer (oh well, I cut corners here not adding langsmith tracing ...), what I know is that the prompts are almost identical, one more agent was added.

Task status is soft too

Teammates create and update tasks as they work. In the run above, they created 9 sub-tasks organically: "Research arguments FOR", "Write rebuttal", "Send final position to judge", etc. When a task is claimed, its status gets updated. When it's done, the teammate marks it complete.

But nothing enforces this. The Claude Code docs warn: "Task status can lag. Teammates sometimes fail to mark tasks as completed." In earlier runs, I saw tasks left as "in_progress" after the debate was fully finished. The work completed fine. The task board just didn't reflect it.

Try it

hippogriff-ai/concept-demos/nano_team. One file, runs in ~4 minutes:

cd nano_team
cp .env.example .env  # add your Anthropic API key
uv sync
uv run python nano_team.py --trace "Your debate topic"

Open output/ in your IDE while it runs. The filesystem is the ground truth. Every message, every forgotten task update, it's all in those JSON files.

Grateful to be picked as one of 500 vibe coders from 13K applicants. Cool to have met fellow builders and learned from them. It was a lot of fun.

Our bathroom has mold — the kind where friends gently suggest that maybe that's why we're always tired. Hiring a contractor was inevitable, but the design part? Out of budget. Plus, I've always loved flipping through Architectural Digest and imagining what I'd do with a space. So when the Built with Opus 4.6 hackathon opened up, I built the tool, something I had been thinking about but hadn't gotten around to.

Remo is an iOS app where you photograph your room, scan it with LiDAR, chat with an AI design consultant, get photorealistic redesigns, iteratively refine them by annotating what you want changed, and walk away with a shoppable product list. Photo to purchasable product list, all AI-orchestrated.

Here's what I learned building it.

Architecture

One Temporal workflow per design project. The user's journey — upload photos, scan the room, chat about style, generate designs, annotate changes, approve, get a shopping list — is one long durable execution. If Gemini times out mid-generation, Temporal retries automatically. If the user closes the app and comes back tomorrow, their progress is still there. If they abandon entirely, a 48-hour timeout auto-purges the entire project from R2 and the database. No cron jobs. No orphaned data.

The key architectural rule: AI calls only happen in activities (except one sync photo validation in the API). Workflow handles orchestration. Activities are stateless — a deliberate trade-off. Every activity re-fetches what it needs (re-downloading images from R2 on every retry) instead of caching in memory. That costs extra I/O, but it buys durability: if a worker crashes mid-generation, Temporal retries the activity on any available worker with zero state to reconstruct. I chose reliability over efficiency because the expensive part is the AI call, not a second image download.

This separation also meant I could swap Gemini model versions, change prompt strategies, and add entire pipeline stages without touching the workflow state machine. Tests across backend and iOS verify this contract holds.

"Read the Room!" — Eager Analysis

Users spend 30-60 seconds on the LiDAR scan. Dead time for the server. So while they walk around, Claude Opus reads their photos and builds a design hypothesis — room type, furniture inventory (keep or replace?), behavioral signals ("toiletries everywhere" → "needs concealed storage"), and where the biggest opportunity lives.

Result: the AI's first question isn't "what style do you like?" — it's "I notice you have no concealed storage — is that a pain point?"

The workflow fires this via asyncio.shield() concurrently with the scan. Opus is thorough, so it sometimes finishes after the user. If it fails entirely? Blank-slate conversation. Less intelligent first question, no crash.

The Intake Agent: Not a Form. A Design Brain.

Most AI apps ask you to fill out a form. Remo has a conversation. The agent asks about your room, references what it saw in the photos, and translates vague language ("I want it cozy") into professional design language ("warm 2700K ambient lighting with layered textiles"). Say "I want it cozy" and the agent dynamically loads style-specific knowledge — proportions, material palettes, signature elements — into its next response.

Behind this is a 243-line system prompt encoding three layers of interior design theory: Francis Ching's spatial foundations, Elsie de Wolfe's human-centered refinement, and Dorothy Draper's emotional impact principles. I didn't know any of these names before building Remo. A designer friend pointed me to the icons, and I spent hours having Claude give me a crash course on the domain — while Claude Code was Ralph-looping Maestro UI tests on the side.

The constraint that makes it work: the agent can only do two things each turn — ask a question or produce a design brief. No free-form rambling. Every turn either gathers information or delivers a result. When the turn budget hits 1, the prompt literally says: "This IS your last chance — draft the best brief you can."

The output is a DesignBrief — room type, pain points, keep items, lighting with Kelvin temps, colors with 60/30/10 proportions, textures as material descriptors, lifestyle patterns, emotional drivers. Every field translates directly into the image generation prompt. The conversation streams to the iOS client via SSE in real-time, so the user watches it appear word by word.

The Annotation Circle: What Multimodal Models Taught Me About Data

Users circle areas they want changed. I was trying to be smart, adding annotations into the input picture. Consequently, Gemini kept those circles in the redesigned image.

My first instinct was to fix the prompt. "Ignore the annotation markers." "The circles are instructions, not content." "Do NOT reproduce any overlay elements." Seven versions of increasingly desperate wording. None of them worked.

The learning: in image generation, visual signals override text instructions. Telling Gemini "ignore the circles" created a contradiction — the pixels said "circles are here" while the prompt said "pretend they're not." The model couldn't reliably distinguish between "annotation that the user drew" and "decorative element on the wall" because both were just pixels in the input image.

The fix wasn't better wording. It was changing the data representation entirely — stop sending visual annotations, switch to text coordinates: "Region 1: upper-left area of the image (30% from left, 40% from top, medium area) — ACTION: replace — INSTRUCTION: replace the dated vanity with a floating modern one". No more conflicting signals. Problem gone. The VLM eval's artifact_cleanliness score confirmed the fix quantitatively.

The broader takeaway: when your text prompt and your image contradict each other, the image wins. So don't fight the model — change the input.

The Eval Pipeline: Measurement Over Intuition

How do you know if a generated room redesign is any good? You "look" at it.

I built a VLM judge — Claude Opus 4.6 scores every generated image against a 100-point rubric with 9 criteria. Room preservation gets the highest weight (20/100), because if the AI turns your room into a completely different room, that's useless no matter how pretty it is.

25 versioned prompt files across three tracks (generation, edit, shopping). A/B testing generates 5 images per version, scores each, then runs 10,000 bootstrap resamples on those 10 scores — small sample, heavy statistical lifting — and returns a SHIP, LIKELY_BETTER, INCONCLUSIVE, or ROLLBACK verdict. Cost per eval: ~$0.02.

Generation prompt v1 was 15 generic lines. By v5, it references Canon EOS R5 camera characteristics — because that's what makes renders look like photographs instead of AI slop.

The rollback story: I shipped room_preservation v5 — LiDAR-aware dimensional constraints. The original eval said "LIKELY_BETTER — SHIP." Then I upgraded the judge from Sonnet 4.5 to Opus 4.6 and built a proper rubric. The stronger judge scored v5 worse than v4 on spatial accuracy. Rollback was one line in a JSON config.

The lesson: measure your measurement tool too. A weak judge had approved a regression that a stronger judge caught.

The Shopping Pipeline: 5 Steps, 24 Retailers, Real Products

The shopping pipeline extracts items from the approved design (Claude vision), builds multi-query search strategies per item, runs dual-pass Exa searches (retailer-constrained pass + open web), scores candidates with a category-adaptive rubric, and assembles the final list.

28 color synonyms expand search recall — "sage" also searches "muted green," "olive," "eucalyptus." 24 curated retailer domains anchor the first pass. A flag-don't-gate philosophy: if a product's dimensions might not fit the LiDAR-measured space, it gets a warning badge, not silent removal. Your room, your call.

The whole pipeline streams results via SSE with a 3-second handoff protocol between the Temporal workflow and the API process — if the iOS client is connected and polling, it claims streaming ownership and delivers products in real-time. Otherwise, the workflow runs shopping as a standard Temporal activity and the user sees results all at once.

Behind the Scenes: The Demo Video

Claude Code co-produced the demo video — 25 SVG overlays from text prompts, burned them into clips via ffmpeg, planned the shot list, drafted voiceover scripts. Even with Claude Code's help, I only managed to submit without voiceover, 2 minutes before deadline. Finished beats perfect. Though I felt a bit disappointed in my video editing fluency - time to shake it off, just means more deliberate practice!

Next Steps

• Latency — The current workflow takes 15min (raw demo video here). To me, it feels way too long. Frankly, I am not sure how to cut down the latency in image generation. Need to do more research.

• Search relevance — Better ranking signals and visual similarity to close the gap between design and purchasable products. I truly do not enjoy shopping all night for renovation things where style and measurement both matter and ended up with sore eyes and an empty shopping cart.

Takeaway

Durability

A good prompt means nothing if the system around it can't retry failures, survive user abandonment, or stream results in real-time. The prompts are maybe 30% of the work. The other 70% is making them reliable at scale.

Enclosed feedback eval loop

The eval pipeline isn't just for me to check results — it's what lets Claude Code iterate on prompts autonomously. Give it a high-level guideline and an eval rubric, and it can tweak a prompt, run the eval, read the scores, adjust, and try again. That's how 25 prompt versions happened without 28 manual review sessions. Some shipped. Some rolled back. The loop catches regressions that neither I nor the AI would notice in a single pass.

Spec

Spec is worth investing your time in, even though it means that the coding will start late. It helps you to think deeper, to reflect whether something is worth building, how it should behave, what should be non-negotiable.

My Go-to claude code features

Agent Team

I like using a team of agents on research and gap analysis tasks.

Ralph-loop

Eventual close-enough perfection right? Just like life.

I always feel defeated when revising my resume. The mixed feeling of "I have so much to offer" and "I am not enough" keeps fighting each other. And guess what, my friends do not enjoy the process either.

About a year ago, two other friends and I tried to build a resume agent in a Google Agent SDK hackathon. We abandoned it halfway because of scheduling and other challenges. I really wanted to materialize the vision, therefore started to tinker on it in spare time off and on. Yeah, it took a while, multiple redesigns from agent harness all the way to UX. And today, it is finally in a not-so-unusable state.

Try here : 30 complimentary runs per day globally

Things I learned

Workflow or agentic

I chose the workflow design because an orchestrated stage made most sense to me as a user: Research target and gaps -> Discover hidden power -> Initial Draft -> Iteration Drafting -> Final output

Meanwhile, I keep doubting myself if this is the best way. Bitter lesson, and this article from Minh Pham mentioned using a human way of thinking to solve problems may restrict the power of LLM. I might go do some experimentation on different agent architectures.

The two architectures on my target list are:

• main-subagents for efficient context management
• skill-based single agent architecture: I do notice that there is a lot of shareable context throughout the workflow. As a matter of fact, I am passing the state along the current orchestrated agent architecture.

Agentic runtime

I am a fan of langgraph. The flexibility to define state, control the state flow, and native support of human-in-the-loop thanks to checkpointing has expanded the canvas greatly to build an agent. deepagents has also been on my radar. I like it a lot for agent harness without tying to a specific model provider. Though I did not use deepagents lib in this project, I want to thank it for teaching me how to think of virtual file system vs. database retrieval. I am amazed at the duck typing that bridged the strong Linux command skill from LLM and RDBMS retrieval.

Development-time eval harness to allow coding agent to better help

If I had enough resources: curate a set of example inputs and outputs, get a comparator to watch the actual output vs expected output. The comparator can be a function if there is a definitive aspect of the criteria, otherwise an LLM judge that shares an expert's taste. Human will drive the cycle, trigger a batch run, get comparison, after analyzing failure modes, update the prompt (or LLM judge), keep going.

However, for a hobby project, I need to find some shortcut. Inspired by the famous ralph loop, if you can give clear criteria for the coding agent, most likely it will get it for you EVENTUALLY. Here is what I did:

• Acquired a deep research report on what a good resume should look like
• Fed that into Claude Code, asking for a draft of grader agent that uses scoring rubric (I had some luck with the scoring rubric idea, got some good results in a finetuning LLM for wine tasting note generation project)
• Test drove the judge on a handful of examples (the draft, the job posting, and the original resume)
• Set up eval harness whose output went directly to the repo
• Gave ralph loop instruction: tune the drafting prompt, ensure score from LLM judge needs to be above 88. Then let the ralph do whatever it thinks it should do to reach there (except for changing the judge, it needs my permission to do so if it really thinks judge should change).

The drafting agent started to behave a lot better than before, but is it there already? Not yet, but it can sometimes generate something I did not think of.

Memory

Well well well, I wanted to build it very much! Stay tuned! I am trying to integrate it with another fun project. In this resume project, I got hesitant because of the PII, therefore I removed all the persistence. Btw, inspired by some tweets, I added CONTINUITY.md as an external memory for the coding agent to know what I have asked it to do. I find it quite helpful even for myself — when vibe coding on a project on and off, it is so easy to lose track of where things are.

I upgraded to an ergonomic split keyboard lately, and my speed tanked. I could get by leveraging my piano skills, now those compensation patterns stop working - split layout turns out to be too big of a gap to fill.

I have drastically cut back on casual playtime so that I can have more time to learn and build, adding uptight typing drills tips the balance too far - it takes the joy out of the process.

Why not make it fun by building something I like, so daily grind becomes daily play?

Space Invaders, but educational

Why Space Invaders

I am a big fan of an pseudonymous street artist Invader space-invaders.com, scanning his work during my trips have always been my highlights.

While I was holding my phone getting ready to scan, my eyes are busy taking in every little detail of the streets, hoping to find the hidden-in-plain-sight mosaic art.

I have so many fond memories because of his art.

How the game works

TypeCraft drops letters from the sky as pixel invaders. Type the letter to destroy it. Miss it, and it lands and eats the grape in the center.

The game tracks which letters you miss, which ones take longest, and adapts — sending more of your weak letters as you play.

It's about precision under pressure.

(for the record, I do NOT want to destroy the invaders at all, I just like the feeling of seeing A LOT OF space invaders)

What I learned building it

SPEC SPEC SPEC It started from a simple idea, but to make it cohesive, it took 45 min iterating with Claude Code to write a spec.

...AND there are still details that both me and Claude missed, like accepting enter key as signal for 'Continue' button.

Try it

TypeCraft is live. Play a round, find your weak keys, and let me know what you think.