# Nowledge Mem Connect Skill

**Canonical URL**: `https://nowledgemem.study/SKILL.md`
**Audience**: AI coding agents and agent runtimes (Claude Code, Grok Build, Grok Bot, Codex, DimAgent, OpenHands, CodeBuddy, WorkBuddy, Cursor, Gemini CLI, Copilot CLI, OpenClaw, Hermes, Ekko Agent, Droid, Alma, Bub, Pi, Step Code, OpenCode, Amp, Kimi Code, Kimi Work, ZCode, DeepSeek Harness, MiMo Code, OMP, LangGraph, Mirasim, Claude Desktop, ChatGPT Web/Desktop, Claude Cloud, MiniMax Cloud, Agent Plugins-compatible clients, and any MCP-capable client)
**Purpose**: One URL. Supported AI tools. Connect the credential, install the right connector, verify with `nmem doctor`.

---

## What This Document Is

This is a machine-readable install SOP for connecting an AI agent to the user's Nowledge Mem. When a user shares this URL with their agent, typically through a prompt like *"Read https://nowledgemem.study/SKILL.md and follow the instructions to install or update Nowledge Mem for the AI tool I am using"*, the agent reads this document and runs the steps below.

You will arrive by one of three entry paths, and Step 1 handles all of them:

- **Already connected**: the machine runs Nowledge Mem Desktop, or the CLI is already pointed at a server. Nothing to redeem.
- **Connect link**: the prompt carries a one-time link or token. No key is in the prompt.
- **URL and key** (self-host and power users): the human hands you a server address and an API key directly.

