akitaonrails/ai-memory

Long-term memory for AI coding agents. Quit Claude Code mid-task,

start OpenAI Codex in the same directory, continue without

re-explaining the architecture, the failed approaches, or the open

questions.

Website: aimemory.sh

Why ai-memory

Your coding agent probably has a memory feature already. Claude Code takes its own notes, Cursor remembers some things, and every platform is adding more. They all have the same limits: the notes live on one machine, belong to one agent, and drop out of view when you switch tools or hand the work to a teammate.

ai-memory removes those limits.

• It follows you across agents. More than twenty harnesses (Claude Code,

Codex, Cursor, Gemini CLI, OpenCode, Grok, Devin, Kimi, Kiro, and others) feed one shared memory. Quit Claude Code mid-task, open Codex in the same directory, and the next agent picks up a handoff that says where you left off, what failed, and what is still open. Handoffs are a typed protocol: each one has an owner and is claimed exactly once.

• It can carry the session, not just a summary. Start agents with

ai-memory run: quit Claude Code, run ai-memory run codex, and Codex gets the shared workstream plus a private, temporary local projection of Claude's visible native history for exact details the bounded startup packet omitted. The remote server receives only the harness and session identity, never the local transcript path or body. Direct harness launches behave exactly as before.

• It follows you across projects. A small profile of how you usually

work (your package manager, test layout, architecture habits) reaches every new repository at session start, so you stop re-explaining yourself. It sits below each repository's rules file as a default. It is on by default for a single user, and on a shared server it is opt-in and private per person. See docs/cross-project-profile.md.

• It follows you across machines. Memory lives in a server you run, on

the same laptop, a homelab box, or anywhere else, so the project you left on the desktop is the project you resume on the laptop, with the same knowledge and the same open questions.

• It works for a team. Point everyone at one server, and what one

person's sessions learn, everyone's agents can retrieve. Knowledge is shared per project; personal handoffs stay personal. Multi-user auth, per-person attribution, and an audit log are built in and are not a paid tier.

• Your memory is plain markdown. The source of truth is a git-backed

wiki of ordinary .md files: grep it, open it in Obsidian, edit it by hand, rsync it. The database is a derived index that can always be rebuilt from the files. There is no vector store to maintain and no content locked in a binary blob.

• It captures the work itself, silently. Lifecycle hooks record what

happened (prompts, tool calls, session boundaries), sanitize it at a typed privacy boundary before anything is stored, and the server consolidates it into readable pages. You do not have to ask it to remember anything. The default path uses zero LLM calls: capture, search, and handoffs all work with no API key.

• It ages memory without an LLM. Memory decays on a schedule you can

tune per tier, and memory you use decays slower: opening a page, searching it, or reaching it through a link counts as use. When episodic notes go cold they can be compacted down to their durable facts (file paths, error codes, decisions) instead of dropped. Near-duplicates collapse into one, and likely contradictions get flagged, all with zero API calls. Nothing is hard-deleted: the original stays in git and the version chain (restore-page brings it back). Access-weighted retention is always on because it can only keep memory longer. The parts that rewrite or drop content (compaction, dedup, per-tier curves) stay off by default until you turn them on.

• It can also "dream", if you let it. With an LLM configured, an opt-in

background pass rewrites whole clusters of cold notes into single coherent pages while you are idle, and cancels as soon as you come back to work. It never deletes a source (the pre-merge versions stay reachable), it is off by default, and it has to pass a recall eval before it could become default behavior. Unless you ask for more, the zero-LLM path above is what runs.

• It is honest about itself. It ships as one self-contained binary.

Purge commands say exactly what "deleted" means. The write ceiling (~700/s) is measured, not guessed. An audit log records every mutation.

How it works

capture ──▶ consolidate ──▶ recall ──▶ handoff
 hooks        session-end      search     next agent,
 observe      summaries as     + brief    any harness
 silently     wiki pages       injection

