### First-time Setup for ai-memory Deployment

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/deploy.md

This script guides through the initial setup of ai-memory on a homelab. It involves copying example configuration files, editing them with homelab-specific values, creating necessary directories on the server, and then copying the configuration files to the server before running the main deployment script.

```bash
# 1. Stamp your homelab values into the local config.
cp bin/deploy.env.example bin/deploy.env
$EDITOR bin/deploy.env                # fill SERVER / DEPLOY_DIR / IMAGE

cp docker/docker-compose.prod.yml.example docker/docker-compose.prod.yml
$EDITOR docker/docker-compose.prod.yml   # set the image tag + adjust ports if needed

cp docker/.env.production.example docker/.env.production
$EDITOR docker/.env.production        # fill API keys; pick LLM provider + model

# 2. Create the deploy dir on the homelab. Source bin/deploy.env so
#    SERVER/DEPLOY_DIR are exported in this shell.
source bin/deploy.env
ssh "$SERVER" "sudo mkdir -p $DEPLOY_DIR/data && \
               sudo chown -R 1000:1000 $DEPLOY_DIR"

# 3. Copy the compose + env to the homelab.
scp docker/docker-compose.prod.yml "$SERVER:$DEPLOY_DIR/docker-compose.yml"
scp docker/.env.production         "$SERVER:$DEPLOY_DIR/.env.production"

# 4. Run the first deploy.
bin/deploy
```

--------------------------------

### Install ai-memory with yay

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Choose between a prebuilt binary for faster installation or building from source. Both methods install the same runtime layout.

```bash
yay -S ai-memory-bin    # prebuilt Linux x86_64/aarch64 binary, fastest install
yay -S ai-memory        # builds from source, works on x86_64 and aarch64
```

--------------------------------

### Memory Query and Exploration Examples

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md

Illustrates various ways agents can query and explore memory. These examples show how to check past decisions, get summaries, and write durable knowledge.

```markdown
| You say | Agent calls |
|---|---|
| "Have we discussed X?" / "search memory for Y" | `memory_query` |
| Before proposing architecture | `memory_query` |
| "Catch me up" / "I've been away" | `memory_explore` |
| "Where did we leave off?" | Existing handoff block, or `memory_handoff_accept` if no block exists |
| "Save context for the next session" | `memory_handoff_begin` |
| "Discard that handoff" / "I created a handoff by mistake" | `memory_handoff_cancel` |
| "Consolidate this session" | `memory_consolidate` |
| "Remember this permanently" / "add an annotation" | `memory_write_page` |
| "Delete this page" / "remove the note about X" | `memory_delete_page` |
| "Audit the wiki" / "any contradictions?" | `memory_lint` |
| "How big is the wiki?" / "stats?" | `memory_status`, `memory_briefing` |
```

--------------------------------

### Install ai-memory from AUR

Source: https://github.com/akitaonrails/ai-memory/blob/main/packaging/aur/README.md

Use an AUR helper to install either the prebuilt binary or the source-built version of ai-memory.

```bash
yay -S ai-memory-bin    # prebuilt binary, fastest on x86_64/aarch64
yay -S ai-memory        # builds from source, supports x86_64/aarch64
```

--------------------------------

### Docker Compose Configuration for Web UI

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md

Example of how to enable the web UI within a Docker Compose setup by modifying the serve command.

```yaml
command: ["serve", "--transport", "http", "--bind", "0.0.0.0:49374", "--enable-web"]
```

--------------------------------

### Install MCP Client with Authentication Token

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/deploy.md

Installs an MCP client and configures it with an authentication token. This command is a template and should be run per client.

```bash
ai-memory install-mcp --client <name> --auth-token <token>
```

--------------------------------

### Install Client Hooks for Handoff

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/mcp-install.md

To enable cross-agent handoffs, ensure the client agent has the necessary hooks installed. This example shows installing hooks for the Cursor agent.

```bash
install-hooks --agent cursor --apply
```

--------------------------------

### Install MCP and Plugin for OpenCode

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Installs the MCP configuration and the AI memory plugin for OpenCode. For hooks, it recommends using `--apply` if the local wrapper is installed, otherwise, it shows a Docker-only preview path. Restart OpenCode after installation.

