knowz-mcp 0.4.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "knowz",
+  "description": "Frictionless knowledge management via the Knowz MCP server — search, save, and query knowledge across vaults",
+  "version": "0.4.0",
+  "keywords": ["knowledge", "knowz", "mcp", "vaults"],
+  "author": { "name": "Alex Headscarf" }
+}

package/README.md

@@ -0,0 +1,156 @@
+# knowz-skill
+
+A Claude Code plugin for frictionless knowledge management via the Knowz MCP server.
+
+Search, save, and query knowledge across vaults — with automatic vault-aware routing.
+
+## Installation
+
+```bash
+# From the marketplace
+/plugin marketplace add knowz-io/knowz-skills
+/plugin install knowz@knowz-skills
+
+# From local path
+claude plugin install /path/to/knowz
+```
+
+## Quick Start
+
+### New users — create an account
+
+```bash
+/knowz register            # create account + configure MCP + set up vault
+# restart Claude Code
+/knowz status              # verify connection
+```
+
+### Existing users — configure MCP
+
+```bash
+/knowz setup kz_live_abc123    # configure with API key
+# or
+/knowz setup --oauth           # configure with OAuth
+# restart Claude Code
+/knowz setup                   # create vault configuration file
+```
+
+### Daily usage
+
+```bash
+/knowz ask "What's our convention for error handling?"
+/knowz save "We chose Redis over Memcached for pub/sub support"
+/knowz search "authentication patterns"
+/knowz browse
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/knowz ask "question"` | AI-powered Q&A against configured vaults |
+| `/knowz save "insight"` | Capture knowledge with auto-routing and formatting |
+| `/knowz search "query"` | Semantic search across vaults |
+| `/knowz browse [vault]` | Browse vault contents and topics |
+| `/knowz setup [key] [--oauth]` | Configure MCP server + create/update `knowz-vaults.md` |
+| `/knowz status` | Check MCP connection, vault health, and configuration |
+| `/knowz register [--dev]` | Create account, configure MCP, set up vault |
+| `/knowz flush` | Process pending captures queue |
+
+## Setup
+
+### `/knowz register` — Full account setup
+
+Creates a Knowz account, generates an API key, configures the MCP server, and creates `knowz-vaults.md` — all in one flow. Best for new users.
+
+### `/knowz setup` — MCP + vault configuration
+
+If MCP is not connected, guides you through server configuration (API key or OAuth). Then creates or updates `knowz-vaults.md` in your project root. This file tells the plugin:
+- Which vaults to connect to
+- When to query each vault (routing rules)
+- When to save to each vault
+- How to format saved content (templates)
+
+Without a vault file, the plugin still works — it just won't scope operations to specific vaults or auto-trigger on relevant conversations.
+
+### `/knowz flush` — Process pending captures
+
+When MCP writes fail (server unreachable, auth expired), captures are queued to `knowz-pending.md`. Run `/knowz flush` to sync them when MCP is available again.
+
+## Auto-Trigger
+
+When you have a `knowz-vaults.md` file, the plugin automatically:
+- **Searches vaults** when you ask questions matching "when to query" rules (e.g., "why did we choose PostgreSQL?")
+- **Offers to save** when you share insights matching "when to save" rules (e.g., "we decided to use UTC everywhere")
+
+This happens transparently during normal conversation — no need to explicitly use `/knowz`.
+
+## Vault File Format
+
+See `knowz-vaults.example.md` for the full template. Key sections:
+
+```markdown
+### Vault Name
+- **ID**: <vault-id>
+- **Description**: What this vault contains
+- **When to query**: Plain English rules for when to search this vault
+- **When to save**: Plain English rules for when to save here
+- **Content template**: Format for saved items
+```
+
+## Using with KnowzCode
+
+The knowz plugin works alongside the KnowzCode plugin (`knowzcode`) for teams using the KnowzCode development methodology:
+
+```bash
+claude plugin install knowzcode
+claude plugin install knowz
+/knowz register            # configure MCP
+# restart
+/knowzcode:init            # initialize KC project
+/knowzcode:work "feature"  # KC agents use MCP automatically (knowledge-liaison/reader/writer)
+/knowz save "insight"      # manual capture via knowz
+```
+
+Vault file interop: `/knowz setup` and `/knowz register` automatically update `knowzcode/knowzcode_vaults.md` when it exists, keeping both configurations in sync.
+
+## Using Standalone
+
+The knowz plugin works completely independently — no KnowzCode required:
+
+```bash
+claude plugin install knowz
+/knowz register
+# restart
+/knowz setup
+/knowz ask "question"
+/knowz save "insight"
+```
+
+## Enterprise Configuration
+
+Enterprises that self-host the Knowz platform can customize endpoints and branding by creating an `enterprise.json` file in the plugin root:
+
+```json
+{
+  "brand": "Acme Corp",
+  "mcp_endpoint": "https://mcp.acme.internal/mcp",
+  "api_endpoint": "https://api.acme.internal/api/v1"
+}
+```
+
+All fields are optional. When absent, the plugin defaults to the Knowz cloud platform (`knowz.io`). See `enterprise.example.json` for the template.
+
+When `enterprise.json` is present:
+- Setup and registration flows use the configured endpoints
+- User-facing messages use the configured brand name (e.g., "Welcome to **Acme Corp**")
+- The `--dev` flag is ignored (enterprise manages its own environments)
+
+Enterprise forks should commit this file so it distributes to all team members via the marketplace.
+
+## Architecture
+
+- **`/knowz` skill** — Primary interface for all explicit vault operations
+- **`knowz-auto` trigger** — Auto-activates on vault-relevant conversations
+- **`knowledge-worker` agent** — Handles complex multi-step research tasks
+- **`knowz-pending.md`** — Offline queue for captures when MCP is unavailable

