shieldcortex 3.1.0 → 3.2.1

package/dist/memory/store.js

@@ -122,6 +122,32 @@ function safeJsonParse(value, fallback) {
         return fallback;
     }
 }
+function inferSourceDetails(input, source) {
+    const tags = (input.tags ?? []).map((tag) => tag.toLowerCase());
+    if (tags.includes('openclaw-hook')) {
+        return { sourceKind: 'hook', captureMethod: tags.includes('auto-extracted') ? 'auto' : 'hook', sourceValue: 'hook:openclaw' };
+    }
+    if (tags.includes('realtime-plugin') || tags.includes('llm-output')) {
+        return { sourceKind: 'plugin', captureMethod: tags.includes('auto-extracted') ? 'auto' : 'plugin', sourceValue: 'agent:openclaw-plugin' };
+    }
+    if (source?.type === 'hook') {
+        return { sourceKind: 'hook', captureMethod: 'hook', sourceValue: `${source.type}:${source.identifier}` };
+    }
+    if (source?.type === 'agent') {
+        return { sourceKind: 'agent', captureMethod: 'plugin', sourceValue: `${source.type}:${source.identifier}` };
+    }
+    if (source?.type === 'api') {
+        return { sourceKind: 'api', captureMethod: 'api', sourceValue: `${source.type}:${source.identifier}` };
+    }
+    if (source?.type === 'cli') {
+        return { sourceKind: 'cli', captureMethod: 'manual', sourceValue: `${source.type}:${source.identifier}` };
+    }
+    return {
+        sourceKind: input.sourceKind ?? 'user',
+        captureMethod: input.captureMethod ?? (tags.includes('auto-extracted') ? 'auto' : 'manual'),
+        sourceValue: input.source ?? (source ? `${source.type}:${source.identifier}` : 'user:direct'),
+    };
+}
 /**
  * Convert database row to Memory object
  */
