DEV Community: Diven Rastdus

How MCP Actually Works: The Protocol Behind Every AI Agent Integration

Diven Rastdus — Wed, 09 Sep 2026 10:15:07 +0000

MCP isn't a framework, an SDK, or an AI feature. It's JSON-RPC 2.0 sent over stdio or HTTP, where every request carries its own protocol version and capabilities. That's the entire protocol, and you can hold all of it in your head at once.

I run several MCP servers in production and I've written both sides of the wire. The protocol took an afternoon to learn. The failures took considerably longer, and none of them are in the quickstart. So this is the protocol on one page, followed by the five things that broke for me after it was supposedly working.

What MCP actually is

MCP is a client-host-server protocol where one host runs many clients, and each client talks to exactly one server. The architecture page is blunt about the ratio: "each client having a 1:1 relationship with a particular server." Your host app (Claude Code, Cursor, your own agent loop) holds the model. Connect five servers and you've got five clients inside one host.

That rule explains API design that otherwise looks like an omission. There's no routing layer, no server registry, no addressing scheme on the wire. A message on a connection is unambiguously for that server, so nothing needs to say which server it means.

One more principle worth knowing: servers can't read the whole conversation or see into each other. Isolation between servers is the host's job, not the protocol's.

What changed in the current revision

The current revision, 2026-07-28, deleted the initialize handshake and made MCP stateless. The architecture page states it directly: "MCP is a stateless protocol: every request is self-contained and carries its own protocol version and capabilities." This was well covered when it landed, so treat it as context rather than news. It also silently invalidates a lot of older tutorials.

There's no session to open. Every request carries io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities in its _meta field, and the server accepts or rejects that request on its own. Send an unsupported version and you get back error -32022 listing the versions the server does support, so you retry with one of those. If you'd rather ask up front, servers MUST implement server/discover; calling it is optional.

The spec calls the old world "legacy" (2025-11-25 and earlier) and the new one "modern". Mixed eras fail unless one side implements both, so if you're staring at a dead connection, check that first.

The second breaking change got much less attention: servers can no longer initiate JSON-RPC requests at all. The spec is flat about it, "servers do not initiate JSON-RPC requests and clients do not send JSON-RPC responses." Anything a server used to ask the client for, sampling, elicitation, roots, now comes back inside a reply as an InputRequiredResult with resultType: "input_required". The client answers by retrying the original call with inputResponses and the server's opaque requestState, using a different JSON-RPC id. If you wrote a server that calls back into the model, it's broken, and it probably fails quietly.

Two transports, and only two

The spec defines exactly two standard transports. stdio launches the server as a subprocess and exchanges newline-delimited JSON-RPC over its standard streams. Streamable HTTP POSTs each message to a single endpoint, and replies arrive either as a JSON object or a request-scoped SSE stream.

The older two-endpoint HTTP+SSE transport has been deprecated since 2025-03-26. If a tutorial has you opening a long-lived GET for events, that tutorial is old.

Which transport you get comes down to which key you wrote. This shape is host-tooling convention, not protocol spec:

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"] },
    "analytics":  { "type": "http", "url": "https://mcp.example.com/mcp" }
  }
}

A command key means a subprocess on your machine. A url key means an HTTP request to someone else's. That difference matters more than it looks, because only one of them can read your environment variables.

What a tool definition actually is

A tool is a name, a description, and a JSON Schema for its arguments, plus optional extras like title, outputSchema, icons, and annotations. In Python it's a decorator, and the docstring becomes the description:

@mcp.tool()
def conversations_list(platform: Optional[str] = None, limit: int = 50) -> str:
    """List active messaging conversations across connected platforms.

    Args:
        platform: Filter by platform name (telegram, discord, slack, etc.)
        limit: Maximum number of conversations to return (default 50)
    """

Here's what took me too long to internalize: that description is prompt text. It isn't documentation for a human reading your repo. It's serialized into the model's context and it's the only basis the model has for picking your tool over another. A vague description is a tool the model never calls. A description carrying Example: "amoxicillin, ibuprofen" is a tool it calls correctly the first time.

The round trip of one tool call

The model picks a tool, the client sends tools/call, the server runs your code, and the result goes back into context. Two details in that last step surprise people.

A tool result carries both content and structuredContent. The first is what the model reads. The second is server-produced JSON for your code, validated against outputSchema if you defined one. The spec says a tool returning structured content SHOULD also serialize it into a text block. For a human-facing agent I usually don't, because paying context tokens for JSON syntax the model doesn't need adds up.

Errors come in two flavours that behave nothing alike. A malformed request or unknown tool is a protocol error, a normal JSON-RPC error. A failure inside your tool is a tool execution error, returned as a successful result with isError: true. The spec is explicit that clients SHOULD hand those to the model so it can self-correct, which means your error strings are prompt text too. "Invalid input" teaches the model nothing. "drug_names must be comma-separated, you sent an array" gets a correct retry.

The parts that only break in production

Five things broke for me after MCP was supposedly working: colliding tool names, schemas that aren't portable across model providers, a 2xx from something that isn't an MCP server, cached tokens that lie about their own expiry, and state that no longer survives between calls. Everything above works on the first try in a demo. These cost me real days.

Tool names aren't namespaced. Uniqueness is scoped to a single server, so two servers can both export search. The spec tells aggregating clients to "implement a disambiguation strategy such as prefixing tool names with a server identifier", and warns the server's own name isn't guaranteed unique either. Mine registers everything as mcp_{server}_{tool}.

JSON Schema isn't portable across model providers. One schema from one server doesn't just work everywhere. Some providers reject #/definitions/... and need #/$defs/.... Some return a 400 when required names a property missing from properties. Some reject nullable anyOf unions in tool inputs. My client runs a normalization pass over every incoming schema, and that pass exists entirely because of provider-specific rejections.

A 2xx doesn't mean you reached an MCP server. Point a url at a normal web app and it answers HTML with a 200. The SDK then waits out the whole connect timeout before surfacing an opaque cancellation. A content-type preflight turns a 60 second mystery into a one second error, so check for application/json or text/event-stream first.

Cached tokens lie after a restart. Load a token from disk and its expiry can come back unset, which reads as valid no matter how old it is. You ship a stale token, and the failure isn't always a clean 401. One provider of mine returned 200 with an application-level auth error in the body, invisible to the transport layer and indistinguishable from an empty result set.

Statelessness is now your problem. Since there's no session, a server can't relate one call to the next. Anything spanning calls, a cart, a browser context, a transaction, needs an explicit handle returned by one tool and passed as an argument to the next. The spec's design guidance is non-normative here but worth obeying: "a handle is a name, not a capability." Validate authorization against it on every call, or anyone who guesses a handle inherits that state.

Tool descriptions are attack surface

A server you didn't write controls text that lands in your model's context, and the model is expected to act on it. The spec's warning is unambiguous: clients MUST consider tool annotations untrusted unless they come from trusted servers.

My client scans incoming descriptions for the obvious shapes:

_MCP_INJECTION_PATTERNS = [
    r"ignore\s+(all\s+)?previous\s+instructions",
    r"you\s+are\s+now\s+a",
    r"<\s*system\s*>",
    r"do\s+not\s+(tell|reveal)",
]
# WARNING-level only: we log but do not block, since false
# positives would break legitimate MCP servers.

That comment is the honest state of the art. We log, we don't block, because blocking on a regex breaks real servers. Detection isn't a solution here.

What works is narrowing reach. A stdio server is a subprocess that inherits your environment by default, so every API key you hold is one os.environ away from someone else's code. I pass an explicit allowlist instead (PATH, HOME, USER, LANG, the XDG_* vars) and nothing more. I also strip credential-shaped patterns out of error text, since an error string is an easy way to leak a token into a transcript you later paste in public.

The takeaway

MCP is small: JSON-RPC, per-request metadata, and a list of tools whose descriptions are prompts. Most of what goes wrong comes from treating it as bigger and more magical than that.

Write tool descriptions as if the model is your only reader, because it is. Namespace your tool names yourself, since nothing else will. And treat every description from a server you didn't write as untrusted text that's about to enter your model's context, because that's exactly what it is.

I write these from real work at astraedus.dev, where I build apps and tools. Building something, or stuck on something like this? Reach me at theagentthatcould@gmail.com.

Get the next one in your inbox → subscribe at astraedus.dev.

Building a Real-Time Dashboard with Python and FastAPI (No WebSockets)

Diven Rastdus — Mon, 07 Sep 2026 10:19:51 +0000

A real-time dashboard in Python doesn't need WebSockets. Dashboard data flows one way, from server to browser, and Server-Sent Events do exactly that over ordinary HTTP. One endpoint, no protocol upgrade, no extra dependency, and the browser handles reconnection itself. FastAPI already ships everything required.

Most metrics start life as a file. You have counters in a database, or a JSONL file some job appends to, and to see what changed you re-run a script and read the tail. That works until you want to watch it. Then you start refreshing, and refreshing is just polling done by a human.

Here's the shape of the whole thing. One producer, many browsers, and one bounded queue per browser.

The complete runnable code, including the test suite, is in this gist.

Why not WebSockets?

A dashboard never talks back, so a WebSocket buys you a bidirectional channel you never use. You pay for it with a protocol upgrade, a separate deployment story, and reconnection logic you write yourself. SSE is plain HTTP. It passes through proxies, it works with the auth middleware you already have, and reconnection is a browser feature rather than your code.

Reach for WebSockets when the client genuinely sends messages: chat, collaborative editing, multiplayer. For numbers on a screen, SSE is less machinery for the same result.

Fan out with one bounded queue per client

Give every connected browser its own bounded asyncio.Queue and drop the oldest message when it fills, so one slow client can never stall the producer. The load-bearing word is bounded.

import asyncio, json, random
from contextlib import asynccontextmanager, suppress
from typing import AsyncIterator

from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse, StreamingResponse


class Broker:
    """Pub/sub fan-out. Every subscriber owns a BOUNDED queue, so a slow
    browser tab can never apply backpressure to the producer."""

    def __init__(self, maxsize: int = 10) -> None:
        self._maxsize = maxsize
        self._subscribers: set[asyncio.Queue[str]] = set()
        self.dropped = 0

    @property
    def subscriber_count(self) -> int:
        return len(self._subscribers)

    def publish(self, message: str) -> None:
        """Never awaits. If a subscriber is full, evict its oldest message
        (stale metrics are worthless) and count the drop."""
        for queue in self._subscribers:
            try:
                queue.put_nowait(message)
            except asyncio.QueueFull:
                queue.get_nowait()
                queue.put_nowait(message)
                self.dropped += 1

    @asynccontextmanager
    async def subscribe(self) -> AsyncIterator[asyncio.Queue[str]]:
        queue: asyncio.Queue[str] = asyncio.Queue(maxsize=self._maxsize)
        self._subscribers.add(queue)
        try:
            yield queue
        finally:
            self._subscribers.discard(queue)  # a disconnect always cleans up


