# ai-memory

> Long-term memory for AI coding agents that persists context across sessions and enables seamless handoffs between different agent CLIs like Claude Code, Codex, and Cursor.

ai-memory is an open-source Rust tool that gives AI coding agents a shared, persistent wiki compiled from sanitized lifecycle observations. Built by Fabio Akita (akitaonrails), it solves the fundamental problem of LLM coding agents losing all context when a session ends — letting you quit Claude Code mid-task and continue in Codex or Cursor without re-explaining the architecture, failed approaches, or open questions.

## What It Is

ai-memory runs as a local or homelab MCP/HTTP server that intercepts lifecycle hooks from supported agent CLIs and compiles session observations into a git-versioned markdown wiki. The wiki is plain markdown — `grep`-able, openable in Obsidian, and backed up with `rsync`. There is no vector database to manage and no manual context-loading ceremony. When a session ends, relevant observations are compiled into a coherent summary; the next agent receives a bounded handoff before its first prompt. The project describes its approach as a "Karpathy-style LLM wiki" — compile, don't retrieve raw logs.

## Architecture and Storage Model

One Rust binary runs an MCP/HTTP server and owns a single data directory with four subdirectories: `wiki/` (markdown source of truth, git-versioned), `raw/` (immutable sanitized managed-workstream transcript segments), `db/` (SQLite indexes including FTS5, entities, and embeddings), and `logs/` (rolling tracing output). Hooks POST observations to the server, which serializes writes through one SQLite writer, compiles session observations into markdown pages, and serves retrieval through FTS5, entity-match and graph-neighbor RRF, optional vector RRF, bounded source-authority adjustment, and bounded raw-observation fallback.

Key architectural properties:
- **Per-project isolation by construction** — each project lives at `<wiki_root>/<workspace_id>/<project_id>/…` keyed by stable UUIDs
- **LLM is opt-in** — zero-LLM mode still provides FTS5, entity, and graph-neighbor search plus rule-based summarization
- **Authority-aware recall** — FTS5, entity-match RRF, graph-neighbor RRF, and optional vector RRF generate candidates, with a bounded adjustment favoring maintained `_rules/`, `decisions/`, `procedures/`, and `gotchas/` pages
- **Entity-assisted recall** — consolidation stores up to 10 specific nouns per page in canonical `entities:` frontmatter for lexical matching without query-time LLM calls

## Agent Support Matrix

ai-memory supports a wide range of AI coding agent CLIs through MCP configuration and lifecycle hooks:

- **Full support (MCP + hooks):** Claude Code, Codex, Command Code, Devin CLI, OpenCode, Cursor, Gemini CLI, Antigravity CLI, Grok Build CLI, Kimi Code, OpenClaw, Oh My Pi / OMP, Kiro CLI (v2 and v3), Zero
- **MCP-only:** Claude Desktop (via `mcp-remote`), VS Code GitHub Copilot agent mode, Zed, Swival CLI
- **Managed workstreams:** `ai-memory run` provides transparent cross-harness continuity for Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, Kiro CLI v2/v3, OMP, Grok Build CLI, and Antigravity CLI
- **LLM/auth providers:** Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, and OpenAI-compatible endpoints
- **Embedding providers:** OpenAI, Voyage, Google Gemini, and keyless OpenAI-compatible endpoints such as Ollama, LM Studio, and vLLM

## Deployment Model

The server runs locally (loopback) or on a homelab box (LAN/VPN/cloud) with bearer-token auth. The published Docker image supports `linux/amd64` and `linux/arm64`. Native packages are available for Arch Linux via AUR (`ai-memory-bin` for prebuilt, `ai-memory` for source build), and tagged releases publish native binaries for macOS (aarch64 and x86_64), Linux, and Windows. The default quick-start binds to loopback only with no authentication — safe for single-user laptops. For multi-user or LAN deployments, bearer auth and HTTPS via a reverse proxy (Caddy or Cloudflare Tunnel templates are included) are recommended.

## Update: v1.29.0

The latest release is v1.29.0, published on August 19, 2026. The repository was created in May 2026 and has seen rapid development, accumulating over 3,200 GitHub stars and 267 forks. The project is actively maintained with frequent tagged releases and a comprehensive support matrix that has expanded to cover over 20 agent CLIs. Recent additions include managed workstream support for Kiro CLI v3, Grok Build CLI, Antigravity CLI, and Zero, as well as per-operator memory slots, auto-improvement scheduling, and a built-in read-only web UI with a JSON frontend API at `/api/v1`.

## Features
- Long-term persistent memory across AI coding agent sessions
- Cross-agent handoffs between Claude Code, Codex, Cursor, and 20+ other CLIs
- Git-versioned markdown wiki as source of truth
- Zero-friction lifecycle hook capture (fire-and-forget)
- Managed workstreams with native per-harness session resume
- FTS5 full-text search with entity-match and graph-neighbor RRF
- Optional vector embeddings for semantic retrieval
- Authority-aware recall favoring rules, decisions, and procedures pages
- Per-project isolation by construction using stable UUIDs
- LLM-optional mode with rule-based summarization fallback
- Built-in read-only web UI at /web with markdown rendering
- JSON frontend API at /api/v1 for custom UIs
- Auto-improvement scheduler for post-session wiki refinement
- Bootstrap command for projects with existing history
- Per-repository capture exclusions via .ai-memory.toml
- Multi-user attribution with per-operator memory slots
- Bearer token auth with HTTPS reverse proxy support
- Docker and native binary deployment options
- AUR packages for Arch Linux with systemd units
- Tab completion for bash, zsh, fish, PowerShell, and elvish
- Thin-client CLI for all admin operations
- Page TTL/expiry support
- Checkpoint-based page recovery with git history
- Session finalization and handoff management

## Integrations
Claude Code, OpenAI Codex, Cursor, Gemini CLI, Command Code, Devin CLI, OpenCode, Kimi Code, Kiro CLI, Oh My Pi / OMP, OpenClaw, Antigravity CLI, Grok Build CLI, Zero, Swival CLI, VS Code GitHub Copilot, Zed, Claude Desktop, Anthropic API, OpenAI API, GitHub Copilot API, Google Gemini API, Ollama, LM Studio, vLLM, OpenRouter, Voyage embeddings, Docker, Caddy, Cloudflare Tunnel, Obsidian, SQLite, Git

## Platforms
WINDOWS, MACOS, LINUX, API, VSC_EXTENSION, CLI

## Pricing
Open Source

## Version
v1.29.0

## Links
- Website: https://github.com/akitaonrails/ai-memory
- Documentation: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md
- Repository: https://github.com/akitaonrails/ai-memory
- EveryDev.ai: https://www.everydev.ai/tools/ai-memory