nowledge-mem-docker

Nowledge Mem — セルフホスト可能な Docker の運用保守

ユーザーが自身の Nowledge Mem サーバー（デスクトップアプリや Mem クライアントの背後で動作する、ヘッドレスの Docker デプロイメント）を運用できるよう支援します。サーバーイメージは docker.io/nowledgelabs/mem です。コミュニティリポジトリには docker compose スタックと、ライフサイクルコントローラー nmemctl が含まれています。

このサーバーの運用に伴う、日常的で面倒な作業を引き受け、コンテナの内外でどのコマンドを実行すべきかユーザーが覚えなくて済むようにしてください。破壊的な操作には一切手を付けません。そうした操作は人間が担当します（以下の「引き継ぎ」セクションを参照してください）。

考え方 — 2 つの CLI

コマンドラインツールは 2 つあります。意図的に似た名前になっています。

• ./nmemctl — コンテナの外、デプロイディレクトリで実行します。コンテナのライフサイクル（起動、状態確認、ログ、アップグレード）を管理します。systemctl や kubectl と同じようなものです。主に使うのはこちらです。
• nmem — コンテナ内で Python アプリケーションの CLI を実行します。データ操作を扱います。通常は ./nmemctl key、./nmemctl license などを使って呼び出し、コマンドが転送されます。直接 docker compose exec を実行する必要はほとんどありません。

docker compose exec mem nmem ... と入力したくなったら、そこで止めてください。やりたい操作に対応する ./nmemctl のサブコマンドが、ほぼ間違いなくあります。

切り分け — ユーザーの状況を確認する

何かを行う前に、次の 3 つの状況のどれに当てはまるかを確認してください。

パス A — 新規インストール（デプロイがまだ存在しない）

ユーザーは、このサーバーに初めて Mem をセットアップしようとしています。該当する兆候：以前にクローンについて言及していない、community/docker/compose.yaml がディスク上にない、docker ps に nowledge-mem コンテナが表示されない。

次の手順をこの順番で正確に実行してください。

# 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

インストールはこれで完了です。nmemctl up は冪等なので、再実行しても安全です。

出力には次の情報が含まれます。

• Access Anywhere API key（nmem_ で始まる長い文字列）。ユーザーは、入力を求められたときにこれをデスクトップ／ウェブクライアントに貼り付けます。
• 開くURL（通常は http://<host-ip>:14242/app）。
• ライセンスの状態（有効化されるまでは「Free / 0 / 20 memories」と表示されます）。

API キーは、文字列を一切変更せずにユーザーへ渡してください。どこにも保存しないでください。ホスト上の compose ファイルと同じ場所にある mode 0600 のファイル ./config/co.nowledge.mem.desktop/remote-access.json に保存されます（コンテナ内では /etc/nowledge-mem/co.nowledge.mem.desktop/remote-access.json にマウントされます）。ユーザーがキーを確認するのは一度だけで十分です。

ユーザーが TLS（HTTPS に対応する実ドメイン）を希望する場合、独自の判断で手順を変えないでください。次のように伝えてください。

「このホストを指す DNS レコードを設定したら、compose.tls.yaml を重ねて TLS を有効にできます。設定手順をご案内しましょうか？ドメイン名、ポート 80／443 の開放、Docker Compose v2.24.4+ が必要です。」

その後、クローンしたリポジトリ内の community/docker/README.md を読み、TLS のセクションに従ってください。

パス B — メンテナンス（サーバーはすでに実行中）

ユーザーは、サーバーの状態やログを確認したり、API キーをもう一度調べたりしたいと考えています。兆候：docker ps に nowledge-mem がすでに実行中と表示される、または「サーバーは正常ですか」「何が実行中ですか」「ログを見せて」といった質問をする。

デプロイディレクトリの特定。 オペレーターによってインストール先は異なります。パス A では妥当なデフォルトとして ~/nowledge-mem/ を使用していますが、既存のインストールでは実際の場所を特定する必要があります。手間が少ない順に：

# 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/?"

場所がわかったら、そこに cd して次を実行します。

./nmemctl status

status は、コンテナーの状態、/livez のヘルス状態、ライセンス階層、イメージのバージョン、現在の API キー、Web URL を表示します。「すべて問題ありませんか？」という質問のほとんどには、このコマンドだけで答えられます。

その他の安全な操作：

./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 は自律的に実行しても安全です。すべてのデータを保持し、「サーバーが応答しなくなったようです」という場合の標準的な復旧手段です。実行後は必ず status の出力を表示し、/livez が復旧したことを確認してください。

