# Nowledge Mem Connect Skill **Canonical URL**: `https://mem.nowledge.co/SKILL.md` **Audience**: AI coding agents (Claude Code, Codex, Cursor, Gemini CLI, Copilot CLI, OpenClaw, Hermes, Droid, Alma, Bub, Pi, OpenCode, 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, 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 Nowledge Mem installed and running. - Check: ask the user to run `nmem status` in any terminal. If the command is not found, or the server is not reachable, the user is not ready yet. - If not installed: send the user to and stop. The agent cannot install the app for the user. Resume from Step 1 once `nmem status` succeeds. ### 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. | | 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. | | Claude Desktop | Running inside Claude Desktop (extension host). | | Proma | Running inside Proma; `~/.proma/agent-workspaces/` exists. | | Slock | Running inside an AI tool launched by Slock, or the user asks to configure a named Slock 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. | | 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 host is Slock, connect the AI tool Slock launches, such as Codex or Claude Code. Then configure each named Slock 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. 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. 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, or Pi. 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. --- ## 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` | | Codex | `codex plugin marketplace add nowledge-co/community && codex plugin add nowledge-mem@nowledge-community`, then run `scripts/install_hooks.py` from the bundled plugin once. Set `[features] plugins = true, hooks = true, plugin_hooks = true` in `~/.codex/config.toml`. 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` | | 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 | `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` | | Proma | Manual: copy MCP, hooks, and skills per the plugin README (see ). | 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, the plugin install also runs a one-time setup that reads the user's saved client credentials. If that setup did not run, the agent can paste the override block produced by `nmem config mcp show --host codex` into the user's host config. ### 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: `cursor`, `claude-desktop`, `codex`, `gemini-cli`. 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) | 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, Codex, Copilot CLI, Gemini CLI, Droid, Hermes, OpenCode**: 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` | The desktop app is not installed, or `nmem` is not on `PATH`. Send the user to and to **Settings → Preferences → Developer Tools → Install bundled CLI**. | | `nmem status` reports server unreachable | Ask the user to open the desktop app. In remote mode, ask them to 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**: