shieldcortex 3.4.37 → 4.0.0

package/dist/memory/staleness.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Memory Staleness Scoring — v4.0.0
+ *
+ * Provides staleness awareness to memories based on age.
+ * Used by search and recall to surface freshness warnings.
+ */
+/**
+ * Days since memory was created.
+ */
+export declare function memoryAgeDays(createdAt: number): number;
+/**
+ * Human-readable age string.
+ */
+export declare function memoryAge(createdAt: number): string;
+/**
+ * Freshness score: 1.0 for today, exponentially decaying.
+ * Half-life of ~7 days: score ≈ 0.5 after a week.
+ */
+export declare function memoryFreshnessScore(createdAt: number): number;
+/**
+ * Warning text for stale memories (>2 days old). Returns null for fresh memories.
+ */
+export declare function memoryFreshnessWarning(createdAt: number): string | null;
+/**
+ * Append staleness warning to a memory's content for display.
+ */
+export declare function appendStalenessWarning(content: string, createdAt: Date): string;

package/dist/memory/staleness.js

@@ -0,0 +1,68 @@
+/**
+ * Memory Staleness Scoring — v4.0.0
+ *
+ * Provides staleness awareness to memories based on age.
+ * Used by search and recall to surface freshness warnings.
+ */
+const MS_PER_DAY = 86_400_000;
+/**
+ * Days since memory was created.
+ */
+export function memoryAgeDays(createdAt) {
+    return Math.max(0, Math.floor((Date.now() - createdAt) / MS_PER_DAY));
+}
+/**
+ * Human-readable age string.
+ */
+export function memoryAge(createdAt) {
+    const days = memoryAgeDays(createdAt);
+    if (days === 0)
+        return 'today';
+    if (days === 1)
+        return 'yesterday';
+    if (days < 7)
+        return `${days} days ago`;
+    if (days < 14)
+        return '1 week ago';
+    if (days < 30)
+        return `${Math.floor(days / 7)} weeks ago`;
+    if (days < 60)
+        return '1 month ago';
+    if (days < 365)
+        return `${Math.floor(days / 30)} months ago`;
+    return `${Math.floor(days / 365)} year${Math.floor(days / 365) > 1 ? 's' : ''} ago`;
+}
+/**
+ * Freshness score: 1.0 for today, exponentially decaying.
+ * Half-life of ~7 days: score ≈ 0.5 after a week.
+ */
+export function memoryFreshnessScore(createdAt) {
+    const days = memoryAgeDays(createdAt);
+    if (days === 0)
+        return 1.0;
+    // Exponential decay with half-life of 7 days
+    return Math.max(0.01, Math.exp(-0.099 * days));
+}
+/**
+ * Warning text for stale memories (>2 days old). Returns null for fresh memories.
+ */
+export function memoryFreshnessWarning(createdAt) {
+    const days = memoryAgeDays(createdAt);
+    if (days <= 2)
+        return null;
+    const age = memoryAge(createdAt);
+    const score = memoryFreshnessScore(createdAt);
+    if (score < 0.1) {
+        return `⚠️ Very stale memory (${age}, freshness ${(score * 100).toFixed(0)}%) — verify before relying on this`;
+    }
+    return `⚠️ Aging memory (${age}, freshness ${(score * 100).toFixed(0)}%) — may need verification`;
+}
+/**
+ * Append staleness warning to a memory's content for display.
+ */
+export function appendStalenessWarning(content, createdAt) {
+    const warning = memoryFreshnessWarning(createdAt.getTime());
+    if (!warning)
+        return content;
+    return `${content}\n\n${warning}`;
+}

package/dist/memory/store.js