バージョン出力の読み取り。 ./nmemctl version は次の 2 行を表示します。

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

これらの値が異なるのは正当な場合があります。image: はオペレーターが取得した Docker タグです。binary: は Python アプリケーションが自身のバージョンとして報告する値（pyproject.toml に記載）です。0.8.4-rc1 のようなプレリリースタグは、サフィックスがアプリケーションのバージョンに含まれないため、同じ基本バージョンの binary: 0.8.4 に対応します。値に食い違いがある場合：

• image と binary の基本バージョンが一致している（0.8.4-rc5 と 0.8.4 など）→ 問題ありません。オペレーターは今後安定版としてリリースされるバージョンのプレリリースを使用しています。中立的に説明し、求められていないのに「アップグレード」を勧めないでください。
• image がプレリリース表記のないセマンティックバージョンで、binary と異なる → 何らかの問題が発生しています（例：新しいイメージに対して古いコンテナーが動作している）。この不一致をユーザーに伝えてください。

パス C — アップグレード（新しいバージョンに移行）

ユーザーは現在のバージョンから新しいバージョンに移行したいと考えています。兆候：「新しいバージョンはありますか」「Mem を X にアップグレードして」「リリースノートで 0.8.5 を見ました」。

./nmemctl version                       # confirm current image tag first
./nmemctl upgrade 0.8.5                 # pull + bump compose.yaml + recreate

nmemctl upgrade は、デフォルトではプレリリースタグ（0.8.5-rc1 のように - サフィックスが付いたもの）を拒否します。これは意図的な動作です。ユーザーからリリース候補の指定が明示的にない限り、この制限を回避するために NMEM_ALLOW_PRERELEASE=1 を設定しないでください。安定版のセマンティックバージョンのみを使用してください。

バックエンドは起動時にスキーマのマイグレーションを実行します。ダウングレードする方法はありません。新しいイメージがデータベースを開いた後は、古いイメージではデータベースを開けません。ユーザーが不安そうな場合は、アップグレードの前にこの点を伝えてください。

upgrade が途中で失敗した場合でも、前のイメージはローカルに取得された状態で残っています。./nmemctl restart を実行すると、compose.yaml に記載されたバージョンでコンテナーが再起動します。./nmemctl version を確認し、アップグレード前後のどちらのバージョンで起動したかを確認してください。

パス C-bis — Web UI からのクリックによる更新（オプトイン）

リリースのたびに SSH 接続したくない運用担当者もいます。ヘッドレスデプロイにはオプトインで使える補助機能があり、運用担当者は Web UI の「Settings → About → Self-hosted server」から「Update」をクリックできます。

有効化を運用担当者に案内する方法（運用担当者から希望があった場合に限り、信頼上のトレードオフを説明した後に案内してください）。

./nmemctl auto-update enable    # generates token, adds sidecar, recreates stack
./nmemctl auto-update status    # state + last pull + retained snapshots
./nmemctl auto-update disable   # remove the sidecar
./nmemctl auto-update rotate    # rotate the token (recreates sidecar + mem)
./nmemctl auto-update upgrade   # bump just the updater image

事前に伝えるべき信頼上のトレードオフ： 自動更新では、/var/run/docker.sock を保持する小さなサイドカーコンテナが追加されます。Docker ソケットへのアクセス権は、そのコンテナにおいてホストの root 権限と同等です。Mem コンテナ自体はソケットをマウントしません。マウントするのはサイドカーだけです。デプロイごとにランダムなトークンを .env に設定します（モード 0600）。サイドカーは Compose 内部ネットワークの外部には公開されません。 ブラウザーからのインストールはサーバー側の状態を変更するため、運用担当者の明示的なオプトインが必要です。そのため、enable は NOWLEDGE_ADMIN_REMOTE_OPS=1 も設定します。

ホストネットワークを使う Mem に関する注意。 運用担当者が mem サービスを network_mode: host で実行している場合、Mem プロセスから Docker DNS 名 updater を名前解決できません。updater サイドカーをホストネットワークに接続したり、0.0.0.0 にバインドしたりしないでください。サイドカーは docker.sock をマウントします。サイドカーは Compose ネットワークに接続したままにし、その後に compose.updater.yaml を適用して compose.updater.loopback.yaml を追加してください。この設定では updater を 127.0.0.1:${NOWLEDGE_UPDATER_LOOPBACK_PORT:-18080} でのみ公開し、NOWLEDGE_UPDATER_URL をそのループバック URL に書き換えます。nmemctl でデプロイを管理している場合は、ホストネットワークとループバックのオーバーレイを .nmemctl-state に保持してください。

