Getting started with ai-memory and regolo: persistent codebase memory across opencode, claude code, and codex

Each time you stop a Claude Code session mid-task and open OpenCode, Codex, or Cursor in the same repo, the new agent starts cold. It cannot read the previous tool’s private notes, so its first ten turns go into re-reading files you already checked and retrying strategies you already rejected. ai-memory (12.6k GitHub stars, MIT, Fabio Akita) eliminates that cold start by compiling sessions into a Git-backed Markdown wiki (<data_dir>/wiki/) and passing a claim-once handoff packet to the next agent.

Does ai-memory save tokens? And when does it actually call an LLM? By default, it uses 0 LLM calls: lifecycle hooks catch prompts and tool calls, SQLite FTS5 indexes your Markdown pages, and cross-agent handoffs work without spending a single API token. When you enable background LLM consolidation and hybrid vector search on Regolo’s OpenAI-compatible endpoint, our live test on a multi-file repo cut session warm-up prompt tokens by 79.2% (26,185 down to 5,453 tokens, and up to 95.2% on 90-turn refactoring handoffs) while stopping the next agent from repeating failed changes.

How ai-memory works: zero-llm capture versus opt-in regolo consolidation

In contrast to hosted memory APIs that call an LLM on every roundtrip and put your notes in a black-box vector DB, ai-memory keeps disk-based plain Markdown files (<data_dir>/wiki/) as the single source of truth. The SQLite DB (db/) is a secondary index that can always be rebuilt from those Markdown files. To see where the tool saves tokens, distinguish the default zero-LLM route from opt-in LLM consolidation:

Two configuration details from ai-memory‘s official provider documentation matter when you connect an open-weight endpoint:

# ~/.config/ai-memory/regolo.env
LLM_API_KEY="your-regolo-api-key"

# 1. LLM Consolidation on Regolo (disable thinking so strict JSON is never truncated)
AI_MEMORY_LLM_PROVIDER="openai-compat"
AI_MEMORY_LLM_BASE_URL="https://api.regolo.ai/v1"
AI_MEMORY_LLM_MODEL="qwen3.5-122b"
AI_MEMORY_LLM_COMPAT_STRICT="true"
AI_MEMORY_LLM_COMPAT_DISABLE_THINKING="true"

# 2. Hybrid Vector Search with Qwen3-Embedding-8B (no trailing space after Query:)
AI_MEMORY_EMBEDDING_PROVIDER="openai-compat"
AI_MEMORY_EMBEDDING_BASE_URL="https://api.regolo.ai/v1"
AI_MEMORY_EMBEDDING_MODEL="Qwen3-Embedding-8B"
AI_MEMORY_EMBEDDING_DIM="4096"
AI_MEMORY_EMBEDDING_QUERY_PREFIX="Instruct: Given a codebase memory query, retrieve relevant wiki pages\nQuery:"Code language: Bash (bash)

Setting AI_MEMORY_LLM_COMPAT_DISABLE_THINKING="true" makes ai-memory pass chat_template_kwargs: {"enable_thinking": false} on every openai-compat consolidation call, so Qwen3-series models use 100% of their output tokens for the structured wiki JSON instead of burning the budget on internal thinking.

For embeddings, Qwen3-Embedding-8B needs an instruction prefix on the query side only, with no space after Query:.

Inspecting real token savings in Regolo Memory Studio

To measure how much context ai-memory saves when an agent comes back to a repo (and to inspect the compiled OKF v0.2 Markdown pages side by side), we created Memory Studio (regolo-ai/tutorials/memory-studio, Python 3.10+ stdlib only, python3 memory_wizard/server.py).

It reads a local repo with git ls-files, strips secrets at the capture boundary, compiles wiki/decisions/*.md, wiki/procedures/*.md, and wiki/handoffs/*.md, and compares a cold full-file session against a warm handoff session:

REGOLO MEMORY STUDIO · WIKI & HANDOFF INSPECTOR

Select a cross-agent transition and compare cold rescans against compiled wiki handoffs

Start the local web inspector with python3 memory_wizard/server.py (http://127.0.0.1:8210) to test any model from GET /v1/models on your own project folder.

STEP 3 · .GITIGNORE-AWARE CAPTURE & HANDOFF TRANSITION

Pick claude-code → opencode, opencode → codex, or wiki bootstrap

Applies git ls-files ignore rules and redacts API keys/tokens before compiling observations into durable Markdown pages.

STEP 4 · MEASURED TOKEN SAVINGS & OKF V0.2 WIKI PAGES

26,185 → 5,453 prompt tokens (−79%) and 27,760 → 6,587 total tokens (−76%)

Displays the compiled wiki/decisions/, wiki/procedures/, and wiki/handoffs/ Markdown files alongside the generated ~/.config/ai-memory/regolo.env file.

Does ai-memory actually save tokens? When it helps and when it does not

A memory tool only saves tokens when the startup brief and wiki pages it injects are smaller than the exploratory file reads they replace. In both the web inspector and our 90-turn multi-file refactoring tests, how you use your coding agents directly determines the savings:

When will it not save tokens? If you run a single one-off prompt in a small repo and never switch agents or revisit the task. In that case, turning on eager per-turn LLM consolidation spends more tokens writing wiki pages than you save.

That is why ai-memory keeps per-turn capture 100% deterministic (0 LLM calls) and runs LLM consolidation only at session checkpoints or on demand with memory_consolidate (under a cent per run: €0.0065 on Regolo Pay-As-You-Go, or negligible pool usage in Regolo Core).