shieldcortex 3.0.2 → 3.0.4

package/dist/memory/search.d.ts

@@ -0,0 +1,37 @@
+import type Database from 'better-sqlite3';
+import { Memory, MemoryCategory, MemoryConfig, SearchResult } from './types.js';
+export interface SearchExecutionOptions {
+    enableSideEffects: boolean;
+    includeExplanation: boolean;
+}
+export interface SearchScoringContext {
+    db: Database.Database;
+    config: MemoryConfig;
+    detectedCategory: MemoryCategory | null;
+    queryTags: string[];
+    vectorResults: Map<number, number>;
+    query: string;
+}
+export interface SearchScoreValues {
+    ftsScore: number;
+    vectorSimilarity: number;
+    vectorBoost: number;
+    decayedScore: number;
+    priorityBoost: number;
+    recencyBoost: number;
+    categoryBoost: number;
+    linkBoost: number;
+    tagBoost: number;
+    activationBoost: number;
+    finalScore: number;
+}
+export type MemoryRowConverter = (row: Record<string, unknown>) => Memory;
+export declare function detectQueryCategory(query: string): MemoryCategory | null;
+export declare function calculateLinkBoost(memoryId: number, db: Database.Database): number;
+export declare function calculateTagScore(queryTags: string[], memoryTags: string[]): number;
+export declare function extractQueryTags(query: string): string[];
+export declare function vectorSearch(db: Database.Database, rowToMemory: MemoryRowConverter, queryEmbedding: Float32Array, limit: number, project?: string, includeGlobal?: boolean): Array<{
+    memory: Memory;
+    similarity: number;
+}>;
+export declare function buildSearchExplanation(memory: Memory, context: SearchScoringContext, values: SearchScoreValues): SearchResult['explanation'];

package/dist/memory/search.js

