Agents
-
When I Use a Subagent and When I Don't
Give a good harness access to subagents and everything starts looking like a team project.
You’ve got one agent working with the database layer. Another can research the API. Another can write the tests. Another can check the work. Another can manage moving the data. As work starts happening in parallel, colored dots appear, and the whole thing starts looking like an org chart.
That sounds like fun to me, but it can also be a mess.
Having more agents doesn’t automatically produce better results.
Sometimes they duplicate work. Sometimes they edit files at the same time, producing unexpected changes or behavior.
I mean, I still use subagents constantly. They are definitely the default.
Sometimes we need, like, a subagent arena. Two agents enter. One survives.
The Subagent Context Boundary
I started using subagents as a way to protect the main context window. I wrote about that back in March: the delegated agent can read files, inspect logs, and grind through intermediate reasoning in its own context.
It’s still one of the best reasons to delegate. When finding the right answer means searching through 20 files, reading five of them, tracing a configuration value, and checking the tests, that sounds like a subagent task to me.
The search is noisy, and the output needs to be compact.
Using subagents keeps the main context window free for the larger task.
I Delegate Bounded, Independent Work
The tasks I delegate have one thing in common: I can define the output before the work begins.
Here are some areas where a subagent makes sense:
- Repository research.
- A separate implementation surface.
- Specialist review.
- Independent verification.
- Real parallel work.
Don’t Delegate an Unclear Problem
Delegation is not a substitute for deciding what the work is.
If a request is vague, spawning more agents isn’t going to help with the vagueness. It’s just more output with no clear direction. The parent still needs to choose the requirement and figure out what we’re building.
Before I delegate, I want to handle the following in the parent context:
- what question the subagent is answering,
- which files or systems it owns,
- whether it may edit anything,
- what constraints it must preserve,
- what evidence it should return,
- when it should stop and ask instead of guessing.
If we can’t figure out answers to those, the next step should be planning, not delegation.
Don’t Split Tightly Coupled Work
Avoid having two agents edit code in neighboring areas. The code may share an interface, a fixture, or a schema, and if you start changing things in multiple places without coordination, you’re going to have problems.
Each agent has its own context window. When it reads a file, block of code, or dependency into that window, the context is only current at that moment. If another agent changes the same thing, how does the first agent know its context needs to be updated?
It’s a complicated problem, for sure.
So your best bet is to avoid parallel edits where agents are working in the same or similar areas of the code. The agent work areas need to be distinct.
If humans can have coordination problems, agents can too.
I Don’t Delegate Five Minutes of Work
Delegation has a cost. The parent needs to describe the task and load enough context for the subagent to do the work and summarize it. Then the parent needs to verify the result. All of that burns a bunch of tokens. Obviously, for one-line changes or small amounts of text, this handoff should never happen in the first place. To decide whether to pass the work to a subagent, ask: will using a subagent substantially improve the output?
Sometimes the answer is just to do it in the parent context window, even if that means you have to compact sooner.
A good subagent task looks a lot like a good software interface. It has a narrow purpose, explicit inputs, clear permissions, and predictable output.
Compare these two assignments:
Look into the tests and fix anything missing.Review the unchanged-record tests for Book. Identify provider-owned fields that are not covered. Add focused tests only in tests/test_books_client.py. Do not change production code. Run the focused test file and report the result.The first transfers uncertainty. The second transfers work.
The difference does matter.
The Parent Still Owns the Result
Subagents report completion. They don’t make completion true.
The parent still has to inspect the changes, reconcile conflicting findings, run the combined quality gate, and decide whether the original requirement was satisfied. If three agents each report that their piece passes, you have three pieces of evidence. You don’t yet know whether the assembled system works.
Delegation changes who gathers the evidence. It doesn’t remove the need to judge it.
The goal isn’t keeping every agent busy. The goal is finishing the work without turning yourself into middle management for robots.
Oh God, I think that’s my job title.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
Where Should This Agent Knowledge Live?
Every agent has a junk drawer.
It usually starts with project instructions. Then I added build commands, personal preferences, database warnings, old architecture decisions, and things to fix later.
The agent could see everything if I wanted it to, but then it would have to read a small novel before touching the code, recurring workflows were buried between random facts, and completed work kept hanging around like it was still relevant. I had given the agent more context and somehow made it less informed.
The problem was not missing knowledge. The problem was putting every kind of knowledge in the same place. An instruction, a skill, a memory, and an issue can all be written in Markdown.
They do four completely different jobs.
Four Places, Four Jobs
A clean version looks like this:
What the agent needs Where it belongs A rule that must apply during every relevant session Instructions A reusable procedure for a particular kind of work Skill A durable fact that may become relevant later Memory A commitment that remains open until completed Issue tracker In practice, this is messier than a table… That’s where the engineering and attention to detail really matter.
So the useful questions are Does the agent need to know about this? and What bucket does this knowledge belong in?
Instructions Are Guaranteed and Expensive
Project instruction files are the things your agent loads automatically. Depending on the tool, that might be
AGENTS.md,CLAUDE.md, or another repository-level file.This is your guaranteed layer. The agent (or harness) doesn’t have to remember to search for it. If a session starts in the project, the rules are sitting in context.
Use that guarantee for knowledge that must shape nearly every relevant action:
- the preferred package manager and command runner,
- where the main source and tests live,
- dangerous commands that require explicit approval,
- the authoritative source for important data,
- mandatory validation before work counts as complete,
- a pointer telling the agent when to load a skill or recall a memory.
The guarantees come with a cost. Every line added to the context is loaded on every session, even when all you really need is a lightweight session where that context doesn’t matter.
Be diligent about cleaning up and maintaining your guaranteed context window, especially if you don’t have a memory layer in place.
Skills Are Procedures With Judgment
A skill answers a different question: how should the agent perform this kind of work?
Publishing a blog post, reviewing a pull request, applying a database migration, preparing a release, updating dependencies. Those are workflows. They have an entry condition, a sequence, safety rules, and a way to verify the result. That’s more than a fact. It’s operational judgment packaged for reuse.
Before we had skills, we had playbooks. Now we can make playbooks out of anything.
A good skill tells the agent when the workflow applies, what to inspect before acting, which steps and tools are appropriate, what must never happen silently, and what evidence proves the work succeeded.
Maybe the deployment instructions can now stay short; when doing a deployment, load the deployment skill.
Instructions are guaranteed. Skills are conditional.
Memory Is Context, Not Policy
Memory is where durable facts live without being injected into every session.
I prefer pnpm for JavaScript and most TypeScript projects. I prefer uv, and sometimes Poetry, for Python. These are facts that shouldn’t have to be repeated.
What about that time you had to troubleshoot an integration and observed some strange behavior? What about when you changed the database design and it broke the support layer? None of this deserves to be injected into every prompt, but it deserves a place where the details can be accessed later.
A semantic memory system can store and retrieve the relevant durable facts and give them to the agent when it asks. I described this earlier.
Memory can be large, and it can be flexible. But it’s also not guaranteed. The agent might not use the right keyword. You might have a problem with the vendor. A critical dependency could go down and take the memory system offline.
Don’t put safety-critical policies in memory. It’s good to have backups. If preferences get lost, they can be recreated, but absolutes like never print secret values belong in several places. If it has anything to do with security, cover your ass.
Memory is best for facts, preferences, relationships, explanations, and past decisions.
Issues Are Promises, Not Storage
An issue tracker tells the agent what needs to be done.
Issues have always been little documentation vaults. We write the history of the bug as it travels through the system. We link back to the issue as it maintains relevance.
An issue should preserve the context for a decision. It should act as a durable property of the project, recording the circumstances around a decision point.
Don’t make it a container for everything the agent did along the way, but I think it’s totally fine if you use it to publish an implementation plan.
Just, you know, you gotta read it.
Our job now is reading about software. The issue trackers are our corpus.
Route the Knowledge With Four Questions
When I don’t know where something belongs, these four questions can help.
1. Must the agent know this before it acts?
Instruction
2. Is this about performing a recurring kind of work?
Skill
3. Is this a durable fact that may help later?
Memory
4. Is this unfinished work or a commitment?
Issue
Sometimes the answer can be more than one place. But don’t copy the content blindly between locations.
All the files may be Markdown, but maintaining the architecture now means knowing where to put the information.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
Not Every Agent Task Needs an Issue
I’ve written before that your AI agent needs a task manager, and I stand by it. Chat history is not project state. Context windows compact. Sessions end. If the work matters tomorrow, it needs to live somewhere tomorrow’s agent can find it.
The part I didn’t mention: not every task matters tomorrow.
Some work should disappear with the session. Turning all of it into durable project state doesn’t make your agent more organized. It gives the next session a bigger pile of bookkeeping to misunderstand.
Tasks Have Different Lifetimes
When we say “task,” we’re lumping together several different things.
“Add filtering to the search API” is a project commitment. It might take several sessions, affect other work, and need a record of why the behavior changed.
“Inspect the existing query code” is not a project commitment. It’s one step the agent needs to finish the larger task.
“Run the focused tests” is even shorter-lived. Once they pass and the result has informed the work, that checklist item has done its whole job.
These all deserve attention. They don’t all deserve permanent storage. I think about them in two buckets:
- Session tasks help the current agent organize execution. They live in a plan or checklist, then disappear when the work is complete.
- Durable issues preserve commitments, decisions, dependencies, and unfinished work across sessions.
The distinction isn’t importance. A database backup check can be a critical session task. The distinction is whether the information needs to outlive the work happening right now.
If it doesn’t, let it die.
Ephemeral Does Not Mean Sloppy
There’s a temptation to treat ephemeral tasks as unstructured work. Just tell the agent,
plz fixand see what happens.A session still benefits from a clear plan. The agent should inspect before editing, break a change into steps, mark progress, run focused tests, run the full quality gate, and verify the result. A visible checklist makes long work easier to supervise, and it reduces the chance the agent quietly skips the boring last step.
The checklist just doesn’t need to become part of the project’s permanent record. Picture something like this:
- inspect the repository method - find every caller - update the shared comparison helper - add focused tests - run the full suiteThose are excellent session tasks. They tell the agent how to move through one change. After the implementation lands, keeping all five around adds nothing. The commit and tests preserve the result. The issue, if one exists, preserves the reason.
An Issue Should Earn Its Permanence
A durable issue is more expensive than it looks. Someone has to write it clearly, connect dependencies, update its state, close it, and eventually decide whether it’s stale. An agent also has to read it. Every open issue becomes part of the project’s apparent reality.
That cost is worth paying when the issue preserves something important. I create one when at least one of these is true:
- The work will survive the current session. If we’re likely to stop before it’s done, the next session needs a reliable handoff.
- Other work depends on it. A dependency belongs in a system that can represent blocked and ready work, not in a paragraph buried in chat history.
- It represents a real commitment. A user-reported bug, an accepted feature, or a promised follow-up shouldn’t vanish because a terminal closed.
- The decision needs a record. If future maintainers will ask why the system behaves this way, the issue preserves context a diff can’t.
- The work crosses boundaries. Changes spanning repos, services, migrations, or people need coordination beyond one agent’s checklist.
- We found valid work but aren’t doing it now. That’s exactly what a backlog is for.
If none of those apply, a session task is probably enough.
Promote Work When It Changes Shape
You don’t have to pick the perfect tracking level before the agent starts.
Begin with a session plan. During inspection, the agent may discover that the “small fix” requires a migration, depends on another repository, or exposes a separate bug. If the work changes shape. Promote it.
Agents are very good at expanding scope. They inspect one path, notice three adjacent problems, and offer to fix everything while the files are open. Sometimes that’s useful…
Your Backlog Is an Agent Prompt
Humans are pretty good at looking at an old issue and thinking, “yeah, we don’t care about that anymore.”
Agents are more literal. If the tracker says the issue is open and ready, the agent has a strong reason to treat it as authorized work. A stale backlog can send a perfectly capable agent down an obsolete implementation plan just as it easily as it can with a valid one.
No issue hygiene needs to be a part of your process. An open issue tells the agent this work is still wanted, this description is still accurate, these constraints still apply, and finishing it would improve the project.
If any of that is false, the issue isn’t harmless clutter. It’s a bad prompt waiting to be executed.
Use the Smallest State That Survives Long Enough
After six months with git-native issue tracking, my workflow has gotten a lot more varied.
I use a session plan when the current agent only needs help organizing the work in front of it. I use an issue tracker when the project needs to remember something after that agent is gone. For local projects i’m very rarely reaching for Beads. For team work it’s always GitHub or GitLab.
Too little tracking and the project forgets real commitments. Too much and it accumulates stale instructions, duplicate tasks, and chores whose only purpose is maintaining the tracker.
Start small. Let the agent make a checklist. Promote the work when it makes sense. Close it when the feature is satisfied. Delete old tasks like you are pulling weeds to make space for the flowers to bloom.
Your agent needs a task manager. It does not need a permanent record of every box it checked along the way.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
Don't Build a Full Agentic Harness. Wrap One Instead.
I keep seeing people talk about building an “Agentic OS”. A personal system where agents get tools, memory, sub-agents, long-running tasks, permissions, and maybe a little dashboard with colored dots so you know the robots are thinking.
I get it. It sounds fun. It is fun. I like building things too.
So first, a distinction, because the word gets thrown around loosely. Wrapping an existing harness is fine. A little script that shells out to Claude Code or Codex to do one job is a wrapper, and most people should build those. Plenty of people build one by accident and never call it a harness. I’ve got three small ones driving the pipeline that publishes this blog, each just handing a task to Claude Code and getting out of the way. That’s not the trap.
The trap is starting from a raw model API and trying to rebuild the whole thing, replicating Codex or Claude Code or OpenCode from scratch because you want a better way to work with agents. Do that and chances are you’re about to spend several weekends building a worse version of the tool you already have.
No-thX.
So the useful question isn’t “should I build a harness?” It’s how much of the harness do I need to own?
You’re Choosing an Ownership Level
A harness is all the stuff around the model: the agent loop, tool execution, sessions, permissions, memory, context management, orchestration. The model is the part you rent. The harness is the part you choose to own.
And that choice is a slider, not a binary.
What you do What you own What you inherit Extend a full harness Skills, sub-agents, MCP servers, conventions The loop, permissions, sessions, tool execution Run an open harness Deployment, provider, config Most core agent machinery Start from primitives The loop, workflow-specific behavior A small SDK and a few tools Build an agent app Everything that makes it a product Framework primitives, maybe Most people should start at the top and work down only when they hit a real reason to.
Start by Composing What Already Works
If you already use Claude Code, Codex, Gemini CLI, or another complete coding harness, you have more leverage than you think.
You can add specialized agents. You can write skills for recurring work. You can connect MCP servers for memory, documents, databases, browser tooling, whatever you need. You can set project conventions so the agent doesn’t rediscover the same rules every time.
That’s not “just configuration.” Configuration is how you shape a system without becoming responsible for every moving part inside it. The host already knows how to run the model loop, ask permission before risky actions, manage sessions and context, stream tool output, handle files and diffs, and coordinate sub-agents.
I’ve got a vault full of agent instructions, task-specific skills, persistent memory, and a few specialized agents. None of it required me to write a scheduler, a context-compaction system, or an approval UI from scratch. Good. I have other things to do.
The DIY Tax Is Real
A basic agent loop looks almost insultingly simple:
send prompt → receive tool call → run tool → send result → repeatYou can get that running in an afternoon.
What happens when a tool hangs? When the user cancels halfway through a long task? Where do sessions live, and how do you resume them? How do you show the user what changed? How do you stop an agent from reading the wrong file, deleting the wrong directory, or spending five dollars retrying the same broken command?
Then you need permissions. Sandboxing. Tool schemas. Retries. Logging. Secret handling. Context limits. Model fallbacks. Observability. A way to update all of it without turning your harness into the largest unmaintained project in your life.
It works. But “it works” and “it’s a good idea” are two very different things.
When You Should Go Lower
There are good reasons to own more of the stack. Maybe you need provider independence, routing cheap models to bulk work and expensive ones to the hard problems. Maybe you need an agent running persistently on your own infrastructure. Maybe the agent has to live inside another product, not a coding CLI. Maybe your workflow is weird: several specialized agents passing structured work between each other, a custom approval model, durable state that’s part of the thing you’re selling.
Those are all real reasons to move down the slider.
The trap is that people move down the slider because they’re curious, not because they hit a constraint. Curiosity is a great reason to build a prototype. It is not automatically a great reason to make yourself responsible for a runtime.
The Path That Doesn’t Make You Miserable
- Extend the harness you already use. Add a few good skills, focused sub-agents, the tools and memory you need. Do this first, because it shows you which parts of the workflow are painful before you replace anything.
- Add a model-agnostic harness for the jobs that hurt. When billing, deployment, or long-running automation become a real problem, reach for an open, self-hostable harness like Goose, OpenHands, Hermes Agent, or Pi. You still inherit the hard machinery but get control over providers and hosting. (This is also the layer where a model gateway like OpenRouter or LiteLLM slots in underneath, so you’re not locked to one vendor.)
- Drop to primitives for one narrow workflow. Skip the harness entirely and write the loop yourself on a thin SDK, the Vercel AI SDK or Anthropic’s Claude Agent SDK, when you need an embedded agent or a topology existing tools can’t represent cleanly. Build the smallest thing that proves the point. Don’t start by recreating a general-purpose coding agent.
- Reach for a framework when you’re shipping an agent product. If the harness itself is the product, then yes, you probably need graphs, durable state, domain models, and all the rest. This is where something like LangGraph or CrewAI earns its weight. That’s a different project from improving your own workflow.
One tool blurs steps 1 through 3 on purpose, and it’s worth calling out: Pi (pi.dev). It’s a coding-agent CLI you can use today and a TypeScript SDK you build your own harness on top of, provider-agnostic, with a “primitives, not features” core. If you already know you’ll want to customize, Pi lets you start by using it and grow into owning the loop, one extension at a time, without ever switching tools. Hermes Agent sits in similar territory for the self-hosted, model-agnostic case. Either one is a saner on-ramp than a from-scratch build on day one.
Own the Part That Makes You Different
The more of the harness you own, the more control you have. You also own more bugs, more security decisions, more context problems, and more ways for an agent to fail that are hard to explain.
So my strategy is boring in the good way. Start with a full harness. Compose it around your work. Add a lower-level tool only when you can name the limitation it solves. Build the loop yourself only when owning the loop is the point.
You don’t need an Agentic OS to get serious value out of agents. You need a workflow that helps you finish work without becoming one more system you have to maintain.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
Amnesia-Free Agents: GBrain and the LLM Wiki Idea
Every agent I work with has amnesia.
Open a new terminal session, spin up a subagent, start a fresh chat, and the thing forgets everything. Your project guidelines, your coding style, your database schemas, the meeting where you decided why the schema looks like that. Gone. So you do one of two things: stuff a few thousand tokens into a bloated system prompt, or hand-maintain fragile context files like
CLAUDE.md. I’ve done both. Neither feels good.So when Y Combinator CEO Garry Tan open-sourced GBrain on April 5, 2026, a markdown-first memory layer, I wanted to understand what it does and whether it’s worth the setup.
What GBrain actually is
GBrain is a Postgres-native knowledge brain that acts as a persistent retrieval layer for your coding agents. The interesting part isn’t that it stores stuff, it’s how opinionated it is about the shape of that storage.
Three ideas do the heavy lifting:
- Compiled truth vs. an append-only timeline. Raw daily logs, Slack messages, and emails go in one bucket. The curated “current facts” (contacts, active projects, decisions) live as clean Markdown in another. One is history, the other is truth.
- A self-wiring knowledge graph. It parses your plain Markdown and pulls out relationships (
works_at,invested_in,founded) using local grammars. No LLM API calls to build the map. - The Dream Cycle. An overnight cron job that crawls your daily logs, reconciles contradictions, checks citations, and rebuilds the search index while you sleep.
That last one worth a callout: Memory that maintains itself.
The category error everyone makes
People keep comparing GBrain to runtime agents like OpenClaw or Hermes, and that comparison doesn’t hold up. They’re different layers entirely.
GBrain isn’t an execution engine. It’s closer to a self-writing wiki.
┌────────────────────────────────────────────────┐ │ AGENT RUNTIMES │ │ (OpenClaw, Hermes, Claude Code) │ │ runs code, spawns subagents, hits the shell │ └─────────────────────────┬────────────────────────┘ │ reads & writes via MCP ▼ ┌────────────────────────────────────────────────┐ │ THE LLM WIKI │ │ (GBrain, OpenWiki) │ │ compiles raw history into clean markdown │ └────────────────────────────────────────────────┘The runtime is the hands and eyes. It sandboxes code, runs terminal commands, touches the file system. The wiki is the long-term memory. You wire them together over the Model Context Protocol (MCP), and when the agent needs context, it doesn’t parse your raw email history. It queries the wiki and gets back synthesized, cited facts.
GBrain isn’t the only thing playing this role. OpenWiki, from the LangChain folks, uses the same trick to compile big source repos into navigable markdown. Same pattern, different input.
The payoff: your agent stays lightweight and task-focused, and your knowledge lives in a clean, git-versioned wiki instead of leaking into a system prompt.
What people actually run into
The concept is great. The reality has some sharp edges, and the community forums are honest about them.
It needs babysitting. GBrain moves fast, which means frequent schema updates and migrations. You’ll find yourself running things like
gbrain doctor --remediateto fix database drift. It is not set-it-and-forget-it.Tool sprawl adds up. To feed the Dream Cycle good data, people bolt on voice transcribers, contact enrichers, email scrapers. Most of those are paid SaaS. String enough together and you’ve built yourself a subscription problem.
Setup is a project. A Dockerized Postgres with
pgvector, system keyring wrangling (macOS Keychain or D-Bus), cron schedulers. Budget anywhere from 30 minutes to a lost afternoon.Should you bother?
If you’re juggling complex work across a bunch of codebases, and you want an agent that knows your past architecture decisions and updates its own docs overnight, the GBrain + OpenClaw setup earns its keep. That’s a real moat.
If you just want a lightweight assistant that remembers a few things, you’re better off with plain
MEMORY.mdfiles or a hosted API like Mem0 until the local graph-RAG tooling settles down. I’m somewhere in the middle right now, so I’ll watching it to see where it goes.Amnesia is the default. It doesn’t have to be.
Sources
- GBrain repository
- OpenClaw agent framework
- Hermes Agent (Nous Research)
- /r/openclaw community threads
- Hacker News
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
Build Your Own Skills Repo
If you’ve been working with AI coding agents for a while, you’ve probably started collecting workflows. You might not call them that yet, but they’re there. Another name for workflows is Skills.
Some are tiny: run these checks before shipping. Some are project-specific: when you touch this library, preserve this API contract. Some are operational: never print secrets, always summarize the logs. Right now they probably live in chat history, a README note, a shell alias, or your own memory. That works until it doesn’t.
A skills repo is a better shape for this. It’s one place to collect, version, review, and share the workflows that make agents useful in your projects. I built my own yesterday, so let me walk through how I think about it.
A skill is judgment, not a command list
The first mistake is treating a skill like a list of commands. Commands matter, but they’re the easy part. The real value is judgment: when to run the command, what to inspect first, what not to do, how to validate the result, and what risks are specific to this tool.
A good skill makes an agent more careful. It narrows the space of bad decisions. So before you write a single instruction, figure out who the skill is for.
Separate adoption from maintenance
Most serious projects have two audiences: people using the project, and people maintaining it. Those should usually be two different skills.
An adoption skill helps an outside developer get value from your project. Install the package, configure it correctly, use the right import path, migrate existing code, avoid the common mistakes, run the right validation.
A maintainer skill helps contributors work inside the source repo. Understand the layout, run the local quality gate, preserve compatibility promises, follow the release conventions.
Here’s why you need two. If you only write maintainer skills, your repo becomes a private automation folder. If you write adoption skills too, it becomes onboarding infrastructure.
Keep each skill focused
A skill should have a job. Not “everything about this project.” Not a duplicate README. Good skill names are verbs:
integrate,audit,upgrade,migrate,debug,ship. That keeps the trigger obvious, so when someone asks the agent to do that kind of work, the skill has a clear reason to load.If a project needs multiple workflows, split them. A library might have
integrateanddevelop. A deployment system might havedeployandrollback. Don’t cram them into one file.Put the safety rules near the top
The most important part of many skills is the “do not” section:
- Do not print secret values.
- Do not delete or archive anything without confirmation.
- Do not add failing CI enforcement unless asked.
- Do not do broad rewrites before previewing a diff.
- Do not commit local registry URLs.
Agents are good at momentum. Safety rules are how you make that momentum usable. The more destructive the workflow, the more explicit the guardrails should be.
Include validation, not just execution
Every skill should answer one question: how do we know this worked? That might be
pnpm test && pnpm build, orcargo test && cargo clippy -- -D warnings, orgo test ./.... For non-code workflows it might be “export the review list” or “verify the generated config is ignored by git.”This matters because agents can complete every step without completing the work. Validation closes the loop.
Write for the agent inside the repo
Skills should assume the agent is operating in a real project with real files and existing conventions. So the useful instructions look like:
- Inspect
package.jsonbefore choosing a package manager. - Read the existing test scripts before adding new ones.
- Prefer the local task-runner commands when they exist.
- Check the framework boundary before picking an import path.
That’s the context generic model knowledge won’t reliably infer. And it’s why you shouldn’t just copy the README into the skill. A README is for a human browsing the project. A skill is for an agent doing work. They overlap, but they aren’t the same artifact. Keep the skill short enough that loading it is cheap.
Use a marketplace repo as the index
Your skills repo doesn’t need to be the canonical home for every skill. Some projects should own their own plugin metadata, especially if they already have a CLI, release process, and docs. Your marketplace can just point at them remotely. Other skills can live directly in the marketplace repo. One structure that works:
skills/ .claude-plugin/ marketplace.json plugins/ esm/ .claude-plugin/plugin.json skills/develop/SKILL.md upkeep-rs/ .claude-plugin/plugin.json skills/audit/SKILL.mdThe marketplace becomes the thing people add once. Individual plugins stay free to live locally or point at their canonical upstream.
Scan third-party skills before you import them
The moment your marketplace points at someone else’s plugin, you’ve inherited their security posture. And skills are a soft target. The dangerous payload usually isn’t code, it’s prose: an attacker buries instructions inside a
SKILL.md, gated behind an innocent-sounding trigger, that tell the agent to read your.envand send it somewhere. A normal code scanner walks right past that. There’s no malware signature to match. It’s just English.This isn’t hypothetical. Snyk’s ToxicSkills research found prompt injection in 36% of the skills they tested, across more than a thousand malicious payloads. If you’re pulling skills from a public index, some fraction of them are trying to do something you didn’t ask for.
So run a scanner before you add anything you didn’t write. A few worth knowing:
- Snyk agent-scan inventories your installed agents, MCP servers, and skills, then checks them for prompt injection and data-handling problems.
- NVIDIA SkillSpector scans repos, URLs, or single files against a big catalog of patterns: injection, exfiltration, privilege escalation, tool poisoning.
- claude-skill-antivirus is purpose-built for Claude Code skills and runs several detection engines at once.
One caveat worth internalizing: scanning an MCP config can execute it, because starting a stdio server means running the command in the file. Do that in a sandbox, a container or a throwaway VM, not on your main machine. The tool you run to check for danger shouldn’t be the thing that sets it off.
This cuts both ways. If you publish a plugin others will install, a clear “do not” block and an honest description of what the skill touches is part of being a good citizen of the marketplace.
Start with your serious projects
You don’t need a skill for everything. Start where better agent behavior would matter: public libraries people might adopt, CLIs with safety-sensitive workflows, tools with tricky setup, projects with recurring maintenance, systems where mistakes are expensive.
For each one, ask yourself:
- Who is this for: user, maintainer, operator, contributor?
- What’s the concrete task?
- What should the agent inspect first?
- What commands are preferred, and which are dangerous?
- What should never happen silently?
- What validation proves the work succeeded?
Answer those and you have enough to write a useful first skill.
Why it’s worth doing
A skills repo turns scattered project knowledge into reusable operational guidance. But it also forces a better product question. If this project is meant to help people, what would it look like for an AI agent to help them use it well?
That’s a higher bar than “can the agent run the command?” The point isn’t to automate everything. It’s to package the judgment around your tools so the next agent starts from a better place.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
The Capture Trap: Why Your Note Vault Is a Graveyard
Open your notes app and scroll to the bottom of the inbox. How many of those clippings have you reread? How many turned into anything? The answer is probably “almost none.” You have hundreds of saved articles, and half-finished thoughts, and the pile only ever grows. That’s not a second brain. That’s a graveyard.
I walked through Forte’s CODE workflow recently, four stages from Capture to Express. This post is about the stage everyone skips, and why skipping it is so easy that most vaults quietly die of it.
Capture feels like work. It isn’t.
Clipping an article gives you a little hit. You found something useful, you saved it, you can close the tab and feel like you made progress. But you didn’t learn anything. You filed it. The act of saving stands in for the act of understanding, and your brain happily accepts the substitution.
The Zettelkasten people have a name for this: the collector’s fallacy. Gathering material feels like knowledge work, so you keep gathering, and the gathering itself becomes the hobby. The collection grows. Your understanding doesn’t. You end up with a beautifully organized library you’ve never read.
Capture is frictionless now, which makes the trap worse. Web clippers, voice memos, a hotkey that drops anything into your inbox. The easier it gets to collect, the faster the graveyard fills.
Express is where the value is, and it’s the part that hurts
Express is the stage where you do something with a note: write the post, make the decision, ship the code, send the reply. It’s the only stage that produces anything. It’s also the one that takes effort, because it forces you to actually think about the material instead of just owning it.
So it gets deferred. Forever. And a vault where nothing ever reaches Express is just an expensive way to forget things slowly.
The fix isn’t more capture discipline or a prettier folder structure. It’s making Express the default destination of a note instead of an optional last step you’ll get to someday.
Give every note a lifecycle
Stop treating notes as either “saved” or “not saved.” Give them a status, a small piece of frontmatter that says where the note is in its life:
rawis something you captured and haven’t processed.distilledis a note you’ve summarized in your own words.expressedis one that fed into actual output.
Now your vault has a pulse. You can query it. “Show me everything still sitting at
rawfrom the last two weeks” turns the invisible backlog into a list you can act on. The graveyard problem was always that dead notes looked exactly like live ones. A status field makes the dead ones visible.Point an agent at the backlog
This is where it gets fun, and where a CLI agent that can read your vault earns its keep.
Once notes carry a status, you can hand the boring half of Express to an agent. Wire up a weekly job that does three things:
- Query every note still sitting at
raw. - For each one, draft a two-sentence summary and a single question: is this worth keeping, and what would you make from it?
- Drop the results in front of you as a short review list.
You’re no longer staring at a wall of three hundred clippings. You’re answering ten questions about ten notes, and the agent did the reading. The notes you keep get promoted to
distilled. The ones you don’t get archived without guilt. Either way they leave the inbox, which is the whole point.The model as a sparring partner
The last piece is using the model to get from a distilled note to actual output. Hand it a cluster of related notes and an outline, and ask it to argue with you. Where’s the thesis weak? What’s the counterargument? What example would make this land?
The model doesn’t write the thing for you, and you don’t want it to, that’s how you end up with generic mush in your own voice. It pushes the note one stage further down the pipeline, from a pile of research into a draft with a spine. You take it from there.
That’s the anti-graveyard loop. Capture stays frictionless, because friction there is bad. But every captured note now enters a pipeline that pushes it toward output instead of letting it rot in an inbox. The status field makes the backlog visible, the agent works it down for you, and the model helps you ship.
A vault isn’t valuable because of what’s in it. It’s valuable because of what comes out. Build the part that gets things out, and the graveyard turns back into a brain.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
Sources
- Tiago Forte, Building a Second Brain (2022) — the CODE workflow and the “Express” stage as the antidote to collect-and-forget note-taking.
- Christian Tietze, “The Collector’s Fallacy” (Zettelkasten.de, 2015) — why gathering material feels like learning when it isn’t, and how the collection becomes the hobby.
-
Four Ways to Build Your Own Agentic Harness
The model is the commodity. You rent it. Everything else, the loop, the tools, the state, the permissions, the memory, the orchestration, is the harness. And the harness is the part you get to own.
So the real question, when people say they want to “build their own agent,” isn’t which model. It’s how much of the scaffolding you want to inherit versus how much you want to build yourself. That’s the whole decision. Where you land on that spectrum gives you, more or less, four approaches.
A: Build on top of a full harness
This is the composition-heavy approach, and it’s the one I’ve mostly done. You take a fully featured harness like Claude Code or opencode (and I think a few of the newer agentic IDEs support this now too), and you extend it. Sub-agents, skills, slash commands. You can call these things remotely with CLI commands and wire your own behavior around them.
There are two flavors here. You can build your harness inside the existing one, or you can build it around the existing one. Either way, you own all the agent definitions, the skills, the model choices. But you inherit a lot too: which tools the agent can call, the permission model, all the safety controls. You don’t get to change those, you just get to use them.
And honestly? That’s the appeal. You don’t start from scratch. Somebody already solved the boring, dangerous parts. You show up and build the part you care about.
B: Self-host a fully open harness
This one looks a lot like A, but with one important difference: the underlying harness is open. You’re self-hosting and extending something fully open-source, then polishing and tailoring it to your needs.
The trade is control. In approach A, the tools and permissions and controls are handed to you and you live with them. Here, the entire stack is yours to crack open. If the permission model annoys you, you change it. If you want a tool to behave differently at the loop level, you can reach in and do that. You’re still not building from nothing, but nothing is off-limits either.
C: Assemble from primitives
Now we’re getting low. With this approach you build your harness up from very minimal pieces. Think of it like a full-stack framework in the web world, except for agents. Something like pydantic-ai’s SDK, or pulling aider in as a library rather than running it as a tool.
You don’t start from absolute zero, but you’re close. You define the agent loop yourself. You register the tools. You add the features you need, one at a time. You’re scaffolding basically everything, and all you’re inheriting is a handful of core primitives that you get to shape into whatever you want.
This is the approach for people who have opinions and want to express all of them. It’s more work. It’s also the most yours.
D: An agentic harness framework
The last one is a different animal, and I’ll admit it took me a second to see why it’s its own category. These are orchestration frameworks like LangGraph or Letta (formerly MemGPT). They’re not coding CLIs. They’re SDKs for building a custom agent application: graphs, state machines, first-class memory.
The distinction that finally clicked for me is what you’re building. With A through C, you’re mostly building a personal dev tool, something that helps you write code. With D, the harness is the product. You’re shipping it. A domain agent, a service, a customer-facing thing that happens to be agentic under the hood. The orchestration framework is what you reach for when the agent isn’t your tool, it’s your deliverable.
So where do you land?
There’s no correct answer here, just a trade you’re making on purpose. The more you inherit, the faster you move and the less you control. The more you build, the more it’s yours and the more of the boring, dangerous plumbing you’re now on the hook for.
For most of what I do, A is the sweet spot. Building around and within an existing harness is just so much easier than starting cold, and I’d rather spend my time on the agent definitions than on reinventing a permission model. But if I were shipping an agent as a product instead of a tool, I’d be over in D without thinking twice.
Figure out which thing you’re building first. The approach falls out of that.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
Sources
- Anthropic, “Claude Code” (GitHub) — documentation and repository for the terminal-based agentic coding tool that reads codebases, runs commands, and integrates MCP servers.
- Aider AI, “Aider” — official documentation and pair-programming guides for the open-source, git-native AI coding assistant.
- Anomaly Co., “OpenCode” — official homepage and repository for the open-source terminal, desktop, and IDE-based AI coding agent.
- Pydantic, “Pydantic AI” — official documentation and API references for the type-safe Python agent framework designed for structured agent trajectories.
- Letta AI, “Letta” (GitHub) — repository for the stateful agent runtime (formerly MemGPT) that manages persistent memory tiers and agentic state machines.
-
Five Places RAG Shows Up in Agentic Systems
Ask most people what RAG is and they’ll tell you it’s semantic document search. You chunk up a pile of text, embed it, stuff it in a vector database, and pull the relevant bits back at query time. That’s the textbook example, and it’s a good one. But retrieval augmented generation does a lot more work inside agentic systems than “search the docs,” and I think it’s worth walking through where it actually shows up. So let’s talk about it.
1. High-Precision Semantic Search
This is the one everybody knows, so let’s get it out of the way first. You take raw text and convert it into high-dimensional vectors, where distance corresponds to conceptual similarity. Store those vectors, index them, and you can look things up by meaning instead of exact keywords.
The interesting part is how you index them, because the algorithm you pick is a real tradeoff.
HNSW (Hierarchical Navigable Small World) builds a multi-layer graph. The upper layers have long-distance links for fast routing across the space, and the lower layers have short-distance links for local search. You get low query latency and near-perfect recall. The catch is memory. It wants to keep the raw vectors around, so the footprint gets big.
IVF-PQ (Inverted File with Product Quantization) goes the other direction. It partitions the vector space into cells using k-means clustering, then compresses the high-dimensional vectors into compact quantized codes. Partition, then squish. That cuts memory consumption dramatically, which makes it a great fit for massive datasets with millions of vectors. The price you pay is recall accuracy, since all that compression throws away detail, and rebuilds get slower when you add new data.
Neither one is “correct.” You pick based on whether you’re optimizing for recall or for fitting the index in memory.
2. Tool Selection (RATS)
Here’s where it gets less obvious. Picture a CLI harness. As your developer toolkit grows, your agent slowly gets “equipped” with dozens or hundreds of possible actions. APIs, database calls, helpers, command executors. At some point you’ve just overloaded the thing with too much stuff.
Three bad things happen when you do that:
- Tool space interference (TSI). Overlapping tool descriptions confuse the agent, and it calls the wrong one.
- Context window saturation. Every tool schema, whether it’s JSON or Markdown, eats thousands of tokens. Pile up enough MCP servers and custom skills and you’re soaking the context window, which drives up cost and latency.
- The lost-middle problem. Models tend to ignore tools and instructions buried in the middle of a very long prompt.
Retrieval augmented tool selection fixes this by treating your tools like a corpus. Instead of dumping every schema into the prompt, you retrieve only the handful of tools relevant to the current task. The agent sees a short, sharp menu instead of the entire pantry.
3. Dynamic Few-Shot Prompting
Few-shot prompting is a reliable way to enforce formatting constraints like a strict JSON schema, teach reasoning paradigms like chain of thought, or train an agent on error recovery. The problem is that static examples baked into a prompt are a guess. They might not match the task in front of you.
RAG lets you select the examples at runtime. You curate a database of gold-standard trajectories, each one pairing a specific query or error case with the correct step-by-step reasoning, tool calls, and final output that solved it. When a new task comes in, you search that database using the user’s intent, grab the top few most similar past trajectories, and prepend them to the system instructions.
So the agent always gets examples that actually resemble what it’s being asked to do, instead of whatever examples you happened to hardcode three weeks ago.
4. Long-Term Agent Memory
Work directly with a model and it forgets everything the moment the session closes. Your preferences, your corrections, the choices you already made. Gone. For an agent to be useful, it needs persistent memory across sessions. I’ve written about this before.
One system here is mem0, which uses a hybrid RAG architecture to persist state. It does asynchronous fact extraction, conflict resolution when new information contradicts old, and grounds the retrieved memories back into the prompt. The retrieval layer is what lets the agent surface the right past fact at the right time instead of replaying the entire history.
5. Evaluation and Test Harnesses
Testing AI in production is hard because the outputs aren’t deterministic. So you build evaluation harnesses that run your agent across hundreds of test cases, and RAG turns out to be a quiet workhorse in that loop.
Two ways it helps:
- Diffing the test suite. Running every eval on every pull request is slow and expensive. Instead, query a vector index of your test suite using the git diff as the query, and run only the cases relevant to the code you actually touched.
- Semantic assertions. Exact string matching is useless when you’re verifying something like an agent’s summary. Instead, the harness retrieves historic successful runs and uses vector similarity to ask whether the new output matches the intent and tone of the target, rather than matching it character for character.
None of this replaces the document-search version of RAG. It’s the same core trick, embed things, retrieve by similarity, ground the result, pointed at different problems: which tool, which example, which memory, which test. Once you start seeing retrieval as a general-purpose way to feed an agent the relevant slice of a much bigger pile, it shows up everywhere. I’ll probably keep finding more.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
Sources
- Yury A. Malkov and Dmitry A. Yashunin, “Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs” (arXiv:1603.09320, 2016) — details on the multi-layer graph architecture and logarithmic complexity of the HNSW index.
- Hervé Jégou, Matthijs Douze, and Cordelia Schmid, “Product Quantization for Nearest Neighbor Search” (IEEE Transactions on Pattern Analysis and Machine Intelligence, 2011) — explains compressing high-dimensional vectors and combining product quantization with inverted file indexing (IVF-PQ).
- mem0ai, “mem0: The Memory Layer for Personalized AI” (GitHub) — documentation and codebase for the persistent, self-improving memory layer for AI agents.
- Mostafa Ibrahim, “Agentic RAG vs Classic RAG: From a Pipeline to a Control Loop” (Towards Data Science, March 2026) — commentary on the shift from static document retrieval to agentic control loops and its associated system failure modes.
- Microsoft Research, “Tool-space interference in the MCP era: Designing for agent compatibility at scale” — the tool-space interference (TSI) problem from section 2, where overlapping tool descriptions degrade agent tool selection.
- rewire.it, “Dynamic Tool Allocation for AI Agents (The RATS Pattern)” — the retrieval-augmented tool selection (RATS) pattern from section 2: a router retrieves a relevant subset of tools from a larger catalog.
-
A Field Glossary for Agentic Knowledge Work
Everywhere you look right now, somebody is saying agentic this and agent that. Harness, scaffold, skill, subagent, agentic OS. The vocabulary is piling up faster than anyone can keep track of, and a lot of it gets used loosely, sometimes by people who don’t actually know what the words mean.
So I figured I’d write down my own working glossary. This isn’t a textbook, and I’m not pretending these are official definitions. It’s how I think about the terms when I’m doing the work. If you’ve been nodding along in conversations without being totally sure what a harness is, this one’s for you.
Agent
There are a lot of flavors of agent, and I’m not going to catalog all of them. Generally speaking, an agent is some code wrapped around an LLM that runs in a loop, has access to tools, and can act using those tools.
That’s the key difference from a plain prompt-and-response call. A direct call to the model gives you one answer and stops. An agent has some degree of autonomy. It can decide to use a tool, look at the result, and keep going. The loop and the tools are what make it an agent instead of a chatbot.
Harness
A harness is the program that sits on top of the model. It manages conversation state, runs the reasoning loop, gives the model access to tools, and enforces the guardrails, things like permissions, controls, and budget.
Here’s an easy way to understand it. The model is the intelligence. The harness is the control on the intelligence. The harness sits between you and the LLM.
A harness can show up in a lot of places. It might be a CLI. It might be a GUI or an app on your phone. It might be a chat thread. You could wire up something like OpenClaw to talk to you in WhatsApp or Telegram, and that chat becomes your harness, while OpenClaw is also a harness underneath. So yes, harnesses can call other harnesses. It’s turtles a little way down.
Scaffold
You’ll hear people say scaffold or scaffolding. This is usually just another word for harness. The prompt, the tools, and the control structure wrapped around the model. Same idea, different label.
Framework or SDK
These are the libraries you build harnesses with. LangChain, the various agent SDKs, or a ready-to-run harness like Claude Code or Hermes.
Worth flagging that framework and SDK mean something specific in regular programming. In the agentic context they’re a little looser. They’re what you build agents and harnesses out of. And it doesn’t have to be off-the-shelf. You can absolutely build your own framework for building your own harnesses if that’s where your head is at.
Context Engineering
This is the big one. The term comes from Karpathy, and while it mattered even more a year ago than it does today, it still applies.
Context engineering is deliberately managing what’s in the context window of the current session. It’s the work of deciding what gets loaded into context and, just as importantly, what gets left out. It’s the successor to what we used to call prompt engineering. The framing shifted because the prompt is only one piece of what the model sees, and the rest of it matters a lot.
MCP
Model Context Protocol. I won’t go deep here, it deserves its own post. MCP is an open protocol for exposing tools and data to an LLM harness. It’s the standard way for your harness to reach out and use third-party software or pull in outside data.
Skills
Skills are a major, important thing, and I’m not going to do them justice in a glossary entry. But here’s the definition.
A skill is a reusable, often self-created capability that bundles up the instructions an agent needs to accomplish a specific task. You can find skills all over the internet now. Everybody’s got their own. You can generate your own pretty easily with the CLI, and harnesses like Claude Code or Hermes can even author their own skills. The word does the work here. Skills are capabilities. It’s how you extend what your agents and harnesses can actually do.
Subagent
A subagent is an isolated child agent spawned from inside a working session.
Say you’re in your harness of choice with a main session running. That orchestration session can fork off a new agent with its own context window, hand it a specific task, and say go do this. The subagent runs on its own, often in parallel with others, working in the background. The main session knows when it finishes and can check the work.
A lot of the time you’ll have a second subagent review the first one’s output. That review loop is the whole idea behind the agentic maturity model, which is a way of thinking about how to structure this kind of work. It’s on GitHub if you want to dig in.
Agentic OS
This is an orchestration layer that combines agents, memory, and tools. It’s not really an operating system, but the name has stuck. You take all these concepts, the skills, the agents, the memory, the tools, and combine them into one organized whole. People are calling that amalgamation an agentic OS.
Second Brain / PKM
A personal knowledge vault. I posted about this just this week. It’s a personal knowledge base that the model can read, search, and extend. Your notes, your references, your accumulated thinking, made available to the agent.
Vibe Coding vs. Agentic Engineering
This is the distinction I care about a lot.
Vibe coding is not really knowing what you’re doing or how it’s being done. Anyone can vibe code. You describe what you want and you accept what comes back.
Agentic engineering is knowing what you’re doing and caring about how it gets done. Not everyone can do that part.
The way people put it is that vibe coding raises the floor and agentic engineering raises the ceiling. Vibe coding lets anyone build something. Agentic engineering lets a professional move a lot faster than they used to. Both are real. They’re not the same thing.
That’s the glossary, at least the version that lives in my head. None of these terms are settled, and half of them will probably mean something slightly different in six months. But hopefully this has helped!
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
Sources
- Vibe coding — Wikipedia — the term coined by Andrej Karpathy (Feb 2025); the “vibe coding vs. agentic engineering” distinction the post draws.
- Andrej Karpathy, "+1 for ‘context engineering’ over ‘prompt engineering’" (X, June 25, 2025) — the origin of the term “context engineering” as the successor to prompt engineering.
- Model Context Protocol — Wikipedia — MCP as the open standard introduced by Anthropic (Nov 2024) for exposing tools and data to LLM harnesses.
- Emma Roth, “Anthropic launches tool to connect AI systems directly to datasets” (The Verge, Nov 25, 2024) — news coverage of the MCP launch.
- Agentic Maturity Model — GitHub — the AMM referenced in the Subagent entry; Level 3 describes the worker-plus-reviewer subagent pattern.
-
Two Kinds of Memory for Your CLI Agent
So you set up a memory layer for your local CLI agent. Now what? How do you actually get that memory in front of the agent so it does something useful?
I’m going to walk through what I did with mem0, but the shape of this applies to pretty much any memory layer. The first thing worth understanding is that CLI agents work with memory in two very different ways, and the difference matters.
The first way is text that’s always loaded. It gets injected into every session’s context automatically. No action needed on the agent’s part, it’s just there. This is your guaranteed data, the stuff that shows up at the start of every conversation.
The second way is semantic memory. For me that’s mem0 and the tooling I’ve built around it. This layer is accessed through an MCP server that exposes commands like
recallandremember. It’s poll-based. The agent has to decide to callrecall, because nothing gets auto-injected. The agent needs to be smart enough to say “I’m not sure about this, let me go look it up.”Those are the two flavors. Let me break them down.
Layer 1A: The Shared Instructions File
For most CLI agents, this is a single markdown file that the harness auto-loads into every session. Claude Code reads
CLAUDE.md. Gemini and Antigravity readGEMINI.md. AndAGENTS.mdhas become the cross-tool convention, read by OpenCode, Antigravity, and Cursor alike. Same idea everywhere, just a different filename.The one rule here: keep it minimal. Every line in this file is context you’re paying for on every single session. So don’t dump your whole knowledge base into it. The durable conventions, the project-specific facts, the things you only occasionally need? Those belong in your semantic layer, not here. This file is for the handful of rules that need to be loaded 100% of the time.
Layer 1B: Auto-Memory
Claude Code shipped a feature called auto-memory. It lives in
~/.claude/projects/, inside a subfolder that’s basically a slug of your project’s path on disk. In there you get amemoryfolder with aMEMORY.mdfile alongside the individual memory files.MEMORY.mdworks like an index. It holds short pointers to the durable memories stored next to it, and the whole thing gets loaded every session. It’s still part of layer 1, the always-loaded kind.Worth noting: this is a Claude Code thing. OpenCode and Antigravity don’t load or even know about these files. There’s no equivalent. Antigravity does have its own separate memory store that it syncs on its own, but it’s a different mechanism entirely, not a reader of Claude’s auto-memory.
Layer 2: The Semantic Layer
This is where it gets fun. I built a small MCP server in Go, a local binary that forwards requests to another server on my network. That server talks to two databases: Qdrant for the vectors, and Neo4j for the graph. The three functions I lean on most are
recall,remember, andadd_relation.If MCP is new to you, the short version: it’s an open standard that lets your agent connect to external tools and data over a common protocol. Instead of N bespoke integrations, you run one MCP server per capability and the host discovers it. People call it “a USB-C port for AI,” which is annoying and also pretty accurate.
Wiring it up is just config. For Claude Code, it goes in
~/.claude.jsonunder the top-levelmcpServers.memoryblock. For OpenCode, it’s~/.config/opencode/opencode.jsonundermcp.memory, withtype: localand a command that runs the binary.The Part People Forget
Here’s the step that ties it all together. Setting up the MCP server doesn’t do anything on its own. Remember, the semantic layer is poll-based. The agent won’t call
recallunless it knows it should.So you go back to layer 1, your always-loaded instructions, and you add a few lines telling the agent how and when to use the MCP server. Something like “before answering questions about this project, call
recallwith a relevant query” and “when the user tells you something worth keeping, callremember.” That instruction is small, it’s cheap, and it’s what turns a dormant memory store into a memory layer the agent actually reaches for.That’s the whole architecture. Always-loaded text that’s guaranteed but expensive, and a semantic store that’s huge but only as good as the agent’s instinct to go check it. Get both layers talking and your agent stops forgetting who you are every morning.
Sources
- mem0 — GitHub — the universal memory layer for AI agents that the post describes wiring up; 59.6k stars, Apache 2.0.
- Model Context Protocol — Wikipedia — MCP as an open standard introduced by Anthropic (Nov 2024) for connecting AI systems to external tools and data sources.
- Emma Roth, “Anthropic launches tool to connect AI systems directly to datasets” (The Verge, Nov 25, 2024) — news coverage of the MCP launch; confirms the “USB-C port for AI” framing and the standard-protocol pitch.
- Jonathan Kemper, “Claude Code now remembers your fixes, your preferences, and your project quirks on its own” (The Decoder, Feb 27, 2026) — news coverage of the auto-memory feature; confirms the
MEMORY.mdper-project file and the~/.claude/projects/directory structure. - How Claude remembers your project — Claude Code Docs — official documentation for
CLAUDE.mdfiles and the auto-memory system.
I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week, or you can find me on Mastodon at @[email protected].
-
AI-Assisted vs AI-Agentic Coding
There are two ways to work (c0de) with AI tools right now. I think most people know the other one exists, but they haven’t taken the time to try it. You should know how to do both. And when to do both.
Assisted Mode
Everybody knows this one. You write some code, you get stuck, you ask a question.
How does date parsing work in Python? What’s this function do? Haven’t we built this already? I need some fucking Regex again.
The AI answers. You copy-paste or accept the suggestion. You keep going. You’re driving. The AI is in the passenger seat reading the map.
I mean, this is really useful. I’m not going to pretend it isn’t. It’s also just autocomplete with opinions. Fancy autocomplete. Smart autocomplete.
Great. You’re doing the thinking. You’re deciding what gets built and how to structure it and what order to do things in. You’re just asking for help on some of the blanks. That’s assisted mode.
Agentic Mode
This is different.
You describe what you want. You need to know how to describe what you want.
That is extremely important. Let me say that again. You need to know how to describe what you want.
You need to build an agent that understands how to interpret your description as what you want.
Sometimes it’s going to get it correct and sometimes it’s not. It’s going to go in a different direction than you wanted and you’re going to have to correct it. That’s the job now. You’re reviewing the output, the code, and how it’s producing the code. What are the gaps? You have to find the gaps and improve the agent so that it understands you better.
When I Use Which
I wish I had a clean rule for this. I don’t. That’s the vibes part.
Small or specific things can be assisted. Quick answers. Great. Easy. Move on.
Once you start wanting to touch multiple files, agentic. Major features like commands or parser changes or handler rewrites, recipes or tests. I’m not writing all that by hand. I can describe what I want way better than I can autocomplete it.
Bug fixes? Depends. If I already know where the bug is, assisted. If I don’t, agentic. Let the agent grep around and figure it out. It’s better at reading a whole codebase quickly than I am. Not better at understanding it. Better at reading it.
New features? Almost always agentic. I describe the feature, point it at similar code in the repo, and let it go.
Again, review is super important. Sometimes you have to send it back or start over or change major portions of it. And if you build a system that learns, it’ll get better along the way.
The Review Problem
Switching to agentic mode, your entire job is code review. All day, all the time, constant. That’s the human’s job. Code review.
Are you good at code review? You should get better at it. You need to get better at it.
This is not whether or not the tests pass. You need to identify possible issues and then describe tests that can check for those issues.
The nuanced bugs are the worst. And if those make it to production, you’re going to have problems.
Don’t skim the diff.
That should be the new motto. Read the code. Get better at code comprehension. It’s extremely important. You may be writing less code but you need to sure as shit understand what the code is doing and how it can be bad.
The Hybrid Reality
It’s totally fine to switch between modes depending on what you’re doing or your work session. Agentic can be way more impactful, but assisted mode is way better at helping you understand what the code is doing because you can select code blocks and easily ask questions about it.
So it’s not a toggle, it’s a spectrum. Now isn’t that funny? I’m on the spectrum of agentic development.
Where are you on the spectrum of agentic development?
So Which Is Better?
Neither. Both. It depends. Whatever, just build stuff.
Is assisted mode safer? Really? Like, does the human actually write better code this way? I don’t know. Agentic mode can be faster and you need to be super careful that it’s not gaslighting you into thinking it knows what it’s doing.
Build software for you. And when it makes sense, help out with the community stuff. Support open source.
If you’re a developer, I’d appreciate a follow. You can subscribe with your email below. The emails go out once a week. Or you can find me on Mastodon at @[email protected].
-
What Is an AI Agent, Actually?
We need some actual definitions. The word “agent” is getting slapped onto every product and service, and marketers aren’t doing anybody favors as they SEO-optimize for the new agentic world we live in. There’s a huge range in what these things can actually do. Here is my attempt at clarity.
The Spectrum of AI Capabilities
Chatbot / Assistant — This is a single conversation with no persistent goals and no tool use. You ask it questions, it answers from a knowledge base. Think of the little chat widget on a product page that helps you find pricing info or troubleshoot a common issue. It talks with you, and that’s about it.
LLM with Tool Use — This is what you get when you open “agent mode” in your IDE. Your LLM can read files, run commands, edit code. A lot of IDE vendors call this an agent, but it’s not really one. It’s a language model that can use tools when you ask it to. The key difference: you are still driving. You give it a task, it does that task, you give it the next one.
Agent — Given a goal, it can plan and execute multi-step workflows autonomously. By “workflow” I mean a sequence of actions that depend on each other: read a file, decide what to change, make the edit, run the tests, fix what broke, repeat. It has reasoning, memory, and some degree of autonomy in completing an objective. You don’t hand it step-by-step instructions. You describe what you want done, and it figures out how to get there.
Sub-Agent — An agent that gets dispatched by another a command or “LLM with Tool Use” to handle a specific piece of a larger task. If you’ve used Claude Code or Cursor, you know what I’m talking about. The main chat coordinator kicks off a sub-agent to go research something, review code, or run tests in parallel while it keeps working on the bigger picture. The sub-agent has its own context and tools, but it reports back to the parent. It’s not a separate autonomous agent with its own goals. It’s more like delegating a subtask.
Multi-Agent System — Multiple independent agents coordinating together, either directly or through an orchestrator. The key difference from sub-agents: these agents have their own goals and specialties. They negotiate, hand off work, and make decisions independently. Think of a system where one agent monitors your infrastructure, another handles incident response, and a third writes the postmortem. Each Agent is operating autonomously but aware of the others.
So How Is Something Like OpenClaw Different From a Chatbot?
A chatbot is designed to talk with you, similar to how you’d just talk with an LLM directly. OpenClaw is designed to work for you. It has agency. It can take actions. It’s more than just a conversation.
Obviously, how much it can do depends on what skills and plugins you enable, and what degree of risk you’re comfortable with. But here’s the interesting part: it’s proactive. It has a heartbeat mechanism that keeps it running continuously in the background. It’ll automatically check on things or take action on a schedule you specify, without you having to prompt it.
A Few Misconceptions Worth Clearing Up
OpenClaw is just one specific framework for building and orchestrating agents, but the misconceptions around it apply broadly.
“Agents have to run locally." That’s how OpenClaw works, sure. But in reality, the enterprise agents are running invisibly in the background all the time. Your agent doesn’t need to live on your laptop.
“Agents need a chat interface." Because you can talk to an agent, people assume you must have a chat interface for it to be an agent. But by definition, agents don’t require a conversation. They can just run in the background doing things. No chat window needed.
“Sub-agents are just function calls." This one trips up developers. When your agent spawns a sub-agent, it’s not the same as calling a function. The sub-agent gets its own context window, its own reasoning loop, its own tool access. It can make judgment calls the parent didn’t anticipate. That’s fundamentally different from passing arguments to a function and getting a return value.
Why Write This Down
I mainly wrote this for myself. I keep running into these terms and needing a mental model to put them in context, so as I’m thinking about building agentic systems and trying to decide what level of capability I actually need for a given problem. The process of writing it down makes those decisions somewhat easier.
-
Spent some time with Google Antigravity today and I think I’m starting to get it. Built a few agents to test it out. The agent manager stuff is genuinely interesting and seems useful. The planning features (spec-driven development) though? Not sold on those yet.