```bash
docker run --rm akitaonrails/ai-memory:latest \
    install-mcp --client opencode \
    --server-url "http://homelab:49374/mcp" \
    --auth-token "$TOKEN"

# Plugin — write to ~/.config/opencode/plugins/ai-memory.ts.
# If you have the local wrapper installed, prefer `--apply`:
ai-memory install-hooks --agent opencode --apply \
    --server-url "http://homelab:49374" \
    --auth-token "$TOKEN"

# Docker-only preview path; redirect only if you want to write the file yourself:
docker run --rm akitaonrails/ai-memory:latest \
    install-hooks --agent opencode \
    --server-url "http://homelab:49374" \
    --auth-token "$TOKEN"
```

--------------------------------

### Project Configuration Example

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/research-basic-memory.md

Configuration structure for managing projects, including path, mode, and workspace ID.

```python
Dict[str, ProjectEntry] (`config.py:184-195`)
```

--------------------------------

### Start ai-memory Server

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/mcp-install.md

If the MCP server is not running, start it using Docker or the ai-memory serve command.

```bash
docker start ai-memory
```

```bash
ai-memory serve --transport http
```

--------------------------------

### Initialize User-Level Service

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Set up the data and configuration directories for the user-level service. This is suitable for single-user workstations and does not require sudo after installation.

```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
```

--------------------------------

### Install MCP Client

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Installs the MCP (Message Communication Protocol) client configuration. This is used to set up communication with the AI Memory server from a client.

```bash
docker run --rm akitaonrails/ai-memory:latest install-mcp --client cursor
```

--------------------------------

### Install MCP and Extension for Oh My Pi / OMP

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Installs the MCP configuration and the AI memory extension for Oh My Pi (OMP). Similar to OpenCode, it suggests using `--apply` with the local wrapper if available. Restart OMP after installation. Note the different client/agent flags for OMP.

```bash
docker run --rm akitaonrails/ai-memory:latest \
    install-mcp --client pi \
    --server-url "http://homelab:49374/mcp" \
    --auth-token "$TOKEN"

# Extension — write to ~/.omp/agent/extensions/ai-memory.ts.
# If you have the local wrapper installed, prefer `--apply`:
ai-memory install-hooks --agent omp --apply \
    --server-url "http://homelab:49374" \
    --auth-token "$TOKEN"
```

--------------------------------

### Install MCP and Hooks for Client Agent

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Installs the necessary components (MCP and hooks) for a client agent to interact with the ai-memory server. Assumes server URL and token are configured.

```bash
ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --agent  claude-code --apply
```

--------------------------------

### Install MCP for Cursor Client

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Installs the MCP configuration for the Cursor client using Docker. Requires an authentication token and server URL.

```bash
docker run --rm akitaonrails/ai-memory:latest \
    install-mcp --client cursor          --auth-token "$TOKEN" \
    --server-url "http://homelab:49374/mcp"
```

--------------------------------

### Install Hooks for Cursor Agent

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Installs hooks for the Cursor agent using Docker. Requires an authentication token and server URL.

```bash
docker run --rm akitaonrails/ai-memory:latest \
    install-hooks --agent cursor         --auth-token "$TOKEN" \
    --server-url "http://homelab:49374"
```

--------------------------------

### Install MCP for Claude Desktop Client

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Installs the MCP configuration for the Claude Desktop client using Docker. Requires an authentication token and server URL.

```bash
docker run --rm akitaonrails/ai-memory:latest \
    install-mcp --client claude-desktop  --auth-token "$TOKEN" \
    --server-url "http://homelab:49374/mcp"
```

--------------------------------

### Install agent hooks for a specific user

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/users.md

Wire a user's agent installation to their authentication token using the `install-hooks` command. The `--as-user` flag is for metadata and verification; the `--auth-token` specifies the actual token used for authentication.

```bash
$ ai-memory install-hooks --apply --agent claude-code \
    --as-user alice --auth-token XGq...<43-chars>...zRm
[ai-memory] hooks installing for user: alice
✓ staged 5 hook script(s) → ...
```

--------------------------------