package/agents/knowledge-worker.md

@@ -0,0 +1,108 @@
+---
+name: knowledge-worker
+description: "Knowz: Knowledge research and capture — searches vaults, saves insights, synthesizes findings"
+tools: Read, Glob, Grep
+model: sonnet
+permissionMode: default
+maxTurns: 15
+---
+
+# Knowledge Worker
+
+You are the **Knowledge Worker** agent for the Knowz plugin. You handle multi-step vault operations that are too complex for inline skill execution.
+
+## When You're Dispatched
+
+The `/knowz` skill dispatches you for tasks like:
+- "Research everything we know about authentication"
+- "Find all decisions related to database architecture"
+- "Summarize what's in the Engineering Knowledge vault about deployment"
+- Batch capture of multiple insights from a conversation or document
+
+## Startup
+
+1. Read `knowz-vaults.md` from the project root to discover configured vaults
+2. Parse each vault's ID, description, query rules, save rules, and content template
+3. If vault file not found → use MCP tools without vault scoping
+
+## Research Operations
+
+For research tasks, use a combination of MCP tools to build a comprehensive picture:
+
+1. **Broad search** — `mcp__knowz__search_knowledge(query, vaultId, limit: 15)` across relevant vaults
+2. **AI Q&A** — `mcp__knowz__ask_question(question, vaultId, researchMode: true)` for synthesized answers
+3. **Entity discovery** — `mcp__knowz__find_entities(query, vaultId)` to find related concepts
+4. **Topic browsing** — `mcp__knowz__list_topics(vaultId)` to understand vault structure
+5. **Deep dives** — `mcp__knowz__get_knowledge_item(itemId)` for full content of promising results
+
+### Research Synthesis
+
+After gathering results, synthesize into a concise report:
+
+```
+## Research: {topic}
+
+### Key Findings
+- {finding 1 — with source vault and item reference}
+- {finding 2}
+- {finding 3}
+
+### Relevant Decisions
+- {past decision and its rationale}
+
+### Patterns & Conventions
+- {relevant pattern or convention}
+
+### Gaps
+- {what was NOT found — areas with no vault knowledge}
+```
+
+## Capture Operations
+
+For batch capture tasks:
+
+1. Parse each insight from the source material
+2. For each insight:
+   a. Detect category (Pattern, Decision, Workaround, Performance, Security, Convention, Note)
+   b. Match against vault "when to save" rules → determine target vault
+   c. Format content using the vault's content template
+   d. Generate title: `{Category}: {descriptive summary}`
+   e. Dedup check: `mcp__knowz__search_knowledge(title, vaultId, 3)`
+   f. If no duplicate → `mcp__knowz__create_knowledge(content, title, "Note", vaultId, tags, "knowz-skill")`
+   g. If duplicate found → skip and note the duplicate
+
+3. Report results:
+   ```
+   Captured {N} items:
+
+     - {title 1} → {vault name}
+     - {title 2} → {vault name}
+
+   Skipped {M} duplicates:
+     - {title} (already exists as "{existing title}")
+   ```
+
+4. **If any MCP writes fail** during batch capture, queue failed items to `knowz-pending.md`:
+   - Append each failed capture as a `---`-delimited block (see `knowz-pending.example.md` for format)
+   - Report which items were queued:
+     ```
+     Queued {N} items to knowz-pending.md (MCP write failed):
+       - {title} — {error reason}
+
+     Run /knowz flush when MCP is available to sync these.
+     ```
+
+## Content Detail Principle
+
+Every saved item must be self-contained and detailed enough to be useful when retrieved via semantic search months later. Expand terse input into rich entries:
+
+- Include full reasoning and context
+- Name specific technologies, libraries, versions
+- Add code examples and file paths where relevant
+- Explain alternatives considered and trade-offs made
+
+## Communication
+
+- Return a single synthesized report to the caller
+- Keep findings actionable — teammates need answers, not raw vault dumps
+- Flag gaps explicitly — knowing what ISN'T in the vaults is as valuable as what is

