Skip to content

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

Rust

M15: homelab deploy pattern + Kimi 2.6 via OpenRouter + config robustness

AkitaOnRails658a0bfae4ba
diff --git a/.gitignore b/.gitignore
index f5e685cc..c58e87e3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,11 @@
.env.local
/.local-data/
+# Homelab deploy config — committed as .example variants only.
+/bin/deploy.env
+/docker/docker-compose.prod.yml
+/docker/.env.production
+
# Editor / OS noise.
.DS_Store
*.tmp
diff --git a/README.md b/README.md
index 211b8ec0..198c7dfb 100644
--- a/README.md
+++ b/README.md
@@ -159,7 +159,7 @@ sensible defaults. Override with the corresponding env var.
| Setting | Default | Why this default | Override |
|---|---|---|---|
-| Anthropic LLM | `claude-sonnet-4-7` | Smart enough to summarise a session into coherent narrative; cheap enough to run on every session-end without thinking about it. Not a reasoning model — consolidation doesn't benefit from extended thinking. | `AI_MEMORY_LLM_MODEL` |
+| Anthropic LLM | `claude-sonnet-4-6` | Smart enough to summarise a session into coherent narrative; cheap enough to run on every session-end without thinking about it. Not a reasoning model — consolidation doesn't benefit from extended thinking. | `AI_MEMORY_LLM_MODEL` |
| OpenAI LLM | `gpt-4o-mini` | Closest OpenAI equivalent to the Sonnet tier in price/quality. | `AI_MEMORY_LLM_MODEL` |
| OpenAI embedding | `text-embedding-3-small` (1536-dim) | Best price/quality from OpenAI; 5× cheaper than `text-embedding-3-large` with marginal recall loss. | `AI_MEMORY_EMBEDDING_MODEL` + `AI_MEMORY_EMBEDDING_DIM` |
| Voyage embedding | `voyage-3` (1024-dim) | Voyage's current general-purpose recommendation. | same |
diff --git a/bin/deploy b/bin/deploy
new file mode 100755
index 00000000..9f71d513
--- /dev/null
+++ b/bin/deploy
@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Build + push + deploy ai-memory to a homelab Docker host.
+#
+# Reads SERVER, DEPLOY_DIR, and IMAGE from bin/deploy.env (which is
+# .gitignored — see bin/deploy.env.example for the template). The
+# script itself is host-agnostic; everything operator-specific lives
+# in that sourced file.
+#
+# Initial setup (one-time, before the first deploy):
+#
+# 1. Copy bin/deploy.env.example to bin/deploy.env and fill in
+# your homelab specifics.
+# 2. Copy docker/docker-compose.prod.yml.example to
+# docker/docker-compose.prod.yml; adjust ports / volumes if
+# needed.
+# 3. Copy docker/.env.production.example to docker/.env.production
+# and fill in API keys (LLM + embeddings).
+# 4. SSH into the homelab and create the deploy dir:
+# ssh "$SERVER" "sudo mkdir -p $DEPLOY_DIR && \
+# sudo chown $(whoami): $DEPLOY_DIR"
+# 5. scp the compose + env files up there:
+# scp docker/docker-compose.prod.yml "$SERVER:$DEPLOY_DIR/docker-compose.yml"
+# scp docker/.env.production "$SERVER:$DEPLOY_DIR/.env.production"
+# 6. Now `bin/deploy` works.
+#
+# See docs/deploy.md for the full setup walkthrough.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+ENV_FILE="$SCRIPT_DIR/deploy.env"
+
+if [[ ! -f "$ENV_FILE" ]]; then
+ cat >&2 <<EOF
+==> bin/deploy.env not found.
+
+This file holds your homelab-specific values (server, deploy dir,
+image tag) and is gitignored. Copy the template and fill it in:
+
+ cp bin/deploy.env.example bin/deploy.env
+ \$EDITOR bin/deploy.env
+
+Then re-run bin/deploy. See docs/deploy.md for details.
+EOF
+ exit 64
+fi
+
+# shellcheck disable=SC1090
+source "$ENV_FILE"
+
+: "${SERVER:?SERVER not set in bin/deploy.env}"
+: "${DEPLOY_DIR:?DEPLOY_DIR not set in bin/deploy.env}"
+: "${IMAGE:?IMAGE not set in bin/deploy.env}"
+
+SSH_OPTS=("-F" "/dev/null" "-o" "StrictHostKeyChecking=accept-new")
+CONTAINER_NAME="${CONTAINER_NAME:-ai-memory}"
+
+cd "$REPO_ROOT"
+
+echo "==> Building Docker image: $IMAGE"
+docker build -t "$IMAGE" -f docker/Dockerfile .
+
+echo "==> Pushing image to registry..."
+docker push "$IMAGE"
+
+echo "==> Deploying to $SERVER:$DEPLOY_DIR"
+# `docker compose pull` fetches the new tag; `down` stops the old
+# container; `up -d` starts the new one with the new tag. We don't
+# `docker compose build` on the server because the binary travels
+# baked into the image.
+ssh "${SSH_OPTS[@]}" "$SERVER" "cd $DEPLOY_DIR && \
+ docker compose pull && \
+ docker compose down && \
+ docker compose up -d"
+
+echo "==> Waiting for container to come up..."
+sleep 3
+ssh "${SSH_OPTS[@]}" "$SERVER" \
+ "docker inspect --format='{{.State.Status}} ({{.State.Health.Status}})' $CONTAINER_NAME"
+
+echo "==> Deploy complete."
+echo
+echo " Container: $CONTAINER_NAME on $SERVER"
+echo " Probe MCP: curl ${SERVER#*@}:49374/mcp"
diff --git a/bin/deploy.env.example b/bin/deploy.env.example
new file mode 100644
index 00000000..3c41c0fc
--- /dev/null
+++ b/bin/deploy.env.example
@@ -0,0 +1,21 @@
+# Homelab-specific deploy configuration.
+#
+# Copy this file to `bin/deploy.env` and fill in your values. The real
+# `bin/deploy.env` is gitignored — never commit it.
+
+# SSH target (user@host or just host if you've set it up in ~/.ssh/config).
+
+# Absolute path on the homelab where docker-compose.yml + .env.production live.
+# The deploy script runs `docker compose pull/down/up` inside this dir.
+DEPLOY_DIR="/var/opt/docker/utils/ai-memory"
+
+# Image tag to build + push + pull. Make sure the Docker host can pull
+# from wherever you push to (Docker Hub, GHCR, your own registry).
+# Default: the official published image. Change to your own fork if
+# you're building from source.
+IMAGE="akitaonrails/ai-memory:latest"
+
+# Optional: override the container name if your docker-compose.yml
+# uses something other than the default `ai-memory`.
+# CONTAINER_NAME="ai-memory"
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index b741dfa4..fac0bc09 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -235,7 +235,7 @@ pub struct LlmTestArgs {
/// Provider to test.
#[arg(long, value_enum)]
pub provider: LlmProviderChoice,
- /// Model identifier (e.g. `claude-sonnet-4-7`, `gpt-4o-mini`, `llama3.1:8b`).
+ /// Model identifier (e.g. `claude-sonnet-4-6`, `gpt-4o-mini`, `llama3.1:8b`).
#[arg(long)]
pub model: String,
/// Prompt to send.
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rs
index c1c06470..b03017f0 100644
--- a/crates/ai-memory-cli/src/config.rs
+++ b/crates/ai-memory-cli/src/config.rs
@@ -16,8 +16,16 @@ use figment::{
use serde::{Deserialize, Serialize};
/// Top-level runtime configuration.
+///
+/// `deny_unknown_fields` is intentionally NOT set: figment's
+/// `Env::prefixed("AI_MEMORY_")` pulls every env var with that prefix
+/// (including ones meant for the LLM/embedding factory:
+/// `AI_MEMORY_LLM_MODEL`, `AI_MEMORY_EMBEDDING_DIM`, …). Those keys are
+/// read directly via `std::env::var` in their own modules; they don't
+/// map into `Config` fields, but figment doesn't know that. Strict
+/// rejection here would crash on every deploy that uses LLM env vars.
#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(deny_unknown_fields, default)]
+#[serde(default)]
pub struct Config {
/// Root data directory holding `wiki/`, `raw/`, `db/`, `models/`, `logs/`.
pub data_dir: PathBuf,
diff --git a/crates/ai-memory-consolidate/src/consolidator.rs b/crates/ai-memory-consolidate/src/consolidator.rs
index 397a8ab4..d2faf73b 100644
--- a/crates/ai-memory-consolidate/src/consolidator.rs
+++ b/crates/ai-memory-consolidate/src/consolidator.rs
@@ -354,7 +354,13 @@ fn build_request(
role: Role::User,
content: buf,
}],
- max_tokens: 1500,
+ // Sized for reasoning models too (Kimi / o3-style): each
+ // consolidation call may burn ~2k tokens on hidden reasoning
+ // before any visible output. With 4000 we leave ~2000 for the
+ // actual ConsolidatedPage JSON, which is plenty for our
+ // ~5 KB max body_markdown. Non-reasoning models stop early
+ // and don't pay extra for the higher cap.
+ max_tokens: 4000,
temperature: Some(0.2),
}
}
diff --git a/crates/ai-memory-consolidate/src/lint.rs b/crates/ai-memory-consolidate/src/lint.rs
index 3bd6666e..5278105b 100644
--- a/crates/ai-memory-consolidate/src/lint.rs
+++ b/crates/ai-memory-consolidate/src/lint.rs
@@ -191,7 +191,10 @@ async fn contradiction_pass(
role: Role::User,
content: prompt,
}],
- max_tokens: 2000,
+ // Same reasoning-model headroom rule as the consolidator —
+ // reasoning models can spend ~2k tokens before any visible
+ // findings JSON appears.
+ max_tokens: 4000,
temperature: Some(0.1),
};
let report: LintReport = complete_structured(&*provider, request).await?;
diff --git a/crates/ai-memory-hooks/src/payload.rs b/crates/ai-memory-hooks/src/payload.rs
index 008e2ac0..b8c961e5 100644
--- a/crates/ai-memory-hooks/src/payload.rs
+++ b/crates/ai-memory-hooks/src/payload.rs
@@ -221,12 +221,12 @@ mod tests {
let raw = serde_json::json!({
"session_id": "abc-123",
"cwd": "/tmp/x",
- "model": "claude-sonnet-4-7"
+ "model": "claude-sonnet-4-6"
});
let env = HookEnvelope::from_query_and_body(q, raw);
assert_eq!(env.event, HookEvent::SessionStart);
assert_eq!(env.session_id.as_deref(), Some("abc-123"));
assert_eq!(env.cwd.as_deref(), Some("/tmp/x"));
- assert_eq!(env.title_hint.as_deref(), Some("claude-sonnet-4-7"));
+ assert_eq!(env.title_hint.as_deref(), Some("claude-sonnet-4-6"));
}
}
diff --git a/crates/ai-memory-llm/src/factory.rs b/crates/ai-memory-llm/src/factory.rs
index 159fa79b..7c730447 100644
--- a/crates/ai-memory-llm/src/factory.rs
+++ b/crates/ai-memory-llm/src/factory.rs
@@ -63,8 +63,29 @@ pub fn provider_from_env() -> LlmResult<Option<ProviderConfig>> {
},
Err(_) => return Ok(None),
};
- let model = std::env::var("AI_MEMORY_LLM_MODEL")
- .map_err(|_| LlmError::NotConfigured("AI_MEMORY_LLM_MODEL".into()))?;
+ // Sensible defaults per provider so the operator can set just the
+ // provider env var and get a reasonable model. Override via
+ // `AI_MEMORY_LLM_MODEL`. We pick the cheapest model that is still
+ // smart enough to summarise a session into a coherent wiki page;
+ // reasoning models are deliberately avoided in the defaults
+ // because consolidation runs frequently and silently.
+ let model = match std::env::var("AI_MEMORY_LLM_MODEL") {
+ Ok(s) if !s.is_empty() => s,
+ _ => match provider {
+ ProviderChoice::Anthropic => "claude-sonnet-4-6".to_string(),
+ ProviderChoice::OpenAi => "gpt-4o-mini".to_string(),
+ // openai-compat covers Ollama / vLLM / LM Studio / OpenRouter.
+ // What's available depends entirely on the user's setup, so
+ // refuse to start without an explicit choice.
+ ProviderChoice::OpenAiCompat => {
+ return Err(LlmError::NotConfigured(
+ "AI_MEMORY_LLM_MODEL must be set explicitly for openai-compat \
+ (no safe default for self-hosted / aggregator endpoints)"
+ .into(),
+ ));
+ }
+ },
+ };
let base_url = std::env::var("AI_MEMORY_LLM_BASE_URL").ok();
let api_key = match provider {
ProviderChoice::Anthropic => std::env::var("ANTHROPIC_API_KEY")
diff --git a/docker/.env.production.example b/docker/.env.production.example
new file mode 100644
index 00000000..0be67acc
--- /dev/null
+++ b/docker/.env.production.example
@@ -0,0 +1,52 @@
+# Production env vars for ai-memory.
+#
+# Copy to docker/.env.production, fill in real values, then scp it to
+# your homelab alongside docker-compose.yml. The live copy is
+# gitignored; never commit it.
+#
+# The container reads these via env_file (see docker-compose.prod.yml.example).
+# Everything is optional — without any LLM/embedding keys, ai-memory
+# still runs in pure-FTS5 mode with rule-based session summaries.
+
+# -- Workspace + project labels stamped on every observation -----------
+# Match whatever name you want for your homelab knowledge silo. These
+# strings are user-visible labels, not paths.
+# AI_MEMORY_WORKSPACE=default
+# AI_MEMORY_PROJECT=homelab
+
+# -- LLM provider ------------------------------------------------------
+# Pick one of: anthropic | openai | openai-compat
+# anthropic -> Anthropic Messages API (needs ANTHROPIC_API_KEY)
+# openai -> OpenAI Chat Completions (needs OPENAI_API_KEY)
+# openai-compat -> Any OpenAI-compatible endpoint: Ollama, vLLM,
+# LM Studio, OpenRouter, Together, etc. Set
+# AI_MEMORY_LLM_BASE_URL + LLM_API_KEY.
+#
+# Without AI_MEMORY_LLM_PROVIDER set, consolidation falls back to
+# rule-based summaries (no LLM cost; lower-signal handoffs).
+AI_MEMORY_LLM_PROVIDER=openai-compat
+AI_MEMORY_LLM_BASE_URL=https://openrouter.ai/api/v1
+AI_MEMORY_LLM_MODEL=moonshotai/kimi-k2.6
+
+# Provider-specific API keys. Set whichever matches your
+# AI_MEMORY_LLM_PROVIDER above.
+# ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+LLM_API_KEY=sk-or-v1-REPLACE_ME
+
+# -- Embeddings (hybrid retrieval) -------------------------------------
+# Optional. When set, ai-memory computes + stores embeddings for every
+# page and uses Reciprocal Rank Fusion to combine FTS5 with vector
+# cosine. Better recall on paraphrased queries; needs a key.
+#
+# Pick: openai | voyage
+AI_MEMORY_EMBEDDING_PROVIDER=openai
+AI_MEMORY_EMBEDDING_MODEL=text-embedding-3-small
+AI_MEMORY_EMBEDDING_DIM=1536
+OPENAI_API_KEY=sk-REPLACE_ME
+# VOYAGE_API_KEY=...
+
+# -- Listen address inside the container -------------------------------
+# The compose file maps the host port to this. Don't change unless
+# you also change the compose port mapping.
+# AI_MEMORY_BIND=0.0.0.0:49374
diff --git a/docker/Dockerfile b/docker/Dockerfile
index 5f4e33c2..f7eac6c2 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -31,8 +31,8 @@ COPY --from=builder /usr/local/bin/ai-memory /usr/local/bin/ai-memory
USER ai-memory
ENV AI_MEMORY_DATA_DIR=/data
WORKDIR /data
-EXPOSE 7777
+EXPOSE 49374
HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
CMD ["/usr/local/bin/ai-memory", "status"]
ENTRYPOINT ["/usr/local/bin/ai-memory"]
-CMD ["serve", "--transport", "http", "--bind", "0.0.0.0:7777"]
+CMD ["serve", "--transport", "http", "--bind", "0.0.0.0:49374"]
diff --git a/docker/docker-compose.prod.yml.example b/docker/docker-compose.prod.yml.example
new file mode 100644
index 00000000..acfe21d5
--- /dev/null
+++ b/docker/docker-compose.prod.yml.example
@@ -0,0 +1,47 @@
+# Production docker-compose template for ai-memory on a homelab host.
+#
+# Copy to docker/docker-compose.prod.yml, adjust if you want, then
+# scp it to your homelab as docker-compose.yml in the deploy dir.
+# The .example variant is committed; the live copy is gitignored.
+#
+# Differences from docker/docker-compose.yml (the local-dev compose):
+# - References an image from a registry instead of building inline.
+# - Binds to 0.0.0.0 so the LAN can reach the MCP endpoint.
+# - Reads secrets from .env.production rather than inlining them.
+# - Volume mounts a host path (under /var/opt/docker/...) so backups
+# can rsync the wiki + db without going through Docker volume APIs.
+
+name: ai-memory
+
+services:
+ ai-memory:
+ image: akitaonrails/ai-memory:latest
+ container_name: ai-memory
+ restart: unless-stopped
+ user: "1000:1000"
+ # openSUSE MicroOS / Fedora / RHEL etc. enforce SELinux on bind
+ # mounts by default; without this the container can't read its
+ # own /data dir. Safe on hosts that don't enforce SELinux (it's
+ # a no-op there).
+ security_opt:
+ - label:disable
+ ports:
+ # LAN-accessible. Behind your home firewall, this is fine. If
+ # you want loopback-only (server-local clients only), change to
+ # "127.0.0.1:49374:49374".
+ - "0.0.0.0:49374:49374"
+ volumes:
+ # Data lives on the host. Back up with: rsync, btrfs snapshots,
+ # restic — anything that can read this directory.
+ - /var/opt/docker/utils/ai-memory/data:/data
+ env_file:
+ - .env.production
+ environment:
+ # Tracing filter; promote modules to debug here without rebuilding.
+ - RUST_LOG=ai_memory=info,ai_memory_store=info,ai_memory_wiki=info,ai_memory_mcp=info,tracing_appender=warn
+ healthcheck:
+ test: ["CMD", "/usr/local/bin/ai-memory", "status"]
+ interval: 30s
+ timeout: 5s
+ retries: 3
+ start_period: 5s
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index f914ec03..87c452c9 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -241,7 +241,7 @@ hard_delete_after_days = 180
**LLM provider env** (opt-in):
```
AI_MEMORY_LLM_PROVIDER anthropic | openai | openai-compat
-AI_MEMORY_LLM_MODEL e.g. claude-sonnet-4-7
+AI_MEMORY_LLM_MODEL e.g. claude-sonnet-4-6
ANTHROPIC_API_KEY / OPENAI_API_KEY / LLM_API_KEY
AI_MEMORY_LLM_BASE_URL for openai-compat (Ollama, vLLM)
```
diff --git a/docs/deploy.md b/docs/deploy.md
new file mode 100644
index 00000000..d3b05eca
--- /dev/null
+++ b/docs/deploy.md
@@ -0,0 +1,175 @@
+# Deploying ai-memory to a homelab
+
+This walks through the pattern documented in `bin/deploy`. The end
+state is: a long-lived ai-memory container on your homelab host,
+reachable on your LAN at `http://<host>:49374/mcp`, configured with
+your LLM/embedding API keys, with backups handled by whatever you
+already use for `/var/opt/docker/...`.
+
+## What gets committed vs. what stays local
+
+The repo ships **templates only**. The real files with your homelab
+specifics and API keys live next to them with the `.example` suffix
+stripped, and are gitignored.
+
+| Committed (template) | Live (gitignored) | What it holds |
+|---|---|---|
+| `bin/deploy` | (the script itself; safe to commit) | The build/push/restart logic |
+| `bin/deploy.env.example` | `bin/deploy.env` | `SERVER`, `DEPLOY_DIR`, `IMAGE` |
+| `docker/docker-compose.prod.yml.example` | `docker/docker-compose.prod.yml` | Image tag, port mapping, volume path |
+| `docker/.env.production.example` | `docker/.env.production` | LLM + embedding API keys |
+
+`.gitignore` excludes the live files. If you ever see one staged,
+something has drifted — unstage before committing.
+
+## First-time setup (one-time)
+
+```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
+```
+
+After step 4, the container should be running. Verify:
+
+```bash
+curl http://<homelab>:49374/mcp
+# Expect a JSON-RPC error (which means the port is reachable and the
+# server is responding). "Connection refused" means the container
+# isn't up or the port mapping is wrong.
+
+ssh "$SERVER" "docker inspect --format='{{.State.Health.Status}}' ai-memory"
+# Expect: healthy
+```
+
+## Routine deploys
+
+After the first-time setup, every subsequent deploy is just:
+
+```bash
+bin/deploy
+```
+
+It builds the image locally, pushes to your registry, pulls on the
+homelab, and restarts. The compose file + env file on the homelab are
+unchanged between deploys; if you ever need to change them, scp the
+new copy + re-run `bin/deploy`.
+
+## Updating API keys
+
+```bash
+$EDITOR docker/.env.production
+scp docker/.env.production "$SERVER:$DEPLOY_DIR/.env.production"
+ssh "$SERVER" "cd $DEPLOY_DIR && docker compose up -d"
+```
+
+`docker compose up -d` reads the env file and recreates the container
+with the new values. No rebuild needed.
+
+## LLM provider choices
+
+The `.env.production.example` defaults to **Kimi 2.6 via OpenRouter**
+(openai-compat transport, $0.73/$3.49 per million tokens). Reasonable
+alternatives:
+
+| Provider | Model | Approx. cost / consolidation | Notes |
+|---|---|---|---|
+| openai-compat (OpenRouter) | `moonshotai/kimi-k2.6` | ~$0.013 | Reasoning model; latency ~2-3 min per consolidation. Fine because consolidation is fire-and-forget. |
+| anthropic | `claude-sonnet-4-6` | ~$0.02 | Faster (~15s), not a reasoning model. Smarter on average but more expensive. |
+| openai | `gpt-4o-mini` | ~$0.002 | Cheapest mainstream option. Decent quality. |
+| openai-compat (Ollama) | `qwen2.5-coder:14b` | $0 | Self-hosted. Set `AI_MEMORY_LLM_BASE_URL=http://host.docker.internal:11434/v1`. Quality depends on the model. |
+
+ai-memory's consolidator uses OpenAI's `json_schema` strict mode for
+structured output. Most modern models honour this, but if you switch
+to a niche local model, run a quick `ai-memory llm-test` (with a
+structured prompt) before trusting it.
+
+## Backups
+
+The data dir is whatever you mounted in `docker-compose.prod.yml`
+(default: `/var/opt/docker/utils/ai-memory/data/`). It contains:
+
+```
+data/
+├── wiki/ # markdown — back up with rsync or git push to a remote
+├── raw/ # immutable session log archive
+├── db/ # memory.sqlite (FTS5 + page_embeddings)
+├── logs/ # daily rolling tracing
+└── models/ # reserved for future local embedders
+```
+
+For point-in-time consistency:
+
+```bash
+ssh "$SERVER" "docker exec ai-memory /usr/local/bin/ai-memory backup --to /data/snapshot-$(date +%F).tar.gz"
+scp "$SERVER:$DEPLOY_DIR/data/snapshot-$(date +%F).tar.gz" ./backups/
+```
+
+The `ai-memory backup` command uses SQLite's online backup API so
+writes during the snapshot are coherent.
+
+## Rolling back
+
+```bash
+ssh "$SERVER" "cd $DEPLOY_DIR && \
+ docker tag $IMAGE $IMAGE-rollback && \
+ docker pull $IMAGE@sha256:<old-digest>"
+ssh "$SERVER" "cd $DEPLOY_DIR && docker compose up -d"
+```
+
+The simplest rollback is to bring back an older image by digest. We
+don't ship a `bin/rollback` because the right way is to keep the
+prior image tag handy before each deploy (Docker Hub keeps every
+push by digest for free).
+
+## Watching logs
+
+```bash
+ssh "$SERVER" "docker logs -f --tail 100 ai-memory"
+```
+
+Or browse the daily rolling logs on the host:
+
+```bash
+ssh "$SERVER" "ls -la $DEPLOY_DIR/data/logs/"
+ssh "$SERVER" "tail -100 $DEPLOY_DIR/data/logs/ai-memory.log.$(date +%F)"
+```
+
+## Troubleshooting
+
+- **`Connection refused`** on `curl http://<host>:49374/mcp`: the
+ container isn't up, or the port mapping is bound to `127.0.0.1`
+ instead of `0.0.0.0`. Check `docker ps` on the homelab.
+- **`unhealthy`** status: the container is running but its embedded
+ `ai-memory status` healthcheck is failing. Most likely the data
+ dir's permissions don't match the container's user (uid 1000). Fix
+ with `sudo chown -R 1000:1000 $DEPLOY_DIR/data` on the host.
+- **Embedding mismatch refusing to start**: ai-memory refuses to boot
+ when the configured `(provider, model, dim)` for embeddings doesn't
+ match the stored pages' embeddings. Either revert the change or run
+ `ai-memory embed --reembed` (after starting with the old config or
+ doing a manual SQL fix) to migrate.
+- **Container restart loop**: check
+ `docker logs ai-memory` — the `ai-memory starting` line at the top
+ reports the resolved config; a missing required env var (e.g.
+ `LLM_API_KEY` with `openai-compat` selected but no model) will fail
+ here with a clear error.