Skip to content
Get packs

Guide · Open source

How to use ai-memory: setup, agents and handoffs

Updated · written with AI from the project's own documentation and checked against our catalogue data

ai-memory is an open-source tool that keeps notes about your coding projects so AI coding agents can continue work another agent started. It runs as a server you host yourself, and agent tools such as Claude Code or Codex send it session activity through hooks. This guide explains what it does, what you need to install it, and how to get the most from handoffs between agents.

ai-memoryakitaonrails/ai-memory · ★ 14.9k · MIT

Quick start

  1. 1Check prerequisites. If you build from source, make sure you have Rust 1.95 or newer, as the README badge states.
  2. 2Clone the repository. Run git clone https://github.com/akitaonrails/ai-memory to get the source.
  3. 3Confirm your agent is supported. Look up your agent in docs/support-matrix.md and note whether it is hooks, MCP, or both.
  4. 4Run the server you host. ai-memory is self-hosted. Start the server on the machine that will hold your memory, following the repository docs.
  5. 5Register your agent. Set up the MCP registration or lifecycle hooks listed for your agent in the support matrix.
  6. 6Work and hand off. Work in an agent as usual. To continue in another agent, quit it and run ai-memory run followed by the new harness name, such as codex.

What ai-memory does and who it suits

ai-memory stores project memory as a git-backed wiki of ordinary markdown files. Lifecycle hooks record what happens during a session, such as prompts, tool calls and session boundaries, and the server turns that activity into readable pages. The next session, in any supported agent, can search that memory and receive a short brief.

It fits developers who switch between several coding agents in one project, people who want agent memory as files they can read and edit, small teams sharing one self-hosted server, and developers working on more than one machine. It is not a hosted service: the README describes running the server yourself.

  • Works across more than twenty agent harnesses listed in the support matrix
  • Memory is plain .md files; the database is an index that can be rebuilt from them
  • The default path makes zero LLM calls, so capture, search and handoffs need no API key

Install ai-memory from source

The README's install instruction is to clone the repository. If you build from source, the README badge lists Rust 1.95 or newer as the requirement. The README excerpt provided here does not include build or run commands beyond this, so check the repository's documentation for the rest of the build steps.

The project is MIT licensed and written in Rust. The README says it ships as one self-contained binary.

  • Prerequisite for building from source: Rust 1.95+
  • Linux and macOS are listed as supported; Windows is supported through WSL2, and native Windows is experimental
git clone https://github.com/akitaonrails/ai-memory

Connect your coding agent

Each agent needs its own integration, which is either MCP registration, lifecycle hooks, or both. The support matrix in the README lists the status of each tool, and the full per-agent notes are in docs/support-matrix.md. Check that your agent appears there before you rely on it.

Some agents are listed as MCP-only, which means they can query memory but do not feed session activity through hooks. Others are listed as hooks-only or hooks plus MCP. Read the status column before you assume full capture.

  • Claude Code and Codex are listed as Supported
  • Cursor, Gemini CLI, OpenCode and Kiro CLI are also listed as Supported
  • Claude Desktop, VS Code Copilot and Zed are listed as MCP-only

Hand off work between agents

The main workflow is switching agents mid-task. Quit one agent, then start another in the same directory. The README gives the example of quitting Claude Code and running ai-memory run codex. Codex receives the shared workstream and a bounded startup packet, and it can search the full memory.

Handoffs are a typed protocol: each one has an owner and is claimed exactly once. The README also says the remote server receives only the harness and session identity, never the local transcript path or body.

  • Direct harness launches behave as before; ai-memory run is the wrapper for handoffs
  • Memory is shared per project; personal handoffs stay personal
ai-memory run codex

Search, aging and privacy controls

Search combines full-text, entity, link and, optionally, vector results into one ranking. Memory you open, search or reach through a link decays more slowly. Compaction, deduplication and per-tier decay curves are off by default and must be turned on by you. Nothing is hard-deleted; the original stays in git and restore-page can bring a page back.

The README also describes a management console for user administration, session inspection and personal MCP API keys. It is optional and needs both a build feature and a runtime flag.

  • Turn on compaction or dedup only after you understand that they rewrite or drop content
  • Use the management console only if you need it; build with --features management-ui and start serve --transport http --enable-management-ui

What people use it for

  • Start a refactor in Claude Code, then continue in Codex in the same directory without re-explaining the design.
  • Keep a readable record of failed approaches and open questions in markdown files you can grep or edit in Obsidian.
  • Resume a project on a laptop after working on it at a desktop, using one self-hosted server.
  • Share project knowledge with a small team through one server, while keeping personal handoffs private.

Frequently asked questions

Is ai-memory free to use?

ai-memory is released under the MIT licence, as stated in the README. The README does not describe any paid tier and says multi-user auth, attribution and audit logging are built in and are not a paid tier.

Does ai-memory need an API key or LLM?

No. The README says the default path makes zero LLM calls, and capture, search and handoffs all work with no API key. Optional LLM features such as the dream pass are off by default and require configuring an LLM.

Which AI coding agents does ai-memory support?

The README lists more than twenty harnesses in its support matrix, including Claude Code, Codex, Cursor, Gemini CLI and OpenCode. Each is marked as hooks, MCP, or both, so check the matrix for your tool.

What are the system requirements for ai-memory?

The README badge lists Rust 1.95 or newer if you build from source. Linux and macOS are listed as supported, Windows through WSL2 is supported, and native Windows is experimental.

Is ai-memory a hosted service?

No. The README describes it as a server you run yourself, on a laptop, a homelab box or elsewhere. It is not presented as a hosted service with no server to run.

How does ai-memory compare to Mem0 or Zep?

The README says ai-memory is built around a git-backed markdown wiki as the source of truth, with a derived index, and works with zero LLM calls by default. It compares itself to Mem0, Zep, Graphiti and mcp-memory-service in a table of what carries over from each tool.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

ai-memory suits developers and small teams who use several coding agents on self-hosted infrastructure and want memory stored as readable markdown. If you want a hosted service with no server to run, or your agent is not on the support matrix, pick another option such as Mem0 or Zep.

Install options & downloads