@@ -0,0 +1,143 @@
+import { cosineSimilarity } from '../embeddings/index.js';
+export function detectQueryCategory(query) {
+    const lower = query.toLowerCase();
+    if (/architect|design|structure|pattern|system|schema|model/.test(lower)) {
+        return 'architecture';
+    }
+    if (/error|bug|fix|issue|crash|exception|fail|problem/.test(lower)) {
+        return 'error';
+    }
+    if (/prefer|always|never|style|convention|like|want/.test(lower)) {
+        return 'preference';
+    }
+    if (/learn|discover|realiz|found\s+out|turns?\s+out/.test(lower)) {
+        return 'learning';
+    }
+    if (/todo|task|pending|need\s+to|should\s+do/.test(lower)) {
+        return 'todo';
+    }
+    if (/relation|depend|connect|link|reference/.test(lower)) {
+        return 'relationship';
+    }
+    return null;
+}
+export function calculateLinkBoost(memoryId, db) {
+    try {
+        const linked = db.prepare(`
+      SELECT m.salience, ml.strength
+      FROM memory_links ml
+      JOIN memories m ON (m.id = ml.target_id OR m.id = ml.source_id)
+      WHERE (ml.source_id = ? OR ml.target_id = ?)
+        AND m.id != ?
+    `).all(memoryId, memoryId, memoryId);
+        if (linked.length === 0)
+            return 0;
+        const totalWeight = linked.reduce((sum, link) => sum + link.strength, 0);
+        if (totalWeight === 0)
+            return 0;
+        const weightedSalience = linked.reduce((sum, link) => sum + link.salience * link.strength, 0) / totalWeight;
+        return Math.min(0.15, weightedSalience * 0.2);
+    }
+    catch {
+        return 0;
+    }
+}
+export function calculateTagScore(queryTags, memoryTags) {
+    if (queryTags.length === 0 || memoryTags.length === 0)
+        return 0;
+    let matches = 0;
+    for (const queryTag of queryTags) {
+        const lowerQueryTag = queryTag.toLowerCase();
+        if (memoryTags.some((memoryTag) => {
+            const lowerMemoryTag = memoryTag.toLowerCase();
+            return lowerMemoryTag.includes(lowerQueryTag) || lowerQueryTag.includes(lowerMemoryTag);
+        })) {
+            matches++;
+        }
+    }
+    return (matches / queryTags.length) * 0.1;
+}
+export function extractQueryTags(query) {
+    const words = query.toLowerCase().split(/\s+/);
+    return words.filter((word) => word.length > 2 &&
+        /^[a-z][a-z0-9-]*$/.test(word) &&
+        !['the', 'and', 'for', 'with', 'how', 'what', 'when', 'where', 'why'].includes(word));
+}
+export function vectorSearch(db, rowToMemory, queryEmbedding, limit, project, includeGlobal = true) {
+    let query = `
+    SELECT * FROM memories
+    WHERE embedding IS NOT NULL
+  `;
+    const params = [];
+    if (project && includeGlobal) {
+        query += ` AND (project = ? OR scope = 'global')`;
+        params.push(project);
+    }
+    else if (project) {
+        query += ` AND project = ?`;
+        params.push(project);
+    }
+    const rows = db.prepare(query).all(...params);
+    return rows
+        .map((row) => {
+        const embeddingBuffer = row.embedding;
+        const embedding = new Float32Array(embeddingBuffer.buffer, embeddingBuffer.byteOffset, embeddingBuffer.length / 4);
+        return {
+            memory: rowToMemory(row),
+            similarity: cosineSimilarity(queryEmbedding, embedding),
+        };
+    })
+        .filter((result) => result.similarity > 0.3)
+        .sort((a, b) => b.similarity - a.similarity)
+        .slice(0, limit);
+}
+export function buildSearchExplanation(memory, context, values) {
+    const matchedTags = context.queryTags.filter((queryTag) => memory.tags.some((memoryTag) => {
+        const lowerMemoryTag = memoryTag.toLowerCase();
+        return lowerMemoryTag.includes(queryTag) || queryTag.includes(lowerMemoryTag);
+    }));
+    const reasons = [];
+    if (values.vectorSimilarity > 0) {
+        reasons.push(`Semantic similarity ${(values.vectorSimilarity * 100).toFixed(0)}%`);
+    }
+    if (values.ftsScore > 0.3) {
+        reasons.push('Strong keyword match');
+    }
+    if (values.categoryBoost > 0 && context.detectedCategory) {
+        reasons.push(`Matches ${context.detectedCategory} category intent`);
+    }
+    if (matchedTags.length > 0) {
+        reasons.push(`Shared tags: ${matchedTags.slice(0, 3).join(', ')}`);
+    }
+    if (values.recencyBoost > 0) {
+        reasons.push('Recently accessed');
+    }
+    if (values.linkBoost > 0) {
+        reasons.push('Connected to related memories');
+    }
+    if (values.activationBoost > 0) {
+        reasons.push('Activated by recent recall activity');
+    }
+    if (reasons.length === 0) {
+        reasons.push('Ranked by salience and base recall heuristics');
+    }
+    return {
+        query: context.query,
+        reasons,
+        breakdown: {
+            ftsScore: values.ftsScore,
+            vectorSimilarity: values.vectorSimilarity,
+            vectorBoost: values.vectorBoost,
+            decayedScore: values.decayedScore,
+            priorityBoost: values.priorityBoost,
+            recencyBoost: values.recencyBoost,
+            categoryBoost: values.categoryBoost,
+            linkBoost: values.linkBoost,
+            tagBoost: values.tagBoost,
+            activationBoost: values.activationBoost,
+            finalScore: values.finalScore,
+            matchedTags,
+            matchedCategory: values.categoryBoost > 0 ? context.detectedCategory : null,
+        },
+    };
+}

package/dist/memory/store.js

@@ -23,6 +23,7 @@ import { scoreSource } from '../defence/trust/source-scorer.js';
 import { logAudit } from '../defence/audit/logger.js';
 import { dispatchWebhook } from '../events/webhooks.js';
 import { getCachedQueryEmbedding, findSimilarMemories } from './embedding.js';
+import { buildSearchExplanation, calculateLinkBoost, calculateTagScore, detectQueryCategory, extractQueryTags, vectorSearch, } from './search.js';
 // Anti-bloat: Maximum content size per memory (10KB)
 const MAX_CONTENT_SIZE = 10 * 1024;
 // Track truncation info globally for the last addMemory call