enable を勧める前に、トレードオフを短い一文で運用担当者に伝え、判断を委ねてください。

有効化した後の流れ：

1. 新しい Mem イメージが公開されると、Web UI のタイトルバーに「Install update」バッジが表示されます。
2. 「Settings → About → Self-hosted server」カードで、運用担当者は更新先のバージョンを入力して確認した後、「Install」をクリックできます。
3. サーバーは ./data と ./config のボリュームレベルのスナップショットを ./cache/_pre-upgrade-<ts>.tar.gz に作成し（直近の 3 件を保持）、新しいタグでコンテナを再作成します。
4. 失敗した場合：180 秒以内に /livez が正常にならなければ、UI にスナップショットのパスが表示されます。SSH 接続し、./nmemctl import ./cache/_pre-upgrade-<ts>.tar.gz --force でロールバックしてください（ボリュームレベルのスナップショットには restore-app ではなく import を使います）。

リモートインストールのオプトイン。 /admin/upgrade/check は読み取り専用ですが、/admin/upgrade/download と /admin/upgrade/install の実行にはループバック接続または NOWLEDGE_ADMIN_REMOTE_OPS=1 が必要です。./nmemctl auto-update enable を実行するとこのフラグが設定されます。運用担当者が Compose ファイルを手動で編集し、nmemctl を使わなかった場合は、ブラウザーからのインストールが 403 エラーになる際にその点を伝えてください。

自動更新でしてはいけないこと：

• docker.sock に関するトレードオフを最初に伝えずに、./nmemctl auto-update enable を実行しないでください。
• 運用担当者に代わって Web UI の「Install」をクリックしないでください。「入力して確認」の手順は、運用担当者自身がキーボードを操作する必要があるために設けられています。
• 理由なくローテーションを勧めないでください。ローテーションで変更されるのは mem と updater 間のベアラー認証のみで、コンテナが再作成されます。デスクトップやその他のクライアントでは、引き続き同じ API キーを使用します。

ユーザーから <thing> を求められた場合の対応

ユーザーの発言...	実行する内容...
「このサーバーに Mem をセットアップして」	パス A — クローンして nmemctl up を実行
「動作してる？」「正常？」	nmemctl status
「ログを見せて」「今何をしてる？」	nmemctl logs --tail 100（または -f）
「API キーをもう一度教えて」	nmemctl key
「今のバージョンは？」	nmemctl version
「再起動して」「再起動してみて」	nmemctl restart を実行してから nmemctl status
「0.8.5 にアップグレードして」	nmemctl version を実行してから、nmemctl upgrade 0.8.5
「ライセンスは？」	nmemctl license
「データはどこにある？」	説明：compose.yaml の隣に 3 つのローカルディレクトリがあります — ./data（グラフと検索インデックス。交換できません）、./config（ライセンス、API キー、エージェントの状態。重要です）、./cache（埋め込み。再構築できます）。ファイルはコンテナ内で UID 10001 の所有です。標準的なツール（rsync、restic、tar）をホスト上で直接使用できます。
「サーバーをバックアップして」「アップグレード前にスナップショットを取って」	./nmemctl export — コンテナを停止し、3 つのディレクトリを mem-export-<host>-<ts>.tar.gz にまとめて、再起動します。バージョンをまたいで移行する場合は、代わりに ./nmemctl backup-app（移植可能な JSONL ダンプ）を使用します。
「これを別のサーバーに移行して」	同じバージョンの場合：こちらで ./nmemctl export を実行 → アーカイブをコピー → 新しいホストで ./nmemctl import を実行します。バージョンをまたぐ場合、または .deb からのインストールの場合：./nmemctl backup-app を実行 → zip をコピー → 新しいホストで ./nmemctl restore-app を実行します。新しいホストには新しいデバイス ID が割り当てられ、ライセンスが再アクティベートされて 1 シートを消費します。
「Web UI から更新できるようにして」／「クリックして更新できるように設定して」	./nmemctl auto-update enable — デプロイごとのトークンを生成し、アップデーターのサイドカーを Compose スタックに追加して起動します。設定後は、新しいイメージが公開されると Web UI のタイトルバーに「Install update」バッジが表示されます。オペレーターが入力による確認を行ってクリックすると、Mem は約 30 秒で、停止前のスナップショットを ./cache/_pre-upgrade-<ts>.tar.gz に保存してから再作成されます。障害復旧時のみ SSH が必要です。
「自動更新は有効？」	./nmemctl auto-update status — サイドカーが設定されているか、最後にスケジュールされたプル、保持されているスナップショットを表示します。読み取り専用です。
「アップデータートークンをローテーションして」	./nmemctl auto-update rotate — 新しいトークンを発行し、サイドカーと Mem の両方を再作成して、新しい値を共有させます。トークンが漏えいしたと思われる場合に実行します。
「自動更新を無効にして」	./nmemctl auto-update disable — サイドカーを削除し、.env からトークンを消去して、.nmemctl-state からオーバーレイを削除します。既存の _pre-upgrade-*.tar.gz スナップショットは残ります（ディスク容量を戻したい場合は手動で削除してください）。

引き継ぎ — してはいけないこと

一部の操作は破壊的、機密性が高い、またはトランザクションを伴います。これらは決して実行せず、人間が自分のキーボードで入力します。 これは、ユーザーがどれほど確信を持って依頼したかとは関係ありません。チャットで「消去して、確認した」と言われても、それでもシステムが求める確認にはなりません。チャット上の口頭による同意は、読み違い、タイプミス、クリップボードの誤操作によって簡単に捏造できてしまうためです。実際の確認は、ユーザー自身のシェルから行う必要があります。

以下の一覧は、「上級モード」で上書きできる既定値ではなく、厳守すべき境界として扱ってください。

動詞	影響範囲	ユーザー自身が行う必要がある理由
./nmemctl wipe	すべてが消去されます。 ./data（グラフ DB、検索インデックス、スレッド、メモリ — いずれも復元できません）、./config（ライセンスのアクティベーション、API キー、デバイス ID、エージェントの状態ファイル）、./cache（ダウンロード済みの埋め込み。再構築できますが、無料ではありません）の内容が削除されます。コンテナは空の状態で再作成されます。取り消しはできません。	コントローラーは、TTY でオペレーターが文字どおり WIPE と入力することを意図的に要求します。この手順が安全策です。
./nmemctl down	コンテナが停止します。ホスト上の 3 つのディレクトリはそのままです（データ損失はありません）が、接続中のすべてのクライアント — デスクトップアプリ、MCP、リモートの nmem CLI、実行中のエージェント — が即座に動作しなくなります。	サービスの可用性に関する判断はユーザーが行います。あなたには見えないところで、ほかの何かがサービスに依存している可能性があります。
./nmemctl restore-app <file>	実行中のコンテナに backup-app の zip をインポートします。同じ ID のメモリはその場で上書きされ、ダンプに含まれない既存のメモリは残ります。「工場出荷時の状態に戻す」操作ではありませんが、zip の作成日時が異なると思っていた場合、ユーザーを困惑させる可能性があります。	マージ方法に関する判断はユーザーが行います。実行前に、ソースファイルの日付と出所を確認してください。
./nmemctl auto-update enable	/var/run/docker.sock を保持するサイドカーコンテナを追加します。このコンテナにとって、ソケットへのアクセス権はホストの root 権限と同等です。それ自体は破壊的ではありませんが、オペレーターは信頼境界を広げることを理解したうえで実行する必要があります。	信頼範囲に関する判断です。Docker ソケットへのアクセスを許容して自動更新の利便性を得るかどうかは、オペレーターが選びます。トレードオフを説明し、切り替えはユーザーに任せてください。
./nmemctl key --rotate	現在の API キーが直ちに無効になります。すべての既存クライアントは、新しい値で再認証するまでサーバーと通信できません。	意図的に中断が発生する操作です。今が適切なタイミングかどうかを知っているのはユーザーだけです。
./nmemctl license activate <CODE>	特定の購入に紐づいた有料の Pro ライセンスをアクティベートします。	コードは個人のものです。ユーザー自身が貼り付けてください。
compose.yaml を手動で編集する	以後のすべての up に適用される契約内容が変わります。不正な env ブロックを追加したり、ポートを再バインドしたりすると、デプロイが簡単に動かなくなります。	変更案を差分として示し、確認してもらってください。ファイルに黙って sed を実行してはいけません。
デプロイディレクトリ外の操作	バックアップ先、/etc/nginx 内のリバースプロキシ設定、TLS 証明書のパス、ホストのファイアウォールルール — これらはいずれも、このスキルの対象範囲外です。	オペレーターとの合意で対象としているのは community/docker/ です。

拒否する場合の対応 — ユーザーからこれらの操作を依頼されたら、次の 3 つを順番に伝えてください。