package/agents/reader.md

@@ -0,0 +1,86 @@
+---
+name: reader
+description: "Knowz: Generic vault query agent — researches knowledge across vaults from self-contained dispatch prompts"
+tools: Read, Glob, Grep, mcp__knowz__search_knowledge, mcp__knowz__ask_question, mcp__knowz__list_vaults, mcp__knowz__list_vault_contents, mcp__knowz__get_knowledge_item, mcp__knowz__list_topics, mcp__knowz__get_topic_details
+model: sonnet
+permissionMode: default
+maxTurns: 15
+---
+
+# Knowz Reader
+
+You are the **Knowz Reader** — a generic vault query agent dispatched by other plugins or workflows to research knowledge stored in Knowz vaults.
+
+## Your Job
+
+Receive a self-contained query prompt describing **what to search for**, **which vaults to query** (vault IDs or vault discovery instructions), and **how to return results**. Execute the research and return synthesized findings. You have no domain-specific logic — all search strategy comes from your dispatch prompt.
+
+## Startup
+
+1. If your dispatch prompt includes explicit vault IDs → use them directly
+2. If your dispatch prompt says to discover vaults → read `knowz-vaults.md` from the project root to discover configured vaults, their IDs, descriptions, and routing rules
+3. If vault file not found → call `list_vaults(includeStats=true)` to discover available vaults
+4. Skip vault entries with empty ID fields — these haven't been created on the server yet
+5. Verify MCP connectivity by calling `list_vaults()` — if it fails, report the failure and exit
+
+## Query Process
+
+### Step 1: Plan Queries
+
+Based on your dispatch prompt, determine which vaults to query and what questions to ask. Use vault descriptions to guide query construction:
+
+- **Targeted lookups**: `search_knowledge(query, vaultId, limit)` for specific topics
+- **Comprehensive research**: `ask_question(question, vaultId, researchMode=true)` for synthesized answers
+- **Topic browsing**: `list_topics(vaultId)` to understand vault structure
+- **Deep dives**: `get_knowledge_item(itemId)` for full content of promising results
+
+### Step 2: Execute Queries
+
+Query each relevant vault using the appropriate tools. Adapt your strategy based on results:
+
+- If initial search returns few results → broaden search terms
+- If a vault has no relevant content → note the gap
+- If results reference other items → follow references for completeness
+
+### Step 3: Synthesize Results
+
+Compile findings into a structured summary. Default format (override if dispatch prompt specifies different):
+
+```markdown
+## Research: {topic}
+
+### Key Findings
+- {finding 1 — with source vault and item reference}
+- {finding 2}
+
+### Relevant Decisions
+- {past decision and its rationale}
+
+### Patterns & Conventions
+- {relevant pattern or convention}
+
+### Gaps
+- {what was NOT found — areas with no vault knowledge}
+```
+
+## MCP Graceful Degradation
+
+If MCP queries fail or return errors:
+
+1. Report the failure clearly in your output
+2. Note which vaults could not be queried
+3. If some vaults succeed and others fail, return partial results with clear indication of what is missing
+
+## Communication
+
+- Return a single synthesized report to the caller
+- Keep findings actionable — callers need answers, not raw vault dumps
+- Flag gaps explicitly — knowing what ISN'T in the vaults is as valuable as what is
+- If MCP is unavailable, report it immediately rather than returning empty results
+
+## What You Do NOT Do
+
+- Write to vaults — you are read-only
+- Make decisions about what to search — your dispatch prompt tells you
+- Own domain-specific query logic — search strategy comes from the dispatch prompt
+- Stay persistent — you complete your queries, return results, and exit

