home›AI Coding›

How to Give AI Coding Agents Persistent Memory and Context

Discover AI-Memory: A shared, persistent wiki for AI coding agents that captures context, enables seamless handoffs, and eliminates re-explanation.

May 26, 2026

#Agents #Automation #Dev Tools #MCP #Memory

Learn how AI-Memory solves the context loss problem for AI coding agents. This tool provides a persistent, Git-versioned Markdown wiki, enabling cross-agent handoffs, automatic context capture, and project isolation for a truly continuous AI-assisted development workflow.

Persistent Memory for AI Coding Agents

AI coding agents lose all context when a session ends. AI-Memory solves this by giving agents a shared, persistent wiki stored as plain Markdown in a Git repository. Lifecycle hooks automatically capture every prompt, tool call, and decision. At session end, relevant observations are compiled into coherent narrative pages. When the next agent starts, a handoff block shows open questions, failed approaches, and next steps. You can quit Claude Code mid-task, open Codex hours later in the same directory, and continue without re-explaining the architecture.

Key Features

Zero-friction capture – Hooks fire on every prompt, tool call, and session boundary; no manual note-taking.
Cross-agent handoffs – Switch between any supported agent; the next session sees a typed handoff.
Per-project isolation – Pages stored under <wiki_root>/<workspace_id>/<project_id>/… keyed by stable UUIDs; override with .ai-memory.toml for mono-repos, work/personal splits, and git worktrees.
LLM-compiled wiki – Observations consolidated at session-end (or pre-compact) into Git-versioned Markdown, not raw logs.
Built-in /web UI – Read-only browser with project list, folder tree, FTS5 search, rendered Markdown, and dark mode.
Multi-agent + multi-machine ready – Supports Claude Code, Codex, OpenCode, Cursor, Gemini CLI, Antigravity CLI, OpenClaw, Oh My Pi/OMP. Server runs local or on a homelab with bearer-token auth.
Thin-client CLI – Commands like bootstrap, purge-project, rename-project, lint, embed, forget-sweep, backup are HTTP clients; they never touch SQLite or wiki files directly.
LLM is opt-in – Zero-LLM mode gives FTS5 search and rule-based summarisation; add a provider for consolidated pages and contradiction linting.

Support Matrix

Area	Status	Notes
Linux	Supported	Primary Docker/server target and CI platform.
macOS	Supported	Workspace tests run in CI; native source builds supported.
Windows via WSL2	Supported	Use the Linux install path inside WSL2.
Native Windows	Experimental	PowerShell wrapper and `.ps1` hooks exist; real agent feedback still needed.
Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Oh My Pi/OMP, OpenClaw, Antigravity CLI	Supported	MCP config + lifecycle hooks.
Claude Desktop	MCP-only	Uses `mcp-remote`; no lifecycle hooks.
LLM providers	Anthropic, OpenAI, Gemini, OpenAI-compatible endpoints
Embedding providers	OpenAI, Voyage, Google Gemini

# 1.
Install the ai-memory CLI wrapper (a ~3 KB shell script that
#    runs the binary inside docker with your $HOME mounted).
This is
#    the only thing that needs to live on the host filesystem.
mkdir -p ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/akitaonrails/ai-memory/main/bin/ai-memory \
    -o ~/.local/bin/ai-memory
chmod +x ~/.local/bin/ai-memory
# 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-... \
    akitaonrails/ai-memory:latest

# 3.
Wire your agent CLI in two commands.
The wrapper takes care of
#    mounts + auto-detecting ~/.claude/settings.json.
Re-run with
#    `--agent codex`, `--agent opencode`, `--agent gemini-cli`,
#    `--agent omp`/`pi`, `--client cursor`, `--client gemini-cli`, 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

Install Notes

Windows: Use the Linux path inside WSL2, or the native PowerShell wrapper and .ps1 hooks for native Windows agents. Do not mix path environments.
Docker compose: docker compose -f docker/docker-compose.yml up -d is supported; agent setup is the same as step 3.
Remote server: Set AI_MEMORY_SERVER_URL=http://<server-ip>:49374 on the client and pass matching --server-url flags when installing MCP/hooks. Any non-loopback server should use bearer auth.
Upgrades: Run ai-memory upgrade to refresh the wrapper, image, and staged hook scripts. Redeploy remote servers separately.

Daily Usage

Day to day you mostly don’t think about ai-memory. Lifecycle hooks capture everything silently. SessionStart hooks fetch pending handoffs before your first prompt in the next agent.

GitHub