ai-memory: switch from Claude Code to Codex without explaining your project again

Commented AKITA? Here is the link and the step by step. ai-memory is a free, open-source tool that gives memory to AI coding agents (Claude Code, Codex, Cursor, Gemini CLI and more than 20 others). While you work, it takes notes on its own: what you asked for, what failed and what is still open. So if Claude’s limit runs out mid-task, Codex starts out knowing where you left off, instead of you explaining everything again.

The project’s official logo (README, MIT licence, Fabio Akita).

First, five truths:

• ai-memory is free, the AI is not. It is free and open source (MIT licence). Claude Code and Codex keep their own plans: your plan’s limits and billing still apply.
• It does not “remember everything”. The next agent gets a handoff: where you left off, what failed and what is still open, and it can search for the rest. The official site warns that what comes back can be incomplete or outdated (aimemory.sh, 30/10/2026).
• It is for people who already use a coding agent (Claude Code, Codex and the like). If you only use ChatGPT or Claude in the browser, it does nothing for you yet.
• You install it from the Terminal. On Mac and Linux it is two copy-and-paste commands. On Windows, the recommended path is WSL2; plain Windows is experimental (README, 30/10/2026). It does not run on phones.
• The steps come from the official documentation and WERE NOT TESTED BY US. The images are screenshots of public pages and one image from the README itself.

How it works, in plain words

Think of ai-memory as a work logbook that fills itself in:

1. A recorder that switches itself on. When you use the agent, “hooks” note down your requests, the commands the agent ran and when each session starts and ends. You never have to say “remember this” (README).
2. It becomes a text file that is yours. At the end of a session, those notes become a text page (markdown) in the project’s “wiki”, kept on your computer. You can open, read, search and even edit it by hand.
3. The next agent starts out knowing. When you open another agent in the same folder, it gets a short summary of where you left off, what failed and what is still open, and can search for the rest when it needs to.
4. No API key. That default path calls no AI at all to work. The AI doing the thinking is still the one on your plan.

The four stages on the official site: capture, consolidate, recall and hand off. Captured on 30/10/2026.

The simplest path

Documentation step, not tested by us. You do not need to code, but you will copy and paste commands into the Terminal. Each command has a copy button.

curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh

Install ai-memory for me by following exactly the instructions at https://cauhi.com/learn/ai-memory/INSTALL_FOR_AGENTS.md and show me each command before you run it.

ai-memory setup

ai-memory run claude

ai-memory run codex

Pick up where we left off: tell me what was already tried, what failed and what the next step is before you touch any file.

What is true (and what the video simplified)

• “Free”: ai-memory is free (MIT). Claude Code and Codex keep their own plans, with the usual limits and billing.
• “It picks up a summary of where you left off”: yes, a handoff with where you stopped, what failed and what is still open. It does not “remember everything”, and what comes back can be incomplete.
• “A week later he walked it back”: in his 23/05/2026 post, Akita says he had recommended another memory tool five days earlier and walked it back after a week of using it, because of a data-loss window and notes that vanished silently. That is when he started ai-memory.
• “More than 20 agents”: the README says “more than twenty” and its support table lists about 35. Not “any agent”.
• The Claude and Codex screens in the video (the freelance request, the failing fixes, the limit badge, the usage bar and the session page) are an illustration of a possible use. The web memory screen is the real README image. We did not test the tool.

Going further

Optional. Documentation step, not tested by us (README, INSTALL_FOR_AGENTS.md, docs/windows.md, docs/install.md and docs/managed-workstreams.md, commit 8cb9722, 30/10/2026).

Install as a plugin (Claude Code or Codex)

The binary is still installed as in step 2; the plugin only wires the agent:

claude plugin marketplace add akitaonrails/ai-memory && claude plugin install ai-memory@ai-memory

codex plugin marketplace add akitaonrails/ai-memory && codex plugin add ai-memory@ai-memory

Codex then asks you to trust the hooks in /hooks.

Windows

• Inside WSL2 (recommended): use the Linux commands from steps 2 and 3 and launch the agent inside WSL2 too. Do not mix: if the agent runs in WSL2, ai-memory must be in WSL2 (docs/windows.md).
• Native Windows (experimental), in PowerShell, no admin:

irm https://github.com/akitaonrails/ai-memory/releases/latest/download/install.ps1 | iex

Then run ai-memory setup. On Windows it starts the server when you sign in, with no console window.

Other ways to install

• Arch Linux (AUR): yay -S ai-memory-bin (prebuilt) or yay -S ai-memory (builds), then ai-memory setup.
• Fedora: download the RPM from the latest release and run sudo dnf install ./ai-memory-*.rpm, then ai-memory setup.
• Mac menu bar app, Docker and NixOS: they exist, but need a build or more setup. They are in the project README (link in the credits).

setup options

Everyday commands with ai-memory run

Inside the agent, you can ask things like “where did we leave off?”, “have we discussed X?” or “catch me up” (README, “Everyday use”).

Details worth knowing:

• The copy of Claude’s history only exists on the same computer. On another machine you only get the server’s handoff.
• If your claude is a shell alias, ai-memory run cannot see it; use a same-named script on your PATH or --executable.
• To not record a folder, use [capture] ignore_paths in the project’s .ai-memory.toml.
• Optional AI: with an API key configured, summaries get better and semantic search turns on. Without a key, everything still works (README, “LLM providers”).
• Teams: you can run one server for everyone, with login, attribution and an audit log, with no paid tier (README, “Teams and multiple machines”).

Official instructions for agents, here on the site (MIT, Fabio Akita, unchanged, in English): INSTALL_FOR_AGENTS.md.

Quick questions

Do I need to know how to code?

Not to install it: it is two copy-and-paste commands. But ai-memory is only useful if you already use a coding agent (Claude Code, Codex, Cursor…). The official site says: “This is a tool for people already using AI to work on code.”

Is it free?

ai-memory is free and open source (MIT), with no sign-up and no API key by default. The agents are not: Claude Code and Codex keep their own plans (or paid API), with the same limits and billing. The tool does not raise your limit: it only saves you from starting from scratch when you switch.

Does it work on my computer? On my phone?

Mac and Linux: yes. Windows: through WSL2 (recommended); native Windows is experimental. Phone: no, it is a desktop tool.

Is it safe?

• The code is open (MIT) and the server, by default, listens only on your computer, with a password created at install. There is no sign-up, and the project says it sends no telemetry (DATA_HANDLING.md).
• But the hooks record your prompts. Recognised passwords and keys are redacted before saving, but filtering can miss sensitive text (aimemory.sh). Do not paste passwords or client data into the chat.
• It is not “100% offline”: on first start the server downloads a small search model (~87 MB) from Hugging Face. None of your content goes with it (DATA_HANDLING.md). And what you send to Claude or Codex still goes to them, as always.
• There is no encryption at rest in version 1: protection comes from your computer’s file permissions (DATA_HANDLING.md).
• It is an active, fast-moving project (several releases a week): start on a test project.

Does it work in Portuguese or Spanish?

It records whatever you type, in any language. The commands and docs are in English.

Honest limits

• It does not make the AI free or raise your plan’s limit.
• It does not “remember everything”: it is a handoff, and memory can be incomplete or outdated. Check important decisions.
• More than 20 agents, not “any agent”.
• Claude’s full history only on the same computer.
• Terminal required; on Windows, WSL2 is recommended. No phone app.
• It can record sensitive text that slips past the filter.
• The numbers (version, number of agents) were checked on 30/10/2026 and change. We did not test the tool or measure anything.

Credits and source

• Project: ai-memory, by Fabio Akita (“Copyright (c) 2026 Fabio Akita”), MIT licence. The logo, the web view image and INSTALL_FOR_AGENTS.md come from the repository at commit 8cb9722 (30/10/2026), with no content changes.
• Why he built it: I Built a Memory System for Coding Agents: ai-memory (Akita’s blog, 23/05/2026) and switching agents with ai-memory run (20/07/2026).
• About the author: akitaonrails.com/about and the Akitando channel.
• Official source: the aimemory.sh site and the code at github.com/akitaonrails/ai-memory.
• Community guide in Portuguese: LinuxPro (covers the older 2.6.3).
• This guide is not affiliated with Fabio Akita, Anthropic or OpenAI.

Akita’s post explaining why he built ai-memory, captured on 30/10/2026.

Public project page on GitHub, captured on 30/10/2026.