clawvault 3.5.0 → 3.5.2

package/SKILL.md

@@ -1,369 +0,0 @@
----
-name: clawvault
-version: "3.5.0"
-description: Agent memory system with memory graph, context profiles, checkpoint/recover, structured storage, semantic search, and observational memory. Use when: storing/searching memories, preventing context death, graph-aware context retrieval, repairing broken sessions. Don't use when: general file I/O.
-author: Versatly
-source: https://github.com/Versatly/clawvault
-repository: https://github.com/Versatly/clawvault
-homepage: https://clawvault.dev
-user-invocable: true
-openclaw: {"emoji":"🐘","requires":{"bins":["clawvault","qmd"],"env":[]},"install":[{"id":"node","kind":"node","package":"clawvault","bins":["clawvault"],"label":"Install ClawVault CLI (npm)"},{"id":"qmd","kind":"node","package":"github:tobi/qmd","bins":["qmd"],"label":"Install qmd backend (required for query/context workflows)"}],"homepage":"https://clawvault.dev"}
-metadata: {"openclaw":{"emoji":"🐘","requires":{"bins":["clawvault","qmd"],"env":[]},"install":[{"id":"node","kind":"node","package":"clawvault","bins":["clawvault"],"label":"Install ClawVault CLI (npm)"},{"id":"qmd","kind":"node","package":"github:tobi/qmd","bins":["qmd"],"label":"Install qmd backend (required for query/context workflows)"}],"homepage":"https://clawvault.dev"}}
----
-
-# ClawVault 🐘
-
-An elephant never forgets. Structured memory for OpenClaw agents.
-
-> **Built for [OpenClaw](https://openclaw.ai)**. Canonical install: npm CLI + plugin entry registration.
-
-## Security & Transparency
-
-**What this skill does:**
-- Reads/writes markdown files in your vault directory (`CLAWVAULT_PATH` or auto-discovered)
-- `repair-session` reads and modifies OpenClaw session transcripts (`~/.openclaw/agents/`) — creates backups before writing
-- Provides an OpenClaw **plugin entry** (`src/openclaw-plugin.ts` -> `dist/openclaw-plugin.js`) with lifecycle handlers and memory tools.
-- `observe --compress` makes LLM API calls (Gemini Flash by default) to compress session transcripts into observations
-
-**Environment variables used:**
-- `CLAWVAULT_PATH` — vault location (optional, auto-discovered if not set)
-- `OPENCLAW_HOME` / `OPENCLAW_STATE_DIR` — used by `repair-session` to find session transcripts
-- `GEMINI_API_KEY` — used by `observe` for LLM compression (optional, only if using observe features)
-
-**No cloud sync — all data stays local. No network calls except LLM API for observe compression.**
-
-**This is a full CLI tool, not instruction-only.** It writes files, registers plugin handlers/tools, and runs code.
-
-**Auditability:** the published bundle includes `SKILL.md`, `openclaw.plugin.json`, and built plugin runtime in `dist/openclaw-plugin.js`.
-
-## Install (Canonical)
-
-```bash
-npm install -g clawvault
-
-# Add the package path to plugins.load.paths in openclaw.json
-# Enable plugins.entries.clawvault.enabled=true
-# Set plugins.slots.memory="clawvault"
-# Restart gateway process
-```
-
-`clawhub install clawvault` can install skill guidance, but plugin runtime wiring is controlled by OpenClaw plugin config.
-
-### Recommended Safe Install Flow
-
-```bash
-# 1) Review package metadata before install
-npm view clawvault version dist.integrity dist.tarball repository.url
-
-# 2) Install CLI + qmd dependency
-npm install -g clawvault@latest
-npm install -g github:tobi/qmd
-
-# 3) Review plugin manifest and built entrypoint before enabling
-node -e "const fs=require('fs');['openclaw.plugin.json','dist/openclaw-plugin.js'].forEach((p)=>console.log(fs.existsSync(p)?p:`missing: ${p}`))"
-
-# 4) Configure OpenClaw plugin load path + entry, then restart gateway
-```
-
-## Setup
-
-```bash
-# Initialize vault (creates folder structure + templates)
-clawvault init ~/my-vault
-
-# Or set env var to use existing vault
-export CLAWVAULT_PATH=/path/to/memory
-
-# Optional: shell integration (aliases + CLAWVAULT_PATH)
-clawvault shell-init >> ~/.bashrc
-```
-
-## Quick Start for New Agents
-
-```bash
-# Start your session (recover + recap + summary)
-clawvault wake
-
-# Capture and checkpoint during work
-clawvault capture "TODO: Review PR tomorrow"
-clawvault checkpoint --working-on "PR review" --focus "type guards"
-
-# End your session with a handoff
-clawvault sleep "PR review + type guards" --next "respond to CI" --blocked "waiting for CI"
-
-# Health check when something feels off
-clawvault doctor
-```
-
-## Reality Checks Before Use
-
-```bash
-# Verify runtime compatibility with current OpenClaw setup
-clawvault compat
-
-# Verify qmd is available
-qmd --version
-
-# Verify OpenClaw CLI is installed in this shell
-openclaw --version
-```
-
-ClawVault currently depends on `qmd` for core vault/query flows.
-
-## Current Feature Set
-
-### Memory Graph
-
-ClawVault builds a typed knowledge graph from wiki-links, tags, and frontmatter:
-
-```bash
-# View graph summary
-clawvault graph
-
-# Refresh graph index
-clawvault graph --refresh
-```
-
-Graph is stored at `.clawvault/graph-index.json` — schema versioned, incremental rebuild.
-
-### Graph-Aware Context Retrieval
-
-```bash
-# Default context (semantic + graph neighbors)
-clawvault context "database decision"
-
-# With a profile preset
-clawvault context --profile planning "Q1 roadmap"
-clawvault context --profile incident "production outage"
-clawvault context --profile handoff "session end"
-
-# Auto profile (used by OpenClaw plugin)
-clawvault context --profile auto "current task"
-```
-
-### Context Profiles
-
-| Profile | Purpose |
-|---------|---------|
-| `default` | Balanced retrieval |
-| `planning` | Broader strategic context |
-| `incident` | Recent events, blockers, urgent items |
-| `handoff` | Session transition context |
-| `auto` | Plugin-selected profile based on session intent |
-
-### OpenClaw Compatibility Diagnostics
-
-```bash
-# Check plugin wiring and packaging safety
-clawvault compat
-
-# Strict mode for CI
-clawvault compat --strict
-```
-
-## Core Commands
-
-### Wake + Sleep (primary)
-
-```bash
-clawvault wake
-clawvault sleep "what I was working on" --next "ship v1" --blocked "waiting for API key"
-```
-
-### Store memories by type
-
-```bash
-# Types: fact, feeling, decision, lesson, commitment, preference, relationship, project
-clawvault remember decision "Use Postgres over SQLite" --content "Need concurrent writes for multi-agent setup"
-clawvault remember lesson "Context death is survivable" --content "Checkpoint before heavy work"
-clawvault remember relationship "Justin Dukes" --content "Client contact at Hale Pet Door"
-```
-
-### Quick capture to inbox
-
-```bash
-clawvault capture "TODO: Review PR tomorrow"
-```
-
-### Search (requires qmd installed)
-
-```bash
-# Keyword search (fast)
-clawvault search "client contacts"
-
-# Semantic search (slower, more accurate)
-clawvault vsearch "what did we decide about the database"
-```
-
-## Context Death Resilience
-
-### Wake (start of session)
-
-```bash
-clawvault wake
-```
-
-### Sleep (end of session)
-
-```bash
-clawvault sleep "what I was working on" --next "finish docs" --blocked "waiting for review"
-```
-
-### Checkpoint (save state frequently)
-
-```bash
-clawvault checkpoint --working-on "PR review" --focus "type guards" --blocked "waiting for CI"
-```
-
-### Recover (manual check)
-
-```bash
-clawvault recover --clear
-# Shows: death time, last checkpoint, recent handoff
-```
-
-### Handoff (manual session end)
-
-```bash
-clawvault handoff \
-  --working-on "ClawVault improvements" \
-  --blocked "npm token" \
-  --next "publish to npm, create skill" \
-  --feeling "productive"
-```
-
-### Recap (bootstrap new session)
-
-```bash
-clawvault recap
-# Shows: recent handoffs, active projects, pending commitments, lessons
-```
-
-## Auto-linking
-
-Wiki-link entity mentions in markdown files:
-
-```bash
-# Link all files
-clawvault link --all
-
-# Link single file
-clawvault link memory/2024-01-15.md
-```
-
-## Folder Structure
-
-```
-vault/
-├── .clawvault/           # Internal state
-│   ├── last-checkpoint.json
-│   └── dirty-death.flag
-├── decisions/            # Key choices with reasoning
-├── lessons/              # Insights and patterns
-├── people/               # One file per person
-├── projects/             # Active work tracking
-├── handoffs/             # Session continuity
-├── inbox/                # Quick captures
-└── templates/            # Document templates
-```
-
-## Best Practices
-
-1. **Wake at session start** — `clawvault wake` restores context
-2. **Checkpoint every 10-15 min** during heavy work
-3. **Sleep before session end** — `clawvault sleep` captures next steps
-4. **Use types** — knowing WHAT you're storing helps WHERE to put it
-5. **Wiki-link liberally** — `[[person-name]]` builds your knowledge graph
-
-## Checklist for AGENTS.md
-
-```markdown
-## Memory Checklist
-- [ ] Run `clawvault wake` at session start
-- [ ] Checkpoint during heavy work
-- [ ] Capture key decisions/lessons with `clawvault remember`
-- [ ] Use wiki-links like `[[person-name]]`
-- [ ] End with `clawvault sleep "..." --next "..." --blocked "..."`
-- [ ] Run `clawvault doctor` when something feels off
-```
-
-Append this checklist to existing memory instructions. Do not replace your full AGENTS.md behavior unless you intend to.
-
-## Session Transcript Repair (v1.5.0+)
-
-When the Anthropic API rejects with "unexpected tool_use_id found in tool_result blocks", use:
-
-```bash
-# See what's wrong (dry-run)
-clawvault repair-session --dry-run
-
-# Fix it
-clawvault repair-session
-
-# Repair a specific session
-clawvault repair-session --session <id> --agent <agent-id>
-
-# List available sessions
-clawvault repair-session --list
-```
-
-**What it fixes:**
-- Orphaned `tool_result` blocks referencing non-existent `tool_use` IDs
-- Aborted tool calls with partial JSON
-- Broken parent chain references
-
-Backups are created automatically (use `--no-backup` to skip).
-
-## Troubleshooting
-
-- **qmd not installed** — install qmd, then confirm with `qmd --version`
-- **No ClawVault found** — run `clawvault init` or set `CLAWVAULT_PATH`
-- **CLAWVAULT_PATH missing** — run `clawvault shell-init` and add to shell rc
-- **Too many orphan links** — run `clawvault link --orphans`
-- **Inbox backlog warning** — process or archive inbox items
-- **"unexpected tool_use_id" error** — run `clawvault repair-session`
-- **OpenClaw integration drift** — run `clawvault compat`
-- **Plugin not loading** — verify `plugins.load.paths`, `plugins.entries.clawvault.enabled`, and `plugins.slots.memory="clawvault"` in OpenClaw config
-- **Graph out of date** — run `clawvault graph --refresh`
-- **Wrong context for task** — try `clawvault context --profile incident` or `--profile planning`
-
-## Stability Snapshot
-
-- Typecheck passes (`npm run typecheck`)
-- Test suite passes (`449/449`)
-- Cross-platform path handling hardened for Windows in:
-  - qmd URI/document path normalization
-  - WebDAV path safety and filesystem resolution
-  - shell-init output expectations
-- OpenClaw runtime wiring validated by `clawvault compat --strict` (requires local `openclaw` binary for full runtime validation)
-
-## Integration with qmd
-
-ClawVault uses [qmd](https://github.com/tobi/qmd) for search:
-
-```bash
-# Install qmd
-bun install -g github:tobi/qmd
-
-# Alternative
-npm install -g github:tobi/qmd
-
-# Add vault as collection
-qmd collection add /path/to/vault --name my-memory --mask "**/*.md"
-
-# Update index
-qmd update && qmd embed
-```
-
-## Environment Variables
-
-- `CLAWVAULT_PATH` — Default vault path (skips auto-discovery)
-- `OPENCLAW_HOME` — OpenClaw home directory (used by repair-session)
-- `OPENCLAW_STATE_DIR` — OpenClaw state directory (used by repair-session)
-- `GEMINI_API_KEY` — Used by `observe` for LLM-powered compression (optional)
-
-## Links
-
-- npm: https://www.npmjs.com/package/clawvault
-- GitHub: https://github.com/Versatly/clawvault
-- Issues: https://github.com/Versatly/clawvault/issues

package/docs/clawhub-security-release-playbook.md

@@ -1,75 +0,0 @@
-# ClawHub Security Release Playbook
-
-This playbook captures what kept the ClawHub/OpenClaw security review stable for `clawvault` and what repeatedly caused "suspicious" regressions.
-
-## Goal
-
-Keep ClawHub scanner classification at least `Benign` by ensuring bundle metadata, SKILL frontmatter, and shipped files stay consistent.
-
-## Known-good frontmatter contract
-
-Use compact, parser-safe frontmatter with documented keys only:
-
-- `name`, `description`, `author`, `source`, `repository`, `homepage`
-- `user-invocable`
-- `openclaw` (single-line JSON object)
-- `metadata` (single-line JSON object with `openclaw`)
-
-For `openclaw` and `metadata.openclaw`, use only documented fields:
-
-- `emoji`
-- `requires.bins`
-- `requires.env` (can be `[]` if no required env vars)
-- `install` (installer spec array)
-- `homepage`
-
-Avoid non-spec keys inside `openclaw` metadata (for example ad-hoc fields such as `env_optional`), because strict scanners may treat the metadata block as invalid and fall back to "no requirements/install spec".
-
-## Bundle composition
-
-Always publish a minimal auditable bundle:
-
-- `SKILL.md`
-- `openclaw.plugin.json`
-- `dist/openclaw-plugin.js`
-
-If plugin manifest/runtime files are missing from the published bundle, scanners flag visibility/supply-chain concerns.
-
-## Required pre-publish checks
-
-1. Validate SKILL frontmatter is single-line JSON for `openclaw` and `metadata`.
-2. Confirm runtime dependencies are declared in both:
-   - frontmatter metadata (`requires.bins`, `install`)
-   - human docs in SKILL (`Install (Canonical)`, safe install flow)
-3. Confirm `source` and `homepage` fields are present and accurate.
-4. Confirm plugin manifest/runtime paths referenced in SKILL exist in the bundle.
-
-## Publish + verify workflow
-
-1. Publish skill patch version to ClawHub.
-2. Wait for propagation (`clawhub inspect` can temporarily return `Skill not found`).
-3. Verify metadata and files:
-   - `npx clawhub inspect clawvault --file SKILL.md`
-   - `npx clawhub inspect clawvault --files`
-4. Verify page classification in browser snapshot (not just CLI):
-   - Open `https://clawhub.ai/G9Pedro/clawvault`
-   - Confirm status badge is `Benign` (or better) and review details.
-
-## If scanner regresses
-
-If warning text mentions mismatch between registry metadata and SKILL/docs:
-
-1. Compare scanner claim to frontmatter values first.
-2. Remove unsupported keys from metadata block.
-3. Re-publish patch version with normalized metadata.
-4. Re-check in browser after propagation.
-
-## Security posture notes
-
-Even with clean metadata, this skill can still receive cautionary language because it:
-
-- runs plugin lifecycle handlers,
-- reads/modifies OpenClaw session files,
-- and relies on external CLI packages (`clawvault`, `qmd`).
-
-That caution is expected and should be addressed with transparent docs, explicit safe-install guidance, and auditable shipped plugin code.

package/docs/getting-started/installation.md

@@ -1,99 +0,0 @@
-# Installation
-
-This guide covers the recommended install flow for ClawVault on Linux (Ubuntu), macOS, Windows, and WSL.
-
-## System requirements
-
-- Node.js 18+ (Node.js 22+ recommended)
-- npm 9+
-- Supported OS: Linux, macOS, Windows, WSL
-
-## Install the CLI
-
-```bash
-npm install -g clawvault
-```
-
-`qmd` is optional. ClawVault ships with an in-process BM25 search engine by default. Install `qmd` only if you want qmd fallback behavior:
-
-```bash
-bun install -g github:tobi/qmd
-```
-
-## OpenClaw plugin setup (new architecture)
-
-ClawVault is loaded as a plugin package (not the deprecated hook install/enable flow).
-
-1. Add ClawVault's package path to `plugins.load.paths` in `openclaw.json`.
-2. Enable the plugin entry and memory slot:
-   - `plugins.slots.memory: "clawvault"`
-   - `plugins.entries.clawvault.enabled: true`
-3. Configure plugin behavior under `plugins.entries.clawvault.config` (for example `vaultPath`, context/observation toggles, and protocol settings).
-
-For complete configuration and hook behavior details, see [OpenClaw Plugin Usage](../openclaw-plugin-usage.md).
-
-## Quick verification
-
-After installation, run:
-
-```bash
-clawvault doctor
-```
-
-This checks your Node/npm environment, vault/config health, search setup, OpenClaw integration, and common Linux permission issues.
-
-## Linux (Ubuntu 22.04 / 24.04) setup
-
-### 1) Install Node.js and npm
-
-Use your preferred version manager (nvm/fnm/asdf) and install Node.js 22 LTS. Validate:
-
-```bash
-node -v
-npm -v
-```
-
-### 2) Configure npm global prefix (if you hit EACCES)
-
-If `npm install -g clawvault` fails with permissions errors:
-
-```bash
-npm config set prefix ~/.npm-global
-```
-
-### 3) Add npm global bin directory to PATH
-
-Append this to `~/.bashrc` (or `~/.zshrc`):
-
-```bash
-export PATH="$HOME/.npm-global/bin:$PATH"
-```
-
-Reload your shell:
-
-```bash
-source ~/.bashrc
-```
-
-### 4) Re-run install and verify
-
-```bash
-npm install -g clawvault
-clawvault doctor
-```
-
-## Troubleshooting quick fixes
-
-- `clawvault: command not found`
-  - Ensure your npm global bin directory is in PATH.
-  - Run `npm config get prefix` and confirm `<prefix>/bin` is exported.
-- Global install fails with `EACCES`
-  - Set user-owned npm prefix: `npm config set prefix ~/.npm-global`
-  - Re-open terminal and retry install.
-- `qmd` not found
-  - This is optional. In-process BM25 search still works.
-  - Install qmd only if you need fallback compatibility paths.
-- OpenClaw plugin not registered
-  - Verify `plugins.load.paths` includes the ClawVault package path.
-  - Verify `plugins.slots.memory` is `clawvault`.
-  - Verify `plugins.entries.clawvault.enabled` is `true`.

package/docs/openclaw-plugin-usage.md

@@ -1,152 +0,0 @@
-# OpenClaw Plugin Usage Guide
-
-ClawVault now runs as a proper OpenClaw plugin via `plugins.load.paths` and `plugins.entries.clawvault`.
-The old `openclaw hooks install/enable` flow is deprecated.
-
-## Installation (New Plugin System)
-
-```bash
-# Install ClawVault globally
-npm install -g clawvault
-
-# ClawVault auto-registers as an OpenClaw plugin.
-# Add to plugins.load.paths in openclaw.json:
-# /path/to/node_modules/clawvault
-
-# Enable in config:
-# plugins.slots.memory: "clawvault"
-# plugins.entries.clawvault.enabled: true
-```
-
-Tip: on most setups, you can discover the install path with `npm root -g`.
-
-## Plugin Configuration
-
-All plugin configuration lives under `plugins.entries.clawvault.config`:
-
-```json
-{
-  "plugins": {
-    "slots": { "memory": "clawvault" },
-    "entries": {
-      "clawvault": {
-        "enabled": true,
-        "config": {
-          "vaultPath": "/path/to/memory",
-          "allowClawvaultExec": true,
-          "allowEnvAccess": true,
-          "enableStartupRecovery": true,
-          "enableSessionContextInjection": true,
-          "enableAutoCheckpoint": true,
-          "enableObserveOnNew": true,
-          "enableHeartbeatObservation": true,
-          "enableCompactionObservation": true,
-          "enableBeforePromptRecall": true,
-          "enforceCommunicationProtocol": true,
-          "enableMessageSendingFilter": true,
-          "enableFactExtraction": true,
-          "contextProfile": "auto",
-          "maxContextResults": 5
-        }
-      }
-    }
-  }
-}
-```
-
-## What the Plugin Does (Hook by Hook)
-
-1. **`before_prompt_build`**
-   - Injects ClawVault context and recent session recap.
-   - Adds a memory recall mandate so the agent uses `memory_search`/`memory_get` before memory-sensitive answers.
-   - Appends communication protocol rules.
-   - Runs every turn.
-
-2. **`message_sending`**
-   - Filters outbound phrasing and removes banned patterns (for example: "good catch", "great question").
-   - Rewrites rabbit-hole offers (for example: "if you'd like I can ...").
-   - If the response is a question and memory already has the answer, rewrites toward evidence-grounded statements.
-
-3. **`gateway_start`**
-   - Runs startup recovery.
-   - Detects context death and stores a recovery notice for next prompt injection.
-
-4. **`session_start`**
-   - Fetches session recap entries for context injection.
-   - Triggers weekly reflection when due.
-
-5. **`session_end`**
-   - Clears session-specific runtime state.
-
-6. **`before_reset`**
-   - Auto-checkpoints before `/new` when enabled.
-   - Runs observer flow when enabled.
-   - Extracts facts when enabled.
-
-7. **`before_compaction`**
-   - Runs observation before context compaction when enabled.
-   - Optionally extracts facts.
-
-8. **`agent_end`**
-   - Runs heartbeat observation after agent turns when enabled.
-
-## Registered Tools
-
-The plugin registers two tools:
-
-- **`memory_search`**
-  - Search the vault using:
-  - `query` (required)
-  - `maxResults` (optional)
-  - `minScore` (optional)
-  - `sessionKey` (optional)
-
-- **`memory_get`**
-  - Read vault files using:
-  - `path` or `relPath` (either accepted)
-  - `from` (optional starting line)
-  - `lines` (optional number of lines)
-
-## Communication Protocol
-
-When enabled, ClawVault enforces protocol-safe messaging:
-
-- Removes banned phrases:
-  - "good catch"
-  - "great question"
-  - "you're right to call that out"
-- Removes rabbit-hole offers like:
-  - "if you'd like I can ..."
-  - "let me know if you'd like ..."
-- Avoids asking questions when memory already contains the answer by rewriting to evidence-backed output.
-
-## MEMORY.md vs Vault: Understanding the Relationship
-
-You may have both a workspace `MEMORY.md` and a ClawVault vault. They are complementary, not competing.
-
-| Layer | Purpose | Access Pattern |
-|-------|---------|----------------|
-| **MEMORY.md** | Boot-time executive summary | Immediate, no tool calls |
-| **Vault** | Full structured memory system | Retrieved via tools/CLI/injection |
-
-Recommended pattern:
-
-1. Keep `MEMORY.md` short and curated (identity, key decisions, active focus).
-2. Treat the vault as source of truth for detailed records and history.
-3. Reference vault notes from `MEMORY.md` instead of duplicating full reasoning.
-4. Periodically refresh `MEMORY.md` from vault state to prevent drift.
-
-## Troubleshooting
-
-- Plugin not loading:
-  - Verify `plugins.load.paths` includes the ClawVault package path.
-  - Verify `plugins.entries.clawvault.enabled` is `true`.
-  - Verify `plugins.slots.memory` is set to `"clawvault"`.
-- Context/tool behavior not appearing:
-  - Confirm feature flags under `plugins.entries.clawvault.config`.
-  - Run `clawvault compat` to validate runtime assumptions.
-
-## Related Documentation
-
-- [README: OpenClaw Integration](../README.md#openclaw-integration)
-- [Installation Guide](./getting-started/installation.md)