Nowledge Mem OpenClaw Plugin

Local-first knowledge graph memory for OpenClaw agents, powered by Nowledge Mem.

Your AI tools forget. We remember. Everywhere. This plugin gives OpenClaw both lossless session memory and the same graph-connected memory layer your other AI tools can use too. Every OpenClaw conversation is captured as a searchable thread, important moments can distill into linked memories with sourceThreadId, and knowledge from Claude, Cursor, web chats, and imported threads stays searchable inside OpenClaw. Local-first by default, with remote mode when you want a shared server.

This is not a flat note store. Nowledge Mem links related knowledge into a graph, tracks how ideas evolve, deduplicates repeated context, and can run background intelligence to produce daily briefings, contradiction checks, and crystals from converging evidence. OpenClaw can search that same growing memory layer instead of starting from scratch every time.

Requirements

• Nowledge Mem desktop app or nmem CLI
• OpenClaw >= 2026.5.3 for ClawHub installs. Older 2026.4.x builds can reject current ClawHub packages with an archive integrity mismatch before the plugin is installed.

Installation

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

OpenClaw's installer writes the install record, enables the plugin, and switches the memory slot to openclaw-nowledge-mem. On current OpenClaw builds, that same install flow may also set plugins.slots.contextEngine to openclaw-nowledge-mem. Plugin 0.8.18+ accepts that automatically as a compatibility alias.

Grant the conversation hook used as the thread-sync safety net:

openclaw config set plugins.entries.openclaw-nowledge-mem.hooks.allowConversationAccess true --strict-json

If openclaw config get tools shows a restrictive profile such as coding, preserve its existing policy and add openclaw-nowledge-mem to tools.alsoAllow. If tools.allow already exists, add the plugin id there instead. The plugin id expands to all manifest-declared tools; do not list individual nowledge_mem_* names.

To update the plugin, re-run the ClawHub install with --force:

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

Use this instead of openclaw plugins update openclaw-nowledge-mem when an old install record is pinned to a specific version.

Restart OpenClaw after install to load it.

If OpenClaw previously blocked the ClawHub package with a warning about dangerous code patterns detected, update to 0.8.17+. That release removes test-only files from the published ClawHub artifact, so the installer no longer scans harmless development fixtures as if they were runtime plugin code.

If you prefer the default resolver path, bare package names also work because OpenClaw resolves external plugins from ClawHub first and then falls back to npm:

openclaw plugins install @nowledge/openclaw-nowledge-mem

If you need a pinned local checkout for validation or development, use local linking:

git clone https://github.com/nowledge-co/community.git
cd community/nowledge-mem-openclaw-plugin
openclaw plugins install --link .

Agent-assisted setup

If another AI agent is helping you install this plugin, point it at the bundled SKILL.md.

Copyable instruction:

Read https://raw.githubusercontent.com/nowledge-co/community/main/nowledge-mem-openclaw-plugin/SKILL.md and follow it to install, configure, verify, and explain Nowledge Mem for OpenClaw.

That guide is written for AI agents, not for humans. It handles local vs remote mode, optional API auth, trust pinning, restart, verification, and next steps.

Recommended hardening

If you keep non-bundled plugins on an explicit trust allowlist, add:

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

plugins.allow is id-based, not source-based. If you also use plugins.load.paths or openclaw plugins install --link, review those paths too. An allowlist trusts the active plugin with that id; it does not pin where it came from.

Manual config or verification

If you manage config manually, or you want to verify what the installer selected, this is the expected shape:

{
  "plugins": {
    "slots": { "memory": "openclaw-nowledge-mem" },
    "entries": {
      "openclaw-nowledge-mem": {
        "enabled": true
      }
    }
  }
}

By default the agent gets 10 tools on demand, a behavioral skill that teaches it when to search and save, a short always-on system hint, and end-of-session capture. Context Bundle / Working Memory injection is optional and controlled by sessionContext.