### Install MCP for Gemini CLI Client

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Installs the MCP configuration for the Gemini CLI client using Docker. Requires an authentication token and server URL.

```bash
docker run --rm akitaonrails/ai-memory:latest \
    install-mcp --client gemini-cli      --auth-token "$TOKEN" \
    --server-url "http://homelab:49374/mcp"
```

--------------------------------

### Install MCP for OpenClaw Client

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Installs the MCP configuration for the OpenClaw client using Docker. Requires an authentication token and server URL.

```bash
docker run --rm akitaonrails/ai-memory:latest \
    install-mcp --client openclaw        --auth-token "$TOKEN" \
    --server-url "http://homelab:49374/mcp"
```

--------------------------------

### Single Workspace, No Per-Repo Overrides Example

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md

Configures a single workspace for all directories under `$HOME`, useful for opting out of the default workspace entirely.

```text
~/.ai-memory.toml → workspace = "home"
```

--------------------------------

### Install Root Certificate on Windows

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/https-via-proxy.md

Installs the Caddy root certificate into the Windows 'Root' certificate store using certutil. Requires Administrator privileges.

```powershell
certutil -addstore -f "Root" caddy-root.crt
```

--------------------------------

### Install MCP for Antigravity CLI Client

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Installs the MCP configuration for the Antigravity CLI client using Docker. Requires an authentication token and server URL.

```bash
docker run --rm akitaonrails/ai-memory:latest \
    install-mcp --client antigravity-cli --auth-token "$TOKEN" \
    --server-url "http://homelab:49374/mcp"
```

--------------------------------

### Install ai-memory MCP Client for Antigravity CLI

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/mcp-install.md

This command installs the ai-memory MCP client for the Antigravity CLI. It's a one-shot command to set up the necessary configuration.

```bash
ai-memory install-mcp --client antigravity-cli
```

--------------------------------

### Install MCP Client Configuration

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/https-via-proxy.md

Installs the ai-memory MCP client configuration, specifying the server URL and authentication token. This is used by client applications to connect to the ai-memory service.

```bash
ai-memory install-mcp   --client claude-code --apply \
    --server-url "https://memory.example.com/mcp" --auth-token "$AI_MEMORY_AUTH_TOKEN"
```

--------------------------------

### Fresh Start (Docker Deploy)

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/lifecycle-ops.md

Wipes all AI Memory data and restarts the service in a Docker deployment. This involves stopping the container, removing data, and then starting the container again.

```bash
ssh homelab
cd ~/deploy/ai-memory
docker compose down
sudo rm -rf /var/opt/docker/utils/ai-memory/data/*
docker compose up -d
```

--------------------------------

### Install MCP Client via CLI

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/mcp-install.md

This command installs an MCP client using the ai-memory CLI. Replace 'gemini-cli' with the desired client name such as 'cursor', 'claude-desktop', 'openclaw', 'pi|omp', or 'antigravity-cli'.

```bash
ai-memory install-mcp --client gemini-cli
```

--------------------------------

### Manage User-Level Service with systemd

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Reload systemd, enable and start the user ai-memory service, and view its status and logs.

```bash
systemctl --user daemon-reload
systemctl --user enable --now ai-memory.service
systemctl --user status ai-memory.service
journalctl --user -u ai-memory.service -f
```

--------------------------------

