--project ` returns a read-only
telemetry report for recent auto-improvement outcomes without staging or
creating proposals; add `--stage` to create one pending report page for
audit/approval. On deployments that distinguish operators, pending learning
proposals are isolated by qualified operator identity, so one person's
proposal for a page does not block another's; unattributed and single-user
deployments retain the shared pending queue. See
[`docs/auto-improve-eval-gates.md`](docs/auto-improve-eval-gates.md) for
example executable eval scorers.
Existing installs do not need per-project migration. The scheduler initializes
a per-project first-run watermark so historical sessions are not reviewed
automatically on upgrade, then records per-session claims so failed scheduled
reviews do not retry forever; use manual auto-improve for old sessions or
failed scheduled sessions you want to catch up. Older configs may still contain
an `[auto_improve] mode = ...` line; current ai-memory ignores that legacy key,
so you can remove it when convenient.
- **"What housekeeping should I consider?"**
`ai-memory curator` runs a no-LLM, rule-based maintenance report over cold
episodic pages, stale slots, duplicate exact normalized titles, and dangling
cross-project links. It is report-only unless `--stage` is passed; staging
queues one report page for approval and still performs no maintenance actions
itself. Shared servers can opt into `[decay] breadth_weight` to give pages
reinforced by several identified operators a retention bonus; the default
`0.0` leaves existing retention scores unchanged.
- **"Run one ai-memory for the whole household."** Stand the server
up on a homelab box at `0.0.0.0:49374` with a bearer token; every
laptop/desktop talks to it. Per-cwd routing keeps each project's
pages cleanly separated; the `/web` UI is reachable from a
browser anywhere on the LAN.
- **"Audit what landed before sharing with a teammate."** Browse
the wiki at `http://:49374/web` - HTTP Basic dialog if
auth is on, paste the token as password. Per-project tree view,
rendered markdown, supersession chain visible per page.
- **"Undo one bad page edit without rolling back the whole server."**
`ai-memory checkpoints` shows recent wiki commits, then
`ai-memory restore-page --path notes/foo.md --from ` restores that one
markdown file and reindexes it into SQLite. Full `backup` / `restore` is
still the answer for DB-only state such as sessions, observations, handoffs,
users, audit rows, and embeddings.
- **"Drop an experiment, keep the rest."**
`ai-memory purge-project --project experimental --confirm`.
Atomic: that project's DB rows cascade away, its wiki subdir gets
`rm -rf`'d, every sibling project is untouched by construction.
## Quick start
### 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
```
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).
### Docker
You need: Docker + 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 default quick-start has **no authentication** - the server binds
to loopback only, so on a single-user laptop nothing else can reach
it. Adding a bearer token is a one-line change once you're ready to
expose the server on the LAN; see [Security](#security) below.
```bash
# 1. Install the ai-memory CLI wrapper (a small 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
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-... \
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 devin`, `--agent opencode`, `--agent gemini-cli`,
# `--agent grok`, `--agent kimi-code`, `--agent kiro-cli`, `--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
# Grok Build CLI example:
# ai-memory install-mcp --client grok --apply
# ai-memory install-hooks --agent grok --apply
# Kiro CLI v2 example (requires an existing Kiro agent config):
# ai-memory install-mcp --client kiro-cli --apply
# ai-memory install-hooks --agent kiro-cli --apply
# Kiro CLI v3 hook capture is not yet supported; see docs/install.md.
```
On Linux/macOS, that's it. 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 release binary is also supported and recommended when you
do not need Docker; see [`docs/macos.md`](docs/macos.md).
If two Claude Code sessions use the same server concurrently, enable
per-session routing on the server and replace only the `ai-memory` MCP entry
with the optional bridge:
```toml
# /config.toml
[auto_scope]
mode = "per_session"
```
```bash
ai-memory install-mcp --client claude-code --session-aware --apply
```
The bridge still connects to the configured local or remote HTTP server and
forwards its bearer token, but also attaches Claude's lifecycle session id to
every MCP request. Existing static HTTP installs remain the default. See
[`docs/auto-scope.md`](docs/auto-scope.md) for Claude's `/clear` and
implicit-resume limitations.
The `install-mcp` / `install-hooks` commands use
`AI_MEMORY_SERVER_URL` / `AI_MEMORY_AUTH_TOKEN` when set; otherwise
they default to `http://127.0.0.1:49374` (matching the server above)
and no bearer token. If hooks are installed after an ai-memory MCP
entry already exists, `install-hooks` reuses that endpoint so a remote
MCP setup cannot silently regenerate loopback-only hooks. Both commands
are idempotent - re-runs replace ai-memory's entry, preserve every
other server / hook you have configured, and write a timestamped
`.bak-` next to the file before each modifying write. The hook
scripts are staged into `~/.local/share/ai-memory/hooks//`
automatically; re-running overwrites them so future image updates ship
updated hooks. Drop `--apply` to print the snippet instead of mutating.
For Claude Code, `CLAUDE_CONFIG_DIR` relocates MCP registration to
`$CLAUDE_CONFIG_DIR/.claude.json`, hooks to
`$CLAUDE_CONFIG_DIR/settings.json`, and global managed skills to
`$CLAUDE_CONFIG_DIR/skills`. The Docker wrapper forwards this variable when
the directory is under its existing `$HOME` bind mount. Use the native binary
when the Claude config root is outside `$HOME`. Uninstall checks both the
active relocated paths and Claude's home defaults, so enabling the variable
does not leave an older default-path ai-memory installation behind.
If your agent often starts inside repository subdirectories or linked
worktrees, add `--project-strategy repo-root` to `install-hooks` so captures
collapse to the main git repo name; see [`docs/install.md`](docs/install.md)
and [`docs/marker-file.md`](docs/marker-file.md) for details. Later bare
`--apply` refreshes, including `ai-memory upgrade`, preserve that choice;
pass `--project-strategy basename` explicitly to remove it.
The Docker wrapper also bridges thin-client commands such as
`ai-memory status` and `ai-memory bootstrap` back to the host's
loopback server. With the local Docker quick start above, no
`AI_MEMORY_SERVER_URL` override is needed.
Managed workstreams are optional. They execute the harness on the host while
the server may remain local or remote:
```bash
ai-memory run claude
# later, continue the same workstream in another harness
ai-memory run codex --yolo
# omit the name to continue the newest usable local harness session
ai-memory run
# or resume the newest managed checkout without changing directories first
ai-memory continue
```
To remove ai-memory later, run `ai-memory uninstall --apply` from the
same host environment. It removes ai-memory-owned config entries, instruction
blocks, default-root managed skill files, and generated plugin files only after
matching their ai-memory signatures; custom skill roots installed with
`--target-dir` are cleaned up manually. Use `--mcp-url` if you installed MCP
with a custom endpoint, and `--mcp-name` only when you need to narrow removal to
one matching entry.
### Install Notes
- **SELinux:** on enforcing Linux hosts, the Docker wrapper automatically adds
`--security-opt label=disable` only to short-lived helper commands that write
bind-mounted host files. It does not alter the long-lived server container
or relabel `$HOME`; do not add `:z`/`:Z` to the whole home bind. See
[`docs/install.md`](docs/install.md#selinux-enforcing-hosts).
- **Windows:** use the Linux path inside WSL2, or the native Windows wrapper
from PowerShell/cmd. Local supported profiles default to host-native commands:
Claude Code may use its supported `ai-memory.exe` exec form, while other
agents use native single command strings matching their hook schema. The
Docker wrapper protects `.ps1` fallback commands from nested PowerShell
expansion with `-EncodedCommand`; rerun
`install-hooks --agent --apply` after upgrading so existing hook
entries receive the current form.
PowerShell/Git Bash script bundles are compatibility fallbacks and do not
enforce capture-policy v1. Do not mix path worlds. See
[`docs/windows.md`](docs/windows.md).
- **Docker compose:** `docker compose -f docker/docker-compose.yml up -d`
is supported; agent setup is the same as step 3 above.
- **Remote server:** set `AI_MEMORY_SERVER_URL=http://:49374`
and `AI_MEMORY_AUTH_TOKEN=` on the client before installing
MCP/hooks. Explicit `--server-url` flags still work, but are no longer
required when the env vars are set. Any non-loopback server should use
bearer auth.
- **Managed-launch wrapper:** `ai-memory run`, `ai-memory show`, and
`ai-memory continue` must be intercepted by the current host wrapper so local
checkouts, native harnesses, and session stores remain accessible. An old
wrapper may pass these commands into Docker and fail to find a checkout or
host executable. Run
`ai-memory upgrade` on the agent machine to refresh it. The host-native runner
inherits `AI_MEMORY_SERVER_URL`, `AI_MEMORY_AUTH_TOKEN`, and the host `PATH`.
- **Upgrades:** for Docker-wrapper installs, run `ai-memory upgrade` on each
agent machine. It refreshes the local wrapper, pulls the latest image, and
re-stages hook scripts under `~/.local/share/ai-memory/hooks//`.
Native package/source installs should rerun
`ai-memory install-hooks --agent --apply` after upgrading the binary.
Remote/homelab servers must still be redeployed separately; local wrapper
upgrade only updates the client machine. Existing project prompt files keep
working. Refresh the managed ai-memory routing package
(`ai-memory install-instructions`, or `--target AGENTS.md` for AGENTS-based
projects) when you want new tool guidance. The refresh writes the slim
markered snippet and managed Agent Skills from the same binary-owned assets.
For every client in the [Support Matrix](#support-matrix), plus curl-based hook
installs, source builds, CLI environment variables, and the full subcommand
reference, see [`docs/install.md`](docs/install.md).
Tab completion for the CLI is available in bash, zsh, fish, PowerShell, and
elvish:
```bash
ai-memory completions fish > ~/.config/fish/completions/ai-memory.fish
```
See [`docs/shell-completions.md`](docs/shell-completions.md) for the other
shells' install paths.
## Security
Loopback-only (`127.0.0.1:49374`) with no auth is the default because
it is safe for a single-user laptop: no process outside the machine can
reach the server.
Enable bearer auth when the server is exposed beyond loopback, when
untrusted local processes share the machine, or when the data dir holds
sensitive project history:
```bash
TOKEN=$(ai-memory generate-auth-token)
docker run -d --name ai-memory \
--restart unless-stopped \
-p 0.0.0.0:49374:49374 \
-v ai-memory-data:/data \
-e AI_MEMORY_AUTH_TOKEN="$TOKEN" \
-e AI_MEMORY_ALLOWED_HOSTS=",localhost,127.0.0.1" \
akitaonrails/ai-memory:latest
ai-memory install-mcp --client claude-code --apply \
--server-url "http://:49374/mcp" --auth-token "$TOKEN"
ai-memory install-hooks --agent claude-code --apply \
--server-url "http://:49374" --auth-token "$TOKEN"
```
Bearer auth protects `/mcp`, `/hook`, `/handoff`, `/admin/*`, and
`/web/*`. Browser access to `/web` uses HTTP Basic auth with the token
as the password. Non-loopback binds should also set
`AI_MEMORY_ALLOWED_HOSTS` to guard against DNS rebinding.
Busy shared hook servers can also set `AI_MEMORY_HOOK_RATE_PER_SEC` (tokens per
second per actor/session source) and optionally `AI_MEMORY_HOOK_RATE_BURST` to
bound one runaway session without blocking unrelated hook sources. Unset or `0`
rate leaves the limiter disabled.
For shared servers where each developer should authenticate their own hook
writes, native Claude Code hooks can use a stored OIDC device token instead of
embedding a shared static token:
```bash
ai-memory auth login oidc-device \
--issuer "https://issuer.example.com/realms/team" \
--client-id "ai-memory-cli"
ai-memory install-hooks --agent claude-code --apply \
--server-url "http://:49374"
```
OIDC hook auth requires the native `ai-memory hook ...` command path. The Docker
wrapper keeps shell-script hooks by default; set up OIDC from a native release
binary or source install. Thin-client HTTP commands such as `ai-memory status`
and `ai-memory search` also use the stored OIDC access token when no static
`AI_MEMORY_AUTH_TOKEN` / `[auth].bearer_token` is configured; the static bearer
still wins when present. This is for OIDC-aware gateways/bridges; native
ai-memory server auth still accepts static root bearer / DB-user tokens, and
`/admin/*` remains root-only unless a gateway translates accepted OIDC auth into
upstream auth that ai-memory accepts.
OIDC/Keycloak session ids are login-provider sessions, not ai-memory agent
sessions. Shared servers that rely on `[auto_scope]` session isolation still
need explicit `workspace` + `project` / `scopes`, or a bridge that forwards the
real lifecycle-hook session id on MCP requests.
**Want HTTPS?** ai-memory deliberately does not terminate TLS itself —
the right answer is a battle-tested reverse proxy in front of it.
[`docs/https-via-proxy.md`](docs/https-via-proxy.md) is the deployment
guide, with copy-paste docker compose templates in
[`docker/compose.tls.caddy.yml`](docker/compose.tls.caddy.yml) (Caddy
with Let's Encrypt or internal CA) and
[`docker/compose.tls.cloudflared.yml`](docker/compose.tls.cloudflared.yml)
(Cloudflare Tunnel — no open ports). Both are recommended once you
turn on multi-user or bind beyond loopback. The Quick Start happy
path of single-user on loopback doesn't need TLS — that case is
called out explicitly in the guide so you don't add ceremony where
it doesn't earn its keep.
**Multi-user attribution (v0.8, optional).** When more than one human
shares a server, ai-memory can attribute each write to a named user.
The bearer token continues to authenticate at the wire level; users
created via `ai-memory user add` get their own tokens that resolve to
their identity in audit logs, page frontmatter, `/api/v1` responses, and the
page view UI. Data stays single-tenant — there is no per-page RBAC. A
`[auth].token_pepper` is required for DB-user authentication, but creating the
first user row is what immediately switches every `/admin/*` endpoint to
root-only, including status/search/read-page and user-management routes.
`ai-memory init` generates a pepper for new installs without changing
single-user behavior until a user is added. An SSO gateway can instead use a
dedicated `[auth].actor_proxy_bearer_token` and trusted `X-Memory-Actor-*`
headers; its credential is deliberately separate from the root bearer so a
missing identity cannot become root. See
[`docs/users.md`](docs/users.md) for the full walkthrough and the
four-rung auth ladder.
See [`docs/deploy.md`](docs/deploy.md) for the full homelab pattern
with bearer auth, host allowlisting, and TLS/reverse-proxy options.
## Using Memory
Day to day, you mostly do not think about ai-memory. Lifecycle hooks
capture prompts, tool calls, compaction checkpoints, and session
boundaries. SessionStart hooks fetch pending handoffs before your first
prompt in the next agent.
Useful entry points:
- 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 ai-memory in an existing
project with months of history.
- Start the server with `--enable-web` and visit `/web` for a read-only
browser view of the markdown wiki. `--enable-web` also mounts a
read-only JSON frontend API at `/api/v1` (workspaces, projects, pages,
recent, briefing, search) so custom web UIs can read the memory without
opening SQLite or wiki files directly:
```text
GET /api/v1/workspaces
GET /api/v1/projects?workspace=...
GET /api/v1/workspaces/{workspace}/projects/{project}/pages
GET /api/v1/workspaces/{workspace}/projects/{project}/pages/{path}
GET /api/v1/workspaces/{workspace}/projects/{project}/recent?limit=...
GET /api/v1/workspaces/{workspace}/projects/{project}/briefing?limit=...
GET /api/v1/workspaces/{workspace}/overview?limit=...
GET /api/v1/workspaces/{workspace}/projects/{project}/overview?limit=...
GET /api/v1/workspaces/{workspace}/projects/{project}/handoffs?state=...&limit=...
GET /api/v1/search?q=...&workspace=...&project=...&limit=...
POST /api/v1/search { "q": "...", "scopes": [{ "workspace": "...", "project": "..." }] }
```
`overview` bundles the open handoff + briefing + memory-health for a workspace
or project in one call (the data a project overview screen needs). The
handoff history defaults to the caller's own plus shared rows; root can use
`all_owners=true` for recovery across operators.
**Full integration guide:** see [`docs/frontend-api.md`](docs/frontend-api.md)
for auth setup, response schemas, error model, limits/pagination,
custom-UI hosting, a worked `fetch`/`curl` example, and the canonical
source-of-truth files. Read that first if you're building a frontend.
To serve your own static frontend instead of the built-in UI, point
`--web-ui-dir` at the frontend's build output (same-origin with
`/api/v1`, `/mcp`, `/admin/*`, so the existing auth applies):
```bash
ai-memory serve --transport http --bind 127.0.0.1:49374 \
--enable-web --web-ui-dir ../ai-memory-ui/dist
```
A reference implementation — a SolidJS knowledge browser with
screenshots and e2e tests — lives at
[djalmajr/ai-memory-ui](https://github.com/djalmajr/ai-memory-ui).
Richer products such as import/migration pipelines and write-capable
browser chat/editors should live as optional companion crates or projects
that call ai-memory's public HTTP/MCP surfaces. The first implemented
companion is the standalone OMC wiki importer at
[`companions/ai-memory-importer`](companions/ai-memory-importer), which is
intentionally not a root workspace member and is not included in root
`cargo test --workspace`. See
[`docs/companion-crates.md`](docs/companion-crates.md) for the boundary.
When a reverse proxy hosts ai-memory under a URL subpath, set
`--base-path` (or `AI_MEMORY_BASE_PATH`) so every HTTP surface moves
together. Example: `--base-path /wiki` serves MCP at `/wiki/mcp`, hooks at
`/wiki/hook`, the API at `/wiki/api/v1`, and the default browser at
`/wiki/web`. Set `--web-slug /` if you want the browser or custom SPA at
`/wiki` itself.
Install the managed routing package once so agents proactively call the
right MCP tool for those prompts:
```bash
ai-memory install-instructions
```
That command writes or updates the slim `` block and
the managed ai-memory Agent Skills that carry the detailed routing guidance.
See [`docs/usage.md`](docs/usage.md) for handoff examples, proactive query
routing, bootstrap details, web UI screenshots, and the raw-wiki inspection
commands. CLI URL/auth configuration lives in
[`docs/install.md`](docs/install.md#configuring-the-cli-url-and-auth).
### Entity retrieval
Consolidation extracts specific technologies, components, services, files, and
domain nouns into each page's canonical frontmatter. Hand-edited wiki pages can
declare the same bounded index explicitly:
```yaml
---
title: Queue choice
entities:
- nats jetstream
- delivery guarantees
---
```
Names are lowercased, whitespace-normalized, de-duplicated, capped at 10 per
page and 64 characters each, and rebuilt from Markdown during a clean-store
`ai-memory reindex`.
Entity lookup is project-scoped, ignores expired pages by default, and reports
`entity_rank`, its raw inverse-frequency `entity_weight`, `matched_entities`,
and its RRF contribution under
`memory_query(..., explain: true)`.
## LLM Providers
ai-memory runs without an LLM: hooks still capture sessions, search uses
FTS5 + declared entities + graph neighbors, and summaries fall back to
rule-based output. Add an LLM provider
when you want LLM consolidation (on PreCompact, on demand via
`memory_consolidate`, or opt-in at session end with
`AI_MEMORY_CONSOLIDATE_ON_SESSION_END`), richer linting, and bootstrap.
Session end always writes a rule-based summary page + handoff either way.
When the session-end opt-in is enabled, provider work is durably queued after
those deterministic writes and handled by one bounded server worker, so hook
drain latency does not cancel it. Failed jobs retry with backoff and survive a
server restart. A resumed native session is ended again only after its
observation generation advances; the persisted generation watermark makes
duplicate SessionEnd delivery and system clock skew converge without repeated
provider work. The end watermark and automatic handoff commit atomically, and
an interrupted keyed replay finishes the wiki commit, queue insert, and key
completion without duplicating that handoff. On the next SessionStart, the
newest cwd-eligible automatic handoff wins; accepting it expires older eligible
automatic handoffs without consuming manual or sibling-directory work. A new
automatic handoff also expires prior open automatic handoffs from its exact
cwd, so repeated SessionEnds cannot accumulate there before a receiver starts.
To keep consolidation style project-specific, write
`_prompts/consolidation.md` in that project's wiki. Its body can express
preferences such as "prefer Portuguese titles" or "omit routine CI noise".
Automatic, single-page, and multi-page consolidation use the page; a manual
`memory_consolidate` call can pass `instructions` to override it once. ai-memory
sanitizes and caps the value at 2,000 characters, JSON-encodes it in the user
message, and treats it as untrusted advisory data. It cannot supply facts,
request tool use or disclosure, or override the consolidation schema and
faithfulness rules. TTL-expired preference pages are ignored. With no active
page or argument, no preference block is appended.
Recommended defaults:
| Provider | Default | Use when |
|---|---|---|
| `anthropic` | `claude-haiku-4-5` | Best default for consolidation quality and rule classification. |
| `anthropic-oauth` | `claude-sonnet-4-6` | Use a Claude Pro/Max subscription via `claude setup-token`, no API key. |
| `openai` | `gpt-5.4-mini` | Cheaper and faster hosted option. |
| `openai-oauth` | `gpt-5.5` | ChatGPT Pro/Plus/Codex backend via `ai-memory auth login openai-oauth`; no Platform API key. |
| `copilot` | `gpt-5.5` | GitHub Copilot Chat backend via `ai-memory auth login copilot` or `COPILOT_GITHUB_TOKEN`; requires a Copilot subscription. |
| `gemini` | `gemini-2.5-flash` | Google-hosted option with a generous free tier. |
| `openai-compat` | no default | OpenRouter, Atlas Cloud, Ollama, vLLM, LM Studio, and other compatible endpoints. |
`openai-oauth` stores a refresh token in `/auth.json` and talks to
the ChatGPT/Codex Responses backend, not `api.openai.com`. For Docker quick
starts, run `ai-memory auth login openai-oauth` with the wrapper so the token
lands in the same `ai-memory-data` volume as the server.
`anthropic-oauth` hits the same `/v1/messages` endpoint as `anthropic` but
authenticates with an OAuth bearer token instead of an API key. Run
`claude setup-token` once, then set `AI_MEMORY_LLM_PROVIDER=anthropic-oauth` and
`ANTHROPIC_OAUTH_TOKEN=` (or `CLAUDE_CODE_OAUTH_TOKEN`, which `claude
setup-token` writes automatically). No `ANTHROPIC_API_KEY` is needed.
**⚠️ Unofficial and against Anthropic's usage policies — use at your own risk;
it may get your account rate-limited or banned. See
[the warning in `docs/install.md`](docs/install.md#anthropic-via-claude-subscription-oauth).**
`copilot` stores a GitHub user token in the same auth file, exchanges it for a
short-lived Copilot API token via GitHub's `/copilot_internal/v2/token`, and
uses the Copilot Chat endpoint with `vscode-chat` integration headers. You can
also set `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN` on the server.
> [!TIP]
> **For the OAuth/subscription backends (`anthropic-oauth`, `openai-oauth`,
> `copilot`), pick a small, fast model** via `AI_MEMORY_LLM_MODEL` — e.g.
> `claude-haiku-4-5` or `gpt-5-mini`. ai-memory's LLM work (consolidation,
> lint, explore) is summarisation, not hard reasoning, so a Haiku/mini-class
> model is plenty and is much easier on subscription rate limits. Save the
> high-effort thinking models for your coding agent.
> [!TIP]
> **OpenAI-compatible structured output is schema-constrained by default.**
> ai-memory sends each operation's JSON Schema through
> `response_format=json_schema`, which recent Ollama, vLLM, LM Studio, and
> llama.cpp releases honour. It falls back to the tolerant parser when an
> endpoint explicitly rejects that field or returns a malformed shape. Set
> `AI_MEMORY_LLM_COMPAT_STRICT=false` only for an incompatible endpoint.
Reranking is optional and off by default. With an LLM provider configured,
`AI_MEMORY_RERANKER=llm` makes project and explicit-scope `memory_query`
calls over-fetch from the hybrid stage, fuse scopes, and make at most one LLM
call to reorder the best candidates. This can promote a relevant page that
RRF ranked below the requested cut, at the cost of LLM latency and usage. The
request sends the query plus at most 30 bounded page titles and search snippets
to the configured provider; all values are JSON-encoded and treated as
untrusted data. A timeout, provider error, or incomplete/invalid score set
preserves the normal order. `global=true` and supplemental global-preference
hits keep their existing non-RRF ranking. Concurrent provider calls are capped
at four; saturated queries keep their local ranking without waiting.
Embeddings are optional and separate from the LLM provider. Set
`AI_MEMORY_EMBEDDING_PROVIDER=openai`, `voyage`, `google`/`gemini`, or
`openai-compat` when you want vector retrieval in addition to FTS5 + entity +
graph-neighbor retrieval. `openai-compat` targets self-hosted engines
(Ollama, LM Studio, vLLM): it needs no API key and requires explicit
`AI_MEMORY_EMBEDDING_BASE_URL`, `AI_MEMORY_EMBEDDING_MODEL`, and
`AI_MEMORY_EMBEDDING_DIM`. Both the FTS-only and hybrid paths apply the same
bounded page-authority adjustment after candidate generation; embeddings
improve relevance recall but do not decide which source is canonical.
See [`docs/install.md#llm-provider-tiers`](docs/install.md#llm-provider-tiers)
for env vars and Ollama/OpenRouter/Atlas Cloud examples, and
[`docs/llm-provider-comparison.md`](docs/llm-provider-comparison.md)
for the empirical model comparison.
## Architecture
One Rust binary runs an MCP/HTTP server and owns one data directory:
```text
/
├── 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, 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
| File | What it is |
|---|---|
| [`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 (homelab/LAN) walkthrough. Read after the Quick start if your setup doesn't match the happy path. |
| [`docs/usage.md`](docs/usage.md) | Handoffs, proactive memory queries, slim routing snippet + managed Agent Skills, migration from other memory tools, web UI, raw-wiki inspection, and rules-vs-facts workflow. |
| [`docs/managed-workstreams.md`](docs/managed-workstreams.md) | Optional `ai-memory run` continuity across Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, OMP, Grok Build CLI, and Antigravity CLI: automatic harness selection, native resume, argument forwarding, ledger search, privacy, and recovery. |
| [`docs/managed-harness-contributions.md`](docs/managed-harness-contributions.md) | Protocol and acceptance bar for contributors adding managed resume, read-only transcript import, and startup context delivery to another harness. |
| [`docs/marker-file.md`](docs/marker-file.md) | `.ai-memory.toml` workspace/project routing for multi-client trees, mono-repos, worktrees, and work/personal separation. |
| [`docs/auto-scope.md`](docs/auto-scope.md) | `[auto_scope]` modes for shared servers: default single-slot routing, session-aware isolation, and multi-user `per_actor` behavior. |
| [`docs/macos.md`](docs/macos.md) | macOS install paths: native release binary (recommended), source build, the Docker wrapper, hook-platform notes, and current macOS 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 current hook/MCP harness caveats. |
| [`docs/mcp-install.md`](docs/mcp-install.md) | Per-client MCP and lifecycle notes, handoff-injection limits, and community bridge guidance. |
| [`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 (v0.8).** Four-rung auth ladder, `ai-memory user add/list/expire/revive/rotate-token` walkthrough, backward-compat migration for pre-v0.8 installs, token storage rationale. |
| [`docs/https-via-proxy.md`](docs/https-via-proxy.md) | **HTTPS via a reverse proxy.** When you need TLS (multi-user, non-loopback) and when you don't (loopback / stdio). Copy-paste docker compose templates for Caddy + Let's Encrypt, Caddy + internal CA (LAN-only), Cloudflare Tunnel (no open ports), and external cert files; plus native-Caddy + nginx recipes. The "thinking you're secure when you're not" failure modes explicitly called out. |
| [`docs/lifecycle-ops.md`](docs/lifecycle-ops.md) | **Read before running purge / rename / backup / restore / reset / reindex / restore-page.** Safety matrix for state-touching commands, per-project disk layout (how isolation actually works), checkpoint-based page recovery, and operator workflows for "fresh start", "snapshot before risky op", "drop one project", and rebuilding SQLite from wiki files. |
| [`docs/auto-improvement-loop.md`](docs/auto-improvement-loop.md) | Auto-improvement design notes: Hermes-inspired scheduled review, auto-approval default, manual review opt-in, pending proposal storage, and curator work. |
| [`docs/companion-crates.md`](docs/companion-crates.md) | Boundary and implementation plan for optional companion projects, including the standalone importer at [`companions/ai-memory-importer`](companions/ai-memory-importer), without widening core ai-memory. |
| [`docs/llm-provider-comparison.md`](docs/llm-provider-comparison.md) | Empirical notes behind the recommended LLM defaults. |
| [`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. |
| Research docs under `docs/` | Karpathy LLM Wiki notes, Hermes Agent, agentmemory / basic-memory / cognee deep-dives, lessons-learned from upstream issues. |
## Influences and prior art
- **[Karpathy LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)** - the compile-not-retrieve pattern.
- **[agentmemory](https://github.com/rohitg00/agentmemory)** - most of the right ideas; this project is the Rust successor.
- **[basic-memory](https://github.com/basicmachines-co/basic-memory)** - the markdown-on-disk source-of-truth model.
- **[cognee](https://github.com/topoteretes/cognee)** - pipeline composition and triplet embeddings.
- **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** - the self-improvement loop: post-turn review, approval gates, and curator boundaries.
- **[A-MEM](https://arxiv.org/abs/2502.12110)** - Zettelkasten-style atomic notes with link evolution.
## 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`.