Agents emit sanitized observations through lifecycle hooks as you work. At session end, observations become coherent markdown pages in the project's wiki (optionally LLM-written; useful even without). The next session, in any agent on any machine, gets a bounded brief and can search everything: full-text, entities, links, and (optionally) vectors, fused into one ranking. Cross-agent handoffs pass the baton explicitly.

The full design, including the invariants that keep multi-user and multi-session use safe, is in docs/ARCHITECTURE.md.

An optional server-rendered management console provides user administration, session inspection and deletion, and personal MCP API keys. Build with --features management-ui and start `serve --transport http --enable-management-ui`; both compile-time and runtime opt-ins are required.

Support matrix

Every row below is a first-party integration (MCP registration, lifecycle hooks, or both) checked by CI. The full matrix with per-agent notes and caveats is in docs/support-matrix.md.

| Area | Status | | --- | --- | | Linux | Supported | | NixOS module | Supported | | macOS | Supported | | Windows via WSL2 | Supported | | Native Windows | Experimental | | Claude Code | Supported | | Codex | Supported | | Command Code | Supported | | Devin CLI | Supported | | OpenCode (V1/V2 auto-detected; legacy force-V2 aliases retained) | Supported | | Cursor | Supported | | Gemini CLI | Supported | | Oh My Pi / OMP | Supported | | Pi | Supported | | Crush | Managed-only | | Managed workstreams | Opt-in | | Claude Desktop | MCP-only | | OpenClaw | Supported | | Antigravity CLI | Supported | | Grok Build CLI | Supported | | Swival CLI | MCP-only | | Zero | Supported | | ZCode | Supported | | Kimi Code | Supported | | Kiro CLI | Supported | | Pool | Hooks-only | | GitHub Copilot CLI | Supported | | Factory Droid | Supported | | Meta Muse Code | Supported | | CodeBuddy Code | Hooks-only | | IBM Bob | Supported | | Qwen Code | Supported | | Qoder | Supported | | VS Code Copilot | MCP-only | | Zed | MCP-only | | DeepSeek Harness (DSH) | Hooks + MCP | | Cline CLI | Hooks + MCP | | FreeBuff | MCP-only | | Prime Agent | MCP-only | | Hermes Agent | Supported | | GrizzyBot | Supported | | LLM/auth providers | Supported | | Embedding providers | Supported |

Coming from another tool?

Most agent-memory tools optimize for one thing: extracting atomic facts per turn, a temporal knowledge graph, an agent-editable memory OS, or a hosted context API. ai-memory is built around a git-backed markdown wiki as the source of truth, with a derived index for retrieval. It captures automatically from lifecycle hooks, is shared across agents, machines, and people, and works with zero LLM calls by default. This table shows what carries over from each tool and what you gain:

| Coming from… | What's similar | What you gain | |---|---|---| | Mem0 / fact extractors (LangMem) | Automatic per-turn capture | Memory compiles into readable pages you own and edit, not opaque fact rows; retrieval fuses FTS + entity + graph (+ local vectors) with no cloud API key | | Zep / Graphiti (temporal KG) | Temporal reasoning, typed relations | Bi-temporal-lite (as_of, version-filtered search) and typed edges without standing up a graph database, in one binary | | mcp-memory-service (fact rows, SQLite) | SQLite + local embeddings, hook capture, typed edges, honest numbers, and, on 2.4, per-tier decay curves, extractive compression, DBSCAN cold-cluster dedup, access reinforcement, and contradiction flagging | Human-editable markdown pages instead of fact-rows, cross-agent claim-once handoffs, and the same aging machinery done zero-LLM by default, reversibly (supersede-not-delete + restore-page), and off by default | | basic-memory (file-first markdown) | Markdown-on-disk as the source of truth | Automatic lifecycle capture and a derived FTS/entity/graph index on top, cross-agent handoffs, and multi-user sharing built in | | Claude Code built-in memory | "Remember my project" convenience, zero setup | Synced across machines and agents, searchable, team-capable, and captures tool lifecycle, unlike a per-laptop MEMORY.md | | Hindsight / OpenViking (LLM or VLM in the loop) | Living pages / document memory with a background consolidation loop, plus, on 2.4, belief-strength confidence plus an opt-in LLM "dream" rewrite of cold clusters | A self-contained binary that runs zero-LLM by default and keeps memory in markdown files that are the source of truth, not a mirror; claim-once handoffs; the dream/belief features are opt-in, off by default, and never delete a source (vs a mandatory LLM loop) | | Supermemory / LiquidLM (hosted memory API) | A managed second brain with automatic ingestion | Git-versioned markdown you own, no required API spend, offline operation, and per-project team sharing; ai-memory remembers this repo, not a general vault |

Across all of these, ai-memory gives you files you own (git-backed markdown), a zero-LLM default, one self-contained binary, sharing across agents, machines, and teams, automatic lifecycle capture, and typed, claim-once handoffs. Opt-in features (LLM consolidation, vector search, the "dream" consolidation pass, belief-strength in ranking) stay opt-in, and the zero-LLM aging path (per-tier decay, extractive compaction, dedup, contradiction flagging, access-weighted retention) works with no API key at all.

Built on the shoulders of: the Karpathy LLM Wiki (compile-not-retrieve), agentmemory (hook capture for coding agents), basic-memory (markdown-on-disk truth), cognee (pipeline composition and triplet embeddings), Hermes Agent (the self-improvement loop), and A-MEM (Zettelkasten-style atomic notes).

The full comparison, covering where each approach wins, where ai-memory differs, and the published benchmark, is in How ai-memory compares.

Quick start

Linux and macOS (two commands, no root)

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

install.sh downloads the release for your OS and CPU, checks it against the release's published SHA-256 checksum (it refuses to install without a match), and links ~/.local/bin/ai-memory. ai-memory setup then creates the data directory with a bearer token in an owner-only file, starts a per-user service (systemd --user or a launchd LaunchAgent), and wires MCP, hooks and Agent Skills for every agent it finds, or the ones you name with --agent. It shows the plan, with where it found each agent, and asks first: answer y, or type the numbers of the agents to wire. --plan prints the plan and changes nothing, --web shows the plan as a page in your browser and applies the agents you tick there, --yes skips the question, and running it again changes nothing. Afterwards, restart your agents and ask one of them "What do you remember about this project?" to see it answer through ai-memory. Details, the environment variables and how to verify the script before running it are in docs/install.md. An AI agent installing ai-memory for you can follow INSTALL_FOR_AGENTS.md.

Claude Code and Codex users can wire their agent as a marketplace plugin instead (the binary is still installed as above):

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. See Marketplace plugins.

Windows (two commands, no admin)

In PowerShell:

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

install.ps1 checks the release zip against its published SHA-256 checksum, unpacks it under %LOCALAPPDATA%\Programs\ai-memory and adds that directory to your user PATH. ai-memory setup then does what it does on Linux and macOS, with a logon entry in place of the service: the server starts when you sign in, with no console window, and restarts if it fails. Details and the other Windows setups (WSL2, Docker Desktop, a real Windows service) are in docs/windows.md.

Arch Linux (AUR)

For native Arch installs, use the AUR packages. They install /usr/bin/ai-memory, packaged hook sources, and both system-level and user-level systemd units.

yay -S ai-memory-bin    # prebuilt Linux x86_64/aarch64 binary
yay -S ai-memory        # builds from source
ai-memory setup         # data dir, user service, agents, self-check

Fedora (RPM)

Download the x86_64 or aarch64 RPM from the latest release, then install it:

sudo dnf install ./ai-memory-*.rpm

On a single-user workstation, ai-memory setup then does the rest, as on the two-command path above: data dir and token, a user service, the agents it finds, and a self-check.

ai-memory setup

System service installs use /var/lib/ai-memory and /etc/ai-memory/ via the packaged unit. Full user-service, system-service, auth, and provider setup is in docs/install.md#arch-linux-native-packages-aur.

macOS (menu bar app)

A self-contained .app that bundles the native ai-memory binary and hooks/ tree, starts the existing LaunchAgent, and opens /web, ai-memory status, and config.toml from the menu bar. Wiki, SQLite, config, and models stay in ~/Library/Application Support/ai-memory, so replacing the app is an update and does not rewrite that tree.

Needs a Rust toolchain and Xcode / Swift 6 (same as a source build):

git clone https://github.com/akitaonrails/ai-memory
cd ai-memory
./companions/ai-memory-macos/build.sh
open "companions/ai-memory-macos/dist/AI Memory.app"

Drag AI Memory.app to /Applications, then Install & Start Server from the menu extra (no Dock icon). The app reads the bearer token init wrote into its data dir, so the status item turns green on its own. Then wire your agents with the bundled binary; --no-service leaves the app's LaunchAgent in charge:

BIN="/Applications/AI Memory.app/Contents/Resources/runtime/ai-memory"
"$BIN" setup --no-service

Prebuilt tarball and launchd-without-the-app paths: docs/macos.md. Companion details: companions/ai-memory-macos.

Docker

You need: Docker or Podman + an agent CLI from the Support Matrix, or anything else that speaks MCP.

The published Docker image includes linux/amd64 and linux/arm64 variants, so Apple Silicon Macs and ARM64 Linux hosts can pull akitaonrails/ai-memory without --platform linux/amd64 emulation.

The Docker quick-start below has no authentication: the container never runs init, so it starts without a token. The server binds to loopback only, so nothing outside the machine can reach it, but local processes and browser pages can. Native installs that run ai-memory init get a bearer token by default; see Security below for that and for adding a token here.

# 1. Install the ai-memory CLI wrapper (a small shell script that
runs the binary inside a container with your $HOME mounted). This is
the only thing that needs to live on the host filesystem.
mkdir -p ~/.local/bin
wrapper_tmp="$(mktemp -d)"
trap 'rm -rf "$wrapper_tmp"' EXIT
wrapper_base=https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-wrapper
curl -fsSL "$wrapper_base" -o "$wrapper_tmp/ai-memory-wrapper"
curl -fsSL "$wrapper_base.sha256" -o "$wrapper_tmp/ai-memory-wrapper.sha256"
expected="$(awk 'NR == 1 { print $1 }' "$wrapper_tmp/ai-memory-wrapper.sha256")"
if command -v sha256sum >/dev/null 2>&1; then
    actual="$(sha256sum "$wrapper_tmp/ai-memory-wrapper" | awk '{ print $1 }')"
else
    actual="$(shasum -a 256 "$wrapper_tmp/ai-memory-wrapper" | awk '{ print $1 }')"
fi
[ -n "$expected" ] && [ "$actual" = "$expected" ] || { echo "wrapper checksum mismatch" >&2; exit 1; }
install -m 0755 "$wrapper_tmp/ai-memory-wrapper" ~/.local/bin/ai-memory
rm -rf "$wrapper_tmp"
trap - EXIT
Most distros put ~/.local/bin on PATH automatically. If `which
ai-memory` comes up empty, add this to ~/.bashrc / ~/.zshrc:
export PATH="$HOME/.local/bin:$PATH"
2. Start the server. --restart unless-stopped makes it come back
on docker daemon restart and on machine boot (provided your
docker service is enabled at boot — `sudo systemctl enable
docker on most distros). Loopback-only bind (127.0.0.1:49374`)
so nothing outside this machine can reach it. Omit the LLM /
EMBEDDING lines for zero-LLM mode — FTS5 search still works
without any keys.
docker run -d --name ai-memory \
    --restart unless-stopped \
    -p 127.0.0.1:49374:49374 \
    -v ai-memory-data:/data \
    -e AI_MEMORY_LLM_PROVIDER=anthropic \
    -e ANTHROPIC_API_KEY=sk-ant-... \
    -e AI_MEMORY_EMBEDDING_PROVIDER=openai \
    -e OPENAI_API_KEY=sk-... \
    docker.io/akitaonrails/ai-memory:latest
3. Wire your agent CLI in two commands. The wrapper takes care of
mounts and each client's config-path detection. Re-run with
--agent codex, --agent command-code, --agent devin, --agent opencode, --agent opencode2, --agent gemini-cli,
--agent grok, --agent kimi-code, --agent kiro-cli, --agent copilot-cli, --agent droid, --agent muse, --agent cline, --agent qwen-code, --agent qoder, --agent omp,
--agent oh-my-pi, --client cursor,
--client gemini-cli, --client grok, --client kiro-cli,
--client cline, --client freebuff, etc.
for additional agents; full list in docs/install.md.
ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --agent  claude-code --apply

On Linux and macOS, the Docker wrapper runs install-hooks through its checksum-verified native host client. Global options may precede the command, for example ai-memory --config /path/to/config.toml run codex; the native client receives the complete argument list. The installed hooks therefore enforce client-side capture controls such as [capture] ignore_paths and allowlist mode before an event reaches the spool or network. Set AI_MEMORY_HOOK_PLATFORM=posix explicitly only when you need the legacy shell compatibility path; the installer warns that path cannot enforce capture policy v1.

The examples use docker; replace it with podman on a Podman host. The wrapper automatically uses Podman when Docker is not installed. Set AI_MEMORY_DOCKER=podman to force Podman when both engines are available.

That completes the setup on Linux/macOS. Start a Claude Code session as usual: every prompt and tool call now lands in ai-memory, and the next session you open in this project will see a handoff with where you left off. On macOS the native binary is the recommended path when you do not need Docker, either through the menu bar app above or a release tarball / launchd agent. Later updates for that path use ai-memory upgrade (checksum-verified GitHub release replace + hook refresh); see docs/install.md#keeping-ai-memory-up-to-date. The same native upgrade path covers Windows x86_64 zip installs under a writable prefix (see docs/windows.md Scenario C). Upgrading a 2.x install of any kind to 3.0? Read docs/upgrading-to-3.0.md first.

Wiring another agent is the same two commands with a different name: --client codex, --agent codex, and so on for every row of the support matrix. OpenCode is version-detected by host-side commands; when generating its artifacts inside a container, use `setup-agent --agent opencode --opencode-dialect v1|v2 --to /tmp/unused` because the container cannot inspect the host executable. The legacy opencode2, opencode-v2, and open-code2 aliases remain force-V2 compatibility spellings for old scripts; use opencode for new commands. The full per-agent guide, including Windows and remote servers, is docs/install.md.

Two agents in the same project at once, or teammates on one server, work out of the box: the "current project" pointer is isolated per caller by default (v1.39+). See docs/auto-scope.md for the optional session-aware Claude Code bridge and the details.

If in doubt, start your harness with ai-memory run. It is the preferred way to launch: the first time it runs a harness it auto-installs that harness's ai-memory hooks + MCP if they are missing (so capture and recall work without a separate install-hooks/install-mcp step to forget), it wires the right project scope by construction, and it adds cross-harness session continuity on top of shared memory. Everything is idempotent and one-time per harness and config home. If the server is unreachable, run warns and launches anyway with local capture spooling; run ai-memory recover after the server returns (see Degraded offline launches). Pass --require-server to fail closed instead.

ai-memory run claude
ai-memory run codex --yolo   # same workstream + local Claude history dossier
ai-memory run --profile work claude  # reusable config.toml env/account preset
ai-memory continue           # resume the newest managed checkout
after a dead launcher left its lease behind (same operator only)
ai-memory run --force-unlock codex
ai-memory resume             # pick from ALL workstreams in this checkout only
ai-memory resume --search auth # find a workstream by name (case-insensitive)
ai-memory resume --all       # pick across every linked checkout

`--force-u