shieldcortex 3.5.0 → 4.0.0

package/dist/api/routes/memories.js

@@ -4,7 +4,7 @@ import { existsSync, readdirSync, readFileSync } from 'fs';
 import { getDatabase } from '../../database/init.js';
 import { searchMemories, getRecentMemories, getHighPriorityMemories, getMemoryStats, getMemoryById, addMemory, deleteMemory, accessMemory, updateMemory, mergeMemories, promoteMemory, createMemoryLink, rowToMemory, enrichMemory, } from '../../memory/store.js';
 import { calculateDecayedScore } from '../../memory/decay.js';
-import { consolidate, findDuplicateMemoryPairs, formatContextSummary, generateContextSummary, } from '../../memory/consolidate.js';
+import { consolidate, findDuplicateMemoryPairs, formatContextSummary, generateContextSummary, consolidateMemories, } from '../../memory/consolidate.js';
 import { getActivationStats, getActiveMemories } from '../../memory/activation.js';
 import { detectContradictions, getContradictionsFor } from '../../memory/contradiction.js';
 import { emitConsolidation } from '../events.js';
@@ -495,7 +495,7 @@ export function registerMemoryRoutes(app, deps) {
         enforceAmber: true,
     }), (req, res) => {
         try {
-            const { title, content, type, category, project, tags, salience } = req.body;
+            const { title, content, type, category, project, tags, salience, memoryPurpose, memoryScope } = req.body;
             if (!title || !content) {
                 return res.status(400).json({ error: 'Title and content required' });
             }
@@ -507,6 +507,8 @@ export function registerMemoryRoutes(app, deps) {
                 project,
                 tags: tags || [],
                 salience,
+                memoryPurpose: memoryPurpose || undefined,
+                memoryScope: memoryScope || undefined,
             });
             res.status(201).json(memory);
         }
@@ -974,7 +976,7 @@ export function registerMemoryRoutes(app, deps) {
     }), (req, res) => {
         try {
             const id = parseInt(req.params.id, 10);
-            const { title, content, category, tags, importance, status, pinned, reviewedBy, cloudExcluded, scope, project } = req.body;
+            const { title, content, category, tags, importance, status, pinned, reviewedBy, cloudExcluded, scope, project, memoryPurpose, memoryScope } = req.body;
             if (title !== undefined && (typeof title !== 'string' || title.trim().length === 0)) {
                 return res.status(400).json({ error: 'Title must be a non-empty string' });
             }
@@ -1127,4 +1129,17 @@ export function registerMemoryRoutes(app, deps) {
             res.status(500).json({ error: error.message });
         }
     });
+    // v4.0.0: Dream Mode — comprehensive memory consolidation
+    app.post('/api/consolidate', requireNotLocked, (_req, res) => {
+        try {
+            const result = consolidateMemories();
+            res.json({
+                success: true,
+                ...result,
+            });
+        }
+        catch (error) {
+            res.status(500).json({ error: error.message });
+        }
+    });
 }

package/dist/cortex/cli.js

@@ -3,7 +3,7 @@
  * Pro tier feature: systematic mistake learning + pre-flight checks.
  */
 import { requireFeature } from '../license/gate.js';
-import { capture, preflight, review, graduate, search, loadMistakes, } from './store.js';
+import { capture, preflight, review, graduate, search, loadMistakes, captureConfirmation, searchConfirmations, loadConfirmations, } from './store.js';
 const SEVERITY_ICON = {
     critical: '🔴',
     high: '🟠',
@@ -26,11 +26,14 @@ function printUsage() {
     list        Browse mistake log
     stats       Summary counts and trends
     search      Full-text search across all entries
+    confirm     Log a positive confirmation (what worked well)
+    confirmations  List or search confirmations
 
   Examples:
     shieldcortex cortex capture --category code --what "Guessed URLs" --why "Didn't use API" --rule "Always fetch handles from API"
     shieldcortex cortex preflight --task "deploy to Fly.io"
     shieldcortex cortex review
+    shieldcortex cortex confirm --category code --what "Used TypeScript strict mode" --why-worked "Caught type errors early" --when-repeat "Always on new TS projects"
     shieldcortex cortex stats
   `);
 }
@@ -184,6 +187,46 @@ export async function handleCortexCommand(args) {
             }
             break;
         }
+        case 'confirm': {
+            if (!opts.category || !opts.what || !opts['why-worked'] || !opts['when-repeat']) {
+                console.error('Required: --category, --what, --why-worked, --when-repeat');
+                console.error(`Categories: ${VALID_CATEGORIES.join(', ')}`);
+                process.exit(1);
+            }
+            if (!VALID_CATEGORIES.includes(opts.category)) {
+                console.error(`Invalid category. Valid: ${VALID_CATEGORIES.join(', ')}`);
+                process.exit(1);
+            }
+            const entry = captureConfirmation({
+                category: opts.category,
+                what: opts.what,
+                whyItWorked: opts['why-worked'],
+                whenToRepeat: opts['when-repeat'],
+                tags: opts.tags ? opts.tags.split(',').map(t => t.trim()) : [],
+                agent: opts.agent,
+                taskContext: opts.context,
+            });
+            console.log(`✅ Captured confirmation #${entry.id}: ${entry.what.slice(0, 60)}`);
+            console.log(`   Why it worked: ${entry.whyItWorked}`);
+            console.log(`   When to repeat: ${entry.whenToRepeat}`);
+            break;
+        }
+        case 'confirmations': {
+            const query = opts.query;
+            const confirmations = query ? searchConfirmations(query) : loadConfirmations();
+            if (confirmations.length === 0) {
+                console.log(query ? `No confirmations matching '${query}'` : 'No confirmations logged yet.');
+            }
+            else {
+                console.log(`🎯 ${confirmations.length} confirmation(s)${query ? ` matching '${query}'` : ''}:\n`);
+                for (const c of confirmations) {
+                    console.log(`  ✅ #${c.id} [${c.category}] ${c.what}`);
+                    console.log(`     Why: ${c.whyItWorked}`);
+                    console.log(`     Repeat: ${c.whenToRepeat}\n`);
+                }
+            }
+            break;
+        }
         default:
             printUsage();
     }

package/dist/cortex/store.d.ts

@@ -50,3 +50,26 @@ export declare function preflight(taskDescription: string): PreflightMatch[];
 export declare function review(): ReviewStats;
 export declare function graduate(): number;
 export declare function search(query: string): Mistake[];
+export interface Confirmation {
+    id: number;
+    timestamp: string;
+    category: MistakeCategory;
+    what: string;
+    whyItWorked: string;
+    whenToRepeat: string;
+    tags: string[];
+    agent?: string;
+    taskContext?: string;
+}
+export declare function loadConfirmations(): Confirmation[];
+export declare function saveConfirmations(confirmations: Confirmation[]): void;
+export declare function captureConfirmation(opts: {
+    category: MistakeCategory;
+    what: string;
+    whyItWorked: string;
+    whenToRepeat: string;
+    tags?: string[];
+    agent?: string;
+    taskContext?: string;
+}): Confirmation;
+export declare function searchConfirmations(query: string): Confirmation[];

package/dist/cortex/store.js

@@ -157,3 +157,46 @@ export function search(query) {
         return text.includes(q);
     });
 }