Hosted ChatGPT, Dots, Claude Cloud, and Grok Bot are an explicit exception: they do
not run `nmem` locally. Identify that host first and go to
[Cloud-hosted hosts](#b-cloud-hosted-hosts), where the host's remote connector
and OAuth flow are configured instead.

MiniMax Cloud is not ready: its managed App remains unavailable until MiniMax
confirms the provider and approved scopes. MiniMax Code's local package is a
separate, supported path.

The contract has four boundaries:

1. **One source of truth for install.** If a per-tool guide disagrees with this document on setup commands, use this document for setup. Use the per-tool guide for behavior, skills, and edge cases.
2. **Agent does every safe step it can.** Command-line hosts can usually be installed by the agent. App-based hosts may still require the user to click a marketplace install, approve a prompt, or restart the host.
3. **The CLI config is the credential source.** Native runtimes usually read the key there. Hosts requiring inline MCP credentials, including iCode, keep a private copy; rerun its installer after rotation and restart the host before testing MCP.
4. **Verification is part of setup.** Success means `nmem doctor` passes, and a fresh host session can reach Context Bundle, Working Memory, or another Mem tool without an error.

---

## Agent Rules

Read these before running anything. Each one prevents a real failure.

1. **Never guess.** Do not invent a server URL, an API key, a workspace name, or which AI tool you are running inside. If the tool, the address, or the credential is unknown, ask the human one short question and wait for the answer.
2. **Never print the key.** Do not echo, quote, log, or write the `api_key` value into chat output, a scratch file, or a commit. When you must refer to it, mask it the way `nmem` does: `nmem_ck_…3969`.
3. **One credential source.** The key belongs in `~/.nowledge-mem/config.json`, written by `nmem connect` or `nmem config client set`. Do not copy it into project files, shell profiles, or `.env` files. A host requiring an inline MCP credential (iCode, Claude Desktop, generic MCP clients in Step 3.C) stores a copy only in its private config. After changing the CLI key or endpoint, refresh that copy; rerun the dedicated installer for iCode, then restart and verify MCP. Never place it in a shared or published file.
4. **Connect links are single use.** A `?nmem_connect=` token can be redeemed exactly once. `410 Gone` means used, expired, or never valid, and the server deliberately does not say which. Do not retry it, do not try variations. Ask the human for a fresh link.
5. **Verify before you claim.** After connecting, run `nmem doctor` and report its lines back. An installer that exited 0 is not evidence that memory works.
6. **Prefer the dedicated connector.** If the host has a native Nowledge Mem plugin (Claude Code, Codex, and the other rows in Step 3.A), install that rather than the generic MCP block, and tell the human which one you installed.
7. **Only touch files the host owns.** Changes belong in the host's own plugin or MCP config path, plus the `nmem` credential home. `nmem connect` writes a `<file>.nmem-backup` before its first edit of a tool config; do the same if you edit one by hand.
8. **One round of recovery, then hand back.** Read the error verbatim, apply the named fix in [Triage](#triage) once, and if it fails again stop and report the exact error and the step you were on. Do not loop.
9. **Reply in the human's language.** Match the language the human used in their prompt to you (for example, the sentence that pointed you at this URL) for every message you send back during this loop: status updates, the Step 5 Definition of Done report, and any question you ask. Do not default to English. This applies to your own words; command output, code, and file paths stay as-is.

---

## The Loop

```
1. Get the nmem CLI on this machine.          (Step 0)
2. Connect the credential: nmem connect       (Step 1)
3. Verify: nmem doctor                        (Step 1)
4. Detect the host.                           (Step 2)
5. Install the connector for that host.       (Step 3)
6. Restart the host.                          (Step 4)
7. Confirm Context Bundle or Working Memory.  (Step 5)
```

`nmem connect` already performs host detection and registration for the tools it recognizes, so read its output before repeating work in Step 3.

If any step fails, see [Triage](#triage) and report back to the user with the failure block.

---

## Step 0: Get the `nmem` CLI

Native connectors, local MCP clients, and remote/headless machines use `nmem`,
so it has to exist on the machine where the agent runs. Hosted cloud clients do
not run this command; use [Cloud-hosted hosts](#b-cloud-hosted-hosts) instead.

```bash
nmem --version
```

- **Same machine as Nowledge Mem Desktop:** use the app's bundled CLI. Open the app first. If `nmem` is still missing, use **Settings → Preferences → Developer Tools → Install bundled CLI**. Do not install the PyPI CLI over it unless the user explicitly asks for a standalone CLI.
- **Any other machine** (remote server, dev box, CI runner, hosted agent, SSH session): install the standalone PyPI package. Python 3.11+ is required.

```bash
python3 -m pip install --user nmem-cli
# or: pipx install nmem-cli
# or on Fedora / RPM-based Linux, use the community COPR:
# sudo dnf copr enable abn/nowledge-mem && sudo dnf install nowledge-mem-cli
# or on Arch Linux: yay -S nmem-cli
# or for one-off checks: uvx --from nmem-cli nmem status
```

If `nmem` exists but rejects a command, flag, or MCP host used below, treat it as an outdated CLI rather than a broken server, and refresh it from the same source it came from (see [Triage](#triage)). Do not work around an old CLI by hand-editing configs.

---

## Step 1: Connect the Credential

Start by asking whether there is anything to connect:

```bash
nmem doctor
```

If `credential home`, `server reachable`, and `api key` all pass, this machine is already pointed at a working Mem. Skip to Step 2. This is the normal answer on a machine running Nowledge Mem Desktop, where the CLI defaults to the local server and no key changes hands.

Otherwise pick the path that matches what the human handed you. Both end in the same place: one credential in `~/.nowledge-mem/config.json`, verified live.

### Path A: connect link (preferred)

The prompt carries a one-time connect link, or an origin plus a token and a redeem URL. The token is the credential; there is no API key in the prompt text. It can be redeemed exactly once. A Nowledge Cloud workspace link lasts 15 minutes; a desktop login link lasts 60 seconds. Redeem it promptly and do not save it anywhere.

Hand the whole link to the CLI. It redeems the token, writes the credential, wires up the tools it recognizes, and verifies:

```bash
nmem connect "https://mem.example.com/app?nmem_connect=nmem_ct_…"
```

Accepted link shapes: `…?nmem_connect=<token>`, `…/connect?token=<token>`, `…/connect?key=<key>`, `…?nmem_api_key=<key>`. If the prompt gave you the origin and the token as separate values, assemble `<origin>/app?nmem_connect=<token>` and run the same command. A `nowledgemem://` deep link is for the desktop app and carries no server address; the CLI refuses it, so ask for the workspace link instead.

If the prompt instructs you to redeem the token yourself, follow the prompt. That call is:

```
POST <origin>/api/remote-access/redeem-connect-token
Content-Type: application/json

{"token": "<token>"}
```

A success answers `{"api_key": "…"}`; Nowledge Cloud also returns `"url"`. Do not print the value. Hand it straight to the CLI, which stores it and continues with tool registration:

```bash
nmem connect --url <origin> --api-key <api_key from the response>
```

To store the credential without touching any tool config, use `nmem config client set --url <origin> --api-key <KEY>` instead. It writes the same file.

### Path B: URL and key (self-host, or no link available)

The human gives you the server address and an API key.

```bash
nmem connect --url https://mem.example.com --api-key <KEY>
```

If either value is missing, ask for it. Do not read a URL or key out of an unrelated config, and do not fall back to a default address. Unlike a connect token, a raw key is long lived: keep it out of chat output, transcripts, and shell history where you can.

Where humans find these values: Nowledge Cloud workspace under **Settings → Mem access** (**Settings → Team** on a team workspace); desktop app under **Settings → Access Anywhere**; a self-hosted server operator can print a fresh login link with `nmem key --show-login`.

### What `nmem connect` does

1. Redeems the token when the input is one. This burns the one-time link.
2. Writes `apiUrl` and `apiKey` to `~/.nowledge-mem/config.json`, the single credential home. `NMEM_API_URL` and `NMEM_API_KEY` in the environment override it per process.
3. Verifies live *before* touching any tool config: a health check, then an authenticated probe. A bad credential stops here, so a failed connect never leaves half-registered tools behind.
4. Detects installed AI tools and registers what it safely can. Claude Code and Codex are registered automatically when their own binary is on `PATH`; Cursor, Gemini CLI, and OpenCode get their exact copy-paste commands printed for you to run. A tool that is already registered is reported and left alone, so re-running is safe.
5. Prints one success line with the server, the workspace, and the masked key.

Flags worth knowing: `--dry-run` prints the whole plan and changes nothing (it does not redeem, so a one-time link survives); `--skip-tools` saves the credential only; `--no-install` detects tools and prints their commands but never runs an installer or edits a tool config.

### Verify

```bash
nmem doctor
```

One line per check: credential home, server reachable, api key, then one line per installed AI tool. `[FAIL]` on any line exits non-zero; `[warn]` does not. Use `nmem --json doctor` when you want to parse the result. Report the lines to the human. If any line is `[FAIL]`, go to [Triage](#triage) before installing anything else.

### Which endpoint the connectors use

Do not hardcode an endpoint. Once the credential home is set, `nmem config mcp show --host <host>` emits the right MCP block for whichever mode the user is in:

- **Local desktop**: use the host's generated MCP block. For WorkBuddy, configure `http://127.0.0.1:14242/mcp` without a trailing slash; keep the generated headers with it. This WorkBuddy-specific URL also takes precedence over the generic manual MCP example below.
- **Nowledge Cloud workspace**: copy the full MCP URL from **Connectors → AI Tools**, including `?space_protocol=exact-v1` for URL-based setup. Current CLI-generated blocks instead carry `X-Nmem-Space-Protocol: exact-v1`; keep their generated URL and headers together. Use exactly one declaration, never both.
- **Self-hosted or managed tunnel**: whatever `nmem config client show` reports.

If an existing Cloud connection reports `space_client_upgrade_required`, inspect
its effective configuration before reinstalling. If it uses bare `/mcp` without
the exact-v1 header, update only its MCP URL to
`<WORKSPACE_URL>/mcp?space_protocol=exact-v1`, preserve its credentials and Space
selection, then reconnect. Verify `read_working_memory` and `memory_search` from
that client. A server deployment does not update the client's saved settings.

Access Anywhere is available without Plus or Max through Quick link. Plus and Max also include the stable managed Nowledge Link; a user-managed Cloudflare domain is another option. Grok Bot is cloud-hosted and cannot use a loopback endpoint. Configure one of those public HTTPS URLs at `https://grok.com/connectors`; do not run a local installer or add Grok Bot to `nmem config mcp show --host <host>`.

---

## Step 2: Detect the host

Identify which host you are running inside. Use the active runtime first;
existing configuration directories are only supporting cues. Use the first match:

| Host             | Detection cue                                                                                  |
|------------------|------------------------------------------------------------------------------------------------|
| Claude Code      | Running inside Claude Code; `~/.claude/` exists.                                               |
| Grok Build       | Running inside Grok Build, the coding agent; `~/.grok/` exists or `GROK_SESSION_ID` / `GROK_WORKSPACE_ROOT` is set. This is not grok.com/x.com web chat. |
| Grok Bot         | Configuring or running a cloud-hosted Grok Bot. It is not locally detectable and cannot reach local loopback services. |
| ChatGPT Web/Desktop | Configuring ChatGPT's hosted connector or using the ChatGPT desktop app. It is not a local plugin runtime. |
| Dots | Configuring Dot's OpenAI MCP plugin, including from Dia. Use the hosted OAuth path, not a local plugin runtime. |
| Claude Cloud     | Configuring Claude's hosted custom connector. It is not Claude Code and has no local plugin runtime. |
| MiniMax Cloud    | Stop and open its status guide. The managed App is unavailable until MiniMax confirms the provider and approved scopes. |
| DimAgent         | Running inside DimAgent or its Codex-compatible plugin host; `DIMCODE_HOME` or `~/.dim/` supports detection. |
| iCode            | Running inside iCode (Chrys); `~/.chrys/`, Windows `%APPDATA%/chrys`, or `CHRYS_SESSION_ROOT_DIR` supports detection. |
| OpenHands        | Running inside OpenHands or OpenHands SDK; `.openhands/` or `OPENHANDS_TOOL_NAME` supports detection. |
| CodeBuddy        | Running inside CodeBuddy Code; `~/.codebuddy/` supports detection. |
| WorkBuddy        | Running inside WorkBuddy; `WORKBUDDY_CONFIG_DIR` or `~/.workbuddy/` supports detection. |
| Codex            | Running inside Codex desktop or Codex CLI; `~/.codex/` exists; `~/.codex/config.toml` present.  |
| Cursor           | Running inside Cursor; `~/.cursor/` exists.                                                    |
| Gemini CLI       | Running inside Gemini CLI; `~/.gemini/` exists.                                                |
| Google Antigravity | Running inside Google Antigravity 2.0; `~/.gemini/config/plugins/` or `~/.gemini/antigravity/` exists, or the user asks about Antigravity plugins, hooks, or `transcript.jsonl`. |
| Copilot CLI      | Running inside GitHub Copilot CLI; `~/.copilot/` exists.                                       |
| OpenClaw         | Running inside OpenClaw; `~/.openclaw/` exists.                                                |
| Hermes           | Running inside Hermes; `~/.hermes/` exists.                                                    |
| Ekko Agent       | Running inside Hermes Studio's Ekko Agent; `HERMES_WEB_UI_HOME` is set or `$HERMES_WEB_UI_HOME/.ekko/ekko.db` exists. |
| Droid            | Running inside Droid (Factory).                                                                |
| Alma             | Running inside Alma; `~/.config/alma/` exists.                                                 |
| Bub              | Running inside Bub.                                                                            |
| Pi               | Running inside Pi; `~/.pi/` exists.                                                            |
| Step Code        | Running inside Step Code; `STEP_CLIENT=stepcode` or `~/.stepcode/` exists.                     |
| OpenCode         | Running inside OpenCode; `~/.config/opencode/` or project `.opencode/` exists.                 |
| Amp              | Running inside Amp; `~/.config/amp/`, project `.amp/`, or `AMP_*` environment hints exist.     |
| Kimi Code        | Running inside Kimi Code; `~/.kimi-code/` exists or `KIMI_CODE_HOME` is set.                   |
| Kimi Work        | Running inside Kimi Work Desktop, or its embedded runtime exists under `~/Library/Application Support/kimi-desktop/daimon-share/daimon/runtime/kimi-code/home`; `KIMI_WORK_HOME` may override it. |
| ZCode            | Running inside ZCode; `~/.zcode/` exists.                                                       |
| DeepSeek Harness | Running inside DeepSeek Harness; `dsh` command exists, `DSH_HOME` is set, or `~/.dsh/profiles/` exists. |
| MiMo Code        | Running inside MiMo Code; `.mimocode/` or `~/.config/mimocode/` exists.                        |
| OMP              | Running inside OMP; `~/.omp/` exists.                                                           |
| Claude Desktop   | Running inside Claude Desktop (extension host).                                                |
| Proma            | Running inside Proma; `~/.proma/agent-workspaces/` exists.                                     |
| Raft | Running inside an AI tool managed by Raft, or the user asks to configure a named Raft agent. |
| Lody             | Running inside an AI tool launched by Lody, or the user asks about Lody Agent Config.          |
| Multica          | Running inside an AI tool launched by Multica, or the user asks about a Multica agent.         |
| Cumora           | Running inside an AI tool launched by Cumora, or the user asks about Cumora.                   |
| Paseo            | Running inside an AI tool launched by Paseo, or the user asks about a Paseo agent.             |
| LangGraph        | A Python project imports `langgraph` or `langchain.agents.create_agent`, has `langgraph.json`, or deploys a LangGraph Agent Server. |
| Mirasim          | Running inside Mirasim, `~/.mirasim/` exists, or the user asks about Mirasim panes, MCP servers, skills, recordings, or `ui-cli`. |
| Cindy            | Running inside Cindy, the Cindy desktop app is installed, or the user asks about Cindy harnesses, Ghost plugins, MCP, skills, memory, or `makecindy/cindy`. |
| Agent Plugins-compatible client | None of the native hosts above, but the host can install Agent Plugins 1.0 packages. |
| Generic MCP client | None of the above, but the host supports MCP servers via a JSON config file.                 |

If you cannot determine the host, ask the user one short question: *"Which AI tool are you running this in?"* Do not guess.

If the user means Grok on grok.com or x.com, do not use the Grok Build plugin command. Use the custom connector at `https://grok.com/connectors` when Grok should search or update Mem. Use Nowledge Mem Exchange separately when the user wants to capture the web conversation into Mem.

If the host is Grok Bot, do not use the Grok Build plugin command. Grok Bot is cloud-hosted and is not a local plugin runtime. Follow the [Grok Bot guide](https://nowledgemem.study/docs/integrations/grok-bot): open `https://grok.com/connectors`, add the public Nowledge Mem `/mcp` endpoint, and complete OAuth without pasting an API key. A Cloud workspace uses its fixed Cloud endpoint; an App workspace first uses Access Anywhere to produce its own public HTTPS endpoint. Never use `localhost` or `127.0.0.1` from Grok Bot. The reviewed Grok Bot surface does not provide a stable transcript export, webhook, or lifecycle hook, so do not promise automatic full-thread capture or run `nmem t sync --from grok-bot`.

For ChatGPT Web/Desktop, use the [published official plugin](https://nowled.ge/openai) for a personal or Team workspace on Nowledge Cloud. Sign in to Mem, choose the intended workspace, approve OAuth, and verify a scoped write and exact-ID readback when authorized. For Mem running on the user's computer, follow the App guide to set up Access Anywhere or Nowledge Link and custom MCP/OAuth pairing. Custom connection availability depends on the ChatGPT account, Developer mode and workspace policy. See the [ChatGPT guide](https://nowledgemem.study/docs/integrations/chatgpt-web).

For Claude Cloud, use the host's remote connector settings with the public Nowledge Mem `/mcp` endpoint and complete OAuth. A Cloud workspace uses its Cloud endpoint; an App workspace first uses Access Anywhere to produce a public HTTPS endpoint. Custom connectors are available on Free, Pro, Max, Team, and Enterprise; Free accounts can add one. These direct connections provide authorized Mem tools; Nowledge does not proxy App MCP traffic through a shared gateway. Neither host connection provides access to unseen transcript history or automatic complete-chat capture. Use the [Claude Cloud guide](https://nowledgemem.study/docs/integrations/claude-cloud).

If the host is MiniMax Cloud, stop at the [MiniMax Cloud status guide](https://nowledgemem.study/docs/integrations/minimax-cloud). The managed App remains unavailable until MiniMax confirms the provider and approved scopes. Do not substitute a raw Mem API key or infer support from MiniMax Code's local MCP capability.

If the host is Raft, connect the AI tool Raft launches, such as Codex or Claude Code. Then configure each named Raft worker with `NMEM_AGENT_ID=<agent-slug>` in that worker's environment variables. Add `NMEM_SPACE=<space>` only if that whole worker should override its default Mem space. Use Mem skills or MCP inside Raft. Do not save a Raft-managed Codex rollout as the Raft conversation: the rollout is an execution trace and the Codex connector intentionally skips the `raft-daemon` originator. The legacy `slock-daemon` originator remains supported. Normal Codex sessions on the same computer still capture automatically.

If the host is Lody, connect the AI tool selected by the Lody Agent Config. Set `NMEM_AGENT_ID=<agent-slug>` only when that Agent Config represents a stable role; leave it unset for generic runtime presets.

If the host is Multica, connect the AI tool Multica launches. If the Multica agent runs Claude Code, save the Nowledge Mem MCP config in that Multica agent's MCP settings so Multica forwards it through `--mcp-config`; do not rely on MCP from the outer terminal. Then set `NMEM_AGENT_ID=<agent-slug>` in the Multica agent custom environment. Supported sessions inside that AI tool can sync through that tool's Nowledge Mem connector.

If the host is Cumora, connect the AI tool Cumora runs on this computer, such as Codex, Claude Code, Pi, or OMP. Supported sessions inside that AI tool can sync through its Nowledge Mem connector. For each long-lived Cumora teammate, add a short persona instruction: pass that teammate's `agent_id` on `read_context_bundle`, `read_working_memory`, `memory_search`, `thread_search`, and `memory_add`; pass `host_agent_id="cumora:<agent>"` when supported. Use daemon-level `NMEM_AGENT_ID` only when that daemon belongs to exactly one teammate. Cumora-native rooms and internal Cumora memory need a Cumora export, API, or hook before Mem can import them directly.

If the host is Paseo, connect the AI tool Paseo launches, such as Codex, Claude Code, OpenCode, Pi, or OMP. Automatic new-session capture comes from that child tool's Nowledge Mem connector, not from Paseo itself. To import older Paseo-managed history, run `nmem t sync --from paseo --all-projects --apply`; this reads Paseo's agent registry and imports the real child transcript while keeping `source_app` and the thread id as the launched tool. The import is safe to rerun. Set `NMEM_AGENT_ID=<agent-slug>` only when the Paseo agent is a durable role. Leave it unset for one-off advisors or generic provider presets; do not label all child sessions as `paseo`.

If the host is a LangGraph application, install `nowledge-mem-langgraph` in the application environment. Set one stable `NMEM_LANGGRAPH_APP_ID` for the deployment, add `NowledgeMiddleware` to LangChain `create_agent`, and load tools with `await NowledgeClient().tools()`. Pass trusted invocation-specific `agent_id`, `host_agent_id`, and `space_id` under `context.nowledge`; keep authorization in `NMEM_API_KEY`. Keep the existing LangGraph checkpointer. LangGraph `thread_id` identifies the conversation; `assistant_id` is deployment provenance and must not become the Mem Thread identity. For raw `StateGraph`, use the connector's explicit Context Bundle and Thread sync helpers at the actual model and completion boundaries.

If the host is Mirasim, add Nowledge Mem as a Mirasim MCP server for the built-in Mirasim agent: run `nmem config mcp show --host mirasim`, add the generated server as `nowledge-mem`, then run `mirasim ui-cli --port 4970 mcp health --name nowledge-mem`. If your Mirasim build accepts shared skills or Agent Plugins package sources, install the Nowledge Mem shared skills as well. If the active Mirasim pane is Claude Code or Codex, also install that child tool's dedicated Nowledge connector for transcript capture. Mirasim documents sessions/history and raw recordings, but it has not published a stable transcript schema or lifecycle hook for a native `nmem t sync --from mirasim` importer yet. Do not label child-tool transcripts as `mirasim`; keep `source_app` as `codex`, `claude-code`, or the runtime that actually produced the transcript.

If the host is Cindy, add Nowledge Mem as a Cindy MCP server for the built-in Cindy agent: run `nmem config mcp show --host cindy`, add the generated server as `nowledge-mem`, then add the shared Nowledge Mem skills or the guide from `https://github.com/nowledge-co/community/tree/main/nowledge-mem-cindy-connector/guide.md`. If Cindy launches Claude Code, Codex, Pi, or OMP, also install that child tool's dedicated Nowledge connector for exact transcript capture. Cindy has MCP and a Ghost plugin runtime, but Mem does not claim Cindy-native automatic thread sync until Cindy exposes a stable message export, lifecycle hook, API, or verified Ghost package path. Do not label child-tool transcripts as `cindy`; keep `source_app` as the runtime that actually produced the transcript. Use `NMEM_AGENT_ID=cindy` only when Cindy is a durable Mem AI Identity/persona.

---

## Step 3: Install for that host

`nmem connect` may have already registered Claude Code or Codex. Read its output first and do not repeat work it reported as done.

Three install patterns. Pick by host.

### A. Native connector, extension, or package hosts

For these hosts, use the native package when available. Some rows are commands the agent can run. Some are user-owned app marketplace steps; in those cases, guide the user and verify after restart.

| Host          | Install command                                                                                                                     |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------|
| Claude Code   | `claude plugin marketplace add /community && claude plugin install nowledge-mem@nowledge-community`    |
| Grok Build    | `grok plugin install nowledge-co/community#nowledge-mem-claude-code-plugin --trust`                                                  |
| ChatGPT Web/Desktop | For a personal or Team workspace on Nowledge Cloud, install the official plugin linked above and complete OAuth. It does not accept an App URL. Mem on the user's computer requires a separate custom MCP connection through Access Anywhere or Nowledge Link; follow the ChatGPT guide. |
| Claude Cloud  | Open the prefilled **Connect to Claude** link for the public `/mcp` endpoint, review the name and URL, then complete OAuth. Use the Cloud endpoint for a Cloud workspace or Access Anywhere for an App workspace; no local plugin is expected. |
| MiniMax Cloud | Do not configure the managed Cloud App yet. Open the status guide and wait for MiniMax provider/scope approval; use the local Marketplace package only for MiniMax Code. |
| DimAgent      | Use a Mem release with native DimAgent import and `nmem t capture --from dimagent`. Install [nowledge-mem-dimagent-plugin](https://github.com/nowledge-co/community/tree/main/nowledge-mem-dimagent-plugin#readme) through DimAgent's Codex-compatible plugin flow, restart DimAgent, and trust its lifecycle hooks if prompted. |
| iCode         | First open `/agents`, select Code and save its profile. macOS/Linux: `bash -lc 'tmp="$(mktemp -d)" && git clone --depth 1 https://github.com/nowledge-co/community.git "$tmp/community" && uv run --no-project --with pyyaml python "$tmp/community/nowledge-mem-icode-plugin/scripts/install.py"'`. Windows: use the fresh-directory PowerShell command in the [iCode guide](https://nowledgemem.study/docs/integrations/icode), including its exit-code checks. Restart and test MCP in `/agents`. Uses the configured CLI workspace; shared skills and context hook do not automatically capture full sessions. |
| OpenHands     | Load [nowledge-mem-openhands-plugin](https://github.com/nowledge-co/community/tree/main/nowledge-mem-openhands-plugin#readme) with OpenHands SDK `Plugin.load("path/to/nowledge-mem-openhands-plugin")`, or copy the package to `.openhands/plugins/nowledge-mem`. |
| CodeBuddy     | `codebuddy plugin marketplace add nowledge-co/community && codebuddy plugin install nowledge-mem@nowledge-community`, then restart CodeBuddy. See the [CodeBuddy guide](https://nowledgemem.study/docs/integrations/codebuddy). |
| WorkBuddy     | In desktop **Plugins -> +**, add `https://raw.githubusercontent.com/nowledge-co/community/main/.workbuddy-plugin/marketplace.json`, find Nowledge Mem in nowledge-community, Install and enable it, then reload. Check Skills and Connections/MCP and guide the user through explicit **Trust** if prompted. Use plugin slash commands only when that host exposes them; do not infer desktop activation from a terminal CLI install. For updates use the plugin card's Update, not marketplace removal. See the [WorkBuddy guide](https://nowledgemem.study/docs/integrations/workbuddy). |
| Codex         | `codex plugin marketplace add nowledge-co/community --sparse .agents --sparse nowledge-mem-codex-plugin && codex plugin add nowledge-mem@nowledge-community`, then run `scripts/install_hooks.py` from the bundled plugin once. Set `[features] plugins = true, hooks = true` in `~/.codex/config.toml`; setup adds the legacy `plugin_hooks` gate only when the installed Codex still requires it. Restart Codex and trust the Nowledge Mem hooks in `/hooks`. This enables startup context, cross-memory routing, and thread capture. If Codex local Memory is enabled, turn off **Allow memory generation from tool-assisted tasks**. The desktop app and CLI share this config. |
| Copilot CLI   | `copilot plugin marketplace add nowledge-co/community && copilot plugin install nowledge-mem@nowledge-community`                     |
| Droid         | `droid plugin marketplace add /community && droid plugin install nowledge-mem@community`     |
| OpenClaw      | `openclaw plugins install clawhub:@nowledge/openclaw-nowledge-mem`, then grant `plugins.entries.openclaw-nowledge-mem.hooks.allowConversationAccess=true`. Inspect `openclaw config get tools`; under a restrictive profile, preserve policy and add the plugin id to `tools.alsoAllow` (or an existing `tools.allow`). |
| Gemini CLI    | `gemini extensions install https://github.com/nowledge-co/nowledge-mem-gemini-cli --auto-update` or install "Nowledge Mem" from the Gemini CLI Extensions Gallery. |
| Google Antigravity | `mkdir -p ~/.gemini/config/plugins && git clone --depth 1 https://github.com/nowledge-co/nowledge-mem-google-antigravity.git ~/.gemini/config/plugins/nowledge-mem`, then restart Google Antigravity. On Windows PowerShell, run `$null = New-Item -ItemType Directory -Force "$env:USERPROFILE\.gemini\config\plugins"` before cloning into `$env:USERPROFILE\.gemini\config\plugins\nowledge-mem`. For remote Mem, run `nmem config mcp show --host google-antigravity` and paste the generated `serverUrl` MCP block into Antigravity's MCP settings. |
| Alma          | In Alma: **Settings → Plugins → Marketplace**, search "Nowledge Mem", click Install.                                                |
| Bub           | `python3 -m pip install nowledge-mem-bub`                                                                                            |
| Hermes        | Windows PowerShell: `irm https://raw.githubusercontent.com/nowledge-co/community/main/nowledge-mem-hermes/setup.ps1 \| iex`. macOS/Linux: `bash <(curl -sL https://raw.githubusercontent.com/nowledge-co/community/main/nowledge-mem-hermes/setup.sh)`. |
| Ekko Agent    | MCP + local import path. Run `nmem config mcp show --host ekko`, add the generated MCP config inside Hermes Studio/Ekko, then use `nmem t sync --from ekko` to preview local Ekko threads and `nmem t sync --from ekko --apply` to import them. |
| Pi            | `pi install npm:nowledge-mem-pi`                                                                                                    |
| Step Code     | Install with `step install npm:nowledge-mem-step-code`; update with `step update npm:nowledge-mem-step-code`; then restart Step Code. Older sessions can be backfilled with `nmem t sync --from step-code --apply`. |
| OpenCode      | Check `opencode --version`. **1.x:** `opencode plugin opencode-nowledge-mem@0.3.10 --global` (append `--force` to reinstall). **2.x:** `opencode plugin add opencode-nowledge-mem` (global by default); update with `opencode plugin update opencode-nowledge-mem`. |
| Amp           | From the `community` repository root, run `bash nowledge-mem-amp-plugin/scripts/install.sh`, then restart Amp. This installs the root plugin entry at `${XDG_CONFIG_HOME:-$HOME/.config}/amp/plugins/nowledge-mem.ts`, the plugin bundle, and the Amp skill. |
| Kimi Code     | Use `nmem` 0.9.19 or newer. In Kimi Code run `/plugins install https://github.com/nowledge-co/community/tree/main`, then `/reload`. Keep the explicit `/tree/main`: a bare repository URL prefers the latest GitHub Release, which can predate the Kimi manifest. For remote Mem, also run `nmem config mcp show --host kimi-code` and paste the generated MCP config into Kimi Code. |
| Kimi Work     | Use `nmem` 0.9.23 or newer. If needed, clone `https://github.com/nowledge-co/community` to `~/.cache/nowledge-community`; run `python3 ~/.cache/nowledge-community/nowledge-mem-kimi-work-connector/scripts/install_kimi_work_plugin.py`, then restart Kimi Work. For remote Mem, also run `nmem config mcp show --host kimi-work` and paste the generated MCP config into Kimi Work's embedded runtime. |
| ZCode         | Plugin path. In ZCode, add `https://github.com/nowledge-co/zcode-plugin` under **Settings → Plugins → Create → Add marketplace**, install `nowledge-mem-zcode`, reload Agent runtime, then verify `nmem t list --source zcode` after one short session. For remote Mem, also run `nmem config mcp show --host zcode` and paste the generated server into ZCode MCP settings. |
| DeepSeek Harness | Community DSH bundle path. Run `dsh plugin --profile web add github:nowledge-co/nowledge-mem-deepseek-harness`, then restart with `dsh web`. The standalone repo is tagged `dsh-plugin` for DeepSeek Harness ecosystem discovery. Verify `nmem t list --source deepseek-harness` after one short session. For remote Mem, set `NMEM_MCP_URL` / `NMEM_API_KEY` or run `nmem config mcp show --host deepseek-harness` for the equivalent MCP block. |
| MiMo Code     | MCP + guidance path. Run `nmem config mcp show --host mimo-code`, add the generated MCP config, then add Nowledge Mem guidance to project instructions. Older local sessions can be imported with `nmem t sync --from mimo-code --apply`. |
| OMP           | `omp plugin install nowledge-mem-omp`, then restart OMP. Use this dedicated OMP plugin, not `nowledge-mem-pi`; old local OMP sessions can be backfilled with `nmem t sync --from omp --apply`. |
| Proma         | Manual: copy MCP, hooks, and skills per the plugin README (see <https://nowledgemem.study/docs/integrations/proma>).                  |
| LangGraph     | `python3 -m pip install nowledge-mem-langgraph`; set a stable `NMEM_LANGGRAPH_APP_ID`, then attach `NowledgeMiddleware` and `await NowledgeClient().tools()`. Pass trusted invocation identity and scope under `context.nowledge`. |
| Mirasim       | MCP + skills path. Run `nmem config mcp show --host mirasim`, add the generated server as `nowledge-mem` in Mirasim, then run `mirasim ui-cli --port 4970 mcp health --name nowledge-mem`. For Mirasim-launched Claude Code or Codex panes, install that child tool's dedicated connector too. |
| Cindy         | MCP + skills path. Run `nmem config mcp show --host cindy`, add the generated server as `nowledge-mem` in Cindy, then add the shared Mem skills or `nowledge-mem-cindy-connector/guide.md`. For Cindy-launched Claude Code, Codex, Pi, or OMP sessions, install that child tool's dedicated connector too. |

For DimAgent, complete a short session and verify `nmem t list --source dimagent`.
An `enqueued` capture acknowledgement confirms queue admission; verify that the
Thread is persisted before reporting automatic capture as working.

For WorkBuddy, keep the raw `.workbuddy-plugin/marketplace.json` URL above.
Adding the repository root can select the CodeBuddy package. Migrate only a
confirmed wrong-package installation; do not remove the market during ordinary
updates. A copied skill plus MCP does not install lifecycle hooks. Verify context
and memory search inside WorkBuddy after enabling/trusting the connector; a
terminal `nmem doctor` does not prove the desktop connector is active.

For Hermes updates, the setup script should print the installed provider version and `Thread import endpoint: /threads/import`. If it does not, Hermes is probably reading a different `HERMES_HOME`; set `HERMES_HOME` to the profile used to launch Hermes and rerun the command before restarting Hermes.

For Codex and any plugin host whose MCP endpoint defaults to the local app, no further config is needed when the user is on local mode. If the user is on remote/managed mode, paste the override block produced by `nmem config mcp show --host <host>` into the user's host config.

For Kimi Code, current builds load Nowledge Mem lifecycle hooks directly from `kimi.plugin.json`; `/reload` or a new session activates them. Use the package's `scripts/install_hooks.py` only as a fallback for an older Kimi Code build that does not load manifest hooks. Kimi Work uses an embedded Kimi Code runtime but does not expose lifecycle hooks today, so it is an explicit import path: use `nmem t sync --from kimi-work --limit 20` to preview, then re-run with `--apply` after the user confirms. Ekko Agent and MiMo Code thread sync are also explicit import paths, not live hook packages: MCP gives them memory/context tools, while `nmem t sync --from ekko` or `--from mimo-code` imports local transcripts from the machine that owns the database.

OMP now has a dedicated plugin for live startup context and automatic thread capture; use `nmem t sync --from omp --apply` only to backfill older OMP sessions. These commands work with remote Mem because `nmem` reads the local transcript store and uploads normalized threads to the configured server.

### B. Cloud-hosted hosts

#### Dots: start with the official Cloud connection

For a personal or Team workspace on Nowledge Cloud, install
[Nowledge Mem](https://nowled.ge/openai), sign in, select the workspace and
approve the requested permissions. If the same OpenAI account already has
the plugin installed and enabled, try that connection first: Dots can use
supported enabled plugins with their existing account permissions.
See [OpenAI's account-permission guide](https://learn.chatgpt.com/docs/dots/computers-and-apps).
Verify a known Memory search before saving a user-approved takeaway.

For Mem on the user's computer, use the App steps below with Access Anywhere
or Nowledge Link. Keep Mem and the connection running. Do not assume the
official Memory plugin grants `threads:sync`, captures full conversations,
or enables background MCP Events.

#### Dots App connection and Grok Bot: custom MCP over OAuth

For a Desktop workspace, keep Mem running and choose a connection type in
**Settings → Access Anywhere**. In **Connectors → AI Tools**, click **Install**
on the **Dots** or **Grok Bot** card. The local Desktop app starts Access
Anywhere if needed, copies the public MCP URL, and opens owner pairing.
Complete tunnel configuration first if required. For remote access to a
Desktop workspace, start its tunnel on the computer running Mem first.
Clicking Install during active pairing cancels it and opens fresh pairing.

Add the copied public `/mcp` URL in **OpenAI Plugins** for Dots, or at
`https://grok.com/connectors` → **New Connector → Custom** for Grok Bot.
Choose OAuth; keep Desktop pairing and approval in the same browser profile.
Enable the Grok connector in the Bot's **Settings → Plugins**. Do not install
a local plugin, Dia extension, or CLI for this connection.

Hosted Cloud uses its full MCP endpoint from **Connectors → AI Tools**,
including `?space_protocol=exact-v1`, and Cloud sign-in. Skip Desktop pairing
and Access Anywhere. If sign-in opens another tab, finish there, return to
approval, and select **Continue after sign-in**.

For snapshots, the client must explicitly request and receive `threads:sync`,
plus `threads:read` for retrieval. Memory writes require `mem:write` separately.
Old read-only grants need new consent; refreshing tools does not add permission.
Check the server version and tool list for `sync_thread` before promising it.

Verify a synthetic first save with `snapshot_saved: true`, exact replay adding
zero messages, and originals in Threads. Keep stable source, conversation and
message IDs, and the receipt's `space_id`. To fill gaps, submit all saved
messages plus missing ones in order with unchanged roles and original text.
Resend the same snapshot after a lost response. Do not send only a new tail,
invent originals, or substitute summaries. Limits are 5,000 messages, 256 KiB
per message, and 8 MiB total original UTF-8 text; Cloud may set a lower
per-message limit. Each growing snapshot must include all saved messages and
fit the limits.

This saves only submitted originals. It does not collect unseen provider
history or automatically distill Memories. See the [Dots guide](https://nowledgemem.study/docs/integrations/openai-dots)
and [Grok Bot guide](https://nowledgemem.study/docs/integrations/grok-bot)
for setup, verification, and recovery. Keep native-host installation separate.

For ChatGPT, keep official installation separate from custom MCP setup: the published official plugin connects only to a personal or Team workspace on Nowledge Cloud. For Mem on the user's computer, follow the App pairing/custom connection section of the [ChatGPT guide](https://nowledgemem.study/docs/integrations/chatgpt-web#custom-mcp). Never ask a hosted ChatGPT client to install the local Codex package or run thread-sync commands. Verify only the tools actually exposed and authorized; do not promise automatic full-chat capture or semantic retrieval when the result reports degradation.

For Claude, prefer the prefilled **Connect to Claude** link; Free accounts can add one custom connector, and paid individual or organization plans can add more. A Cloud workspace uses its Cloud endpoint; an App workspace uses a public HTTPS Access Anywhere endpoint. Do not use `localhost` or `127.0.0.1`. Use the host-specific guide for export or browser-capture alternatives; custom MCP alone does not grant unseen transcript history.

MiniMax Cloud is not part of that ready list. Its managed App remains blocked on MiniMax's provider and scope confirmation. MiniMax Code can use the local Marketplace package, but that does not establish MiniMax Cloud support.

Do not ask a hosted client to run `nmem doctor`, install `nmem-cli`, or redeem a
local connect token. If the Cloud endpoint does not expose OAuth discovery yet,
stop and report that the Cloud connector is not deployed for this flow; use a
supported local/Access Anywhere path only when the client accepts it. Do not
paste a private `nmem_` API key into a hosted client that requires OAuth.

### C. Universal Agent Plugin hosts

Use this only when the client supports Agent Plugins 1.0 and none of the native rows above apply. Do not use it instead of a dedicated Nowledge connector.

Install this source package from the client's Agent Plugins install flow:

```text
https://github.com/nowledge-co/community/tree/main/nowledge-mem-agent-plugin
```

This package provides shared Mem skills plus a local Streamable HTTP MCP declaration at `http://127.0.0.1:14242/mcp/`. It does not provide portable lifecycle hooks or transcript access, so full-thread capture remains a native-connector feature.

For remote Mem, Nowledge Cloud, Access Anywhere, or any authenticated endpoint, do not put a private key into the published package. Use the client's private MCP settings. Prefer:

```bash
nmem config mcp show --host <host>
```

If the CLI does not know this host yet, use the generic MCP block in Step 3.C and fill in the user's private remote URL and key only in that client's local config.

### D. Direct-MCP hosts

For these hosts, there is no plugin marketplace install. The agent emits the host-specific MCP config from `nmem config mcp show` and the user pastes it into the host's MCP settings file.

```bash
nmem config mcp show --host <host>
```

Supported `<host>` values include `cursor`, `claude-desktop`, `codex`, `gemini-cli`, `google-antigravity`, `kimi-code`, `kimi-work`, `zcode`, `deepseek-harness`, `mimo-code`, `mirasim`, and `cindy`. Use the value that matches Step 2.

Example for Cursor:

```bash
nmem config mcp show --host cursor
```

This prints a JSON block. Tell the user where to paste it:

| Host           | Target file                                                                 |
|----------------|------------------------------------------------------------------------------|
| Cursor         | `~/.cursor/mcp.json` (under `mcpServers.nowledge-mem`)                       |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)    |
| Google Antigravity | `~/.gemini/config/mcp_config.json` or Antigravity's MCP Store override (`mcpServers.nowledge-mem.serverUrl`) |
| Kimi Code      | `$KIMI_CODE_HOME/mcp.json` or `~/.kimi-code/mcp.json`                         |
| Kimi Work      | `$KIMI_WORK_HOME/mcp.json` or Kimi Work's embedded runtime `mcp.json`          |
| Cindy          | Cindy's custom MCP server settings, with server name `nowledge-mem`            |
| iCode          | Installer-managed `~/.chrys/agents/<Agent>.yaml` under `tools.mcp` (Windows: `%APPDATA%/chrys/agents/<Agent>.yaml`). Use the dedicated installer, not a generic JSON paste. |

If `--host cursor` (or whichever host) is rejected as an unsupported choice, the host is not yet covered by the CLI helper. Fall through to the generic MCP block:

```json
{
  "mcpServers": {
    "nowledge-mem": {
      "url": "http://127.0.0.1:14242/mcp/",
      "type": "streamableHttp"
    }
  }
}
```

In remote/managed mode, replace the URL with the user's managed endpoint and add the `Authorization: Bearer <API_KEY>` header (the form depends on the host). When in doubt, prefer `nmem config mcp show` because it handles both modes correctly.

### E. Browser-only and external surfaces

These are out of scope for an agent-driven connect:

- **Browser Extension** (web chat: ChatGPT, Claude.ai, Gemini, etc.): the user installs from the Chrome Web Store and opens the side panel. Direct the user to <https://nowledgemem.study/docs/integrations/browser-extension>.
- **Raycast**, **Windsurf trajectory extractor**, and old **Antigravity trajectory extractor** fallback: external installs. Direct the user to the connector docs page. For new Google Antigravity sessions, use the native Google Antigravity plugin row above instead of the extractor.

Tell the user this is the path; do not try to install browser extensions or Raycast for them.

---

Re-run `nmem doctor` after installing. Each installed tool gets its own line, so this is where a connector that registered against the wrong server shows up.

---

## Step 4: Restart the host

Most hosts only load new plugins or MCP servers on startup. Tell the user to:

- **Claude Code, Grok Build, Codex, DimAgent, OpenHands, CodeBuddy, WorkBuddy, Copilot CLI, Gemini CLI, Droid, Hermes, Ekko Agent, OpenCode, Amp, Kimi Code, Kimi Work, ZCode, DeepSeek Harness, MiMo Code, OMP**: end the current session and start a fresh one.
- **Cursor, Claude Desktop, Alma, Raycast**: fully quit and relaunch.
- **iCode**: quit and restart iCode so saved agent profiles and hooks reload.
- **OpenClaw, Bub, Pi**: end the agent session.
- **Grok Bot**: reload the Bot after changing its connector settings.

Do not skip this step. Pre-restart, the new tools or hooks are not visible to the agent.

---

## Step 5: Confirm Context Is Reachable

In a fresh host session, the agent calls the host's Context Bundle tool, `read_working_memory` fallback, or equivalent skill / MCP tool / slash command. On first connect, Context Bundle may include an empty Working Memory section, and that is a successful empty result, not a failure.

Acceptance is one of:

- The skill/tool returns Context Bundle content.
- The skill/tool returns Working Memory content.
- The skill/tool returns an empty result with a message like *"Working Memory is empty, save your first thought."*
- The agent can call `memory_search` (or the host's equivalent) and get a non-error response (possibly zero hits).

If the call fails with *"unknown skill"*, *"tool not found"*, *"connection refused"*, or *"unauthorized"*, see [Triage](#triage).

---

## Definition of Done

Report all of the following to the user:

1. Host detected: `<name>`
2. Credential path used: `connect link` or `url + key`
3. Install path used: `marketplace plugin` or `direct mcp` or `manual`, and which connector
4. `nmem doctor`: all checks pass, with the lines quoted
5. Restart: confirmed by user (the agent cannot restart its own host)
6. Context Bundle or Working Memory call: succeeded (with or without contents) inside the restarted session
7. First suggested action: *"Save your first memory: tell me one decision, preference, procedure, event, or lesson from today."*

Do not declare success until all seven are true. Never include the API key in this report; masked or nothing.

---

## Triage

Connect and verify failures. Apply the fix once, then hand back.

| Symptom | What it means | What to do |
|---|---|---|
| `nmem: command not found` | The CLI is not on this machine | Step 0. Do not proceed without it, and do not hand-edit tool configs as a substitute. |
| Redeem returns `410 Gone` | The connect link was already used, has expired, or was never valid. The server answers one uniform 410 for all three, so you cannot tell which. | Ask the human for a fresh connect link. Do not retry the same link and do not vary it. |
| Redeem returns `429` | The server is throttling redemptions | Wait a minute, then ask for a fresh link and try once. |
| Redeem returns `404` or `405` | The server predates connect links | Switch to Path B: ask the human for the URL and key, then `nmem connect --url <URL> --api-key <KEY>`. |
| `doctor`: `api key` `[FAIL]`, invalid or rotated | The stored key no longer authenticates (401/403) | Ask for a fresh connect link or a new key. A rotated key never comes back, so retrying is wasted work. |
| `doctor`: `server reachable` `[FAIL]`, connection refused | Wrong URL, server down, or the desktop app is not running | Local: ask the user to open the Nowledge Mem app. Remote: confirm the address with the human, then re-run `nmem connect`. Do not guess another URL. |
| `doctor`: `credential home` `[FAIL]`, not valid JSON | `~/.nowledge-mem/config.json` is corrupt | Tell the human, then delete or fix that file and re-run Step 1. |
| `doctor`: a tool row `[FAIL]`, points at a different server | That tool's MCP config still names the old endpoint, which is common right after moving from local to a workspace | Run `nmem config mcp show --host <host>` and replace the block in that tool's config. |

A tool row that reads `[warn] not registered` is not a failure. It means the tool is installed but has no connector yet: run `nmem connect` again, or the Step 3 command for that tool.

### Install and restart problems

| Symptom | What to do |
|---|---|
| `nmem` exists but a command, flag, or host is unknown | The CLI is older than this document. Check `nmem --version`, then refresh from the same source: desktop **Install bundled CLI**, `python3 -m pip install --user --upgrade nmem-cli`, `pipx upgrade nmem-cli`, `sudo dnf upgrade nowledge-mem-cli`, or `yay -Syu nmem-cli` / `paru -Syu nmem-cli`. If the refreshed CLI still lacks the command, the desktop app itself is behind: ask the human to update the Nowledge Mem app first, then run **Install bundled CLI** again. Until then, skip the missing command and continue with the steps that work; report the version gap to the human instead of looping. Re-run `nmem doctor` before touching host plugin config. |
| Plugin marketplace install fails | Read the host's error verbatim. Do not retry blindly. If the marketplace name `nowledge-co/community` is rejected, the user may have an older host version; ask them to update the host. |
| A tool's registration failed during `nmem connect` (exit code 1) | The CLI printed that tool's copy-paste commands. Run them yourself, or hand them to the human if they need a marketplace click. |
| `nmem config mcp show --host <host>`: unsupported | The CLI helper does not yet cover that host. Use the generic MCP block in Step 3.C and ask the user for the host-specific header format if needed. |
| After restart, host says "unknown tool / unknown skill" | The plugin or MCP server is registered but the host did not pick it up. Ask the user to fully quit (not just close the window) and reopen. |

If a fix fails after one round, hand back to the user with the exact error and the step you were on. Do not loop.

---

## What this skill does not do

- It does not install the desktop app. The user must do that.
- It does not sign the user in. Sign-in is a browser action.
- It does not restart the host. The user must restart.
- It does not mint or rotate credentials. It redeems a link the human already has, or stores a key the human already handed over.
- It does not modify settings outside the host's plugin or MCP config path and the `nmem` credential home. No other files are touched.

---

## Behavioral hand-off

After the connect loop succeeds, fetch the host's connector page for behavioral guidance (recall, distill, save-thread). The full list is at <https://nowledgemem.study/docs/integrations>. Each page describes the skills, lifecycle hooks, and ambient-space rules that make the connection productive. Those are concerns of the host's plugin, not of this install contract.

---

**Version**: 1.1.0
**Last updated**: 2026-09-23
**Source**: <https://github.com/nowledge-co/nowledge-labs-website/blob/main/nowledge-mem/public/SKILL.md>