@nowledge/openclaw-nowledge-mem 0.2.7

package/CHANGELOG.md

@@ -0,0 +1,211 @@
+# Changelog
+
+All notable changes to the Nowledge Mem OpenClaw plugin will be documented in this file.
+
+## [0.2.7] - 2026-02-18
+
+### Added — Gap closures: date range, EVOLVES CLI, WM section edit
+
+**Feed date range filtering**
+
+- `nowledge_mem_timeline` now accepts `date_from` and `date_to` (YYYY-MM-DD) for exact temporal queries ("what was I doing last Tuesday?").
+- `client.feedEvents()` passes `--from`/`--to` to `nmem f`; falls back to API `?date_from=&date_to=` params.
+- Backend `GET /agent/feed/events` now accepts `date_from` / `date_to` query params alongside `last_n_days`.
+- CLI: `nmem f --from 2026-02-17 --to 2026-02-17`
+
+**EVOLVES version chain via CLI**
+
+- `nmem g evolves <id>` — new CLI command showing the full EVOLVES chain for a memory (replaces/enriches/confirms/challenges relations).
+- `client.graphEvolves()` — new client method using `nmem g evolves`; falls back to `GET /agent/evolves?memory_id=<id>`.
+- `connections.js` now uses `client.graphEvolves()` instead of a raw API call. "Knowledge evolution" section now correctly shows direction (→ newer / ← older) relative to the queried memory.
+- Backend `GET /agent/evolves` now accepts `memory_id` query param to filter edges for a specific memory.
+
+**Working Memory section-level edit**
+
+- `nmem wm patch --heading "## Notes" --content/--append` — new CLI subcommand. Does client-side read-modify-write: reads WM, patches just the target section, writes the full doc back.
+- `client.patchWorkingMemory(heading, { content, append })` — new client method.
+- `nowledge_mem_context` now supports optional `patch_section` + `patch_content`/`patch_append` parameters. An agent can now update one section of Working Memory without destroying the rest.
+- Includes a JS `patchWmSection()` helper in `client.js` for the API fallback path (for CLI versions that predate `wm patch`).
+
+## [0.2.6] - 2026-02-18
+
+### Added — Rich save: labels, event_start, temporal_context, unit_type fixed
+
+## [0.2.5] - 2026-02-18
+
+### Added — Remote mode configuration
+
+- `apiUrl` config option: set to your remote server URL to use Nowledge Mem across devices or in a team. Leave empty for local mode (default: `http://127.0.0.1:14242`).
+- `apiKey` config option: API key for remote access. Marked `"secret": true` in uiHints so OpenClaw can mask it in the UI. **Never logged, never passed as a CLI argument** — injected as `NMEM_API_KEY` env var into child processes only.
+- `NowledgeMemClient` now accepts `{ apiUrl, apiKey }` credentials at construction time. Both config values and `NMEM_API_URL` / `NMEM_API_KEY` env vars are supported; plugin config wins over env vars.
+- Initialization log now shows `mode=remote → https://...` vs `mode=local` (key never appears in logs).
+- `_spawnEnv()` helper: builds per-spawn env with credentials injected; `_apiUrlArgs()` adds `--api-url` flag only when not local.
+
+## [0.2.4] - 2026-02-18
+
+### Changed — CLI-first architecture
+
+All operations now go through the `nmem` CLI instead of direct API calls.
+This is a structural alignment that makes every feature work in remote mode
+(`NMEM_API_URL` + `NMEM_API_KEY`) without any plugin changes.
+
+- `client.graphExpand()` — uses `nmem g expand <id>`; falls back to API on older CLI
+- `client.feedEvents()` — uses `nmem f`; falls back to API on older CLI
+- `client.search()` — CLI now returns `relevance_reason`, `importance`, `labels`,
+  temporal fields natively; `searchRich()` is now an alias for `search()`
+- `client.searchTemporal()` — uses `nmem m search --event-from/--recorded-from`
+  CLI args; falls back to API if CLI is pre-bi-temporal-update
+- `client._normalizeMemory()` — canonical memory shape shared across all search paths
+- Removed `client.apiJson()` usage in `connections.js` and `timeline.js`
+- `connections.js`: `client.apiJson()` retained only for the `/agent/evolves` chain
+  (no CLI command for this yet — tracked as future improvement)
+
+## [0.2.3] - 2026-02-18
+
+### Changed — Graph Transparency & Scoring Visibility
+
+- `nowledge_mem_connections`: completely rewritten output format
+  - Edges are now JOIN-ed to their target nodes — each connection shows its relationship type and strength
+  - Sections organized by edge type: "Synthesized from N source memories" (CRYSTALLIZED_FROM), "Knowledge evolution" (EVOLVES), "Sourced from document" (SOURCED_FROM), "Entities mentioned" (MENTIONS)
+  - EVOLVES sub-relations are labeled: supersedes, enriches, confirms, challenges
+  - Each connected memory includes its `id` for direct follow-up with `memory_get` or `nowledge_mem_connections`
+- `memory_search`: now always uses API path (`searchRich`) — returns `matchedVia` with scoring breakdown
+  - e.g. `"matchedVia": "Text Match (100%) + Semantic Match (69%) | decay[imp:high]"`
+  - Also returns `importance` per result
+  - Response `mode` field updated to `"multi-signal"` to reflect actual behavior
+- `nowledge_mem_timeline`: timeline entries now include `(id: <memoryId>)` hint for events with linked memories — enables immediate chaining to `nowledge_mem_connections`
+- `nowledge_mem_timeline`: `event_type` filter values documented in tool description for model discoverability
+- Auto-recall hook: uses `searchRich` instead of CLI search — shows scoring breakdown in recalled context
+
+### Added
+
+- `client.searchRich()` — convenience wrapper for `searchTemporal` without temporal filters; always returns `relevanceReason`
+
+## [0.2.2] - 2026-02-18
+
+### Added
+
+- `memory_search` now supports bi-temporal filtering:
+  - `event_date_from` / `event_date_to` — when the fact/event happened (YYYY, YYYY-MM, YYYY-MM-DD)
+  - `recorded_date_from` / `recorded_date_to` — when the memory was saved to Nowledge Mem
+  - Uses API-direct path (`client.searchTemporal`) so it works regardless of installed CLI version
+  - Results include `eventStart`, `eventEnd`, `temporalContext` when available
+- `client.searchTemporal()` — new method wrapping `/memories/search` bi-temporal API directly
+
+## [0.2.1] - 2026-02-18
+
+### Added
+
+- `nowledge_mem_timeline` tool: temporal feed browser wrapping `/agent/feed/events`. Answers "what was I working on last week?" with a day-grouped activity timeline. Supports `last_n_days`, `event_type`, and `tier1_only` filters.
+- `memory_search` description now surfaces the full scoring pipeline (embedding + BM25 + labels + graph + decay)
+- Recall hook updated: explicit tool routing for temporal queries (`nowledge_mem_timeline`) vs topic queries (`memory_search`/`nowledge_mem_connections`)
+
+## [0.2.0] - 2026-02-18
+
+### Changed — Tool Set Redesign
+
+Redesigned from first principles around Nowledge Mem's v0.6 architecture.
+This version reflects our genuine strengths: knowledge graph, structured types,
+Working Memory, and cross-AI continuity.
+
+### Added
+
+- `nowledge_mem_save` tool: structured knowledge capture with `unit_type` parameter (fact, preference, decision, plan, procedure, learning, context, event) — replaces generic `nowledge_mem_store`
+- `nowledge_mem_context` tool: read today's Working Memory daily briefing — replaces `nowledge_mem_working_memory` with clearer naming
+- `nowledge_mem_connections` tool: explore knowledge graph around a topic — returns connected memories, EVOLVES chains, related entities, and Source document provenance (SOURCED_FROM edges from Library). This is our graph-native differentiator.
+- `nowledge_mem_forget` tool: delete memories by ID or search query with confirmation flow
+- `/forget` slash command: quick memory deletion from chat
+- Capture quality gate: prompt injection detection, question filtering, memory-trigger pattern matching
+- Recall context now includes tool guidance for Nowledge Mem native tools
+
+### Removed
+
+- `nowledge_mem_search` tool: redundant with `memory_search`. One search tool, done right.
+- `nowledge_mem_store` tool: replaced by `nowledge_mem_save` with richer `unit_type` model
+- `nowledge_mem_working_memory` tool: replaced by `nowledge_mem_context`
+
+### Fixed
+
+- Capture hook no longer saves questions or prompt-injection payloads as memory notes
+- Recall context properly escapes memory content for prompt safety
+
+## [0.1.5] - 2026-02-17
+
+### Fixed
+
+- Aligned plugin ids with OpenClaw installer id derivation so `openclaw plugins install --link` and npm installs work without config validation failures:
+  - package id (`@nowledge/openclaw-nowledge-mem`) -> plugin id (`openclaw-nowledge-mem`)
+  - manifest/export ids now match installer-derived id
+
+### Changed
+
+- Updated docs/examples to use:
+  - `plugins.slots.memory = "openclaw-nowledge-mem"`
+  - `plugins.entries.openclaw-nowledge-mem`
+
+## [0.1.4] - 2026-02-17
+
+### Added
+
+- OpenClaw memory-compatible tool aliases:
+  - `memory_search` (structured recall output with source paths)
+  - `memory_get` (fetch by `nowledgemem://memory/<id>` or raw memory ID)
+- `after_compaction` capture hook to preserve thread continuity across compaction cycles
+
+### Changed
+
+- Auto-capture is now append-first with deterministic thread IDs:
+  - Attempts `append` with deduplication
+  - Falls back to `create` on first write
+- Added CLI/API fallback in client for mixed nmem versions (append/create with explicit thread IDs)
+- Added retry-safe append `idempotency_key` propagation for transcript batches
+- Updated docs to require `plugins.slots.memory = "nowledge-mem"` for full memory-slot replacement behavior
+
+## [0.1.3] - 2026-02-17
+
+### Changed
+
+- Replaced `autoCapture` no-op with real capture pipeline:
+  - `agent_end`: stores high-signal user memory via `nmem m add`
+  - `before_reset`: snapshots recent session messages via `nmem t create`
+- Added resilient session snapshot fallback by reading `before_reset.sessionFile` JSONL when hook payload messages are not present
+
+## [0.1.2] - 2026-02-17
+
+### Fixed
+
+- Aligned tool handler signature with OpenClaw runtime (`execute(toolCallId, params)`)
+- Hardened `nmem` execution path to avoid shell interpolation/injection
+- Updated package metadata to `openclaw.extensions` for plugin install/discovery compatibility
+- Corrected manifest `uiHints` structure and `maxRecallResults` type (`integer`)
+- Added prompt-safety escaping for recalled memory context
+- Fixed store tool handling for `importance: 0`
+- Updated docs for current OpenClaw install/config flow
+
+### Changed
+
+- `autoCapture` now logs a warning and skips capture because nmem-cli does not support OpenClaw thread/message persistence
+
+## [0.1.1] - 2026-02-15
+
+### Changed
+
+- Removed unused `serverUrl` configuration from schema/docs (plugin is local `nmem` CLI based)
+- Improved recall hook prompt to present injected context as central external memory
+- Added UI hint details for `maxRecallResults`
+
+## [0.1.0] - 2026-02-14
+
+### Added
+
+- **Tools**: 3 agent tools
+  - `nowledge_mem_search` : semantic search across personal knowledge base
+  - `nowledge_mem_store` : save insights, decisions, and findings
+  - `nowledge_mem_working_memory` : read daily Working Memory briefing
+- **Hooks**:
+  - `before_agent_start` : auto-recall Working Memory + relevant memories
+  - `agent_end` : auto-capture conversation thread
+- **Slash commands**: `/remember`, `/recall`
+- **CLI**: `openclaw nowledge-mem search`, `openclaw nowledge-mem status`
+- **nmem CLI integration**: local-first, no API key required
+- **Plain JavaScript** (ES modules): no build step, no TypeScript dependency

