# Installation Guide

> **Choose your path before you start — installation differs by audience and deployment scale.**
>
> | I am… | My deployment is… | Start here |
> |---|---|---|
> | **A single developer** | One AI client (Claude Code / Cursor / ChatGPT / etc.) on one laptop | [`install-quickstart.md`](install-quickstart.md) — 5-minute super-simple install + LLM-backend wired in one config block. Skip the rest of this file. |
> | **An engineer / architect** | Multi-agent on one node, or any single-node production deployment | This file (full singleton reference) → [`production-deployment.md`](production-deployment.md) — 10-min hardening checklist. |
> | **An engineer / architect** | Multi-server, multi-rack, multi-DC, multi-region, swarm, or hive | [`enterprise-deployment.md`](enterprise-deployment.md) — 60–90 min planning artefact covering 8 topologies, federation, identity material at fleet scale, disaster recovery. |
> | **An engineer / architect** | PostgreSQL + Apache AGE storage backend (multi-tenant, multi-writer, 10M+ memories, KG-heavy workloads) | [`postgres-age-guide.md`](postgres-age-guide.md) — first-class postgres operator guide. |
> | **A decision-maker** | Evaluating ai-memory for adoption | [`audience/decision-maker.html`](audience/decision-maker.html) — security posture, threat model, deployment cost envelope. |
>
> This file (`INSTALL.md`) is the **SME singleton + single-node reference.** Path-A non-technical readers should use [`install-quickstart.md`](install-quickstart.md) instead — it covers configuration end-to-end without exposing every flag.

> **BLUF (Bottom Line Up Front):** `ai-memory` is an AI-agnostic memory management system that works with **any MCP-compatible AI client** -- including Claude AI, OpenAI ChatGPT, xAI Grok, META Llama, OpenClaw, and others. Install the binary, configure your AI client's MCP settings, and you get **7 MCP memory tools at the default `--profile core`** (or 74 advertised entries at `--profile full` — 73 callable memory tools + the always-on `memory_capabilities` bootstrap) at v0.7.0. The default `semantic` tier includes embedding-based hybrid recall out of the box. Total time: ~60 seconds (pre-built binary + fast internet; first semantic-tier run also downloads a ~100MB embedding model).

## Install in 60 Seconds (pre-built binary + fast internet)

1. **Install the binary** (pick one):

   **One-liner (pre-built binary, Linux/macOS):**
   ```bash
   curl -fsSL https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.sh | sh
   ```

   **Windows (PowerShell):**
   ```powershell
   irm https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.ps1 | iex
   ```

   **Cargo (crates.io):**
   ```bash
   cargo install ai-memory
   ```

   **Homebrew (macOS + Linux):**
   ```bash
   brew install alphaonedev/tap/ai-memory
   ```

   **cargo-binstall (pre-built, no compile):**
   ```bash
   cargo binstall ai-memory
   ```

   **Ubuntu/Debian (.deb manual install):**
   ```bash
   # Download from https://github.com/alphaonedev/ai-memory-mcp/releases/latest
   sudo dpkg -i ai-memory_0.7.0_amd64.deb   # or arm64
   ```

   **Fedora/RHEL (COPR — recommended):**
   ```bash
   sudo dnf copr enable alpha-one-ai/ai-memory
   sudo dnf install ai-memory
   ```

   **Fedora/RHEL (.rpm manual install):**
   ```bash
   # Download from https://github.com/alphaonedev/ai-memory-mcp/releases/latest
   sudo rpm -i ai-memory-0.7.0-1.x86_64.rpm    # or aarch64
   ```

   **Arch Linux (AUR — v0.7.0 Gap #3 / issue #804):**
   ```bash
   # via your favourite AUR helper (paru / yay / aurutils):
   paru -S ai-memory
   # or build from the in-repo PKGBUILD:
   git clone https://github.com/alphaonedev/ai-memory-mcp.git
   cd ai-memory-mcp/packaging/aur
   makepkg -si
   ```
   The PKGBUILD lives at `packaging/aur/PKGBUILD` and is reviewable in
   the source tree. The submitted AUR slot is `ai-memory` (operator
   ownership; upstream submission tracked in #804).

   **Docker:**
   ```bash
   docker build -t ai-memory https://github.com/alphaonedev/ai-memory-mcp.git
   docker run -p 9077:9077 -v data:/data ai-memory
   ```

   **From source (requires Rust + C compiler):**
   ```bash
   cargo install --git https://github.com/alphaonedev/ai-memory-mcp.git
   ```

   ### Version pinning (v0.7.0 Gap #3 / issue #804)

   For production deployments, pin to an exact version. The substrate
   honours semver discipline (`0.7.x` series stays backward-compatible;
   `0.8.0` will land schema bumps and new tools). The supported pin
   syntax per channel:

   | Channel       | Pin syntax                                                          |
   |---------------|---------------------------------------------------------------------|
   | Cargo         | `cargo install ai-memory --version =0.7.1 --locked`                 |
   | cargo-binstall| `cargo binstall ai-memory --version 0.7.1`                          |
   | Homebrew      | The tap publishes a single rolling `Formula/ai-memory.rb` (no versioned `@0.7.0` formula). Pin by installing the desired release, then `brew pin ai-memory` to block upgrades. |
   | COPR          | `sudo dnf install ai-memory-0.7.1-1.fc40`                           |
   | .deb / .rpm   | Download the `0.7.0` artifact from the GH Release; pin by filename. |
   | AUR           | AUR helpers build the latest PKGBUILD; pin by checking out the package at the `0.7.0-1` revision and `makepkg -si`, or hold with `IgnorePkg = ai-memory` in `pacman.conf`. |
   | Docker        | `docker pull ghcr.io/alphaonedev/ai-memory:0.7.1` (digest pin is even safer: `@sha256:…`). |

   In CI, prefer the cargo-binstall + `--version` form so the version
   appears in your build manifest and reproducibility is trivial.

2. **Configure MCP in your AI client.** The example below is for **Claude Code** — add the `mcpServers` key to `~/.claude.json` (user scope, applies to all projects):

   **macOS / Linux — semantic tier (default; no LLM backend needed):**
   ```json
   {
     "mcpServers": {
       "memory": {
         "command": "ai-memory",
         "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
       }
     }
   }
   ```

   **Windows** (in `%USERPROFILE%\.claude.json`):
   ```json
   {
     "mcpServers": {
       "memory": {
         "command": "ai-memory",
         "args": ["--db", "C:/Users/YourName/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
       }
     }
   }
   ```

   **`smart` / `autonomous` tier with a cloud LLM backend** (xAI Grok shown; same shape for OpenAI / Anthropic / Gemini / DeepSeek / Kimi / Qwen / Mistral / Groq / Together / Cerebras / OpenRouter / Fireworks / LMStudio / vLLM / llama.cpp server):

   ### Recommended path — `[llm]` section in `~/.config/ai-memory/config.toml` ([#1146](https://github.com/alphaonedev/ai-memory-mcp/issues/1146))

   Write the backend, model, and an env-var name pointing at your API key into the canonical config file. Every surface — MCP server, HTTP daemon, `ai-memory atomise`, `ai-memory curator`, the boot banner, and the `ai-memory doctor` reachability probe — reads the same file, so the boot banner and the live MCP server agree on the backend.

   ```toml
   # ~/.config/ai-memory/config.toml
   schema_version = 2

   tier = "autonomous"
   db   = "~/.claude/ai-memory.db"

   [llm]
   backend     = "xai"                    # ollama | openai | xai | anthropic | gemini |
                                          # deepseek | kimi | qwen | mistral | groq |
                                          # together | cerebras | openrouter |
                                          # fireworks | lmstudio | openai-compatible
   model       = "grok-4.3"               # vendor-specific identifier
   base_url    = "https://api.x.ai/v1"   # optional; vendor-default if unset
   api_key_env = "XAI_API_KEY"            # process-env-var name (NOT the literal key)
   # api_key_file = "/etc/ai-memory/keys/xai.key"   # mode 0400 enforced; alt to api_key_env
   ```

   Then keep the MCP config minimal — no `env:` block needed:

   ```json
   {
     "mcpServers": {
       "memory": {
         "command": "ai-memory",
         "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "autonomous"]
       }
     }
   }
   ```

   Export `XAI_API_KEY` in your shell rc (`.zshrc` / `.bashrc` / `.profile`) so the parent process inherits it; the MCP-spawned subprocess inherits from the AI client which inherits from your login shell. **Inline keys in `config.toml` are rejected at parse time** — use `api_key_env` (process-env reference) or `api_key_file` (file path; mode 0400 enforced).

   > **Service-manager daemons don't inherit shell-rc exports.** The above works for an MCP server spawned by your AI client. A `serve` or `curator --daemon` started by **launchd (macOS) or systemd (Linux)** does NOT see a key you `export` from `.zshrc`/`.bashrc` — its env comes only from the unit/plist. For those, prefer `api_key_file` (env-independent across platforms) or declare the key inside the unit's `Environment=` / plist `EnvironmentVariables` dict. See [`production-deployment.md` § 7b](production-deployment.md#7b-llm-backend-wiring-smart--autonomous-tier).

   Full canonical schema reference: [`CONFIG_SCHEMA.md`](CONFIG_SCHEMA.md).

   ### Override path — `env:` block in the MCP config

   Pre-#1146 operators wired LLM config via the `env:` block of the AI client's MCP config. This still works and takes precedence over `config.toml`, but it's the override layer now — useful for CI / per-session tweaks, not the primary path.

   ```json
   {
     "mcpServers": {
       "memory": {
         "command": "ai-memory",
         "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "autonomous"],
         "env": {
           "AI_MEMORY_LLM_BACKEND": "xai",
           "AI_MEMORY_LLM_API_KEY": "xai-...",
           "AI_MEMORY_LLM_MODEL": "grok-4.3"
         }
       }
     }
   }
   ```

   > **Important — MCP clients do NOT inherit your interactive shell.** Setting `export AI_MEMORY_LLM_BACKEND=xai` in `.zshrc` / `.bashrc` is sufficient for the standalone `ai-memory` CLI and the HTTP daemon, but is **NOT** sufficient for Claude Code / Cursor / Codex / Cline / Continue / Zed / Windsurf / etc. — they spawn the MCP server as a fresh subprocess with only the `env:` keys from the MCP config. The recommended path above (a `[llm]` section in `config.toml` with `api_key_env`) avoids this paper-cut by letting every surface read the same file. Background: [#1144](https://github.com/alphaonedev/ai-memory-mcp/issues/1144) (env-block paper-cut) and [#1146](https://github.com/alphaonedev/ai-memory-mcp/issues/1146) (single source of truth). Full per-backend recipes (every supported provider with copy-pasteable snippets): [`integrations/llm-backends.md`](integrations/llm-backends.md).

   > **Note:** `~/.claude.json` likely already exists with other settings. Merge the `mcpServers` key into the existing JSON — do not overwrite the file. See [Claude Code MCP Scopes](#claude-code-mcp-configuration-scopes) below for project-level and team-shared alternatives.

   > **`~` in `--db` args.** The binary uses a CLI `--db` value verbatim — tilde expansion happens in your shell (or in some MCP hosts), NOT inside ai-memory. Only a `db = "~/..."` line in `config.toml` is tilde-expanded by ai-memory itself (#507). If memories land in a literal `./~` directory, replace `~/.claude/ai-memory.db` in the args with the absolute path (e.g. `/Users/you/.claude/ai-memory.db`) or move the path into `config.toml`.

   > The `--tier` flag selects the feature tier: `keyword`, `semantic` (default), `smart`, or `autonomous`. **Important:** The `--tier` flag must be passed in the MCP args — the `config.toml` `tier` setting is not used when the server is launched by an AI client. Smart and autonomous tiers require an LLM backend — post-[#1067](https://github.com/alphaonedev/ai-memory-mcp/issues/1067) (v0.7.0), any of: local [Ollama](https://ollama.com), LMStudio, vLLM, llama.cpp server, OR any OpenAI-compatible vendor (xAI Grok, OpenAI, Anthropic, Google Gemini, DeepSeek, Kimi, Qwen, Mistral, Groq, Together, Cerebras, OpenRouter, Fireworks). Selected via `AI_MEMORY_LLM_BACKEND` env var. Full env-var matrix in [`ADMIN_GUIDE.md` § "LLM Backend Setup"](ADMIN_GUIDE.md#llm-backend-setup-smart--autonomous-tiers); MCP-config recipes in [`integrations/llm-backends.md`](integrations/llm-backends.md).
   > **Other AI platforms** (OpenAI ChatGPT, xAI Grok, META Llama, etc.) have their own MCP configuration locations. Consult your platform's documentation for where to add MCP server entries. The server command and args are the same — only the config file location differs.

3. **Restart your AI client.**

   > **Verify the LLM backend wired through (smart/autonomous tier only).** After restart, check the ai-memory boot banner that prints on first MCP session-start (or the AI client's MCP server stderr log). You should see `LLM ready (backend=<vendor>, model=<name>, …)` matching what you put in the `env:` block, plus an `embedder loaded (…)` line reflecting the independently-resolved `[embeddings]` configuration (#1598 — the embedder can be local Ollama or any API backend; the historical `(#1143)` dedicated-Ollama embed-client banner was superseded at this boot site). If you see `llm=gemma3:4b` or another local Ollama tag when you intended a cloud backend, the `env:` block didn't land — re-check the MCP config path you edited matches the AI client's actual scope. Full troubleshooting: [`TROUBLESHOOTING.md` § LLM backend silently fell back](TROUBLESHOOTING.md#llm-backend-silently-fell-back-to-ollama).

4. **Verify** — at the default `--profile core` (v0.7.0) you should see **7 new tools** registered plus the always-on `memory_capabilities` bootstrap (8 total): `memory_store`, `memory_recall`, `memory_search`, `memory_list`, `memory_get`, `memory_load_family`, `memory_smart_load`. To eagerly load the full v0.7.0 surface (74 advertised entries — 73 callable memory tools + the always-on `memory_capabilities` bootstrap), launch with `ai-memory mcp --profile full`. The full-profile surface includes (highlights): `memory_update`, `memory_delete`, `memory_promote`, `memory_forget`, `memory_stats`, `memory_link`, `memory_get_links`, `memory_consolidate`, `memory_expand_query`, `memory_auto_tag`, `memory_detect_contradiction`, the 4 archive tools, `memory_check_duplicate`, the 2 entity tools, the 3 KG tools (`memory_kg_query`/`memory_kg_timeline`/`memory_kg_invalidate`), `memory_get_taxonomy`, the 3 namespace-standard tools, the 3 pending-action tools, the 2 agent tools, `memory_notify`/`memory_inbox`, the 3 subscription tools, `memory_session_start`, `memory_gc`, and the v0.7 additions: `memory_reflect`, `memory_atomise`, `memory_ingest_multistep`, `memory_persona`, `memory_persona_generate`, `memory_offload`, `memory_deref`, `memory_calibrate_confidence`, the 7 L1-5 Agent Skills tools, `memory_check_agent_action`, `memory_rule_list`, `memory_export_reflection`, `memory_reflection_origin`, `memory_dependents_of_invalidated`, `memory_find_paths`, `memory_verify`, `memory_quota_status`, the archive-list metadata helpers (#860), and more. Full per-tool reference: [API_REFERENCE.md](API_REFERENCE.md). Run `memory_capabilities` from the agent loop to get the live family list.

5. **Test** -- ask your AI assistant to store a memory. It should use `memory_store` automatically.

6. **Disable built-in auto-memory (recommended).** ai-memory replaces built-in memory systems with zero-token-cost on-demand recall. Built-in systems load your entire memory into every message, burning tokens and money. Disable them:

   **Claude Code (Desktop or CLI):** Add to `~/.claude/settings.json`:
   ```json
   {
     "autoMemoryEnabled": false
   }
   ```

   **ChatGPT:** Settings > Personalization > Memory > turn off (ai-memory replaces it via MCP/HTTP)

   This stops the built-in system from injecting 200+ lines of memory context into every conversation. ai-memory uses zero tokens until `memory_recall` is called -- only relevant memories are returned, ranked by score.

7. **Token savings are automatic.** All recall, search, and list responses use TOON compact format by default -- eliminating 40-60% of repeated field-name tokens vs JSON. The MCP server also provides `recall-first` and `memory-workflow` prompts that teach AI clients to use memory proactively.

That's it. Everything below is optional detail.

---

## Prerequisites

> **Pre-built binaries have no prerequisites** -- just run `install.sh` or `install.ps1` as shown above. The requirements below only apply when building from source.

- **Rust toolchain (1.96+; `rust-version` in `Cargo.toml`)**: Install via [rustup](https://rustup.rs/)
  ```bash
  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  ```

- **C compiler**: Required for the candle ML backend and bundled SQLite:
  - **Ubuntu/Debian:** `sudo apt-get install build-essential pkg-config`
  - **Fedora/RHEL:** `sudo dnf install gcc pkg-config`
  - **macOS:** Xcode command line tools (`xcode-select --install`) -- usually already present
  - **Windows:** MSVC C++ build tools via [Visual Studio Installer](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (select "Desktop development with C++")

## Install from Source (One-Liner)

For the postgres + Apache AGE storage backend, append `--features sal,sal-postgres` to the `cargo install` command (adds the `migrate` + `schema-init` CLI subcommands and the `ai-memory serve --store-url postgres://…` daemon path).

```bash
cargo install --git https://github.com/alphaonedev/ai-memory-mcp.git
```

This builds a release binary and places it in `~/.cargo/bin/ai-memory`.

Or clone and build locally:

```bash
git clone https://github.com/alphaonedev/ai-memory-mcp.git
cd ai-memory
cargo install --path .
```

## Pre-built Binaries

Pre-built binaries are available on the [Releases](https://github.com/alphaonedev/ai-memory-mcp/releases) page for five targets: Linux (`x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu`), macOS (`x86_64-apple-darwin`, `aarch64-apple-darwin`), and Windows (`x86_64-pc-windows-msvc`, zipped). Releases are created on git tags. Note the pre-built binaries are default-feature builds — the `migrate` / `schema-init` subcommands and the postgres `--store-url` daemon path require a `--features sal,sal-postgres` source build.

The easiest way to install is via the install scripts:

```bash
# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.ps1 | iex
```

Or download and install manually:

```bash
tar xzf ai-memory-x86_64-unknown-linux-gnu.tar.gz
chmod +x ai-memory
sudo mv ai-memory /usr/local/bin/
```

## Platform Notes

- **macOS Gatekeeper**: Pre-built binaries downloaded outside the App Store may be quarantined. If you get "cannot be opened because the developer cannot be verified", run:
  ```bash
  xattr -d com.apple.quarantine ~/.cargo/bin/ai-memory
  # or wherever the binary was installed:
  xattr -d com.apple.quarantine /usr/local/bin/ai-memory
  ```

- **Windows**: Use the PowerShell install script (`install.ps1`) for pre-built binaries. For building from source, use `cargo install` with the MSVC toolchain (the default Rust target on Windows). MinGW is not supported.

- **WSL (Windows Subsystem for Linux)**: Works as native Linux. Follow the Ubuntu/Debian instructions for both pre-built binaries and building from source.

- **Docker**: A `Dockerfile` is included in the repository root. Build and run:
  ```bash
  docker build -t ai-memory .
  docker run --rm -v ai-memory-data:/data ai-memory --db /data/ai-memory.db serve
  ```

## Network Requirements

- **First run with `semantic` tier (or above)**: Downloads a ~100MB embedding model from HuggingFace. No account or API key is required. The model is cached in `~/.cache/huggingface/` for subsequent runs. After the initial download, no network access is needed for keyword or semantic tiers.
- **Smart/autonomous tiers**: Require an LLM backend. Post-#1067 (v0.7.0) any of 15 OpenAI-compatible vendors (xAI, OpenAI, Anthropic, Gemini, DeepSeek, Kimi/Moonshot, Qwen/DashScope, Mistral, Groq, Together, Cerebras, OpenRouter, Fireworks, LMStudio) or local Ollama works — selected via `AI_MEMORY_LLM_BACKEND`. Local Ollama is the default for zero-network installs; cloud backends require their respective API key.

## Disk Space

| Component | Size |
|-----------|------|
| `ai-memory` binary (pre-built) | ~50 MB |
| Cargo build from source (including build artifacts) | ~500 MB |
| Semantic embedding model (downloaded on first run) | ~100 MB |
| Ollama models (smart/autonomous tiers only) | ~1--2.3 GB |

## MCP Server Setup (Recommended)

The primary integration path is the **MCP tool server**. MCP (Model Context Protocol) is an open standard -- `ai-memory` works with **any MCP-compatible AI client**, including Claude AI, OpenAI ChatGPT, xAI Grok, META Llama, OpenClaw, and others.

### Step 1: Add MCP configuration

Each AI platform has its own MCP configuration location. The server command and arguments are identical across all platforms.

#### Claude Code MCP Configuration Scopes

Claude Code supports three scopes for MCP server configuration. Pick the one that matches your use case:

| Scope | File | Applies to | Best for |
|-------|------|------------|----------|
| **User** (global) | `~/.claude.json` | All projects on your machine | Personal tools you want everywhere |
| **Project** (shared) | `.mcp.json` in project root | Everyone who clones the repo | Team-wide tools (checked into git) |
| **Local** (private) | `~/.claude.json` under `projects` | One project, only you | Project-specific overrides |

> **Scope precedence:** Local > Project > User. A server defined in a narrower scope overrides a same-named server from a broader scope.

> **Important:** MCP servers are **not** configured in `settings.json` or `settings.local.json` — those files do not support `mcpServers`.

**User scope (recommended — available in every project):**

Merge the `mcpServers` key into your existing `~/.claude.json`:

<table>
<tr><th>macOS / Linux</th><th>Windows</th></tr>
<tr><td>

File: `~/.claude.json`

```json
{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}
```

</td><td>

File: `%USERPROFILE%\.claude.json`

```json
{
  "mcpServers": {
    "memory": {
      "command": "ai-memory.exe",
      "args": ["--db", "C:/Users/YourName/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}
```

</td></tr>
</table>

> **Note:** `~/.claude.json` likely already exists with other Claude Code settings (tips, projects, etc.). Add the `mcpServers` key at the top level of the existing JSON object — do not overwrite the file.

> **Adding an LLM backend (smart/autonomous tiers).** Extend the `memory` server block with an `env` map containing `AI_MEMORY_LLM_BACKEND`, `AI_MEMORY_LLM_API_KEY`, and `AI_MEMORY_LLM_MODEL`. **Do not** rely on shell exports — MCP-spawned subprocesses don't see your interactive shell's environment (see [#1144](https://github.com/alphaonedev/ai-memory-mcp/issues/1144)). Copy-pasteable recipes for every supported provider live in [`integrations/llm-backends.md`](integrations/llm-backends.md).

**Project scope (shared with your team via git):**

Create `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}
```

> Claude Code prompts for approval before using project-scoped MCP servers from `.mcp.json` files.

**Local scope (one project, private):**

Add an `mcpServers` entry under the project path in `~/.claude.json`:

```json
{
  "projects": {
    "/Users/you/my-project": {
      "mcpServers": {
        "memory": {
          "command": "ai-memory",
          "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "smart"]
        }
      }
    }
  }
}
```

#### Database Path by Platform

| Platform | Default `--db` path | Environment variable |
|----------|---------------------|---------------------|
| **macOS** | `~/.claude/ai-memory.db` | `$HOME/.claude/ai-memory.db` |
| **Linux** | `~/.claude/ai-memory.db` | `$HOME/.claude/ai-memory.db` |
| **Windows** | `C:\Users\YourName\.claude\ai-memory.db` | `%USERPROFILE%\.claude\ai-memory.db` |

> Use forward slashes in JSON args on all platforms: `"C:/Users/YourName/.claude/ai-memory.db"`. The `AI_MEMORY_DB` environment variable can also be used to set the database path globally.

#### OpenAI Codex CLI

| Scope | File | Notes |
|-------|------|-------|
| **Global** (user) | `~/.codex/config.toml` | macOS/Linux: `~/.codex/config.toml`; Windows: `%USERPROFILE%\.codex\config.toml` |
| **Project** | `.codex/config.toml` in project root | Only loaded for trusted projects |

> Override config directory with the `CODEX_HOME` environment variable.

```toml
[mcp_servers.memory]
command = "ai-memory"
args = ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
enabled = true
```

Or add via CLI:

```bash
codex mcp add memory -- ai-memory --db ~/.local/share/ai-memory/memories.db mcp --tier semantic
```

> **Notes for Codex CLI:** Codex uses TOML format with underscored key `mcp_servers` (not camelCase, not hyphenated — this is critical). Additional supported options include `env` (explicit key/value pairs), `env_vars` (list of env vars to forward), `cwd`, `startup_timeout_sec`, `tool_timeout_sec`, `enabled_tools` (restrict which memory tools are exposed), and `disabled_tools`. Use `/mcp` in the TUI to view server status. Codex also supports HTTP-based MCP servers via `url` and `bearer_token_env_var`. See [Codex MCP docs](https://developers.openai.com/codex/mcp).

> **Windows:** Use `%USERPROFILE%\.codex\config.toml`. WSL uses the Linux home directory by default — set `CODEX_HOME` to share config with the Windows host.

#### Google Gemini CLI

| Scope | File | Notes |
|-------|------|-------|
| **User** (global) | `~/.gemini/settings.json` | macOS/Linux: `~/.gemini/settings.json`; Windows: `%USERPROFILE%\.gemini\settings.json` |
| **Project** | `.gemini/settings.json` in project root | Scoped to the project directory |

```json
{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"],
      "timeout": 30000
    }
  }
}
```

Or add via CLI:

```bash
gemini mcp add memory ai-memory -- --db ~/.local/share/ai-memory/memories.db mcp --tier semantic
```

> **Notes for Gemini CLI:** Avoid underscores in server names (use hyphens). Tool names are auto-prefixed as `mcp_<serverName>_<toolName>`. Environment variables in the `env` field support `$VAR` / `${VAR}` syntax (all platforms) and `%VAR%` (Windows only) — undefined variables resolve to empty strings. Gemini sanitizes sensitive patterns (`*TOKEN*`, `*SECRET*`, `*PASSWORD*`) from the inherited environment unless explicitly declared. Add `"trust": true` to skip tool confirmation prompts. Additional supported options include `cwd`, `includeTools`, `excludeTools`, `url` (SSE), and `httpUrl` (HTTP). CLI management: `gemini mcp list`, `gemini mcp remove`, `gemini mcp enable/disable`. See [Gemini CLI MCP docs](https://geminicli.com/docs/tools/mcp-server/).

#### Cursor IDE

| Scope | File | Notes |
|-------|------|-------|
| **Global** (user) | `~/.cursor/mcp.json` | macOS/Linux: `~/.cursor/mcp.json`; Windows: `%USERPROFILE%\.cursor\mcp.json` |
| **Project** | `.cursor/mcp.json` in project root | Overrides global for same-named servers |

```json
{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
    }
  }
}
```

Or add via Cursor Settings > Tools & MCP.

> **Notes for Cursor:** Restart Cursor (or reload window) after editing `mcp.json`. Verify server status in Settings > Tools & MCP (green dot = connected). Supports `env` field for environment variables, `envFile` for `.env` files, and `${env:VAR_NAME}` interpolation in config values (note: env var interpolation can be unreliable for shell profile variables — use `envFile` with a `.env` file as a workaround). Also supports `url` + `headers` for remote HTTP/SSE servers. **~40 tool limit** across all MCP servers combined. See [Cursor MCP docs](https://cursor.com/docs/context/mcp).

#### Windsurf (Codeium)

| Scope | File | Notes |
|-------|------|-------|
| **Global only** | `~/.codeium/windsurf/mcp_config.json` | macOS/Linux: `~/.codeium/windsurf/mcp_config.json`; Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json` |

> **No project-level scope.** Windsurf uses global configuration only.

```json
{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
    }
  }
}
```

> **Notes for Windsurf:** Supports `${env:VAR_NAME}` interpolation in `command`, `args`, `env`, `serverUrl`, `url`, and `headers` fields. Also supports `disabled` (boolean) and `alwaysAllow` (list of tool names) per server. **100 tool limit** across all MCP servers. Can also add servers via MCP Marketplace or Windsurf Settings > Cascade > MCP Servers. See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp).

#### Continue.dev

| Scope | File | Notes |
|-------|------|-------|
| **User** (global) | `~/.continue/config.yaml` | macOS/Linux: `~/.continue/config.yaml`; Windows: `%USERPROFILE%\.continue\config.yaml` |
| **Project** | `.continue/mcpServers/` directory in workspace root | Individual YAML or JSON files per server |

```yaml
mcpServers:
  - name: memory
    command: ai-memory
    args:
      - "--db"
      - "~/.local/share/ai-memory/memories.db"
      - "mcp"
      - "--tier"
      - "semantic"
```

> **Notes for Continue.dev:** Uses YAML list format. MCP tools only work in agent mode. Supports `${{ secrets.SECRET_NAME }}` syntax for secret interpolation via Continue's secrets system. Project-level config uses the `.continue/mcpServers/` directory — drop individual YAML or JSON config files there (JSON configs from Claude Code, Cursor, etc. are auto-detected). See [Continue MCP docs](https://docs.continue.dev/customize/deep-dives/mcp).

#### xAI Grok (API-level, remote MCP)

Grok connects to MCP servers over HTTPS (remote only, no stdio). No config file — servers are specified per API request.

Start ai-memory as an HTTP server behind HTTPS:

```bash
ai-memory serve --host 127.0.0.1 --port 9077
# Expose via HTTPS reverse proxy (nginx, caddy, cloudflare tunnel, etc.)
```

Then add the MCP server to your Grok API call:

```bash
curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "tools": [{
      "type": "mcp",
      "server_url": "https://your-server.example.com/mcp",
      "server_label": "memory",
      "server_description": "Persistent AI memory with recall and search",
      "allowed_tools": ["memory_store", "memory_recall", "memory_search"]
    }],
    "input": "What do you remember about our project?"
  }'
```

> **Requirements:** HTTPS required. `server_label` is required. Supports Streamable HTTP and SSE transports. Optional parameters: `allowed_tools` / `allowed_tool_names` (restrict tools), `authorization` (bearer token), `headers` / `extra_headers` (custom HTTP headers). Works with the xAI native SDK, OpenAI-compatible Responses API, and Voice Agent API. See [xAI Remote MCP docs](https://docs.x.ai/docs/guides/tools/remote-mcp-tools).

#### META Llama (via Llama Stack)

No standardized config file path — configuration is deployment-specific. Two approaches:

**Option A: Python/Node.js SDK (programmatic):**

```bash
ai-memory serve --host 127.0.0.1 --port 9077
```

```python
client.toolgroups.register(
    provider_id="model-context-protocol",
    toolgroup_id="mcp::memory",
    mcp_endpoint={"uri": "http://localhost:9077/sse"}
)
```

**Option B: run.yaml (declarative):**

```yaml
providers:
  tool_runtime:
    - provider_id: model-context-protocol
      provider_type: remote::model-context-protocol
      config: {}

tool_groups:
  - toolgroup_id: mcp::memory
    provider_id: model-context-protocol
    mcp_endpoint:
      uri: "http://localhost:9077/sse"
```

> **Notes for Llama Stack:** Supports `${env.VARIABLE_NAME}` syntax for environment variable interpolation in run.yaml. Transport is migrating from SSE to Streamable HTTP as the primary protocol. See [Llama Stack Tools docs](https://llama-stack.readthedocs.io/en/latest/building_applications/tools.html).

#### OpenClaw

| Scope | File | Notes |
|-------|------|-------|
| **Single config** | Platform config file | OpenClaw uses a single configuration file (no separate global/project scopes) |

> **Important:** OpenClaw uses `mcp.servers` (NOT `mcpServers`). The key structure is different from most other platforms.

```json
{
  "mcp": {
    "servers": {
      "memory": {
        "command": "ai-memory",
        "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
      }
    }
  }
}
```

Or add via CLI:

```bash
openclaw mcp set memory '{"command":"ai-memory","args":["--db","~/.local/share/ai-memory/memories.db","mcp","--tier","semantic"]}'
```

> **Notes for OpenClaw:** Uses `mcp.servers` key (not camelCase `mcpServers` — this is critical). CLI management: `openclaw mcp list`, `openclaw mcp show <name>`, `openclaw mcp unset <name>`. See [OpenClaw MCP docs](https://docs.openclaw.ai/cli/mcp).

#### Nous Research Hermes Agent

| Scope | File | Notes |
|-------|------|-------|
| **Global only** | `~/.hermes/config.yaml` | YAML format, no per-project scope |

> **Important:** Hermes uses `mcp_servers` (underscored YAML key, NOT camelCase `mcpServers`).

**Stdio (local):**

```yaml
mcp_servers:
  memory:
    command: ai-memory
    args:
      - "--db"
      - "~/.local/share/ai-memory/memories.db"
      - "mcp"
      - "--tier"
      - "semantic"
```

**HTTP (remote — requires ai-memory running as HTTP daemon):**

```yaml
mcp_servers:
  memory:
    url: "http://localhost:9077/mcp"
```

**With tool filtering (restrict to core tools):**

```yaml
mcp_servers:
  memory:
    command: ai-memory
    args: ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
    tools:
      include:
        - memory_store
        - memory_recall
        - memory_search
        - memory_list
        - memory_get
```

> **Notes for Hermes Agent:** Uses YAML format with underscored `mcp_servers` key. Supports both stdio (local subprocess) and HTTP (remote endpoint) transports. Per-server tool filtering via `tools.include`/`tools.exclude`. Additional supported fields: `env` (environment variables), `timeout` (tool call timeout), `connect_timeout` (connection timeout), `enabled` (boolean), `sampling` (LLM inference config). See [Hermes MCP docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp).

If `ai-memory` is not in your PATH, use the full path to the binary in any of the configurations above:

```json
{
  "mcpServers": {
    "memory": {
      "command": "/usr/local/bin/ai-memory",
      "args": ["--db", "/var/lib/ai-memory/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}
```

### Step 2: Verify

Restart your AI client. With `--profile core` (default at v0.7.0) you should see 7 tools available (`memory_store`, `memory_recall`, `memory_search`, `memory_list`, `memory_get`, `memory_load_family`, `memory_smart_load`) plus the always-on `memory_capabilities` bootstrap. With `--profile full` you get all 74 advertised entries (73 callable memory tools + `memory_capabilities`). Other profiles: `graph` (18 tools), `admin` (21 tools), `power` (30 tools). The full advertised inventory is asserted by `Profile::full().expected_tool_count() = 74` in `src/profile.rs`; the canonical surface list lives in `docs/USER_GUIDE.md`.

### Step 3: Test

Ask your AI assistant to store a memory. It should use the `memory_store` tool automatically.

## Hook Installation (Optional, Claude Code-Specific)

The SessionStart hook auto-recalls relevant memories at the start of each Claude Code session. Other AI platforms may have their own hook/plugin mechanisms -- the CLI commands used in this hook work with any platform.

### Recommended — one command

```bash
ai-memory install claude-code            # dry-run (default) — prints what would change
ai-memory install claude-code --apply    # actually write the file
```

This writes a managed `SessionStart` entry into `~/.claude/settings.json`
running `ai-memory boot --quiet --limit 10 --budget-tokens 4096` on every
fresh session. Re-running is idempotent;
`ai-memory install claude-code --uninstall --apply` removes the managed
entry surgically.

### Manual alternative — `hooks/session-start.sh`

```bash
# Copy the hook
cp hooks/session-start.sh ~/.claude/hooks/

# Make it executable
chmod +x ~/.claude/hooks/session-start.sh
```

Then configure it under the `SessionStart` event in
`~/.claude/settings.json` (note the nested `hooks` array shape Claude
Code expects):

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/session-start.sh" }
        ]
      }
    ]
  }
}
```

### Environment variables for the hook

| Variable | Default | Description |
|----------|---------|-------------|
| `AI_MEMORY_DB` | `ai-memory.db` | Path to the database |
| `AI_MEMORY_BIN` | `ai-memory` | Path to the binary |

## Systemd Service Setup (HTTP Daemon)

If you want to run the HTTP daemon as a background service (alternative to MCP). The HTTP API at `localhost:9077` works with **any AI platform, framework, or tool** -- no MCP required:

```bash
sudo tee /etc/systemd/system/ai-memory.service > /dev/null << 'EOF'
[Unit]
Description=AI Memory Daemon
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/ai-memory --db /var/lib/ai-memory/ai-memory.db serve
Restart=on-failure
RestartSec=5
Environment=RUST_LOG=ai_memory=info

# Graceful shutdown checkpoints the WAL
KillSignal=SIGINT
TimeoutStopSec=10

[Install]
WantedBy=multi-user.target
EOF
```

Create the data directory and enable the service:

```bash
sudo mkdir -p /var/lib/ai-memory
sudo systemctl daemon-reload
sudo systemctl enable --now ai-memory
```

## Verify Installation

```bash
# Check the binary
ai-memory --help

# v0.7.x — comprehensive health check (Storage / Index / Recall /
# Governance / Sync / Webhook / Capabilities / Reflection Health /
# LLM Reachability (#1146) + Embeddings Reachability (#1598)).
# 10-section operator-visible dashboard.
ai-memory doctor

# If running as MCP server, test manually:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ai-memory mcp
# Expected: JSON-RPC response with serverInfo

# If running as HTTP daemon, check health:
curl http://127.0.0.1:9077/api/v1/health
# Expected: {"status":"ok","service":"ai-memory"}

# Store a test memory via CLI
ai-memory store -T "Installation test" -c "It works." --tier short

# Recall it
ai-memory recall "installation"
```

## Post-install: migrate from v0.6.x (if upgrading)

**If you're upgrading from v0.6.x**, run the one-shot config
migrator to rewrite `~/.config/ai-memory/config.toml` from the
legacy flat-field shape (`llm_model`, `ollama_url`, `embed_url`,
`embedding_model`, `cross_encoder`, `default_namespace`, ...) into
the v0.7.x sectioned schema (`[llm]`, `[llm.auto_tag]`,
`[embeddings]`, `[reranker]`, `[storage]`):

```bash
# 1. Preview the rewrite (no writes)
ai-memory config migrate --dry-run

# 2. Apply with a timestamped .bak backup
ai-memory config migrate

# 3. (Optional, opt-in) — also strip the now-redundant
#    mcpServers.<*>.env block from ~/.claude.json (only entries
#    whose `command` resolves to ai-memory are touched)
ai-memory config migrate --also-clean-claude-json

# 4. Verify wiring end-to-end
ai-memory doctor
```

The migrator is **idempotent** — running against an already-v2
file is a no-op INFO log. Legacy v0.6.x flat fields continue to
work in v0.7.x with a single-line deprecation WARN at load time;
they will be removed in v0.8.0.

The DB schema migration is **automatic** — the daemon walks v20 →
v55 on first open of an existing v0.6.4 DB (writing an automatic
`<db>.pre-migration-v<from>-to-v<to>-<token>.bak` snapshot first).
No operator action required.

For a comprehensive walkthrough (security-posture defaults that
changed, tiered admin / DevOps recipes, NFS-shared config fleets),
see [`docs/MIGRATION_QUICKSTART.md`](MIGRATION_QUICKSTART.md).

## Man Page

Generate and install the man page:

```bash
# View immediately
ai-memory man | man -l -

# Install system-wide
ai-memory man | sudo tee /usr/local/share/man/man1/ai-memory.1 > /dev/null
sudo mandb
man ai-memory
```

## Shell Completions

Generate completions for your shell:

```bash
# Bash
ai-memory completions bash > ~/.local/share/bash-completion/completions/ai-memory

# Zsh
ai-memory completions zsh > ~/.zfunc/_ai-memory
# Then add to ~/.zshrc: fpath+=~/.zfunc && autoload -Uz compinit && compinit

# Fish
ai-memory completions fish > ~/.config/fish/completions/ai-memory.fish
```

## LLM Backend Setup (Smart & Autonomous Tiers)

Smart and autonomous tiers require an LLM backend. **Post-[#1067](https://github.com/alphaonedev/ai-memory-mcp/issues/1067) + [#1146](https://github.com/alphaonedev/ai-memory-mcp/issues/1146) (v0.7.0)** the backend is provider-agnostic — pick from:

- **Local LLM:** [Ollama](https://ollama.com), [LMStudio](https://lmstudio.ai), [vLLM](https://docs.vllm.ai), or llama.cpp server (any OpenAI-compatible local endpoint).
- **Cloud LLM:** xAI Grok, OpenAI, Anthropic (via OpenAI shim), Google Gemini, DeepSeek, Kimi (Moonshot), Qwen (Alibaba), Mistral, Groq, Together AI, Cerebras, OpenRouter, Fireworks.

The `keyword` and `semantic` tiers do **not** require any LLM backend.

### Recommended path — `[llm]` section in `config.toml`

Single source of truth — every surface (MCP, HTTP daemon, CLI, boot banner, doctor probe) reads the same file. Example for xAI Grok 4.3:

```toml
# ~/.config/ai-memory/config.toml
schema_version = 2

[llm]
backend     = "xai"
model       = "grok-4.3"
base_url    = "https://api.x.ai/v1"
api_key_env = "XAI_API_KEY"                       # process-env-var name
# api_key_file = "/etc/ai-memory/keys/xai.key"    # alt — mode 0400 enforced
```

Export `XAI_API_KEY` in the parent shell (`.zshrc` / `.bashrc` / `.profile`) so the daemon and MCP-spawned subprocess inherit it. **Inline keys in `config.toml` are rejected at parse time.**

Verify end-to-end:

```bash
ai-memory boot --quiet --limit 1   # banner should report llm=xai:grok-4.3
ai-memory doctor                    # LLM Reachability (#1146) — DNS + TLS + auth round-trip
```

Canonical schema reference: [`CONFIG_SCHEMA.md`](CONFIG_SCHEMA.md). Full operator runbook (per-vendor recipes, precedence ladder, secret-handling discipline): [`ADMIN_GUIDE.md` § "LLM Backend Setup"](ADMIN_GUIDE.md#llm-backend-setup-smart--autonomous-tiers).

### Override path — env vars

`AI_MEMORY_LLM_BACKEND` / `_MODEL` / `_BASE_URL` / `_API_KEY` env vars take precedence over `[llm]` in `config.toml`. Useful for CI / per-session tweaks, and the only path that doesn't require editing a file. Per-vendor recipes: [`integrations/llm-backends.md`](integrations/llm-backends.md).

### Ollama (local LLM — v0.6.4 default, still supported)

Below is the canonical local-Ollama install path. For other backends, write the `[llm]` section per the recipe above (or set env vars as the override path).

### macOS

```bash
# Install via Homebrew
brew install ollama

# Or download directly from https://ollama.com/download/mac
# Drag Ollama.app to Applications

# Start Ollama (runs as a background service)
ollama serve &

# Pull the model for your tier
ollama pull gemma3:4b     # Default LLM model for ai-memory (~3 GB) — handles smart-tier auto-tag + contradict + query expansion
ollama pull nomic-embed-text:v1.5  # Default embedder (~280 MB) — semantic + autonomous tiers
```

### Linux

```bash
# One-line install script
curl -fsSL https://ollama.com/install.sh | sh

# Start the service
sudo systemctl enable ollama
sudo systemctl start ollama

# Or run manually
ollama serve &

# Pull the model for your tier
ollama pull gemma3:4b     # Default LLM model for ai-memory (~3 GB) — handles smart-tier auto-tag + contradict + query expansion
ollama pull nomic-embed-text:v1.5  # Default embedder (~280 MB) — semantic + autonomous tiers
```

### Windows

```powershell
# Download installer from https://ollama.com/download/windows
# Run OllamaSetup.exe — installs and starts as a background service

# Or install via winget
winget install Ollama.Ollama

# Pull the model (in PowerShell or Command Prompt)
ollama pull gemma3:4b     # Default LLM model for ai-memory (~3 GB) — handles smart-tier auto-tag + contradict + query expansion
ollama pull nomic-embed-text:v1.5  # Default embedder (~280 MB) — semantic + autonomous tiers
```

### Verify Ollama is Running

```bash
# Check Ollama status
curl http://localhost:11434/api/tags

# Test the model
ollama run gemma3:4b "Hello, world"
```

### Configure ai-memory for Smart/Autonomous Tier

```json
{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "smart"]
    }
  }
}
```

> ai-memory connects to Ollama at `http://localhost:11434` automatically. No additional configuration needed. If Ollama is not running, LLM-backed features degrade gracefully (the semantic-tier embedder + keyword recall keep working). Post-#1598 the embedder itself can also be pointed at an API backend instead of Ollama — see `[embeddings]` in [`CONFIG_SCHEMA.md`](CONFIG_SCHEMA.md).

> **Note:** The `semantic` tier (default) downloads a HuggingFace embedding model (~100 MB) on first startup. No account or API key is required. The model is cached in `~/.cache/huggingface/`.

## Multi-Node Sync Setup

If you use ai-memory on multiple machines (e.g., laptop and server), you can sync databases:

```bash
# Pull memories from a remote database (e.g., over NFS, sshfs, or rsync'd copy)
ai-memory sync /mnt/server/ai-memory.db --direction pull

# Push local memories to remote
ai-memory sync /mnt/server/ai-memory.db --direction push

# Bidirectional merge (both sides get all memories, dedup-safe)
ai-memory sync /mnt/server/ai-memory.db --direction merge
```

The sync operation uses the same dedup-safe upsert as regular stores -- title+namespace conflicts are resolved by keeping the higher priority and never downgrading tier.

## Uninstall

```bash
# Stop and remove the service (if using systemd)
sudo systemctl stop ai-memory
sudo systemctl disable ai-memory
sudo rm /etc/systemd/system/ai-memory.service
sudo systemctl daemon-reload

# Remove MCP configuration from ~/.claude.json (delete the "mcpServers" key)
# Or remove .mcp.json from your project root if using project scope

# Remove the binary
cargo uninstall ai-memory
# or: sudo rm /usr/local/bin/ai-memory

# Remove the database (WARNING: deletes all memories)
rm -f ai-memory.db ai-memory.db-wal ai-memory.db-shm
# or if using the systemd path:
# sudo rm -rf /var/lib/ai-memory
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `AI_MEMORY_DB` | `ai-memory.db` | Path to the SQLite database file |
| `RUST_LOG` | (none) | Log level filter (e.g., `ai_memory=info,tower_http=info`) |

### TTL and Archive Configuration

Memory TTLs (time-to-live) can be customized per tier via `config.toml`. When garbage collection runs, expired memories can optionally be archived instead of permanently deleted by setting `archive_on_gc = true`. Archived memories can be listed, restored, or purged using the 4 archive tools (`memory_archive_list`, `memory_archive_restore`, `memory_archive_purge`, `memory_archive_stats`). See the [Admin Guide](ADMIN_GUIDE.md) for full configuration details.

> **Note:** Configuration is loaded once at process startup. Changes to `config.toml` require restarting the ai-memory process (MCP server, HTTP daemon, or CLI) to take effect.

**Setting environment variables by platform:**

macOS / Linux (add to `~/.bashrc`, `~/.zshrc`, or equivalent):
```bash
export AI_MEMORY_DB="$HOME/.claude/ai-memory.db"
```

Windows (PowerShell — persistent for current user):
```powershell
[Environment]::SetEnvironmentVariable("AI_MEMORY_DB", "$env:USERPROFILE\.claude\ai-memory.db", "User")
```

Windows (Command Prompt — persistent):
```cmd
setx AI_MEMORY_DB "%USERPROFILE%\.claude\ai-memory.db"
```