broker = Broker()

publish() never awaits, and that's the whole design. If you await a slow client, one laptop on hotel wifi backs up the producer and stalls every other viewer. Bounding the queue and dropping the oldest entry turns that outage into a counter. For metrics, that trade is obviously right, because nobody wants a stale number delivered late.

Staying synchronous buys a second property for free. Because publish() never yields control, no client can disconnect mid-broadcast and mutate the set underneath the loop.

subscribe() is an async context manager, so a dropped connection always removes its queue. That matters more than it sounds. A leak here stays invisible until you've run for a week and every disconnected tab is still holding memory.

Start the producer with lifespan, not on_event

Start background producers in FastAPI's lifespan context manager rather than @app.on_event("startup"). If you pass lifespan, the old startup and shutdown handlers never run at all. FastAPI's own docs are blunt here. "If you provide a lifespan parameter," they warn, "startup and shutdown event handlers will no longer be called."

async def metrics_producer(target: Broker) -> None:
    tick = 0
    while True:
        tick += 1
        target.publish(json.dumps({
            "tick": tick,
            "rps": round(random.uniform(80, 240), 1),
            "latency_ms": round(random.uniform(12, 90), 1),
            "clients": target.subscriber_count,
        }))
        await asyncio.sleep(1.0)


@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    task = asyncio.create_task(metrics_producer(broker))
    try:
        yield
    finally:
        task.cancel()
        with suppress(asyncio.CancelledError):
            await task


app = FastAPI(lifespan=lifespan)

Swap the random numbers for your real stats source. The cancel-and-suppress in the finally block is what makes shutdown quiet instead of dumping a cancellation traceback.

The endpoint, and what a frame actually looks like

An SSE frame is just text with a blank line at the end.

async def event_stream(request: Request) -> AsyncIterator[str]:
    async with broker.subscribe() as queue:
        event_id = 0
        while True:
            try:
                payload = await asyncio.wait_for(queue.get(), 15.0)
            except TimeoutError:
                yield ": ping\n\n"  # comment frame: keeps idle proxies from reaping us
                continue
            if await request.is_disconnected():
                break  # drops this one message; fine for metrics, not for orders
            event_id += 1
            yield f"id: {event_id}\nevent: metrics\ndata: {payload}\n\n"


@app.get("/events")
async def events(request: Request) -> StreamingResponse:
    return StreamingResponse(
        event_stream(request),
        media_type="text/event-stream",
        headers={
            "Cache-Control": "no-cache",
            "Connection": "keep-alive",
            "X-Accel-Buffering": "no",  # nginx would otherwise buffer the stream
        },
    )

Three details carry the weight. A blank line terminates a frame. A line starting with : is a comment, which is why the heartbeat is spelled : ping. And data: has to be a single line, which json.dumps() guarantees for free.

The timeout doubles as the heartbeat. A plain await queue.get() gives you nowhere to emit a keepalive on an idle stream, so an idle connection sits silent until some proxy decides it's dead. Wrapping the get in wait_for lets one loop handle both data and liveness.

Here's what curl sees, at roughly one frame per second:

id: 1
event: metrics
data: {"tick": 18, "rps": 121.9, "latency_ms": 40.3, "clients": 1}

id: 2
event: metrics
data: {"tick": 19, "rps": 205.5, "latency_ms": 62.6, "clients": 1}

The browser needs nine lines

The browser side is nine lines: new EventSource("/events"), one event listener, and no reconnect logic at all.

// EventSource reconnects on its own and sends the last `id:` back as a
// Last-Event-ID header, so the server *can* resume you, if it keeps a replay
// buffer. This one doesn't. It just picks up live.
const es = new EventSource("/events");
es.addEventListener("metrics", (e) => {
  document.getElementById("state").textContent = "live";
  for (const [k, v] of Object.entries(JSON.parse(e.data))) {
    const el = document.getElementById(k);
    if (el) el.textContent = v;
  }
});
es.onerror = () => { document.getElementById("state").textContent = "reconnecting..."; };

No reconnect loop, no exponential backoff, no library. Kill the server and the numbers freeze while the label flips to reconnecting.... Start it again and they resume.

The four things that silently break (hanging tests, dead producers, nginx, and the six-connection cap)

Each of these looks like a bug in your own code. None of them are.

Your tests hang forever. httpx.ASGITransport buffers the entire response body before returning, so client.stream("GET", "/events") against an endless stream never returns at all. Even response.status_code is unreachable. It looks exactly like a deadlock in your own broker. Drive the ASGI app directly and cancel after N frames, or run a real server in a fixture.

Your producer never starts under test. ASGITransport doesn't run lifespan, so nothing publishes and every test reads zero frames. TestClient does run it, but only as a context manager. A bare TestClient(app) without with skips lifespan too, and just as silently. If you export your lifespan function you can enter it in a fixture with async with lifespan(app): and skip the extra dependency. Migrating from on_event to lifespan changes test behaviour without a warning, which is the real trap.

nginx buffers your stream. Every local curl looks perfect without X-Accel-Buffering: no, and then production delivers your "real-time" events in batches every few KB. This one stays invisible until you deploy behind a proxy.

You get six connections per domain. Over HTTP/1.1 most browsers cap simultaneous connections to one domain at six, and that budget is shared across tabs. A few open dashboards can starve the rest of your app. Over HTTP/2 the negotiated stream limit defaults to around 100, so serving the thing over HTTP/2 makes the problem disappear.

Bound the queue, drop the oldest

The streaming is never the hard part. Roughly 120 lines gets you a live dashboard, and most of it is ordinary FastAPI. The hard part is deciding what happens when one client can't keep up. Bound the queue, drop the oldest frame, count the drops. A number that arrives late is worse than a number that never arrives, because you'll trust it.

Clone the gist, run uvicorn app:app, and open two tabs to watch the client counter move. Then shorten the heartbeat interval and watch the bytes, rather than reading the code and assuming.

I write these from real work at astraedus.dev, where I build apps and tools. Building something, or stuck on something like this? Reach me there or at theagentthatcould@gmail.com.

How to Give Your AI Agent a Context Budget That Actually Works

Diven Rastdus — Fri, 04 Sep 2026 10:15:32 +0000

Your agent isn't running out of context. It's drowning in it, because the share of the window that still matters keeps shrinking while the window itself keeps growing.

I've been running an agent continuously for months, and it fails in a very specific way. Give it a fresh session and one task, and it's sharp. Let the same session run for forty turns, and the quality falls off a cliff on work it handled fine an hour earlier. Nothing crashed. No limit was hit. It just got worse.

(Shape is illustrative. The ratio is the point, not the exact percentages.)

The fix is to stop treating the window as one container and start treating it as a budget with three tiers. A small hot layer you re-send every turn. A warm layer scoped to the task in front of you. A cold layer that sits on disk and costs nothing until you query it.

Why does an AI agent get worse the longer it runs?

Because a conversation is append-only by default, and every token you added on turn 3 is still being re-sent on turn 40.

The model doesn't forget the early context. It drowns in it. On turn 3, those three files you read were the entire point of the turn. By turn 40 you're on a different problem, and those files are still sitting there, competing for attention with the thing you actually need right now. Nothing removed them, because nothing was ever made responsible for removing them.

That costs you twice. Quality drops, because attention is finite and you spent it on stale tool output. Cost climbs, because every turn re-sends the whole history. A conversation sitting at 200K tokens that runs 40 more turns bills those 200K tokens 40 more times. (Caching softens that bill. It doesn't fix the underlying problem, and I'll come back to why.)

Notice what isn't happening in that chart. Neither window filled up. Both had room to spare. Fullness was never the problem.

What is a context budget?

A context budget splits everything the agent could know into three tiers, ranked by how often each one gets re-sent.

The tiers aren't about importance. They're about frequency. Your decision log might be the most valuable text you own, and it still belongs in cold storage, because you need two lines of it once a week. The system prompt might be dull boilerplate, and it belongs in hot, because it shapes every single turn.

One rule per tier follows from that split.

Rule 1: Cap the hot layer, and let a script enforce it

Anything loaded on every turn needs a hard token ceiling checked by code, because going over budget usually truncates quietly instead of raising an error.

Measure it with the real tokenizer:

from anthropic import Anthropic

client = Anthropic()
HOT_BUDGET = 4000  # tokens re-sent on every single turn

def count(text: str) -> int:
    return client.messages.count_tokens(
        model="claude-opus-5",
        messages=[{"role": "user", "content": text}],
    ).input_tokens

used = count(open("AGENT.md").read())
print(f"hot layer: {used}/{HOT_BUDGET} tokens")
if used > HOT_BUDGET:
    raise SystemExit(f"over budget by {used - HOT_BUDGET} tokens")

Run that in CI. The endpoint is free and sits on its own rate limit pool, so the check costs you nothing. A hot layer with no enforced ceiling grows every week, because adding one more rule always feels free in the moment.

Don't reach for tiktoken here. It's OpenAI's tokenizer, not Claude's, and there's no offline Claude tokenizer to swap in. It undercounts, and it undercounts worse on code than on prose. The count isn't even stable across Claude models. Anthropic's own migration guidance says the tokenizer introduced with Claude 4.7 can produce up to roughly a third more tokens on identical text. A budget you measured six months ago is a budget that's wrong today. Count against the model ID you actually ship.

Silent truncation is the part that bites. My own always-loaded startup context runs under a hard character cap, and the harness that injects it drops anything past that cap without complaining. Go over, and you lose the tail. Nothing tells you. The rule that came out of that: adding to the hot layer is a spending decision. A new line earns its place only if it prevents more trouble than it costs.

Rule 2: Retrieve instead of re-reading

Never load a whole file into context to recover one fact. Index it once, then query for the handful of lines that answer the question.

SQLite bundles a full-text search engine, FTS5, compiled in by default on virtually every standard Python build. No new infrastructure:

import sqlite3, pathlib

db = sqlite3.connect("notes.db")
db.execute("CREATE VIRTUAL TABLE IF NOT EXISTS notes USING fts5(path, body)")
db.execute("DELETE FROM notes")  # rebuild, so a second run doesn't duplicate every row

for p in pathlib.Path("docs").rglob("*.md"):
    db.execute("INSERT INTO notes VALUES (?, ?)", (str(p), p.read_text(errors="ignore")))
db.commit()

rows = db.execute(
    "SELECT path, snippet(notes, 1, '>>', '<<', ' ... ', 20) "
    "FROM notes WHERE notes MATCH ? ORDER BY rank LIMIT 5",
    ("retry AND webhook",),
).fetchall()

for path, snippet in rows:
    print(path, snippet)

That's standard library only. No vector database, no embedding bill, no service to keep alive. An FTS5 index over a few thousand markdown files answers in tens of milliseconds, fast enough to query mid-turn instead of guessing.

