# 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](https://github.com/akitaonrails/ai-memory) (12.6k GitHub stars, MIT, Fabio Akita) eliminates that cold start by compiling sessions into a Git-backed Markdown wiki (`/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](https://regolo.ai/pricing/), 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. FEATURED AGENT MEMORY · GITHUB TRENDING ★ **12.6k** stars **20+** coding harnesses License: **MIT** ### [akitaonrails / ai-memory](https://github.com/akitaonrails/ai-memory) Created by **Fabio Akita** (@akitaonrails) Persistent long-term codebase memory and claim-once cross-agent handoffs across OpenCode, Claude Code, Codex, Cursor, and Gemini CLI, backed by a plain Markdown repository wiki (OKF v0.2) and zero-LLM FTS5 + entity search by default. `$curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh` Works with OpenCode · Claude Code · Codex · Cursor · Gemini CLI [View ai-memory on GitHub →](https://github.com/akitaonrails/ai-memory) [Open Regolo Memory Studio ↗](https://github.com/regolo-ai/tutorials/tree/main/memory-studio) Zero-LLM Default · Git-backed Markdown Wiki · Claim-Once Handoffs --- ## 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 (`/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: QUICK CONFIGURATION · ZERO-LLM HOOKS + REGOLO CONSOLIDATION### Set up ai-memory and connect Regolo in 3 steps Use the zero-LLM lifecycle hooks for daily capture, and point **openai-compat** to **https://api.regolo.ai/v1** when you want LLM-written wiki pages and **Qwen3-Embedding-8B** vector recall. STEP 01 · ZERO-LLM SETUP Install & wire agents ai-memory setup ai-memory bootstrap Installs hooks + MCP for OpenCode, Claude Code, and Codex with **0 API calls**. STEP 02 · REGOLO PROVIDER Configure openai-compat AI_MEMORY_LLM_PROVIDER="openai-compat" AI_MEMORY_LLM_BASE_URL=\ "https://api.regolo.ai/v1" AI_MEMORY_LLM_COMPAT_DISABLE_THINKING="true" Disables thinking tokens so structured JSON consolidation never truncates. STEP 03 · HANDOFF Switch agents mid-task ai-memory run claude ai-memory run opencode ai-memory continue Passes a claim-once startup brief + temporary native history projection. 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:`. --- ZERO DATA RETENTION ### Get engineering notes and model releases in your inbox. Sovereign AI inference, OpenAI-compatible, EU-hosted. Benchmarks, new models (Mistral, Qwen, GLM), and cost insights. One email, no spam. ✓ #### Thank you for subscribing! Please check your inbox to confirm your subscription. Subscribe Free I accept the [Privacy Policy](https://regolo.ai/privacy-policy/) \* 100% European infrastructure · Zero spam · Unsubscribe anytime. ## 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](https://github.com/regolo-ai/tutorials/tree/main/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. ![Regolo Memory Studio selecting a repository folder and cross-agent handoff transition](https://raw.githubusercontent.com/regolo-ai/tutorials/main/memory-studio/docs/img/app-project.png) 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. ![Regolo Memory Studio Compare mode showing 79% fewer prompt tokens and compiled OKF v0.2 wiki pages](https://raw.githubusercontent.com/regolo-ai/tutorials/main/memory-studio/docs/img/app-compare.png) 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. OPEN-SOURCE WIKI & HANDOFF INSPECTOR · MIT LICENSE ### Clone Regolo Memory Studio on GitHub Test `ai-memory` consolidation and Claim-Once handoffs on your own repository with `python3 memory_wizard/server.py`. [Open memory-studio on GitHub →](https://github.com/regolo-ai/tutorials/tree/main/memory-studio) --- ## 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: CAPTURE & FTS5 0 LLM tokens Default hook & search path Unlike per-turn fact extractors (Mem0/LangMem), `ai-memory`'s default capture, FTS5 search, and rule-based handoffs use **zero API calls**. REPO WARM-UP −79.2% Single-repo Compare run In Regolo Memory Studio (Oct 22, 2026), resuming from compiled wiki cards cut prompt tokens from **26,185 to 5,453** (and total time from 12.8s to 9.7s). 90-TURN HANDOFF −95.2% Long-session harness switch When switching from Claude Code to OpenCode after a 90-turn session, the Claim-Once brief + top-2 wiki pages used **2,485 tokens vs 52,262** for a cold rescan. AVOIDED REWORK 100% (6/6) Failed-approach guardrails The largest hidden saving is stopping the next agent from re-running a broken idea (e.g., setting SQLite `synchronous=OFF` after a prior crash test). WITHOUT AI-MEMORY · SILOED PER-AGENT NOTES#### What happens when you switch agents mid-task **1. 26K–52K cold-start discovery tax**Opening Codex or OpenCode after Claude Code hits a rate limit forces the new agent to re-read your directory tree and config files from scratch. **2. Repeating failed experiments**Because rejected ideas lived only in the previous agent's chat scrollback, the new agent wastes 5–10 turns re-discovering the same bug. **3. Locked inside one machine or vendor**Built-in `MEMORY.md` files do not sync across 20+ CLI harnesses or across teammates working on the same repository. Prompt tokens on agent switch**26,185 – 52,262 tokens** WITH AI-MEMORY + REGOLO CONSOLIDATION#### Git-backed OKF v0.2 wiki + Claim-Once handoffs **1. Bounded startup brief on `ai-memory run`**The receiving agent starts with `Where We Left Off`, `Locked Decisions`, and a temporary local projection of the previous session. **2. Zero-LLM aging + opt-in Regolo consolidation**Daily capture and FTS5 cost 0 tokens; background consolidation on `brick-complexity-pro` and `qwen3.5-122b` compiles clean wiki pages. **3. Plain Markdown you own in Git**Every page in `wiki/decisions/` and `wiki/procedures/` is human-editable in Obsidian or VS Code and processed under EU Zero Data Retention. Prompt tokens on agent switch**2,485 – 5,453 tokens (−79% to −95%)** **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). PRODUCTION-READY EU INFERENCE · ZERO DATA RETENTION OpenAI-Compatible API ## Ship Private AI. Not Infrastructure. You have the architecture and the open-source workflow. Now give it a sovereign European inference layer built for production: fast access to **GLM-5.2, Qwen3.5, Mistral, Llama, DeepSeek**, and **Brick Complexity Pro** with zero data retention and no new SDK to learn. DROP-IN ENDPOINT `export OPENAI_BASE_URL="https://api.regolo.ai/v1"` Keep your existing SDK & agent setup [ 30-DAY FREE TRIAL ### Start your 30-day free trial → Build, test, and deploy with no infrastructure to maintain. Core plans from €11.70/mo (70% off first 3 months). ](https://regolo.ai/pricing/?utm_source=blog&utm_medium=footer_stub&utm_campaign=tutorials) [ OPEN-SOURCE CODE ### Clone the GitHub repository → Get the full implementation, configuration scripts, evaluation benchmarks, and ready-to-run templates. ](https://github.com/regolo-ai/tutorials/) [ BUILDER COMMUNITY ### Join the Regolo Discord → Meet engineers building with coding agents, private RAG, local LLMs, and production open-weight models. ](https://discord.gg/bqGrVJHeF) [ ARCHITECTURE REVIEW ### Talk to an AI Infrastructure Engineer → Scaling beyond a proof of concept or running regulated EU workloads? Get a tailored architecture and commercial plan. ](https://regolo.ai/contacts/?utm_source=blog&utm_medium=footer_stub&utm_campaign=tutorials) **Private AI should not require a private data center.** Regolo gives your team an EU-native path from local experimentation to production-grade inference. [API Docs](https://docs.regolo.ai) · [GitHub](https://github.com/regolo-ai/tutorials/) · [Discord](https://discord.gg/bqGrVJHeF) · [X (@regolo\_ai)](https://x.com/regolo_ai) · [Reddit](https://www.reddit.com/r/regolo_ai/) · [Contact](https://regolo.ai/contacts/) Built by the Regolo team · 100% EU Sovereign GPU