### Manage System-Level Service with systemd

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Reload systemd, enable and start the system-wide ai-memory service, and view its status and logs.

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now ai-memory.service
sudo systemctl status ai-memory.service
journalctl -u ai-memory.service -f
```

--------------------------------

### TOML Configuration for Authentication

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/users.md

Example TOML configuration block for setting up authentication, including `token_pepper`, `root_username`, `root_email`, and `root_name`.

```toml
[auth]
# ... your existing settings (bearer_token, etc.) ...
token_pepper = "<paste-the-generated-pepper-here>"
root_username = "boss"     # optional; enables root-token attribution
root_email    = "boss@..." # optional
root_name     = "Boss"     # optional
```

--------------------------------

### Multi-client Example Configuration

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md

Illustrates how to configure .ai-memory.toml for multiple clients and personal projects. Each entry maps a directory to a specific workspace.

```text
~/projects/movvia/.ai-memory.toml     → workspace = "movvia"
~/projects/cliente-x/.ai-memory.toml  → workspace = "cliente-x"
~/personal/.ai-memory.toml            → workspace = "personal"
```

--------------------------------

### Run HTTP MCP Server

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Starts the HTTP MCP server using Docker Compose. This command is typically run once during the initial setup.

```bash
docker compose up -d
```

--------------------------------

### Exercise Binary - Initialize

Source: https://github.com/akitaonrails/ai-memory/blob/main/CLAUDE.md

Initializes the AI Memory application.

```bash
./target/debug/ai-memory init
```

--------------------------------

### Install Lifecycle Hooks for Gemini CLI

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/mcp-install.md

Applies lifecycle hooks for the Gemini CLI agent with ai-memory. This command ensures that events like session start and end are correctly captured.

```bash
ai-memory install-hooks --agent gemini-cli --apply
```

--------------------------------

### Bootstrap an Existing Project

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md

Seed an existing project's history and docs into the AI memory wiki. Use `--dry-run` to preview changes before applying them.

```bash
export AI_MEMORY_SERVER_URL="http://localhost:49374"
ai-memory bootstrap --dry-run
ai-memory bootstrap
```

--------------------------------

### Exercise Binary - Initialize with Custom Data Directory

Source: https://github.com/akitaonrails/ai-memory/blob/main/CLAUDE.md

Initializes the AI Memory application using a specified data directory.

```bash
AI_MEMORY_DATA_DIR=/tmp/x ./target/debug/ai-memory init
```

--------------------------------

### Install Cargo Tools

Source: https://github.com/akitaonrails/ai-memory/blob/main/CONTRIBUTING.md

Install cargo-deny and cargo-audit if they are not already installed on your system. These tools are used for checking dependency policies and security vulnerabilities.

```bash
cargo install cargo-deny cargo-audit
```

--------------------------------

### YAML Frontmatter Example

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/research-basic-memory.md

Example of YAML frontmatter used in Markdown files for metadata.

```yaml
---
title: Coffee Brewing Methods
type: note
permalink: coffee-brewing-methods
tags: [coffee, brewing]
---

```

--------------------------------

### Setup Agent Scripts and Configuration

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Extracts bundled scripts and prints configuration for setting up an agent. This is a one-shot command that requires specifying agent details, output path, and host prefix.

```bash
docker run --rm -v "$(pwd)":/data akitaonrails/ai-memory:latest setup-agent --agent <agent_name> --to <output_path> --host-prefix <host_prefix>
```

--------------------------------

### Memory Handoff Begin Tool

Source: https://github.com/akitaonrails/ai-memory/blob/main/CLAUDE.md

Initiates a handoff for the next session, creating a terse summary. Use this when wrapping up and saving context for the next session. Detail should be placed in 'open_questions' and 'next_steps'.

```bash
memory_handoff_begin
```

--------------------------------

### Semantic Grammar Convention Example

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/research-basic-memory.md

Provides examples of the human-authored semantic grammar conventions used for categories, tags, and relations.

```markdown
- [category] text #tag (context)
```

```markdown
- relation_type [[Target]]
```

--------------------------------

### Configure Single-User Workstation

Source: https://github.com/akitaonrails/ai-memory/blob/main/README.md

Set up AI Memory for a single-user workstation by initializing configuration and data directories, enabling the user service, and installing MCP and hooks.

```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
```

--------------------------------

### Build Project

Source: https://github.com/akitaonrails/ai-memory/blob/main/CLAUDE.md

Builds all components of the project. Run this to ensure the entire project compiles successfully.

```bash
cargo build --workspace
```

--------------------------------

### Install Hooks for OpenClaw Agent

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Installs hooks for the OpenClaw agent using Docker. Requires an authentication token and server URL.

```bash
docker run --rm akitaonrails/ai-memory:latest \
    install-hooks --agent openclaw       --auth-token "$TOKEN" \
    --server-url "http://homelab:49374"