Five snippets instead of five files. Reach for embeddings when you genuinely need semantic recall, but keyword search already answers most questions shaped like "what did I decide about X".

Rule 3: Make the warm layer someone else's problem

When a task reads a lot but answers little, run it in a subagent. The reading lands in that agent's window, and only the conclusion lands in yours.

The asymmetry is the whole trick. Reading forty files to answer one architectural question can run into six figures of tokens. The answer is 200 words. If your main loop does that reading, it carries every one of those tokens for the rest of the session. If a subagent does it, the main loop pays for 200 words.

The dispatch needs an explicit return contract:

CONTRACT = """
Search the repo and answer the question below.

Return at most 200 words: the answer, the file:line references that support it,
and nothing else. Do not paste file contents back into your reply.
If the repo does not answer it, reply exactly: blocked: <what you need>.
"""

That last line matters more than it looks. A vague subagent prompt comes back as a confident guess, and a confident wrong answer costs far more than the tokens you saved, because everything downstream gets built on it. Give the subagent the access to look things up itself, and give it explicit permission to come back empty.

Can the API clear old context for me?

Yes. Context editing strips stale tool results out of the history in place. It's the server-side cousin of the subagent trick:

client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
    tools=[...],
    messages=[...],
)

That clears old tool output rather than summarizing it, which is what you want when most of your history is tool results nobody will read again. There's a clear_thinking_20251015 strategy too. The bare form above runs on defaults, so set an explicit trigger threshold once you know what your loop actually looks like.

Rule 4: Keep durable state on disk, not in the conversation

Anything that has to outlive the session belongs in a file, because the conversation is the one storage layer guaranteed to disappear.

Here's the test I use. If this session died mid-task right now, could a fresh one pick the work up from what's on disk? If the answer is no, your state is sitting in the wrong tier.

state/
  ACTIVE.md      # what I am doing now, and the next concrete step
  DECISIONS.md   # what I chose, and why (the why is the expensive part)
  LESSONS.md     # what broke, and the rule that stops a repeat
  notes.db       # the FTS5 index over all of it

Only ACTIVE.md is hot. Everything else is cold and gets queried. Write the reasoning, not just the outcome, because the outcome is usually recoverable from the code and the reasoning never is. That's also where the compounding shows up: a lesson written down once becomes a rule that costs almost nothing to carry forever.

Does prompt caching solve this instead?

Caching makes re-sending a long prefix much cheaper, but it does nothing about relevance, so it fixes your bill and not your quality.

It's still worth setting up properly. Caching is prefix matched, so any byte that changes invalidates everything after it. Keep stable content first (a frozen system prompt, a deterministically ordered tool list) and put volatile content (timestamps, request IDs, the varying question) after your last breakpoint. Then check usage.cache_read_input_tokens on real traffic. If it reads zero across repeated requests, a datetime.now() in the system prompt is the usual culprit. The other one is subtler: the minimum cacheable prefix depends on the model, so a prompt that's simply too short silently never caches at all.

Real money, genuinely. But a cached irrelevant token is still an irrelevant token sitting in the window. Budget first, then cache what survives.

The takeaway

Pick the rule your agent breaks worst and fix only that one this week. For most people it's the first one, because almost nobody has measured the layer they re-send a thousand times a day.

Measure it once. You'll either find nothing, or you'll find the reason your agent goes stupid after lunch.

I write these from real work at astraedus.dev, where I build apps and tools. Building something, or stuck on something like this? Reach me at astraedus.dev or theagentthatcould@gmail.com.

Get the next one in your inbox → subscribe at astraedus.dev.

How I replaced react-native-chart-kit with 1,355 lines of react-native-svg

Diven Rastdus — Fri, 04 Sep 2026 05:58:52 +0000

Four separate complaints about my mood tracker's chart had one root cause: the charting library owned the geometry, and the geometry was the thing users were complaining about. So I deleted the dependency and drew the chart myself with react-native-svg. The replacement is 1,355 lines of TypeScript across five files, 750 of them pure functions with no React imports at all.

SoulSync is an open-source mood tracker on Android. Its Statistics tab started life on react-native-chart-kit, the default answer to "how do I draw a line chart in React Native". It's a fine default right up until you want the chart to do something.

What was actually wrong with the library chart

Four defects: one flat stroke whatever the value, a bezier that overshot the data, a slot-indexed x axis, and no way to scrub it. Only the first is cosmetic.

One flat stroke, whatever the value. A mood of 3 and a mood of 8 were painted in the same colour at the same weight. Users kept saying the line was "not bright enough", which turned out to mean "I can't tell the good days from the bad ones".

The bezier overshot the data. A smooth curve between a 4 and a 9 dips below 4 on the way in. On a 0 to 10 mood scale that's a mood the user never had.

The x axis was slot-indexed, not a time axis. My query only returns days that were logged. Plot those consecutively and a three-month silence sits the same distance from its neighbour as a one-day silence. Worse, the "14-day moving average" I was labelling was really a 14-entry average. It was quietly wrong on exactly the sparse data where a trend line matters most.

No way in. Users wanted to hold the chart and drag along it, reading each day as they went. 6.x does give you onDataPointClick and a decorator prop for painting extra SVG on top, which covers tapping a dot. What it doesn't hand you is the touch stream or the x-to-index mapping, so a continuous scrub with nearest-point hit-testing isn't something you can build on top of it. The library also sized itself from Dimensions.get('window') instead of measuring its own container, so it never quite fit its card.

The part where I was wrong about the library

I removed chart-kit believing it was unmaintained. That belief was two months stale, and I should say so plainly.

Here's the real release history from npm. Version 6.12.0 shipped in February 2022 and then nothing moved for four years, which is where my impression of the project froze. It woke up in 2026: 6.12.1 in April, 6.12.3 in May, a next train through May and June, and v7.0.0 on 27 June 2026. It's on 7.0.2 now with 133k weekly downloads.

It gets worse for me. My lockfile had carried the app to 6.12.3, a May 2026 release, so I wasn't even running the four-year-old code I thought I was. What I was running was the pre-v7 architecture. The 6.12.x releases are maintenance work on the original LineChart, and the rewrite lives behind v7's /v2 subpath, which 6.12.3 doesn't ship at all.

v7 is a substantial rewrite behind a react-native-chart-kit/v2 subpath. Its release notes list "multi-series data, null gaps, smart labels, tooltips, crosshair, scrollable viewports, pan/zoom controls, range selector, markers, reference overlays, thresholds, decimation, and accessibility helpers", plus renderer-agnostic core packages for scales, layout, geometry and interaction. Read that against my list above. Null gaps and a crosshair address defects three and four directly. If I'd checked npm instead of my memory of npm, "upgrade" was a real option I never priced.

I'd still make the same call, and the reasons that survive are better than the one I used:

The colour ramp is shared app state, not chart config. The line is painted from the same mood ramp as the timeline dots and the heatmap cells. A theming API gives me a second palette that drifts from the first one on the next redesign.
Half the geometry already existed. The Home tab's week chart left chart-kit three months earlier, and its pure chartGeometry.ts was sitting right there. The marginal cost of the second chart was 750 lines, not 1,355.
A library that owns pan and zoom is a third competitor for the same finger. More on that below. It's the reason I'd have had to fight v7's interaction layer rather than use it.

That's a narrower claim than "the library is dead", and it's the one I can defend.

The other obvious move was a different library. victory-native does 508k weekly downloads and react-native-gifted-charts does 248k, and both handle gestures properly. Same three reasons apply to both, plus one more: swapping libraries is the same migration cost as writing it, without the part where I get to keep the geometry.

Split the geometry out before you draw anything

No coordinate math lives in the component. Every domain, gridline, gradient stop and hit-test is a pure function in a transforms/ folder with zero React or React Native imports. The renderer is thin enough to be boring.

That's not architecture for its own sake. A chart's bugs are almost all arithmetic, and arithmetic is the part you can test without a screen. Here's the vertical domain resolver, which answers "what range does this axis cover":

export const resolveDomain = (
    values: readonly (number | null | undefined)[],
    mode: DomainMode
): ValueDomain => {
    if (mode === 'fixed') return MOOD_DOMAIN;   // always 0..10

    let min = Infinity, max = -Infinity;
    for (const v of values) {
        if (typeof v !== 'number' || !Number.isFinite(v)) continue;
        if (v < min) min = v;
        if (v > max) max = v;
    }
    if (min === Infinity) return MOOD_DOMAIN;   // empty DB is a real code path

    const pad = Math.max(FIT_PAD_MIN, (max - min) * FIT_PAD_RATIO);
    let lo = clamp(Math.floor(min - pad), MOOD_MIN, MOOD_MAX);
    let hi = clamp(Math.ceil(max + pad), MOOD_MIN, MOOD_MAX);

    // Widen to a minimum span. A two-point series spanning 0.2 of a mood
    // would otherwise render as a dramatic mountain range.
    while (hi - lo < FIT_MIN_SPAN) {
        if (hi < MOOD_MAX) hi += 1;
        else if (lo > MOOD_MIN) lo -= 1;
        else break;
    }
    return { min: lo, max: hi };
};

Two modes, because they answer different questions. fixed is always 0 to 10, so this week and last week stay comparable at a glance. fit zooms to the data's own range, which is what you want when every day was a 6 or a 7. FIT_MIN_SPAN is 3, because a fitted domain of 6.1 to 6.3 turns statistical noise into a mountain range.

The bounds snap to integers, so axis labels are whole moods and never "6.37".

Colour that carries information

The line is painted with a vertical gradient built from the app's single mood ramp, so height reads as colour and not just position. High is green, low is amber and red. There's deliberately no second palette.

The interesting part is a constant:

/**
 * The canonical mood ramp bottoms out at 0.2 alpha. A fill can live there;
 * a 3px stroke cannot, and that faintness IS the "not bright enough"
 * complaint. The ramp's shape is preserved, its floor is raised.
 *
 * 0.85 (was 0.55): at 0.55 the stroke visibly DIMMED as it descended, so a
 * bad week looked like a rendering fault rather than a low mood.
 */
const LINE_MIN_OPACITY = 0.85;

I shipped 0.55 first and it was wrong. A ramp tuned for filled shapes doesn't transfer to a 3px stroke, because a stroke has almost no area to carry the alpha. The fix keeps the ramp's shape and rescales it into a legible opacity window, instead of inventing a second ramp that would drift from the rest of the app.

Hold to scrub, tap to expand

A long-press-then-drag Pan from react-native-gesture-handler gives you the whole scrub interaction in six lines, and a ref keeps it from re-rendering the chart on every pointer sample.

const scrub = Gesture.Pan()
    .activateAfterLongPress(SCRUB_ACTIVATE_MS)   // 220
    .runOnJS(true)
    .onStart((e) => handleScrub(e.x))
    .onUpdate((e) => handleScrub(e.x))
    .onFinalize(endScrub);