package/README.md

@@ -0,0 +1,191 @@
+# Nowledge Mem OpenClaw Plugin
+
+Local-first knowledge graph memory for [OpenClaw](https://openclaw.ai) agents, powered by [Nowledge Mem](https://mem.nowledge.co).
+
+Your AI tools forget. We remember. Everywhere. This plugin gives your OpenClaw agents persistent, graph-connected memory across WhatsApp, Telegram, Discord, Slack, and every channel OpenClaw supports. All data stays on your machine.
+
+## Requirements
+
+- [Nowledge Mem](https://mem.nowledge.co) desktop app **or** `nmem` CLI
+- [OpenClaw](https://openclaw.ai) >= 2026.1.29
+
+## Installation
+
+```bash
+openclaw plugins install @nowledge/openclaw-nowledge-mem
+```
+
+### Local mode (default)
+
+Start Nowledge Mem desktop app or run `nmem serve`, then configure:
+
+```json
+{
+  "plugins": {
+    "slots": { "memory": "openclaw-nowledge-mem" },
+    "entries": {
+      "openclaw-nowledge-mem": {
+        "enabled": true,
+        "config": {
+          "autoRecall": true,
+          "autoCapture": false,
+          "maxRecallResults": 5
+        }
+      }
+    }
+  }
+}
+```
+
+### Remote mode
+
+Connect to a Nowledge Mem server running elsewhere — on a VPS, a home server, or shared team instance. See [remote access guide](https://docs.nowledge.co/docs/remote-access) for server setup.
+
+```json
+{
+  "plugins": {
+    "slots": { "memory": "openclaw-nowledge-mem" },
+    "entries": {
+      "openclaw-nowledge-mem": {
+        "enabled": true,
+        "config": {
+          "autoRecall": true,
+          "autoCapture": false,
+          "apiUrl": "https://nowledge.example.com",
+          "apiKey": "your-api-key-here"
+        }
+      }
+    }
+  }
+}
+```
+
+The `apiKey` is injected as `NMEM_API_KEY` into the nmem CLI process — never passed as a CLI argument, never logged.
+
+## 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`.
+
+**memory_get** — Read a specific memory by ID or path. Supports `MEMORY.md` alias for Working Memory.
+
+### 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 today's Working Memory: focus areas, priorities, unresolved flags, and recent activity. Generated by the Knowledge Agent each morning, updated throughout the day.
+
+**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.
+
+## Hooks
+
+These run automatically at OpenClaw lifecycle events — no agent decision-making involved. The LLM never calls a hidden "save" tool; the plugin's code fires at the right moments.
+
+### Auto-Recall (`autoRecall`, default: true)
+
+Before each agent turn, the plugin:
+
+1. Reads **Working Memory** (today's AI-generated briefing — focus areas, flags, recent activity)
+2. Searches your knowledge graph for **relevant memories** matching the current prompt
+3. Prepends both as context to the system prompt, along with **tool guidance** for Nowledge Mem tools
+
+The agent receives richer context automatically. No tool call is made; no agent action is required.
+
+### Auto-Capture (`autoCapture`, default: false)
+
+At three lifecycle points — `agent_end`, `after_compaction`, `before_reset` — the plugin does two independent things:
+
+**1. Thread transcript (always)**
+The full conversation is appended to a persistent thread in Nowledge Mem, keyed by a stable session ID. This happens unconditionally on every successful session end, regardless of what was said. The thread is searchable via `nowledge_mem_timeline` and `nmem t` commands.
+
+**2. Memory note (conditional)**
+If the last user message matches a memory-trigger pattern (decision, preference, fact, entity — e.g. "I prefer TypeScript", "we chose Postgres"), a separate structured memory is also created. Questions, slash commands, and injected-context blocks are skipped. The memory note is independent of the thread — both can happen, either, or neither.
+
+**Compaction captures**: when OpenClaw compresses a long conversation to fit the model's context window, the plugin fires `after_compaction` and appends the pre-compaction transcript to the thread. Messages that get compressed away are not lost.
+
+**Deduplication**: thread appends are idempotent by `external_id`. If the same hook fires twice (e.g. both `agent_end` and `before_reset`), messages are deduplicated — no duplicates in Nowledge Mem.
+
+**Quality gates** (memory note only): skips messages shorter than 24 characters, fewer than 5 words, questions, slash commands, prompt-injection patterns, and LLM-generated context blocks.
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/remember <text>` | Save a quick memory |
+| `/recall <query>` | Search your knowledge base |
+| `/forget <id or query>` | Delete a memory |
+
+## CLI Commands
+
+```bash
+openclaw nowledge-mem search "database optimization"
+openclaw nowledge-mem status
+```
+
+## Configuration
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `autoRecall` | boolean | `true` | Inject Working Memory + relevant memories at session start |
+| `autoCapture` | boolean | `false` | Capture knowledge notes and thread transcripts across lifecycle hooks |
+| `maxRecallResults` | integer | `5` | Max memories to recall (1-20) |
+
+## 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](https://mem.nowledge.co/docs/search-relevance).
+
+## License
+
+MIT

package/openclaw.plugin.json

@@ -0,0 +1,61 @@
+{
+	"id": "openclaw-nowledge-mem",
+	"version": "0.2.7",
+	"kind": "memory",
+	"uiHints": {
+		"autoRecall": {
+			"label": "Auto-recall at session start",
+			"help": "Inject Working Memory briefing and relevant memories when a new session begins"
+		},
+		"autoCapture": {
+			"label": "Auto-capture at session end",
+			"help": "Store high-value notes on agent_end / after_compaction / before_reset"
+		},
+		"maxRecallResults": {
+			"label": "Max recall results",
+			"help": "How many memories to inject for each recall cycle (1–20)"
+		},
+		"apiUrl": {
+			"label": "Server URL (remote mode)",
+			"help": "Leave empty for local mode (default: http://127.0.0.1:14242). Set to your remote server URL for cross-device or team access. See: https://docs.nowledge.co/docs/remote-access"
+		},
+		"apiKey": {
+			"label": "API key (remote mode)",
+			"help": "Required when connecting to a remote server. Never logged or passed as a CLI argument — injected as NMEM_API_KEY env var only.",
+			"secret": true
+		}
+	},
+	"configSchema": {
+		"type": "object",
+		"properties": {
+			"autoRecall": {
+				"type": "boolean",
+				"default": true,
+				"description": "Inject Working Memory and recalled memories at session start"
+			},
+			"autoCapture": {
+				"type": "boolean",
+				"default": false,
+				"description": "Enable memory note capture across session lifecycle hooks"
+			},
+			"maxRecallResults": {
+				"type": "integer",
+				"default": 5,
+				"minimum": 1,
+				"maximum": 20,
+				"description": "Maximum memories to recall at session start"
+			},
+			"apiUrl": {
+				"type": "string",
+				"default": "",
+				"description": "Remote server URL. Empty = local (http://127.0.0.1:14242). Example: https://nowledge.example.com"
+			},
+			"apiKey": {
+				"type": "string",
+				"default": "",
+				"description": "API key for remote access. Stored in plugin config, injected as NMEM_API_KEY env var — never logged."
+			}
+		},
+		"additionalProperties": false
+	}
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@nowledge/openclaw-nowledge-mem",
+	"version": "0.2.7",
+	"type": "module",
+	"description": "Nowledge Mem memory plugin for OpenClaw — local-first knowledge graph memory across all your AI tools",
+	"keywords": [
+		"openclaw",
+		"openclaw-plugin",
+		"memory",
+		"knowledge-graph",
+		"nowledge",
+		"nowledge-mem",
+		"ai-memory",
+		"local-first"
+	],
+	"author": {
+		"name": "Nowledge Labs",
+		"email": "hello@nowledge-labs.ai",
+		"url": "https://nowledge-labs.ai"
+	},
+	"license": "MIT",
+	"homepage": "https://mem.nowledge.co/docs/integrations/openclaw",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/nowledge-co/community.git",
+		"directory": "nowledge-mem-openclaw-plugin"
+	},
+	"bugs": {
+		"url": "https://github.com/nowledge-co/community/issues"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"files": [
+		"src/",
+		"openclaw.plugin.json",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"openclaw": {
+		"extensions": ["./src/index.js"]
+	},
+	"main": "src/index.js",
+	"scripts": {
+		"lint": "biome check .",
+		"format": "biome format --write ."
+	},
+	"peerDependencies": {
+		"openclaw": ">=2026.1.29"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^1.9.0"
+	}
+}