shieldcortex 4.12.14 → 4.13.0

package/dist/memory/lifecycle.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Memory lifecycle operations.
+ *
+ * Phase 2 of the audit-recommended store.ts split. The "lifecycle"
+ * group is the set of functions that mutate a memory's state over
+ * time *without* being CRUD: access reinforcement, search
+ * reinforcement, enrichment, decay-score persistence, STM→LTM
+ * promotion, and bulk decay cleanup. Lifted out of store.ts (still
+ * 1,800+ lines after phase 1) so each concern can be read on its
+ * own. No behaviour change vs the original implementation — exports
+ * re-emerge from store.ts via a barrel re-export so existing import
+ * paths keep working.
+ *
+ * Imports from store.ts (getMemoryById, rowToMemory, getMemoriesByType,
+ * MAX_CONTENT_SIZE) form a module cycle. Both directions only invoke
+ * the imported symbols inside function bodies — ESM live bindings
+ * handle this correctly at runtime. As of phase 3, reinforceFromSearch
+ * and enrichMemory are consumed by search-recall.ts (not store.ts);
+ * that import is non-cyclic since search-recall.ts is a leaf consumer
+ * of lifecycle.ts.
+ */
+import { Memory, MemoryConfig } from './types.js';
+import type { DefenceSource } from '../defence/types.js';
+/**
+ * Access a memory (updates access count and timestamp, returns reinforced memory)
+ */
+export declare function accessMemory(id: number, config?: MemoryConfig, source?: DefenceSource): Memory | null;
+/**
+ * Reinforce a memory that appeared in search results
+ * Gives a small salience boost with diminishing returns based on access count.
+ * ORGANIC FEATURE: Searched memories get reinforced, closing the feedback loop
+ * so frequently-found memories grow stronger over time.
+ */
+export declare function reinforceFromSearch(memoryId: number): void;
+/**
+ * Enrichment result indicating what happened
+ */
+export interface EnrichmentResult {
+    enriched: boolean;
+    reason: string;
+}
+/**
+ * Enrich a memory with additional context
+ *
+ * This adds timestamped context to a memory when:
+ * 1. The new context is sufficiently related but different (new information)
+ * 2. The memory hasn't been enriched recently (cooldown)
+ * 3. The content won't exceed the size limit
+ *
+ * ORGANIC FEATURE: Memories grow with new context over time,
+ * mimicking how human memories are reconsolidated with new information
+ *
+ * @param memoryId - ID of the memory to enrich
+ * @param newContext - New context to add
+ * @param contextType - Type of context ('search' | 'access' | 'related')
+ * @returns EnrichmentResult indicating success or failure with reason
+ */
+export declare function enrichMemory(memoryId: number, newContext: string, contextType?: 'search' | 'access' | 'related'): EnrichmentResult;
+/**
+ * Clear enrichment cooldown for a memory (for testing)
+ */
+export declare function clearEnrichmentCooldown(memoryId: number): void;
+/**
+ * Get enrichment cooldown status for a memory
+ */
+export declare function getEnrichmentCooldownStatus(memoryId: number): {
+    onCooldown: boolean;
+    remainingMs: number;
+};
+/**
+ * Update persisted decay scores for all memories
+ * Called during consolidation and periodically by the API server
+ * Returns the number of memories updated
+ */
+export declare function updateDecayScores(): number;
+/**
+ * Promote a memory from short-term to long-term
+ */
+export declare function promoteMemory(id: number): Memory | null;
+/**
+ * Bulk delete decayed memories
+ */
+export declare function cleanupDecayedMemories(config?: MemoryConfig): number;

package/dist/memory/lifecycle.js

