Agents
-
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.