Verify Nowledge Mem is running and guide the user to the best connector for their agent.
When to Use
- User asks about Nowledge Mem setup or configuration
- Memory tools are failing or not available
- User asks "is my memory working?" or "how do I set up Nowledge Mem?"
- First time using Nowledge Mem in this agent
- User asks about upgrading from skills to a native connector
Step 1: Check nmem CLI
nmem --json status
Use this rule before repairing anything:
- Same machine as Nowledge Mem Desktop: use the desktop app's bundled
nmem. Ask the user to open Nowledge Mem; if the command is still missing, use Settings → Preferences → Developer Tools → Install bundled CLI. - Different machine: install the standalone PyPI package
nmem-clion this machine, then point it at the user's Mem server. This covers 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.
If the agent is not on the desktop machine and nmem is missing, install the PyPI CLI:
python3 -m pip install --user nmem-cli
# or: pipx install nmem-cli
# or for one-off checks: uvx --from nmem-cli nmem --json status
nmem config client set url https://<their-mem-server>
nmem config client set api-key nmem_...
nmem --json status
If nmem exists but status fails, Nowledge Mem is not reachable from this machine. Guide the user:
- Local desktop: open the Nowledge Mem app, then retry
nmem --json status - Remote/client machine: verify the URL/API key with
nmem config client show - Full install guide: https://mem.nowledge.co/docs/installation
- Remote access guide: https://mem.nowledge.co/docs/remote-access
Step 2: Detect Agent and Recommend The Best Path
For a fresh install, start from the universal connect skill:
Read https://mem.nowledge.co/SKILL.md and follow the instructions to install or update Nowledge Mem for the AI tool I am using.
Use this check-integration skill as the diagnostic fallback: confirm what was installed, explain what behavior the user should expect, and repair configuration when something failed.
Do not only answer "install X". Explain the behavior contract the user will get:
- what starts automatically
- what is only guided by skills/rules and still model-driven
- whether threads are captured automatically, saved explicitly, or only supported as handoff summaries
Use this priority order:
- Native connector first when the host has one
- Universal Agent Plugin when the host supports Agent Plugins but has no native connector
- Direct MCP when the host supports MCP but has no better package path
- Reusable package when the host supports shared skills/prompts but has no native connector, Agent Plugins support, or MCP tool surface
Fresh users care about outcome, not transport. Tell them what they will actually get after setup.
Autonomy levels
| Path | What usually happens | What it does not guarantee |
|---|---|---|
| Native connector | Strongest setup: session bootstrap is often automatic; some hosts also add auto-capture or hook-driven recall | Exact proactive recall/distill timing can still be host-specific |
| Universal Agent Plugin | Standard Agent Plugins package with shared skills plus local Mem MCP for compatible clients without a dedicated connector | Agent Plugins 1.0 does not provide portable lifecycle hooks or transcript access |
| Direct MCP | Tools are available; with the recommended prompt block, the agent can use them proactively | MCP alone does not create host-enforced autonomy |
| Reusable package | Working Memory, recall, and distill are guided by rules/skills | The host may still ignore the guidance unless prompts and project guidance are strong |
Check which agent you're running in and recommend the native connector if available.
The canonical source for this table is community/integrations.json.
| Agent | How to Detect | Connector setup | Docs |
|---|---|---|---|
| Claude Code | Running as Claude Code agent; ~/.claude/ exists |
claude plugin marketplace add https://github.com/nowledge-co/community && claude plugin install nowledge-mem@nowledge-community |
Guide |
| Grok | Running as Grok; ~/.grok/ exists |
grok plugin install nowledge-co/community#nowledge-mem-claude-code-plugin --trust |
Guide |
| Grok Bot | Configuring a cloud-hosted Grok Bot; no local CLI installation is expected | Add a custom Nowledge Mem MCP connector in Grok Bot settings with a public HTTPS endpoint. If the Bot or team exposes a compatible Plugins setting, enable the shared package there for supported skills/hooks. Do not use localhost or 127.0.0.1; automatic full-thread capture still requires a documented Bot transcript export or hook payload. |
Guide |
| OpenClaw | Running as OpenClaw agent; ~/.openclaw/ exists |
openclaw plugins install clawhub:@nowledge/openclaw-nowledge-mem |
Guide |
| Cursor | Running inside Cursor IDE | Copy nowledge-mem-cursor-plugin from the community repo into ~/.cursor/plugins/local/nowledge-mem-cursor, then reload Cursor |
Guide |
| Gemini CLI | Running as Gemini CLI agent; ~/.gemini/ exists |
gemini extensions install https://github.com/nowledge-co/nowledge-mem-gemini-cli --auto-update or install "Nowledge Mem" from the Extensions Gallery |
Guide |
| Google Antigravity | Running as Antigravity; ~/.gemini/config/plugins/ or ~/.gemini/antigravity/ exists |
Install the native plugin: 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 Antigravity. For remote Mem, run nmem config mcp show --host google-antigravity and paste the generated serverUrl MCP block into Antigravity's MCP settings. Preview older history with nmem t sync --from antigravity; use the Trajectory Extractor only for old cache-only sessions. |
Guide |
| Alma | Running inside Alma; ~/.config/alma/ exists |
In Alma: Settings > Plugins > Marketplace, search "Nowledge Mem" | Guide |
| Droid | Running inside Droid (Factory) | Add nowledge-co/community marketplace, install nowledge-mem@community | Guide |
| OpenHands | Running inside OpenHands or OpenHands SDK | Load nowledge-mem-openhands-plugin with Plugin.load("path/to/nowledge-mem-openhands-plugin"), or copy it to .openhands/plugins/nowledge-mem. |
Package guide |
| CodeBuddy | Running inside CodeBuddy Code | codebuddy plugin marketplace add nowledge-co/community && codebuddy plugin install nowledge-mem@nowledge-community, then restart CodeBuddy |
Guide |
| WorkBuddy | Running inside WorkBuddy | Desktop Plugins -> +: add https://raw.githubusercontent.com/nowledge-co/community/main/.workbuddy-plugin/marketplace.json, Install and enable Nowledge Mem, reload, then review MCP Trust. Use Update on the plugin card; plugin slash commands are an alternative only when the host exposes them. |
Guide |
| Codex | Running inside Codex desktop or Codex CLI; ~/.codex/ exists |
codex plugin marketplace add nowledge-co/community --sparse .agents --sparse nowledge-mem-codex-plugin && codex plugin add nowledge-mem@nowledge-community, enable [features] plugins = true, hooks = true, and [plugins."nowledge-mem@nowledge-community"] enabled = true, then run the installed scripts/install_hooks.py. It adds the legacy plugin_hooks gate only when the host still needs it. Restart Codex and trust the Nowledge Mem hooks when prompted. If Codex local Memory is enabled, turn off Allow memory generation from tool-assisted tasks. |
Guide |
| Bub | Running inside Bub | pip install nowledge-mem-bub |
Guide |
| Pi | Running as Pi agent; ~/.pi/ exists |
pi install npm:nowledge-mem-pi |
Guide |
| DimAgent | Running inside DimAgent; ~/.dim/ exists or DIMCODE_HOME is set |
After upgrading to a Mem release with native DimAgent import, install nowledge-mem-dimagent-plugin through DimAgent's Codex-compatible plugin flow, restart DimAgent, and trust its lifecycle hooks if prompted. No verified host-specific marketplace command is published yet. |
Package guide |
| OMP | Running as OMP agent; ~/.omp/ exists |
omp plugin install nowledge-mem-omp |
Guide |
| OpenCode | Running as OpenCode agent; ~/.config/opencode/ or .opencode/ exists |
Check opencode --version. 1.x: opencode plugin opencode-nowledge-mem@0.3.10 --global. 2.x: opencode plugin add opencode-nowledge-mem (global by default). Restart OpenCode so its hooks load |
Guide |
| Amp | Running as Amp agent; ~/.config/amp/ or .amp/ exists |
Run bash nowledge-mem-amp-plugin/scripts/install.sh, then restart Amp so the tools, agent.end capture hook, and skill load |
Guide |
| Craft Agent | Running inside Craft Agent; ~/.craft-agent/ exists or CRAFT_CONFIG_DIR is set |
nmem config mcp show --host craft-agent, then add the generated source config and guide to the active Craft workspace. Use nmem t sync --from craft-agent --all-projects --apply for real session import. |
Guide |
| Hermes Agent | Running as Hermes agent; ~/.hermes/ exists |
Install the native Hermes provider (or use MCP only as fallback) | Guide |
| Cradle | Running inside Cradle; the bundled nowledge-mem integration appears in Plugin Marketplace |
Enable Cradle's bundled Nowledge Mem plugin. Configure its API URL, optional MCP URL, Space, and runtime-only API key as needed. | Guide |
| Arkloop | Running inside Arkloop; Settings > Memory lists Nowledge | Enable Memory, select Nowledge, then detect the local instance or enter Base URL, API Key, and timeout. | Guide |
| iCode | Running inside iCode (Chrys); ~/.chrys/ exists or CHRYS_SESSION_ROOT_DIR is set |
Run nowledge-mem-icode-plugin/scripts/install.py from a community checkout, then restart iCode. It merges the nowledge-mem MCP server into the agent profile, installs the user_prompt_submit context hook, and copies the shared skills. Verify with /agents > MCP and a first prompt in a fresh session. |
Package guide |
| OpticLM | Running inside Optic; Extension settings expose Nowledge Mem | Enable Optic's built-in integration. Add direct Mem MCP separately if you also need Working Memory, search, or durable memory tools. | Guide |
For Hermes updates, run the setup command from the guide and confirm it prints Thread import endpoint: /threads/import. If it prints an old endpoint or no endpoint, the user is likely launching Hermes with a different HERMES_HOME; set that explicitly and rerun setup before restart.
If the agent is not listed above:
- use the Universal Agent Plugin when the host supports Agent Plugins
- otherwise use direct MCP plus the recommended prompt block
- use the shared
npx skillspackage when the host supports shared skills but has no MCP tool surface
Do not describe raw MCP as equivalent to a native connector.
Step 3: Verify
After setup, verify with:
nmem --json m search "test" -n 1
If this returns results (or an empty list with no error), the connector is working.
Then state the expected outcome in plain language:
- Working Memory: automatic, guided, or manual
- Recall: automatic, guided, or manual
- Distill: automatic, guided, or manual
- Threads: automatic capture, explicit save, handoff-only, or none
If the path is only guided, say what strengthens it:
- keep
nmemavailable locally - restart the host after install
- merge the package
AGENTS.mdor equivalent repo guidance when recommended - configure the local
nmemclient in remote mode
What Native Connectors Add
Skills give you CLI-based memory access. Native connectors usually add:
- Auto-recall: relevant memories injected before each response (no manual search needed)
- Auto-capture: conversations saved as searchable threads at session end
- LLM distillation: key decisions and insights extracted automatically
- Graph tools: explore connections, evolution chains, and entity relationships
- Working Memory: daily briefing loaded or injected at session start
- Slash commands:
/remember,/recall,/forget(where supported)
Do not promise all of these on every host. Match the actual path the user is setting up.