@@ -0,0 +1,274 @@
+/**
+ * Memory lifecycle operations.
+ *
+ * Phase 2 of the audit-recommended store.ts split. The "lifecycle"
+ * group is the set of functions that mutate a memory's state over
+ * time *without* being CRUD: access reinforcement, search
+ * reinforcement, enrichment, decay-score persistence, STM→LTM
+ * promotion, and bulk decay cleanup. Lifted out of store.ts (still
+ * 1,800+ lines after phase 1) so each concern can be read on its
+ * own. No behaviour change vs the original implementation — exports
+ * re-emerge from store.ts via a barrel re-export so existing import
+ * paths keep working.
+ *
+ * Imports from store.ts (getMemoryById, rowToMemory, getMemoriesByType,
+ * MAX_CONTENT_SIZE) form a module cycle. Both directions only invoke
+ * the imported symbols inside function bodies — ESM live bindings
+ * handle this correctly at runtime. As of phase 3, reinforceFromSearch
+ * and enrichMemory are consumed by search-recall.ts (not store.ts);
+ * that import is non-cyclic since search-recall.ts is a leaf consumer
+ * of lifecycle.ts.
+ */
+import { getDatabase } from '../database/init.js';
+import { DEFAULT_CONFIG, } from './types.js';
+import { calculateReinforcementBoost, calculateDecayedScore, } from './decay.js';
+import { activateMemory as spreadActivation } from './activation.js';
+import { jaccardSimilarity } from './similarity.js';
+import { emitMemoryAccessed, emitMemoryUpdated, persistEvent, } from '../api/events.js';
+import { createMemoryLink } from './links.js';
+// Cyclic import — see header. getMemoryById/rowToMemory/getMemoriesByType
+// live in store.ts; MAX_CONTENT_SIZE is the per-memory content budget
+// that both truncateContent (store.ts) and enrichMemory (here) honour.
+import { getMemoryById, rowToMemory, getMemoriesByType, MAX_CONTENT_SIZE, } from './store.js';
+/**
+ * Access a memory (updates access count and timestamp, returns reinforced memory)
+ */
+export function accessMemory(id, config = DEFAULT_CONFIG, source) {
+    const db = getDatabase();
+    const memory = getMemoryById(id, source);
+    if (!memory)
+        return null;
+    // Calculate new salience with reinforcement
+    const newSalience = calculateReinforcementBoost(memory, config);
+    db.prepare(`
+    UPDATE memories
+    SET access_count = access_count + 1,
+        last_accessed = CURRENT_TIMESTAMP,
+        salience = ?
+    WHERE id = ?
+  `).run(newSalience, id);
+    const updatedMemory = getMemoryById(id);
+    // Emit event for real-time dashboard (in-process)
+    emitMemoryAccessed(updatedMemory, newSalience);
+    // Persist event for cross-process IPC (MCP → Dashboard)
+    persistEvent('memory_accessed', { memoryId: id, memory: updatedMemory, newSalience });
+    // ORGANIC FEATURE: Link strengthening on co-access
+    // If memory A and B are both accessed within 5 minutes, strengthen their link
+    // This mimics Hebbian learning: "neurons that fire together, wire together"
+    try {
+        const recentlyAccessed = db.prepare(`
+      SELECT id FROM memories
+      WHERE last_accessed > datetime('now', '-5 minutes')
+        AND id != ?
+      LIMIT 10
+    `).all(id);
+        for (const recent of recentlyAccessed) {
+            // Check if link exists in either direction
+            const existingLink = db.prepare(`
+        SELECT id, strength FROM memory_links
+        WHERE (source_id = ? AND target_id = ?) OR (source_id = ? AND target_id = ?)
+      `).get(id, recent.id, recent.id, id);
+            if (existingLink) {
+                // Strengthen existing link (cap at 1.0)
+                const newStrength = Math.min(1.0, existingLink.strength + 0.05);
+                db.prepare('UPDATE memory_links SET strength = ? WHERE id = ?')
+                    .run(newStrength, existingLink.id);
+            }
+            else {
+                // Create new weak link for co-accessed memories
+                createMemoryLink(id, recent.id, 'related', 0.2);
+            }
+        }
+    }
+    catch (e) {
+        // Don't fail memory access if link strengthening fails
+        console.error('[shieldcortex] Link strengthening failed:', e);
+    }
+    // ORGANIC FEATURE: Spreading Activation (Phase 2)
+    // Activate this memory and spread activation to linked memories
+    // This makes related memories easier to recall in subsequent searches
+    spreadActivation(id);
+    return updatedMemory;
+}
+/**
+ * Reinforce a memory that appeared in search results
+ * Gives a small salience boost with diminishing returns based on access count.
+ * ORGANIC FEATURE: Searched memories get reinforced, closing the feedback loop
+ * so frequently-found memories grow stronger over time.
+ */
+export function reinforceFromSearch(memoryId) {
+    const db = getDatabase();
+    const memory = db.prepare('SELECT salience, access_count FROM memories WHERE id = ?').get(memoryId);
+    if (!memory)
+        return;
+    // Small salience boost per search appearance (diminishing returns)
+    const boost = Math.max(0.005, 0.02 / (1 + memory.access_count * 0.1));
+    const newSalience = Math.min(1.0, memory.salience + boost);
+    db.prepare(`
+    UPDATE memories
+    SET last_accessed = CURRENT_TIMESTAMP,
+        access_count = access_count + 1,
+        salience = ?
+    WHERE id = ?
+  `).run(newSalience, memoryId);
+}
+// ============================================
+// ORGANIC FEATURE: Memory Enrichment (Phase 3)
+// ============================================
+// Enrichment configuration
+const ENRICHMENT_SIMILARITY_THRESHOLD = 0.3; // Min similarity to trigger enrichment
+const ENRICHMENT_COOLDOWN_HOURS = 1; // Don't enrich same memory within 1 hour
+const MAX_ENRICHMENT_SIZE = 2000; // Max chars to add per enrichment
+// Track last enrichment times (in-memory, ephemeral like activation cache)
+const enrichmentTimestamps = new Map();
+let enrichmentCallCount = 0;
+function pruneEnrichmentTimestamps() {
+    const now = Date.now();
+    const cooldownMs = ENRICHMENT_COOLDOWN_HOURS * 60 * 60 * 1000;
+    for (const [memoryId, timestamp] of enrichmentTimestamps) {
+        if (now - timestamp > cooldownMs) {
+            enrichmentTimestamps.delete(memoryId);
+        }
+    }
+}
+/**
+ * Enrich a memory with additional context
+ *
+ * This adds timestamped context to a memory when:
+ * 1. The new context is sufficiently related but different (new information)
+ * 2. The memory hasn't been enriched recently (cooldown)
+ * 3. The content won't exceed the size limit
+ *
+ * ORGANIC FEATURE: Memories grow with new context over time,
+ * mimicking how human memories are reconsolidated with new information
+ *
+ * @param memoryId - ID of the memory to enrich
+ * @param newContext - New context to add
+ * @param contextType - Type of context ('search' | 'access' | 'related')
+ * @returns EnrichmentResult indicating success or failure with reason
+ */
+export function enrichMemory(memoryId, newContext, contextType = 'access') {
+    // Prune stale cooldown entries every 100 calls
+    if (++enrichmentCallCount % 100 === 0) {
+        pruneEnrichmentTimestamps();
+    }
+    const db = getDatabase();
+    const memory = getMemoryById(memoryId);
+    if (!memory) {
+        return { enriched: false, reason: 'Memory not found' };
+    }
+    // Check cooldown
+    const lastEnrichment = enrichmentTimestamps.get(memoryId);
+    const now = Date.now();
+    if (lastEnrichment && (now - lastEnrichment) < ENRICHMENT_COOLDOWN_HOURS * 60 * 60 * 1000) {
+        return { enriched: false, reason: 'Enrichment cooldown active' };
+    }
+    // Check similarity - should be related but not too similar (new info)
+    const similarity = jaccardSimilarity(memory.content, newContext);
+    if (similarity > 0.8) {
+        return { enriched: false, reason: 'Context too similar (no new information)' };
+    }
+    if (similarity < ENRICHMENT_SIMILARITY_THRESHOLD) {
+        return { enriched: false, reason: 'Context not sufficiently related' };
+    }
+    // Truncate context if needed
+    const truncatedContext = newContext.slice(0, MAX_ENRICHMENT_SIZE);
+    // Build enrichment block with timestamp
+    const timestamp = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
+    const enrichmentBlock = `\n\n---\n[${timestamp}] ${contextType}: ${truncatedContext}`;
+    // Check size limit (leave 500 char buffer for future enrichments)
+    const newContent = memory.content + enrichmentBlock;
+    if (newContent.length > MAX_CONTENT_SIZE - 500) {
+        return { enriched: false, reason: 'Content size limit reached' };
+    }
+    // Update memory
+    db.prepare(`
+    UPDATE memories
+    SET content = ?,
+        last_accessed = CURRENT_TIMESTAMP
+    WHERE id = ?
+  `).run(newContent, memoryId);
+    // Update cooldown timestamp
+    enrichmentTimestamps.set(memoryId, now);
+    // Emit update event for dashboard
+    const updatedMemory = getMemoryById(memoryId);
+    emitMemoryUpdated(updatedMemory);
+    return { enriched: true, reason: `Added ${contextType} context (${truncatedContext.length} chars)` };
+}
+/**
+ * Clear enrichment cooldown for a memory (for testing)
+ */
+export function clearEnrichmentCooldown(memoryId) {
+    enrichmentTimestamps.delete(memoryId);
+}
+/**
+ * Get enrichment cooldown status for a memory
+ */
+export function getEnrichmentCooldownStatus(memoryId) {
+    const lastEnrichment = enrichmentTimestamps.get(memoryId);
+    if (!lastEnrichment) {
+        return { onCooldown: false, remainingMs: 0 };
+    }
+    const cooldownMs = ENRICHMENT_COOLDOWN_HOURS * 60 * 60 * 1000;
+    const elapsed = Date.now() - lastEnrichment;
+    const remaining = Math.max(0, cooldownMs - elapsed);
+    return {
+        onCooldown: remaining > 0,
+        remainingMs: remaining,
+    };
+}
+/**
+ * Update persisted decay scores for all memories
+ * Called during consolidation and periodically by the API server
+ * Returns the number of memories updated
+ */
+export function updateDecayScores() {
+    const db = getDatabase();
+    // Get all memories
+    const memories = db.prepare('SELECT * FROM memories').all();
+    let updated = 0;
+    const updateStmt = db.prepare('UPDATE memories SET decayed_score = ? WHERE id = ?');
+    for (const row of memories) {
+        const memory = rowToMemory(row);
+        const decayedScore = calculateDecayedScore(memory);
+        // Only update if score has changed significantly (saves writes)
+        const currentScore = row.decayed_score;
+        if (currentScore === null || Math.abs(currentScore - decayedScore) > 0.01) {
+            updateStmt.run(decayedScore, memory.id);
+            updated++;
+        }
+    }
+    return updated;
+}
+/**
+ * Promote a memory from short-term to long-term
+ */
+export function promoteMemory(id) {
+    const db = getDatabase();
+    db.prepare(`
+    UPDATE memories
+    SET type = 'long_term'
+    WHERE id = ? AND type = 'short_term'
+  `).run(id);
+    return getMemoryById(id);
+}
+/**
+ * Bulk delete decayed memories
+ */
+export function cleanupDecayedMemories(config = DEFAULT_CONFIG) {
+    const db = getDatabase();
+    // Get all short-term memories and check decay
+    const shortTerm = getMemoriesByType('short_term', 1000);
+    const toDelete = [];
+    for (const memory of shortTerm) {
+        const decayedScore = calculateDecayedScore(memory, config);
+        if (decayedScore < config.salienceThreshold) {
+            toDelete.push(memory.id);
+        }
+    }
+    if (toDelete.length > 0) {
+        const placeholders = toDelete.map(() => '?').join(',');
+        db.prepare(`DELETE FROM memories WHERE id IN (${placeholders})`).run(...toDelete);
+    }
+    return toDelete.length;
+}

package/dist/memory/links.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Memory relationships (links).
+ *
+ * Lifted out of the 2,166-line store.ts so the linking surface can be
+ * read, tested, and modified without scrolling past every CRUD/search
+ * helper in the memory module. No behaviour change vs the original
+ * implementation in store.ts — exports re-emerge from store.ts via
+ * a barrel re-export so existing import paths keep working.
+ *
+ * Imports from store.ts (getMemoryById, rowToMemory) form a module
+ * cycle, but both are only invoked inside function bodies — ESM live
+ * bindings handle this correctly at runtime.
+ */
+import type { Memory } from './types.js';
+export type RelationshipType = 'references' | 'extends' | 'contradicts' | 'related';
+export interface MemoryLink {
+    id: number;
+    sourceId: number;
+    targetId: number;
+    relationship: RelationshipType;
+    strength: number;
+    createdAt: Date;
+}
+/**
+ * Create a link between two memories.
+ *
+ * Returns null if either memory id doesn't exist, the source equals
+ * the target, or the link already exists (UNIQUE constraint).
+ */
+export declare function createMemoryLink(sourceId: number, targetId: number, relationship: RelationshipType, strength?: number): MemoryLink | null;
+/**
+ * Get all memories related to a given memory (incoming + outgoing links).
+ */
+export declare function getRelatedMemories(memoryId: number): {
+    memory: Memory;
+    relationship: RelationshipType;
+    strength: number;
+    direction: 'outgoing' | 'incoming';
+}[];
+/**
+ * Delete a memory link by source/target id pair. Returns true if a row was removed.
+ */
+export declare function deleteMemoryLink(sourceId: number, targetId: number): boolean;
+/**
+ * Get every memory link in the database, newest first.
+ */
+export declare function getAllMemoryLinks(): MemoryLink[];
+/**
+ * Detect potential relationships for a new memory.
+ *
+ * Three strategies in priority order:
+ *   1. Tag-based linking (shared tags)
+ *   2. Embedding-based semantic linking (cosine similarity >= 0.6)
+ *   3. FTS content similarity fallback (Jaccard similarity >= 0.3)
+ *
+ * Returns deduped results sorted by strength descending, capped at
+ * maxResults.
+ */
+export declare function detectRelationships(memory: Memory, maxResults?: number): {
+    targetId: number;
+    relationship: RelationshipType;
+    strength: number;
+}[];

