nowledge-co/nowledge-mem-openclaw-plugin

Nowledge Mem for OpenClaw

Use this guide when an AI agent is helping a user install, configure, verify, or explain the Nowledge Mem OpenClaw plugin.

Nowledge Mem is not just "memory for OpenClaw." It is the user's shared memory layer across OpenClaw, Claude Code, Cursor, browser capture, imported threads, and documents. OpenClaw joins that context exchange.

Use This When

• The user wants to install or configure the OpenClaw plugin
• The user wants OpenClaw to connect to existing Nowledge Mem data
• The user wants local-first memory on this machine
• The user wants remote or multi-machine memory through a remote apiUrl
• The user wants to verify that OpenClaw can recall, save, and search memory

Do Not Use This When

• The user only wants temporary context in the current OpenClaw session
• The user is troubleshooting unrelated OpenClaw issues
• The user only wants direct MCP setup for another client

Product Framing

When talking to users:

• Say "Nowledge Mem gives OpenClaw the same shared memory your other AI tools can use."
• Lead with cross-tool continuity, not with plugin internals.
• For local mode, say "No API key is needed for local mode."
• For remote mode, say "Set apiUrl, and add apiKey when the server requires auth."
• Do not imply that OpenClaw is the only source of truth. It is one client of the user's larger memory system.
• Do not imply that cloud backup is the default. Our default story is local-first.

Good user-facing explanation:

OpenClaw can now read the same memory you already built in your other AI tools, and what happens in OpenClaw can enrich that shared memory too.

Definition of Done

This task is not complete until all of the following are true:

1. nmem is available
2. The intended backend is verified reachable with nmem
3. The OpenClaw plugin is installed
4. OpenClaw is using the Nowledge Mem memory slot
5. Remote config is written only if the user chose remote mode
6. OpenClaw is restarted
7. openclaw nowledge-mem status succeeds
8. The user receives a short handoff covering:
   • one real first question to ask
   • how to bring in older history
   • local vs remote expectations
   • trust pinning if they see plugins.allow warnings

Setup Flow

Step 0 — Choose Local or Remote

Ask the user which setup they want:

1. Local Nowledge Mem already running on this machine
2. Existing remote Nowledge Mem server

Explain the difference plainly:

• Local mode: OpenClaw talks to the local Nowledge Mem app/server through nmem
• Remote mode: OpenClaw talks to a remote Nowledge Mem server through nmem --api-url ...; add apiKey when that server has auth enabled
• If the user wants one agent-specific lane, use plugin config space first, plugin config spaceTemplate only when the launcher already exposes a trustworthy lane signal, and NMEM_SPACE="<space name>" only as the fallback for CLI-style launches instead of inventing a second OpenClaw-only memory namespace

Step 1 — Verify nmem

nmem --version

If this fails:

• For users with the desktop app, direct them to Settings > Preferences > Developer Tools > Install CLI
• Otherwise suggest pip install nmem-cli

Step 2 — Verify the Backend Before Plugin Setup

Local mode:

nmem --json status

Remote mode without auth:

nmem --json --api-url "$API_URL" status

Remote mode with auth:

NMEM_API_KEY="$API_KEY" nmem --json --api-url "$API_URL" status

Success means the backend responds correctly through nmem. Do not skip this step and assume the URL/auth is right.

Step 3 — Install the Plugin

Default install:

openclaw plugins install clawhub:@nowledge/openclaw-nowledge-mem

Alternatively, if the user is installing from OpenClaw's default registry rather than ClawHub, this also works:

openclaw plugins install @nowledge/openclaw-nowledge-mem

Important facts:

• The installer already writes the install record
• The installer already enables the plugin
• The installer already switches the memory slot to openclaw-nowledge-mem

Do not tell the user to hand-edit those settings unless they are using a manual/path setup.

Step 4 — Configure Remote Only When Needed

Local mode:

• No extra config is required

Remote mode:

• Prefer setting apiUrl and apiKey in the OpenClaw plugin settings
• Use ~/.nowledge-mem/openclaw.json only when the user wants a stable machine-local override or scripted setup

~/.nowledge-mem/openclaw.json example:

{
  "apiUrl": "https://nowledge.example.com",
  "apiKey": "your-api-key-here"
}

Important precedence rule:

• ~/.nowledge-mem/openclaw.json overrides OpenClaw plugin settings
• Then plugin settings override inherited environment variables
• Do not assume stale NMEM_API_URL or NMEM_API_KEY env vars should keep winning

If the remote server does not require auth, omit apiKey.

Step 5 — Pin Trust When Appropriate

If OpenClaw warns that plugins.allow is empty, or the user wants explicit trust for non-bundled plugins, add:

{
  "plugins": {
    "allow": ["openclaw-nowledge-mem"]
  }
}

Explain this correctly:

• plugins.allow trusts the plugin id
• It does not pin the plugin source path
• If the user also has linked or workspace copies in plugins.load.paths, they should review those too

Step 6 — Restart OpenClaw

Restart OpenClaw so the plugin and hooks are active.

If an agent is doing the restart automatically, tell the user before triggering it.

Step 7 — Verify the Plugin

First check the plugin status:

openclaw nowledge-mem status

If only memory_search and memory_get tools are available (other Nowledge Mem tools missing), the memory slot may still point to the built-in memory-core. Verify the slot in ~/.openclaw/openclaw.json:

{
  "plugins": {
    "slots": { "memory": "openclaw-nowledge-mem" }
  }
}

If missing, reinstall (openclaw plugins install clawhub:@nowledge/openclaw-nowledge-mem) which sets the slot automatically. This is common after upgrading OpenClaw to 3.22+ where the default memory slot changed.

Then verify in chat.

For a clean synthetic check:

1. /remember We chose PostgreSQL for task events
2. /recall PostgreSQL
3. /new
4. Ask What database did we choose for task events?

If the user already has real memory in Nowledge Mem, prefer a real question over a synthetic demo. Good examples:

• What was I working on this week?
• What did we already decide about the task API?
• Find the conversation where we discussed Redis caching

Handoff Message

After setup succeeds, send a short handoff that covers all four points:

1. OpenClaw is now connected
2. The best next question to ask
3. How to bring in older history
4. What the local/remote trust model is

Good structure:

OpenClaw is now connected to Nowledge Mem.

Try this next:
- Ask OpenClaw: "What was I working on this week?"

If you want more history:
- Import old AI threads or browser-captured chats into Nowledge Mem so OpenClaw can search them too.

What to expect:
- Local mode needs no API key.
- Remote mode uses the same apiUrl and, when auth is enabled, the same apiKey you already verified with nmem.
- If OpenClaw warns that plugins.allow is empty, add openclaw-nowledge-mem to the allowlist to pin trust explicitly.

Troubleshooting

| Symptom | What to do | | --- | --- | | nmem --json status fails in local mode | Start Nowledge Mem locally first | | Remote mode fails | Re-run nmem --json --api-url ... status with the exact URL and auth you plan to use | | openclaw nowledge-mem status fails after install | Restart OpenClaw and confirm the plugin was installed successfully | | plugins.allow is empty warning | Add openclaw-nowledge-mem to plugins.allow if the user wants explicit trust | | Remote config seems ignored | Check whether ~/.nowledge-mem/openclaw.json is overriding plugin settings | | Local mode unexpectedly talks to a remote server | Check for stale NMEM_API_URL / NMEM_API_KEY in the environment or an overriding ~/.nowledge-mem/openclaw.json | | Plugin tools missing | Ensure the plugin is in plugins.allow: ["openclaw-nowledge-mem"]. Do not put nowledge_mem_* tool names in tools.allow — OpenClaw silently strips plugin-only allowlists. No tools.* config is needed; plugin tools load automatically when the plugin is allowed. |

Notes for Agents

• Human docs and AI setup instructions are different things. Keep the human explanation short and concrete.
• Do not dump the whole configuration model on the user up front.
• Do not reduce Nowledge Mem to "OpenClaw memory." The real value is shared context across tools and growth of knowledge over time.