@@ -77,6 +78,18 @@ function escapeFts5Query(query) {
         .split(/\s+/)
         .filter(term => term.length > 0)
         .map(term => {
+        // Replace apostrophes with spaces — FTS5 porter unicode61 tokenizer treats
+        // apostrophes as word separators during indexing ("don't" → "don" + "t").
+        // We must split the same way so queries match the indexed tokens.
+        if (term.includes("'")) {
+            const parts = term.split("'").filter(p => p.length > 0);
+            // Recursively escape each part and join with spaces
+            return parts.map(p => {
+                if (/[^a-zA-Z0-9_]/.test(p))
+                    return `"${p.replace(/"/g, '""')}"`;
+                return p;
+            }).join(' ');
+        }
         // FTS5 boolean operators - quote them to search literally
         const upperTerm = term.toUpperCase();
         if (upperTerm === 'AND' || upperTerm === 'OR' || upperTerm === 'NOT') {
@@ -90,6 +103,7 @@ function escapeFts5Query(query) {
         }
         return term;
     })
+        .filter(Boolean)
         .join(' ');
 }
 /**
@@ -763,171 +777,6 @@ export function updateDecayScores() {
     }
     return updated;
 }
-/**
- * Detect the likely category a query is asking about
- */
-function detectQueryCategory(query) {
-    const lower = query.toLowerCase();
-    if (/architect|design|structure|pattern|system|schema|model/.test(lower)) {
-        return 'architecture';
-    }
-    if (/error|bug|fix|issue|crash|exception|fail|problem/.test(lower)) {
-        return 'error';
-    }
-    if (/prefer|always|never|style|convention|like|want/.test(lower)) {
-        return 'preference';
-    }
-    if (/learn|discover|realiz|found\s+out|turns?\s+out/.test(lower)) {
-        return 'learning';
-    }
-    if (/todo|task|pending|need\s+to|should\s+do/.test(lower)) {
-        return 'todo';
-    }
-    if (/relation|depend|connect|link|reference/.test(lower)) {
-        return 'relationship';
-    }
-    return null;
-}
-/**
- * Calculate a boost for memories linked to high-salience memories
- */
-function calculateLinkBoost(memoryId, db) {
-    try {
-        // Get linked memories and their salience
-        const linked = db.prepare(`
-      SELECT m.salience, ml.strength
-      FROM memory_links ml
-      JOIN memories m ON (m.id = ml.target_id OR m.id = ml.source_id)
-      WHERE (ml.source_id = ? OR ml.target_id = ?)
-        AND m.id != ?
-    `).all(memoryId, memoryId, memoryId);
-        if (linked.length === 0)
-            return 0;
-        // Calculate weighted average of linked memory salience
-        const totalWeight = linked.reduce((sum, l) => sum + l.strength, 0);
-        if (totalWeight === 0)
-            return 0;
-        const weightedSalience = linked.reduce((sum, l) => sum + l.salience * l.strength, 0) / totalWeight;
-        // Cap boost at 0.15
-        return Math.min(0.15, weightedSalience * 0.2);
-    }
-    catch {
-        return 0;
-    }
-}
-/**
- * Calculate partial tag match score
- */
-function calculateTagScore(queryTags, memoryTags) {
-    if (queryTags.length === 0 || memoryTags.length === 0)
-        return 0;
-    // Count partial matches (substring matching)
-    let matches = 0;
-    for (const qt of queryTags) {
-        const qtLower = qt.toLowerCase();
-        if (memoryTags.some(mt => mt.toLowerCase().includes(qtLower) || qtLower.includes(mt.toLowerCase()))) {
-            matches++;
-        }
-    }
-    return (matches / queryTags.length) * 0.1;
-}
-/**
- * Extract potential tags from a query string
- */
-function extractQueryTags(query) {
-    // Extract words that might be tags (tech terms, project-specific terms)
-    const words = query.toLowerCase().split(/\s+/);
-    return words.filter(w => w.length > 2 &&
-        /^[a-z][a-z0-9-]*$/.test(w) &&
-        !['the', 'and', 'for', 'with', 'how', 'what', 'when', 'where', 'why'].includes(w));
-}
-/**
- * Search memories by vector similarity
- * Returns memories sorted by cosine similarity to the query embedding
- */
-function vectorSearch(queryEmbedding, limit, project, includeGlobal = true) {
-    const db = getDatabase();
-    // Get memories with embeddings
-    let query = `
-    SELECT * FROM memories
-    WHERE embedding IS NOT NULL
-  `;
-    const params = [];
-    if (project && includeGlobal) {
-        query += ` AND (project = ? OR scope = 'global')`;
-        params.push(project);
-    }
-    else if (project) {
-        query += ` AND project = ?`;
-        params.push(project);
-    }
-    const rows = db.prepare(query).all(...params);
-    // Calculate similarities
-    const results = rows
-        .map(row => {
-        const embeddingBuffer = row.embedding;
-        const embedding = new Float32Array(embeddingBuffer.buffer, embeddingBuffer.byteOffset, embeddingBuffer.length / 4);
-        const similarity = cosineSimilarity(queryEmbedding, embedding);
-        return {
-            memory: rowToMemory(row),
-            similarity,
-        };
-    })
-        .filter(r => r.similarity > 0.3) // Threshold for relevance
-        .sort((a, b) => b.similarity - a.similarity)
-        .slice(0, limit);
-    return results;
-}
-function buildSearchExplanation(memory, context, values) {
-    const matchedTags = context.queryTags.filter((queryTag) => memory.tags.some((memoryTag) => {
-        const lowerMemoryTag = memoryTag.toLowerCase();
-        return lowerMemoryTag.includes(queryTag) || queryTag.includes(lowerMemoryTag);
-    }));
-    const reasons = [];
-    if (values.vectorSimilarity > 0) {
-        reasons.push(`Semantic similarity ${(values.vectorSimilarity * 100).toFixed(0)}%`);
-    }
-    if (values.ftsScore > 0.3) {
-        reasons.push('Strong keyword match');
-    }
-    if (values.categoryBoost > 0 && context.detectedCategory) {
-        reasons.push(`Matches ${context.detectedCategory} category intent`);
-    }
-    if (matchedTags.length > 0) {
-        reasons.push(`Shared tags: ${matchedTags.slice(0, 3).join(', ')}`);
-    }
-    if (values.recencyBoost > 0) {
-        reasons.push('Recently accessed');
-    }
-    if (values.linkBoost > 0) {
-        reasons.push('Connected to related memories');
-    }
-    if (values.activationBoost > 0) {
-        reasons.push('Activated by recent recall activity');
-    }
-    if (reasons.length === 0) {
-        reasons.push('Ranked by salience and base recall heuristics');
-    }
-    return {
-        query: context.query,
-        reasons,
-        breakdown: {
-            ftsScore: values.ftsScore,
-            vectorSimilarity: values.vectorSimilarity,
-            vectorBoost: values.vectorBoost,
-            decayedScore: values.decayedScore,
-            priorityBoost: values.priorityBoost,
-            recencyBoost: values.recencyBoost,
-            categoryBoost: values.categoryBoost,
-            linkBoost: values.linkBoost,
-            tagBoost: values.tagBoost,
-            activationBoost: values.activationBoost,
-            finalScore: values.finalScore,
-            matchedTags,
-            matchedCategory: values.categoryBoost > 0 ? context.detectedCategory : null,
-        },
-    };
-}
 async function searchMemoriesInternal(options, config, source, execution) {
     if (++searchCount % 100 === 0) {
         pruneActivationCache();
@@ -945,7 +794,7 @@ async function searchMemoriesInternal(options, config, source, execution) {
             if (!queryEmbedding) {
                 throw new Error('query embedding unavailable');
             }
-            const vectorHits = vectorSearch(queryEmbedding, limit * 2, options.project, includeGlobal);
+            const vectorHits = vectorSearch(db, rowToMemory, queryEmbedding, limit * 2, options.project, includeGlobal);
             for (const hit of vectorHits) {
                 vectorResults.set(hit.memory.id, hit.similarity);
             }

package/dist/tools/forget.d.ts

@@ -32,8 +32,8 @@ export declare const forgetSchema: z.ZodObject<{
     } | undefined;
     project?: string | undefined;
     id?: number | undefined;
-    category?: "architecture" | "pattern" | "preference" | "error" | "context" | "learning" | "todo" | "note" | "relationship" | "custom" | undefined;
     query?: string | undefined;
+    category?: "architecture" | "pattern" | "preference" | "error" | "context" | "learning" | "todo" | "note" | "relationship" | "custom" | undefined;
     olderThan?: number | undefined;
     belowSalience?: number | undefined;
 }, {
@@ -43,8 +43,8 @@ export declare const forgetSchema: z.ZodObject<{
     } | undefined;
     project?: string | undefined;
     id?: number | undefined;
-    category?: "architecture" | "pattern" | "preference" | "error" | "context" | "learning" | "todo" | "note" | "relationship" | "custom" | undefined;
     query?: string | undefined;
+    category?: "architecture" | "pattern" | "preference" | "error" | "context" | "learning" | "todo" | "note" | "relationship" | "custom" | undefined;
     olderThan?: number | undefined;
     belowSalience?: number | undefined;
     dryRun?: boolean | undefined;

package/dist/tools/recall.d.ts

@@ -37,9 +37,9 @@ export declare const recallSchema: z.ZodObject<{
     } | undefined;
     project?: string | undefined;
     type?: "short_term" | "long_term" | "episodic" | undefined;
+    query?: string | undefined;
     category?: "architecture" | "pattern" | "preference" | "error" | "context" | "learning" | "todo" | "note" | "relationship" | "custom" | undefined;
     tags?: string[] | undefined;
-    query?: string | undefined;
 }, {
     source?: {
         type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
@@ -49,9 +49,9 @@ export declare const recallSchema: z.ZodObject<{
     mode?: "search" | "important" | "recent" | undefined;
     type?: "short_term" | "long_term" | "episodic" | undefined;
     limit?: number | undefined;
+    query?: string | undefined;
     category?: "architecture" | "pattern" | "preference" | "error" | "context" | "learning" | "todo" | "note" | "relationship" | "custom" | undefined;
     tags?: string[] | undefined;
-    query?: string | undefined;
     includeDecayed?: boolean | undefined;
     includeGlobal?: boolean | undefined;
 }>;

package/hooks/openclaw/cortex-memory/handler.ts

@@ -6,158 +6,22 @@
  * - Context injection on agent bootstrap
  * - Keyword-triggered memory saves
  */
-import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
+import { createOpenClawRuntime } from "./runtime.mjs";
 
 // ==================== SERVER COMMAND RESOLUTION ====================
 
-let _shieldConfig = null;
 let _autoMemoryNoticeShown = false;
-
-async function loadShieldConfig() {
-  if (_shieldConfig) return _shieldConfig;
-
-  try {
-    const configPath = path.join(homedir(), ".shieldcortex", "config.json");
-    _shieldConfig = JSON.parse(await fs.readFile(configPath, "utf-8"));
-  } catch {
-    _shieldConfig = {};
-  }
-
-  return _shieldConfig;
-}
+const runtime = createOpenClawRuntime({ logPrefix: "[cortex-memory]" });
+const loadShieldConfig = runtime.loadShieldConfig;
+const callCortex = runtime.callCortex;
 
 async function isOpenClawAutoMemoryEnabled() {
   const config = await loadShieldConfig();
-  // Default OFF — OpenClaw has its own memory system. User must explicitly opt in.
-  return config?.openclawAutoMemory === true;
-}
-
-/**
- * Resolve the fastest way to invoke shieldcortex:
- * 1. ~/.shieldcortex/config.json "binaryPath" override
- * 2. Global install detected via `which shieldcortex`
- * 3. Fallback to `npx -y shieldcortex` (slow on ARM64)
- */
-let _resolvedServerCmd = null;
-
-async function resolveServerCmd() {
-  if (_resolvedServerCmd) return _resolvedServerCmd;
-
-  // 1. Check config for explicit binaryPath
-  try {
-    const config = await loadShieldConfig();
-    if (config?.binaryPath) {
-      await fs.access(config.binaryPath);
-      _resolvedServerCmd = config.binaryPath;
-      console.log(`[cortex-memory] Using configured binary: ${config.binaryPath}`);
-      return _resolvedServerCmd;
-    }
-  } catch { /* Config not found, no binaryPath, or path invalid */ }
-
-  // 2. Try to find global install via `which`
-  try {
-    const { execFileSync } = await import("node:child_process");
-    const bin = execFileSync("which", ["shieldcortex"], {
-      encoding: "utf-8",
-      timeout: 3000,
-    }).trim();
-    if (bin) {
-      _resolvedServerCmd = bin;
-      console.log(`[cortex-memory] Using global install: ${bin}`);
-      return _resolvedServerCmd;
-    }
-  } catch { /* Not in PATH */ }
-
-  // 3. Fall back to npx (slow but always works)
-  _resolvedServerCmd = "npx -y shieldcortex";
-  console.log("[cortex-memory] Falling back to npx -y shieldcortex (slow path)");
-  return _resolvedServerCmd;
-}
-
-// ==================== CORTEX MCP HELPER ====================
-
-let _lastCallErrorType = null;
-
-function classifyCallError(err) {
-  if (err.killed || err.code === "ETIMEDOUT" || err.signal === "SIGTERM") return "timeout";
-  if (/ENOENT|not found|command not found/i.test(err.message || "")) return "not-found";
-  if (/mcporter/i.test(err.message || "")) return "mcporter";
-  return "unknown";
-}
-
-/**
- * Call a ShieldCortex MCP tool via mcporter
- * @param {string} tool - Tool name (e.g., "remember", "recall", "get_context")
- * @param {Record<string, string>} args - Tool arguments as key:value pairs
- * @param {object} options - Options { retries: number, timeout: number }
- * @returns {Promise<string|null>} Raw stdout or null on error
- */
-async function callCortex(tool, args = {}, options = { retries: 1, timeout: 15000 }) {
-  const serverCmd = await resolveServerCmd();
-
-  return new Promise((resolve) => {
-    const cmdArgs = [
-      "mcporter", "call", "--stdio",
-      serverCmd,
-      tool,
-    ];
-    for (const [key, value] of Object.entries(args)) {
-      // Escape single quotes by doubling them (FTS5-safe)
-      const safe = String(value).replace(/'/g, "''");
-      cmdArgs.push(`${key}:${safe}`);
-    }
-
-    let attempts = 0;
-    const maxAttempts = (options.retries || 0) + 1;
-
-    function attempt() {
-      attempts++;
-      execFile("npx", cmdArgs, {
-        timeout: options.timeout || 15000,
-        maxBuffer: 1024 * 256,
-      }, (err, stdout) => {
-        if (err) {
-          // Distinguish timeout from other errors
-          const isTimeout = err.killed || err.code === "ETIMEDOUT" || err.signal === "SIGTERM";
-          const errorType = isTimeout ? "TIMEOUT" : "ERROR";
-
-          if (attempts < maxAttempts) {
-            console.warn(`[cortex-memory] ${errorType} on ${tool} (attempt ${attempts}/${maxAttempts}), retrying...`);
-            setTimeout(attempt, 1000); // 1s delay before retry
-            return;
-          }
-
-          // One-time categorised warning per error type (prevents spam)
-          const category = classifyCallError(err);
-          if (category !== _lastCallErrorType) {
-            _lastCallErrorType = category;
-            switch (category) {
-              case "timeout":
-                console.warn("[cortex-memory] ShieldCortex call timed out (15s). Memory may be under heavy load.");
-                break;
-              case "not-found":
-                console.warn("[cortex-memory] ShieldCortex binary not found. Run: npm install -g shieldcortex");
-                break;
-              case "mcporter":
-                console.warn("[cortex-memory] mcporter failed to reach ShieldCortex MCP server. Is it configured?");
-                break;
-              default:
-                console.warn(`[cortex-memory] ShieldCortex call failed: ${err.message}`);
-            }
-          }
-          resolve(null);
-          return;
-        }
-        resolve(stdout?.trim() || null);
-      });
-    }
-
-    attempt();
-  });
+  return runtime.isOpenClawAutoMemoryEnabled(config);
 }
 
 // ==================== NOVELTY / DEDUPE GATE ====================