@@ -145,6 +171,16 @@ export function rowToMemory(row) {
         embedding: row.embedding,
         scope: row.scope ?? 'project',
         transferable: Boolean(row.transferable),
+        status: (row.status ?? 'active'),
+        pinned: Boolean(row.pinned),
+        reviewedAt: row.reviewed_at ? new Date(row.reviewed_at) : null,
+        reviewedBy: row.reviewed_by ?? null,
+        sourceKind: (row.source_kind ?? 'user'),
+        captureMethod: (row.capture_method ?? 'manual'),
+        trustScore: Number(row.trust_score ?? 1),
+        sensitivityLevel: row.sensitivity_level ?? 'INTERNAL',
+        source: row.source ?? null,
+        cloudExcluded: Boolean(row.cloud_excluded),
     };
 }
 /**
@@ -357,9 +393,16 @@ export function addMemory(input, config = DEFAULT_CONFIG, source) {
     const scope = input.scope ??
         (detectGlobalPattern(input.content, category, tags) ? 'global' : 'project');
     const transferable = input.transferable ?? (scope === 'global' ? 1 : 0);
+    const sourceDetails = inferSourceDetails({ ...input, tags }, source);
+    const status = input.status ?? 'active';
+    const pinned = input.pinned ? 1 : 0;
+    const cloudExcluded = input.cloudExcluded ? 1 : 0;
     const stmt = db.prepare(`
-    INSERT INTO memories (uuid, type, category, title, content, project, tags, salience, metadata, scope, transferable, updated_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+    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
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
   `);
     // Anti-bloat: Truncate content if too large
     const truncationResult = truncateContent(input.content);
@@ -372,10 +415,14 @@ 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);
+        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);
         if (defenceResult) {
             db.prepare(`UPDATE memories SET trust_score = ?, sensitivity_level = ?, source = ? WHERE id = ?`)
-                .run(defenceResult.trust.score, defenceResult.sensitivity.level, `${source.type}:${source.identifier}`, result.lastInsertRowid);
+                .run(defenceResult.trust.score, defenceResult.sensitivity.level, sourceDetails.sourceValue, result.lastInsertRowid);
+        }
+        else {
+            db.prepare(`UPDATE memories SET source = ?, trust_score = COALESCE(trust_score, ?), sensitivity_level = COALESCE(sensitivity_level, ?) WHERE id = ?`)
+                .run(sourceDetails.sourceValue, input.trustScore ?? 1.0, input.sensitivityLevel ?? 'INTERNAL', result.lastInsertRowid);
         }
         return result.lastInsertRowid;
     })();
@@ -455,30 +502,32 @@ export function addMemory(input, config = DEFAULT_CONFIG, source) {
     });
     // Anti-bloat: Check if limits exceeded and trigger async cleanup
     // We use setImmediate to not block the insert response
-    setImmediate(() => {
-        try {
-            if (!isDatabaseInitialized()) {
-                return;
+    if (process.env.NODE_ENV !== 'test') {
+        setImmediate(() => {
+            try {
+                if (!isDatabaseInitialized()) {
+                    return;
+                }
+                const stats = getMemoryStats();
+                if (stats.shortTerm > config.maxShortTermMemories ||
+                    stats.longTerm > config.maxLongTermMemories) {
+                    // Import dynamically to avoid circular dependency
+                    import('./consolidate.js').then(({ enforceMemoryLimits }) => {
+                        if (typeof enforceMemoryLimits === 'function') {
+                            enforceMemoryLimits(config);
+                        }
+                    }).catch((e) => {
+                        // Log but don't fail - consolidation will happen on next scheduled run
+                        console.warn('[shieldcortex] Async cleanup import failed:', e instanceof Error ? e.message : e);
+                    });
+                }
             }
-            const stats = getMemoryStats();
-            if (stats.shortTerm > config.maxShortTermMemories ||
-                stats.longTerm > config.maxLongTermMemories) {
-                // Import dynamically to avoid circular dependency
-                import('./consolidate.js').then(({ enforceMemoryLimits }) => {
-                    if (typeof enforceMemoryLimits === 'function') {
-                        enforceMemoryLimits(config);
-                    }
-                }).catch((e) => {
-                    // Log but don't fail - consolidation will happen on next scheduled run
-                    console.warn('[shieldcortex] Async cleanup import failed:', e instanceof Error ? e.message : e);
-                });
+            catch (e) {
+                // Log unexpected errors in async cleanup
+                console.warn('[shieldcortex] Async cleanup check failed:', e instanceof Error ? e.message : e);
             }
-        }
-        catch (e) {
-            // Log unexpected errors in async cleanup
-            console.warn('[shieldcortex] Async cleanup check failed:', e instanceof Error ? e.message : e);
-        }
-    });
+        });
+    }
     return memory;
 }
 /**
@@ -541,6 +590,44 @@ export function updateMemory(id, updates) {
         fields.push('metadata = ?');
         values.push(JSON.stringify(updates.metadata));
     }
+    if (updates.status !== undefined) {
+        fields.push('status = ?');
+        values.push(updates.status);
+    }
+    if (updates.pinned !== undefined) {
+        fields.push('pinned = ?');
+        values.push(updates.pinned ? 1 : 0);
+    }
+    if (updates.reviewedBy !== undefined) {
+        fields.push('reviewed_by = ?');
+        values.push(updates.reviewedBy);
+        fields.push('reviewed_at = ?');
+        values.push(updates.reviewedBy ? new Date().toISOString() : null);
+    }
+    if (updates.sourceKind !== undefined) {
+        fields.push('source_kind = ?');
+        values.push(updates.sourceKind);
+    }
+    if (updates.captureMethod !== undefined) {
+        fields.push('capture_method = ?');
+        values.push(updates.captureMethod);
+    }
+    if (updates.trustScore !== undefined) {
+        fields.push('trust_score = ?');
+        values.push(updates.trustScore);
+    }
+    if (updates.sensitivityLevel !== undefined) {
+        fields.push('sensitivity_level = ?');
+        values.push(updates.sensitivityLevel);
+    }
+    if (updates.source !== undefined) {
+        fields.push('source = ?');
+        values.push(updates.source);
+    }
+    if (updates.cloudExcluded !== undefined) {
+        fields.push('cloud_excluded = ?');
+        values.push(updates.cloudExcluded ? 1 : 0);
+    }
     if (fields.length === 0)
         return existing;
     values.push(id);
@@ -877,6 +964,12 @@ async function searchMemoriesInternal(options, config, source, execution) {
         sql += ' AND m.type = ?';
         params.push(options.type);
     }
+    if (!options.includeArchived) {
+        sql += ` AND m.status != 'archived'`;
+    }
+    if (!options.includeSuppressed) {
+        sql += ` AND m.status != 'suppressed'`;
+    }
     if (options.minSalience) {
         sql += ' AND m.salience >= ?';
         params.push(options.minSalience);
@@ -915,12 +1008,33 @@ async function searchMemoriesInternal(options, config, source, execution) {
         const vectorSimilarity = vectorResults.get(memory.id) || 0;
         const vectorBoost = vectorSimilarity * 0.3;
         const priorityBoost = calculatePriority(memory) * 0.05;
+        const contradictionCount = db.prepare(`SELECT COUNT(*) as count FROM memory_links WHERE relationship = 'contradicts' AND (source_id = ? OR target_id = ?)`).get(memory.id, memory.id).count;
+        const contradictionPenalty = Math.min(0.12, contradictionCount * 0.03);
+        const eligibilityReasons = [];
+        if (memory.status === 'archived')
+            eligibilityReasons.push('Archived memories are excluded from normal recall');
+        if (memory.status === 'suppressed')
+            eligibilityReasons.push('Suppressed memories are excluded from normal recall');
+        if (memory.cloudExcluded)
+            eligibilityReasons.push('Excluded from cloud sync');
+        if (memory.trustScore < 0.7)
+            eligibilityReasons.push(`Low trust source (${memory.trustScore.toFixed(2)})`);
+        if (contradictionCount > 0)
+            eligibilityReasons.push(`${contradictionCount} contradiction link${contradictionCount === 1 ? '' : 's'} attached`);
         const relevanceScore = (ftsScore * 0.25 +
             vectorBoost +
             decayedScore * 0.2 +
             priorityBoost +
-            recencyBoost + categoryBoost + linkBoost + tagBoost + activationBoost);
-        const result = { memory, relevanceScore };
+            recencyBoost + categoryBoost + linkBoost + tagBoost + activationBoost -
+            contradictionPenalty);
+        const result = {
+            memory,
+            relevanceScore,
+            recallEligibility: {
+                eligible: eligibilityReasons.length === 0,
+                reasons: eligibilityReasons,
+            },
+        };
         if (execution.includeExplanation) {
             result.explanation = buildSearchExplanation(memory, scoringContext, {
                 ftsScore,
@@ -933,8 +1047,12 @@ async function searchMemoriesInternal(options, config, source, execution) {
                 linkBoost,
                 tagBoost,
                 activationBoost,
+                contradictionPenalty,
                 finalScore: relevanceScore,
             });
+            if (result.explanation) {
+                result.explanation.eligibility = result.recallEligibility;
+            }
         }
         return result;
     });

package/dist/memory/types.d.ts

@@ -2,6 +2,9 @@
  * Core type definitions for the ShieldCortex memory system
  */
 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 MemoryCategory = 'architecture' | 'pattern' | 'preference' | 'error' | 'context' | 'learning' | 'todo' | 'note' | 'relationship' | 'custom';
 export interface Memory {
     id: number;
@@ -22,6 +25,16 @@ export interface Memory {
     embedding?: Buffer;
     scope: 'project' | 'global';
     transferable: boolean;
+    status: MemoryStatus;
+    pinned: boolean;
+    reviewedAt: Date | null;
+    reviewedBy: string | null;
+    sourceKind: MemorySourceKind;
+    captureMethod: MemoryCaptureMethod;
+    trustScore: number;
+    sensitivityLevel: string;
+    source: string | null;
+    cloudExcluded: boolean;
 }
 export interface MemoryInput {
     type?: MemoryType;
@@ -34,6 +47,15 @@ export interface MemoryInput {
     metadata?: Record<string, unknown>;
     scope?: 'project' | 'global';
     transferable?: boolean;
+    status?: MemoryStatus;
+    pinned?: boolean;
+    reviewedBy?: string | null;
+    sourceKind?: MemorySourceKind;
+    captureMethod?: MemoryCaptureMethod;
+    trustScore?: number;
+    sensitivityLevel?: string;
+    source?: string | null;
+    cloudExcluded?: boolean;
 }
 export interface SearchOptions {
     query: string;
@@ -45,6 +67,8 @@ export interface SearchOptions {
     limit?: number;
     includeDecayed?: boolean;
     includeGlobal?: boolean;
+    includeArchived?: boolean;
+    includeSuppressed?: boolean;
 }
 export interface SearchResult {
     memory: Memory;
@@ -55,6 +79,7 @@ export interface SearchResult {
         score: number;
     }[];
     explanation?: SearchExplanation;
+    recallEligibility?: RecallEligibility;
 }
 export interface SearchScoreBreakdown {
     ftsScore: number;
@@ -67,14 +92,20 @@ export interface SearchScoreBreakdown {
     linkBoost: number;
     tagBoost: number;
     activationBoost: number;
+    contradictionPenalty: number;
     finalScore: number;
     matchedTags: string[];
     matchedCategory: string | null;
 }
+export interface RecallEligibility {
+    eligible: boolean;
+    reasons: string[];
+}
 export interface SearchExplanation {
     query: string;
     reasons: string[];
     breakdown: SearchScoreBreakdown;
+    eligibility?: RecallEligibility;
 }
 export interface ConsolidationResult {
     consolidated: number;

package/dist/setup/quickstart.js

@@ -41,27 +41,34 @@ function printAutoGuide() {
     lines.push('');
     lines.push('ShieldCortex Quickstart');
     lines.push('────────────────────────────────────────────────────');
+    lines.push('Goal: give your agent memory you can inspect and security you can trust.');
     lines.push(`Detected: Claude=${env.claude ? 'yes' : 'no'} · OpenClaw=${env.openclaw ? 'yes' : 'no'} · Copilot/Cursor=${env.copilot ? 'yes' : 'no'}`);
     lines.push('');
+    lines.push('Best paths:');
+    lines.push('');
     if (env.claude) {
-        lines.push('Best next step for persistent memory in Claude Code:');
+        lines.push('Claude Code');
+        lines.push('  Make recall and review available in Claude sessions:');
         lines.push('  shieldcortex quickstart claude');
         lines.push('');
     }
     if (env.openclaw) {
-        lines.push('Best next step for OpenClaw hook + realtime plugin:');
+        lines.push('OpenClaw');
+        lines.push('  Install the hook + realtime plugin for session capture and defence:');
         lines.push('  shieldcortex quickstart openclaw');
         lines.push('');
     }
     if (env.copilot) {
-        lines.push('Best next step for VS Code / Cursor MCP wiring:');
+        lines.push('VS Code / Cursor');
+        lines.push('  Wire ShieldCortex in as an MCP memory + security layer:');
         lines.push('  shieldcortex quickstart copilot');
         lines.push('');
     }
-    lines.push('Security-only workflow:');
+    lines.push('Security-only');
+    lines.push('  Scan prompts, tools, and environments without adopting memory first:');
     lines.push('  shieldcortex quickstart security');
     lines.push('');
-    lines.push('You can also run one of these directly:');
+    lines.push('Direct commands:');
     lines.push('  shieldcortex setup');
     lines.push('  shieldcortex openclaw install');
     lines.push('  shieldcortex copilot install');
@@ -79,7 +86,7 @@ ShieldCortex Security Quickstart
 2. Audit your local agent environment:
    shieldcortex audit
 
-3. Open the dashboard for quarantine, audit, and graph visibility:
+3. Open the dashboard for quarantine, recall review, and sync visibility:
    shieldcortex dashboard
 `);
 }

package/dist/tools/context.d.ts

@@ -15,23 +15,23 @@ export declare const getContextSchema: z.ZodObject<{
         type: z.ZodEnum<["user", "cli", "hook", "email", "web", "agent", "file", "api", "tool_response"]>;
         identifier: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     }, {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     }>>;
 }, "strip", z.ZodTypeAny, {
     format: "summary" | "detailed" | "raw";
     source?: {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     } | undefined;
     project?: string | undefined;
     query?: string | undefined;
 }, {
     source?: {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     } | undefined;
     project?: string | undefined;

package/dist/tools/forget.d.ts

@@ -17,17 +17,17 @@ export declare const forgetSchema: z.ZodObject<{
         type: z.ZodEnum<["user", "cli", "hook", "email", "web", "agent", "file", "api", "tool_response"]>;
         identifier: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     }, {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     }>>;
 }, "strip", z.ZodTypeAny, {
     dryRun: boolean;
     confirm: boolean;
     source?: {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     } | undefined;
     project?: string | undefined;
@@ -38,7 +38,7 @@ export declare const forgetSchema: z.ZodObject<{
     belowSalience?: number | undefined;
 }, {
     source?: {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     } | undefined;
     project?: string | undefined;

package/dist/tools/recall.d.ts

@@ -20,10 +20,10 @@ export declare const recallSchema: z.ZodObject<{
         type: z.ZodEnum<["user", "cli", "hook", "email", "web", "agent", "file", "api", "tool_response"]>;
         identifier: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     }, {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     }>>;
 }, "strip", z.ZodTypeAny, {
@@ -32,7 +32,7 @@ export declare const recallSchema: z.ZodObject<{
     includeDecayed: boolean;
     includeGlobal: boolean;
     source?: {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     } | undefined;
     project?: string | undefined;
@@ -42,7 +42,7 @@ export declare const recallSchema: z.ZodObject<{
     query?: string | undefined;
 }, {
     source?: {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     } | undefined;
     project?: string | undefined;
@@ -87,22 +87,22 @@ export declare const getMemorySchema: z.ZodObject<{
         type: z.ZodEnum<["user", "cli", "hook", "email", "web", "agent", "file", "api", "tool_response"]>;
         identifier: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     }, {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     }>>;
 }, "strip", z.ZodTypeAny, {
     id: number;
     source?: {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     } | undefined;
 }, {
     id: number;
     source?: {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     } | undefined;
 }>;

package/dist/tools/remember.d.ts

@@ -19,40 +19,55 @@ export declare const rememberSchema: z.ZodObject<{
         type: z.ZodEnum<["user", "cli", "hook", "email", "web", "agent", "file", "api", "tool_response"]>;
         identifier: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     }, {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     }>>;
+    sourceType: z.ZodOptional<z.ZodEnum<["user", "cli", "hook", "email", "web", "agent", "file", "api", "tool_response"]>>;
+    sourceIdentifier: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodString>;
+    workspaceDir: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     title: string;
     content: string;
     scope?: "project" | "global" | undefined;
     transferable?: boolean | undefined;
     source?: {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     } | undefined;
     project?: string | undefined;
     type?: "short_term" | "long_term" | "episodic" | undefined;
     category?: "architecture" | "pattern" | "preference" | "error" | "context" | "learning" | "todo" | "note" | "relationship" | "custom" | undefined;
     tags?: string[] | undefined;
+    sourceIdentifier?: string | undefined;
+    sessionId?: string | undefined;
     importance?: "critical" | "low" | "high" | "normal" | undefined;
+    sourceType?: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response" | undefined;
+    agentId?: string | undefined;
+    workspaceDir?: string | undefined;
 }, {
     title: string;
     content: string;
     scope?: "project" | "global" | undefined;
     transferable?: boolean | undefined;
     source?: {
-        type: "api" | "user" | "cli" | "hook" | "email" | "web" | "agent" | "file" | "tool_response";
+        type: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response";
         identifier: string;
     } | undefined;
     project?: string | undefined;
     type?: "short_term" | "long_term" | "episodic" | undefined;
     category?: "architecture" | "pattern" | "preference" | "error" | "context" | "learning" | "todo" | "note" | "relationship" | "custom" | undefined;
     tags?: string[] | undefined;
+    sourceIdentifier?: string | undefined;
+    sessionId?: string | undefined;
     importance?: "critical" | "low" | "high" | "normal" | undefined;
+    sourceType?: "user" | "cli" | "hook" | "agent" | "api" | "email" | "web" | "file" | "tool_response" | undefined;
+    agentId?: string | undefined;
+    workspaceDir?: string | undefined;
 }>;
 export type RememberInput = z.infer<typeof rememberSchema>;
 /**

package/dist/tools/remember.js

@@ -30,6 +30,13 @@ export const rememberSchema = z.object({
         type: z.enum(['user', 'cli', 'hook', 'email', 'web', 'agent', 'file', 'api', 'tool_response']),
         identifier: z.string(),
     }).optional().describe('Source of this memory for trust scoring (agents should pass this)'),
+    sourceType: z.enum(['user', 'cli', 'hook', 'email', 'web', 'agent', 'file', 'api', 'tool_response']).optional()
+        .describe('Flat source type for integrations that cannot pass nested objects'),
+    sourceIdentifier: z.string().optional()
+        .describe('Flat source identifier for integrations that cannot pass nested objects'),
+    sessionId: z.string().optional().describe('Optional integration session identifier'),
+    agentId: z.string().optional().describe('Optional integration agent identifier'),
+    workspaceDir: z.string().optional().describe('Optional workspace/source path'),
 });
 /**
  * Execute the remember tool
@@ -53,6 +60,14 @@ export async function executeRemember(input) {
         }
         // Resolve project (auto-detect if not provided)
         const resolvedProject = resolveProject(input.project);
+        const derivedSource = input.source ?? (input.sourceType && input.sourceIdentifier
+            ? { type: input.sourceType, identifier: input.sourceIdentifier }
+            : undefined);
+        const metadata = {
+            ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+            ...(input.agentId ? { agentId: input.agentId } : {}),
+            ...(input.workspaceDir ? { workspaceDir: input.workspaceDir } : {}),
+        };
         // Map importance to salience override
         let salienceOverride;
         if (input.importance) {
@@ -96,7 +111,8 @@ export async function executeRemember(input) {
             salience: salienceOverride,
             scope: input.scope,
             transferable: input.transferable,
-        }, undefined, input.source ?? { type: 'cli', identifier: 'mcp' });
+            metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+        }, undefined, derivedSource ?? { type: 'cli', identifier: 'mcp' });
         // Auto-detect and create relationships with existing memories
         let linksCreated = 0;
         try {

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

@@ -400,6 +400,9 @@ async function onSessionEnd(event) {
       scope: "global",
       importance: "high",
       tags: "auto-extracted,openclaw-hook",
+      sourceType: "hook",
+      sourceIdentifier: "openclaw-session-end",
+      workspaceDir: context.workspaceDir || "",
     });
     if (result) {
       saved++;
@@ -468,6 +471,9 @@ async function onSessionStop(event) {
       scope: "global",
       importance: "high",
       tags: "auto-extracted,openclaw-hook,session-stop",
+      sourceType: "hook",
+      sourceIdentifier: "openclaw-session-stop",
+      workspaceDir: context.workspaceDir || "",
     });
     if (result) {
       saved++;
@@ -611,6 +617,8 @@ async function checkAndSaveKeywordTrigger(messageText, event) {
     scope: "global",
     importance: matchedTrigger.importance,
     tags: `keyword-trigger,openclaw-hook,trigger:${matchedTrigger.phrase.replace(/\s+/g, "-")}`,
+    sourceType: "hook",
+    sourceIdentifier: `openclaw-keyword:${matchedTrigger.phrase.replace(/\s+/g, "-")}`,
   });
 
   if (result) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "shieldcortex",
-  "version": "3.1.0",
-  "description": "Persistent brain for AI agents. Knowledge graphs, memory decay, contradiction detection, Iron Dome behaviour protection — plus the only defence pipeline that stops memory poisoning. Works with Claude Code, OpenClaw, LangChain, and any MCP agent.",
+  "version": "3.2.1",
+  "description": "Trustworthy memory and security for AI agents. Recall debugging, review queue, OpenClaw session capture, and memory poisoning defence for Claude Code, OpenClaw, LangChain, and MCP agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {