/nowledge-mem-docker

name: nowledge-mem-docker
description: Install, check on, or upgrade a self-hosted Nowledge Mem server (the headless Docker deployment) using the `nmemctl` lifecycle controller. Use this whenever the user mentions running their own Nowledge Mem instance, self-hosting Mem on a NAS, VPS, homelab, or server, deploying `nowledgelabs/mem` from Docker Hub, troubleshooting their Mem container, or upgrading a Mem server to a newer version. Trigger even when the user says "my Mem server", "self-hosted Mem", "the docker version of Mem", "memory server on my Synology / Proxmox / Raspberry Pi", or just describes a container that's at `docker.io/nowledgelabs/mem` without naming the product. Do NOT trigger for the Mem desktop app, Mem Cloud, or anything that doesn't touch the operator's own server.

Nowledge Mem — self-hosted Docker maintenance

You are helping the user run **their own** Nowledge Mem server — the headless Docker deployment that lives behind the desktop app and Mem clients. The server image is `docker.io/nowledgelabs/mem`. The community repo ships a `docker compose` stack and a lifecycle controller called `nmemctl`.

Your job is to take care of the routine boring parts of running this server, so the user doesn't have to remember which command goes inside or outside the container. **You do not touch anything destructive** — those stay with the human (see the "Handoff" section below).

Mental model — the two CLIs

There are two command-line tools, and they look similar on purpose:

• **`./nmemctl`** — outside the container, in the deploy directory. Controls the **container lifecycle** (up, status, logs, upgrade). Same idea as `systemctl` or `kubectl`. **This is the one you'll use most.**
• **`nmem`** — inside the container, runs the Python application CLI. Handles data operations. You normally reach it via `./nmemctl key`, `./nmemctl license`, etc., which forward to it. You rarely need to `docker compose exec` it directly.

If you find yourself wanting to write `docker compose exec mem nmem ...`, stop — there's almost certainly an `./nmemctl` verb for what you want.

Triage — where is the user?

Before doing anything, figure out which of these three situations applies:

Path A — Fresh install (no deploy exists yet)

The user wants to set Mem up on this server for the first time. Signals: they haven't mentioned a clone before; `community/docker/compose.yaml` isn't on disk; `docker ps` shows no `nowledge-mem` container.

Run this exact sequence:

# 1. Get the deploy stack (idempotent; updates to latest if already cloned)
git clone https://github.com/nowledge-co/community.git ~/nowledge-mem || \
  git -C ~/nowledge-mem pull --ff-only

# 2. Bring it up — nmemctl will wait for /livez, print the API key, and show the URL
cd ~/nowledge-mem/community/docker
./nmemctl up

That's the whole install. `nmemctl up` is idempotent — safe to rerun.

The output includes:

• An **Access Anywhere API key** (a long string starting with `nmem_`). The user pastes this into the desktop / web client when prompted.
• The **URL** to open (typically `http://<host-ip>:14242/app`).
• License status (will say "Free / 0 / 20 memories" until activated).

Hand the API key to the user verbatim. **Do not save it anywhere** — it lives in a `mode 0600` file at `./config/co.nowledge.mem.desktop/remote-access.json` next to the compose file on the host (mounted at `/etc/nowledge-mem/co.nowledge.mem.desktop/remote-access.json` inside the container). The user only needs to see it once.

If the user wants TLS (a real domain with HTTPS), do **not** improvise. Tell them:

> "I can enable TLS by overlaying `compose.tls.yaml` once you've pointed a DNS record at this host. Want me to walk you through that? You'll need a domain name, ports 80/443 open, and Docker Compose v2.24.4+."

Then read `community/docker/README.md` (in the cloned repo) for the TLS section and follow it.

Path B — Maintenance (server already running)

The user wants to know how their server is doing, see logs, look up the API key again, etc. Signals: `docker ps` shows `nowledge-mem` already running; the user says things like "is my server healthy", "what's running", "show me the logs".

**Finding the deploy directory.** Different operators install in different places. Path A uses `~/nowledge-mem/` as a sensible default, but on existing installs you'll need to discover the actual location. In order of cost:

# 1. Cheapest: ask docker where the compose project lives
docker inspect nowledge-mem --format '{{ index .Config.Labels "com.docker.compose.project.working_dir" }}'

# 2. Fall back: find a compose.yaml that defines a 'mem' service
find ~ -maxdepth 5 -name compose.yaml -path '*/community/docker/*' 2>/dev/null

# 3. Worst case: ask the user "where did you clone community/docker/?"

Once located, `cd` there and run:

./nmemctl status

`status` prints the container state, `/livez` health, license tier, image version, the current API key, and the web URL. Most "is everything ok?" questions are answered by this one command.

Other safe operations:

./nmemctl logs --tail 100      # recent server logs
./nmemctl logs -f              # live tail; use --no-color in scripts
./nmemctl key                  # print the current API key (read-only)
./nmemctl license              # show license tier + activation status
./nmemctl version              # image tag + binary version
./nmemctl restart              # restart the container, data preserved

`./nmemctl restart` IS safe to run autonomously — it preserves all data and is the standard recovery move for "the server feels stuck". Always print the `status` output afterwards to confirm `/livez` is back.

**Reading version output.** `./nmemctl version` prints two lines:

image:   docker.io/nowledgelabs/mem:0.8.4-rc5
binary:  0.8.4

These can legitimately differ. `image:` is the docker tag the operator pulled; `binary:` is what the Python application rep