package/dist/memory/links.js

@@ -0,0 +1,232 @@
+/**
+ * Memory relationships (links).
+ *
+ * Lifted out of the 2,166-line store.ts so the linking surface can be
+ * read, tested, and modified without scrolling past every CRUD/search
+ * helper in the memory module. No behaviour change vs the original
+ * implementation in store.ts — exports re-emerge from store.ts via
+ * a barrel re-export so existing import paths keep working.
+ *
+ * Imports from store.ts (getMemoryById, rowToMemory) form a module
+ * cycle, but both are only invoked inside function bodies — ESM live
+ * bindings handle this correctly at runtime.
+ */
+import { getDatabase } from '../database/init.js';
+import { cosineSimilarity } from '../embeddings/index.js';
+import { jaccardSimilarity } from './similarity.js';
+import { escapeFts5Query } from './fts.js';
+import { getMemoryById, rowToMemory } from './store.js';
+/**
+ * Create a link between two memories.
+ *
+ * Returns null if either memory id doesn't exist, the source equals
+ * the target, or the link already exists (UNIQUE constraint).
+ */
+export function createMemoryLink(sourceId, targetId, relationship, strength = 0.5) {
+    const db = getDatabase();
+    const source = getMemoryById(sourceId);
+    const target = getMemoryById(targetId);
+    if (!source || !target)
+        return null;
+    if (sourceId === targetId)
+        return null;
+    try {
+        const result = db.prepare(`
+      INSERT INTO memory_links (source_id, target_id, relationship, strength)
+      VALUES (?, ?, ?, ?)
+    `).run(sourceId, targetId, relationship, strength);
+        return {
+            id: result.lastInsertRowid,
+            sourceId,
+            targetId,
+            relationship,
+            strength,
+            createdAt: new Date(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get all memories related to a given memory (incoming + outgoing links).
+ */
+export function getRelatedMemories(memoryId) {
+    const db = getDatabase();
+    const outgoing = db.prepare(`
+    SELECT m.*, ml.relationship, ml.strength
+    FROM memory_links ml
+    JOIN memories m ON m.id = ml.target_id
+    WHERE ml.source_id = ?
+  `).all(memoryId);
+    const incoming = db.prepare(`
+    SELECT m.*, ml.relationship, ml.strength
+    FROM memory_links ml
+    JOIN memories m ON m.id = ml.source_id
+    WHERE ml.target_id = ?
+  `).all(memoryId);
+    const results = [];
+    for (const row of outgoing) {
+        results.push({
+            memory: rowToMemory(row),
+            relationship: row.relationship,
+            strength: row.strength,
+            direction: 'outgoing',
+        });
+    }
+    for (const row of incoming) {
+        results.push({
+            memory: rowToMemory(row),
+            relationship: row.relationship,
+            strength: row.strength,
+            direction: 'incoming',
+        });
+    }
+    return results;
+}
+/**
+ * Delete a memory link by source/target id pair. Returns true if a row was removed.
+ */
+export function deleteMemoryLink(sourceId, targetId) {
+    const db = getDatabase();
+    const result = db.prepare(`
+    DELETE FROM memory_links WHERE source_id = ? AND target_id = ?
+  `).run(sourceId, targetId);
+    return result.changes > 0;
+}
+/**
+ * Get every memory link in the database, newest first.
+ */
+export function getAllMemoryLinks() {
+    const db = getDatabase();
+    const rows = db.prepare('SELECT * FROM memory_links ORDER BY created_at DESC').all();
+    return rows.map((row) => ({
+        id: row.id,
+        sourceId: row.source_id,
+        targetId: row.target_id,
+        relationship: row.relationship,
+        strength: row.strength,
+        createdAt: new Date(row.created_at),
+    }));
+}
+/**
+ * Detect tag-based links for a memory.
+ * Finds memories sharing tags and scores by overlap count.
+ */
+function detectTagLinks(db, memory, maxResults) {
+    const results = [];
+    if (memory.tags.length > 0) {
+        const tagPlaceholders = memory.tags.map(() => '?').join(',');
+        const tagMatches = db.prepare(`
+      SELECT DISTINCT m.id, m.tags
+      FROM memories m, json_each(m.tags)
+      WHERE json_each.value IN (${tagPlaceholders})
+        AND m.id != ?
+      LIMIT ?
+    `).all(...memory.tags, memory.id, maxResults);
+        for (const match of tagMatches) {
+            const matchTags = JSON.parse(match.tags);
+            const sharedCount = memory.tags.filter((t) => matchTags.includes(t)).length;
+            const strength = Math.min(0.9, 0.3 + (sharedCount * 0.2));
+            results.push({ targetId: match.id, relationship: 'related', strength });
+        }
+    }
+    return results;
+}
+/**
+ * Detect embedding-based semantic links for a memory.
+ * Computes cosine similarity against top memories that have embeddings.
+ */
+function detectEmbeddingLinks(db, memory, maxResults) {
+    if (!memory.embedding)
+        return [];
+    const candidates = db.prepare(`
+    SELECT id, embedding FROM memories
+    WHERE embedding IS NOT NULL AND id != ?
+    ORDER BY decayed_score DESC
+    LIMIT 100
+  `).all(memory.id);
+    const results = [];
+    const sourceEmbedding = new Float32Array(memory.embedding.buffer, memory.embedding.byteOffset, memory.embedding.byteLength / 4);
+    for (const candidate of candidates) {
+        const candidateEmbedding = new Float32Array(candidate.embedding.buffer, candidate.embedding.byteOffset, candidate.embedding.byteLength / 4);
+        const similarity = cosineSimilarity(sourceEmbedding, candidateEmbedding);
+        if (similarity >= 0.6) {
+            results.push({
+                targetId: candidate.id,
+                relationship: 'related',
+                strength: Math.min(0.9, similarity),
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Detect content-based links using FTS5 and Jaccard similarity.
+ * Fallback when embeddings are not available.
+ */
+function detectFtsLinks(db, memory, maxResults) {
+    const queryText = `${memory.title} ${memory.content.slice(0, 200)}`;
+    const escapedQuery = escapeFts5Query(queryText);
+    if (!escapedQuery.trim())
+        return [];
+    let ftsMatches;
+    try {
+        ftsMatches = db.prepare(`
+      SELECT m.id, m.title, m.content
+      FROM memories_fts fts
+      JOIN memories m ON m.id = fts.rowid
+      WHERE memories_fts MATCH ?
+        AND m.id != ?
+      LIMIT ?
+    `).all(escapedQuery, memory.id, maxResults * 2);
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const match of ftsMatches) {
+        const matchText = `${match.title} ${match.content.slice(0, 200)}`;
+        const sim = jaccardSimilarity(queryText, matchText);
+        if (sim >= 0.3) {
+            results.push({
+                targetId: match.id,
+                relationship: 'related',
+                strength: Math.min(0.7, sim + 0.2),
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Detect potential relationships for a new memory.
+ *
+ * Three strategies in priority order:
+ *   1. Tag-based linking (shared tags)
+ *   2. Embedding-based semantic linking (cosine similarity >= 0.6)
+ *   3. FTS content similarity fallback (Jaccard similarity >= 0.3)
+ *
+ * Returns deduped results sorted by strength descending, capped at
+ * maxResults.
+ */
+export function detectRelationships(memory, maxResults = 5) {
+    const db = getDatabase();
+    const seen = new Set();
+    const results = [];
+    function addResults(links) {
+        for (const link of links) {
+            if (!seen.has(link.targetId)) {
+                seen.add(link.targetId);
+                results.push(link);
+            }
+        }
+    }
+    addResults(detectTagLinks(db, memory, maxResults));
+    addResults(detectEmbeddingLinks(db, memory, maxResults));
+    if (!memory.embedding) {
+        addResults(detectFtsLinks(db, memory, maxResults));
+    }
+    return results
+        .sort((a, b) => b.strength - a.strength)
+        .slice(0, maxResults);
+}

package/dist/memory/prune.d.ts

@@ -0,0 +1,34 @@
+export interface PruneOptions {
+    /** Salience ceiling (inclusive). Memories with salience <= this are candidates. 0..1, default 0.2. */
+    salienceLte?: number;
+    /** Minimum age in days. Memories older than this are candidates. 1..365, default 30. */
+    ageDaysGte?: number;
+    /** Optional project scope. Omit for all projects. */
+    project?: string;
+    /** When true (default) pinned memories are never pruned. */
+    excludePinned?: boolean;
+    /** When true (default) only count + sample, no deletes. */
+    dryRun?: boolean;
+}
+export interface PruneSampleEntry {
+    id: number;
+    title: string;
+    project: string | null;
+    salience: number;
+    ageDays: number;
+}
+export interface PruneResult {
+    options: Required<Omit<PruneOptions, 'project'>> & {
+        project: string | null;
+    };
+    matched: number;
+    sample: PruneSampleEntry[];
+    deleted?: number;
+    backupPath?: string;
+}
+/**
+ * Find + optionally delete memories below a salience threshold older than N
+ * days. Always backs up the live DB before any delete; the backup path is
+ * returned in the result so the caller can surface it to the user.
+ */
+export declare function pruneMemories(rawOptions?: PruneOptions): Promise<PruneResult>;