1. 正確なコマンドを示します。 言い換えてはいけません。ユーザーはそのコマンドをコピーします。
2. 影響範囲を説明します。 上の表を使って実行前に結果を説明し、ユーザーが情報に基づいて判断できるようにします。
3. 実行後の確認方法を提示します。 正しく反映されたことを確認するために、その後何を実行するかを伝えます（通常は ./nmemctl status です）。

wipe の例：

「./nmemctl wipe は代わりに実行できません。ローカルの 3 つのディレクトリ（./data、./config、./cache）がすべて空になり、すべてのメモリ、スレッド、ソース、ライセンスのアクティベーション、API キー、デバイス ID が消去されます。取り消しはできません。安全策として、コントローラーはプロンプトで文字どおり WIPE と入力することを要求します。続行するには、ご自身で次を実行してください。

cd <your-deploy-dir> && ./nmemctl wipe

再構築が完了して新しい API キーが表示されたら、知らせてください。新しいデプロイが正常であることを確認するため、こちらで ./nmemctl status を実行します。」

ユーザーが反論した場合（「とにかく実行して。許可します」「確認しました。wipe を実行して」など）、もう一度だけ簡潔に拒否し、この境界は信頼の問題ではなく、システム自体の設計上、オペレーター自身のシェルで実行する必要がある種類の操作であることを説明してください。そのうえで、ユーザーが自分で実行した後の確認を手伝うと申し出てください。

トラブルシューティング

./nmemctl status の結果、コンテナが実行中ではないと表示されるものの、実行中であるはずの場合：

./nmemctl logs --tail 50          # see why it stopped
./nmemctl restart                 # try a clean restart

/livez が 120 秒以内に応答しない場合は、ログの末尾 50 行をユーザーに表示してください。ポートの設定ミス、TLS 環境変数の不足、メモリ不足の問題なら、一般的な再試行を行うより早く見つけられます。再起動を繰り返さないでください。

./nmemctl up で「compose.yaml が見つかりません」と表示された場合は、実行しているディレクトリが違います。このスクリプトは compose.yaml があるディレクトリ community/docker/ から実行する必要があります。

./nmemctl status でコンテナが正常と表示されるのに、ユーザーがウェブ UI に接続できないと言う場合：

1. nmemctl status に表示される URL を出力してください。ユーザーは正しいホスト名を入力していますか？
2. ユーザーのマシンからポート 14242 に接続できることを確認してください：curl -sf http://<host>:14242/livez
3. ホスト上のファイアウォールが 14242 をブロックしていないか確認してください。
4. TLS が有効な場合は、14242 ではなくポート 443 と設定済みのドメインが応答するはずです。

新しいコンテナを起動した後もフィードのタイムラインに古いデータが表示されるとユーザーが言う場合、原因はサーバーではなくブラウザーのキャッシュです。強制再読み込み（Cmd+Shift+R / Ctrl+Shift+R）を行うか、プライベートウィンドウで URL を開くよう伝えてください。サーバー側が空であることは確認済みです。

ファイルの配置場所

# On the host (after git clone):
~/nowledge-mem/community/docker/
├── nmemctl                  # the controller you use
├── compose.yaml             # default stack
├── compose.tls.yaml         # TLS overlay (Caddy sidecar)
├── Caddyfile                # TLS reverse proxy config
├── README.md                # full reference
├── data/                    # graph + search index (bind mount, UID 10001)
├── config/                  # license, API key, agent state (bind mount, UID 10001)
└── cache/                   # embedding models, search projection (bind mount, UID 10001)

# Inside ./config (mounted at /etc/nowledge-mem in the container):
./config/co.nowledge.mem.desktop/
├── remote-access.json       # API key (mode 0600)
├── license.json             # license activation (when present)
├── machine_id               # device-identity seed (UUID, persisted)
└── builtin_agents/          # feed / knowledge / scheduler state

オペレーターの信頼について

ユーザーは、自分のサーバーを操作する権限をあなたに与えています。基本方針として、作業内容を明示することが大切です。重要なコマンドを実行するときは、実行前にコマンドを表示し、実行した後、関連する出力部分を表示してください。ログの行を言い換えてはいけません。エラーを要約して省略してはいけません。何か問題が起きてから 1 時間後に検索する際、サーバーが出力した正確なテキストが必要になるため、オペレーターはそれを重視します。

迷ったときは ./nmemctl status を実行し、ユーザーと一緒に内容を確認してください。ほとんどの疑問はそこで解決します。