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/.gitignoreindex 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*.tmpdiff --git a/README.md b/README.mdindex 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/deploynew file mode 100755index 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.examplenew file mode 100644index 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).+SERVER="[email protected]"++# 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.examplenew file mode 100644index 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:49374diff --git a/docker/Dockerfile b/docker/Dockerfileindex 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-memoryUSER ai-memoryENV AI_MEMORY_DATA_DIR=/dataWORKDIR /data-EXPOSE 7777+EXPOSE 49374HEALTHCHECK --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.examplenew file mode 100644index 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: 5sdiff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 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-6ANTHROPIC_API_KEY / OPENAI_API_KEY / LLM_API_KEYAI_MEMORY_LLM_BASE_URL for openai-compat (Ollama, vLLM)```diff --git a/docs/deploy.md b/docs/deploy.mdnew file mode 100644index 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.