```

--------------------------------

### Snapshot Before Risky Operation (Example)

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/lifecycle-ops.md

Demonstrates taking a backup before performing a risky operation and then restoring if necessary. Includes dynamic date formatting for the backup filename.

```bash
ai-memory backup --output-path "/tmp/ai-memory-$(date +%Y%m%d-%H%M).tar.gz"
# … do the risky thing …
# … oh no something broke …
docker compose down
ai-memory restore --from /tmp/ai-memory-2026-05-23-1530.tar.gz --confirm
docker compose up -d
```

--------------------------------

### Install Routing Snippet

Source: https://github.com/akitaonrails/ai-memory/blob/main/README.md

Command to install the routing snippet once. This ensures agents proactively call the correct MCP tool for prompts.

```bash
ai-memory install-instructions
```

--------------------------------

### Serve AI Memory with Custom UI Directory

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/frontend-api.md

Starts the AI Memory server, enabling the web UI and specifying the directory for your SPA's static files. Ensure the directory exists and contains an index.html file.

```bash
ai-memory serve \
    --transport http \
    --bind 127.0.0.1:49374 \
    --enable-web \
    --web-ui-dir /path/to/your-spa/dist
```

--------------------------------

### Install MCP Hooks

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Installs a configuration snippet for an existing hooks directory. This command is used to integrate AI Memory hooks into your system.

```bash
docker run --rm akitaonrails/ai-memory:latest install-hooks --agent <agent_name>
```

--------------------------------

### Serve AI Memory Wiki with Web UI

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md

Start the AI memory server with the web interface enabled. This command binds to a specific address and port.

```bash
ai-memory serve --transport http --bind 127.0.0.1:49374 --enable-web
```

--------------------------------

### Run Ollama qwen3:32b vs OpenRouter Kimi

Source: https://github.com/akitaonrails/ai-memory/blob/main/evals/README.md

Execute the evaluation harness comparing Ollama's qwen3:32b model against OpenRouter's Kimi model. Ensure OPENROUTER_API_KEY is set in your environment.

```bash
export OPENROUTER_API_KEY="sk-or-v1-..."

cargo run -p ai-memory-eval -- \
    --baseline-provider openai-compat \
    --baseline-base-url https://openrouter.ai/api/v1 \
    --baseline-model moonshotai/kimi-k2.6 \
    --baseline-api-key-env OPENROUTER_API_KEY \
    --candidate-provider openai-compat \
    --candidate-base-url http://192.168.0.90:11434/v1 \
    --candidate-model qwen3:32b \
    --candidate-api-key ollama-local
```

--------------------------------

### Install Root Certificate on Arch/openSUSE Linux

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/https-via-proxy.md

Installs the Caddy root certificate on Arch Linux or openSUSE using the 'trust anchor' command.

```bash
sudo trust anchor --store caddy-root.crt
```

--------------------------------

### Install Root Certificate on macOS

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/https-via-proxy.md

Installs the extracted Caddy root certificate into the macOS system keychain, enabling trust for Caddy-signed certificates.

```bash
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain caddy-root.crt
```

--------------------------------

### Agent Handoff Example

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md

Demonstrates how agents can pass context to each other using handoffs. The first agent exits, and the second agent in the same directory automatically picks up the context.

```text
$ claude
> Working on the auth refactor. JWT rotation is broken; trying session cookies.
[work for an hour]
> /exit

$ codex   # in the same directory, later
[SessionStart hook fetches the handoff; Codex sees it before your prompt.]
> Picking up: you were investigating session cookies as an alternative...
```

--------------------------------

### Docker Quick Start with GitHub Copilot

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Launches the AI Memory Docker container configured for GitHub Copilot. Requires prior login via 'ai-memory auth login copilot'.

```bash
ai-memory auth login copilot
docker run -d --name ai-memory \
    -p 127.0.0.1:49374:49374 \
    -v ai-memory-data:/data \
    -e AI_MEMORY_LLM_PROVIDER=copilot \
    akitaonrails/ai-memory:latest
```

--------------------------------

### Install Hooks for Antigravity CLI Agent

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Installs hooks for the Antigravity CLI agent using Docker. Requires an authentication token and server URL.

```bash
docker run --rm akitaonrails/ai-memory:latest \
    install-hooks --agent antigravity-cli --auth-token "$TOKEN" \
    --server-url "http://homelab:49374"
