# Nowledge Mem Connect Skill **Canonical URL**: `https://mem.nowledge.co/SKILL.md` **Audience**: AI coding agents (Claude Code, Grok Build, Codex, Cursor, Gemini CLI, Copilot CLI, OpenClaw, Hermes, Droid, Alma, Bub, Pi, OpenCode, Kimi Code, Kimi Work, ZCode, MiMo Code, OMP, Claude Desktop, and any MCP-capable client) **Purpose**: One URL. Supported AI tools. Use the best known connect path for the host the agent runs in. --- ## What This Document Is This is a machine-readable install contract 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://mem.nowledge.co/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. The contract has three 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. **Verification is part of setup.** Success means `nmem status` reports OK, and a fresh host session can reach Context Bundle, Working Memory, or another Mem tool without an error. --- ## The Loop ``` 1. Confirm Nowledge Mem is installed and running. 2. Detect the host (Claude Code, Grok Build, Codex, Cursor, ...). 3. Install for that host (plugin marketplace OR MCP config). 4. Verify with nmem status. 5. Restart the host. 6. Confirm Context Bundle or Working Memory is reachable from inside the host. ``` If any step fails, see [Recovery](#recovery) and report back to the user with the failure block. --- ## Step 0: Prerequisites The user must have a Nowledge Mem server available, and the agent's machine must have the `nmem` CLI. Use this rule: - **Agent runs on the same machine as Nowledge Mem Desktop:** use the desktop app's bundled `nmem`. Open the app first. If `nmem` is still missing, use **Settings → Preferences → Developer Tools → Install bundled CLI**. - **Agent runs on another machine:** install the standalone PyPI package `nmem-cli` on that machine, then point it at the user's Mem server. Do this for remote servers, dev boxes, CI runners, hosted agents, and SSH machines. Python 3.11+ is required. Do not install the PyPI CLI over the desktop-bundled CLI on the user's own desktop unless the user explicitly asks for a standalone CLI. First check: ```bash nmem status ``` If `nmem` exists but fails because a command, flag, or MCP host is unknown, treat it as an outdated CLI rather than a broken Mem server. Check the version and refresh the CLI from the same source before continuing: ```bash nmem --version ``` - **Desktop-bundled CLI:** open Nowledge Mem and run **Settings → Preferences → Developer Tools → Install bundled CLI** again. - **PyPI CLI:** run `python3 -m pip install --user --upgrade nmem-cli`. - **pipx CLI:** run `pipx upgrade nmem-cli`. - **uvx one-off CLI:** rerun the command with `uvx --from nmem-cli nmem ...`; do not cache an old wrapper. - **Arch/AUR CLI:** update the package with `yay -Syu nmem-cli` or `paru -Syu nmem-cli`. After refreshing, run `nmem status` again. Do not keep using an older `nmem` just because it is already on PATH; new plugin and MCP setup commands may depend on newer CLI helpers. If the agent is not on the desktop machine and `nmem` is missing, install the PyPI CLI: ```bash python3 -m pip install --user nmem-cli # or: pipx install nmem-cli # or for one-off checks: uvx --from nmem-cli nmem status ``` After installing the CLI on a remote/client machine, configure it with the user's Mem URL and API key before continuing: ```bash nmem config client set url nmem config client set api-key nmem status ``` If `nmem status` still cannot reach the server, stop and report that connection problem before installing any host plugin. ### Endpoint The MCP endpoint the agent should connect through depends on the user's current `nmem` client config: - **Local mode** (default): endpoint is `http://127.0.0.1:14242/mcp/`. - **Remote mode** (managed tunnel, self-hosted, or another shared server): endpoint comes from `nmem config client show`. If the user has not yet pointed the CLI at that server, ask them for the URL and API key and set them once: ```bash nmem config client set --url --api-key ``` In the desktop app, remote URL and key controls live under **Settings → Access Anywhere**. Do not invent an account URL or API key if the user has not provided one. The agent should not hardcode an endpoint. Use `nmem config mcp show --host ` (Step 2, MCP path) to emit the correct config for whichever mode the user is in. --- ## Step 1: Detect the host Identify which host you are running inside. 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. | | 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. | | Copilot CLI | Running inside GitHub Copilot CLI; `~/.copilot/` exists. | | OpenClaw | Running inside OpenClaw; `~/.openclaw/` exists. | | Hermes | Running inside Hermes; `~/.hermes/` exists. | | Droid | Running inside Droid (Factory). | | Alma | Running inside Alma; `~/.config/alma/` exists. | | Bub | Running inside Bub. | | Pi | Running inside Pi; `~/.pi/` exists. | | OpenCode | Running inside OpenCode; `~/.config/opencode/` or project `.opencode/` exists. | | 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. | | 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 (formerly Slock) | 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. | | 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 consumer Grok on grok.com or x.com, do not use the Grok Build plugin command. That web chat is connected through the Nowledge Mem Exchange browser extension. If the host is Raft (formerly Slock), connect the AI tool Raft launches, such as Codex or Claude Code. Then configure each named Raft worker with `NMEM_AGENT_ID=` in that worker's environment variables. Add `NMEM_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 originators `slock-daemon` and `raft-daemon`. 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=` 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=` 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:"` 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=` 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`. --- ## Step 2: Install for that host Two 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 https://github.com/nowledge-co/community && claude plugin install nowledge-mem@nowledge-community` | | Grok Build | `grok plugin install nowledge-co/community#nowledge-mem-claude-code-plugin --trust` | | 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 https://github.com/nowledge-co/community && droid plugin install nowledge-mem@nowledge-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. | | 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)`. | | Pi | `pi install npm:nowledge-mem-pi` | | OpenCode | `opencode plugin opencode-nowledge-mem -g` | | Kimi Code | Use `nmem` 0.9.19 or newer. If needed, clone `https://github.com/nowledge-co/community` to `~/.cache/nowledge-community`; in Kimi Code run `/plugins install ~/.cache/nowledge-community/nowledge-mem-kimi-code-plugin`, `/plugins enable nowledge-mem`, and `/reload`; then run `python3 ~/.cache/nowledge-community/nowledge-mem-kimi-code-plugin/scripts/install_hooks.py` once. 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 | MCP + skills path. Run `nmem config mcp show --host zcode`, add it under **Settings → MCP Servers**, then import or copy skills under **Settings → Skills**. | | 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 ). | 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 ` into the user's host config. For Kimi Code, the package has an explicit hook installer because Kimi does not execute plugin scripts during install and does not accept hooks in `kimi.plugin.json`. 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. MiMo Code thread sync is also an explicit import path, not a live hook package. 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. 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 ``` Supported `` values include `cursor`, `claude-desktop`, `codex`, `gemini-cli`, `kimi-code`, `kimi-work`, `zcode`, and `mimo-code`. Use the value that matches Step 1. 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) | | 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` | 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 ` header (the form depends on the host). When in doubt, prefer `nmem config mcp show` because it handles both modes correctly. ### C. 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 . - **Raycast**, **Antigravity / Windsurf trajectory extractors**: external installs. Direct the user to the connector docs page. Tell the user this is the path; do not try to install browser extensions or Raycast for them. --- ## Step 3: Verify Run: ```bash nmem status ``` Or, for a machine-readable result: ```bash nmem --json status ``` Expected: a green/OK status with the server reachable and the configured endpoint (local or remote) named. If the server is unreachable or the API key is missing in remote mode, fix that before continuing. --- ## 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, Copilot CLI, Gemini CLI, Droid, Hermes, OpenCode, Kimi Code, Kimi Work, ZCode, MiMo Code, OMP**: end the current session and start a fresh one. - **Cursor, Claude Desktop, Alma, Raycast**: fully quit and relaunch. - **OpenClaw, Bub, Pi**: end the agent session. 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 [Recovery](#recovery). --- ## Definition of Done Report all of the following to the user: 1. Host detected: `` 2. Install path used: `marketplace plugin` or `direct mcp` or `manual` 3. `nmem status`: green 4. Restart: confirmed by user (the agent cannot restart its own host) 5. Context Bundle or Working Memory call: succeeded (with or without contents) inside the restarted session 6. First suggested action: *"Save your first memory: tell me one decision, preference, procedure, event, or lesson from today."* Do not declare success until all six are true. --- ## Recovery | Symptom | What to do | |----------------------------------------------------|----------------------------------------------------------------------------------------------------------------| | `nmem: command not found` | Same machine as Nowledge Mem Desktop: open the app and use **Settings → Preferences → Developer Tools → Install bundled CLI**. Different machine: install the standalone CLI with `python3 -m pip install --user nmem-cli` or `pipx install nmem-cli`, then run `nmem config client set url ...` and `nmem config client set api-key ...`. | | `nmem` exists but a command/flag/host is unknown | The CLI is probably older than this connector guide. Check `nmem --version`, then refresh it from the same source: desktop **Install bundled CLI**, `python3 -m pip install --user --upgrade nmem-cli`, `pipx upgrade nmem-cli`, or `yay -Syu nmem-cli` / `paru -Syu nmem-cli`. Re-run `nmem status` before touching host plugin config. | | `nmem status` reports server unreachable | Local desktop: ask the user to open the Nowledge Mem app. Remote/client machine: verify the server URL is reachable, then re-run `nmem config client set --url --api-key `. | | 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. | | `nmem config mcp show --host `: unsupported | The CLI helper does not yet cover that host. Use the generic MCP block in Step 2.B. and ask the user to fill 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. | | Authorization errors in remote mode | The saved `nmem` client config is using the wrong URL or API key. Ask the user to copy the correct values from **Settings → Access Anywhere** or their server admin, then run `nmem config client set --url --api-key `. | If recovery 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 modify settings outside the host's plugin or MCP config path. 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 . 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**: 0.9.0 **Last updated**: 2026-05-28 **Source**: