ai-memory 3.1.1: Claude Code and Codex share one git-backed markdown memory

ai-memory is an open-source project by the developer Fabio Akita (GitHub: akitaonrails), created in May 2026, written in Rust and licensed MIT. It exists to solve one handoff: quit Claude Code mid-task, open Codex in the same directory, and continue without re-explaining the architecture, the failed attempts, or the open questions. On 2026-10-17T18:09:02Z it shipped version 3.1.1, whose changelog holds a single “Fixed” section — 28 entries, none of them a feature. The heaviest is a Windows main-thread stack overflow: as the async CLI command tree grew, every integration test in the native Windows suite that launched ai-memory aborted before it could handle a command.

Key points

• 3.1.1 adds nothing. Besides the Windows stack fix, it repairs hook events stranded when a harness kills the process after the spool file is synced but before its atomic rename, and hardens OIDC credential transport after CodeQL alert #176.
• “More than twenty harnesses” and “zero LLM calls by default” were already the project’s own wording in the 2.0 post on 2026-09-02, so they are old claims, not 3.1.1 selling points. The feature work landed in 3.1.0 a day earlier: IBM Bob, CodeBuddy Code, native-history continuation across managed harnesses, and a Windows logon service.
• Memory’s source of truth is a git-versioned markdown wiki, and ai-memory reindex rebuilds page rows, links and FTS from it; sessions, observations, handoffs and embeddings live only in SQLite and are not rebuilt. GitHub API on 2026-10-18: 10,084 stars, 727 forks, 3,922 commits.

Background

The repository was created on 2026-05-21, and GitHub lists about 150 named contributors. Releases come fast: 3.0.0 on October 14, 3.0.1 on the 15th, 3.1.0 on the 16th, 3.1.1 on the 17th. 3.1.0 is the one with features — first-party IBM Bob and Tencent CodeBuddy Code integrations, ai-memory run handing a receiving harness a private temporary dossier of the previous harness’s visible history, a two-command install.ps1 with a Windows logon service, setup --web, and a Tauri desktop installer preview.

The site carries more than one memory entry now, and the closest to ai-memory is deja-vu: it also makes no model calls by default and also lets Claude Code and Codex see what the other did. deja-vu indexes the session files already on disk with one Go binary and pure lexical search; ai-memory captures live through hooks, compiles sessions into editable markdown wiki pages, and hands unfinished work to the next agent through a claim-once handoff. Basic Memory also treats Markdown files as the memory itself. Graphiti is Zep’s temporal knowledge graph; ai-memory shares its interest in facts that change, without a graph database and without full temporal reasoning. Cross-agent sharing is also a different problem from the markdown long-term memory LangChain described for Deep Agents, which manages one harness’s context window rather than moving context between vendors.

What 3.1.1 changes