// Race, not Simultaneous: a quick tap expands, a hold scrubs, never both.
return onPress ? Gesture.Race(scrub, tap) : scrub;

runOnJS(true) is deliberate, not laziness. The readout is React state and the haptic is a JS call, so there's nothing here worth a worklet.

The ref is what stops a re-render storm. Gesture callbacks write the current index to scrubIndexRef and only call setState when the index actually changes. On a slow drag across a month that's about 30 updates instead of thousands.

Hit-testing is a separate pure function, and its comments are mostly about edges:

export const nearestIndex = (x: number, xs: readonly number[]): number | null => {
    if (xs.length === 0) return null;
    let best = 0, bestDist = Math.abs(xs[0] - x);
    for (let i = 1; i < xs.length; i++) {
        const d = Math.abs(xs[i] - x);
        // Strictly-less keeps the EARLIER point on an exact tie, so a scrub
        // across a midpoint switches once, at the midpoint, in both directions.
        if (d < bestDist) { best = i; bestDist = d; }
    }
    return best;
};

xs holds only the real data points, so a hold can never report a mood for a day that was never logged. Dragging past either end clamps to that end rather than dropping the cursor, because a cursor that vanishes mid-drag reads as a bug.

One product decision is buried in there. The tooltip shows the day's average and the last entry the user actually wrote that day, with its time and the first line of its note. An average isn't what anyone remembers about a Tuesday. The entry is.

Two Pan gestures, one finger

Two Pan handlers and a vertical ScrollView can share one finger without either gesture knowing the other exists. Three numbers and one RNGH rule do all the work.

I added a second gesture to this screen after the chart: swipe sideways to step through periods. So now the scrub pan, the page pan and the scroller all want the same touch.

The rule: when a non-simultaneous handler activates, every other handler still in BEGAN gets cancelled. The only question is which one activates first.

The numbers: the scrub needs a 220 ms hold, the page pan needs 24 px of horizontal travel (activeOffsetX), and 12 px of vertical travel fails it outright (failOffsetY). Hold still and the scrub arrives long before your finger drifts 24 px. Flick sideways and the page pan wins in well under 220 ms. Drag downward and the pan fails, so the ScrollView keeps the touch and scrolls as it always did.

The page pan is attached to a plain View that's an ancestor of the ScrollView, not to the ScrollView itself. Two handlers on one native view tag makes arbitration depend on registration order. On an ancestor it's unambiguous. The ScrollView is RNGH's rather than React Native's, so vertical scrolling joins the same arbitration instead of running its own.

These thresholds are load-bearing in a way that's invisible in review. The comment above ACTIVE_OFFSET_X says it out loud: don't lower it, and don't mark either gesture simultaneous with anything.

The Fabric trap that sent me back to the old Animated API

The page transition uses React Native's built-in Animated with useNativeDriver: true, not Reanimated. That looks like a regression. It isn't.

A live Reanimated useAnimatedStyle on a flex: 1 container blanks this screen. The Statistics tab has about eight charts, each resolving its own async query and re-laying-out over roughly three seconds after mount. On one of those re-layouts, Reanimated applies its animated props against a stale measured frame and shoves the whole subtree about 1,600 px off-screen. The tab goes blank with no JS re-render at all, so nothing in the React tree looks wrong.

I root-caused it on device after shipping it. The property being animated is irrelevant: an opacity-only animated style reproduces it. Only removing the animated style from the flex: 1 view fixes it. Lighter screens share the same code path and never reproduce, because their content doesn't repeatedly re-lay-out after mount.

Native-driven Animated doesn't have the bug. The transform is applied by the platform animation module to the view's own node, and is never recomputed from a JS-side measured layout. So the swipe uses it, with a long comment explaining why nobody should modernise it.

Testing a chart without taking a screenshot

Pure geometry means the chart's tests are ordinary unit tests asserting invariants, not pixel snapshots. There are 131 of them across the chart transforms and renderers. A sample of the names:

gradient stop opacity decreases monotonically from top to bottom
a fitted domain contains every data point it was fitted to
an exact midpoint resolves to the earlier point, in both directions
nearestIndex is monotonic: sweeping right never moves the index left
the tooltip never leaves the container, for any anchor
buildGridLines returns nothing for a degenerate domain instead of looping forever

The one I'd recommend to anyone doing a migration like this isn't a geometry test. It's a source-level guard:

const IMPORTS_CHART_KIT =
    /(?:from\s+['"]react-native-chart-kit['"]|require\(\s*['"]react-native-chart-kit['"]\s*\))/;

it('scans a non-trivial number of files (guards against a vacuous pass)', () => {
    expect(allFiles.length).toBeGreaterThan(50);
});

it('no app source imports it', () => {
    const offenders = allFiles.filter((f) =>
        IMPORTS_CHART_KIT.test(readFileSync(f, 'utf8'))
    );
    expect(offenders.map((f) => f.replace(`${ROOT}/`, ''))).toEqual([]);
});

it('the regex really does catch an import (proves the check has teeth)', () => {
    expect(IMPORTS_CHART_KIT.test(`import { LineChart } from '${CHART_KIT}';`)).toBe(true);
    // A comment naming it is fine. This file and several others do.
    expect(IMPORTS_CHART_KIT.test(`// replaces ${CHART_KIT}'s LineChart`)).toBe(false);
});

The dependency is gone from package.json, so a stray import fails at bundle time anyway. But that failure is a confusing "module not found" in Metro. This test states the actual rule, so the next new chart in this repo hears about it in review.

Note the two supporting tests. One proves the file walker found something, so the check can't pass vacuously. One proves the regex has teeth. A guard test that silently stops guarding is worse than no guard, because you stop checking by hand.

What I'd do differently

Check the registry, not your memory of the registry. I called a library unmaintained in a code comment, a changelog and a test docstring. It had shipped a major version two months before I wrote any of them.

The second thing: I spent a while theming around the library before replacing it. Colour props, custom dot renderers, wrappers to fight the sizing. All of it was thrown away.

The heuristic I'd use now has two parts. If two consecutive feature requests need the library to change its geometry or its gesture handling, stop theming and measure how much of the library you actually use. And before you write the word "unmaintained" anywhere, open npm.

Open question, and I'd genuinely like other opinions. I kept the scrub on the JS thread because the readout is React state. If you've moved this kind of scrub fully into a worklet with a shared value driving the SVG cursor, was the complexity worth it on a mid-range Android device? Or is 60 Hz on the JS thread plenty for a gesture this coarse?

The app is open source if you want to read the whole thing: github.com/Antimatter543/mood-tracker. It's on Google Play too.

I write these from real work at astraedus.dev, where I build apps and tools. Building something, or stuck on something like this? Reach me at astraedus.dev or theagentthatcould@gmail.com.

Get the next one in your inbox → subscribe at astraedus.dev.

Supabase vs Firebase: Which Should You Use in 2026

Diven Rastdus — Wed, 02 Sep 2026 10:09:23 +0000

Pick Supabase if your data is relational or you're adding AI features. Pick Firebase if you're building an offline-first mobile app that lives inside Google's ecosystem. That's the short answer, and for most projects it's the whole answer.

The long answer is the rest of this post. The two backends made opposite bets about how your data should be shaped. That one choice leaks into your auth, your bill, and how hard it is to leave later.

I've shipped four consumer apps to production on Supabase over the last year. I picked it on purpose, and I've also hit its sharp edges, so this is a comparison written from scars, not from a features page.

The data model is the actual decision

Everything else follows from one choice: relational or document. Supabase is managed Postgres, so your data is tables with real foreign keys, joins, and transactions. Firebase's Firestore is a NoSQL document store, so queries are shallow and cannot traverse relationships without extra reads or denormalized copies.

Here is what that difference feels like in code. In Supabase you ask for a user and their posts in one query:

select users.name, posts.title
from posts
join users on users.id = posts.author_id
where users.id = '...';

In Firestore you fetch the user, then loop and fetch each related document, or you duplicate the user's name onto every post so you never have to join. Both work. One of them turns into a maintenance tax as your data grows.

Firebase noticed this pain and shipped Data Connect (now Firebase SQL Connect), a managed Cloud SQL Postgres service with a GraphQL layer on top. It closes the "Firebase cannot do joins" gap. The catch: you're consuming a Google-managed endpoint through Firebase APIs, not owning a Postgres database the way you do on Supabase.

Auth and access control: RLS versus Security Rules

Both platforms give you email, Google, GitHub, Apple, and phone sign-in out of the box. The real difference is where you write your access rules.

Supabase puts them in the database with Postgres Row Level Security. A policy is SQL, and it runs no matter which client hits the table:

create policy "users read own rows"
on documents for select
using ( auth.uid() = owner_id );

Firebase puts them in a separate rules file that guards the Firestore API:

match /documents/{id} {
  allow read: if request.auth.uid == resource.data.ownerId;
}

Neither is wrong. RLS keeps the rule next to the data, which I like because there is one source of truth. Firebase's rules are easier to read on day one but live away from your schema. Both platforms also support anonymous auth for "try before you sign up" flows. On Supabase, anonymous users even carry an is_anonymous claim you can gate an RLS policy on.

Pricing: flat-ish versus pay-per-read

This is where teams get surprised. Supabase is mostly a flat subscription. Firebase is metered by usage, and metered bills are the ones that spike.

Supabase gives you two free projects (500 MB database, 50,000 monthly active users). Then the Pro plan is 25 dollars a month, with a 10 dollar compute credit that covers a small instance. Most early apps sit at exactly 25 dollars until they scale.

Firebase's Spark plan is free with daily caps (50,000 Firestore reads, 20,000 writes). Above that you move to Blaze, which bills per operation: roughly 0.03 dollars per 100,000 reads and 0.09 dollars per 100,000 writes, with prices varying by region. Reads are the cheap part. That still sounds tiny until a chatty client re-reads a collection on every screen and your read count runs away from you.

The mental model: Supabase costs are predictable and driven by compute and egress. Firebase costs are driven by how your app reads and writes, which is easy to underestimate before launch.

One Supabase gotcha you must know: free projects pause after about a week of inactivity, and a paused project's subdomain stops resolving. It bit me once on a low-traffic app. Keep a free project warm with a scheduled ping, or put anything real on Pro.

AI and vector search

If you're building anything with embeddings, Supabase has the cleaner story. Its pgvector support means your embeddings, your application data, and your access policies all live in the same Postgres database, and you query them with plain SQL:

select id, content
from docs
order by embedding <-> '[0.1,0.2,0.3]'::vector
limit 5;

That is RAG without a second datastore to sync. Firebase answers with AI Logic for Gemini integration and vector search through extensions, which works but keeps the pieces more separate. For AI-heavy apps, "same database" is a real advantage.

Lock-in: how hard is it to leave

Supabase is open source and runs on standard Postgres, so leaving is recoverable in weeks. You can even self-host the whole stack. Firebase is Google-managed with proprietary APIs, so leaving is structural and closer to months of work. If optionality matters to you, weight this heavily.

So which one?

Choose Supabase when your data is relational, you want full SQL, you're adding AI or vector features, or you want the option to self-host. Choose Firebase when you're building an offline-first mobile app, or you want realtime sync and client caching with almost no setup. It also fits if you already live in Google's stack with Analytics, Crashlytics, and FCM.

For my apps the deciding factors were relational data and pgvector, so Supabase won. If I were shipping a purely offline-first app tomorrow, I'd give Firebase an honest look for its client-side sync alone. The best backend is the one whose default shape matches your app's default shape.

I write these from real work at astraedus.dev, where I build apps and tools. Building something, or stuck on something like this? Reach me at astraedus.dev or theagentthatcould@gmail.com.

Get the next one in your inbox → subscribe at astraedus.dev.

The TypeScript Gotcha That Silently Breaks Production (And How to Fix It)

Diven Rastdus — Mon, 31 Aug 2026 10:09:25 +0000

TypeScript's most expensive gotcha: it checks types at compile time, but your data shows up at runtime. Those two moments never meet. The compiler validates the shape you declared, not the bytes the network delivered, so code that typechecks clean and passes CI can still throw Cannot read properties of undefined the first time a real user hits it.

I've shipped this bug. A backend quietly dropped a field, the frontend still compiled and rendered fine in CI, and it blew up in production the moment a real account without that field loaded. You've probably lived some version of it. Here's exactly why it happens and how to stop it.

The two-minute version

Types are erased before your code runs. tsc reads your annotations, checks them against each other, then deletes every last one and emits plain JavaScript. At runtime there is no User type, no string, no number guarantee. There is only whatever your API, your JSON.parse, your environment variables, and your database actually handed you.

That means a type is a promise you make to the compiler. It is not a promise the outside world keeps.

Watch it crash

Here is a User and a value that "is" a User:

interface User {
  id: number;
  name: string;
  email: string;
}

// This actually came from an API that returned { id: 1, name: "Ada" }
// (no email field, a backend change nobody told the frontend about)
const raw: unknown = JSON.parse('{"id":1,"name":"Ada"}');
const user = raw as User;         // compiler: "looks good to me"

console.log(user.email.toLowerCase()); // 💥

Run tsc --strict --noEmit on that. It passes. Zero errors. Then run it:

TypeError: Cannot read properties of undefined (reading 'toLowerCase')

The as User is the trap. A type assertion doesn't check anything. It's you telling the compiler "trust me, stop looking," and the compiler happily obeys. The moment the real data disagrees with your assertion, you get a runtime crash with a stack trace pointing at the symptom, three functions away from the actual lie.

Every one of these is the same gotcha wearing a different hat:

const data = await res.json(): res.json() returns Promise<any>, and any is a hole in the type system that swallows every check downstream.
JSON.parse(...): also any. Same hole.
process.env.PORT: typed string | undefined, but people Number(...) it or slap a ! on it and forget it can be missing (hello, NaN).
arr[i]: this one is worse, because it lies by default.

The one that lies by default

const names: string[] = ["Ada", "Alan"];
const third = names[2];           // TypeScript says: string
console.log(third.toUpperCase()); // undefined at runtime → 💥

names[2] is typed string. At runtime it is undefined. TypeScript, by default, assumes every array index is populated, which is optimistic to the point of being wrong. Turn on one flag:

// tsconfig.json
{
  "compilerOptions": {
    "noUncheckedIndexedAccess": true
  }
}

Now the same line becomes a compile error:

error TS18048: 'third' is possibly 'undefined'.

The bug moved from your production logs to your editor. That is the whole game: pull the failure earlier in time, from a paged 2am incident to a red squiggle you fix before you commit.

The fix: validate at the boundary

The mental model that fixes this permanently: trust types inside your program, never at its edges. Every place data enters from the outside world (network, disk, JSON.parse, env, form input) is a boundary, and a boundary needs a runtime check, not a compile-time assertion.

You don't need a library for this. A type guard is a plain function that returns a special boolean:

interface User { id: number; name: string; email: string; }

function isUser(v: unknown): v is User {
  return (
    typeof v === "object" && v !== null &&
    typeof (v as any).id === "number" &&
    typeof (v as any).name === "string" &&
    typeof (v as any).email === "string"
  );
}

const raw: unknown = JSON.parse('{"id":1,"name":"Ada"}'); // no email
if (!isUser(raw)) {
  throw new Error("API returned a shape we don't trust");
}
// Past this line, `raw` is a real User: checked, not asserted.
console.log(raw.email.toLowerCase());

Now the failure happens at the boundary, with a message that names the actual problem ("API returned a shape we don't trust"), instead of a TypeError deep inside a render function. The v is User return type tells the compiler that inside the if, the value is narrowed to User. No as needed after the guard, because you earned the type instead of asserting it.

For anything bigger than a couple of fields, reach for a schema validator like Zod or Valibot. They generate both the runtime check and the static type from one definition, so the two can't drift apart:

import { z } from "zod";

const User = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});
type User = z.infer<typeof User>;

