Merge pull request #126 from nowledge-co/dev_0611

feat(openclaw): add agent behavioral skill + directive guidance (0.6.12)

Author: wey-gu

nowledge-mem-openclaw-plugin/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to the Nowledge Mem OpenClaw plugin will be documented in this file.
 
+## [0.6.12] - 2026-03-15
+
+### Added
+
+- **Agent behavioral skill**: the plugin now registers a `skills/memory-guide/SKILL.md` skill via the OpenClaw manifest `skills[]` array. OpenClaw auto-discovers it and presents it to the agent as an available skill. The skill teaches the agent when and how to search, save, explore connections, browse timelines, fetch past conversations, and use Working Memory. This is the single biggest change for memory recall quality: agents now receive structured guidance before their first memory interaction, rather than relying on tool descriptions alone.
+
+### Changed
+
+- **Behavioral guidance is now directive**: the always-on system hint now says "Before answering questions about prior work, decisions, dates, people, preferences, or plans: search with memory_search" instead of the previous "When prior context would improve your response, search." This matches the imperative pattern that LLMs follow most reliably, and explicitly notes "natural language queries, not file paths" to prevent confusion with OpenClaw's built-in file-based memory guidance.
+
 ## [0.6.11] - 2026-03-15
 
 ### Changed

nowledge-mem-openclaw-plugin/CLAUDE.md

@@ -45,7 +45,10 @@ src/
     forget.js           - memory deletion by ID or search
     thread-search.js    - search past conversations by keyword
     thread-fetch.js     - fetch full messages from a thread with pagination
-openclaw.plugin.json - manifest + config schema (version, uiHints, configSchema)
+skills/
+  memory-guide/
+    SKILL.md            - agent behavioral skill: when/how to search, save, explore memory (auto-discovered by OpenClaw)
+openclaw.plugin.json - manifest + config schema (version, uiHints, configSchema, skills)
 ~/.nowledge-mem/openclaw.json - optional user config file (overrides OpenClaw settings when present)
 ```
 
@@ -69,10 +72,14 @@ openclaw.plugin.json - manifest + config schema (version, uiHints, configSchema)
 ### Diagnostics
 - `nowledge_mem_status` - show effective config (mode, apiUrl, apiKey set, sessionContext, sessionDigest, etc.), backend connectivity, and version. No parameters.
 
+## Skill Surface
+
+- `skills/memory-guide/SKILL.md` - agent behavioral skill auto-discovered by OpenClaw via manifest `skills[]`. Teaches the agent when/how to search, save, explore connections, fetch threads, and use Working Memory. Read on-demand when the agent identifies a memory-related task.
+
 ## Hook Surface
 
-- `before_prompt_build` (always-on) - behavioral guidance in system-prompt space: brief note telling agent to save/search proactively. Adjusts when sessionContext is on to avoid redundant searches.
-- `before_prompt_build` (sessionContext) - session context: Working Memory + `searchRich()` with `relevanceReason` in context
+- `before_prompt_build` (always-on) - directive behavioral guidance in system-prompt space: tells agent to search before answering questions about prior work/decisions/preferences, and to save decisions/learnings proactively. Explicitly notes semantic search (not file paths) to counter OpenClaw's hardcoded memory section. Adjusts when sessionContext is on to avoid redundant searches.
+- `before_prompt_build` (sessionContext) - session context: Working Memory + `searchRich()` memories with `relevanceReason`. Note: does NOT inject thread snippets — threads are available via `memory_search` tool and `nowledge_mem_thread_fetch`.
 - `agent_end` - thread capture + LLM triage/distillation (requires `sessionDigest: true`)
 - `after_compaction` - thread append
 - `before_reset` - thread append

nowledge-mem-openclaw-plugin/README.md

@@ -62,7 +62,7 @@ If you manage config manually, or you want to verify what the installer selected
 }
 ```
 
-By default the agent gets 10 tools on demand, a short always-on system hint, and end-of-session capture. Working Memory injection is optional and controlled by `sessionContext`.
+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. Working Memory injection is optional and controlled by `sessionContext`.
 
 ### Remote mode
 
@@ -115,7 +115,7 @@ flowchart TD
 
 ### When Each Tool Gets Called
 
-The behavioral hook nudges the agent to **search before answering** and **save after deciding**. Here's when each tool fires:
+The behavioral skill and always-on hook nudge the agent to **search before answering** and **save after deciding**. Here's when each tool fires:
 
 | Scenario | Tool | What happens |
 |----------|------|--------------|
@@ -322,7 +322,7 @@ Honest answers to common questions about how the memory system works.
 
 **Does the agent always search before answering?**
 
-No. The behavioral guidance nudges the agent to search, but doesn't force it. This is a deliberate tradeoff: forcing a search on every turn would add latency and cost for messages that don't need past context (like "hello" or "thanks"). In practice, modern LLMs follow behavioral guidance reliably for knowledge-related questions. 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.
+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?**
 

nowledge-mem-openclaw-plugin/openclaw.plugin.json