+function getConfirmationsFile() {
+    return join(getDataDir(), 'confirmations.json');
+}
+export function loadConfirmations() {
+    const file = getConfirmationsFile();
+    if (!existsSync(file))
+        return [];
+    try {
+        return JSON.parse(readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return [];
+    }
+}
+export function saveConfirmations(confirmations) {
+    const file = getConfirmationsFile();
+    writeFileSync(file, JSON.stringify(confirmations, null, 2) + '\n', { mode: 0o600 });
+}
+export function captureConfirmation(opts) {
+    const confirmations = loadConfirmations();
+    const entry = {
+        id: confirmations.length + 1,
+        timestamp: new Date().toISOString(),
+        category: opts.category,
+        what: opts.what,
+        whyItWorked: opts.whyItWorked,
+        whenToRepeat: opts.whenToRepeat,
+        tags: opts.tags || [],
+        agent: opts.agent,
+        taskContext: opts.taskContext,
+    };
+    confirmations.push(entry);
+    saveConfirmations(confirmations);
+    return entry;
+}
+export function searchConfirmations(query) {
+    const confirmations = loadConfirmations();
+    const lower = query.toLowerCase();
+    return confirmations.filter(c => c.what.toLowerCase().includes(lower) ||
+        c.whyItWorked.toLowerCase().includes(lower) ||
+        c.whenToRepeat.toLowerCase().includes(lower) ||
+        c.tags.some(t => t.toLowerCase().includes(lower)));
+}

package/dist/database/init.js

@@ -784,6 +784,14 @@ function runMigrations(database) {
     if (!columnNames.has('graph_extraction_version')) {
         database.exec('ALTER TABLE memories ADD COLUMN graph_extraction_version INTEGER DEFAULT 0');
     }
+    // Migration: v4.0.0 — memory_purpose for type taxonomy
+    if (!columnNames.has('memory_purpose')) {
+        database.exec("ALTER TABLE memories ADD COLUMN memory_purpose TEXT DEFAULT 'project'");
+    }
+    // Migration: v4.0.0 — memory_scope for private/team visibility
+    if (!columnNames.has('memory_scope')) {
+        database.exec("ALTER TABLE memories ADD COLUMN memory_scope TEXT DEFAULT 'private'");
+    }
     // Migration: Pro feature tables (custom_patterns, iron_dome_policies, firewall_rules)
     try {
         database.exec(`
@@ -1054,7 +1062,9 @@ function getInlineSchema() {
       trust_score REAL DEFAULT 1.0,
       sensitivity_level TEXT DEFAULT 'INTERNAL',
       source TEXT DEFAULT 'user:direct',
-      graph_extraction_version INTEGER DEFAULT 0
+      graph_extraction_version INTEGER DEFAULT 0,
+      memory_purpose TEXT DEFAULT 'project',
+      memory_scope TEXT DEFAULT 'private'
     );
 
     CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(

package/dist/index.js

@@ -749,6 +749,20 @@ ${bold}DOCS${reset}
         console.log(`\n${bold}Summary:${reset} ${filesToScan.length} scanned, ${threatCount} with threats\n`);
         process.exit(threatCount > 0 ? 1 : 0);
     }
+    // Handle "consolidate" subcommand (v4.0.0 — Dream Mode)
+    if (process.argv[2] === 'consolidate') {
+        const { initDatabase } = await import('./database/init.js');
+        initDatabase();
+        const { consolidateMemories } = await import('./memory/consolidate.js');
+        console.log('🧠 Starting Dream Mode consolidation...');
+        const result = consolidateMemories();
+        console.log(`✅ Consolidation complete:`);
+        console.log(`   Near-duplicates merged: ${result.nearDuplicatesMerged}`);
+        console.log(`   Archival candidates:    ${result.archivalCandidates}`);
+        console.log(`   Contradictions found:   ${result.contradictionsDetected}`);
+        console.log(`   Total processed:        ${result.totalProcessed}`);
+        process.exit(0);
+    }
     // Handle "cortex" subcommand (Pro tier — mistake learning)
     if (process.argv[2] === 'cortex') {
         const { handleCortexCommand } = await import('./cortex/cli.js');
@@ -760,7 +774,7 @@ ${bold}DOCS${reset}
         'doctor', 'quickstart', 'setup', 'install', 'migrate', 'uninstall', 'hook',
         'openclaw', 'clawdbot', 'copilot', 'codex', 'service', 'config', 'status',
         'graph', 'license', 'licence', 'audit', 'iron-dome', 'scan', 'cloud',
-        'scan-skill', 'scan-skills', 'dashboard', 'api', 'worker', 'stats', 'cortex',
+        'scan-skill', 'scan-skills', 'dashboard', 'api', 'worker', 'stats', 'cortex', 'consolidate',
     ]);
     const arg = process.argv[2];
     if (arg && !arg.startsWith('-') && !knownCommands.has(arg)) {

package/dist/lib.d.ts

@@ -38,3 +38,14 @@ export type { AuditFinding, AuditSeverity } from './audit/types.js';
 export { getLicense, getLicenseTier, isFeatureEnabled, requireFeature, listFeatures, FeatureGatedError, verifyLicenseKey, TIER_RANK, } from './license/index.js';
 export type { LicenseTier, LicenseInfo, GatedFeature, } from './license/index.js';
 export declare const version: string;
+export { memoryAgeDays, memoryAge, memoryFreshnessScore, memoryFreshnessWarning, appendStalenessWarning, } from './memory/staleness.js';
+export { rerankResults, buildRerankPrompt, parseRerankResponse, DEFAULT_RERANK_CONFIG, } from './memory/rerank.js';
+export type { RerankConfig } from './memory/rerank.js';
+export { consolidateMemories, } from './memory/consolidate.js';
+export type { DreamModeResult } from './memory/consolidate.js';
+export { shouldFilterMemory, DEFAULT_SAVE_FILTER_CONFIG, } from './memory/save-filter.js';
+export type { SaveFilterConfig, SaveFilterResult } from './memory/save-filter.js';
+export { captureConfirmation, searchConfirmations, loadConfirmations, } from './cortex/store.js';
+export type { Confirmation } from './cortex/store.js';
+export type { MemoryPurpose, MemoryScope, } from './memory/types.js';
+export { VALID_MEMORY_PURPOSES, VALID_MEMORY_SCOPES, isValidMemoryPurpose, isValidMemoryScope, } from './memory/types.js';

package/dist/lib.js

@@ -45,3 +45,10 @@ import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
 export const version = pkg.version;
+// ── v4.0.0: New Modules ────────────────────────────────────────
+export { memoryAgeDays, memoryAge, memoryFreshnessScore, memoryFreshnessWarning, appendStalenessWarning, } from './memory/staleness.js';
+export { rerankResults, buildRerankPrompt, parseRerankResponse, DEFAULT_RERANK_CONFIG, } from './memory/rerank.js';
+export { consolidateMemories, } from './memory/consolidate.js';
+export { shouldFilterMemory, DEFAULT_SAVE_FILTER_CONFIG, } from './memory/save-filter.js';
+export { captureConfirmation, searchConfirmations, loadConfirmations, } from './cortex/store.js';
+export { VALID_MEMORY_PURPOSES, VALID_MEMORY_SCOPES, isValidMemoryPurpose, isValidMemoryScope, } from './memory/types.js';

package/dist/memory/consolidate.d.ts

@@ -132,3 +132,17 @@ export declare function fullCleanup(config?: MemoryConfig): {
     merged: number;
     quarantineExpired: number;
 };
+export interface DreamModeResult {
+    nearDuplicatesMerged: number;
+    archivalCandidates: number;
+    contradictionsDetected: number;
+    totalProcessed: number;
+}
+/**
+ * "Dream Mode" — comprehensive memory consolidation.
+ *
+ * 1. Find near-duplicates by embedding similarity >0.9, merge them
+ * 2. Flag memories >30 days old with no access as archival candidates
+ * 3. Detect and flag contradictions
+ */
+export declare function consolidateMemories(): DreamModeResult;

package/dist/memory/consolidate.js

@@ -763,3 +763,76 @@ export function fullCleanup(config = DEFAULT_CONFIG) {
     }
     return { consolidation, vacuumed, merged, quarantineExpired };
 }
+/**
+ * "Dream Mode" — comprehensive memory consolidation.
+ *
+ * 1. Find near-duplicates by embedding similarity >0.9, merge them
+ * 2. Flag memories >30 days old with no access as archival candidates
+ * 3. Detect and flag contradictions
+ */
+export function consolidateMemories() {
+    const db = getDatabase();
+    let nearDuplicatesMerged = 0;
+    let archivalCandidates = 0;
+    let contradictionsDetected = 0;
+    // Step 1: Find and merge near-duplicates
+    const duplicatePairs = findDuplicateMemoryPairs({ limit: 100 });
+    for (const pair of duplicatePairs) {
+        try {
+            const memA = pair.memoryA;
+            const memB = pair.memoryB;
+            if (!memA || !memB)
+                continue;
+            // Keep the recommended one, delete the other
+            const removedId = pair.recommendedKeepId === memA.id ? memB.id : memA.id;
+            const keptId = pair.recommendedKeepId;
+            // Merge tags from both
+            const kept = keptId === memA.id ? memA : memB;
+            const removed = keptId === memA.id ? memB : memA;
+            const mergedTags = [...new Set([...kept.tags, ...removed.tags])];
+            db.prepare('UPDATE memories SET tags = ? WHERE id = ?')
+                .run(JSON.stringify(mergedTags), keptId);
+            deleteMemory(removedId);
+            nearDuplicatesMerged++;
+        }
+        catch {
+            // Skip problematic pairs
+        }
+    }
+    // Step 2: Flag stale memories for archival (>30 days, no access)
+    const thirtyDaysAgo = new Date(Date.now() - 30 * 86_400_000).toISOString();
+    const staleRows = db.prepare(`
+    SELECT id FROM memories
+    WHERE status = 'active'
+      AND last_accessed < ?
+      AND access_count <= 1
+      AND pinned = 0
+  `).all(thirtyDaysAgo);
+    for (const row of staleRows) {
+        try {
+            db.prepare("UPDATE memories SET status = 'archived', updated_at = CURRENT_TIMESTAMP WHERE id = ?")
+                .run(row.id);
+            archivalCandidates++;
+        }
+        catch {
+            // Skip
+        }
+    }
+    // Step 3: Detect contradictions
+    try {
+        const contradictions = detectContradictions();
+        if (contradictions.length > 0) {
+            contradictionsDetected = linkContradictions(contradictions);
+        }
+    }
+    catch {
+        // Contradiction detection may fail on empty/small DBs
+    }
+    const totalProcessed = duplicatePairs.length + staleRows.length;
+    return {
+        nearDuplicatesMerged,
+        archivalCandidates,
+        contradictionsDetected,
+        totalProcessed,
+    };
+}

package/dist/memory/rerank.d.ts

@@ -0,0 +1,31 @@
+/**
+ * LLM-Powered Memory Reranking — v4.0.0
+ *
+ * Optional hybrid recall: after embedding-based retrieval returns top-N candidates,
+ * send them to an LLM to rerank by relevance to the query.
+ */
+import type { SearchResult } from './types.js';
+export interface RerankConfig {
+    enabled: boolean;
+    model: string;
+    maxCandidates: number;
+}
+export declare const DEFAULT_RERANK_CONFIG: RerankConfig;
+/**
+ * Build the reranking prompt for the LLM.
+ */
+export declare function buildRerankPrompt(query: string, candidates: {
+    id: number;
+    title: string;
+    content: string;
+}[]): string;
+/**
+ * Parse the LLM response to extract the reranked order.
+ * Returns array of memory IDs in relevance order.
+ */
+export declare function parseRerankResponse(response: string): number[];
+/**
+ * Rerank search results using an LLM.
+ * This is a framework function — the actual LLM call is delegated to a caller-provided function.
+ */
+export declare function rerankResults(query: string, results: SearchResult[], llmCall: (prompt: string) => Promise<string>, config?: RerankConfig): Promise<SearchResult[]>;

package/dist/memory/rerank.js

@@ -0,0 +1,88 @@
+/**
+ * LLM-Powered Memory Reranking — v4.0.0
+ *
+ * Optional hybrid recall: after embedding-based retrieval returns top-N candidates,
+ * send them to an LLM to rerank by relevance to the query.
+ */
+export const DEFAULT_RERANK_CONFIG = {
+    enabled: false,
+    model: 'sonnet',
+    maxCandidates: 20,
+};
+/**
+ * Build the reranking prompt for the LLM.
+ */
+export function buildRerankPrompt(query, candidates) {
+    const candidateList = candidates
+        .map((c, i) => `[${i + 1}] ID=${c.id} | Title: ${c.title}\n${c.content.slice(0, 200)}`)
+        .join('\n\n');
+    return `Given the query: "${query}"
+
+Rank the following memory candidates by relevance to the query. Return ONLY a JSON array of memory IDs in order of relevance (most relevant first).
+
+Candidates:
+${candidateList}
+
+Response format: [id1, id2, id3, ...]`;
+}
+/**
+ * Parse the LLM response to extract the reranked order.
+ * Returns array of memory IDs in relevance order.
+ */
+export function parseRerankResponse(response) {
+    try {
+        // Try to extract JSON array from the response
+        const match = response.match(/\[[\d,\s]+\]/);
+        if (match) {
+            return JSON.parse(match[0]);
+        }
+        // Fallback: extract numbers in order
+        const numbers = response.match(/\d+/g);
+        return numbers ? numbers.map(Number) : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Rerank search results using an LLM.
+ * This is a framework function — the actual LLM call is delegated to a caller-provided function.
+ */
+export async function rerankResults(query, results, llmCall, config = DEFAULT_RERANK_CONFIG) {
+    if (!config.enabled || results.length <= 1) {
+        return results;
+    }
+    const candidates = results.slice(0, config.maxCandidates).map(r => ({
+        id: r.memory.id,
+        title: r.memory.title,
+        content: r.memory.content,
+    }));
+    const prompt = buildRerankPrompt(query, candidates);
+    try {
+        const response = await llmCall(prompt);
+        const rankedIds = parseRerankResponse(response);
+        if (rankedIds.length === 0) {
+            return results; // Fallback to original order
+        }
+        // Build a map for O(1) lookup
+        const resultMap = new Map(results.map(r => [r.memory.id, r]));
+        const reranked = [];
+        // Add results in LLM-determined order
+        for (const id of rankedIds) {
+            const result = resultMap.get(id);
+            if (result) {
+                reranked.push(result);
+                resultMap.delete(id);
+            }
+        }
+        // Append any results not mentioned by the LLM
+        for (const remaining of resultMap.values()) {
+            reranked.push(remaining);
+        }
+        return reranked;
+    }
+    catch {
+        // If LLM reranking fails, return original order
+        return results;
+    }
+}

package/dist/memory/save-filter.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Memory Save Filter — v4.0.0
+ *
+ * Prevents saving derivable information that can be found in
+ * code, git history, or file system.
+ */
+export interface SaveFilterConfig {
+    filterDerivable: boolean;
+}
+export declare const DEFAULT_SAVE_FILTER_CONFIG: SaveFilterConfig;
+export interface SaveFilterResult {
+    allowed: boolean;
+    reason?: string;
+    warning?: string;
+}
+/**
+ * Check whether a memory should be filtered (not saved).
+ */
+export declare function shouldFilterMemory(title: string, content: string, config?: SaveFilterConfig): SaveFilterResult;

package/dist/memory/save-filter.js

@@ -0,0 +1,60 @@
+/**
+ * Memory Save Filter — v4.0.0
+ *
+ * Prevents saving derivable information that can be found in
+ * code, git history, or file system.
+ */
+export const DEFAULT_SAVE_FILTER_CONFIG = {
+    filterDerivable: true,
+};
+// Patterns that suggest derivable content
+const DERIVABLE_PATTERNS = [
+    // File paths that can be found with grep/find
+    { pattern: /^(?:the )?file (?:is )?(?:at |located at )?[\/~][\w\/.@-]+$/i, reason: 'File paths are discoverable via file system' },
+    // Git commit references
+    { pattern: /^(?:commit |git )(?:hash |sha )?[0-9a-f]{7,40}/i, reason: 'Git history is queryable with git log' },
+    // Simple grep-able patterns
+    { pattern: /^(?:the )?(?:function|class|method|variable|const|let|var) ['"`]?\w+['"`]? (?:is |exists )?(?:in|at) /i, reason: 'Code symbols are discoverable via grep/search' },
+    // Package version info
+    { pattern: /^(?:the )?(?:version|pkg) (?:of |is )?\w+(?:@| is )[\d.]+/i, reason: 'Package versions are in package.json/lock files' },
+    // Environment variable values
+    { pattern: /^(?:the )?(?:env(?:ironment)? )?(?:var(?:iable)? )?[A-Z_]{3,}(?:\s*=\s*|\s+is\s+)/i, reason: 'Environment variables should not be stored in memory (security risk)' },
+];
+// Content characteristics that suggest derivable info
+const DERIVABLE_SIGNALS = [
+    { test: (c) => /^(?:import|require|from)\s/m.test(c), reason: 'Import statements are visible in source code' },
+    { test: (c) => c.split('\n').length <= 2 && /^\s*(?:cd |ls |cat |grep |find |git )\s/m.test(c), reason: 'Shell commands are not valuable to memorize' },
+];
+/**
+ * Check whether a memory should be filtered (not saved).
+ */
+export function shouldFilterMemory(title, content, config = DEFAULT_SAVE_FILTER_CONFIG) {
+    if (!config.filterDerivable) {
+        return { allowed: true };
+    }
+    const combined = `${title}\n${content}`.trim();
+    // Check against derivable patterns
+    for (const { pattern, reason } of DERIVABLE_PATTERNS) {
+        if (pattern.test(title) || pattern.test(content)) {
+            return { allowed: false, reason };
+        }
+    }
+    // Check content signals
+    for (const { test, reason } of DERIVABLE_SIGNALS) {
+        if (test(combined)) {
+            return { allowed: false, reason, warning: `Filtered: ${reason}` };
+        }
+    }
+    // Heuristic: very short content with file path patterns = likely derivable
+    if (combined.length < 100) {
+        const pathCount = (combined.match(/[\/~][\w\/.@-]{5,}/g) || []).length;
+        if (pathCount > 0 && combined.replace(/[\/~][\w\/.@-]+/g, '').trim().length < 30) {
+            return {
+                allowed: false,
+                reason: 'Content appears to be primarily file paths (discoverable via file system)',
+                warning: 'Memory content is mostly file paths — these are discoverable without memory',
+            };
+        }
+    }
+    return { allowed: true };
+}

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;