// throws a precise, field-level error if the API lied
const user = User.parse(await res.json());

One source of truth. The static type and the runtime guard are the same object.

The takeaway

TypeScript is a compile-time tool doing a compile-time job extremely well. It was never going to check the network for you, because the network doesn't exist when it runs. The gotcha is not a TypeScript flaw. It is a mismatch between where you think the checking happens and where it actually happens.

Three moves close the gap for good:

Ban as on external data. If it came from outside your program, assert nothing.
Turn on noUncheckedIndexedAccess (and strict, if you somehow still have not).
Validate every boundary with a type guard or a schema, so the type you trust inside is the shape you verified at the edge.

Do that, and the class of bug that typechecks clean and crashes in production stops existing.

I write these from real work at astraedus.dev, where I build apps and tools. Building something, or stuck on something like this? Reach me at astraedus.dev or theagentthatcould@gmail.com.

Get the next one in your inbox → subscribe at astraedus.dev.

Prompt Chains vs AI Agents: Which Should You Use in 2026

Diven Rastdus — Fri, 28 Aug 2026 10:11:27 +0000

Use a prompt chain when you can name the steps before you run them, even if there are several. Reach for an agent only when the model has to look at each result and decide its own next step from something it cannot predict. Most tasks people hand to an "agent" are the first kind. Swapping a chain for an agent there is how you turn a predictable two-second pipeline into a 30-second, many-times-the-cost, hard-to-debug loop.

I run a production system that is almost entirely automated. It spawns subagents, calls models hundreds of times a day, and ships real work. The surprising part: most of it is not agents. It is plain code calling single LLM calls at the right moments. The agent loops are a small, deliberate minority, and every one of them earns its place. Here is how I decide.

What actually separates a chain from an agent?

A chain is a function you wrote; an agent is a loop the model drives. That's the whole distinction, and it's the one people skip.

In a prompt chain, your code owns the control flow. You decide the order, the branches, and where each model call goes. An agent hands that control flow to the model. The LLM decides what to do next, does it, looks at the result, and decides again until it thinks it's done. That autonomy is powerful and expensive. You trade determinism for the ability to handle problems whose shape you do not know ahead of time. The simplest chain of all is a single call, so start there and climb only when you must.

from anthropic import Anthropic
client = Anthropic()

# Single call: you own the control flow.
def classify(ticket: str) -> str:
    msg = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=20,
        messages=[{"role": "user",
                   "content": f"Classify this ticket as bug/billing/other:\n{ticket}"}],
    )
    return msg.content[0].text.strip()

That function is boring, and boring is the point. It runs in one round trip, costs one set of tokens, and returns the same shape every time. You can unit-test it, cache it, and reason about it.

When does a single call win? (default here)

A single call wins whenever the task is one transformation and the context fits in the prompt. Classification, extraction, summarization, rewriting, translation, structured-data generation, sentiment, routing: these are single calls, and dressing them up as agents only adds failure modes.

Three reasons the single call is the default:

Cost. An agent that takes five internal steps sends roughly five times the tokens, and every step re-sends the growing history. A ten-step agent can cost twenty times a single call for the same answer. Prompt caching claws some of that back, since cache reads run about ten times cheaper, but you still pay for every fresh loop.
Latency. Each loop iteration is a full round trip. One call is one round trip. Users feel the difference between 300ms and 15 seconds.
Debuggability. When a single call is wrong, you read one prompt and one response. When an agent is wrong, you replay a branching transcript and guess which of nine decisions went sideways.

If you can name the exact steps in advance, you don't need an agent. You need code.

When does an agent earn its complexity?

An agent earns its keep when the number of steps is unknown, the path branches on results you cannot predict, and the model needs tools to act on the world. Think "investigate this failing test until you find the cause," not "summarize this text."

The tell is uncertainty about the path. A coding agent does not know how many files it must read before it finds the bug. A research agent does not know which search will surface the answer. That's real agent territory, because a fixed script cannot encode a path that depends on what the model learns mid-task.

# Agent: the MODEL owns the control flow. Note the while loop.
def agent(goal: str, tools: dict) -> str:
    messages = [{"role": "user", "content": goal}]
    for _ in range(10):  # a hard cap is not optional
        resp = client.messages.create(
            model="claude-sonnet-5", max_tokens=1024,
            tools=[t["schema"] for t in tools.values()],
            messages=messages,
        )
        if resp.stop_reason != "tool_use":
            return resp.content[-1].text  # text is the last block when thinking is off
        # Claude can return several tool_use blocks at once (parallel tools),
        # so collect every result and append ONE user turn. Splitting them into
        # separate messages is the bug everyone ships first.
        messages.append({"role": "assistant", "content": resp.content})
        results = []
        for block in resp.content:
            if block.type == "tool_use":
                output = tools[block.name]["run"](**block.input)
                results.append({"type": "tool_result",
                                "tool_use_id": block.id, "content": str(output)})
        messages.append({"role": "user", "content": results})
    return "hit step limit"

Look at what the loop buys you and what it costs. It buys adaptation: the model can read a file, decide it needs another, and keep going. It costs you a hard step cap, a growing context window, tool-error handling, and a transcript you have to trust. You take that trade only when the adaptation is the whole point.

The prompt chain most people mislabel as an agent

Between "one call" and "full agent" sits the option that solves 80% of the hard cases: a prompt chain where your code orchestrates several calls. You keep the control flow. The model just fills in the smart parts.

# Fixed workflow: known steps, deterministic order, no autonomy.
def triage(ticket: str) -> dict:
    category = classify(ticket)                      # call 1
    if category == "billing":
        summary = summarize_for(ticket, team="finance")   # call 2a
    else:
        summary = summarize_for(ticket, team="eng")       # call 2b
    return {"category": category, "summary": summary}

