Merge pull request #141 from nowledge-co/dev_0613

refactor: unify all plugins with skills

Author: wey-gu

CLAUDE.md

@@ -0,0 +1,30 @@
+# Nowledge Community — Agent Guidelines
+
+## Registry
+
+[`integrations.json`](integrations.json) is the **single source of truth** for all Nowledge Mem integrations. It tracks capabilities, versions, install commands, transport, tool naming, and thread save methods.
+
+**When adding or modifying any integration, update `integrations.json` first.** Other surfaces (website `integrations.ts`, desktop app integrations view, README tables, marketplace JSONs) derive from or validate against this file.
+
+The desktop app fetches this file at runtime from `https://raw.githubusercontent.com/nowledge-co/community/main/integrations.json` for plugin update awareness. Changes to the schema (adding/removing/renaming fields) affect:
+- **Rust** (`lib.rs`): `fetch_plugin_registry`, `detect_installed_plugins`, `write_plugin_update_state`
+- **TypeScript** (`plugin-update-manager.ts`): `RegistryIntegration` interface
+- **Python** (`health.py`): `_read_plugin_update_state` reader
+
+## Behavioral Guidance
+
+[`shared/behavioral-guidance.md`](shared/behavioral-guidance.md) defines when plugins should search, save, read Working Memory, and distill. All plugins should align with this shared guidance.
+
+## Plugin Development
+
+See [`docs/PLUGIN_DEVELOPMENT_GUIDE.md`](docs/PLUGIN_DEVELOPMENT_GUIDE.md) for authoring rules, directory layout, and testing expectations.
+
+## Submodules
+
+`nowledge-mem-gemini-cli` is a nested submodule (separate repo with its own release cycle). All other integrations are normal directories in this repo.
+
+## Commit Workflow
+
+When modifying this repo as a submodule of the parent `muscat` repo:
+1. Commit inside `community/` first
+2. Then stage the updated submodule reference in the parent repo

README.md

@@ -14,6 +14,12 @@
 
 </div>
 
+## Registry
+
+The canonical source of truth for all integrations is [`integrations.json`](integrations.json). Capabilities, install commands, transport, tool naming, and thread save methods are tracked there. Update the registry first when adding or modifying integrations.
+
+For behavioral guidance (when to search, save, read Working Memory), see [`shared/behavioral-guidance.md`](shared/behavioral-guidance.md). For plugin authoring rules, see [`docs/PLUGIN_DEVELOPMENT_GUIDE.md`](docs/PLUGIN_DEVELOPMENT_GUIDE.md).
+
 ## Integrations
 
 Each directory is a standalone integration. Pick the one that matches your tool.
@@ -23,14 +29,17 @@ Each directory is a standalone integration. Pick the one that matches your tool.
 | **[Skills](nowledge-mem-npx-skills)** | `npx skills add nowledge-co/community/nowledge-mem-npx-skills` | Reusable workflow package for Working Memory, routed recall, resumable handoffs, and distillation. Prefer native packages when your tool has one. |
 | **[Claude Code Plugin](nowledge-mem-claude-code-plugin)** | `claude plugin marketplace add nowledge-co/community` then `claude plugin install nowledge-mem@nowledge-community` | Claude Code native plugin with hooks for Working Memory bootstrap, routed recall, and automatic session capture. |
 | **[Droid Plugin](nowledge-mem-droid-plugin)** | `droid plugin marketplace add https://github.com/nowledge-co/community` then `droid plugin install nowledge-mem@nowledge-community` | Factory Droid plugin with Working Memory bootstrap, routed recall, distillation, and honest `save-handoff` semantics. |