@@ -198,6 +198,8 @@ export function rowToMemory(row) {
         sensitivityLevel: row.sensitivity_level ?? 'INTERNAL',
         source: row.source ?? null,
         cloudExcluded: Boolean(row.cloud_excluded),
+        memoryPurpose: (row.memory_purpose ?? 'project'),
+        memoryScope: (row.memory_scope ?? 'private'),
     };
 }
 /**
@@ -417,9 +419,9 @@ export function addMemory(input, config = DEFAULT_CONFIG, source) {
     const stmt = db.prepare(`
     INSERT INTO memories (
       uuid, type, category, title, content, project, tags, salience, metadata, scope, transferable,
-      status, pinned, reviewed_at, reviewed_by, source_kind, capture_method, cloud_excluded, updated_at
+      status, pinned, reviewed_at, reviewed_by, source_kind, capture_method, cloud_excluded, memory_purpose, memory_scope, updated_at
     )
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
   `);
     // Anti-bloat: Truncate content if too large
     const truncationResult = truncateContent(input.content);
@@ -432,7 +434,7 @@ export function addMemory(input, config = DEFAULT_CONFIG, source) {
     // Transaction: INSERT + defence UPDATE must be atomic to prevent wrong trust scores
     const insertedId = db.transaction(() => {
         const memoryUuid = randomUUID();
-        const result = stmt.run(memoryUuid, type, category, input.title, truncationResult.content, input.project || null, JSON.stringify(tags), salience, JSON.stringify(input.metadata || {}), scope, transferable, status, pinned, input.reviewedBy ? new Date().toISOString() : null, input.reviewedBy ?? null, sourceDetails.sourceKind, sourceDetails.captureMethod, cloudExcluded);
+        const result = stmt.run(memoryUuid, type, category, input.title, truncationResult.content, input.project || null, JSON.stringify(tags), salience, JSON.stringify(input.metadata || {}), scope, transferable, status, pinned, input.reviewedBy ? new Date().toISOString() : null, input.reviewedBy ?? null, sourceDetails.sourceKind, sourceDetails.captureMethod, cloudExcluded, input.memoryPurpose || 'project', input.memoryScope || 'private');
         if (defenceResult) {
             db.prepare(`UPDATE memories SET trust_score = ?, sensitivity_level = ?, source = ? WHERE id = ?`)
                 .run(defenceResult.trust.score, defenceResult.sensitivity.level, sourceDetails.sourceValue, result.lastInsertRowid);
@@ -653,6 +655,14 @@ export function updateMemory(id, updates) {
         fields.push('cloud_excluded = ?');
         values.push(updates.cloudExcluded ? 1 : 0);
     }
+    if (updates.memoryPurpose !== undefined) {
+        fields.push('memory_purpose = ?');
+        values.push(updates.memoryPurpose);
+    }
+    if (updates.memoryScope !== undefined) {
+        fields.push('memory_scope = ?');
+        values.push(updates.memoryScope);
+    }
     if (fields.length === 0)
         return existing;
     values.push(id);

package/dist/memory/types.d.ts

@@ -5,6 +5,8 @@ export type MemoryType = 'short_term' | 'long_term' | 'episodic';
 export type MemoryStatus = 'active' | 'archived' | 'suppressed' | 'canonical';
 export type MemorySourceKind = 'user' | 'cli' | 'hook' | 'plugin' | 'agent' | 'import' | 'cloud' | 'api' | 'system';
 export type MemoryCaptureMethod = 'manual' | 'hook' | 'plugin' | 'import' | 'cloud' | 'api' | 'auto' | 'review';
+export type MemoryPurpose = 'user' | 'feedback' | 'project' | 'reference';
+export type MemoryScope = 'private' | 'team';
 export type MemoryCategory = 'architecture' | 'pattern' | 'preference' | 'error' | 'context' | 'learning' | 'todo' | 'note' | 'relationship' | 'custom';
 export interface Memory {
     id: number;
@@ -35,6 +37,8 @@ export interface Memory {
     sensitivityLevel: string;
     source: string | null;
     cloudExcluded: boolean;
+    memoryPurpose: MemoryPurpose;
+    memoryScope: MemoryScope;
 }
 export interface MemoryInput {
     type?: MemoryType;
@@ -56,6 +60,8 @@ export interface MemoryInput {
     sensitivityLevel?: string;
     source?: string | null;
     cloudExcluded?: boolean;
+    memoryPurpose?: MemoryPurpose;
+    memoryScope?: MemoryScope;
 }
 export interface SearchOptions {
     query: string;
@@ -69,6 +75,8 @@ export interface SearchOptions {
     includeGlobal?: boolean;
     includeArchived?: boolean;
     includeSuppressed?: boolean;
+    memoryPurpose?: MemoryPurpose;
+    memoryScope?: MemoryScope;
 }
 export interface SearchResult {
     memory: Memory;
@@ -149,3 +157,7 @@ export declare const DEFAULT_CONFIG: MemoryConfig;
  * Lower threshold = harder to delete (more valuable)
  */
 export declare const DELETION_THRESHOLDS: Record<MemoryCategory, number>;