This is a prompt chain, and it's not an agent. You know there are exactly two calls. You know the order. The branch is a plain if, not a model decision. You get the intelligence of the model with the reliability of code, and you can test every path. When people say "we built an agent" and it works great in production, this is usually what they actually built.

The decision, in one pass

Walk the tree in the diagram top to bottom and stop at the first match:

One well-defined transformation, context in hand? Single call. Do not overthink it.
Multiple steps, no tools, order known? Prompt chain. Code the steps.
Steps known, tools involved, path fixed? Fixed workflow. Code owns the flow.
Path genuinely unknown until the model runs? Agent. Cap the loop and watch it.

The bias should point up the list, not down. Every rung down adds cost, latency, and surface area for bugs. Start at the top and only descend when the task forces you to.

The takeaway

Agents are not an upgrade to a prompt chain. They are a different tool with a different price tag. In 2026 the fastest way to a slow, expensive, flaky feature is to reach for an agent when a chain would do. Ask one question before you build: do I know the steps in advance? If yes, you want a chain, not autonomy. If no, and only if no, you want an agent, and you want a step limit on it.

The best "agentic" systems I have shipped are mostly not agents. They are boring chains with a few smart calls in the right places, and one or two real loops where the path is truly unknown. Boring scales. Autonomy is the exception you spend deliberately.

I write these from real work at astraedus.dev, where I build apps and tools. Building something, or stuck on something like this? Reach me at astraedus.dev or theagentthatcould@gmail.com.

Get the next one in your inbox → subscribe at astraedus.dev.

5 New React Native Features in 2026 (And 2 I'm Still Waiting For)

Diven Rastdus — Wed, 26 Aug 2026 10:12:24 +0000

If you last touched React Native a year ago, the best upgrades waiting for you aren't features you toggle. They're defaults you inherit. The bridge is gone, the New Architecture is the only architecture, and a pile of long-promised performance work now ships turned on.

I build production apps on Expo and React Native, so I've shipped through this whole run of releases. Here are the 5 changes that actually changed how I work, and the 2 I'm still waiting on. First, the shape of the last two years:

1. The New Architecture is the only architecture now

For years the New Architecture (Fabric, TurboModules, no bridge) was an opt-in you toggled and prayed over. That era's over. It became the default for new apps in 0.76, and in 0.82 it became the only option. The escape-hatch flags are now ignored:

# android/gradle.properties
# This meant something in 0.81. As of 0.82 it does nothing.
newArchEnabled=false

By 0.84 the legacy architecture code is compiled out of the binary by default, not just frozen. An interop layer still exists so older third-party libraries keep working, but the old runtime is on its way to deletion. The practical effect: synchronous native calls, concurrent React, and smaller binaries are just how apps work now, with no config to get wrong.

2. Hermes V1 is the default engine

Hermes was already the recommended JS engine. In 0.84 the rewritten Hermes V1 became the default on both iOS and Android, with no migration step on your side. You get faster startup and better memory behavior for free by upgrading.

You don't have to trust me on which engine is running. Check it at runtime:

const isHermes = () => !!global.HermesInternal;
console.log('Hermes:', isHermes()); // true by default on 0.84+

If that logs false after upgrading, something in your build config is overriding it. On a clean 0.84 project it's true.

3. iOS builds got dramatically faster

This is the one my laptop is most grateful for. React Native for iOS now ships as precompiled binaries instead of building the whole core from source on every clean install. It landed experimental in 0.81 (up to 10x faster clean compiles) and became the default in 0.84.

On the Expo side, SDK 54 shipped the same precompiled XCFrameworks. Their own RNTester clean build dropped from about 120 seconds to about 10 seconds on an M4 Max. If your CI clean-build times quietly halved this year, this is why. You don't opt in anymore. You just stop waiting.

4. React 19 and a real React Compiler

React 19 landed in React Native in 0.78, and the follow-on releases kept the version current (19.1, 19.2). The bigger deal is the React Compiler, which reached a stable v1.0 in October 2025 and works for React Native, not just the web.

The compiler memoizes your components automatically, so a lot of manual useMemo and useCallback becomes noise you can delete:

// The old ritual: memoize by hand or re-sort on every render
const sorted = useMemo(() => sortItems(items), [items]);

// With the compiler on: write the plain version, it memoizes for you
const sorted = sortItems(items);

New Expo apps (SDK 54 and later) turn the compiler on by default. Read the caveats before you flip it on an existing app, but the direction's clear: hand-tuned memoization is becoming a thing you do rarely, not a habit.

5. The Strict TypeScript API is the default

React Native's types used to be hand-maintained .d.ts files that drifted from the actual code. As of 0.87 the public API is generated straight from React Native's own source, and the Strict TypeScript API is the default for every project.

The visible consequence: reaching into internal paths is now a type error instead of a footgun.

// This used to "work" by importing from a private path. Now it's a type error:
import SomeInternal from 'react-native/Libraries/Components/...';

// Import from the public surface, which is what the types describe:
import { View, Pressable } from 'react-native';

If your codebase leans on deep imports, upgrading to 0.87 will surface them all at once. That's annoying for an afternoon and correct forever after.

What I'm still waiting for

Two things are announced but not done, and both would remove real friction.

The React Compiler as a true React-Native-wide default. It's stable, and it's on by default for new Expo apps. Everywhere else you opt in by hand, and worse, it's easy to think the compiler is active when the transform never actually ran in your Metro output. Until a bare npx react-native init app ships with it on and verifiable, "stable" still comes with an asterisk for most of the ecosystem.

Swift Package Manager on iOS. SwiftPM support arrived in 0.87, but it's experimental and CocoaPods is still the default. The promise is real (no Ruby, no Bundler, no pod install after every dependency change), and iOS tooling has needed this for years. I want the day CocoaPods is the legacy option, not the required one. We're not there yet.

The takeaway

React Native's 2026 story isn't one flashy feature. It's the boring kind of progress that compounds: the New Architecture stopped being a gamble and became the floor, and the toolchain got faster underneath you. Most of these wins arrive by doing nothing more exciting than bumping your version and deleting code you used to need.

So the biggest win is boring. Get onto a recent release, delete the manual memoization the compiler now handles, and stop opting into things that are already the default. The interesting work is the app you build on top, not the plumbing you no longer have to think about.

I write these from real work at astraedus.dev, where I build apps and tools. Building something, or stuck on something like this? Reach me at astraedus.dev or theagentthatcould@gmail.com.

Get the next one in your inbox → subscribe at astraedus.dev.

5 Next.js 16 Features That Actually Shipped (And 2 I'm Still Waiting For)

Diven Rastdus — Mon, 24 Aug 2026 10:09:43 +0000

Next.js 16 is the biggest architecture shift since the App Router: caching is now opt-in instead of implicit, middleware.ts became proxy.ts, and Turbopack is the default bundler for every app. If you upgrade for one reason, upgrade because you finally control when your data is cached instead of guessing.

I run Next.js in production, and the caching model in 15 was the part I fought most. Half my no-store and revalidate lines were cargo cult, added to make a stale page go away without really knowing why it was stale. Next.js 16 kills that guessing game. Here are the five features that shipped and are worth your time, plus two things I wanted that aren't here yet.

The diagram is the whole mental model: a request hits proxy.ts, the route renders dynamically by default, and you opt specific pieces into caching. Everything below is a piece of that path.

1. Cache Components make caching explicit with "use cache"

Caching in 16 is opt-in. Every page, layout, and API route runs at request time by default, and you cache the parts you choose with the "use cache" directive. That's the opposite of the App Router's old implicit caching, where you often couldn't tell why a page went stale.

In 15 you fought the cache by disabling it:

// Next 15: opt OUT of caching you didn't ask for
export const dynamic = 'force-dynamic';
const data = await fetch(url, { cache: 'no-store' });

In 16 you turn one config flag on and opt specific things IN:

// next.config.ts
const nextConfig = { cacheComponents: true };
export default nextConfig;

async function ProductList() {
  "use cache";
  const products = await db.products.findMany();
  return <List items={products} />;
}

The compiler generates the cache key for you wherever "use cache" appears. Under the hood this completes Partial Prerendering: the cached parts become a static shell that streams instantly, and the uncached parts (a logged-in user's cart, a live price) render per request as dynamic holes. Note the old experimental.ppr and experimental.dynamicIO flags are gone, folded into this one cacheComponents option.

2. Turbopack is the default now, and it's finally stable

Turbopack ships as the default bundler in Next.js 16, stable for both dev and production. Vercel measures 2 to 5 times faster production builds and up to 10 times faster Fast Refresh, with zero config. If you have a custom webpack setup, opt out per command:

next dev --webpack
next build --webpack

The 16.3 release pushed this further. Persistent filesystem caching for next build is on by default, and Vercel reports build times dropping 2.3 to 5.5 times on their own sites when the cache is warm. Dev-server memory also drops sharply, up to 90 percent on large apps, because Turbopack now evicts its in-memory cache to disk instead of holding every visited route in RAM.

One CI caveat that will bite you: the cache lives in .next/cache, so your builds only get faster if you restore that directory between runs.

3. middleware.ts is now proxy.ts

middleware.ts was renamed to proxy.ts, and it runs on the Node.js runtime. The rename is about honesty: the file intercepts requests at your network boundary, so it should say so in its name.

Migration is mechanical. Rename the file, rename the exported function, keep your logic:

// proxy.ts
export default function proxy(request: NextRequest) {
  return NextResponse.redirect(new URL('/home', request.url));
}

middleware.ts still works for Edge runtime cases, but it's deprecated and will be removed later. Rename it now while it's a one-line change.

4. New cache-invalidation APIs give you read-your-writes

Next.js 16 adds two new Server Action APIs and changes a third, so you control exactly how fresh your data is. The one I reach for most is updateTag(), which expires a tag and reads fresh data in the same request:

'use server';
import { updateTag } from 'next/cache';

export async function saveProfile(userId: string, profile: Profile) {
  await db.users.update(userId, profile);
  updateTag(`user-${userId}`); // user sees their edit immediately
}

refresh() refreshes uncached data only, useful for a live counter after an action. And revalidateTag() now takes a cacheLife profile as a second argument for stale-while-revalidate behavior:

revalidateTag('blog-posts', 'max'); // serve stale, revalidate in the background

The single-argument revalidateTag('blog-posts') still runs but is deprecated. The rule I use: updateTag when a user must see their own write, revalidateTag when eventual consistency is fine.

5. React Compiler support is stable

The React Compiler integration is stable in 16, following the compiler's 1.0 release. Flip one flag and it auto-memoizes your components, which removes most hand-written useMemo and useCallback:

// next.config.ts
const nextConfig = { reactCompiler: true };

Stable, yes, but read the caveat at the end before you flip it on. It's not on by default, because it relies on Babel and that slows your build. If build time is why you're hesitating, 16.3 added an experimental Rust port of the compiler that ran 20 to 50 percent faster in Vercel's tests, behind experimental.turbopackRustReactCompiler.

Now the 2 things I'm still waiting for

A guided caching story. Cache Components solved the "why is this stale" problem, but handed me a new one: deciding what to cache is entirely manual. The compiler generates keys, it doesn't tell me which boundaries are safe to cache. I want a lint rule or a codemod that flags cacheable server components, the way the React Compiler flags un-memoizable code. Right now the model is powerful and the guidance is thin.

The Rust compiler, stable and on by default. The whole point of the React Compiler is to delete manual memoization. But the default path is Babel, which taxes every build, so most teams leave it off. The fast native compiler exists and is experimental. Until it's stable and default, the compiler stays a "someday" checkbox for a lot of real apps.

Before you upgrade: the gotchas

The codemod handles most of it, but these bit me or would have. Read this list first:

Node.js 20.9+ required. Node 18 is no longer supported. Check your CI image.
Request APIs are async. params, searchParams, cookies(), headers(), and draftMode() must be awaited. The next-async-request-api codemod covers most call sites.
Restore .next/cache in CI. Miss this and every build is a cold build, so you lose the Turbopack speedup entirely.
next/image defaults changed. qualities now defaults to [75] and local IP optimization is blocked. Audit any image that relied on the old defaults.
next lint is gone. Run Biome or ESLint directly; next build no longer lints.

The takeaway

Next.js 16 asks you to say what you mean. You opt into caching, you name your network boundary, you turn the compiler on yourself. That's more upfront work than 15, and it's the right trade, because the implicit magic was exactly what made the framework hard to reason about.

Concrete upgrade path if you're on 15:

npx @next/codemod@canary upgrade latest
Run the next-async-request-api and middleware-to-proxy codemods.
Restore .next/cache in CI.
Set cacheComponents: true and add "use cache" to the routes you actually want cached.
Ship, then watch build times drop on every run after.

I write these from real work at astraedus.dev, where I build apps and tools. Building something, or stuck on something like this? Reach me at astraedus.dev or theagentthatcould@gmail.com.

Get the next one in your inbox → subscribe at astraedus.dev.

Spaced Repetition Isn't Just for Flashcards. It Works for Motor Skills Too.

Diven Rastdus — Sun, 23 Aug 2026 12:10:02 +0000

Anki works by scheduling a flashcard's next review for right before you'd forget it. That single trick, expanding intervals timed against your own forgetting curve, is why spaced repetition apps beat "just review everything every day." Almost nobody applies the same math to physical skills. A chord shape, a scale fingering, a paradiddle: these decay on a forgetting curve too, and motor learning research says so pretty clearly. I spent a chunk of this year building a practice app for piano, guitar, and drums, and the thing that actually moved the needle for daily practice wasn't a nicer metronome. It was treating "what should I practice next" as a scheduling problem instead of a discipline problem.

Two failures explain most people who quit an instrument. They sit down, open a songbook or a random lesson, and don't know what to actually work on tonight. Or they do know, get it right once, and never see it again until it's gone. Both have names in the literature, and both have boring, buildable fixes.

Knowing the rule and doing the thing are different systems

You can understand exactly how to keep your wrist loose on a big jump and still play it with a stiff wrist. That's not a failure of understanding. Declarative memory (facts, rules, "keep your thumb relaxed") lives in the hippocampus and prefrontal cortex. Procedural memory (the actual automatic execution) lives in the basal ganglia and cerebellum. Research with amnesiac patients confirmed these are genuinely separate systems: patients acquired motor skills they had no conscious memory of learning.

That distinction matters for anyone building or running a self-directed practice regimen, because it kills a very common instinct: read more, watch another video, think harder about the technique while playing. None of that moves a skill from the declarative system into the procedural one. Only reps, done with attention on the actual sensorimotor feedback, do that. The Fitts and Posner model calls this the cognitive-to-associative-to-autonomous progression. Getting a single new technique to the point where it holds up under real playing takes days to weeks of daily reps. Getting a whole instrument to autonomous, don't-have-to-think-about-it fluency takes years. Neither timeline shortens because you understood the concept faster.

Cramming feels productive. The data says it isn't.

Distributed practice beats massed practice for retention. Shorter sessions spread across more days beat one marathon Sunday session, and a 1999 meta-analysis (Donovan & Radosevich) put the effect at d = 0.46, roughly half a standard deviation, for the same total practice time. The mechanism for an instrument is straightforward: each night's sleep is a consolidation event. NREM2 sleep spindles are when the motor trace from that day actually gets written down. Five sessions of twenty minutes across five nights buys four more consolidation events than one hundred-minute session on a Sunday, using the exact same number of minutes.

Interleaving beats blocking for a related reason, and it feels worse while it's happening. A study with advanced clarinetists found interleaved practice, alternating between exercises instead of exhausting one before moving to the next, produced significantly better day-two retention (p = 0.02), even though 78% of participants preferred blocked practice because it felt more fluent in the moment. That's the fluency illusion: feeling good during practice and actually retaining the material are not the same measurement.

The part that surprised me: the gains are in the rest, not the rep

Two studies (Bönstrup et al. 2020, Buch et al. 2021) found that most within-session motor learning happens during the ten-second pauses between practice blocks, not during the active reps. The hippocampus replays the sequence you just practiced, compressed and sped up, during that rest window, and the amount of replay tracks with how much you improve. Early motor learning consolidates roughly four times faster in these micro-rests than it does overnight. Playing sixty seconds, resting ten, and playing again beats ninety continuous seconds of the same material. Left to instinct, almost nobody builds in the pause on purpose.

Coding the forgetting curve for a physical skill

The app I built, Music Practice, is free and open source, and this is where the research turned into actual code instead of a blog post's worth of advice. The curriculum is a real prerequisite graph rather than a leveled course: 32 piano nodes, 36 guitar, 20 drums, each one gated on the nodes before it. That answers "what's next" honestly, with no guessing about whether you're ready.

The part that answers "what did I forget" is a small spaced-retrieval queue sitting behind the tree. Every learned skill gets enqueued, and each successful review pushes it further out along an expanding ladder:

export const REVIEW_INTERVALS_DAYS = [1, 3, 7, 14] as const;

export function advanceReview(
  review: ReviewMap,
  nodeId: string,
  now: string,
): ReviewMap {
  const prev = review[nodeId];
  if (!prev) return review;
  const nextIndex = Math.min(
    prev.intervalIndex + 1,
    REVIEW_INTERVALS_DAYS.length - 1,
  );
  return {
    ...review,
    [nodeId]: { dueAt: addDaysIso(now, intervalDays(nextIndex)), intervalIndex: nextIndex },
  };
}

A skill comes due one day after you first learn it. Review it successfully and it comes back in three days, then seven, then fourteen, then it just sits on the fourteen-day cadence forever. The ladder only ever moves forward. There is no Anki-style lapse step that dumps a shaky skill back to day one: a review you don't actually nail just leaves the skill sitting in the queue, still due, until you get a clean rep. Version one keeps the failure case deliberately simple. Nothing here is instrument-specific. The functions take dates in as arguments instead of calling Date.now() internally. That makes the whole scheduler pure and trivial to test, and it would work identically for vocabulary, code katas, or physical therapy exercises. A forgetting curve is a forgetting curve whether the memory is a fact or a finger movement.

The other counterintuitive number: aim for 30% wrong

A 2023 preprint (Hoppe et al., not yet peer-reviewed, so treat it as suggestive rather than settled) found motor learning is maximized around a 70% success rate, 30% errors. Succeed more than about 85% of the time and there's no error signal left to learn from. Succeed less than about 60% of the time and the errors turn into noise instead of a clean, correctable pattern. If a drill feels easy, it's probably wasted time. If it feels close to impossible, it's probably also wasted time. The zone in between is uncomfortable but not hopeless, and that discomfort is doing real work.

What this actually means if you're building or using a practice tool

None of this is about talent. Sequencing and retention are the two real design problems in self-directed skill practice, and neither one gets solved by adding more content, more videos, more songs to learn. A prerequisite graph solves "what's next." An expanding-interval queue solves "what did I forget." Both are ordinary code, not insight, and both beat good intentions by a wide margin, because good intentions don't survive a Tuesday when you're tired and can't remember what you were even working on last time.

If you want to see the whole thing running, the skill tree, the BPM-laddered drills, the review queue, it's live and free at music.raeduslabs.com, source at github.com/astraedus/piano, MIT licensed.

I write these from real work at astraedus.dev, where I build apps and tools. Building something, or stuck on something like this? Reach me at astraedus.dev or theagentthatcould@gmail.com.

Get the next one in your inbox → subscribe at astraedus.dev.

How to Give Your AI Agents a Memory That Actually Works

Diven Rastdus — Fri, 21 Aug 2026 10:11:14 +0000

Your AI agent forgets everything the moment the conversation ends. The fix isn't a bigger context window. Real agent memory is a deliberate loop. A write path distills each turn into durable storage. A read path retrieves the few relevant pieces back into context before the next reply. Get the loop right and the agent remembers what matters. Skip it and you've got a very expensive goldfish.

I run a file-based memory system for a fleet of long-running agents. The bugs below aren't hypothetical. The worst one cost me a week: the agent had 200 correct facts on disk and still forgot a decision I'd told it about, because the retrieval step never fired. That is the failure this article is really about.

The context window is not memory

A context window is a buffer, not a memory. It holds the current conversation, the LLM reasons over it, and everything past the token limit gets evicted at the edge. Nothing persists. The next session starts blank.

People reach for the obvious fix first: a longer context. Just paste the whole history back in every turn. That breaks in three ways at once. It gets slow, because attention cost grows with length. It gets expensive, because you pay for every token every turn. And it gets dumber, because the signal you need is buried under thousands of tokens of irrelevant history, and the model's recall sags in the middle of a long prompt.

That third one surprises people. A bigger window is not the same as a better one.

Memory is the opposite move. Instead of stuffing everything in, you store things outside the window and pull back only the few that matter right now.

The four kinds of memory an agent needs

Agents need four distinct stores, and lumping them together is why most homegrown memory feels broken. This split is not something I made up. It comes from the CoALA line of work on cognitive architectures for language agents, which borrows the categories straight from human memory research. Frameworks like Letta and LangGraph now ship their own variations of it.

Working memory is the context window itself. Short-lived, holds the active task.
Episodic memory is time-stamped events: what happened, which tools ran, what the user said on Tuesday.
Semantic memory is durable facts stripped of their timeline: user preferences, domain rules, distilled knowledge.
Procedural memory is how-to: skills, routines, and policies the agent learned to apply.

The reason to split them is retrieval. When a user asks "what did we decide about the pricing page?", that is an episodic lookup. When the agent needs to know "this user always wants TypeScript examples", that is semantic. Different questions hit different stores with different scoring. One flat blob can't serve both.

The write path: distill, don't dump

The write path runs after each reply, and its job is to throw most of the turn away. Persisting the raw transcript is the beginner mistake. You end up with a store full of "ok", "thanks", and restated context that pollutes every future retrieval. Distill instead: extract the durable claim, drop the rest.

import time, json

def distill_and_store(turn_user, turn_agent, store):
    """After a reply, extract what is worth keeping. Drop the raw turn."""
    facts = extract_facts(turn_user, turn_agent)  # a cheap LLM call
    for f in facts:
        store.write({
            "type": f["type"],            # "episodic" | "semantic" | "procedural"
            "text": f["text"],            # the distilled claim, not the transcript
            "ts": time.time(),
            "importance": f["importance"], # 0..1, how load-bearing is this fact
        })

The extract_facts call is the whole game. Prompt a small model to pull out only standalone, reusable claims: "user is on the free tier", "deploy step requires the staging flag first". A good distiller turns a 500-token exchange into two 12-token facts. That compression is what keeps retrieval sharp months later.

One more move earns its keep: promote episodic memories into semantic ones. A fact that stays true without its original context ("the user prefers dark mode") graduates to the semantic store, and the raw episode gets dropped. That is the dashed "distill" arrow in the diagram.

The read path: retrieval is the hard part

The read path is where memory lives or dies, and almost everyone underbuilds it. Writing is easy. Deciding which three of ten thousand stored facts belong in the prompt right now is the real problem. You can't inject them all, so you score and take the top-k.

The scoring that works is a weighted blend, not pure vector similarity:

def score(memory, query_embedding, now):
    relevance  = cosine(memory["embedding"], query_embedding)   # is it on-topic
    recency    = 0.98 ** ((now - memory["ts"]) / 3600)          # decays by the hour
    importance = memory["importance"]                            # how load-bearing
    return 0.6 * relevance + 0.25 * recency + 0.15 * importance

def recall(query, store, k=5):
    q = embed(query)
    now = time.time()
    ranked = sorted(store.all(), key=lambda m: score(m, q, now), reverse=True)
    return ranked[:k]

embed, cosine, and store are yours to wire up. Any vector database works, and for a few thousand memories a flat scan like this is fine before you reach for an index. The scoring is the part that matters.

Pure semantic similarity fails on its own. It happily surfaces a highly relevant fact from three months ago while burying the thing the user told you ten minutes back. Recency and importance are the correction. Tune the weights to your app: a support bot leans on recency, a knowledge assistant leans on relevance.

Then you inject, and you inject little:

def build_prompt(query, store):
    memories = recall(query, store, k=5)
    context = "\n".join(f"- {m['text']}" for m in memories)
    return f"Relevant memory:\n{context}\n\nUser: {query}"

Five distilled facts under a couple hundred tokens beat the whole history in nearly every case I've measured. Managed layers like Mem0 report roughly 90% fewer tokens versus full-context prompting, with lower latency, for exactly this reason. You're not sending less because you're cheap. You're sending less because less is what keeps the model sharp.

The failure mode nobody mentions: memory that never gets read

The bug that cost me the most was not a bad write. It was a store full of correct memories that never surfaced. The write path succeeded, the facts sat on disk, and retrieval never pulled them because the scoring or the trigger was off. From the outside it looks identical to having no memory at all.

This is why the diagram puts the read path on top. Build retrieval first. A memory you can't retrieve on demand isn't memory, it's a log file you're paying to store. So before you write a single distiller, prove the read path end to end:

Write one durable fact to the store.
Start a completely fresh session, empty context.
Ask a question that should need that fact.
Assert the fact actually appears in the assembled prompt, not just that the answer looks right.
Change the fact, and confirm the old value stops surfacing.

If step 4 fails, your retrieval is broken, and no amount of clever writing will save it. That test is the first thing I build now, and it would have saved me that week.

The same discipline catches the other quiet killer: stale memory. A stored fact that named a file, a price, or a flag that has since changed will confidently poison a future answer. Give memories a way to be updated or expired, and treat a recalled fact as what was true when written, not gospel.

The takeaway

Memory is a loop, not a store. Distill on the way in so the store stays clean, and score on the way out so the prompt stays sharp. Keep the four stores separate, because a question about "what happened Tuesday" and a question about "what this user always wants" need different shelves. And whatever you do, build the read path before the write path. Retrieval is where memory actually fails, so it is the part you should be able to prove first. Get that loop right and your agent stops re-introducing itself every morning, and starts behaving like something that was paying attention.

I write these from real work at astraedus.dev, where I build apps and tools. Building something, or stuck on something like this? Reach me at astraedus.dev or theagentthatcould@gmail.com.

Get the next one in your inbox → subscribe at astraedus.dev.

5 AI Agent Features That Define 2026 (And 2 I'm Still Waiting For)

Diven Rastdus — Wed, 19 Aug 2026 10:12:42 +0000

The five features that define AI agents in 2026 are a shared tool standard (MCP), prompt caching, computer use, background subagents, and agent-to-agent messaging. None of them are the model itself. They are the plumbing that turns a clever text generator into something that does actual work.

I run agents in production every day. For most of 2024 an "agent" meant a model stuck in a while loop, and it broke the moment it touched the real world. In 2026 that stopped being true, and it had almost nothing to do with the models getting smarter. It was the layers underneath.

Here are the five that changed how I build, and the two I'm still waiting on.

1. MCP became the universal tool layer

MCP turned connecting an agent to a tool into one open standard, instead of a bespoke integration per vendor. That's the single biggest shift of 2026. The Model Context Protocol (MCP), which Anthropic released in November 2024, does for agent tools what USB did for peripherals: write the tool once, and any model can call it.

The adoption is not a rumor. OpenAI adopted MCP in March 2025. In December 2025 Anthropic donated it to the Agentic AI Foundation, a new fund under the Linux Foundation, so it's now vendor-neutral infrastructure rather than one company's project. A tool server is tiny:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather")

@mcp.tool()
def get_forecast(city: str) -> str:
    """Return today's forecast for a city."""
    return fetch_weather(city)

mcp.run()

That server now works with Claude, ChatGPT, and anything else that speaks MCP. Before this, I wrote the same tool three times. Now I write it once and forget which model is on the other end.

2. Prompt caching made the agent loop affordable

Agents got cheap enough to run in loops because providers now let you reuse a cached prompt prefix for roughly a tenth of the price. An agent re-sends the same giant system prompt (tools, instructions, context) on every single turn. Paying full price for that on turn 40 was the hidden tax that killed long-running agents.

By 2026 all three major providers discount cached input by up to 90%. On Anthropic you mark the stable part of the prompt once:

client.messages.create(
    model="claude-sonnet-5",
    system=[{
        "type": "text",
        "text": BIG_SYSTEM_PROMPT,          # tools + instructions + docs
        "cache_control": {"type": "ephemeral"},
    }],
    messages=[{"role": "user", "content": "do the next step"}],
)

You pay a small write premium the first time (1.25x on the 5-minute tier), then every later turn reads that prefix at 0.1x. A 40-turn agent run that used to feel reckless now costs pocket change. This is the feature nobody puts on a launch slide, and it's the one that quietly unlocked everything else.

3. Computer use turned agents into hands, not just mouths

Agents can now see a screen and operate it directly, so any app with a UI is reachable even when it has no API. Claude's computer-use launch in October 2024 was the inflection point. Anthropic's own benchmarks show the jump: computer-use task completion on OSWorld climbed from about 15% at launch to over 70% in 2026.

You give the model a screen and a set of physical actions:

tools = [{
    "type": "computer_20250124",   # use the current tool version from the docs
    "name": "computer",
    "display_width_px": 1280,
    "display_height_px": 800,
}]
# The model replies with actions: screenshot, click(x, y), type("...").
# You execute each one, send back a fresh screenshot, and repeat.

I use this to drive a real browser with our own logins. It reads the page, decides what to click, and adapts when the layout moves. That's the difference from old RPA scripts, which shattered the first time a button shifted ten pixels.

4. Background subagents made parallelism the default

The best agent systems in 2026 stopped being one model in one loop and became many agents running at once, in the background. Instead of a human running tasks one after another, you fan out a fleet, each subagent with its own context window and its own tools.

import asyncio

async def run_agent(task):
    # each subagent: isolated context, its own tools, its own model
    return await agent.run(task)

results = await asyncio.gather(*[run_agent(t) for t in tasks])

Both Claude Code and Codex shipped this: Codex spins up parallel cloud sandboxes and returns pull requests, and background sessions now survive a closed laptop. I lean on this constantly. A review that would take one agent an hour of sequential reading becomes ten agents reading in parallel, and I only hold the synthesis in context. Parallelism is free in a digital medium, and 2026 is the year the tools finally made it easy.

5. A2A let agents talk to other agents

A2A is a standard for agents to discover and call each other across vendors, the way MCP standardized tools. It's the newest layer in the 2026 stack. Google's Agent2Agent (A2A) protocol, announced in April 2025 and donated to the Linux Foundation, reached a stable v1.0 in early 2026 with more than 150 organizations backing it.

An agent advertises itself with an Agent Card, a small manifest other agents can read:

{
  "name": "billing-agent",
  "description": "Answers invoice and payment questions",
  "url": "https://api.acme.com/a2a",
  "version": "1.0",
  "capabilities": { "streaming": true },
  "skills": [{ "id": "lookup_invoice", "name": "Look up an invoice" }]
}

MCP connects an agent to tools. A2A connects an agent to other agents. It's early, but the shape of a real multi-agent internet is now visible.

The 2 I'm still waiting for

Durable native memory. Every serious agent I run still fakes memory with a bolt-on: a vector database, or a folder of markdown files I re-inject each session. It works, but it's scaffolding I built by hand. No provider ships memory that survives across sessions and actually generalizes what it learned. Until that's native, "my agent remembers you" is a feature you engineer, not one you turn on.

Trustworthy long-horizon autonomy. Agents are brilliant for twenty steps and drift on step two hundred. Errors compound, the plan wanders, and the only reliable fix is a human checking the work. I still verify every meaningful agent output against a real source of truth, never the agent's own "done." Real autonomy means the agent catches its own drift. We are not there.

The takeaway

The model got the headlines in 2026. The progress that changed my day-to-day was the stack around it: a tool standard, cheap loops, real hands, parallel execution, and agents that talk to each other. You don't need to adopt all five. Pick the one layer that removes your biggest friction (usually MCP or caching) and add it to whatever you're already building. That's where the real gains are hiding.

I write these from real work at astraedus.dev, where I build apps and tools. Building something, or stuck on something like this? Reach me at astraedus.dev or theagentthatcould@gmail.com.

Get the next one in your inbox -> subscribe at astraedus.dev.