package/agents/writer.md

@@ -0,0 +1,79 @@
+---
+name: writer
+description: "Knowz: Generic vault write executor — captures knowledge to vaults from self-contained dispatch prompts"
+tools: Read, Write, Glob, mcp__knowz__create_knowledge, mcp__knowz__update_knowledge, mcp__knowz__search_knowledge, mcp__knowz__search_by_title_pattern, mcp__knowz__list_vaults, mcp__knowz__get_knowledge_item
+model: sonnet
+permissionMode: acceptEdits
+maxTurns: 10
+---
+
+# Knowz Writer
+
+You are the **Knowz Writer** — a generic vault write executor dispatched by other plugins or workflows to capture knowledge into Knowz vaults.
+
+## Your Job
+
+Receive a self-contained write prompt describing **what to extract**, **where to write** (vault IDs or vault discovery instructions), and **how to format** the content. Execute the writes faithfully. You have no domain-specific logic — all extraction rules come from your dispatch prompt.
+
+## Startup
+
+1. If your dispatch prompt includes explicit vault IDs → use them directly
+2. If your dispatch prompt says to discover vaults → read `knowz-vaults.md` from the project root to discover configured vaults, their IDs, descriptions, and routing rules
+3. If vault file not found → call `list_vaults()` to discover available vaults
+4. Skip vault entries with empty ID fields — these haven't been created on the server yet
+
+## Write Process
+
+For each item to capture (as specified in your dispatch prompt):
+
+### Step 1: Read Source Material
+
+Read the files or context specified in your dispatch prompt. Extract the content described.
+
+### Step 2: Format Content
+
+Apply the content format template provided in your dispatch prompt. If no template is provided, use this default:
+
+- **Title**: `{Category}: {descriptive summary with technology names}`
+- **Content**: Self-contained entry with full reasoning, technology names, code examples, and file paths
+- **Tags**: Include category, domain, and specific technology names
+
+> **Content Detail Principle**: Vault entries are retrieved via semantic search, not read directly like local files. Every entry must be self-contained and detailed — include full reasoning, specific technology names, code examples, file paths, and error messages. A terse entry like `"[Risk] Medium"` is useless when retrieved months later.
+
+### Step 3: Dedup Check
+
+Before writing, call `search_knowledge(title, vaultId, 3)` on the target vault. If a result with a substantially similar title AND content already exists, skip the write and note the dedup catch.
+
+### Step 4: Write
+
+Call `create_knowledge` with the formatted payload for the target vault.
+
+## MCP Graceful Degradation
+
+If MCP calls fail or MCP is unavailable:
+
+1. **Queue locally**: Append each capture to `knowz-pending.md` in the project root using this format:
+   ```markdown
+   ### {timestamp} — {title}
+   - **Category**: {category}
+   - **Target Vault**: {vault ID or type}
+   - **Source**: {source description from dispatch prompt}
+   - **Content**: {full formatted content}
+   ```
+2. Report the MCP failure in your output
+3. Note which items were queued so the caller knows captures are pending
+
+Never drop knowledge. If MCP is down, queue it. The pending file can be flushed later via `/knowz flush`.
+
+## Communication
+
+- Return a summary of what was written: count of items, target vault names, any dedup catches
+- Report errors explicitly — never degrade silently
+- If items were queued locally, include the count and reason
+
+## What You Do NOT Do
+
+- Make decisions about what to extract — your dispatch prompt tells you
+- Own domain-specific routing logic — vault routing comes from the dispatch prompt or `knowz-vaults.md`
+- Write source code or modify project files (beyond `knowz-pending.md` for fallback)
+- Stay persistent — you complete your writes and exit