@@ -1,7 +1,8 @@
 {
 	"id": "openclaw-nowledge-mem",
-	"version": "0.6.11",
+	"version": "0.6.12",
 	"kind": "memory",
+	"skills": ["skills/memory-guide"],
 	"uiHints": {
 		"sessionContext": {
 			"label": "Session context injection",

nowledge-mem-openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nowledge/openclaw-nowledge-mem",
-	"version": "0.6.11",
+	"version": "0.6.12",
 	"type": "module",
 	"description": "Nowledge Mem memory plugin for OpenClaw, local-first personal knowledge base",
 	"author": {
@@ -16,6 +16,7 @@
 	},
 	"files": [
 		"src",
+		"skills",
 		"README.md",
 		"CHANGELOG.md",
 		"CLAUDE.md",

nowledge-mem-openclaw-plugin/skills/memory-guide/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: nowledge-mem-guide
+description: >
+  Cross-AI personal knowledge graph memory (Nowledge Mem). Stores memories from this tool,
+  Claude Code, Cursor, browser capture, imported documents, and more. Use when: (1) the user
+  asks about prior work, decisions, preferences, people, dates, plans, or todos, (2) the user
+  references something discussed before or says "remind me" / "what did we decide" / "what was
+  I working on", (3) the conversation produces a decision, preference, plan, or learning worth
+  keeping, (4) the user wants to browse recent activity or explore how ideas connect, (5) the
+  user asks about a past conversation or wants to find a specific thread.
+---
+
+# Nowledge Mem
+
+## Search (memory_search)
+
+Use natural language queries. This is semantic search, not file search.
+
+- "database choice for task events" (not "MEMORY.md" or file paths)
+- "meeting with Sarah about API redesign"
+- "deployment procedure for production"
+
+Results include `matchedVia` (scoring breakdown), `importance`, `labels`, `sourceThreadId`.
+
+When results include `relatedThreads`, use `nowledge_mem_thread_fetch` with the `threadId` for full conversation context. Start with a small page; fetch more via `offset` + `limit` only when needed.
+
+Bi-temporal filters narrow results by time:
+
+- `event_date_from` / `event_date_to` — when the fact happened
+- `recorded_date_from` / `recorded_date_to` — when it was saved
+
+## Save (nowledge_mem_save)
+
+Save proactively when the conversation produces a decision, preference, plan, procedure, learning, or important context. Do not wait to be asked.
+
+Structure saves:
+
+- `unit_type`: fact | preference | decision | plan | procedure | learning | context | event
+- `labels`: lowercase-hyphenated topic tags
+- `importance`: 0.0-1.0 (most: 0.5; key decisions/preferences: 0.7-0.9)
+- `event_start` / `event_end`: ISO dates when temporal
+
+Skip trivial exchanges, greetings, and meta-conversation about memory itself.
+
+## Connections (nowledge_mem_connections)
+
+Pass a `memoryId` from search results to explore related memories, evolution chains, and source documents. Edge types: EVOLVES, CRYSTALLIZED_FROM, SOURCED_FROM, MENTIONS.
+
+## Timeline (nowledge_mem_timeline)
+
+Browse recent activity grouped by day. Filter by `event_type` or exact `date_from` / `date_to` range.
+
+## Threads (nowledge_mem_thread_search + nowledge_mem_thread_fetch)
+
+Find past conversations by keyword, then progressively fetch messages. Threads span all sources: this tool, other AI tools, browser capture, imports.
+
+## Working Memory (nowledge_mem_context)
+
+Read the user's daily briefing (priorities, active projects, flags). Patch a specific section with `patch_section` + `patch_content`/`patch_append` when the conversation updates a priority or resolves a flag.
+
+## Important
+
+- Search uses natural language queries, not file paths. Never search for "MEMORY.md" or "memory/*.md".
+- When `relatedThreads` appear in results, they often contain the most useful context.
+- Use tools directly; do not tell the user to "check your memory."

nowledge-mem-openclaw-plugin/src/hooks/behavioral.js

@@ -15,22 +15,22 @@
 const BASE_GUIDANCE = [
 	"<nowledge-mem-guidance>",
 	"You have access to the user's personal knowledge graph (Nowledge Mem).",
-	"When the conversation produces something worth keeping — a decision made, a preference stated,",
-	"something learned, a plan formed, a useful discovery — save it with nowledge_mem_save. Don't wait to be asked.",
-	"When prior context would improve your response, search with memory_search.",
-	"memory_search also returns relevant past conversation snippets alongside memories.",
-	"When a memory has a sourceThreadId, fetch the full conversation with nowledge_mem_thread_fetch.",
+	"Before answering questions about prior work, decisions, dates, people, preferences, or plans:",
+	"search with memory_search using natural language queries (not file paths).",
+	"memory_search returns memories with scores, labels, and relevant past conversation snippets.",
+	"When results include a sourceThreadId, use nowledge_mem_thread_fetch for full conversation context.",
+	"When the conversation produces a decision, preference, plan, or learning, save it with nowledge_mem_save.",
 	"</nowledge-mem-guidance>",
 ].join("\n");
 
 const SESSION_CONTEXT_GUIDANCE = [
 	"<nowledge-mem-guidance>",
 	"You have access to the user's personal knowledge graph (Nowledge Mem).",
 	"Relevant memories and your Working Memory have already been injected into this prompt.",
-	"Use memory_search only when you need something specific beyond what was auto-recalled.",
-	"When the conversation produces something worth keeping — a decision made, a preference stated,",
-	"something learned, a plan formed, a useful discovery — save it with nowledge_mem_save. Don't wait to be asked.",
-	"When a memory has a sourceThreadId, fetch the full conversation with nowledge_mem_thread_fetch.",
+	"Use memory_search when you need something specific beyond what was auto-recalled (natural language queries, not file paths).",
+	"memory_search also returns relevant past conversation snippets alongside memories.",
+	"When results include a sourceThreadId, use nowledge_mem_thread_fetch for full conversation context.",
+	"When the conversation produces a decision, preference, plan, or learning, save it with nowledge_mem_save.",
 	"</nowledge-mem-guidance>",
 ].join("\n");