ai-memory: Long-Term Memory Solution for AI Coding Agents

Introduction

ai-memory is a powerful, Rust-based open-source project designed to provide long-term memory for AI coding agents. It addresses the common challenge of fragmented agent memory, where knowledge is often confined to a single tool or machine. With ai-memory, your AI agents can maintain a persistent, shared understanding of project context, past attempts, and open questions, enabling seamless transitions between different agent vendors and development environments.

For more details, visit the official GitHub repository: akitaonrails/ai-memory

Why use and benefits

ai-memory offers several compelling advantages for developers working with AI coding agents:

Cross-Agent Continuity: It supports over twenty agent harnesses, allowing you to switch between tools like Claude Code, OpenAI Codex, Cursor, and others without losing context. Handoffs become a structured protocol, ensuring the next agent picks up exactly where the previous one left off.
Cross-Machine Persistence: Your project's memory resides on a server you control, whether it's your local machine or a homelab. This means you can resume work on any device, accessing the same knowledge and open questions.
Team Collaboration: Point multiple team members to a single ai-memory server, and the collective knowledge gained by one person's agents becomes accessible to everyone. It supports multi-user authentication, per-person attribution, and an audit log.
Plain Markdown Memory: The core of your memory is a git-backed wiki of ordinary Markdown files. This allows for easy inspection, editing, searching with tools like grep, and ensures data is never held hostage in proprietary formats. The database is a derived index, rebuildable from these files.
Silent Work Capture: Lifecycle hooks automatically record prompts, tool calls, and session boundaries. This data is sanitized for privacy before storage and consolidated into readable pages, eliminating the need for manual "remember this" commands. By default, it operates with zero LLM calls for capture, search, and handoffs.
Transparent and Reliable: ai-memory is a self-contained Rust binary, offering clear purge commands, a measured write ceiling, and an audit log of every mutation, providing the reliability expected from infrastructure tools.

Installation

Getting started with ai-memory is straightforward, with Docker being a highly recommended method for quick setup.

Docker Quick Start

1. Install the ai-memory CLI wrapper: This small shell script runs the binary inside a container, mounting your $HOME directory.

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
# Add ~/.local/bin to your PATH if not already present.

2. Start the ai-memory server: This command runs the server in a Docker container. You can optionally configure LLM and embedding providers.

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: Connect your preferred agent, for example, Claude Code.

ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --agent  claude-code --apply

For other installation methods, including Arch Linux AUR, native macOS, Windows via WSL2, and more detailed configurations, please refer to the official installation documentation.

Examples

Once installed and configured, ai-memory integrates seamlessly into your daily workflow:

Continue tasks: Ask your agent "where did we leave off?" to get a summary of the pending handoff.
Query memory: Use prompts like "have we discussed X?" or "search memory for Y" to retrieve information from the project wiki.
Catch up: Request "catch me up" for a prose digest of recent project activity.
Managed Workstreams: Utilize ai-memory run <agent> to manage session continuity across different harnesses, allowing you to seamlessly switch between agents while working on the same task.