clawvault 3.3.0 → 3.4.1

package/README.md

@@ -267,23 +267,24 @@ clawvault setup --theme neural --canvas --bases
 
 ## OpenClaw Integration
 
-For hook-based lifecycle integration with OpenClaw:
+ClawVault integrates with OpenClaw as a plugin package (not the deprecated `openclaw hooks install/enable` flow):
 
 ```bash
-# Install and enable hook pack
-openclaw hooks install clawvault
-openclaw hooks enable clawvault
+# Install ClawVault
+npm install -g clawvault
+
+# Add ClawVault package path to plugins.load.paths in openclaw.json
+# (You can use `npm root -g` to locate node_modules)
 
-# Verify
-openclaw hooks list --verbose
-openclaw hooks check
+# Enable plugin + memory slot in openclaw.json:
+# plugins.slots.memory = "clawvault"
+# plugins.entries.clawvault.enabled = true
+
+# Verify runtime assumptions
 clawvault compat
 ```
 
-The hook automatically:
-- Detects context death and injects recovery alerts
-- Auto-checkpoints before session resets
-- Provides `--profile auto` for context queries
+The plugin provides lifecycle hooks, memory tools, and protocol-safe messaging behavior for OpenClaw sessions.
 
 ### MEMORY.md vs Vault
 
@@ -351,27 +352,26 @@ clawvault compat
 
 ## OpenClaw Setup (Canonical)
 
-If you want hook-based lifecycle integration, use this sequence:
+Use this sequence for plugin-based OpenClaw integration:
 
 ```bash
 # Install CLI
 npm install -g clawvault
 
-# Install and enable hook pack
-openclaw hooks install clawvault
-openclaw hooks enable clawvault
+# Locate global node_modules
+npm root -g
 
-# Verify
-openclaw hooks list --verbose
-openclaw hooks info clawvault
-openclaw hooks check
-clawvault compat
+# In openclaw.json:
+# - add <npm-root>/clawvault to plugins.load.paths
+# - set plugins.slots.memory = "clawvault"
+# - set plugins.entries.clawvault.enabled = true
+# - set plugins.entries.clawvault.config.vaultPath as needed
 ```
 
 Important:
 
-- `clawhub install clawvault` installs skill guidance, but does not replace hook-pack installation.
-- After enabling hooks, restart the OpenClaw gateway process so hook registration reloads.
+- `clawhub install clawvault` installs skill guidance, but does not configure OpenClaw plugin loading.
+- After changing plugin config, restart the OpenClaw gateway process.
 
 ## Minimal AGENTS.md Additions
 
@@ -488,10 +488,10 @@ vault/
 - `qmd` fallback errors:
   - `qmd` is optional; in-process BM25 search is available without it
   - if you want fallback compatibility, ensure `qmd --version` works in the same shell
-- Hook/plugin not active in OpenClaw:
-  - run `openclaw hooks install clawvault`
-  - run `openclaw hooks enable clawvault`
-  - verify with `openclaw hooks list --verbose`
+- Plugin not active in OpenClaw:
+  - verify `plugins.load.paths` includes the ClawVault package path
+  - verify `plugins.slots.memory` is `clawvault`
+  - verify `plugins.entries.clawvault.enabled` is `true`
 - OpenClaw integration drift:
   - run `clawvault compat`
 - Session transcript corruption:

package/bin/command-registration.test.js

@@ -49,7 +49,7 @@ describe('CLI command registration modules', () => {
     });
 
     const names = listCommandNames(program);
-    expect(names).toEqual(expect.arrayContaining(['search', 'vsearch', 'context', 'inject', 'observe', 'reflect', 'session-recap']));
+    expect(names).toEqual(expect.arrayContaining(['search', 'vsearch', 'context', 'recall', 'inject', 'observe', 'reflect', 'session-recap']));
 
     const contextCommand = program.commands.find((command) => command.name() === 'context');
     const profileOption = contextCommand?.options.find((option) => option.flags.includes('--profile <profile>'));
