Back in July I published What’s New in My AI-MEMORY, where I showed off ai-memory run: switching from Claude Code to Codex without losing your line of work. That day we were on version 1.17.1.

Today 2.0 shipped. And this time I’m not going to rehash how the hooks work or how a session turns into a wiki page. That’s already in the earlier posts. Here I want to talk about where ai-memory landed against the competition, what 2.0 brings, and why it earned the jump to a “2”.

If you’ve never heard of the project, the summary is short. ai-memory is a long-term memory server for your coding agents. It captures what happened in the session, consolidates it into Markdown pages, and hands the right context to the next agent, whatever the harness or the machine.

This is the web interface that comes with it, handy for auditing what the agents wrote and for browsing between projects. Notice how each project lives separately, with its own page count, all of it coming out of real sessions.

Why it became 2.0

For me, the first digit of a version carries a commitment.

The 1.x line grew too fast. We went from 1.1 to 1.39 in a little over two months, stacking feature on top of feature in minor releases. It worked for iterating, but it blurred what the numbers meant.

2.0 fixes that. It bundles the few compatibility-breaking changes into a single major, and from here on versioning follows real Semantic Versioning. A fix is a patch. A new feature is a minor. Only a format or contract break is a major, and always with warning. The new contributing guide spells that rule out for any PR.

The main break is the new on-disk format. The first time you bring up 2.0, it migrates your wiki on its own. Before touching anything, it compresses your entire data directory into a verified backup with the date in the name. If the backup can’t be written and checked, the migration aborts and the server refuses to start. No “trust me”.

This is the notice that shows up once, right after the migration: it tells you where the backup landed, the file size, and how to roll back if something looks off. Once you confirm everything is fine, you just delete the backup and the reminder disappears.

OKF: your memory isn’t locked inside ai-memory

This is the change that made me happiest.

Starting with 2.0, the ai-memory wiki is, natively, a bundle in the Open Knowledge Format, the open format Google published in 2026. Each memory page is a valid OKF file: plain Markdown with standardized metadata. There’s no export step that produces a divergent copy. The wiki files already are the OKF files.

In practice that means your memory stopped being a hostage of my project. You can read it all with grep, open it in Obsidian, version it in Git, or hand the bundle to a coworker who uses another OKF-compatible tool. There’s even an ai-memory export-okf to package a whole project into a validated tarball.

That was always the thesis: the model and the harness are rented, the project’s memory is yours. Now the format backs that up in writing.

Local embeddings, on by default

Up through 1.x, real semantic search depended on you configuring an embeddings provider. Either you paid for an API and sent every page and every query out, or you spun up an Ollama on the side. Both options have a cost.

2.0 brings a local provider that runs the embeddings model inside the process itself, in pure Rust, with all-MiniLM-L6-v2. No API key, no external server, no GPU, and nothing about your data leaving the box. And now it comes on by default. On the first run it downloads the model (about 87 MB, with a fixed checksum) in the background and turns on hybrid search at the next restart.

The gain is measurable. On the LongMemEval-S benchmark, hit@5 goes from 0.617 with full-text only to 0.779 with the local embeddings. If for some reason you don’t want it, an embedding_provider = "none" turns it off.

A detail that matters: I chose candle on purpose, instead of the native runtime the competition uses. That native layer is exactly what caused a recurring kind of crash in other memory projects. I preferred not to inherit the problem.

Several agents at once, on the same project

Here’s where the part that drove most of the work before 2.0 begins.

The ai-memory run case I showed in July was sequential: I close Claude, open Codex, keep going. But what about when I leave two or three harnesses open at the same time on the same project? Claude in one tab, Codex in another, OpenCode in a third.

ai-memory handles that without anyone stepping on anyone else. Each memory call figures out on its own which project it belongs to, from the session’s directory. The “current project” pointer is now per actor, so two harnesses in the same checkout each keep their own sense of context. And the project’s identity comes from the checkout name. The absolute path on disk doesn’t count, so the same project on the laptop and on the desktop lands in the same place.

When two windows write to the same page, the second doesn’t erase the first. It creates a new version that becomes the latest, and the previous one stays reachable in the version chain. Writing something identical doesn’t create a new version. Every write goes through a single writer, with a queue and backpressure, so a burst doesn’t corrupt anything.

This isn’t theory. There’s an acceptance test calling Claude, Codex, OpenCode, Pi, Crush, and a few others for real, inside a single workstream, covering leases, session adoption, and context handoff between harnesses.

A whole team on the same project

The second scenario is the one that gives the post its title. Here it’s several people, a whole team pointing their agents at the same server.

The way to run it is simple. Someone brings up a server, usually a container in a homelab or on a machine on the network, and each person points their agents at that URL. HTTPS goes in front with a reverse proxy, if you want. The database is still a single SQLite.

Everyone sees the same project pages. What one person learned in a session, the other’s agent recovers. And each new session gets a briefing with the project’s state right at the start. I’ll be honest about the term “real time”. What exists is a shared central store, with immediate reads, plus the briefing at the open. The note a coworker wrote shows up right away for anyone’s next query or next session. A session that’s already running only gets the news at the next query or the next open, with no interruption mid-flight.

What changes in multi-user mode is attribution. Each write records who did it. There’s an audit log and the interface shows “edited by so-and-so”. That comes in the box, for free. And there’s no per-page permission, on purpose. Attribution is there to record authorship; anyone authenticated can write, and the history is what keeps track of who did.

There’s an important security distinction between what’s shared and what’s personal. The pages belong to everyone. But the handoff is a baton with a single owner: exactly one session takes it, and a second accept doesn’t steal the baton from anyone. The handoff you left pending isn’t delivered to or consumed by a coworker. Likewise, the “what I’m working on right now” slots are per person, so your personal context doesn’t leak into the whole team’s briefing.

There’s also a battery of real concurrency tests covering these cases: simultaneous writes, per-actor isolation under load, the handoff baton that doesn’t get stolen, and the personal slots that don’t leak.

Where ai-memory stands against the competition

Before 2.0 we did another round of research on the 2026 landscape, documented in the repository. It was the basis for deciding what 2.0 needed to cover. Let me summarize the field.

There’s agentmemory, a TypeScript MCP server tied to a native sidecar and a giant surface of dozens of tools. There’s basic-memory, in Python, Markdown on disk, but with manual capture: you have to ask it to remember. There’s cognee, which combines graph, vector, and relational into a heavy pipeline that wants several gigs of RAM. There’s MemPalace, which went viral with almost 50,000 stars in two weeks over a benchmark number that, once audited, turned out to be inflated, on top of suffering corruption when two writes happen together. And there are the temporal graphs like Zep, the “memory OS” like Letta (the old MemGPT), and the fact extractors like Mem0.

There’s also the native memory that Claude Code itself started turning on by default. I treat that one as the funnel that introduces the category to people. As a competitor it stays limited: tied to one machine, tied to one agent, without real search and without team history.

2.0 closes the gaps the research pointed out. We started publishing a reproducible benchmark with LongMemEval, running the actual server. We got the open OKF format. We got typed links between pages, with causes, fixes, and contradicts, which also feed a contradiction check without spending an LLM. We got queries with as_of, to ask what we knew about a subject on a given date. We got the local embeddings. And we got an optional “experience” pass that reviews several sessions to find patterns that only show up across the set.

Now the part that matters for whoever’s choosing. What ai-memory has that the others don’t, all together:

• It follows you across agents. More than twenty harnesses feed a single memory, and the handoff here is a real protocol: typed, with an owner, and claimed exactly once.
• It follows you across machines. The memory lives on a server that’s yours. The project you dropped on the desktop is the one you pick back up on the laptop.
• It works for a team. Multi-user authentication, per-person attribution, and an audit log come in the box, for free.
• Your memory is plain Markdown. The source of truth is a wiki versioned in Git. The database is a derived index you can rebuild at any moment from the files, with no vector store to babysit and nothing trapped in a binary blob.
• It captures the work on its own, quietly. No “remember this” ceremony. And the default path runs with zero LLM calls.
• It’s a single binary. No sidecar, no three databases to sync. Every write goes through a single writer, with a write ceiling we actually measured, with a real test. That design is exactly what avoided the concurrent-write corruption that took the others down.

No competitor delivers this set. Some have one piece or another. ai-memory has the whole package, and now with parity on the items where it used to fall behind.

2.0 belongs to everyone

When I wrote the July post, fifteen people had a merged PR in the project. Today it’s around seventy. This stopped being a weekend project a long time ago.

The numbers up to 2.0: more than 1,500 commits, 371 merged pull requests, and 181 closed issues. That came from people actually using it and sending fixes, features, and documentation.

I have to give special thanks to Djalma Júnior, who on his own passed 50 merged PRs, and to Samir Hanna Verza, with more than 20. Right behind come lhzapata, pedrofjr, mrpaiva, lucasliet, lihuiyang1024, Murillofilho86, and Matheus Rodrigues. And there’s a long tail of dozens of other people with a merged PR that it would be unfair to try to list in full here.

If you want in on this, the contributing guide was rewritten to make everything clear: how to set up the environment, the gates the CI enforces, the CHANGELOG rule, and the versioning policy. A bug fix usually ships fast in the next patch. A small feature, like a new harness or provider, goes into the next minor. There are issues tagged for people just starting out.

How to get 2.0

The project page has every install method, including AUR, Homebrew, and release binaries:

• ai-memory on GitHub
• v2.0.0 release notes

After updating, on the first run let the migration take the backup and convert your wiki to the OKF format. If you use the managed mode, reinstall the hooks for the harnesses you plan to use.

Conclusion

1.x proved the idea worked. 2.0 is the version I’d recommend without an asterisk for someone else to put on a team.

The format is open, so your memory doesn’t get locked in. Semantic search runs local, so you don’t pay and you don’t leak. Several agents and several people work on the same project without running each other over. And the single-binary, single-writer design is what avoids exactly the problems that sank half the competition.

The LLM and the subscription I keep renting from whoever’s best that month. The project’s memory stays with me, with the team, and now in a format nobody can take away from me.

Version 1.1.0 shipped that same day. Today, July 20, we’re at 1.17.1.

Version numbers alone don’t mean much, so I counted what actually happened after that post went live: 31 releases, 55 merged pull requests, and 46 closed issues. I counted 24 groups of new user-facing features in the CHANGELOG, ignoring fixes, documentation, and internal details from the same delivery. If I split the new ai-memory run family into auto-selection, session adoption, Crush support, --yolo, search, and recovery, we’d blow past that number.

Fifteen people had PRs merged during that period, fourteen besides me. Special thanks go to Djalma Júnior, who alone had 24 PRs merged, Matheus Rodrigues, with five, lhzapata, with four, Thiago Silva and Cristiano Dewes, with two each. Nine more contributors had a PR merged. This stopped being “a little program I made over a weekend” a while ago.

I’m not going to dump 55 PRs here. I want to talk about the change that affects my daily use the most: the new ai-memory run.

The session is part of the project too

Code is the result that survived. It doesn’t preserve the entire investigation.

Git shows that you replaced Redis with SQLite. Maybe the commit explains part of it. But where is the Redis experiment? Where is the intermittent bug that only showed up with two workers? Who remembered that the first solution broke on Windows? Why did the team change its mind after three hours? Which workaround was temporary, and which one became the decision?

Much of that exists only in the agent session.

When I program with Claude Code or Codex, the session accumulates the project’s operational reasoning: questions, corrections, discarded attempts, test results, surprises, decisions, and changes in direction. The final code shows what stayed. The session explains how we got there.

And an LLM session, at the end of the day, is text. Claude Code writes JSONL. Codex does too. OpenCode uses SQLite. Pi, OMP, and Crush have their own formats and directories. Each harness packages the conversation differently, but the visible content is still messages and tool results.

Why should I leave the most expensive part of the work trapped inside the harness?

Anthropic can change limits, pricing, models, or formats tomorrow. OpenAI can too. An agent can be excellent this week and unbearable the next. I want to swap the engine without throwing away the whole trip.

That has been ai-memory’s thesis from the start: the programmer must remain independent of provider whims. Models and harnesses are replaceable. The project memory is mine.

Handoffs solved only half the problem

ai-memory already handled handoffs. I would close Claude Code, the hooks would consolidate the session, and the next Codex would receive a short summary with what had been done, open questions, and next steps.

That still exists and is still useful. Anyone who opens claude, codex, or opencode directly keeps the previous behavior. The new launcher is opt-in.

But a handoff is deliberately lossy compression. It preserves what seems most important at that moment. It isn’t meant to carry the entire session or resume each harness’s native session. If the summary left out an old attempt that became relevant again two hours later, you have to search the wiki or the records.

ai-memory run adds another layer: a managed workstream, one line of work that crosses harnesses.

Claude now, Codex in a little while

Basic usage looks like this:

cd ~/Projects/meu-projeto

ai-memory run claude
# work, then exit Claude Code normally

ai-memory run codex --yolo
# Codex continues the same line of work

