akitaonrails · Trending

akitaonrails/ai-memory

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

9.3kstars 656forks 100+contributors Rust

README.md

> 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](https://aimemory.sh)**

[![Website](https://img.shields.io/badge/website-aimemory.sh-blue)](https://aimemory.sh)
[![Release](https://img.shields.io/github/v/release/akitaonrails/ai-memory)](https://github.com/akitaonrails/ai-memory/releases/latest)
[![Rust](https://img.shields.io/badge/rust-1.95+-blue)](rust-toolchain.toml)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

## 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 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`](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`](docs/ARCHITECTURE.md).

## 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`](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) | Supported |
| OpenCode V2 compatibility aliases (`opencode2`, `opencode-v2`, `open-code2`) | 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 |
| VS Code Copilot | MCP-only |
| Zed | MCP-only |
| DeepSeek Harness (DSH) | 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](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
(compile-not-retrieve),
[agentmemory](https://github.com/rohitg00/agentmemory) (hook capture for coding
agents), [basic-memory](https://github.com/basicmachines-co/basic-memory)
(markdown-on-disk truth),
[cognee](https://github.com/topoteretes/cognee) (pipeline composition and
triplet embeddings),
[Hermes Agent](https://github.com/NousResearch/hermes-agent) (the
self-improvement loop), and [A-MEM](https://arxiv.org/abs/2502.12110)
(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](docs/comparison.md).

## Quick start

### Linux and macOS (two commands, no root)

```bash
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 and asks first; `--yes` skips the question, and running it again
changes nothing. Restart your agents afterwards. Details, the environment
variables and how to verify the script before running it are in
[`docs/install.md`](docs/install.md#one-step-native-install-installsh--ai-memory-setup).
An AI agent installing ai-memory for you can follow
[`INSTALL_FOR_AGENTS.md`](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):

```bash
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](docs/install.md#marketplace-plugins).

### 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.

```bash
yay -S ai-memory-bin    # prebuilt Linux x86_64/aarch64 binary
yay -S ai-memory        # builds from source
```

### Fedora (RPM)

Download the `x86_64` or `aarch64` RPM from the
[latest release](https://github.com/akitaonrails/ai-memory/releases/latest),
then install it:

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

Then follow the native Linux service instructions in [`docs/install.md`](docs/install.md).

Single-user workstation:

```bash
mkdir -p ~/.config/ai-memory ~/.local/share/ai-memory
ai-memory --data-dir ~/.local/share/ai-memory \
  --config ~/.config/ai-memory/config.toml init
systemctl --user enable --now ai-memory.service
ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply
```

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`](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):

```bash
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
an agent with the bundled binary:

```bash
BIN="/Applications/AI Memory.app/Contents/Resources/runtime/ai-memory"
"$BIN" install-mcp --client claude-code --apply
"$BIN" install-hooks --agent claude-code --apply
```

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

### Docker

You need: Docker or Podman + an agent CLI from the [Support Matrix](#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](#security) below for that and for adding a token here.

```bash
# 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 omp`,
#    `--agent oh-my-pi`, `--client cursor`,
#    `--client gemini-cli`, `--client grok`, `--client kiro-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
```

On Linux and macOS, the Docker wrapper runs `install-hooks` through its
checksum-verified native host client. 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](#macos-menu-bar-app) above or a
[release tarball / launchd agent](docs/macos.md). 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`](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`](docs/windows.md) Scenario C).
Upgrading a 2.x install of any kind to 3.0? Read
[`docs/upgrading-to-3.0.md`](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 `opencode2` aliases remain force-V2 compatibility
spellings. The full per-agent guide, including Windows and remote servers, is
[`docs/install.md`](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`](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](docs/managed-workstreams.md#degraded-offline-launches)).
Pass `--require-server` to fail closed instead.

```bash
ai-memory run claude
ai-memory run codex --yolo   # later: same workstream, different harness
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-unlock` immediately expires the selected workstream's active lease;
use it only when you know the previous launcher is gone. It does not kill a
native process, and it cannot evict another authenticated operator's run. See
the [managed-workstream recovery notes](docs/managed-workstreams.md#lease-recovery)
for the full safety contract.

In `resume`, type to search, use Up/Down to select a workstream, and Left/Right
to choose its harness. Enter launches the selection; Escape clears a search,
then cancels when the search is empty (Ctrl-C always cancels).
The list scrolls and loads every checkout-local page;
there is no default workstream cutoff. Use `--limit N` only when you want to
cap the matching results. Workstreams from other repositories or worktrees
are left out unless you pass `--all`, which lists every linked checkout (the
current one first); `continue` still resumes the newest linked checkout from
anywhere. Listing reads Git identity only; it does not scan the working tree
with `git status` before showing the picker. Full checkpoints are still captured
when launching the selected workstream.

Auto-wiring is on by default; opt out with `ai-memory run --no-autowire` or
`AI_MEMORY_RUN_AUTOWIRE=false`. You can still wire agents by hand with
`install-hooks` / `install-mcp` (e.g. for a harness you never launch through
`ai-memory run`).

`ai-memory uninstall --apply` removes everything ai-memory installed,
and only what it installed. It also clears `ai-memory run`'s auto-wire
record, so the next managed launch wires that harness again; to keep it
unwired, launch with `--no-autowire` or set `AI_MEMORY_RUN_AUTOWIRE=false`. Install commands are idempotent and write
timestamped backups next to any file they touch.

### NixOS

This flake ships a NixOS module (`nixosModules.default`) with a
`systemd.services.ai-memory` unit: a dedicated `ai-memory` system user
(`nologin`, no linger) plus a hardened systemd sandbox
(`ProtectSystem = "strict"`, empty capability sets,
`MemoryDenyWriteExecute`, `RestrictAddressFamilies`, and the rest; see
[`nix/systemd-sandbox.nix`](nix/systemd-sandbox.nix)). Packaged FHS units
under `packaging/systemd/` keep their existing lighter hardening.
The flake exports packages for `x86_64-linux`, `aarch64-linux`, and
`aarch64-darwin`. Intel macOS remains supported by the release tarball and
Homebrew, but not by the pinned Nixpkgs revision.

```nix
{
  inputs.ai-memory.url = "github:akitaonrails/ai-memory";

outputs = { nixpkgs, ai-memory, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ai-memory.nixosModules.default
        {
          services.ai-memory = {
            enable = true;
            # enableWeb = true;  # off by default — the web UI is opt-in
            # enableApi = true;  # API-only companions; no browser UI
            settings = {
              allowed_hosts = [ "localhost" "127.0.0.1" "::1" "homelab.example" ];
              log_level = "info";
            };
            # Loopback (default): secrets optional; missing env file is tolerated.
            # Non-loopback: set one of ageSecret, sopsSecret, or environmentFile.
            # ageSecret = "ai-memory-env";  # config.age.secrets.<name> (agenix)
            # sopsSecret = "ai-memory/env"; # config.sops.secrets.<name> (sops-nix)
          };
        }
      ];
    };
  };
}
```

Declarative non-secret config lives in `services.ai-memory.settings` (a
small typed set for common keys, plus `freeformType` for the rest of
`config.toml`). The module renders a generated TOML file and passes
`--config`. Top-level `bind`, `port`, and `enableWeb` win over duplicate
settings keys. Anything in `settings` (including `llm_headers`) lands in a
world-readable Nix store path, so do not put API keys there.

Secrets such as `AI_MEMORY_AUTH_TOKEN` never go in `settings` or the
world-readable Nix store. This includes `llm_headers`, which can carry API
credentials; set `AI_MEMORY_LLM_HEADERS` in `ageSecret`, `sopsSecret`, or
`environmentFile` instead. These three secret sources are mutually exclusive.
Non-loopback binds require one; loopback may omit them and tolerates a missing
environment file (systemd `EnvironmentFile=-…`). Put TLS in front of a LAN/WAN
bind; see [`docs/https-via-proxy.md`](docs/https-via-proxy.md).

All options and defaults are in [`nix/nixos-module.nix`](nix/nixos-module.nix).
The module is entirely opt-in: `nix build`, `nix run`, `nix develop`, and the CLI are
unchanged if you don't import it.

## Everyday use

Day to day, you mostly do not think about ai-memory. Hooks capture
prompts, tool calls, and session boundaries; session end turns them into
readable wiki pages; the next session starts with a handoff.

- Ask "where did we leave off?" to continue from the pending handoff.
- Ask "have we discussed X?" or "search memory for Y" to query the wiki.
- Ask "catch me up" for a prose digest of recent project activity.
- Run `ai-memory bootstrap` once when adopting an existing project with
  months of history.
- Start the server with `--enable-web` for a read-only browser view of
  the wiki and a JSON API under `/api/v1`. On a server with a bearer token
  and no user accounts (every fresh install), the browser asks for a username
  and password: any username, and the contents of
  `<data_dir>/auth-tokens/default` as the password.
- Back up host-side harness configuration with
  `ai-memory backup-agents -o agent-assets.tar.gz`; inspect a restore with
  `ai-memory restore-agents -i agent-assets.tar.gz`, then add `--apply` only
  after reviewing the active skills, plugins, instructions, and destinations.

Search modes, entities, feedback, briefings, and the web API are covered in [`docs/usage.md`](docs/usage.md) and
[`docs/use-cases.md`](docs/use-cases.md).

## Teams and multiple machines

Run the server somewhere reachable, such as a homelab box or a LAN host, and
point every machine and every teammate at it. Knowledge is shared per
project; personal handoffs stay personal; every write is attributed and
audited. Multi-user auth (passwords, API credentials) is built in.

Start with [`docs/users.md`](docs/users.md) for accounts and ownership,
and [`docs/deploy.md`](docs/deploy.md) for the server itself. It includes
measured capacity numbers and the one rule you must follow: one server per
data directory, never two.

## Security

The server binds to loopback only by default. A fresh `ai-memory init` also
mints a root bearer token into the data dir, which the hooks, the CLI and the
`ai-memory mcp-bridge` stdio bridge read from there; it is never written into
a harness config. An install created before that default (and the Docker
quick-start) runs without auth until `ai-memory auth enable`, and
`ai-memory status` says so. From there, hardening is incremental: a bearer
token for the LAN, per-user accounts, OIDC device auth for hooks, TLS via
a reverse proxy. Capture is sanitized at a typed privacy boundary before
anything is stored, and per-repository `[capture]` rules can exclude
paths or invert to allowlist mode. A repository can also route its capture
to a different server than the one the hooks were installed against.

The full model is in [`docs/security.md`](docs/security.md),
[`docs/users.md`](docs/users.md), and
[`docs/https-via-proxy.md`](docs/https-via-proxy.md). For data-flow,
identity/SSO, and offline-install questions specifically, see
[`DATA_HANDLING.md`](DATA_HANDLING.md), [`docs/sso.md`](docs/sso.md), and
[`docs/airgapped-install.md`](docs/airgapped-install.md).

## LLM providers

Optional. Everything works with zero LLM calls; adding a provider
upgrades session summaries and enables semantic search. Anthropic,
OpenAI (including OAuth), Codex CLI credential reuse, GitHub Copilot, Gemini,
OpenCode (Go and Zen), the Cursor Agent CLI (`cursor`), and
any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM) are supported
for consolidation; OpenAI, Voyage, Gemini, and keyless OpenAI-compatible
endpoints for embeddings. Configuration lives in
[`docs/llm-providers.md`](docs/llm-providers.md).

## Architecture

One Rust binary runs an MCP/HTTP server and owns one data directory:

```text
<data_dir>/
├── wiki/    # markdown source of truth, git-versioned
├── raw/     # immutable sanitized managed-workstream transcript segments
├── db/      # SQLite indexes, including FTS5, entities, and embeddings
├── models/  # reserved for local embedding models
└── logs/    # rolling tracing output
```

Hooks POST observations to the server. The server 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, an observation-evidence stream that lifts a session's
page when its captured turns match (on by default), bounded source-authority
adjustment, and bounded raw-observation fallback for non-global searches.

See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the data-flow
diagram, crate breakdown, schema notes, and invariants.

## Docs

### For users

| File | What it is |
|---|---|
| [`docs/cookbook.md`](docs/cookbook.md) | **Task-oriented cheat sheet.** "I want to do X" → how: recall prior work, keep a project rule, import an existing knowledge base, get two agents/repos working together. Start here. |
| [`docs/install.md`](docs/install.md) | **Installation cookbook.** Every agent CLI, every alternative (curl, source build, no-docker, no-auth), and the server-on-a-different-machine walkthrough. |
| [`docs/usage.md`](docs/usage.md) | Handoffs, proactive memory queries, slim routing snippet + managed Agent Skills, web UI, raw-wiki inspection, and the rules, memory and profile precedence. |
| [`docs/cross-project-profile.md`](docs/cross-project-profile.md) | **The cross-project profile.** Your usual choices delivered to every project as defaults: defaults per deployment, every setting, per-project opt-outs, multi-user opt-in and privacy, CLI. |
| [`docs/managed-workstreams.md`](docs/managed-workstreams.md) | Optional `ai-memory run` continuity across harnesses: auto harness selection, native resume, argument forwarding, ledger search, privacy, and recovery. |
| [`docs/agent-messaging.md`](docs/agent-messaging.md) | Cross-project agent-to-agent messaging: a directed, claim-once inbox/queue plus the on-start "you have mail" notice. |
| [`docs/marker-file.md`](docs/marker-file.md) | Default repository-path project naming plus `.ai-memory.toml` workspace/project routing for multi-client trees, mono-repos, worktrees, and work/personal separation, plus per-repository server profiles. |
| [`docs/auto-scope.md`](docs/auto-scope.md) | `[auto_scope]` modes for shared servers: the default `per_actor` isolation, session-aware `per_session` isolation, and the pre-v1.39 `single` slot. |
| [`docs/macos.md`](docs/macos.md) | macOS install paths: menu bar app, native release tarball, source build, Docker wrapper, launchd, and current limitations. |
| [`docs/windows.md`](docs/windows.md) | Windows install modes: full WSL2, native Windows with Docker Desktop, prebuilt native release zip, native source builds, and caveats. |
| [`docs/mcp-install.md`](docs/mcp-install.md) | Per-client MCP and lifecycle notes, handoff-injection limits, and community bridge guidance. |
| [`docs/programmatic-memory.md`](docs/programmatic-memory.md) | Use ai-memory from any tool: MCP write/query/handoff calls, scope rules and incremental reads. |
| [`docs/deploy.md`](docs/deploy.md) | Homelab deploy: bin/deploy, bearer-token auth, pointers to the TLS guide. |
| [`docs/users.md`](docs/users.md) | **Multi-user attribution and human login.** Four-rung bearer ladder, password sessions, `ai-memory user` / `api-key` walkthrough, brownfield migration. |
| [`docs/https-via-proxy.md`](docs/https-via-proxy.md) | **HTTPS via a reverse proxy.** When you need TLS and when you don't, with copy-paste Caddy / nginx / Cloudflare Tunnel templates and the "secure when you're not" failure modes. |
| [`docs/lifecycle-ops.md`](docs/lifecycle-ops.md) | **Read before purge / rename / backup / restore / reset / reindex / restore-page.** Safety matrix, per-project disk layout, checkpoint page recovery, and operator workflows. |
| [`docs/backup.md`](docs/backup.md) | Backing up the wiki + data dir to a remote git repository: what to include, what to exclude, scheduled push pattern, restore, and security posture. Companion to `docs/lifecycle-ops.md` (which covers the on-box `ai-memory backup` snapshot). |
| [`docs/design-backup-agent-assets.md`](docs/design-backup-agent-assets.md) | Host agent-asset backup/restore: supported paths, filtering, redaction limits, archive bounds, active-content warning, and rollback behavior. |
| [`docs/llm-providers.md`](docs/llm-providers.md) | Provider configuration for consolidation and embeddings. |
| [`docs/security.md`](docs/security.md) | The full security model. |
| [`docs/support-matrix.md`](docs/support-matrix.md) | The full agent/platform matrix with notes. |
| [`docs/use-cases.md`](docs/use-cases.md) | Scenario walkthroughs. |
| [`DATA_HANDLING.md`](DATA_HANDLING.md) | **Data-flow reference for security/legal review.** What's stored, what's local-only, the two opt-in external paths, and how deletion/retention work. |
| [`docs/sso.md`](docs/sso.md) | Enterprise identity: the OIDC device-auth flow, its scope, and how to front the server with an OIDC-aware gateway. |
| [`docs/airgapped-install.md`](docs/airgapped-install.md) | Offline/air-gapped install: self-contained build, checksum-verified release binaries, and offline local embedding models. |
| [`docs/upgrading-to-3.0.md`](docs/upgrading-to-3.0.md) | Upgrading a 2.x install to 3.0: what changed, the removed token commands and their replacements, upgrade steps, and rollback. |
| [`docs/MIGRATION-2.0.md`](docs/MIGRATION-2.0.md) | Upgrading an existing store to 2.0: the backup-gated automatic migration and how to restore. |
| [`docs/benchmarks/`](docs/benchmarks/README.md) | Published retrieval-quality numbers with provenance, reproducible from the in-repo harness. |
| [`docs/okf.md`](docs/okf.md) | The wiki is natively an Open Knowledge Format (OKF v0.2) bundle; design and field mapping. |

### For contributors

| File | What it is |
|---|---|
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Operational summary: data flow, crate layout, cross-cutting invariants, schema. |
| [`docs/design-decisions.md`](docs/design-decisions.md) | The full v1 spec. |
| [`docs/managed-harness-contributions.md`](docs/managed-harness-contributions.md) | Protocol and acceptance bar for adding managed resume, transcript import, and startup context delivery to another harness. |
| [`docs/companion-crates.md`](docs/companion-crates.md) | Optional companion projects: the [importer](companions/ai-memory-importer), [external lifecycle relay](companions/ai-memory-relay), [team-wiki sync](companions/ai-memory-wikisync) and the [TypeScript client SDK](companions/ai-memory-ts). |
| [`docs/external-lifecycle.md`](docs/external-lifecycle.md) | External lifecycle producers: per-execution native capture suppression, preserved handoffs, batch ingestion and stable retry identity. |
| [`docs/auto-improvement-loop.md`](docs/auto-improvement-loop.md) | Auto-improvement design notes: scheduled review, auto-approval default, manual review opt-in, pending proposal storage, and curator work. |

### Community articles

Written by users; not maintained here, so check them against the version you run.

- [Installing and configuring ai-memory on Linux](https://www.linuxpro.com.br/2026/09/ai-memory-instalar-configurar-agentes-linux/) (pt-BR, LinuxPro, covers v2.6.3)
- [ai-memory from v2.4 to v2.6.3](https://www.linuxpro.com.br/2026/10/ai-memory-a-evolucao-da-2-4-a-2-6-3/) (pt-BR, LinuxPro)

## License

MIT. See [LICENSE](LICENSE).

## Acknowledgements

This codebase is being built collaboratively with Claude Code
(Anthropic Claude Opus 4.7) following the plan documented in
`docs/design-decisions.md`.

Repository info

Default branch: main
Latest version: v3.0.0
Created: 2026-05-22
Last activity: 2026-10-14
License: MIT
Open issues: 22
Watchers: 50

Contributors

akitaonrails

2.4k contributions

djalmajr

126 contributions

viniciusdsandrade

104 contributions

everton-dgn

95 contributions

samirhvbr

52 contributions