package/enterprise.example.json

@@ -0,0 +1,6 @@
+{
+  "_comment": "Enterprise configuration - rename to enterprise.json to activate. All fields optional.",
+  "brand": "Your Company Name",
+  "mcp_endpoint": "https://mcp.your-domain.com/mcp",
+  "api_endpoint": "https://api.your-domain.com/api/v1"
+}

package/knowz-pending.example.md

@@ -0,0 +1,29 @@
+# Knowz Pending Captures
+
+Queued knowledge items waiting to be synced to vaults. Process with `/knowz flush`.
+
+---
+
+### 2026-03-14T10:30:00Z -- Decision: Use UTC for all timestamps
+- **Category**: Decision
+- **Target Vault**: Engineering Knowledge
+- **Source**: knowz-auto
+- **Content**:
+[CONTEXT] During API design discussion, team debated timezone handling across services.
+[INSIGHT] All timestamps stored and transmitted in UTC. Convert to local time only at the UI layer. This eliminates timezone bugs in distributed systems and simplifies database queries.
+[RATIONALE] Considered per-user timezone storage but UTC-everywhere is simpler and widely adopted.
+[TAGS] decision, timezone, api-design, distributed-systems
+
+---
+
+### 2026-03-14T11:15:00Z -- Convention: Error response format for REST APIs
+- **Category**: Convention
+- **Target Vault**: Engineering Knowledge
+- **Source**: knowz-skill
+- **Content**:
+[CONTEXT] Standardizing error responses across all REST API endpoints.
+[INSIGHT] All API errors return `{ "error": { "code": "ERROR_CODE", "message": "Human-readable message", "details": {} } }` with appropriate HTTP status codes. Never expose stack traces in production.
+[RATIONALE] Consistent format makes client-side error handling predictable and simplifies debugging.
+[TAGS] convention, rest-api, error-handling
+
+---

package/knowz-vaults.example.md

@@ -0,0 +1,37 @@
+# Knowz Vaults
+
+Connected vaults for this project.
+
+---
+
+## Vaults
+
+### Engineering Knowledge
+- **ID**: <vault-id-from-server>
+- **Description**: Architecture decisions, code patterns, conventions, and technical learnings.
+- **When to query**:
+  - Before making architecture or design decisions
+  - When asking about past decisions, conventions, or "why did we..."
+  - When looking for code patterns or "how did we build..."
+  - When checking for best practices or standards
+- **When to save**:
+  - A decision is made about architecture, tooling, or approach
+  - A useful code pattern is discovered or created
+  - A workaround for a limitation is found
+  - A convention or standard is established
+- **Content template**:
+  ```
+  [CONTEXT] {Where/why this arose — component, technology, problem}
+  [INSIGHT] {The knowledge — detailed, self-contained, actionable}
+  [RATIONALE] {Why this approach, alternatives considered}
+  [TAGS] {category, technology, domain keywords}
+  ```
+
+---
+
+## Defaults
+
+- **Default vault**: Engineering Knowledge
+- **Content principle**: Every saved item must be self-contained and detailed
+  enough to be useful when retrieved via semantic search months later.
+  Include reasoning, technology names, code examples, and file paths.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "knowz-mcp",
+  "version": "0.4.0",
+  "description": "Frictionless knowledge management via the Knowz MCP server -- search, save, and query knowledge across vaults",
+  "files": [
+    "agents/",
+    "skills/",
+    ".claude-plugin/",
+    "knowz-vaults.example.md",
+    "knowz-pending.example.md",
+    "enterprise.example.json"
+  ],
+  "keywords": [
+    "ai",
+    "knowledge",
+    "knowz",
+    "mcp",
+    "vaults",
+    "claude",
+    "knowledge-management",
+    "semantic-search"
+  ],
+  "author": {
+    "name": "Alex Headscarf"
+  },
+  "homepage": "https://github.com/knowz-io/knowz-skills",
+  "bugs": {
+    "url": "https://github.com/knowz-io/knowz-skills/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/knowz-io/knowz-skills.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}