+export declare const VALID_MEMORY_PURPOSES: MemoryPurpose[];
+export declare const VALID_MEMORY_SCOPES: MemoryScope[];
+export declare function isValidMemoryPurpose(value: unknown): value is MemoryPurpose;
+export declare function isValidMemoryScope(value: unknown): value is MemoryScope;

package/dist/memory/types.js

@@ -27,3 +27,12 @@ export const DELETION_THRESHOLDS = {
     todo: 0.25, // Todos - easier to delete
     custom: 0.22, // Custom memories
 };
+// ── Memory Purpose Validation ────────────────────────────────────
+export const VALID_MEMORY_PURPOSES = ['user', 'feedback', 'project', 'reference'];
+export const VALID_MEMORY_SCOPES = ['private', 'team'];
+export function isValidMemoryPurpose(value) {
+    return typeof value === 'string' && VALID_MEMORY_PURPOSES.includes(value);
+}
+export function isValidMemoryScope(value) {
+    return typeof value === 'string' && VALID_MEMORY_SCOPES.includes(value);
+}

package/dist/tools/recall.js

@@ -8,6 +8,7 @@ import { searchMemories, recallWithEmbeddings, accessMemory, getRecentMemories,
 import { formatTimeSinceAccess } from '../memory/decay.js';
 import { MemoryNotFoundError, formatErrorForMcp } from '../errors.js';
 import { resolveProject } from '../context/project-context.js';
+import { memoryFreshnessWarning } from '../memory/staleness.js';
 const sourceSchema = z.object({
     type: z.enum(['user', 'cli', 'hook', 'email', 'web', 'agent', 'file', 'api', 'tool_response']),
     identifier: z.string(),
@@ -100,6 +101,14 @@ export async function executeRecall(input) {
         }
         // Access each memory to reinforce it
         memories = memories.map(m => accessMemory(m.id, undefined, source) || m);
+        // v4.0.0: Append staleness warnings to old memories
+        memories = memories.map(m => {
+            const warning = memoryFreshnessWarning(m.createdAt.getTime());
+            if (warning) {
+                return { ...m, content: m.content + '\n\n' + warning };
+            }
+            return m;
+        });
         return {
             success: true,
             memories,

package/dist/tools/remember.d.ts

@@ -15,6 +15,8 @@ export declare const rememberSchema: z.ZodObject<{
     importance: z.ZodOptional<z.ZodEnum<["low", "normal", "high", "critical"]>>;
     scope: z.ZodOptional<z.ZodEnum<["project", "global"]>>;
     transferable: z.ZodOptional<z.ZodBoolean>;
+    memoryPurpose: z.ZodOptional<z.ZodEnum<["user", "feedback", "project", "reference"]>>;
+    memoryScope: z.ZodOptional<z.ZodEnum<["private", "team"]>>;
     source: z.ZodOptional<z.ZodObject<{
         type: z.ZodEnum<["user", "cli", "hook", "email", "web", "agent", "file", "api", "tool_response"]>;
         identifier: z.ZodString;
@@ -46,6 +48,8 @@ export declare const rememberSchema: z.ZodObject<{
     sourceIdentifier?: string | undefined;
     sessionId?: string | undefined;
     sourceType?: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response" | undefined;
+    memoryPurpose?: "project" | "user" | "feedback" | "reference" | undefined;
+    memoryScope?: "private" | "team" | undefined;
     importance?: "critical" | "low" | "high" | "normal" | undefined;
     agentId?: string | undefined;
     workspaceDir?: string | undefined;
@@ -65,6 +69,8 @@ export declare const rememberSchema: z.ZodObject<{
     sourceIdentifier?: string | undefined;
     sessionId?: string | undefined;
     sourceType?: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response" | undefined;
+    memoryPurpose?: "project" | "user" | "feedback" | "reference" | undefined;
+    memoryScope?: "private" | "team" | undefined;
     importance?: "critical" | "low" | "high" | "normal" | undefined;
     agentId?: string | undefined;
     workspaceDir?: string | undefined;

package/dist/tools/remember.js

@@ -8,6 +8,7 @@ import { addMemory, searchMemories, detectRelationships, createMemoryLink, getLa
 import { analyzeSalienceFactors, explainSalience } from '../memory/salience.js';
 import { formatErrorForMcp } from '../errors.js';
 import { resolveProject } from '../context/project-context.js';
+import { shouldFilterMemory } from '../memory/save-filter.js';
 // Input schema for the remember tool
 export const rememberSchema = z.object({
     title: z.string().describe('Short title for the memory (what to remember)'),
@@ -26,6 +27,10 @@ export const rememberSchema = z.object({
         .describe('Memory scope: project (default) or global (cross-project)'),
     transferable: z.boolean().optional()
         .describe('Whether this memory can be transferred to other projects'),
+    memoryPurpose: z.enum(['user', 'feedback', 'project', 'reference']).optional()
+        .describe('Purpose of memory: user (preferences), feedback (corrections/confirmations), project (work context), reference (docs/specs)'),
+    memoryScope: z.enum(['private', 'team']).optional()
+        .describe('Scope: private (agent-specific) or team (shared across agents)'),
     source: z.object({
         type: z.enum(['user', 'cli', 'hook', 'email', 'web', 'agent', 'file', 'api', 'tool_response']),
         identifier: z.string(),
@@ -103,6 +108,14 @@ export async function executeRemember(input) {
             };
         }
         // Create the memory (use trimmed title and content)
+        // v4.0.0: Save filter — prevent storing derivable info
+        const filterResult = shouldFilterMemory(title, content);
+        if (!filterResult.allowed) {
+            return {
+                success: false,
+                error: `Memory filtered: ${filterResult.reason}${filterResult.warning ? ' — ' + filterResult.warning : ''}`,
+            };
+        }
         const memory = addMemory({
             title,
             content,
@@ -114,6 +127,8 @@ export async function executeRemember(input) {
             scope: input.scope,
             transferable: input.transferable,
             metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+            memoryPurpose: input.memoryPurpose,
+            memoryScope: input.memoryScope,
         }, undefined, derivedSource ?? { type: 'cli', identifier: 'mcp' });
         // Auto-detect and create relationships with existing memories
         let linksCreated = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shieldcortex",
-  "version": "3.4.37",
+  "version": "4.0.0",
   "description": "Trustworthy memory and security for AI agents. Recall debugging, review queue, OpenClaw session capture, and memory poisoning defence for Claude Code, Codex, OpenClaw, LangChain, and MCP agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/plugins/openclaw/dist/index.js

@@ -12,6 +12,8 @@ import { existsSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { createInterceptor, DEFAULT_CONFIG as DEFAULT_INTERCEPTOR_CONFIG } from './interceptor.js';
+import { syncInterceptEvent } from './intercept-ingest.js';
 let runtimePromise = null;
 function addRuntimeCandidate(candidates, packageRoot) {
     const runtimePath = path.join(packageRoot, "hooks", "openclaw", "cortex-memory", "runtime.mjs");
@@ -583,6 +585,68 @@ export default {
     },
     register(api) {
         applyPluginConfigOverride(api);
+        // --- Interceptor (lazy init) ---
+        let interceptorReady = null;
+        let interceptorInitAttempted = false;
+        async function initInterceptor() {
+            if (interceptorInitAttempted)
+                return interceptorReady;
+            interceptorInitAttempted = true;
+            try {
+                const scConfig = await loadConfig();
+                const rawInterceptorConfig = scConfig.interceptor;
+                const interceptorConfig = {
+                    ...DEFAULT_INTERCEPTOR_CONFIG,
+                    ...(rawInterceptorConfig && typeof rawInterceptorConfig === 'object' ? {
+                        enabled: rawInterceptorConfig.enabled ?? DEFAULT_INTERCEPTOR_CONFIG.enabled,
+                        severityActions: { ...DEFAULT_INTERCEPTOR_CONFIG.severityActions, ...rawInterceptorConfig.severityActions },
+                        failurePolicy: { ...DEFAULT_INTERCEPTOR_CONFIG.failurePolicy, ...rawInterceptorConfig.failurePolicy },
+                    } : {}),
+                    logger: { info: api.logger?.info ?? console.log, warn: api.logger?.warn ?? console.warn },
+                };
+                if (!interceptorConfig.enabled)
+                    return null;
+                // Dynamic import with string variable to prevent TypeScript from resolving
+                // at compile time — 'shieldcortex/defence' only exists at runtime when the
+                // package is installed globally, not during CI builds of the plugin itself.
+                const defenceModPath = 'shieldcortex' + '/defence';
+                const defenceMod = await import(/* webpackIgnore: true */ defenceModPath);
+                if (typeof defenceMod.runDefencePipeline !== 'function')
+                    return null;
+                interceptorReady = createInterceptor(interceptorConfig, defenceMod.runDefencePipeline, {
+                    onAuditEntry: (entry) => syncInterceptEvent(entry, {
+                        cloudApiKey: scConfig.cloudApiKey ?? '',
+                        cloudBaseUrl: scConfig.cloudBaseUrl ?? 'https://api.shieldcortex.ai',
+                        cloudEnabled: scConfig.cloudEnabled ?? false,
+                    }),
+                });
+                api.logger?.info?.('[shieldcortex] Interceptor active — watching: remember, mcp__memory__remember');
+                return interceptorReady;
+            }
+            catch (err) {
+                api.logger?.warn?.(`[shieldcortex] Interceptor init failed: ${err instanceof Error ? err.message : err}`);
+                return null;
+            }
+        }
+        // Register before_tool_call with lazy-init wrapper
+        api.registerHook('before_tool_call', async (context) => {
+            const interceptor = await initInterceptor();
+            if (interceptor)
+                await interceptor.handleToolCall(context);
+        }, {
+            name: 'shieldcortex-intercept-tool',
+            description: 'Active threat gating on tool calls',
+        });
+        // Try to register session_end for cache cleanup
+        try {
+            api.registerHook('session_end', () => { interceptorReady?.resetSession(); }, {
+                name: 'shieldcortex-session-cleanup',
+                description: 'Clear interceptor deny cache on session end',
+            });
+        }
+        catch {
+            // session_end may not be a supported hook — TTL safety net handles this
+        }
         // Explicit capability registration (replaces legacy api.on)
         api.registerHook("llm_input", handleLlmInput, {
             name: "shieldcortex-scan-input",
@@ -595,19 +659,20 @@ export default {
         // Register a lightweight status command so the plugin is not hook-only
         api.registerCommand({
             name: "shieldcortex-status",
-            aliases: ["sc-status"],
             description: "Show ShieldCortex real-time scanner status",
-            async execute({ reply }) {
+            async handler() {
                 const cfg = await loadConfig();
                 const autoMemory = isAutoMemoryEnabled(cfg) ? "on" : "off";
                 const dedupe = isAutoMemoryDedupeEnabled(cfg) ? "on" : "off";
                 const cloud = cfg.cloudApiKey ? "configured" : "not configured";
-                reply(`ShieldCortex v${_version}\n` +
-                    `  Hooks: llm_input (scan), llm_output (memory)\n` +
-                    `  Auto memory: ${autoMemory} | Dedupe: ${dedupe}\n` +
-                    `  Cloud sync: ${cloud}`);
+                return {
+                    text: `ShieldCortex v${_version}\n` +
+                        `  Hooks: llm_input (scan), llm_output (memory)\n` +
+                        `  Auto memory: ${autoMemory} | Dedupe: ${dedupe}\n` +
+                        `  Cloud sync: ${cloud}`,
+                };
             },
         });
-        api.logger.info(`[shieldcortex] v${_version} registered (llm_input + llm_output + /shieldcortex-status)`);
+        api.logger.info(`[shieldcortex] v${_version} registered (llm_input + llm_output + before_tool_call + /shieldcortex-status)`);
     },
 };

package/plugins/openclaw/dist/intercept-ingest.js

@@ -0,0 +1,18 @@
+export function syncInterceptEvent(event, config) {
+    if (!config.cloudEnabled || !config.cloudApiKey)
+        return;
+    const url = `${config.cloudBaseUrl}/v1/audit/ingest`;
+    fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${config.cloudApiKey}`,
+        },
+        body: JSON.stringify({
+            events: [{ ...event, source: 'openclaw-interceptor' }],
+        }),
+        signal: AbortSignal.timeout(5_000),
+    }).catch(() => {
+        // Fire-and-forget — never block on cloud sync failure
+    });
+}