```

--------------------------------

### Install Hooks for Gemini CLI Agent

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Installs hooks for the Gemini CLI agent using Docker. Requires an authentication token and server URL.

```bash
docker run --rm akitaonrails/ai-memory:latest \
    install-hooks --agent gemini-cli     --auth-token "$TOKEN" \
    --server-url "http://homelab:49374"
```

--------------------------------

### Run Local Integration Test

Source: https://github.com/akitaonrails/ai-memory/blob/main/packaging/aur/README.md

Execute the manual distrobox harness from the repository root to test native Arch systemd packaging before publishing updates.

```bash
scripts/test-native-arch-systemd-distrobox.sh
```

--------------------------------

### Aggressive AliasChoices Aliasing Example

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/research-basic-memory.md

Demonstrates aggressive aliasing of parameter names using `AliasChoices` to absorb LLM variance. Examples from `write_note.py:31` and `search.py:574`.

```python
directory|folder|dir|path
```

```python
query|q|search|text
```

--------------------------------

### Install AI Memory CLI Wrapper for Docker

Source: https://github.com/akitaonrails/ai-memory/blob/main/README.md

Download and make executable the AI Memory CLI wrapper script, which runs the Dockerized binary. Ensure ~/.local/bin is in your PATH.

```bash
# 1. Install the ai-memory CLI wrapper (a ~3 KB 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"
```

--------------------------------

### Mono-repo with Grouped Packages Example

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md

Shows how to configure .ai-memory.toml for a mono-repository where packages are grouped under a single project. A closer marker file overrides outer ones.

```text
~/projects/movvia/.ai-memory.toml              → workspace = "movvia"
~/projects/movvia/pe-portais/.ai-memory.toml   → workspace = "movvia"
                                                  project   = "pe-portais"
```

--------------------------------

### Wide Tool Surface Example

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/research-basic-memory.md

Lists a subset of the approximately 25 tools available to agents, highlighting the cognitive load of selecting the correct tool.

```python
write_note/edit_note/move_note/delete_note/read_note/view_note/read_content/search/search_notes/build_context/recent_activity/list_directory/list_memory_projects/canvas/schema_*
```

--------------------------------

### Install AI Memory via AUR

Source: https://github.com/akitaonrails/ai-memory/blob/main/README.md

Use `yay` to install AI Memory from the Arch User Repository. Choose the prebuilt binary or build from source.

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

--------------------------------

### Setup Agent using Bind Mount for Claude Code

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Uses `setup-agent` with a bind mount to extract and render hooks in one step for the Claude Code agent. This method works when the container user's UID matches the host user's UID and may fail on rootless Docker or with `userns-remap`.

```bash
docker run --rm -v "$HOME/.ai-memory:/host" \
    akitaonrails/ai-memory:latest \
    setup-agent --agent claude-code --to /host/hooks \
        --host-prefix "$HOME/.ai-memory/hooks" \
        --server-url "http://homelab:49374" --auth-token "$TOKEN"
```

--------------------------------

### Install Root Certificate on Debian/Ubuntu Linux

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/https-via-proxy.md

Installs the Caddy root certificate on Debian-based or Ubuntu systems by copying it to the CA certificates directory and updating the trust store.

```bash
sudo cp caddy-root.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates
```

--------------------------------

### Run ai-memory CLI Commands on Windows

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/windows.md

After building, use these commands to initialize ai-memory and start the server. The server can be configured to use HTTP transport and bind to a specific address and port.

```powershell
target\debug\ai-memory.exe init
target\debug\ai-memory.exe serve --transport http --bind 127.0.0.1:49374
```

--------------------------------

### Build and Run AI Memory from Source

Source: https://github.com/akitaonrails/ai-memory/blob/main/docs/install.md

Builds and runs the AI Memory server from source code using Cargo. This is recommended for development or unsupported platforms. It includes initialization and serving commands.

```bash
git clone https://github.com/akitaonrails/ai-memory ~/.ai-memory
cd ~/.ai-memory
cargo build --release --workspace
./target/release/ai-memory init                       # one-time
./target/release/ai-memory serve --transport http \
    --bind 127.0.0.1:49374                            # MCP + hook HTTP server
```