You spend three weeks teaching an agent your codebase. It learns that your test suite needs CI=true, that one service can't take a new gem mid-session, that a particular sticker layout always fails die-cut. Then you switch coding tools — a better model lands somewhere else, or your team standardizes on a different harness — and all of it is gone. The new tool greets you like a stranger.

That is the portability problem, and almost nobody designs for it until the day they hit it. The accumulated context that makes an agent useful is usually trapped inside one vendor's storage format, reachable only through that vendor's API, deleted the moment you stop paying or stop using it.

This is a different failure than agents forgetting between sessions. We've written about durability before — keeping memory alive across restarts. Portability is the next layer up: keeping memory alive across tools. You can solve durability perfectly and still lose everything when you migrate.

The lock-in is in the storage, not the data

Your agent's memory is just text and vectors. A rejection note is a sentence. A "search before acting" lookup is an embedding query against a table. None of that is proprietary in any technical sense.

What makes it non-portable is where it lives. When a tool stores your agent's history inside a managed backend you can only reach through its own SDK, three things happen:

• You can't read it without the tool running.
• You can't diff it, grep it, or put it in version control.
• You can't take it with you, because there's no export that isn't an afterthought.

The data is generic. The container is the cage. So the design question is not "what memory format is best" — it's "who owns the bytes, and can I walk away with them."

The portability test

Before adopting any memory system, run one check: if this tool disappeared tomorrow, what would I still have?

If the answer is "a directory of files I can read with cat and a database I can open with sqlite3," you own your memory. If the answer is "a support ticket asking for a data export," you're renting it.

We built our agents' memory to pass that test, and the architecture is boring on purpose.

Two stores, both yours

We split memory into two tiers, and neither one is locked to the tool that reads it.

Short-term memory is plain markdown. Each agent role has one file — mistakes, recent learnings, a short session log — capped at 80 lines so it can't bloat the context window. It lives in the repo. It's diffable in pull requests, greppable from any shell, and editable by hand when an agent records something wrong. No format, no API, no parsing step beyond "read the file."

The portability win is almost too obvious to state: a markdown file is readable by anything. Any agent, in any tool, in any language, can load it as context. There is no migration, because there is nothing to migrate from.

Long-term memory is SQLite plus embeddings. Unbounded history — every rejected design, every defect pattern, every exhausted idea — goes into a single SQLite file with an embedding column for semantic search. The agent calls search before acting and store after.

SQLite matters here precisely because it's a file. One .sqlite3 you can copy, back up, commit, or hand to a completely different program. The embeddings are computed with a standard model and stored as blobs; any tool that can run the same embedding call can query the same database. Move the file, keep the memory.

Separation by namespace, not by tool

A second trap in proprietary memory is bleed. If everything an agent knows lands in one undifferentiated pile, your marketing agent's context contaminates your security agent's reasoning, and project A's lessons leak into project B.

We key every entry by role and category — marketing/blog_rejections, security/findings, and so on. A search is scoped to one namespace, so an agent only recalls what's relevant to its job.

The portability angle: namespaces are part of our schema, not the vendor's. Because we define the separation in our own table, it survives a tool switch intact. Lock-in often hides in exactly this kind of structural metadata — the relationships a managed store builds around your data that don't come with you when you leave. Owning the schema means owning the structure, not just the rows.

Export isn't a feature — it's the default

The mindset shift is this: portable memory treats reading and copying as the primary access path, and the tool's own API as a convenience layer on top.

When the storage is files, export is free. There's no "export button" to build because there's nothing trapping the data in the first place. A nightly cp is a backup. A git commit is a migration plan. Pointing a new tool at the same directory is onboarding.

Compare that to the rented model, where export is a project — a ticket, a format negotiation, a one-time dump that's already stale by the time it lands. The difference isn't effort. It's ownership.

The honest seam

Portability has a real cost, and pretending otherwise would be dishonest. Plain files and a local database mean you run the embedding calls, you manage the backups, you own the dedup logic that stops the same lesson from being stored fifty times. A managed store does that work for you, and that convenience is genuinely valuable right up until the day you want to leave.

We made the trade deliberately: the operational overhead of self-hosting in exchange for never having a migration that can't happen. For a business run by agents that we expect to outlive any single tool generation, that trade is obvious. For a weekend project, a managed store might be the right call — as long as you go in knowing what you're renting.

There's also no settled standard yet. Several competing protocols are trying to become the portable-memory layer, and it's too early to crown one. That's an argument for keeping your memory in formats you control — files and SQLite — rather than betting the farm on a protocol that may not win.

What we extracted

This pattern is the basis of Agent Cerebro, the open-source memory layer we pulled out of our own stack. It's framework-agnostic and self-hosted by design — store and search over a local SQLite file, with semantic dedup so the same lesson doesn't pile up. We lead with the pattern, not the product, because the pattern is the point: the value isn't the tool, it's that your agent's memory keeps working after the tool is gone.

The test stays the same no matter what you build on. Pick up your agent's entire memory, drop it next to a different tool, and ask whether it still works. If it does, you own it. If it doesn't, you were only ever borrowing.

Next time: what happens to a lesson when one agent hands work to another, and the context degrades a little at every hop.