@@ -127,6 +127,7 @@ describe('CLI command registration modules', () => {
       'compat',
       'graph',
       'entities',
+      'entity',
       'link',
       'rebuild',
       'archive',

package/bin/help-contract.test.js

@@ -6,6 +6,7 @@ describe('CLI help contract', () => {
     const help = registerAllCommandModules().helpInformation();
     expect(help).toContain('init');
     expect(help).toContain('context');
+    expect(help).toContain('recall');
     expect(help).toContain('inject');
     expect(help).toContain('doctor');
     expect(help).toContain('benchmark');
@@ -22,6 +23,7 @@ describe('CLI help contract', () => {
     expect(help).toContain('template');
     expect(help).toContain('config');
     expect(help).toContain('route');
+    expect(help).toContain('entity');
   });
 
   it('documents context/compat/inject/project help details', () => {

package/bin/register-maintenance-commands.js

@@ -174,11 +174,37 @@ export function registerMaintenanceCommands(program, { chalk }) {
     .command('entities')
     .description('List all linkable entities in the vault')
     .option('-v, --vault <path>', 'Vault path')
+    .option('--refresh', 'Regenerate entity profiles before listing')
     .option('--json', 'Output as JSON')
     .action(async (options) => {
       try {
         const { entitiesCommand } = await import('../dist/commands/entities.js');
-        await entitiesCommand({ json: options.json, vaultPath: options.vault });
+        await entitiesCommand({
+          json: options.json,
+          vaultPath: options.vault,
+          refresh: options.refresh
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // === ENTITY ===
+  program
+    .command('entity <name>')
+    .description('Show synthesized profile for one entity')
+    .option('-v, --vault <path>', 'Vault path')
+    .option('--refresh', 'Regenerate entity profiles before lookup')
+    .option('--json', 'Output as JSON')
+    .action(async (name, options) => {
+      try {
+        const { entityCommand } = await import('../dist/commands/entities.js');
+        await entityCommand(name, {
+          json: options.json,
+          vaultPath: options.vault,
+          refresh: options.refresh
+        });
       } catch (err) {
         console.error(chalk.red(`Error: ${err.message}`));
         process.exit(1);

package/bin/register-query-commands.js

@@ -202,6 +202,41 @@ export function registerQueryCommands(
       }
     });
 
+  // === INJECT ===
+  program
+    .command('recall <query>')
+    .description('Recall memory context with strategy classification (quick|entity|temporal|verification|relationship)')
+    .option('-n, --limit <n>', 'Max results (default: 6)', '6')
+    .option('--strategy <strategy>', 'Override strategy (quick|entity|temporal|verification|relationship)')
+    .option('--json', 'Output as JSON')
+    .option('--no-sources', 'Hide source paths in recall context')
+    .option('-v, --vault <path>', 'Vault path')
+    .action(async (query, options) => {
+      try {
+        const parsedLimit = Number.parseInt(options.limit, 10);
+        if (!Number.isFinite(parsedLimit) || parsedLimit <= 0) {
+          throw new Error(`Invalid --limit value: ${options.limit}`);
+        }
+
+        const allowedStrategies = new Set(['quick', 'entity', 'temporal', 'verification', 'relationship']);
+        if (options.strategy && !allowedStrategies.has(options.strategy)) {
+          throw new Error(`Invalid --strategy value: ${options.strategy}`);
+        }
+
+        const { recallCommand } = await import('../dist/commands/recall.js');
+        await recallCommand(query, {
+          vaultPath: resolveVaultPath(options.vault),
+          limit: parsedLimit,
+          strategy: options.strategy,
+          json: options.json,
+          includeSources: options.sources
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
   // === INJECT ===
   program
     .command('inject <message>')

package/bin/register-query-commands.test.js

@@ -20,6 +20,21 @@ function buildProgram() {
 }
 
 describe('register-query-commands', () => {
+  it('registers recall command with strategy options', () => {
+    const program = buildProgram();
+    const recallCommand = program.commands.find((command) => command.name() === 'recall');
+    expect(recallCommand).toBeDefined();
+
+    const flags = recallCommand?.options.map((option) => option.flags) ?? [];
+    expect(flags).toEqual(expect.arrayContaining([
+      '-n, --limit <n>',
+      '--strategy <strategy>',
+      '--json',
+      '--no-sources',
+      '-v, --vault <path>'
+    ]));
+  });
+
   it('documents inject command options and config-backed defaults', () => {
     const program = buildProgram();
     const injectCommand = program.commands.find((command) => command.name() === 'inject');

package/dist/chunk-35JCYSRR.js

@@ -0,0 +1,158 @@
+// src/lib/maintenance/heuristics.ts
+var CATEGORY_PATTERNS = [
+  {
+    category: "decisions",
+    patterns: [
+      /\b(decid(?:e|ed|ing|ion)|chose|selected|opted|trade[- ]?off)\b/i,
+      /\b(approved|agreed|consensus)\b/i
+    ]
+  },
+  {
+    category: "lessons",
+    patterns: [
+      /\b(learn(?:ed|ing|t)|lesson|insight|realized|retrospective)\b/i,
+      /\b(next time|note to self|mistake)\b/i
+    ]
+  },
+  {
+    category: "commitments",
+    patterns: [
+      /\b(todo|task|action item|follow[- ]?up|deadline|due)\b/i,
+      /\b(i will|we will|must|need to)\b/i
+    ]
+  },
+  {
+    category: "people",
+    patterns: [
+      /\b(met with|talked to|spoke with|emailed|called|messaged)\b/i,
+      /\b(client|customer|partner|colleague|contact)\b/i
+    ]
+  },
+  {
+    category: "projects",
+    patterns: [
+      /\b(project|feature|release|deployment|deploy|service|api|repo)\b/i,
+      /\b(shipped|launched|merged|rolled out)\b/i
+    ]
+  },
+  {
+    category: "preferences",
+    patterns: [
+      /\b(prefer(?:s|red|ence)?|like(?:s|d)?|dislike|style|convention)\b/i,
+      /\b(always use|never use|default to)\b/i
+    ]
+  },
+  {
+    category: "facts",
+    patterns: [
+      /\b(is|are|was|were|has|have|contains|includes)\b/i
+    ]
+  }
+];
+function splitSentences(content) {
+  return content.split(/\r?\n|(?<=[.?!])\s+/).map((sentence) => sentence.trim()).filter(Boolean);
+}
+function compactWhitespace(value) {
+  return value.toLowerCase().replace(/[^\w\s]/g, " ").replace(/\s+/g, " ").trim();
+}
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "and",
+  "or",
+  "to",
+  "of",
+  "for",
+  "in",
+  "on",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "this",
+  "that",
+  "it",
+  "with",
+  "as",
+  "at",
+  "by",
+  "from",
+  "we",
+  "i",
+  "you",
+  "they",
+  "he",
+  "she"
+]);
+function classifyInboxItemHeuristic(item) {
+  const sample = `${item.title}
+${item.content.slice(0, 2400)}`;
+  for (const rule of CATEGORY_PATTERNS) {
+    if (rule.patterns.some((pattern) => pattern.test(sample))) {
+      return rule.category;
+    }
+  }
+  return "inbox";
+}
+function normalizeForDedup(content) {
+  return compactWhitespace(content.replace(/\[\[[^\]]+\]\]/g, ""));
+}
+function wordSet(content) {
+  const words = compactWhitespace(content).split(" ").filter(Boolean);
+  const filtered = words.filter((word) => !STOP_WORDS.has(word) && word.length > 2);
+  return new Set(filtered);
+}
+function similarityScore(left, right) {
+  const leftWords = wordSet(left);
+  const rightWords = wordSet(right);
+  if (leftWords.size === 0 || rightWords.size === 0) {
+    return 0;
+  }
+  let intersection = 0;
+  for (const word of leftWords) {
+    if (rightWords.has(word)) {
+      intersection += 1;
+    }
+  }
+  const union = leftWords.size + rightWords.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+function extractHeuristicInsights(content) {
+  const sentences = splitSentences(content);
+  const facts = sentences.filter((line) => /\b(is|are|was|were|has|have|contains|includes)\b/i.test(line)).slice(0, 8);
+  const decisions = sentences.filter((line) => /\b(decid(?:e|ed|ing|ion)|chose|selected|opted|agreed)\b/i.test(line)).slice(0, 8);
+  const lessons = sentences.filter((line) => /\b(learn(?:ed|ing|t)|lesson|insight|realized|next time|mistake)\b/i.test(line)).slice(0, 8);
+  if (facts.length === 0 && sentences.length > 0) {
+    facts.push(sentences[0]);
+  }
+  return { facts, decisions, lessons };
+}
+function buildHeuristicSurveyRecommendations(params) {
+  const recommendations = [];
+  if (params.inboxCount > 20) {
+    recommendations.push(`Inbox backlog is high (${params.inboxCount}); run \`clawvault maintain --worker curator\` more frequently.`);
+  }
+  if (params.linkedRatio < 0.25) {
+    recommendations.push("Graph connectivity is low; add wiki-links between related notes to improve context traversal.");
+  }
+  if ((params.categoryCounts.lessons ?? 0) < 5) {
+    recommendations.push("Lessons are sparse; run distillation on long-form captures to keep reusable learnings explicit.");
+  }
+  if ((params.categoryCounts.decisions ?? 0) < 5) {
+    recommendations.push("Decision coverage is light; capture major choices and rationale in decisions/.");
+  }
+  if (recommendations.length === 0) {
+    recommendations.push("Vault health looks balanced. Keep regular maintenance cadence and continue linking related notes.");
+  }
+  return recommendations;
+}
+
+export {
+  classifyInboxItemHeuristic,
+  normalizeForDedup,
+  similarityScore,
+  extractHeuristicInsights,
+  buildHeuristicSurveyRecommendations
+};

package/dist/{chunk-TDWFBDAQ.js → chunk-D5U3Q4N5.js}

@@ -5,6 +5,13 @@ import {
 import {
   readInboxItems
 } from "./chunk-2PKBIKDH.js";
+import {
+  buildHeuristicSurveyRecommendations,
+  classifyInboxItemHeuristic,
+  extractHeuristicInsights,
+  normalizeForDedup,
+  similarityScore
+} from "./chunk-35JCYSRR.js";
 import {
   resolveVaultPath
 } from "./chunk-GJO3CFUN.js";
@@ -173,157 +180,6 @@ function writeMaintenanceState(vaultPath, state) {
 import * as path5 from "path";
 import matter from "gray-matter";
 
-// src/lib/maintenance/heuristics.ts
-var CATEGORY_PATTERNS = [
-  {
-    category: "decisions",
-    patterns: [
-      /\b(decid(?:e|ed|ing|ion)|chose|selected|opted|trade[- ]?off)\b/i,
-      /\b(approved|agreed|consensus)\b/i
-    ]
-  },
-  {
-    category: "lessons",
-    patterns: [
-      /\b(learn(?:ed|ing|t)|lesson|insight|realized|retrospective)\b/i,
-      /\b(next time|note to self|mistake)\b/i
-    ]
-  },
-  {
-    category: "commitments",
-    patterns: [
-      /\b(todo|task|action item|follow[- ]?up|deadline|due)\b/i,
-      /\b(i will|we will|must|need to)\b/i
-    ]
-  },
-  {
-    category: "people",
-    patterns: [
-      /\b(met with|talked to|spoke with|emailed|called|messaged)\b/i,
-      /\b(client|customer|partner|colleague|contact)\b/i
-    ]
-  },
-  {
-    category: "projects",
-    patterns: [
-      /\b(project|feature|release|deployment|deploy|service|api|repo)\b/i,
-      /\b(shipped|launched|merged|rolled out)\b/i
-    ]
-  },
-  {
-    category: "preferences",
-    patterns: [
-      /\b(prefer(?:s|red|ence)?|like(?:s|d)?|dislike|style|convention)\b/i,
-      /\b(always use|never use|default to)\b/i
-    ]
-  },
-  {
-    category: "facts",
-    patterns: [
-      /\b(is|are|was|were|has|have|contains|includes)\b/i
-    ]
-  }
-];
-function splitSentences(content) {
-  return content.split(/\r?\n|(?<=[.?!])\s+/).map((sentence) => sentence.trim()).filter(Boolean);
-}
-function compactWhitespace(value) {
-  return value.toLowerCase().replace(/[^\w\s]/g, " ").replace(/\s+/g, " ").trim();
-}
-var STOP_WORDS = /* @__PURE__ */ new Set([
-  "the",
-  "a",
-  "an",
-  "and",
-  "or",
-  "to",
-  "of",
-  "for",
-  "in",
-  "on",
-  "is",
-  "are",
-  "was",
-  "were",
-  "be",
-  "this",
-  "that",
-  "it",
-  "with",
-  "as",
-  "at",
-  "by",
-  "from",
-  "we",
-  "i",
-  "you",
-  "they",
-  "he",
-  "she"
-]);
-function classifyInboxItemHeuristic(item) {
-  const sample = `${item.title}
-${item.content.slice(0, 2400)}`;
-  for (const rule of CATEGORY_PATTERNS) {
-    if (rule.patterns.some((pattern) => pattern.test(sample))) {
-      return rule.category;
-    }
-  }
-  return "inbox";
-}
-function normalizeForDedup(content) {
-  return compactWhitespace(content.replace(/\[\[[^\]]+\]\]/g, ""));
-}
-function wordSet(content) {
-  const words = compactWhitespace(content).split(" ").filter(Boolean);
-  const filtered = words.filter((word) => !STOP_WORDS.has(word) && word.length > 2);
-  return new Set(filtered);
-}
-function similarityScore(left, right) {
-  const leftWords = wordSet(left);
-  const rightWords = wordSet(right);
-  if (leftWords.size === 0 || rightWords.size === 0) {
-    return 0;
-  }
-  let intersection = 0;
-  for (const word of leftWords) {
-    if (rightWords.has(word)) {
-      intersection += 1;
-    }
-  }
-  const union = leftWords.size + rightWords.size - intersection;
-  return union === 0 ? 0 : intersection / union;
-}
-function extractHeuristicInsights(content) {
-  const sentences = splitSentences(content);
-  const facts = sentences.filter((line) => /\b(is|are|was|were|has|have|contains|includes)\b/i.test(line)).slice(0, 8);
-  const decisions = sentences.filter((line) => /\b(decid(?:e|ed|ing|ion)|chose|selected|opted|agreed)\b/i.test(line)).slice(0, 8);
-  const lessons = sentences.filter((line) => /\b(learn(?:ed|ing|t)|lesson|insight|realized|next time|mistake)\b/i.test(line)).slice(0, 8);
-  if (facts.length === 0 && sentences.length > 0) {
-    facts.push(sentences[0]);
-  }
-  return { facts, decisions, lessons };
-}
-function buildHeuristicSurveyRecommendations(params) {
-  const recommendations = [];
-  if (params.inboxCount > 20) {
-    recommendations.push(`Inbox backlog is high (${params.inboxCount}); run \`clawvault maintain --worker curator\` more frequently.`);
-  }
-  if (params.linkedRatio < 0.25) {
-    recommendations.push("Graph connectivity is low; add wiki-links between related notes to improve context traversal.");
-  }
-  if ((params.categoryCounts.lessons ?? 0) < 5) {
-    recommendations.push("Lessons are sparse; run distillation on long-form captures to keep reusable learnings explicit.");
-  }
-  if ((params.categoryCounts.decisions ?? 0) < 5) {
-    recommendations.push("Decision coverage is light; capture major choices and rationale in decisions/.");
-  }
-  if (recommendations.length === 0) {
-    recommendations.push("Vault health looks balanced. Keep regular maintenance cadence and continue linking related notes.");
-  }
-  return recommendations;
-}
-
 // src/lib/maintenance/worker-utils.ts
 import * as fs4 from "fs";
 import * as path4 from "path";

package/dist/{chunk-YCUVAOFC.js → chunk-DCF4KMFD.js}

@@ -9,22 +9,22 @@ import {
 } from "./chunk-OFOCU2V4.js";
 import {
   registerMaintainCommand
-} from "./chunk-TDWFBDAQ.js";
+} from "./chunk-D5U3Q4N5.js";
 import {
   registerObserveCommand
 } from "./chunk-BLQXXX7Q.js";
 import {
   registerContextCommand
 } from "./chunk-GFCHWMGD.js";
-import {
-  ClawVault
-} from "./chunk-ECGJYWNA.js";
 import {
   registerEmbedCommand
 } from "./chunk-T7E764W3.js";
 import {
   registerInboxCommand
 } from "./chunk-HEHO7SMV.js";
+import {
+  ClawVault
+} from "./chunk-ECGJYWNA.js";
 import {
   resolveVaultPath
 } from "./chunk-GJO3CFUN.js";