Remote mode

Connect to a Nowledge Mem server running elsewhere (a VPS, a home server, or a shared team instance). See remote access guide for server setup.

Enable the plugin the same way as local mode, then set apiUrl and apiKey in the OpenClaw plugin settings.

Or use the shared config file at ~/.nowledge-mem/config.json so OpenClaw, nmem, Bub, Claude Code, and other integrations all point at the same remote Mem:

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

Legacy ~/.nowledge-mem/openclaw.json is still honored first for backward compatibility.

The resolved apiUrl and apiKey are reused across the plugin: CLI-backed memory tools and API-backed thread sync both talk to the same backend. The apiKey is never passed as a CLI argument and is never logged.

Spaces

Spaces are optional. OpenClaw should choose one ambient lane only when the profile or process already belongs to one real project or agent lane.

The OpenClaw plugin settings can own that lane directly:

{
  "space": "Research Agent",
  "spaceTemplate": "agent-${OPENCLAW_AGENT_NAME}"
}

Use space when one OpenClaw profile belongs to one stable lane. Use spaceTemplate only when your launcher or host environment already sets a trustworthy variable that identifies the lane. If your OpenClaw runtime does not expose per-AI Identity to plugins, do not fake it. Use one profile/process per lane or stay on Default.

If you are running OpenClaw from a launcher or script with no richer config surface, you can still set one session-wide fallback lane with:

NMEM_SPACE="Research Agent"

Nowledge Mem's CLI-backed Working Memory, memory search/save, and the plugin's API-backed thread/feed fallbacks will then stay in that lane together. There is no second OpenClaw-only vault setting; the shared Mem boundary is still one hidden space key, but humans and agents should normally work with the space name instead.

For multi-agent orchestrators, set NMEM_AGENT_ID=<agent-slug> per spawned OpenClaw worker. Add NMEM_SPACE only when that run should override the AI Identity's default space. NMEM_HOST_AGENT_ID is for advanced external aliases. Context Bundle will use the stable identity while keeping source_app=openclaw for provenance. Keep these as launcher environment variables instead of plugin config keys so OpenClaw's strict config validation remains stable.

Shared spaces, default retrieval, and agent guidance still live in Mem's own space profile. OpenClaw chooses the lane and preserves it across transports; it should not duplicate the profile semantics.

Configure via WebUI of OpenClaw

How It Works

Per-Turn Flow

Every user message triggers hooks before the agent sees it, then the agent decides which tools to call.

When Each Tool Gets Called

The behavioral skill and always-on hook nudge the agent to search before answering and save after deciding. Here's when each tool fires:

Session Lifecycle (Automatic Capture)

When sessions end, conversations are captured and optionally distilled. No user action needed.

Key points:

• Thread capture is unconditional: every conversation is saved and searchable via nowledge_mem_thread_search
• Thread sync is incremental: the plugin preserves the real transcript but appends only the unsynced tail instead of replaying the whole session
• LLM distillation only runs at agent_end, not during compaction/reset checkpoints
• Distilled memories carry sourceThreadId, linking them back to the source conversation
• Cooldown (digestMinInterval, default 300s) prevents burst distillation

Progressive Retrieval (Memory -> Thread -> Messages)

Memories distilled from conversations carry a sourceThreadId. This creates a retrieval chain:

Direct conversation search also works:

Two entry points:

1. From a memory: memory_search or memory_get returns sourceThreadId, then fetch the source conversation
2. Direct search: nowledge_mem_thread_search finds conversations by keyword, then fetch any result

Corpus Supplement (Dreaming Integration)

When OpenClaw's memory-core is the primary memory slot and Nowledge Mem runs alongside it, you can enable corpusSupplement: true. This registers Nowledge Mem as a searchable corpus inside memory-core's recall pipeline and three-phase dreaming system (light, deep, REM).

What happens:

• Every time memory-core runs memory_search, it also searches Nowledge Mem's knowledge graph via the supplement.
• Recalled Nowledge Mem content accumulates frequency and relevance scores in memory-core's short-term store.
• High-scoring content is promoted to MEMORY.md during deep-phase dreaming (daily, 3 AM).
• The plugin's own search-based recall is automatically disabled to avoid duplicates. Startup context injection continues as before.

When to enable: When memory-core is the memory slot and you want your cross-tool knowledge graph to participate in OpenClaw's native dreaming cycle. Most users have Nowledge Mem as the memory slot directly, so this defaults to false.

Requires OpenClaw >= 2026.4.5.

As of 0.8.15, this works without local source edits. The plugin now stays active beside memory-core for supplement mode, while leaving memory-core's own memory_search / memory_get pair in place.

If OpenClaw stores a top-level dreaming object on this plugin while it owns the memory slot, that is expected. Dreaming remains OpenClaw-native host config; this plugin accepts it so memory-core can run the dreaming engine alongside Nowledge Mem without registration errors.

Three Modes at a Glance

Tools

OpenClaw Memory Compatibility

These satisfy the OpenClaw memory slot contract and activate the "Memory Recall" section in OpenClaw's system prompt.

memory_search - Multi-signal recall using embedding, BM25, label match, graph signals, and recency decay. Returns structured source paths (nowledgemem://memory/<id>) for follow-up with memory_get or nowledge_mem_connections. Also returns relevant past conversation snippets (relatedThreads) and sourceThreadId (link to the conversation the memory was distilled from) when available.

memory_get - Read a specific memory by ID or path. Supports MEMORY.md alias for Working Memory. Returns sourceThreadId when the memory was distilled from a conversation.

Nowledge Mem Native

These reflect capabilities unique to Nowledge Mem's knowledge graph architecture.

nowledge_mem_save - Capture structured knowledge with type classification, labels, and temporal context.

text:             "We decided to use PostgreSQL with JSONB for the task events table"
title:            "Task events database choice"
unit_type:        decision
importance:       0.8
labels:           ["backend", "architecture"]
event_start:      2024-03
temporal_context: past
> Saved: Task events database choice [decision] (id: mem_abc) - labels: backend, architecture - event: 2024-03

Eight memory types: fact, preference, decision, plan, procedure, learning, context, event. Each becomes a typed node in the knowledge graph. Labels enable filtering in memory_search. event_start records when something happened, not just when you saved it, powering bi-temporal search.

nowledge_mem_context - Read startup context. On current Nowledge Mem installs this is Context Bundle: owner identity, AI Identity, active space, active rules, Working Memory, and KFS paths. Older nmem clients fall back to today's Working Memory. Patch mode still edits Working Memory sections.

nowledge_mem_connections - Explore the knowledge graph around a topic or memory. Returns connected memories, EVOLVES version chains (how understanding has grown), related entities, and source document provenance (which files or URLs knowledge was extracted from).

memoryId: "mem_abc"
> Connected memories:
  - PostgreSQL optimization patterns: Use JSONB GIN indexes for...
  - Redis caching layer decision: For frequently accessed task lists...
  Source documents (provenance):
  - api-spec.pdf (file): API specification for task management...
  Related entities:
  - PostgreSQL (Technology)
  - Task Management API (Project)
  Knowledge evolution:
  - superseded by newer understanding (version chain)

nowledge_mem_timeline - Browse your knowledge history chronologically. Use for questions like "what was I working on last week?" or "what happened yesterday?". Groups activity by day: memories saved, documents ingested, insights generated, and more.

last_n_days: 7
> 2026-02-18:
  - [Memory saved] UV guide - Python toolchain setup
  - [Knowledge extracted from document] api-spec.pdf
2026-02-17:
  - [Daily briefing] Focus: NebulaGraph, AI biotech...
  - [Insight] Connection between Redis caching and...

nowledge_mem_forget - Delete a memory by ID or search query. Supports user confirmation when multiple matches are found.

Thread Tools

nowledge_mem_thread_search - Search past conversations by keyword. Returns matched threads with message snippets and relevance scores. Use when the user asks about a past discussion or wants to find a conversation from a specific time.

nowledge_mem_thread_fetch - Fetch full messages from a conversation thread with pagination. Pass a sourceThreadId from memory results or a threadId from thread search. Supports offset and limit for progressive retrieval of long conversations.

threadId: "openclaw-db-arch-a1b2c3"
offset: 0, limit: 50
-> Thread: "Database architecture discussion" (128 messages)
  [user] We need to decide on the database for task events...
  [assistant] Based on the requirements, PostgreSQL with JSONB...
  ... (126 more messages, use offset=50 for next page)

Operating Modes

The plugin supports three modes. Choose based on how much you want to guarantee versus how much token budget you're willing to spend.

Which mode should you use?

• Most users: start with default. The agent gets behavioral guidance nudging it to search before answering and save after deciding. It works well for most conversations.
• Short sessions or critical accuracy: enable sessionContext. This guarantees relevant memories are present from the first turn. The agent doesn't need to decide whether to search. The tradeoff is a larger per-turn prompt.
• Full manual control: set sessionDigest: false. You control what gets saved (via /remember or nowledge_mem_save) and nothing is captured automatically.

Session Context (sessionContext, default: false)

When enabled, the plugin injects Working Memory and relevant search results at prompt time. The behavioral guidance automatically adjusts to tell the agent that context is already present, so memory_search should only be used for specific follow-up queries, not broad recall. This prevents the agent from redundantly searching for the same context that was just injected.

Useful for giving the agent immediate context without waiting for it to search proactively.

Session Digest (sessionDigest, default: true)

When enabled, two things happen at agent_end, after_compaction, and before_reset:

1. Thread capture (always). The full conversation is appended to a persistent thread. Unconditional, idempotent by message ID.

2. LLM distillation (when worthwhile). A lightweight LLM triage determines if the conversation has save-worthy content. If yes, a full distillation pass creates structured memories with types, labels, and temporal data. Language-agnostic, works in any language.

Design Decisions

Honest answers to common questions about how the memory system works.

Does the agent always search before answering?

The plugin uses two layers to drive recall. First, a behavioral skill (auto-discovered by OpenClaw) teaches the agent when and how to use memory tools. Second, a short always-on system hint reminds it to "search before answering questions about prior work, decisions, dates, people, preferences, or plans." In practice, modern LLMs follow this directive guidance reliably for knowledge-related questions. For messages that don't need past context (like "hello" or "thanks"), the agent skips the search, which is the right tradeoff. If guaranteed recall matters for your use case, enable sessionContext: true. That injects relevant memories at prompt time, before the agent even processes your message.

What stops the agent from saving duplicate memories?

Two layers. First, the plugin checks for near-identical existing memories before every save. If a memory with >=90% similarity already exists, the save is skipped and the existing memory is returned instead. Second, Nowledge Mem's Knowledge Agent runs in the background and handles deeper deduplication, identifying semantic overlap across memories and linking them via EVOLVES chains (replaces, enriches, confirms, or challenges). The plugin handles obvious duplicates; the Knowledge Agent handles subtle ones.

When sessionContext is on, will the agent search again and get duplicate context?

The behavioral guidance adjusts when sessionContext is enabled. Instead of "search with memory_search when prior context would help," it tells the agent "relevant memories have already been injected, use memory_search only for specific follow-up queries." This reduces redundant searches. The injected context and manual search results are in different XML blocks, so even if overlap occurs, it doesn't confuse the agent.

What happens to conversations I don't explicitly save?

With sessionDigest enabled (the default), every conversation is saved as a searchable thread. The boundary follows OpenClaw's own session lifecycle: one active chat becomes one Mem thread, /new or /reset starts a fresh thread, and internal compaction keeps appending to the same thread instead of forking a duplicate. Context Engine capture and hook-based capture still converge on the same conversation. Internal helper sessions like temp:* and subagent runs are excluded, so your recent threads stay focused on real chats. On top of thread capture, a lightweight LLM triage checks if the conversation contained decisions, insights, or preferences worth keeping as structured memories. If yes, they're extracted with proper types, labels, and temporal context. If the conversation was routine ("fix this typo"), nothing extra is saved.

Can memories be wrong or outdated?

Yes. Memories are what you or the AI saved at a point in time. Nowledge Mem's EVOLVES chains track how understanding changes: a newer memory can supersede, enrich, or challenge an older one. The Knowledge Agent identifies these relationships automatically. When you search, the relevance scoring considers recency, so newer memories rank higher by default.

Slash Commands

CLI Commands

openclaw nowledge-mem search "database optimization"
openclaw nowledge-mem status

Configuration

The plugin defaults work for local Mem, and openclaw plugins install enables the plugin and selects the memory slot. Current OpenClaw releases still require one explicit conversation-hook grant for the agent_end capture fallback. Restrictive tool profiles also need the plugin id added to their effective allow policy; see Installation above.

To change settings, use the OpenClaw plugin settings UI. Changes take effect on restart.

Customize without editing the plugin

OpenClaw does not currently have a separate user-owned instruction file in this integration contract.

• Use the OpenClaw plugin settings UI for supported behavior changes such as sessionContext, digest controls, remote credentials, and space selection.
• If you need additional behavioral guidance, customize OpenClaw's own prompt or agent configuration surface.
• Do not patch the installed plugin source under the OpenClaw extensions directory.

Remote access

Configure this machine once:

nmem config client set url https://<your-url>
nmem config client set api-key nmem_...

That writes the shared local client config used by nmem, OpenClaw, Bub, Claude Code, and other integrations on this machine. You can still set Server URL and API key in the OpenClaw dashboard if you want plugin-specific overrides.

See Access Mem Anywhere.

Advanced: environment variables

For CI, scripts, or Docker deployments, all options also support environment variables:

NMEM_SESSION_CONTEXT=true
NMEM_SESSION_DIGEST=true
NMEM_DIGEST_MIN_INTERVAL=300
NMEM_MAX_CONTEXT_RESULTS=5
NMEM_RECALL_MIN_SCORE=0
NMEM_MAX_THREAD_MESSAGE_CHARS=800
NMEM_CORPUS_SUPPLEMENT=false
NMEM_CORPUS_MAX_RESULTS=5
NMEM_CORPUS_MIN_SCORE=0
NMEM_API_URL=https://...
NMEM_API_KEY=your-key

Priority

Plugin-specific settings:

openclaw.json (legacy) > OpenClaw dashboard > env vars > defaults

Credentials (apiUrl, apiKey):

openclaw.json (legacy) > OpenClaw dashboard > config.json (shared) > env vars > defaults

~/.nowledge-mem/openclaw.json is still honored for backward compatibility but is no longer the recommended path. New users should configure plugin-specific settings via the OpenClaw dashboard and shared credentials via nmem config client ....

Use nowledge_mem_status (or openclaw nowledge-mem status) to see where each value comes from.

Trust warning after install

If OpenClaw logs a warning like plugins.allow is empty; discovered non-bundled plugins may auto-load, the plugin is installed correctly. OpenClaw is warning that you have not pinned trust for non-bundled plugins yet. Add:

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

If you also use linked or workspace copies, review plugins.load.paths before relying on an allowlist. OpenClaw allowlists plugin ids, not install provenance.

Troubleshooting

Only memory_search and memory_get show up — saves go to local markdown files

The memory slot is probably still set to the built-in memory-core. OpenClaw 3.22+ defaults to memory-core when no explicit slot is configured. Reinstall to reset the slot automatically:

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

Or set the slot manually in ~/.openclaw/openclaw.json:

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

Restart OpenClaw after either change.

Plugin tools not available

All 10 plugin tools register automatically when the plugin loads. No tool-level config is needed — just make sure the plugin itself is trusted:

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

If OpenClaw logs must declare contracts.tools before registering agent tools, update the plugin to 0.8.27 or newer and restart OpenClaw. That error means a newer OpenClaw build is enforcing plugin tool ownership metadata before it accepts runtime tool registration.

corpusSupplement: true is set, but startup still logs corpus=false

Update to 0.8.15 or newer. Older builds could disable the plugin too early when memory-core owned the memory slot, which made supplement mode look unavailable even on new OpenClaw builds.

If openclaw status shows a CRITICAL warning about plugins.allow, this is the fix. Run nowledge_mem_status inside a conversation to check both plugin trust and memory slot status.

Do not list nowledge_mem_* tool names in tools.allow — OpenClaw silently strips allowlists that contain only plugin entries, so the config looks active but does nothing.

Memory tools still work, but thread auto-sync does not

This is usually a capture-path issue, not a search/save issue:

• memory tools use the local nmem CLI
• thread auto-sync uses the Mem HTTP API
• cron / isolated automation sessions are intentionally excluded from capture in 0.8.x

Run nowledge_mem_status in a conversation and check, in this order:

• the plugin is loaded
• sessionDigest is still true
• the backend is reachable
• which capture path is active: hook events, or Context Engine afterTurn with hook fallback
• whether you changed plugin settings recently without restarting OpenClaw yet

If your config enables plugins.slots.contextEngine: "nowledge-mem":

• on 0.8.6+, Context Engine capture stays active and hooks remain enabled as a safety net
• on 0.8.5 and earlier, temporarily removing the contextEngine slot is a valid isolation step if thread sync stops while tools still work

If OpenClaw selected plugins.slots.contextEngine: "openclaw-nowledge-mem" during install, plugin 0.8.18+ treats that as the same engine. You only need to rewrite it to "nowledge-mem" if you want the config to use the canonical manual id.

Remember: OpenClaw applies plugin setting changes after restart. If you turned sessionDigest off earlier but had not restarted yet, thread sync could appear to keep working until the next restart, then stop.

What healthy OpenClaw thread sync looks like:

• one active OpenClaw chat becomes one Mem thread
• running /new or /reset starts a fresh Mem thread
• compaction does not fork a second thread for the same chat
• helper sessions like temp:slug-generator do not appear
• the synthetic /new / /reset startup prompt is not stored as the first user message

To inspect the recent synced threads directly, run:

nmem t list --source openclaw -n 20

Search timeouts with many concurrent agents

When running many agents in parallel, all searches share a single database connection. Upgrade to Nowledge Mem v0.6.12+ (backend) so scoring writes no longer block search responses.

nmem --json status fails in local mode

The Nowledge Mem backend is not running. Start it from the desktop app, or run the backend manually.

Remote mode not connecting

Run nmem config client show and confirm the effective URL and API key state. Then run nmem --json --api-url "$URL" status to verify the server is reachable.

What Makes This Different

• Local-first: no API key, no cloud account. Your knowledge stays on your machine.
• Knowledge graph: memories are connected nodes, not isolated vectors. EVOLVES edges track how understanding grows over time.
• Source provenance: the Library ingests PDFs, DOCX, URLs. Extracted knowledge links back to the exact document section it came from.
• Working Memory: an AI-generated daily briefing that evolves, not a static user profile.
• Cross-AI continuity: knowledge captured in any tool (Cursor, Claude, ChatGPT) flows to OpenClaw and back.
• Typed memories: 8 knowledge types mapped to graph node properties. Structured understanding, not text blobs.
• Multi-signal search: not just semantic similarity. Combines embedding, BM25 keyword, label match, graph & community signals, and recency/importance decay. See Search & Relevance.

License

MIT