ai-memory run claude --model opus
# return to Claude's previous native session

ai-memory run
# or let ai-memory choose the right harness to continue

You don’t need -- to separate arguments. Everything after the harness name goes to it, with one deliberate exception: --yolo belongs to the wrapper and is translated into the native dangerous option for Claude Code, Codex, OpenCode, Pi, or Crush.

Under the hood, ai-memory doesn’t try to convert a Codex file into a Claude file. That would be fragile and would probably break on the next update. Each harness keeps its own native session. The workstream connects those sessions to a portable ledger containing the visible part of the conversation.

Think of it this way:

Claude native session ─┐
Codex native session  ─┼─ workstream ─ portable context
OpenCode session      ─┤                 + full search
Pi native session     ─┘

The first time Claude enters that workstream, it gets a native session. When you switch to Codex, Codex gets its own native session and receives the portable delta it hasn’t seen yet. When you return to Claude, the launcher uses Claude Code’s own --resume and delivers only what happened in the other harnesses since the last visit.

This is very different from starting a new chat with a summary pasted into the prompt. Claude returns to its real session. Codex returns to its real session. ai-memory handles continuity between the two.

Managed mode currently supports Claude Code, Codex, OpenCode, Pi, Crush, and OMP. General ai-memory support is broader, with MCP and hooks for other clients, but that doesn’t mean every client already has a native-session adapter for run. Those are different contracts, and I prefer to make that explicit.

What goes into the workstream

When the harness exits, ai-memory reads the tail of the native session without modifying the original store. It imports visible user and assistant messages, completed tool calls with their results, compaction summaries, and a non-mutating Git checkpoint. Every event keeps its origin: Claude, Codex, OpenCode, Pi, Crush, or OMP.

Provider credentials, encrypted records, system and developer prompts, and hidden reasoning stay out. Private formats the adapter doesn’t understand stay out too and produce a loss annotation instead of letting the system pretend it imported everything.

Records pass through the sanitizer before entering ai-memory’s searchable ledger and immutable JSONL segments. The adapter opens native stores read-only; the harness itself remains the writer.

I don’t cram the entire session into the next prompt either. That would recreate the problem the project is trying to solve: too much raw context, too much cost, and too much noise. The next agent gets a size-limited recent delta. If an old decision matters again, the full ledger remains searchable:

ai-memory workstream-search "por que desistimos do Redis"
ai-memory workstream-search --limit 50 --json "migration que falhou"

Inside an ai-memory run, the workstream ID is already in the environment. The agent doesn’t have to discover some UUID.

And the ledger doesn’t replace the wiki. It handles operational continuity. Decisions, rules, procedures, and gotchas that need to survive for months still deserve consolidated Markdown pages. A raw session is evidence. A wiki is organized knowledge.

Can I keep more than one line of work?

Yes. The default workstream is called default, selected by repository and worktree. If I want an independent line for an investigation without contaminating the main work:

ai-memory run --new investigar-race claude

# later, continue that line with another harness
ai-memory run --workstream investigar-race codex

A lease prevents two windows from writing to the same workstream at once. On a normal exit, the launcher imports the tail of the session and releases it immediately. If someone kills the process without cleanup, the lease expires within 90 seconds and the next run resumes from the last confirmed cursor without duplicating imported events.

One stupid annoyance kept coming back: I would reopen a project after a few days and have no idea whether the newest session was in Claude or Codex. I’d guess, open one, realize the context was in the other, close it, and try again.

Now I just run:

ai-memory run

# or keep the same auto-selection in YOLO mode
ai-memory run --yolo

In an empty workstream, ai-memory looks for local sessions from that checkout in Claude Code, Codex, OpenCode, Pi, and Crush, finds the newest one, and opens the right harness for me. In an established workstream, server memory beats the file timestamp: it returns to the last harness attached to that work instead of accidentally adopting an old session that happened to receive a newer write. OMP remains available when selected explicitly, but it doesn’t participate in auto-selection yet.

On the first explicit run, the launcher can also offer existing sessions from the same checkout for adoption. You can start using it without abandoning the chat that was already open before you updated ai-memory.

Other new features I actually use

I promised I wouldn’t read the entire changelog out loud, but a few changes from this month deserve a mention because they reduce work for the programmer.

A briefing before the first question

A project can request an automatic briefing at the start of every session:

[briefing]
inject_on_session_start = "true"
max_chars = 4000

ai-memory assembles a package with pinned pages, _rules/, _slots/, and recent titles. The agent starts with the project’s rules and basic state instead of spending the first conversation rediscovering the architecture. It’s opt-in because it consumes context on every SessionStart, including after a Claude /clear.

Global preferences and cross-project search

Preferences that apply to all my work can now live in the reserved _global scope: coding style, preferred tools, personal rules, and conventions that don’t belong to one specific repository. Normal queries already combine that scope with the current project.

For meta-repos that need to query several sibling projects all the time, there is another opt-in:

[recall]
default_global = "true"

With that, memory_query and memory_recent without an explicit scope search every project. I don’t turn it on in every repo because gratuitous global search only adds noise.

Less static instruction, more Agent Skills

The routing block in CLAUDE.md or AGENTS.md got smaller. Detailed instructions for when to search memory, consolidate, save a decision, or create a handoff moved into managed Agent Skills. One command installs or updates both without trampling the rest of the file:

ai-memory install-instructions

That reduces drift too. When the protocol changes, I update the managed package instead of hunting down an old prompt copied across forty repositories.

Privacy before the network

Each repo can now exclude paths from capture:

[capture]
ignore_paths = ["private/**", "~/personal-notes/**"]

When an integration recognizes a file tool and the path matches, the event is discarded locally before spool, queue, network, or server. The limits are clear: this isn’t magic DLP, it doesn’t understand every shell command, and it doesn’t track content quoted in free-form text. But it handles the verifiable case without selling a fake guarantee.

There are also new integrations with Kimi Code, Grok Build CLI, Devin, and Zero, an OpenCode Zen/Go provider, finalize-session for Codex, and workspace-administration improvements. Again: having MCP and a hook doesn’t automatically mean having ai-memory run. The README separates those levels.

Bonus: ai-jail on the outside, YOLO on the inside

Just over a week ago I wrote about how I protect myself from agents deleting my stuff. My recommendation remains the same: YOLO mode gives the best experience, provided the system limits the possible damage.

ai-jail reached version 1.15.0 and now understands the ai-memory launcher. My favorite way to work has become:

ai-jail ai-memory run codex --yolo

Or, when I want ai-memory to choose which harness should continue:

ai-jail ai-memory run --yolo

Order matters. ai-jail stays on the outside so the launcher and child process remain inside the same sandbox. ai-memory run by itself manages the session, but it doesn’t create a sandbox.

--yolo gets rid of the harness’s approval ceremony. ai-jail handles containment: the current project is read-write, home is replaced with tmpfs, necessary parts of agent state are mounted selectively, and sensitive directories such as .ssh, .gnupg, and .aws stay outside the jail. The new support also keeps ai-memory’s local state writable so hooks can maintain spools and cursors between runs.

ai-jail recognizes both the ai-memory layer and the selected harness. If you have Codex-specific global configuration, for example, it still applies when the actual command is ai-memory run codex. Even the status-bar redraw adjustment understands that the child is Codex.

This combination takes care of both annoyances at once: the agent stops asking for confirmation on every command, and the session stops belonging to the agent. You get the speed without handing over your entire home directory.

One more thing: ai-usagebar grew too

When I published the original ai-usagebar, it monitored Claude, Codex, Z.AI, and OpenRouter in a Waybar widget or TUI. Version 0.14.0 already covers eleven usage, spending, or balance integrations.

Kimi got the two pieces of information that really matter for coding: weekly subscription quota and the rolling five-hour window. Kilo, Novita, Moonshot, and Grok show remaining balance. A separate Anthropic Console integration shows API spending for the month without conflating it with the Claude Code subscription. It makes clear that the Cost API doesn’t include Priority Tier.

You can also register multiple Anthropic accounts, see weekly limits for specific models such as Fable, and get a pace marker. The bar doesn’t turn red just because it reached 40%; it compares the percentage spent with how much of the window has passed. If I used 40% in 20% of the week, I’m moving too fast. That’s the useful information.

The project outgrew Waybar. It has a native macOS menu bar app, a GNOME extension, and a standalone TUI. The newest addition is a local Claude Code context monitor: I press c, choose one of the recent sessions, and see how much of the window it has consumed. It reads limited tails from local JSONL files and doesn’t invent a percentage when it can’t determine the window size.

In my workflow, the three end up working together. ai-usagebar shows which subscription still has room. ai-memory run switches harnesses without throwing away the work. ai-jail lets the chosen one run in YOLO without unrestricted access to the machine.

Updating

The installation pages for all three projects cover every method, including AUR, Homebrew, and release binaries:

• ai-memory
• ai-jail
• ai-usagebar

After updating ai-memory, reinstall the hooks for the harnesses you plan to use in managed mode. The three main ones in my case:

ai-memory install-hooks --agent claude-code --apply
ai-memory install-hooks --agent codex --apply
ai-memory install-hooks --agent opencode --apply

Crush doesn’t need a hook in managed mode; it receives context through a temporary file configured only for the launched process. The managed workstreams documentation covers installation, privacy, recovery, and native arguments for each adapter.

Conclusion

A month ago, ai-memory could already turn a session into a wiki and hand off to the next agent. Now it can manage the line of work itself: adopt an existing session, keep one native session per harness, carry visible history, resume each client in its own format, and keep the entire ledger searchable.

For me, that’s the value. The code contains the implementation that won. The session contains the decisions, failed experiments, gotchas, unexpected bugs, and changes of mind that produced that implementation. Throwing all of it away every time you change providers is wasteful.

A raw transcript doesn’t solve the problem by itself either. It’s large, repetitive, and expensive to stuff into every context. ai-memory keeps the evidence, delivers only the recent delta, and uses consolidation to turn what deserves to survive into short Markdown pages.

There are still new formats to support, platform rough edges, and plenty of testing ahead. The difference is that there is now a real foundation, with an acceptance test that calls actual harnesses, 14 outside contributors with merged PRs in a little over a month, and daily use pushing the design forward.

I rent LLMs and subscriptions from whoever is delivering the best service today. My project’s session stays with me.

Today I want to talk about the other side: what this is useful for day to day, and how the project now incorporates an idea inspired by Hermes Agent: a self-improvement loop with validation, an audit trail, and an optional manual review mode when you want more control.

If you dropped in cold, the sequence so far is:

1. First I wrote about agent memory, Karpathy LLM Wiki, and agentmemory. Back then I was still evaluating the original agentmemory.
2. Then I published the main post: I built a memory system for coding agents: ai-memory. That one explains the foundation of the project.
3. In the AI toolkit post, I placed ai-memory next to ai-jail and ai-usagebar: small tools for real pain points when you use agents every day.
4. Yesterday came the emergent architecture post, showing how the project evolved with contributors.

This post is the practical continuation. ai-memory turns long development sessions into a project wiki that an agent can query weeks later, without turning you into the human cache for project context.

The real problem: long sessions become long amnesia

Anyone using Claude Code, Codex, OpenCode, Cursor, Gemini CLI, or any of these agents knows the cycle. You start a session, explain the project, show the important files, correct a hallucination, find a trap, decide on an architecture, run tests, fail, fix, run again. After two hours, the agent is finally warmed up. It knows what not to do. It knows where the holes are. It knows that one function looks wrong but exists for legacy compatibility. It knows the test only passes if service X is running first.

Then the session ends.

The next day you open another agent, or the same agent in another window, or you switch from Claude Code to Codex because you want to compare. And it starts again. “No, this project uses that.” “No, we already tried that.” “No, that API does not exist.” “No, that file is generated.” You become the agent’s cache.

A large context window only helps up to a point. It belongs to the current session, not to the whole month of work. And raw context is still raw context. Dumping one hundred thousand tokens of logs into a prompt is different from having a short page that says:

• decision: SQLite is a derived index, markdown is the source of truth;
• trap: on Windows, do not trust inode, use our own index;
• rule: do not edit content/_index.md by hand, run the generator;
• procedure: to publish a new post, write PT first, humanize, validate Hugo, translate only after approval.

That is useful memory. Not a transcript. A synthesis.

The mental model: Karpathy Wiki

The name I like for this pattern is what Karpathy called an LLM Wiki: instead of depending on raw history, you maintain a versioned markdown wiki that the agent can query. Small pages, stable names, separated by type of knowledge. The agent does not need to remember everything. It needs to know how to search.

ai-memory implements this with a simple idea: hooks capture what happened, the server organizes that material into a markdown wiki, and agents query that wiki when they need to continue the work.

Some pages are session summaries. Others become decisions, traps, procedures, or project rules. The user does not need to memorize the taxonomy. The point is that knowledge stops being trapped inside the chat window and starts existing as readable files.

Notice that last part: markdown is the source of truth. You can open it in Obsidian, grep it, version it, back it up with rsync, inspect a git diff. SQLite helps with search, but it is a derived index. If I throw the database away tomorrow, the system can rebuild the index from the wiki.

This is where I get stubborn. I want a file I can read, not a black box of embeddings that “maybe” remembers.

The base: memory that crosses agents

From early on, ai-memory solved the main pain: context that survives the agent you happened to be using.

You could end a Claude Code session, open Codex in the same directory, and the next agent would receive a short summary of where things stopped, which questions were still open, and which next steps made sense.

On top of that, the agent could query the wiki before answering. Instead of depending only on what still fits in the context window, it could search old decisions, known traps, recent pages, and permanent project rules.

In practice, the agent stops guessing about architecture. It can ask: “what did we decide about auth?”, “did we already try Redis here?”, “what was the Docker trap in this project?” And the answer does not come back as a thousand raw events. It comes back as a wiki page.

In software projects, this matters because the most useful knowledge is usually not “which file exists.” The agent can find that with grep. The expensive knowledge is why something is that way. Why we did not use library X. Why this test is strange. Why the CI config has an exception. Why that refactor was postponed.

That is what long-term memory needs to preserve.

What came from real use

Yesterday I mentioned some numbers and thanked contributors, but it is worth calling out the newer capabilities because they changed the shape of the project. ai-memory stopped being “my local daemon” and became something you can run on a homelab or shared server.

The short version of the changes is:

• It works for one person or a team. The system now understands users, projects, and workspaces. That makes it possible to run it on a homelab or shared server without mixing clients, repositories, and sessions.
• Scoping became predictable. A .ai-memory.toml file can say which project a directory belongs to. That helps with monorepos, worktrees, consulting, and personal/work separation.
• More agents can participate. Beyond Claude Code, Codex, and OpenCode, there is support for Cursor, Gemini CLI, Antigravity CLI, Grok Build CLI, OpenClaw, Oh My Pi/OMP, VS Code GitHub Copilot, and Claude Desktop. Some have full hooks, others can only query through MCP, but all of them can benefit from the same wiki.
• Administration and recovery became less fragile. Renaming or moving projects, restoring pages, rebuilding the index, using the web UI, and auditing changes are boring to explain, but important once the tool becomes part of daily work.

I will not go through every detail here. That is what the GitHub documentation is for. The important shift is the category change: this stopped being my local daemon and became shareable project memory.

This came from real use. Djalma Júnior, wlech, Pedro de Freitas Jr, Mauro Couto de Paiva, Gustavo Cateim, Lucas Oliveira, Pablo Winter, azevedo-luis, zanlucathiago, and others pushed the project into cases I had not planned for. That is how software grows without becoming PowerPoint architecture: need pulls the architecture, not the other way around.

Auto-improve: sessions become memory

Today, ai-memory has a safe self-improvement loop: when an LLM provider is configured, a background job can review new sessions, separate noise from real learning, and turn useful lessons into durable wiki pages.

That is what matters for the user: you do not need to remember to open a notes file at the end of the day, or manually write “session learnings.” If the session revealed a decision, a reproducible trap, or a procedure worth repeating, the system can promote it into project memory.

Under the hood, it uses the consolidated session, looks for strong signals, asks an LLM to suggest small edits, validates paths, evidence, size, and confidence, records the proposal in an audit trail, and applies the write through the normal wiki path.

If you want human review before the final write, set [auto_improve] require_approval = true. Then proposals stay pending until someone reviews, approves, or rejects them.

In the architecture diagram above, this sits on the maintenance side, in the work that depends on an LLM provider. It is not in the hot hook path. That is intentional. Hooks need to capture quickly, return 202 or 429, and get out of the way. LLM review is a different class of work.

The important detail: this does not enter the agent’s hot path.

The user keeps working normally. Hooks capture the session. The handoff stays short and actionable. auto-improve runs as maintenance: it looks back, identifies what deserves to survive, and turns learning into queryable memory. The feature exists to answer one question:

“What did this session teach us that is worth turning into permanent memory?”

And the answer becomes reusable knowledge, with proposal trail and evidence, not a loose guess inside the prompt.

That may sound small, but it is the difference between useful memory and an agent polluting your project with confident junk. If you let an LLM write a rule every time something goes wrong, in one week your wiki becomes a graveyard of superstition: “never use tool X,” “always run command Y,” “library Z is broken.” Many of those problems were temporary: wrong PATH, expired token, network down, outdated dependency, a bug fixed five minutes later.

Bad memory is worse than no memory. No memory makes you ask. Bad memory gives you false certainty.

What Hermes Agent is

The inspiration came from Hermes Agent, which treats learning as part of the normal agent cycle. After doing the work, it can look back and ask: “did this create any memory or skill that will help next time?”

What interested me was the separation. The agent does the work first. Then, in the background, it reviews what happened. There is also slower maintenance that looks for stale, duplicated, or low-value knowledge. One loop learns from the session; the other cleans the garden.

That separation avoids the common mistake of creating a magical daemon that changes everything all the time. It sounds powerful, but it becomes impossible to trust. If you want the details, I left them in the auto-improvement loop documentation.

How we adapted Hermes to ai-memory

ai-memory does not copy Hermes literally. Hermes works with memories and skills. ai-memory works with wiki pages. So the adaptation is simple: when a session teaches something useful, the system tries to turn that into a small, readable, queryable page.

The LLM suggests, but the product imposes boundaries. The suggestion needs evidence, a valid path, reasonable size, and minimum confidence. That keeps a messy session from contaminating the whole wiki.

The current shape is this:

1. The session ends and becomes sessions/<id>.md, as before.
2. A background job reviews eligible completed sessions after the first-run watermark and configured minimum age.
3. The reviewer looks for decisions, traps, procedures, and rules worth keeping.
4. The system validates the suggestion and records an audit trail.
5. By default, the memory enters the wiki; if you want, you can require manual review first.

That trail is the missing piece between “the LLM suggested it” and “this became project truth.” Project memory cannot be a black box.

What should become memory

This part matters more than the tool: not everything that happens in a session deserves to become permanent memory.

What is worth keeping is whatever helps the next agent work better: a decision with future consequences, a reproducible trap, a procedure that will repeat, an explicit user preference, or an important project pattern.

What is not worth keeping is noise: a test command, a transient error, a failure caused by that day’s environment, or a whole session narrative that is already preserved under sessions/.

That filter is the difference between a wiki that helps and a wiki that gets in the way. auto-improve does not exist to capture more things. It exists to selectively promote what deserves to move out of the episodic layer and into durable project memory.

Hooks, MCP, and prompts: the part that makes it usable

The other half of the system is less glamorous, but it is what makes the thing feel natural. The user works normally. Hooks capture the session cycle. MCP gives the agent a way to query memory. And the instruction block in CLAUDE.md or AGENTS.md teaches when to use all of it.

When the integration is complete, the experience becomes almost invisible: you close one session, open another tool, and the next agent can orient itself. When a client only supports MCP, it can still query the wiki, even if it cannot capture the full lifecycle.

The important detail is not the specific hook format of each tool. That is in the installation documentation. The important part is that ai-memory tries to hide those differences and give the agent a simple behavior: before deciding, consult memory; when it learns something durable, preserve it.

Why this makes coding sessions smarter

The flow I want is this.

You open OpenCode in an old project. Before answering anything serious, it knows to query ai-memory. It finds an existing database decision. It finds a build trap. It finds a handoff from the last agent saying the test failed in PaymentImporter. You do not need to retell the whole soap opera.

During the session, hooks record what happens. At the end, the session becomes a short narrative. If it was a rich session, the auto-improve job can turn the lessons into pages like:

• gotchas/payment-importer-timezone.md;
• decisions/use-ledger-table-for-reconciliation.md;
• procedures/run-importer-smoke-test.md.

In the default mode, this enters as validated, auditable memory. In manual mode, you inspect the diff, approve, or reject. Next week, another agent can query it and avoid stepping into the same hole.

That is the cycle I want: work becomes knowledge, knowledge improves the next work. No prompt religion, no infinite context window, no blind trust in opaque memory.

Be careful with the word “auto”

There is a marketing trap here. “Self-improvement” sounds like science fiction: the agent learns by itself and gets better forever. I do not want to sell that, because it becomes a lie quickly.

What exists today is much more grounded: a job that reviews sessions, suggests memory, validates the suggestion, keeps evidence, and applies through the normal wiki path. If you prefer, there is a manual review mode before the final write. And precisely because it is limited, it is useful. The active prompt and hook latency stay protected. The system observes, filters, validates, and leaves a trail.

That is the right boundary for a system like this right now. Auto-approval only after structural validation and evidence. Human review when the project needs it. Trust is earned with history, not enthusiasm.

Closing

ai-memory started as a simple answer to a simple frustration: I got tired of re-explaining the same project to different agents. In a few weeks it became a versioned wiki, with hooks, MCP, handoff, multi-user mode, multi-workspace support, marker files, support for several CLIs, web UI, recovery, and now a Hermes-inspired self-improvement loop with validation and audit instead of blind faith in the LLM.

The philosophy is still the same: good memory organizes knowledge into small, readable, versioned, citable pages. It turns a long session into a decision, trap, procedure, or rule. It lets the next agent start where the previous one stopped.

If you use agents for real software projects, this is the bottleneck that starts hurting first: continuity. A better model alone will not fix it.

The repo is here: github.com/akitaonrails/ai-memory. If you already use it with an LLM provider configured, update and let auto-improve work in the background on new completed sessions.

If you want manual review before applying, configure:

[auto_improve]
require_approval = true

In manual mode, do not accept everything. That is the point. Read, criticize, approve only what deserves to become memory. In the default mode, follow the audit trail when you want to understand what was promoted and why.

So here’s the thing. In three weeks this little project grew in a way that deserves a post about the process alone, because it became a living example of something I’ve been preaching for years: real software is grown, like a plant. Nobody builds good software piece by piece the way you snap a Lego together. Let me show you the numbers, and mostly the story they tell.

The numbers, today

ai-memory has, in 24 days of life (from the first commit on May 21 until now):

• 482 commits on main, averaging 20 a day.
• 26 people committed to the repo.
• 10 Rust crates in the workspace.
• ~62.7k lines of production Rust, plus ~11k lines of tests in tests/, more than 1,000 test functions, and 90 #[cfg(test)] modules scattered through the code.
• ~19.7k lines of markdown documentation (docs/).
• 70 pull requests, of which 59 merged (84% acceptance).
• 27 issues, 100% closed.
• We cut v1.0.0 on June 12 and we’re already on v1.0.6.

Twenty-four days. Hold onto that number, because the interesting part isn’t the final size, it’s the way it got here.

How it started: one of everything

ai-memory was born small and dumb on purpose. In the first two days I nailed down the whole skeleton: workspace bootstrap, MCP server, hook capture, cross-agent handoff, git wiki versioning, an LLM provider trait, embeddings. All of it running for one user, one machine, one workspace, one architecture (Linux, basically). No multi-user, no permissions, no scopes, no Windows or macOS support. It was my agent brain, on my machine, for me.

On day 3, when the first external contribution landed (a fix from Lucas Oliveira for OpenAI-compatible provider URLs, PR #6), the project had 102 commits and around 22.9k lines of source. Already the same 10 crates as today, but with a fraction of the functionality. It was a one-of-everything MVP that worked for me and nobody else.

And this is where most projects die, or worse, where most inexperienced programmers get it wrong.

The Lego fallacy

There’s a widespread belief, especially among people starting out, that you can design everything a piece of software will be before writing the first line. You sit down, plan the entire architecture, break it into neat little pieces with all the folders and layers and interfaces mapped out, and then build it piece by piece. When the last Lego brick clicks in, the software is done. Beautiful on paper.

In practice, it’s the fastest road to rotting code. The sooner you crystallize a structure, the sooner it becomes a straitjacket. You predicted an elaborate permission system before having any users? Congrats, now you carry the weight of maintaining an abstraction nobody uses, and that’s almost always wrong, because you designed it guessing the future instead of answering a real need. The inexperienced programmer over-engineers at the start, and no matter how much they plan, the result starts to rot fast, because they’re solving problems that don’t exist yet and getting wrong the ones that do.

I don’t believe in software that finishes. I already wrote about this in “Software Is Never Done”, and it connects straight to the original Agile methodologies, the real ones, before they turned into a corporate post-it ritual. Good software is a clay sculpture: malleable, always wet, that you keep adjusting and reshaping, and that never gets finished. It’s clay you mold while it’s being used. The Lego tower that one day clicks into place and is done is a fantasy.

What the contributors built

And this is where the best part of open-sourcing it comes in. That one-of-everything MVP became a cross-platform, multi-user system because a lot of people put their hands on it. I want to thank them by name, because without these people the project would be a fraction of what it is:

Djalma Júnior drove a big chunk of the heavy architecture (multi-user, admin, cross-project recall), with 25 merged PRs. wlech with dozens of commits. Pedro de Freitas Jr on embeddings and web fixes. Mauro Couto de Paiva and Gustavo Cateim drove a big part of the Windows support. Pablo Winter, Lucas Oliveira (author of the first external PR), and Said Rodrigues, among many others. Thank you so much, folks.

What those contributions added, the highlights:

• Real Windows, macOS, and Linux support. What was Linux-only got macOS bash 3.2 compatibility, an NTFS file index for tracking inodes on Windows, and native per-platform hook commands.
• Frontend API (/api/v1) and a customizable web UI. It stopped being only MCP + CLI and got a real HTTP surface, with clickable wiki links and search by file path.
• Multi-user with attribution. A users table, writer/reader commands, and write attribution in the same SQL transaction as the data (pages.author_id + frontmatter).
• Multi-workspace and cross-project recall. Global search, links between wikis of different projects, and active-project isolation per session and per actor.
• More providers and more agents. Gemini, Copilot via OAuth, OpenAI-compat strict mode; plus support for Antigravity, Grok, and VS Code Copilot on top of the originals.
• Operational robustness. Checkpoint recovery, reindex-from-wiki to rebuild the index from the markdown, self-describing _meta.md manifests.

Notice something: none of this was in the original plan. There was no original plan. Each of these features landed because someone needed it, opened an issue or a PR, and the structure gave way to make room. Multi-user wasn’t predicted: it emerged.

And only now did we stop to consolidate

Here’s the central point of the post. Over these three weeks, the code grew a little messy on purpose. When multi-user support came in, the logic for “which workspace and project is this request aiming at” ended up embedded right in the middle of several handlers in the MCP server, the web API, the admin, scattered and duplicated. Each spot resolved scope its own way. There was duplication. There was code that wasn’t pretty. And that’s fine, because it was working, and working for a lot of people.

Only after the software was already running on dozens of people’s machines, across three operating systems, with real multi-user in production, did I stop and say: “okay, now is a good time to refactor and rethink the internal wiring.” The second-to-last big commit, refactor: centralize scope auth and wiki consistency, did exactly that, with 1,239 lines added and 249 removed, creating a central 601-line ScopeResolver and a consolidated ActorContext.

Look at the “before.” This scope-resolution snippet lived duplicated, with variations, across several methods:

// BEFORE: scope logic embedded, repeated in every handler
let active = self.active_project.get_for(actor);
if let Some(name) = explicit_project.map(str::trim).filter(|s| !s.is_empty()) {
    if let Some((active_ws, _)) = active
        && let Ok(Some(pid)) = self.reader.find_project(active_ws, name.to_string()).await
    {
        return Ok((active_ws, pid));
    }
    if active.map(|(ws, _)| ws) != Some(self.workspace_id)
        && let Ok(Some(pid)) = self
            .reader
            .find_project(self.workspace_id, name.to_string())
            .await
    {
        return Ok((self.workspace_id, pid));
    }
    return Err(McpError::internal_error(
        format!("project '{name}' not found in the active or default workspace"),
        None,
    ));
}
Ok(active.unwrap_or((self.workspace_id, self.project_id)))

And the “after.” The same resolution, now delegated to a single authority in the store crate:

// AFTER: one central resolver, one call
fn scope_resolver(&self) -> ScopeResolver<'_> {
    ScopeResolver::new(&self.reader, self.workspace_id, self.project_id)
        .with_writer(&self.writer)
        .with_active_project(&self.active_project)
}

// ... and each handler becomes this:
self.scope_resolver()
    .resolve_current_or_project(explicit_project, actor)
    .await
    .map(ai_memory_store::ResolvedScope::as_tuple)
    .map_err(Self::scope_error)

Three different methods that each used to carry 30 lines of embedded logic, with lookup_ids, workspace fallback, and their own error handling, collapsed into one call each. Alongside came the sibling commits: harden multi-user admin auth boundaries and prevent scoped fallback bleed. Centralizing permissions, workspace and user scope, and wiki consistency, all in one place, with a clear rule.

The detail that matters: ScopeResolver wasn’t invented at the start of the project by guessing there’d be multi-user one day. It was extracted from code that already existed, already worked, and had already shown, in practice, which patterns kept repeating. The abstraction came after the usage, not before. I let the structure emerge from the code, and only once it was obvious did I consolidate it.

The right order: make it work, make it right, make it fast

This is the summary of everything. There’s an old saying, attributed to Kent Beck, that I carry like a mantra: “make it work, make it right, make it fast.” Make it work, then make it right, then make it fast. In that order. Most inexperienced programmers want to make it “right” and “fast” before making it “work,” and so they invent rules with no code to justify the rule.

ai-memory followed the right order without me even thinking much about it. First I made it work for one person, simple scope. Then I made it work one feature at a time, refactoring and hardening the code along the way, but never falling into over-engineering and never rewriting from scratch to fit a preconceived structure. I let the current structures emerge from the code that was being added. That meant living with some duplication and some so-so code for a while, until that moment hit of “okay, now it’s time to refactor and rethink the wiring.” And only now, with the software mature and in use, did I establish better patterns and rules for new code. Rules backed by real code, not by guesswork.

KISS, “keep it simple,” is about not solving a problem you don’t have yet. It has nothing to do with writing little code. It’s about letting architecture emerge from the code, not the other way around. You don’t design the sculpture and pour the clay into the mold. You take the clay, start shaping, and the form appears as your hands work. The mold, if you ever need one, you build later, around the form that already exists.

Twenty-four days, 482 commits, 26 people, and none of them followed a diagram drawn on day 1. Because there was no diagram on day 1. And that’s exactly why it worked.

ai-memory is open source and keeps changing every week: github.com/akitaonrails/ai-memory. Want to help shape the next piece? There’s an open issue waiting.

I’ll repeat something important before someone starts cloning all my repositories thinking they are 1.0 products: most of the frank-* projects on my GitHub are proofs of concept. Experiments. Some work well for me, in my environment, in my workflow. That does not mean they are ready to become a critical dependency in your company tomorrow morning. Want to play, contribute, study? Great. Just don’t confuse “I published it on GitHub” with “this is production ready.”

There are exceptions. FrankMD, for example, received a decent amount of contributions, tests, polish, real bug fixes, real use. Today it is much more stable than it was in the first post. Still, the point stands: these projects were born as a vibe-coding lab, not as a 3-year product plan with roadmap, enterprise support, and SLA.

This post is a roundup of what I learned in that lab. A few of my tools, a few habits, a few recommendations. Nothing mystical. No “revolutionary new way to program.” Old engineering with new tooling.

First: stop collecting agents

If you are a normal developer, you do not need 12 agents, 40 wrappers, 7 orchestrators, and a Kubernetes diagram to choose who gets to write an if.

In practice, focus on Claude Code, Codex, or opencode. That’s it.

Yes, Gemini CLI exists. Yes, Cursor exists. Yes, Windsurf, Crush, OpenClaw, Pi, Aider exist, and tomorrow another half-dozen will show up. I tested a bunch. Read my LLM benchmark posts, especially “LLM Benchmarks Part 3: DeepSeek, Kimi, MiMo”. The conclusion is boring and obvious: today, the best cost-benefit options for heavy programming are Opus 4.7 and GPT 5.5 on subsidized Pro/Plus/Max plans. Nothing comes close when the job is spending several hours a day with a real coding agent.

Paying directly for tokens is expensive. Paying for a subsidized monthly plan is much cheaper. That’s why I keep alternating between Claude Code and Codex: not because I want “multi-agent architecture,” but because the plans have limits and I work many hours in a row.

Are DeepSeek v4 and Kimi 2.6 cheaper? Yes. Are they usable? Yes. I like them for several cases. But for Agile Vibe Coding the way I’ve been advocating since “From Zero to Post-Production in 1 Week”, they are still lacking. They stumble more on continuity, long refactors, tests, understanding the whole project. Can you use them? Sure. But if the goal is consistent productivity, Opus and GPT are still the bar.

Running an open-source model locally is neat. I played with that a lot in the Minisforum MS-S1 Max with AMD AI Max+ 395 review. For one-shots, studying, playing with local inference, it’s fun. For Agile Vibe Coding all day, every day, it is still not practical. Latency, context, quality, setup maintenance, VRAM, all of it collects tax.

Running multiple LLMs in parallel is not practical either, the whole “planner + executor + reviewer + judge” routine. I tested that in “LLM Benchmarks: Is It Worth Mixing 2 Models?”. The idea looks nice on paper. In practice, it increases cost, latency, error surface, and the gain does not pay for the complexity.

The secret is not having a bunch of agents. Forget OpenClaw or Pi for day-to-day programming. The secret is engineering process. XP. Tests. Clean Code for AI Agents. CI. Pair programming. Constant refactoring. Small code. Automated deploy. Fast feedback.

Tools help. Engineering wins.

ai-jail: autonomy with a fence

The first project I want to highlight is ai-jail. It is a sandbox wrapper to run AI agents with restricted system access. On Linux it uses bubblewrap (bwrap) and Landlock. On macOS it uses sandbox-exec. The idea is simple: the agent sees the environment it needs to work, but does not go rummaging through your whole system.

Do I use it every day? Yes. Do I use it always? No.

When I know I am not doing anything risky, I open claude or codex directly. If I am touching a simple project, just running tests, editing markdown, refactoring local stuff, often I do not bother. In more than 600 hours of intense Agile Vibe Coding, more than half a million lines of code and documentation, I never had one of those folklore cases of an LLM destroying my host system in some unrecoverable way.

And look, I explicitly used agents to configure my Omarchy. ZSH, Hyprland, Waybar, terminal configs, login scripts, all of it. They never did anything I did not ask for.

Those stories of “the agent deleted my whole home by itself” make me raise an eyebrow. In my experience, when you ask it to delete something dangerous, Claude and Codex ask for confirmation. You have to say yes. If you said yes without reading, that is not LLM black magic. That is user in zombie mode.

Nothing is guaranteed, of course. Hence ai-jail.

My favorite use is combining ai-jail with the harness’ no-brakes mode:

ai-jail claude --dangerously-allow-permissions
ai-jail codex --dangerously-bypass-approvals-and-sandbox

It sounds contradictory, but it makes sense. I remove the confirmation friction inside the agent, but put a fence at the operating-system level. The agent can work fast inside the project, but the host filesystem is essentially read-only. The current directory is read-write. Whatever I explicitly map with --rw-map is also read-write. The rest is not to be touched.

The ai-jail README sums it up well: it is a sandbox wrapper for agents like Claude Code, GPT Codex, OpenCode, and Crush. On the first run it creates a .ai-jail in the project, which can be committed. It supports --dry-run to see mounts before executing, --lockdown for a stricter mode, --private-home to hide real dotfiles, --mask .env to hide sensitive files inside the project itself, and isolated browser profiles for Chromium/Firefox.

Do not sell this as absolute security. Process sandboxing is not a VM. Kernel bugs exist. Side channels exist. macOS has limitations. The README itself is clear: if you need to isolate a truly hostile workload, use a disposable VM. I do not use ai-jail as “military-grade armor.” I use it as another layer, good enough for a development workflow.

And even inside the project, everything is Git. I push frequently to GitHub or to my private Gitea. So the realistic worst case is the agent destroying the project directory. Annoying? Yes. Catastrophic? No. I clone again. I come back from the remote. I redo what was local. If .git gets corrupted, I delete everything and clone again.

Secrets also have a copy outside. .env, tokens, keys, everything that matters sits in Bitwarden. Self-hosted in Vaultwarden, of course. So if I lose the local directory, I did not lose the keys to the kingdom.

The most common risk is not the agent deleting everything. It is you leaking a secret to Git. That happened to me more than once. You run git add ., forget a .env, push to the remote, congratulations. It happens. That’s why you must look at git status, git diff --cached, and think before pushing.

Even when it happens, LLMs are very competent at helping rewrite history. I ask them to clean the secret from Git, force-push, review that it disappeared, and then I rotate the key. It is not pretty, but it is manageable.

So yes, I recommend using Claude/Codex with dangerous permissions inside ai-jail. Is there a 0.001% chance of an unrecoverable accident? There is. But if you are a good engineer, that should not kill you. I have layers: automatic Btrfs snapshots, restic to my NAS, NAS archiving offsite to AWS Glacier, remote Git, Bitwarden. No tool replaces backups.

ai-memory: context that survives the harness

The second is ai-memory, which I explained in detail in “I Built a Memory System for Coding Agents: ai-memory”.

The motivation is simple: harnesses lose context. Claude Code compacts. Codex compacts. opencode compacts. The session ends. You open another agent and it does not know what happened in the last 4 hours. If you only use one harness, maybe it does not bother you much. If you alternate between Claude and Codex like I do, it gets annoying fast.

I wanted a long-term memory consolidator that worked across different harnesses. Something that allowed handoff between Claude, Codex, and opencode without me manually writing HANDOFF.md every time. Something that captured prompts, tool calls, and session events through hooks, consolidated them into markdown pages, indexed with SQLite/FTS5, and exposed everything through MCP when the agent needed to query it.