The stranded-hook fix is the one most likely to matter in daily use. As the changelog describes it, a harness that kills the process after the spool file is synced but before the atomic rename leaves the event stuck forever. A later drain now adopts complete, valid *.json.tmp entries after a five-minute grace period and removes malformed remnants. Claude Code installs now give SessionEnd 15 seconds instead of its 1.5-second default; plugin hooks cannot raise their timeout through Claude, so they rely on the recovery path (#1377).

The OIDC entry traces to CodeQL alert #176: the shared refresh-grant sink now requires a typed TLS-or-loopback endpoint, and device authorization and token polling revalidate endpoints immediately before each request, so a caller-mutated discovery object can no longer bypass the login-time HTTPS check. A related fix stops device login and refresh from sending credential-bearing requests to non-TLS endpoints (#1354). A separate fix repairs a config bug with real consequences: the anthropic and openai providers silently dropped an explicit llm_base_url (or AI_MEMORY_LLM_BASE_URL), sending requests and the API key straight to api.anthropic.com or api.openai.com with nothing in the log (#1347). Anyone routing through a gateway was not routing through it.

The documentation corrections matter too. 3.1.1 removes stale claims that Windows has no service step and that its install is experimental; the changelog states that the 3.1 install.ps1 plus setup Windows service step “is shipped production, not experimental” (#1271). Bitdefender is only half resolved: 3.1.0 stopped shelling out to reg.exe for the Run key after Bitdefender’s behavioral engine quarantined ai-memory.exe over it, and 3.1.1 writes plain paths instead of the \\?\ verbatim prefix, but the changelog says this “does not by itself resolve Bitdefender’s behavioral detection.”

How the memory is stored

One Rust binary runs an MCP/HTTP server over a single data directory: wiki/ for the markdown source of truth under git, raw/ for immutable sanitized managed-session segments, db/ for the SQLite database holding both the rebuildable index (FTS5, entities, links) and the state that exists only there (sessions, observations, handoffs, embeddings), models/ reserved for local embedding models, and logs/. Hooks POST observations to the server, which serializes writes through one SQLite writer and compiles each finished session into markdown pages.

Retrieval fuses FTS5, entity match and graph-neighbour scores through reciprocal rank fusion, adds optional vector RRF, and layers on an observation-evidence stream that is on by default: a session’s page gets lifted when its captured turns match the query. Cross-agent handoffs are typed, have an owner, and can be claimed exactly once. On a team server, knowledge is shared per project while personal handoffs stay personal, and multi-user auth, per-person attribution and an audit log are built in rather than sold as a tier.

The zero-LLM boundary needs precision. Capture, search and handoffs need no API key. In the ageing path, access-weighted retention is always on because it can only keep memory longer; the parts that rewrite or drop content — compaction, dedup, per-tier decay curves — stay off until you enable them. The README says near-duplicates collapse into one page and likely contradictions get flagged, both with zero API calls. Nothing is hard-deleted: the original stays in git and restore-page brings it back.

Install paths number more than five: install.sh with a SHA-256 check plus ai-memory setup on Linux and macOS, install.ps1 on Windows, AUR and RPM packages, a Docker image, a macOS menu-bar app, and marketplace plugins for Claude Code and Codex. The server binds to loopback by default and init mints a bearer token. Capture is sanitized at a typed privacy boundary, and each repository can exclude paths with [capture] rules or invert to allowlist mode.

Three counts, two Windows answers

The same question — how many agents does it support — gets three answers inside one repository. The website says “Works with 32 coding agents”; the README says “More than twenty harnesses”; docs/support-matrix.md has 48 rows; once 5 platform rows, 2 feature rows and 2 provider rows are removed, 39 agent entries remain: 24 Supported, 6 MCP-only, 6 “MCP-only (documented)”, 2 Hooks-only and 1 Managed-only. The matrix states at the top that the six documented rows have a hand-written recipe nobody has run end to end, and those rows are not in the README’s compact view at all.

Windows gets two answers on the same day. Both the README and the support matrix still read “Native Windows | Experimental”, while the 3.1.1 changelog says the Windows install and service step are production. Both statements sit in the author’s repository. I have not picked one for him; readers have to judge by what happens on their own machine.

The counting problem is survivable. Splitting MCP-only, Hooks-only and Managed-only is more honest than most projects bother to be. Three unreconciled numbers still mean any citation has to say which one it is using.

Benchmarks and outside coverage

The published retrieval number is 0.951 hit@5 on LongMemEval-S v1, across all 470 questions, re-run on 2026-10-16 against commit a288a10 with the dataset’s sha256 starting 08d8dad4. The same report gives FTS hit@1 of 0.857, hit@10 of 0.972, p50 12 ms and p95 101 ms, with 528 mean context tokens for the top five hits. Every number comes from the project’s own harness. The website labels it “caveats included” and states that hit@5 “measures retrieval, not answer accuracy.” I found no third-party reproduction or comparison.

Independent reporting amounts to one article. Nilton at LinuxPro covered the 2.4 to 2.6.3 run on 2026-10-10 and closed with a disclosure: “As descrições acima vêm das notas oficiais, não de benchmarks próprios” — the descriptions come from official release notes, not from his own benchmarks. Two of his caveats are worth keeping. A complete backup has to preserve the database state, not just copy the wiki; and turning off an agent’s confirmation prompts is not a security mechanism. The first is right, and the repository’s own docs back it. The README calls the database a “derived index that can always be rebuilt from the files,” and docs/backup.md puts db/ in the do-not-back-up column because it can be rebuilt with ai-memory reindex. But docs/lifecycle-ops.md draws the boundary precisely: reindex rebuilds workspaces and projects, the latest page rows, page links and FTS. Sessions, observations, handoffs, users/tokens, audit rows, access counters and embeddings are DB-only state, are not rebuilt, and need a backup if you want them. Another passage in docs/backup.md says the same — those records “live only in the DB” and come back only from the paired tarball. Delete db/ and run reindex, then, and you do not get everything back; a complete backup has to include db/. That is Nilton’s warning, not a stale version-specific one: he places it in his “Ponto de partida” section, followed directly by “Esses fundamentos já existiam antes da 2.4” — these foundations predate 2.4.

Community reaction is essentially absent. HN Algolia shows a single 2.0 submission (2026-09-02, item 49543786) with 1 point and no comments. There is nothing here to write up as a discussion, and we are not inventing one.

Our take

For a team already running Claude Code and Codex that would rather not hand its project context to either vendor, ai-memory is one of the few options you can self-host today: a binary, a data directory, one reachable server, and memory as markdown you can grep or open in Obsidian. Backups and migration do not depend on a vendor. Zero LLM calls by default also means “remembering things” does not burn tokens as a separate line item.

The difference from deja-vu is where the data comes from and how it gets written: deja-vu indexes session files already on disk and can search months of history the day you install it, with no hooks; ai-memory needs hooks and a running server, and in exchange compiles finished sessions into pages you can edit and share with a team. The difference from Basic Memory is automatic capture plus cross-agent handoff: Basic Memory is a notebook people and agents both write, while ai-memory records from the session lifecycle and passes unfinished work to the next agent exactly once. The difference from Graphiti is the setup cost: no graph database to run, at the price of full temporal reasoning — the README calls its version bi-temporal-lite.

The honest catches are specific. The support matrix marks 24 agent rows as Supported, not 32. Windows is still described as both experimental and production. The zero-LLM ageing features that rewrite content are off by default and have to be switched on. Capture records prompts and some tool observations, and after redaction the project still warns that “filtering can miss sensitive text.” One more disclosure is in the README’s acknowledgements: the codebase is being built collaboratively with Claude Code (Opus 4.7). That is worth knowing, and worth reading as transparency rather than a deduction.

How to try it

On a Linux or macOS machine, two commands:

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

setup lists the agents it found, asks for confirmation, and wires MCP and hooks. Restart your agent and ask what it remembers about the project. To see the plan without changing anything, run ai-memory setup --plan; to tick agents in a browser instead, use --web.