-| **[Gemini CLI](https://github.com/nowledge-co/nowledge-mem-gemini-cli)** | `git clone https://github.com/nowledge-co/nowledge-mem-gemini-cli.git` then `cd nowledge-mem-gemini-cli && gemini extensions link .` | Gemini-native context, hooks, commands, and skills for Working Memory, routed recall, real thread save, and handoff summaries. |
+| **[Gemini CLI](https://github.com/nowledge-co/nowledge-mem-gemini-cli)** | Search `Nowledge Mem` in the [Gemini CLI Extensions Gallery](https://geminicli.com/extensions/?name=nowledge-co/nowledge-mem-gemini-cli) and install | Gemini-native context, hooks, commands, and skills for Working Memory, routed recall, real thread save, and handoff summaries. |
 | **[Antigravity Trajectory Extractor](https://github.com/jijiamoer/antigravity-trajectory-extractor)** | `git clone https://github.com/jijiamoer/antigravity-trajectory-extractor.git` | Live RPC extraction for Antigravity conversation trajectories. |
 | **[Windsurf Trajectory Extractor](https://github.com/jijiamoer/windsurf-trajectory-extractor)** | `git clone https://github.com/jijiamoer/windsurf-trajectory-extractor.git` | Offline protobuf extraction for Windsurf Cascade conversation history. |
-| **[Cursor Plugin](nowledge-mem-cursor-plugin)** | Use the packaged Cursor plugin directory with Cursor's plugin workflow | Cursor-native plugin package with bundled MCP config, rules, Working Memory, routed recall, distillation, and honest `save-handoff` semantics. |
+| **[Cursor Plugin](nowledge-mem-cursor-plugin)** | Search `Nowledge Mem` in Cursor Marketplace | Cursor-native plugin package with bundled MCP config, rules, Working Memory, routed recall, distillation, and honest `save-handoff` semantics. |
 | **[Codex Prompts](nowledge-mem-codex-prompts)** | Copy `AGENTS.md` to your project | Codex-native workflow pack for Working Memory, routed recall, real session save, and distillation. |
 | **[OpenClaw Plugin](nowledge-mem-openclaw-plugin)** | `openclaw plugins install @nowledge/openclaw-nowledge-mem` | Full memory lifecycle with memory tools, thread tools, automatic capture, and distillation. |
 | **[Alma Plugin](nowledge-mem-alma-plugin)** | Search Nowledge in Alma official Plugin marketplace | Alma-native plugin with Working Memory, thread-aware recall, structured saves, and optional auto-capture. |
+| **[Bub Plugin](nowledge-mem-bub-plugin)** | `pip install nowledge-mem-bub` | Bub-native plugin: cross-tool knowledge, auto-capture via save_state, Working Memory, and graph exploration. |
 | **[Raycast Extension](nowledge-mem-raycast)** | Search Nowledge in Raycast Extension Store | Search memories from Raycast launcher. |
+| **[Claude Desktop](https://github.com/nowledge-co/claude-dxt)** | Download from [nowled.ge/claude-dxt](https://nowled.ge/claude-dxt), double-click `.mcpb` file | One-click extension for Claude Desktop with memory search, save, and update. |
+| **[Browser Extension](https://chromewebstore.google.com/detail/nowledge-memory-exchange/kjgpkgodplgakbeanoifnlpkphemcbmh)** | Install from Chrome Web Store | Side-panel capture for ChatGPT, Claude, Gemini, Perplexity, and other web AI surfaces. |
 | **[MCP](#direct-mcp)** | For tools without a dedicated Nowledge package, use [direct MCP](#direct-mcp). | Standard memory and thread tools exposed through one shared MCP server. |
 
 ## Direct MCP

docs/PLUGIN_DEVELOPMENT_GUIDE.md

@@ -0,0 +1,142 @@
+# Plugin Development Guide
+
+> Rules and conventions for building Nowledge Mem integrations. Follow these when creating a new plugin or extending an existing one.
+
+---
+
+## Transport
+
+Use `nmem` CLI as the execution layer for memory operations.
+
+| Transport | When to use | Examples |
+|-----------|------------|----------|
+| **nmem CLI** | Agent plugins that can spawn subprocesses | OpenClaw, Alma, Bub, Droid, Claude Code, Gemini CLI |
+| **MCP** | Declarative runtimes that natively speak MCP and connect to the backend MCP server | Cursor |
+| **HTTP API** | UI extensions where subprocess spawning is inappropriate | Raycast, browser extension |
+
+**CLI resolution order:**
+1. `nmem` on PATH
+2. `uvx --from nmem-cli nmem` (auto-download fallback)
+
+**Credential handling:**
+- API key via `NMEM_API_KEY` environment variable only — never as a CLI argument or in logs
+- API URL via `--api-url` flag or `NMEM_API_URL` environment variable
+- Shared config file: `~/.nowledge-mem/config.json` (`apiUrl`, `apiKey`)
+
+---
+
+## Tool Naming
+
+### Canonical convention
+
+New tools should use the **`nowledge_mem_<action>`** prefix (underscore-separated).
+
+### Platform exceptions
+
+Some platforms have strong naming conventions that take precedence:
+
+| Platform | Convention | Reason |
+|----------|-----------|--------|
+| Bub | `mem.<action>` | Bub dot-namespace convention |
+| OpenClaw | `memory_<action>` for memory-slot tools | OpenClaw memory slot convention |
+| MCP backend | `memory_<action>` | Backend-defined tool surface |
+
+### Rules
+
+1. **Never rename a published tool name.** If alignment is needed, add the new name as an alias and deprecate the old one gradually.
+2. **Document the naming convention** in `integrations.json` under `toolNaming`.
+3. **New plugins** should use `nowledge_mem_<action>` unless the platform has a documented naming convention.
+
+---
+
+## Skill Alignment
+
+### Reference the shared behavioral guidance
+
+All behavioral heuristics (when to search, when to save, when to read Working Memory) should align with `community/shared/behavioral-guidance.md`.
+
+**Platform-specific additions** (MCP tool names for Cursor, Context Engine details for OpenClaw, Bub comma commands) are kept separate from the shared heuristics.
+
+### Skill naming
+
+Skill names use kebab-case and are consistent across all plugins:
+
+| Skill | Purpose |
+|-------|---------|
+| `read-working-memory` | Load daily briefing at session start |
+| `search-memory` | Proactive recall across memories and threads |
+| `distill-memory` | Capture decisions, insights, and learnings |
+| `save-handoff` | Structured resumable summary (when no real thread importer exists) |
+| `save-thread` | Real session capture (only when supported) |
+| `check-integration` | Detect agent, verify setup, guide plugin installation |
+| `status` | Connection and configuration diagnostics |
+
+### Autonomous save is required
+
+Every integration's distill/save guidance MUST include proactive save encouragement:
+
+> Save proactively when the conversation produces a decision, preference, plan, procedure, learning, or important context. Do not wait to be asked.
+
+---
+
+## Capabilities Checklist
+
+Every integration should provide at minimum:
+
+- [ ] **Working Memory read** — load daily briefing at session start
+- [ ] **Search** — proactive recall across memories, with thread fallback
+- [ ] **Distill** — save decisions and insights (with autonomous save encouragement)
+- [ ] **Status** — connection and configuration diagnostics
+
+Optional capabilities (require platform support):
+
+- [ ] **Auto-recall** — inject relevant memories before each response
+- [ ] **Auto-capture** — save session as searchable thread at session end
+- [ ] **Graph exploration** — connections, evolution chains, entity relationships
+- [ ] **Thread save** — real transcript import (only if parser exists)
+- [ ] **Slash commands** — quick access to common operations
+
+---
+
+## Thread Save Decision
+
+Before adding thread save to a new integration:
+
+1. **Does `nmem t save --from <runtime>` already have a parser?** If yes → delegate to CLI (Tier 1)
+2. **Can the plugin capture the session via lifecycle hooks?** If yes → implement plugin-level capture (Tier 2)
+3. **Neither?** → Use `save-handoff` and be honest about it (Tier 3)
+
+**Never fake `save-thread`** in a runtime that doesn't support real transcript import.
+
+---
+
+## Registry Checklist
+
+When shipping a new integration:
+
+1. [ ] Add entry to `community/integrations.json` — **always update the registry first**
+2. [ ] Align behavioral guidance with `community/shared/behavioral-guidance.md`
+3. [ ] Use `nowledge_mem_*` tool naming (or document platform convention)
+4. [ ] Update `community/README.md` integration table
+5. [ ] Verify `nowledge-labs-website/nowledge-mem/data/integrations.ts` alignment
+6. [ ] Add marketplace entry if applicable (`.claude-plugin/`, `.cursor-plugin/`, `.factory-plugin/`)
+7. [ ] Update `nowledge-mem-npx-skills/skills/check-integration/SKILL.md` detection table
+8. [ ] Add integration docs page to website (EN + ZH)
+
+When bumping a plugin **version**:
+
+1. [ ] Update `version` field in `community/integrations.json`
+2. [ ] Verify `nowledge-labs-website/nowledge-mem/data/integrations.ts` alignment
+3. [ ] Add marketplace entry version bump if applicable
+
+### Runtime Consumers
+
+The registry is fetched at runtime by multiple consumers. Changes to schema or field
+names affect all of them:
+
+| Consumer | How it reads | What it uses |
+|----------|-------------|-------------|
+| Desktop app (Tauri) | `fetch_plugin_registry` command — fetches from GitHub, caches to disk | `id`, `name`, `version` for update awareness |
+| `nmem plugins check` CLI | Direct `httpx.get()` — fetches from GitHub, caches to `~/.nowledge-mem/` | `id`, `name`, `version` for update awareness |
+| `check-integration` npx skill | Reads detection hints at skill invocation time | `install.command`, `install.docsUrl`, detection hints |
+| Website `integrations.ts` | Manually synced (not auto-fetched) | All fields for the integrations showcase page |