Another motivator was what I explained in “Is RAG Dead? Long Context, Grep, and the End of the Mandatory Vector DB”. For code projects, simple text almost always solves more than fancy vector DB architecture. Markdown, grep, SQLite FTS5, long context, and good files in docs/ already take you far. ai-memory follows that line: compile memory into text, leave it on disk, index it simply, and only call an LLM when consolidation is worth it.

ai-memory was not made to be a user-browsable knowledge base. It has a read-only web UI, yes, but that is for auditing and inspection. The memory is optimized for LLM consumption. It is an internal wiki the harness can query when it thinks it needs to. It is a place where I can explicitly ask “save this for the next session” and expect it to survive longer than Claude or Codex’s default compaction.

The README sums it up well: coding agents lose all context when the session ends; ai-memory gives them a shared persistent wiki. Every prompt, tool call, and decision can be captured automatically. At the end of the session, relevant pages are rewritten as coherent narrative. In the next session, another agent can receive a handoff already prepended into the context.

This is useful when you close Claude at 6pm, open Codex the next day in the same directory, and want it to know you were testing session cookies because JWT rotation had run into trouble. Or when you return to a project six weeks later and do not remember why you discarded Redis.

But do not confuse it with canonical documentation. If you did important research you do not want to lose, ask the agent to write markdown in docs/ inside the project. Architecture decision, benchmark, library analysis, deploy runbook, anything that must survive with guarantees should become an explicit file in the repo. That is simpler, auditable, and versioned.

ai-memory covers the middle band: transient information that might matter later. A weird bug that appeared. The reasoning that led to a decision. An environment gotcha. A session summary. Things you do not want to turn into official docs yet, but also do not want to throw away.

It is still beta. I use it in personal production, but it needs many more users beating on it. The most polished integrations today are Claude Code, Codex, and opencode. Gemini CLI, OpenClaw, and exotic MCP clients still need more testing. PRs are welcome. Bug reports too. “I installed it and it broke on my setup” is exactly the kind of feedback that reveals a wrong assumption.

ai-usagebar: knowing when to switch horses

As I said above, I prefer using Anthropic and OpenAI’s subsidized plans. The problem is that if you do real Agile Vibe Coding, you hit limits. Daily limit. Weekly limit. Session limit. Limit that changes. Limit that does not show up clearly anywhere.

I was using claudebar, which is good, but only covers Claude. I wanted to see the main vendors in one place. That became ai-usagebar, which I introduced in “I Built a Waybar Widget for Omarchy to Monitor LLM Plan Usage: ai-usagebar”.

It is a Waybar widget and Rust TUI to monitor Anthropic Claude, OpenAI Codex/ChatGPT, Z.AI GLM, and OpenRouter usage. For Claude and OpenAI, it reads the OAuth credentials the official CLIs already wrote. For Z.AI and OpenRouter, it uses API keys. It shows session percentage, reset, limits, balance, and lets you switch the primary vendor.

The value is banal and therefore useful: I glance at the bar and know whether I should continue in Claude, hand off to Codex, or top up OpenRouter credit. I do not want to discover I hit the weekly limit in the middle of a large refactor.

There is also a standalone TUI:

If you do not use Omarchy, Hyprland, or Waybar, you can still run ai-usagebar-tui in any terminal. SSH, tmux, normal terminal, whatever. The bar is convenience. The TUI is the universal form.

ghpending: GitHub pending stuff without the ritual

After the marathon, I ended up with dozens of ai-* and frank-* repos on GitHub. That creates an annoying problem: issues and pull requests start appearing. A contributor opens a PR. Someone reports a bug. Someone else sends a suggestion. If I have to open the browser, enter repo by repo, filter tab by tab, I will postpone it. And if I postpone it, I go weeks without answering contributors.

Yes, I could use gh, the official GitHub CLI. I do use it. But I wanted something dumber and faster: a short command to print a digest of everything pending in the repos I chose to monitor. That became ghpending, which I described in “I Built a CLI to Check My GitHub Pending Stuff: ghpending”.

That is it: ghpending add to choose repos, ghpending to see the digest, ghpending list, ghpending rm. Without auth it works with GitHub’s 60 req/h anonymous limit. With GITHUB_TOKEN=$(gh auth token) ghpending, it goes up to 5,000 req/h.

The point is not replacing GitHub. It is reducing friction. If I can run one command in the terminal and see “there are 3 PRs and 2 issues to look at,” I look. If it depends on browser ritual, notifications, and tabs, it waits.

And Claude/Codex are very good at this kind of work. You can ask:

“Check the open pull requests, review the code, see if it compiles, run the tests, add tests if missing, rebase from master if needed, merge and close.”

Or:

“Check the open issues, evaluate whether there is a real bug, reproduce it if possible, propose a fix, answer the user.”

They read the PR, understand the diff, run tests, rebase, solve simple conflicts, write the contributor response. You still keep your brain on. You are delegating mechanical work you already know how to do.

Refactoring: ask explicitly, several times

Claude and Codex are very good at refactoring, but do not assume they will do it automatically the way you would. I usually start projects or features with explicit instructions:

“Use Rust best practices. Avoid unnecessary duplication. Modularize only where it makes sense. Add unit tests for every new feature. Follow Clean Code principles. Do not create an abstraction before it is needed.”

After a large feature, a large fix, or a few hours of development, I stop and ask:

“Now that we touched a lot of code, re-evaluate it carefully. Delete dead code. Refactor obvious duplication. Add missing tests. Remove magic numbers. Check if any modules are too large. Do not change behavior without tests.”

Before release:

“Before publishing this version, do a sanity audit. Look for secret leaks, dangerous permissions, destructive commands, path traversal, unnecessary unwraps, missing validation, and anything that looks like an obvious vulnerability.”

Does that guarantee security? Of course not. Not even close. But it removes a lot of dumb mistakes. It is another layer. I like running this audit with Claude and then with Codex, because each one finds different things. Bugs still pass. Security is process, not a magic ritual.

Disposable experiments: code got cheap

Before choosing a library, framework, architecture, model, or service, I like creating experiments/.

Example:

“Before choosing between Qwen and DeepSeek, create a disposable prototype in experiments/ for an A/B test. Document the analysis in docs/ with result, cost, latency, quality, and recommendation.”

This changed how I decide. Before, many engineering decisions became opinion, feeling, faith in somebody else’s benchmark. Now code is cheap. I ask the agent to make two or three versions, run tests, measure, document, throw away what does not work.

Prototyping got genuinely fast. Frank Karaoke is a good example: turning YouTube into a karaoke app was the kind of idea I would maybe leave in a mental list for months, waiting for “a free weekend” that never arrives. Now I can open experiments/, ask for a rough prototype, test the technical path, and decide whether it deserves to become a project. Look at my other 2026 posts about frank-* and ai-* projects: almost all of them started like this, as disposable code that proved something before earning a name.

But cheap prototypes do not mean one-shot. I already wrote in “Why LLMs Aren’t Giving You the Result You Expect”: a good prompt is an iterative conversation. You provide context, show references, point out constraints, read the result, correct direction, ask for a rewrite. If you throw in a vague sentence and expect a finished product, that’s on you.

I learned this by taking a beating too. In the Frank Yomik post I described my first real vibe-coding failure: when the direction is wrong, insisting on the same prompt just digs the hole deeper. Sometimes you need to reduce scope, isolate the problem, create a test, change strategy. LLM does not turn a bad plan into good engineering.

And there are domains where you need to study along with it. In the DriveClub and shadPS4 post, AI almost sent me in every wrong direction because the problem required understanding rendering, gamma, shaders, buffers. The tool helps you explore, but you still decide whether the explanation makes sense. If you do not understand enough to verify, you are just accepting a pretty guess.

That is also why I keep repeating the idea from “Software Is Never Done”: deploy is not the finish line. The prototype becomes a product when it handles bug reports, maintenance, refactoring, docs, releases, rollbacks, users complaining. LLM helps a lot with that boring cycle. But the cycle still exists.

If it is testable, test it. If it can be measured, measure it. If it cannot be measured, at least write down the assumptions. The important thing is not choosing just because it “seems better.”

Cheap code also means detachment. Make code to throw away. Make an ugly prototype. Make a disposable benchmark. Ask the agent to document what it learned in docs/decision-qwen-vs-deepseek.md, then delete experiments/ if you want. The document stays. The lesson stays.

LLMs are also very good at documentation. Use that. Ask it to document everything. Why we chose PostgreSQL instead of SQLite in this case. Why the deploy uses a multi-stage Docker image. Why the service runs behind Cloudflare Tunnel. Why that sysctl exists. Even if you delete half of it later, the cost of writing fell near zero.

Automated deploy or you will stop maintaining it

Every project of mine that matters has automated build. Many run in my homelab, as I described in “Migrating my Home Server with Claude Code”. Almost every project has a bin/deploy that builds a Docker image, pushes it, rotates it on the server, applies migration if needed, and validates healthcheck.

Claude and Codex are excellent at deploy. They read bin/deploy, understand Dockerfile, edit GitHub Actions, adjust release workflows, fix binary signing, update Homebrew taps, generate checksums. And yes, I ask Claude/Codex to SSH into my homelab and redeploy Docker containers. They are very good at that. ai-jail, for example, has GitHub Actions to build signed binaries for Linux and macOS.

If you have dozens of projects, the more automated the better. I rarely type admin commands in the terminal by myself. I ask the LLM to do it, observe, approve what is dangerous, and then ask:

“Document what was done and why it was done.”

This applies to the homelab and my workstation. My Omarchy is customized through Claude: ZSH, Hyprland, Waybar, scripts, shortcuts, themes, integrations. Even my gaming/emulation setups fall into this, as I showed in the retro racing games running on Distrobox post. This is a case where I normally do not use ai-jail, because I actually want to touch the host. So I look at commands, read diffs, approve slowly. Even then, I never had the agent break my system in an unrecoverable way. Quite the opposite. My PC has never been more stable and documented.

Days later, when I forget why I configured something that way, the context is in markdown, Git, ai-memory, or the project history itself. I can ask and the agent has something to pull from.

Even this post was written this way

This is how I write these posts now. I dump a huge messy block from my brain into Claude. I ask it to read recent posts to calibrate style. I ask it to check the projects directly and elaborate the technical parts. I ask it to use the latest screenshots, upload to S3 when needed, link previous posts, review the tone.

Then I read and edit. I cut what sounds generic. I replace sentences that sound like release notes. I put my rants back in. The result is still my text; I just spend energy on what matters: deciding what to say, correcting nuance, cutting nonsense.

“But did you test Pi?”

Every time I mention an LLM or LLM tool, someone shows up in the comments with the same question: “but did you test Pi?”, “but did you test DeepSeek?”, “but what about Qwen?”, “but what about the new model that came out yesterday?” Every. Single. Time.

It is annoying as fuck. And almost always it comes from three kinds of people: someone who tested nothing and wants to outsource the work, someone who already chose a tool and wants me to validate their choice, or a fanboy treating an LLM vendor like a soccer team. They all sound the same. NPC repeating tutorial dialogue.

Software engineers should not decide based on other people’s opinions. Not even mine. If you choose a tool because “Akita said so,” you understood it wrong. I advocate Claude Code and Codex because I used them for hundreds of hours, in real projects, publishing code and post-mortems of what worked and what failed. And even then I did not stop at opinion.

I built my own automated benchmark: llm-coding-benchmark. I update it when a popular vendor releases a new version. I run comparable scenarios. I publish results. Then I adjust my opinion based on the data. That gives me enough ground to say that, in my workflow, Opus and GPT keep winning. Not because I woke up wanting to defend some billionaire company’s logo.

If your first reaction was “but did you test Qwen?”, great. Test it yourself. Run the benchmark. Create a better scenario. Send a PR. Show numbers. Show cost. Show latency. Show where it failed. Show where it won. Bring new data.

Loose opinion is irrelevant. “It works for me” does not scale. “I like it better” does not matter. “In my one-shot prompt it was better” is an anecdote. Engineering starts when something can be reproduced, compared, and acted on.

So it is simple: bring actionable data or shut the hell up. I do not need vendor fan clubs in the comments. I need people testing, measuring, and contributing new results.

Final checklist

Short summary, because this post is already long:

• Focus on Claude Code, Codex, or opencode. Stop collecting agents.
• Use Opus 4.7 and GPT 5.5 through Pro/Plus/Max plans when daily productivity matters.
• DeepSeek, Kimi, and local models are useful, but still do not replace the main workflow.
• Agile Vibe Coding is XP with LLM: tests, Clean Code, CI, pair programming, and deploy.
• Use ai-jail when you want agent autonomy with a filesystem fence.
• Combine ai-jail with dangerous Claude/Codex permissions when the project is protected by Git.
• Have real backup: Btrfs snapshots, restic, NAS, offsite, Git, Bitwarden.
• Review git add, git diff --cached, and pushes so you do not leak secrets.
• Use ai-memory for transient context and handoff between agents.
• Write canonical documentation in docs/ when information needs to survive with guarantees.
• Use ai-usagebar to know when to switch from Claude to Codex, or when to top up OpenRouter.
• Use ghpending so you do not abandon issues and PRs.
• Ask for refactoring explicitly after large features.
• Run a security audit before release, preferably with more than one model.
• Create disposable prototypes in experiments/ before deciding by faith.
• If you disagree with a benchmark, run llm-coding-benchmark and bring new data.
• Document decisions in markdown. Code got cheap. Documentation too.
• Automate deploy. If it depends on a manual ritual, you will stop doing it.

In the end, it is the same advice as always: tools change, engineering does not. LLM increases leverage. If you already had good habits, you will produce more. If you did not, you will just produce mess faster.

And yes, this changes the interface of the work. I already wrote about that in “VS Code Is the New Punch Card”: polishing pixels in an editor is now old-programmer nostalgia. The hard part is writing intent correctly, reviewing execution without being lazy, measuring results, throwing away cheap code, and not confusing opinion with data.

Five days ago I wrote a long post on coding-agent memory where I recommended agentmemory as the answer. After a week running it in personal production, I’m walking it back. This post explains what went wrong and the open source project I started building to fix it: ai-memory.

Why agentmemory didn’t pan out

agentmemory has the right ideas (Karpathy’s LLM Wiki, tiered consolidation, automatic-capture hooks, MCP) but the implementation has structural problems that hurt in daily use. The main ones I hit in practice:

• BM25 reindex on every restart. The index persists to a file (mem:index:bm25.bin) through a remote KV called iii-engine. With few observations it flies, but pass 10K observations and state::set starts timing out, the file stays at ~96 empty bytes, and every restart pays ~5 minutes rebuilding from scratch (issue #309, still open).
• 5-second data-loss window. All persistence flows through a 5s debounce on IndexPersistence. When the 30s state::set timeout blows up, the Node process dies taking everything that was in memory with it (#204).
• Two config-read paths in the same codebase. process.env directly in one place, getMergedEnv() in another. The classic “I set the variable and nothing changed” (#456).
• Wrong hook key on ~47% of Claude Code tool calls. The hook reads data.tool_output, but Claude Code sends tool_response. Six weeks of observations silently vanishing (#539).
• Engine runs from the caller’s working directory. Windows users thought they’d lost memories because every terminal opened the state store in a different path (#303, still open).

There’s more. I wrote it all up here in my research repo. The author is responsive, the repo has 15.7K stars, and even so the architecture chosen (TypeScript MCP + separate iii-engine Rust binary + 4 ports, 3 processes, in-memory indexes persisted via remote KV) accumulates a class of bug you can’t close without rewriting half the system. The shape of the problem is structural, not a lack of effort from the maintainer.

Same story with every other solution I tried: either it’s incomplete, or too fixated on some specific technology (proprietary vector DB, a knowledge graph that needs Neo4j, an elaborate LLM pipeline), or it demands that the user yell write_note every time something’s worth saving. None of them “stay out of the way” enough for me to trust them in long sessions.

What I wanted from day one

When I started my 37-day vibe coding marathon back in February, I knew I needed some kind of knowledge organizer. It took more than 500 hours of experimentation to crystallize what I actually wanted.

If you use just one of the three (only Claude Code, or only Codex, or only opencode) and stay there, you probably don’t need anything extra. The three of them already do a reasonable job of managing memory within the session. Claude Code has three levels of compaction (time-gap microcompact, token-threshold autocompact, experimental sessionMemoryCompact). Codex has per-model auto_compact_token_limit. opencode has anchored compaction with a 20K buffer. I covered this in detail in the previous post.

The one extra discipline worth adopting in that scenario is to keep a docs/ folder in the project with markdown files organized by topic, and ask the agent to save there when something important happens. Research you don’t want to redo, known gotchas, why you picked option A over B. Works. Takes discipline.

The problem shows up for people like me, jumping between agents in the same project. I use Claude Code by default (I find the harness, the subagent orchestrator, and the long-task planning superior). But when Claude gets stuck, I fire up Codex in the same directory just to “stir things up.” Codex thinks more “outside the box” and sometimes finds a solution Claude didn’t see. Then I go back to Claude to implement carefully.

This back-and-forth between agents is where external memory really matters. Without it:

• You close Claude Code, open Codex in the same directory, and Codex knows nothing about the last 4 hours of discussion.
• You have to manually ask Claude to write a handoff note to ./HANDOFF.md, then ask Codex to read it. Every time.
• Projects you left untouched for weeks: you open them again, forgot why you decided against Redis, forgot what the bug in library X was.

Karpathy nailed the concept in his LLM Wiki, which I went deep on in the previous post. But there’s one specific line from the gist that stuck in my head:

index.md is “surprisingly good at ~100 sources, a few hundred pages, no embeddings needed”.

That line summed up what I wanted. You don’t need complicated technology. Simple storage (markdown in git), simple index (SQLite with FTS5 and links), simple install (a binary or container), automatic use (hooks that fire on their own), zero maintenance (memory decays without the user touching anything).

That’s why I started ai-memory.

Research before code

Instead of just diving into code, we dug through the source and issues of the relevant projects to understand what each one got right and wrong. The research lives in the repo itself:

• research-karpathy-llm-wiki.md — what Karpathy literally wrote, separated from what the community attributes (paraphrasing) to him. Three core principles: compile instead of retrieve, three layers (raw / wiki / schema), three operations (ingest / query / lint). The conceptual blueprint.
• research-agentmemory.md — technical breakdown of agentmemory: four consolidation tiers (working → episodic → semantic → procedural), supersession with is_latest=false instead of delete, exponential decay, cluster reflection. I kept agentmemory’s ideas; I changed the implementation.
• research-basic-memory.md — Python, MCP-native, plain markdown on disk. The model is explicitly manual: the agent calls write_note when it decides to save. Good storage model, terrible capture model (it depends on the agent remembering to call).
• research-cognee.md — cognify pipeline (extract → chunk → graph + summarize → embed → persist) with a triple knowledge graph + vector + relational store. Excellent for a well-funded enterprise agent that wants semantic relationships between entities. Way too heavy for “coding session memory.”

The synthesis I took away: agentmemory has the right ideas. The rest is execution.

The idea I like most from agentmemory, which it inherited partially from LLM Wiki v2, is the sleep-style consolidation: short memory keeps raw detail, long memory keeps consolidating and summarizing, and long-term memory that nobody touches eventually gets forgotten. It doesn’t pile up cruft. There’s accessCount, geometric exponential decay, spaced-repetition reinforcement. It’s similar to (and inspired by) what a human does while sleeping.

In ai-memory I kept that structure but swapped the engineering underneath:

• TypeScript → single Rust binary. No separate remote KV. No 3 processes. One Rust binary, with a data directory and an Axum server.
• Persistent index in SQLite + FTS5. Native. No reindex on every restart. WAL mode, 5s busy_timeout.
• Single writer in a dedicated thread via mpsc. No 5s loss window, no 30s timeout blowing up.
• Plain markdown on disk as source of truth. SQLite is just a derived index. You can open the wiki in Obsidian. You can grep it. You can version it with git (and it versions automatically).
• Per-project isolation in the physical layout on disk. <wiki_root>/<workspace_id>/<project_id>/... keyed by stable UUIDs. Renaming a project is a column update. Deleting a project is rm -rf on a subdir. Same page name in two projects doesn’t collide.
• Embedding and LLM are optional. Without a provider key, the system still works with FTS5, link expansion, and raw-observation fallback. Add embeddings when you want vector re-ranking, and Claude Haiku or GPT-5.4-mini when you want quality consolidated pages.

How it works day to day

Interaction with the agents happens through two mechanisms: hooks/extensions (automatic capture) and MCP (on-demand query).

Claude Code and Codex use shell hooks. OpenCode uses a TypeScript plugin. OMP/Pi uses a TypeScript extension. Cursor and Gemini CLI use JSON lifecycle config. They all emit equivalent events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop, SessionEnd) as fire-and-forget POSTs to ai-memory’s HTTP server (running at 127.0.0.1:49374 by default). The agent never waits. If ai-memory is down, the session continues normally, just without capture. Claude Desktop and OpenClaw are MCP-only: they can query memory, but they don’t automatically capture lifecycle events.

On the agent side, the MCP server exposes tools the LLM can call when it sees fit:

The routing snippet that lands in CLAUDE.md (or AGENTS.md for Codex/OpenCode/Cursor/Gemini/OMP) is what teaches the agent when to call which tool. You install it with one command: ask the agent “install the ai-memory routing in this project” and it invokes the MCP tool memory_install_self_routing, gets back the canonical snippet, and writes it to the right file. Idempotent.

Handoff between agents in action

Here’s the concrete scenario that motivated the project:

$ claude
> "Refactoring auth. JWT rotation is broken; I'm going to try
   session cookies as an alternative."
[works for an hour]
> /exit

$ codex   # same directory, hours or days later
[ai-memory's SessionStart hook fetches the handoff and prepends it to context]
> "Picking up: you were investigating session cookies as an
   alternative to broken JWT rotation. Continue?"

You did nothing special. At Claude Code’s SessionEnd, ai-memory consolidated the session’s observations into a sessions/<uuid>.md page, created a typed handoff with open_questions + next_steps, and marked it “pending.” At Codex’s SessionStart, the server saw the pending handoff, fetched it, and injected it into the initial context. The agent reads and continues.

Same scenario if you abandon the project for two months and come back. memory_explore auto-tunes verbosity: less than an hour since the last session, it returns one line. More than 30 days, it returns a full catch-up of what happened.

Adopting ai-memory on an existing project

If you install ai-memory on a project with months of history, the wiki starts empty and the first sessions break even — you’re populating, not retrieving. ai-memory bootstrap solves this. It collects your git log, README, docs/, module headers, and project-rules files (CLAUDE.md / AGENTS.md), then sends them to the server which uses the LLM to generate seed wiki pages:

cd ~/Projects/my-project
ai-memory bootstrap

Costs about $0.05 with Claude Haiku 4.5 (budget capped at 50K input tokens). Run with --dry-run first to see what would be sent without paying. From there the wiki starts with real context, and every session builds on top.

Install: three commands

I reduced the install to the bare essentials. The recommended path is Docker, because the server stays isolated and updates are one line. Nothing else needed:

# 1. Wrapper script (~3KB) that runs the binary inside the container
mkdir -p ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/akitaonrails/ai-memory/main/bin/ai-memory \
    -o ~/.local/bin/ai-memory
chmod +x ~/.local/bin/ai-memory

# 2. Start the server (loopback-only, no auth — single-user laptop)
docker run -d --name ai-memory \
    --restart unless-stopped \
    -p 127.0.0.1:49374:49374 \
    -v ai-memory-data:/data \
    -e AI_MEMORY_LLM_PROVIDER=anthropic \
    -e ANTHROPIC_API_KEY=sk-ant-... \
    akitaonrails/ai-memory:latest

# 3. Wire up your agent
ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --agent  claude-code --apply

Done. Open Claude Code as usual. Every prompt and tool call now lands in ai-memory, and the next session you open in this project will see a handoff with where you left off.

Repeat step 3 with --agent codex, --agent opencode, --agent omp/pi, --client cursor, --client gemini-cli, --client pi/omp, etc. for other agents. Claude Desktop and OpenClaw are MCP-only. Idempotent: re-running replaces only the ai-memory entry, preserving any other hooks/MCP servers you have. It writes a .bak-<timestamp> backup before every modifying write.

The project README covers the variations (Docker compose, homelab on the LAN with a bearer token, no-Docker install, source build). Follow docs/install.md if your setup wanders off the happy path.

Useful commands worth knowing

Once installed, the day-to-day is just using the agents. But it’s worth knowing a handful of commands for when you need them:

• ai-memory upgrade — self-upgrades the wrapper + docker pulls the new image + re-stages hook scripts/plugins/extensions. Idempotent. If you have a separate remote server, this only refreshes the local client; you update the server separately.
• ai-memory bootstrap — seeds the wiki from git log + README + docs/ + project rules. For projects that existed before ai-memory came along.
• ai-memory purge-project --project <name> --confirm — wipes an entire project. Atomic: SQLite rows, the wiki subdir, neighbors untouched.
• ai-memory rename-project --from <name> --to <new> — renames. One column in the DB, no file moves on disk. No side effects.
• ai-memory backup — snapshot of the data directory (wiki + SQLite). ai-memory restore undoes it.
• ai-memory lint / ai-memory forget-sweep / ai-memory embed — manual maintenance. Lint and forget-sweep also run on the server schedule by default; embedding backfill exists but stays off by default because it may call a paid provider.
• ai-memory generate-auth-token — when you’re about to expose the server beyond loopback (see docs/deploy.md).

Spelunking the wiki in the browser

The server can also mount a read-only web UI at http://127.0.0.1:49374/web when started with --enable-web. Same binary, same port, no extra process. It’s handy for three practical things: auditing what the agent’s been saving, checking whether the consolidated pages still look coherent, and sharing a single page with a teammate without giving them access to the agent.

The homepage lists detected projects, each with a page count and time since last activity:

Notice the orange warning at the top: the wiki is optimised for LLM consumption, with pages compiled from session observations by the LLM consolidator. For human-curated canonical documentation, use the project’s own docs/. The /web UI is for spelunking.

Each project is isolated by UUID in the physical layout on disk. Two pages with the same path in different projects don’t collide. Click a card and you land in the project’s page tree:

The sidebar groups the tree by kind: concepts/ (durable knowledge), decisions/ (architectural calls), gotchas/ (footguns), _rules/ (project rules suggested for promotion into CLAUDE.md), sessions/ (per-session logs), and bootstrap.md (the manifest generated by ai-memory bootstrap). The right column shows recent activity.

Click any page and you land in rendered markdown:

The rendering has syntax highlighting, tier badges (working/episodic/semantic/procedural) and kind badges (decision/gotcha/rule/fact), breadcrumbs, the supersession chain visible. Search combines FTS5, link expansion, and embeddings when configured; light/dark mode follows the OS preference via prefers-color-scheme.

To edit the wiki you open the files directly in any markdown editor (Obsidian works great). The web UI is read-only by design: the LLM consolidator is the one writing, humans just read.

Why Docker

Picking Docker as the recommended path was deliberate. A few practical wins:

• Updates are one line. ai-memory upgrade pulls the new image, refreshes the wrapper, re-stages hooks/plugins/extensions. You don’t compile Rust, don’t manage libsqlite versions, don’t fight with mise/Node version churn the way Node-based solutions force you to.
• Real isolation. The server runs in the container, reads only /data (named volume), doesn’t pollute your system. To clean up, it’s docker volume rm.
• Same image across setups. Laptop, desktop, homelab. Same amd64 or arm64 image.
• Auto restart. --restart unless-stopped brings the server back when you restart Docker, or when the machine boots (assuming systemctl enable docker).
• No source build needed. Compiling the Rust 1.95+ toolchain takes about 3 minutes in release. For end users, that’s unnecessary ceremony. Docker abstracts it away.

There’s a no-Docker path in docs/install.md for anyone who prefers it. But Docker is where the UX is best.

Which LLM for consolidation

This is a case where you don’t need a heavy model. Consolidation is text in, text out: the agent records raw observations during the session, on SessionEnd the LLM compiles 1-5 wiki pages classified as concept / decision / gotcha / rule. No complex reasoning, no code. Opus 4.7 or GPT-5.5 thinking are overkill — expensive and slow for a task that accepts a light model.

To pick the default we ran serious A/B testing across 6 different providers against 5 synthetic fixtures, each designed to stress a specific failure mode: multi-page extraction, restraint (resisting the urge to fabricate a page when the session is trivial), correct classification of rule vs gotcha vs decision, and topic separation. Full writeup with parse-rate, latency, and quality tables per fixture is at docs/llm-provider-comparison.md. The summary table:

Why Haiku ended up as default: hosted (always available), best at restraint (resists fabricating pages when the session is trivial, crucial for the wiki not to turn into a pile of empty pages), and best at classification (consistently gets kind: rule right, which is what makes auto-routing to _rules/<slug>.md work). $0.02 per consolidation is negligible for personal use.

But the user has legitimate alternatives:

• GPT-5.4-mini if budget is tight (5× cheaper than Haiku, 2× faster). The only measurable defect was fabricating a decisions/docs-spelling.md page on a typo-fix session. Over-classification, but mild.
• qwen3:32b on Ollama if you have a local server with ~20GB of RAM/VRAM. Zero cost per consolidation, fidelity comparable to the top hosted models. The ~92s latency doesn’t matter because consolidation runs in the background.
• DeepSeek V4 Flash works, but GPT-mini matches it on quality and beats it on speed.

If you want to test other models, the eval harness is at evals/ as a separate Rust crate. Add a JSON fixture, run cargo run -p ai-memory-eval --release, compare two providers side by side. Outputs land in evals/runs/<timestamp>/{baseline,candidate}/ with the exact .raw.txt the model answered plus .meta.json for latency and parse rate. PRs with new models tested are very welcome.

Status: beta, needs users

ai-memory is at the v0.2-complete tag on GitHub. The main features work: automatic capture, MCP, optional web UI, bootstrap, purge/rename/backup, bearer auth, browsing, FTS5 + graph/link-neighbour RRF search, optional embeddings, consolidation, decay, scheduled maintenance, and handoff across Claude Code / Codex / OpenCode / Cursor / Gemini CLI / OMP-Pi. I’ve been running it in personal production for a few weeks.

But it’s beta. It needs many more users banging on it for me to find the bugs that don’t show up on my machine. Claude Desktop and OpenClaw work as MCP-only clients; some exotic MCP clients still need real testing. The most polished integration today is Claude Code, followed by Codex, OpenCode, and OMP/Pi.

If you’ve made it this far, consider installing and sending feedback. Issues at github.com/akitaonrails/ai-memory/issues. PRs are very welcome — the code is Rust, MIT licensed, and the architecture is documented in docs/ARCHITECTURE.md and docs/design-decisions.md. Even a bug report of “I installed it, it didn’t run on my setup” helps — it means I assumed something about environments that doesn’t match yours.

The core motivation stays the Karpathy line. Agent memory is text. Text lives on disk. You index it with SQLite. You compile with an LLM when the work is worth it. You forget what nobody looks at anymore. You stay out of the way. And when you switch agents in the middle of a project, the next one already knows where you left off.

That’s what ai-memory tries to deliver.

Update (May 23, 2026): after a week running agentmemory in personal production, I’m walking it back. The architecture it picked accumulates a class of bug that doesn’t close without rewriting half the system (BM25 reindex on every restart, 5-second data-loss window, wrong hook key on ~47% of Claude Code tool calls, etc). I started a Rust replacement called ai-memory that fixes those. See I Built a Memory System for Coding Agents: ai-memory for the full writeup, the alternatives ranking, and install instructions. The rest of this post still holds as background on how compaction works in the three agents, Karpathy’s LLM Wiki pattern, and why external memory matters.

Anyone running long sessions in Claude Code, Codex CLI or opencode has eventually seen the “context approaching limit” warning or watched the agent “forget” decisions made three hours ago. This post is a deep dive into how memory works in these agents today, where it breaks, and what you can do to get something closer to long-term memory. I read the source code directly: Codex (Rust), opencode (TypeScript) and Claude Code (TypeScript, via the leak that’s been circulating). Then I closed by testing agentmemory, an open source MCP server that tries to solve the problem systematically.

First things first: what is “context”

A language model (LLM) has no persistent memory. What it “remembers” during a conversation is just the set of tokens that fit inside its context window. Every message exchanged, every file read, every command output, every tool call — all of it goes into the window. When you use Claude Code, Codex or opencode, the agent is assembling a sequence of messages (system prompt + history + tools + tool output) and sending the whole thing to the API on every turn.

That has two direct effects. The first is behavioral: the agent performs best when the relevant part of the conversation is fresh in context, and degrades as important information gets buried under pages of ls and grep output. The second is financial: every token sent gets billed (or chipped off your quota), and large windows have higher latency. Opus 4.7 has a 1M context, GPT 5.5 too, but just because the window fits doesn’t mean it pays to fill it. The fuller it is, the slower inference gets and the pricier each request becomes.

That’s why every agent implements some form of compaction: when the context approaches the limit, the agent runs an extra LLM call that summarizes the conversation so far into something much shorter, dumps the raw history, and continues the session on top of the summary. The upside is obvious (more room to work) and so is the downside (the summarized part loses detail).

Let’s see how each of the big three pulls this off.

Codex CLI: per-model limit + explicit handoff

Codex CLI is open source (github.com/openai/codex), so we get to read it directly. The auto-compaction logic lives in codex-rs/core/src/session/turn.rs and fires like this:

let auto_compact_limit = model_info.auto_compact_token_limit().unwrap_or(i64::MAX);
// ... every turn ...
let total_usage_tokens = sess.get_total_token_usage().await;
let token_limit_reached = total_usage_tokens >= auto_compact_limit;

if token_limit_reached && needs_follow_up {
    let reset_client_session = match run_auto_compact(
        &sess, &turn_context, &mut client_session,
        InitialContextInjection::BeforeLastUserMessage,
        CompactionReason::ContextLimit,
        CompactionPhase::MidTurn,
    ).await { /* ... */ }
}

The limit is per model (auto_compact_token_limit comes from ModelProviderInfo). When it hits, Codex calls the LLM itself with a specific compaction prompt (in codex-rs/core/templates/compact/prompt.md):

You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM that will resume the task.

Include:

• Current progress and key decisions made
• Important context, constraints, or user preferences
• What remains to be done (clear next steps)
• Any critical data, examples, or references needed to continue

The response becomes the new context, prefixed with a preamble that literally says “another language model started to solve this problem and produced a summary of its thinking process.” Codex emits pre_compact and post_compact events that hooks can intercept (handled in codex-rs/core/src/hook_runtime.rs). Those hooks are the seam where external tools (like agentmemory) plug in to save state before compaction wipes the history.

opencode: 20K buffer + anchored summarization

opencode (github.com/sst/opencode) does the same thing with different math. In packages/opencode/src/session/overflow.ts:

const COMPACTION_BUFFER = 20_000

export function usable(input: { cfg, model, outputTokenMax? }) {
  const context = input.model.limit.context
  const reserved = input.cfg.compaction?.reserved
    ?? Math.min(COMPACTION_BUFFER, ProviderTransform.maxOutputTokens(input.model, input.outputTokenMax))
  return input.model.limit.input
    ? Math.max(0, input.model.limit.input - reserved)
    : Math.max(0, context - ProviderTransform.maxOutputTokens(input.model, input.outputTokenMax))
}

export function isOverflow(input) {
  if (input.cfg.compaction?.auto === false) return false
  const count = input.tokens.total
    || input.tokens.input + input.tokens.output + input.tokens.cache.read + input.tokens.cache.write
  return count >= usable(input)
}

By default, opencode reserves 20K tokens as a buffer between content and the window limit. When total tokens crosses usable(), it marks the session as needsCompaction = true and runs the compaction flow on the next turn. The summarization prompt (in packages/opencode/src/agent/prompt/compaction.txt) is more surgical than Codex’s:

You are an anchored context summarization assistant for coding sessions.

Summarize only the conversation history you are given. The newest turns may be kept verbatim outside your summary, so focus on the older context that still matters for continuing the work.

If the prompt includes a <previous-summary> block, treat it as the current anchored summary. Update it with the new history by preserving still-true details, removing stale details, and merging in new facts.

Notice the difference: opencode keeps an “anchored summary” that gets updated on every compaction, instead of regenerated from scratch. The most recent turns stay verbatim, and only the older history gets collapsed. It’s a middle ground between Codex’s full handoff and keeping everything raw.

Claude Code: three levels of compaction + detailed summary

Claude Code is proprietary, but a recent leak exposed the source (TypeScript, same as opencode but with very different architecture). The code shows Anthropic went further than the competition: Claude Code has three levels of compaction running in parallel, not one.

The first is microcompact, time-based, in src/services/compact/microCompact.ts and timeBasedMCConfig.ts. When the gap since the last assistant message goes past 60 minutes, the server-side prompt cache (1h TTL) is guaranteed expired, so the whole prefix is going to be rewritten on the next request anyway. Before sending it, Claude Code clears the content of old tool results (Read, Grep, Glob, WebFetch, Bash, etc.) and replaces them with [Old tool result content cleared]. Shrinks the request size without entering the expensive summarization flow. Comment in the code:

/** Trigger when (now − last assistant timestamp) exceeds this many minutes.
 *  60 is the safe choice: the server's 1h cache TTL is guaranteed expired
 *  for all users, so we never force a miss that wouldn't have happened. */
gapThresholdMinutes: number

The second level is autoCompact, in src/services/compact/autoCompact.ts. Similar to opencode’s, but more carefully tuned:

const MAX_OUTPUT_TOKENS_FOR_SUMMARY = 20_000
export const AUTOCOMPACT_BUFFER_TOKENS = 13_000
export const WARNING_THRESHOLD_BUFFER_TOKENS = 20_000
export const ERROR_THRESHOLD_BUFFER_TOKENS = 20_000

export function getAutoCompactThreshold(model: string): number {
  const effectiveContextWindow = getEffectiveContextWindowSize(model)
  return effectiveContextWindow - AUTOCOMPACT_BUFFER_TOKENS
}

Reserves 20K tokens for the summarization output, 13K of buffer for triggering the compaction, and has warning + error thresholds 20K below that limit (the TUI status bar turns yellow past the warning, red past the error). There’s also a circuit breaker: after 3 consecutive auto-compact failures, it stops trying — an internal comment reveals that without it “1,279 sessions had 50+ consecutive failures (up to 3,272), wasting ~250K API calls/day globally.”

The third level is sessionMemoryCompact in sessionMemoryCompact.ts, marked experimental, which ties into the persistent cross-session memory system.

The most visible difference vs Codex and opencode is in the summarization prompt. Where Codex asks for 4 short bullets and opencode asks for an update of the “anchored summary,” Claude Code asks for a 9-section explicit structure (src/services/compact/prompt.ts):

1. Primary Request and Intent: Capture all of the user’s explicit requests and intents in detail
2. Key Technical Concepts: List all important technical concepts, technologies, and frameworks discussed.
3. Files and Code Sections: Enumerate specific files and code sections examined, modified, or created…
4. Errors and fixes: List all errors that you ran into, and how you fixed them…
5. Problem Solving: Document problems solved and any ongoing troubleshooting efforts.
6. All user messages: List ALL user messages that are not tool results. These are critical…
7. Pending Tasks: Outline any pending tasks that you have explicitly been asked to work on.
8. Current Work: Describe in detail precisely what was being worked on immediately before this summary request…
9. Optional Next Step: List the next step that you will take…

Section 6 (“All user messages”) is the unusual one: the summary has to contain a verbatim list of every user message that isn’t a tool result. Meaning even after compaction, Claude Code keeps your asks, literal. That’s why compacted sessions in Claude Code feel like they preserve the tone of the conversation better than Codex (where the handoff is more executive and less narrative).

There’s also a PARTIAL_COMPACT_PROMPT variant that summarizes only the recent stretch when a prior summary is preserved, and a PARTIAL_COMPACT_UP_TO_PROMPT to keep cache hits by placing the summary at the start. The /compact slash command is still around for manual force, and the PreCompact / PostCompact hooks run the same as the other agents.

Comparing the three side by side

The design choices tell a story. Claude Code invests in preserving user narrative (the 9 sections, especially #6) and optimizing cache cost (gap-based microcompact, clean separation of 3 paths). Codex prioritizes handoff between models (the “summary produced by the other language model” preamble shows the expectation that the next turn might be executed by a different LLM). opencode picked incremental summarization: the anchored summary updates each cycle instead of being regenerated. Each strategy has trade-offs, but this is the first time you can look at all three side by side using real source.

“Vendor lock”? Doesn’t exist for this kind of memory

A worry that comes up a lot: by starting with Claude Code you get “locked in” and can’t migrate to opencode or Codex later. That’s a myth. Agent memory, as we saw, is just text. No proprietary binary format, no closed schema, no vendor-only state. Everything the agent carries is prompt + message history + context files.

In practice you can do a manual handoff between agents. Tell Claude Code: “write a markdown doc at ./HANDOFF.md with the current project state, decisions made, next steps, and any important context for a different agent to continue.” Out comes a well-written session, you close Claude Code, open opencode, say “read ./HANDOFF.md and pick up where it left off.” And opencode picks up from where Claude stopped, without meaningful loss (the loss is exactly the loss an internal compaction would have caused).

This pattern of explicitly exporting context is actually better than relying on automatic compaction. You decide when and what to preserve, instead of leaving it to the agent under token pressure.

The problem: long-term memory disappears alongside

Compaction solves the immediate problem (room in the context) but creates a subtler one: information from the start of the session is the first to go. If you spent 30 minutes on turn 5 exploring an architecture, decided three trade-offs and discarded two approaches, by turn 50 that whole exploration may have collapsed into a single bullet. If you need to revisit one of those discarded trade-offs (“why did we decide against Redis here?”), the agent doesn’t know anymore.

The workaround I’ve been using for months is to force the agent to write into files manually. On important projects I keep a ./.docs/ or ./docs/ directory with markdown files organized by topic: architecture, decisions, known gotchas, weird configurations, links to relevant issues. When something important happens in a session, I ask: “save this to ./.docs/<topic>.md”. Then on the next session, or after a compaction, the agent can re-read the file if it needs to.

The cost of this approach is discipline. I have to remember to ask. The agent won’t do it on its own. And I have to organize the files so it can find what it needs later (which usually means a MEMORY.md or CLAUDE.md at the root listing the topics).

There’s a more systematic way to do this. It’s called LLM Wiki, popularized by Andrej Karpathy in April 2026 in a GitHub gist.

Karpathy’s LLM Wiki pattern

The idea is simple and powerful: instead of treating knowledge as something to retrieve on demand (RAG), treat it as something to compile over time, like code. The architecture has three layers:

1. Raw Sources — immutable documents (papers, articles, transcripts, notes) that serve as source of truth.
2. Wiki Layer — markdown files generated and maintained by the LLM. Each concept gets a page. Pages link to other pages. The LLM updates, cross-references, flags contradictions.
3. Schema — a file (think CLAUDE.md or SCHEMA.md) that defines conventions: how to name pages, tag taxonomy, minimum structure per entry.

The workflow has three operations. Ingest: when a new source arrives, the LLM reads, extracts what matters, updates 10-15 existing pages, creates the missing ones, fixes cross-references. Query: questions get synthesized answers with citations; valuable insights become new pages. Lint: periodic passes detect contradictions, outdated claims, missing connections.

The core win over RAG is that knowledge compounds. RAG re-derives the answer on every query, starting from the same raw documents. The wiki synthesizes once, and the next query starts from the synthesis, not from raw material. For programming work this is gold: the first time you discover that a library has a weird timezone gotcha, it becomes a wiki page. The second time the topic comes up, the agent reads the page instead of re-discovering the problem.

The grunt work of maintaining a wiki always killed human wikis. That’s why they die. But LLMs are good at writing and repetitive maintenance. Karpathy’s bet is that we finally have a machine that does the boring work of keeping the wiki alive.

agentmemory: practical implementation of the pattern

I’d been doing this wiki by hand in ./.docs/ for months. This week I migrated to a tool that automates most of the process: agentmemory by Rohit Ghumare. It’s open source (Apache-2.0) and is literally an implementation of the LLM Wiki pattern with some extensions (confidence scoring, memory lifecycle, knowledge graph, hybrid search).

What it is, in practice:

• A Node daemon running locally on 127.0.0.1:3111 (REST) and :3113 (web viewer with timeline and session replay). Storage on SQLite + in-memory vector index, zero external dependencies.
• An MCP server (@agentmemory/mcp) that any MCP-compatible agent (Claude Code, Codex, opencode, Cursor, Gemini CLI, etc.) loads as a stdio server. Exposes 51 memory tools (memory_smart_search, memory_save, memory_sessions, memory_consolidate, etc.).
• Hook plugins for Claude Code (12 hooks) and Codex (6 hooks) that capture observations automatically on every tool call, prompt and compaction event.
• Hybrid retrieval: BM25 + vector + knowledge graph, fused via Reciprocal Rank Fusion (RRF, k=60), with per-session diversification.
• 4-tier memory consolidation inspired by how the human brain processes memory during sleep: Working (raw observations) → Episodic (session summaries) → Semantic (extracted facts and patterns) → Procedural (workflows and decision patterns).

That last part is what makes it interesting. It’s not just a log of everything that happened. There’s decay (Ebbinghaus curve — memories that aren’t accessed decay), reinforcement (frequently accessed memories strengthen), stale eviction, contradiction detection and resolution. Exactly what’s missing from the “write to ./.docs/ by hand” pattern.

Quick install

Three options: npm global, npx, or (what I did) a dedicated prefix to dodge mise/Node version churn. The one-liner version from the project README:

npm install -g @agentmemory/agentmemory     # once — `agentmemory` on PATH
agentmemory                                  # spin up the daemon on :3111
agentmemory demo                             # seed sample sessions + validate recall
agentmemory connect claude-code              # wire your agent (also: codex, cursor, gemini-cli, ...)

For full details, the agentmemory README covers every variant (Docker, source build, Windows, embedding providers). For folks using mise to manage Node, it’s worth installing into a dedicated prefix (something like ~/.local/share/agentmemory-npm/) and starting the daemon via a systemd user unit, so global packages don’t vanish when mise swaps Node versions. But the README path works for most cases.

After the daemon is up, the main step is registering the MCP server in whichever agent you use.

For Claude Code, edit ~/.mcp.json:

{
  "mcpServers": {
    "agentmemory": {
      "command": "/path/to/agentmemory-mcp",
      "env": { "AGENTMEMORY_URL": "http://localhost:3111" }
    }
  }
}

Verify with claude mcp list. You should see agentmemory: ✓ Connected.

For Codex CLI, edit ~/.codex/config.toml:

[mcp_servers.agentmemory]
command = "/path/to/agentmemory-mcp"

[mcp_servers.agentmemory.env]
AGENTMEMORY_URL = "http://localhost:3111"

For opencode, edit ~/.config/opencode/opencode.json and add at the root of the object:

{
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["/path/to/agentmemory-mcp"],
      "enabled": true,
      "environment": { "AGENTMEMORY_URL": "http://localhost:3111" }
    }
  }
}

After this, the three agents share the same memory server. Save a decision in Claude Code, run memory_smart_search in Codex and it shows up.

To push the agent toward consulting memory at the start of non-trivial tasks, it’s worth adding a line to CLAUDE.md (or equivalent):

At the start of non-trivial tasks, call `memory_smart_search` with the task
keywords. Use `memory_save` or `memory_lesson_save` when capturing decisions,
patterns, or preferences worth keeping.

Otherwise the agent uses the tools when it judges it useful, but will skip them on purely exploratory sessions.

Practical upside: frictionless handoff

Here’s the thing that sold me. Remember the export-to-markdown pattern I described earlier, for migrating between agents? With agentmemory, it’s automatic. You save an architectural decision in a Claude Code session (memory_save type=architecture content="we use cookie store instead of session store because X"). Open opencode in the same project. Ask about session persistence. opencode calls memory_smart_search, retrieves the entry, and works from there.

Forget the “export to markdown, open the other agent, tell it to read”. Both agents read from the same place. Vendor lock stops making sense in this setup, because the memory source is external to both.

The trade-offs that stay

This isn’t magic. Some things to keep in mind:

The ideal embedding layer is a paid API (Voyage, OpenAI, Cohere). Without that, agentmemory uses local MiniLM via @xenova/transformers, which works but is slower on first ingest and less accurate on complex semantic queries. For anyone fine with a local model, it’s a real solution. If you want max recall quality, the API key is worth it.

The daemon runs as a permanent process. Needs a systemd unit (I run mine in user mode) or launchd on macOS. There’s no “start the server when you remember” — it has to stay up, or the plugin hooks miss events.

The 4-tier consolidation uses an LLM to process. Without a provider key configured, agentmemory runs in “no-op mode” — still indexes observations and searches, but doesn’t compress or consolidate. You still have the equivalent of the wiki, just without Karpathy’s “periodic lint.”

And like any new tool, the docs have holes. Some things to watch for that aren’t in the upstream README: the real state path depends on how the daemon is started (relative to its cwd), the iii engine’s port 49134 binds to 0.0.0.0 by default (passes through your firewall, worth checking), import-jsonl doesn’t honor the --dry-run flag despite the global help saying it does. Read the project README first, and be ready to debug when the docs fall short.

Memory is text. Text needs management.

The synthesis I take from all this is simple. Agent memory, at the root, is text. No proprietary schema, no binary format, no secret state. That’s liberating: you’re not locked to a vendor, you can move between Claude Code, Codex and opencode whenever you want, manually or via an external layer like agentmemory.

But loose text turns into garbage fast. Without compaction, the context window fills up and the agent gets slow and expensive. With compaction, you lose long-term memory. Without the discipline to save into files, important decisions evaporate on the next compaction. Without structure across files, they turn into a pile the agent can’t read efficiently.

The answer is a combination of four layers:

• Compaction solves the full-context-window problem. The big three (Claude Code, Codex, opencode) handle that by themselves.
• Manual markdown in ./.docs/ or ./docs/ is the baseline fallback that always works, at the cost of demanding discipline from the programmer.
• LLM Wiki pattern (Karpathy) lifts manual markdown into a structured workflow: source / wiki / schema, with ingest / query / lint.
• agentmemory (or similar MCP-based tools) automates the wiki, adds tiered consolidation, hybrid retrieval, memory lifecycle, and as a bonus serves the three agents off the same daemon.

The most underrated piece of all this is the compound effect. An architectural decision saved today is available for every future session, in any agent. A library gotcha discovered on Tuesday doesn’t need to be re-discovered on Sunday. It’s the kind of productivity that takes a few weeks to show up (you need critical mass of saved memories first) but that changes the game once it lands.

Worth testing. If you use Claude Code, Codex or opencode every day and never set up anything for long-term memory, start simple (a ./.docs/ in the current repo). When the frustration of the third “explanation I already gave” hits, install agentmemory.