--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. 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.
- **"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.
yay -S ai-memory-bin # prebuilt Linux x86_64/aarch64 binary
yay -S ai-memory # builds from source
Single-user workstation:
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.
# 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
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 devin`, `--agent opencode`, `--agent gemini-cli`,
# `--agent grok`, `--agent kimi-code`, `--agent omp`, `--agent oh-my-pi`, `--client cursor`,
# `--client gemini-cli`, `--client grok`, 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
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).
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.
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.
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:
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
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
- **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.
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-run wrapper:** `ai-memory run` must be intercepted by the current
host wrapper so the native harness and its session store remain accessible.
An old wrapper may pass `run` into Docker and fail with `No such file or
directory` for `codex`, `claude`, or another 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).
## 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:
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:
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. 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:
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/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).
**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):
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:
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).
## LLM Providers
ai-memory runs without an LLM: hooks still capture sessions, search uses
FTS5, 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.
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, 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.
Embeddings are optional and separate from the LLM provider. Set
`AI_MEMORY_EMBEDDING_PROVIDER=openai`, `voyage`, `google`, or `gemini` when
you want vector reranking in addition to FTS5 + graph-neighbor retrieval.
See [`docs/install.md#llm-provider-tiers`](docs/install.md#llm-provider-tiers)
for env vars and Ollama/OpenRouter 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:
/
├── wiki/ # markdown source of truth, git-versioned
├── raw/ # immutable sanitized managed-workstream transcript segments
├── db/ # SQLite indexes, including FTS5 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, graph-neighbor RRF, optional
vector RRF, 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, and OMP: 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`.
