shieldcortex 4.12.14 → 4.13.1

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>;

package/dist/memory/prune.js

@@ -0,0 +1,76 @@
+import { getDatabase } from '../database/init.js';
+import { deleteMemory } from './store.js';
+import { backupMemoriesDb } from './backup.js';
+const DEFAULTS = {
+    salienceLte: 0.2,
+    ageDaysGte: 30,
+    excludePinned: true,
+    dryRun: true,
+};
+const SAMPLE_LIMIT = 10;
+function buildWhereClause(options) {
+    const where = [
+        'salience <= ?',
+        "(julianday('now') - julianday(created_at)) >= ?",
+        "COALESCE(status, 'active') NOT IN ('archived', 'suppressed')",
+    ];
+    const params = [options.salienceLte, options.ageDaysGte];
+    if (options.project !== null) {
+        where.push('project = ?');
+        params.push(options.project);
+    }
+    if (options.excludePinned) {
+        where.push('COALESCE(pinned, 0) = 0');
+    }
+    return { where: where.join(' AND '), params };
+}
+/**
+ * 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 async function pruneMemories(rawOptions = {}) {
+    const options = {
+        salienceLte: rawOptions.salienceLte ?? DEFAULTS.salienceLte,
+        ageDaysGte: rawOptions.ageDaysGte ?? DEFAULTS.ageDaysGte,
+        project: rawOptions.project ?? null,
+        excludePinned: rawOptions.excludePinned ?? DEFAULTS.excludePinned,
+        dryRun: rawOptions.dryRun ?? DEFAULTS.dryRun,
+    };
+    if (options.salienceLte < 0 || options.salienceLte > 1) {
+        throw new Error('salienceLte must be between 0 and 1');
+    }
+    if (options.ageDaysGte < 0) {
+        throw new Error('ageDaysGte must be >= 0');
+    }
+    const { where, params } = buildWhereClause(options);
+    const db = getDatabase();
+    const countRow = db.prepare(`SELECT COUNT(*) AS n FROM memories WHERE ${where}`).get(...params);
+    const matched = countRow.n;
+    const sampleRows = db
+        .prepare(`SELECT id, title, project, salience,
+              CAST(julianday('now') - julianday(created_at) AS INTEGER) AS age_days
+       FROM memories WHERE ${where}
+       ORDER BY salience ASC, created_at ASC
+       LIMIT ?`)
+        .all(...params, SAMPLE_LIMIT);
+    const sample = sampleRows.map((r) => ({
+        id: r.id,
+        title: r.title,
+        project: r.project,
+        salience: r.salience,
+        ageDays: r.age_days,
+    }));
+    const result = { options, matched, sample };
+    if (options.dryRun || matched === 0)
+        return result;
+    result.backupPath = await backupMemoriesDb('pre-prune');
+    const idRows = db.prepare(`SELECT id FROM memories WHERE ${where}`).all(...params);
+    let deleted = 0;
+    for (const row of idRows) {
+        if (deleteMemory(row.id, { type: 'cli', identifier: 'maintenance:prune' }))
+            deleted++;
+    }
+    result.deleted = deleted;
+    return result;
+}

package/dist/memory/search-recall.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Memory search and recall.
+ *
+ * Phase 3 of the audit-recommended store.ts split. The "search/recall"
+ * group is the hybrid FTS5 + vector pipeline (`searchMemoriesInternal`)
+ * and its three public entry points (`searchMemories`,
+ * `searchMemoriesExplained`, `recallWithEmbeddings`). Lifted out of
+ * store.ts (1,564 lines after phase 2) so the search pipeline can be
+ * read on its own without scrolling past every CRUD helper. 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 (`rowToMemory`, `logAccessDenial`) form a
+ * module cycle, but both are only invoked inside function bodies —
+ * never at module load. ESM live bindings handle this correctly at
+ * runtime. `logAccessDenial` is exported from store.ts purely as a
+ * cycle artifact; it is not intended as public API (same precedent
+ * as `MAX_CONTENT_SIZE` in phase 2).
+ *
+ * Imports from lifecycle.ts (`reinforceFromSearch`, `enrichMemory`)
+ * are not cyclic — phase 2 added them to store.ts specifically for
+ * the search pipeline; in phase 3 they move with the consumer.
+ */
+import { Memory, MemoryConfig, SearchOptions, SearchResult } from './types.js';
+import type { DefenceSource } from '../defence/types.js';
+/**
+ * Search memories using full-text search, vector similarity, and filters
+ * Now uses hybrid search combining FTS5 keywords with semantic vector matching
+ */
+export declare function searchMemories(options: SearchOptions, config?: MemoryConfig, source?: DefenceSource): Promise<SearchResult[]>;
+export declare function searchMemoriesExplained(options: SearchOptions, config?: MemoryConfig, source?: DefenceSource): Promise<SearchResult[]>;
+/**
+ * Recall with embedding-based vector similarity fallback.
+ *
+ * 1. First tries FTS5 search (existing searchMemories)
+ * 2. If FTS5 returns < 3 results, also runs embedding similarity search
+ * 3. Merges results (FTS5 first, then embedding results not already in FTS5 set)
+ * 4. Caps at `limit` (default 15)
+ * 5. The `threshold` (default 0.3) filters out low-similarity embedding results
+ */
+export declare function recallWithEmbeddings(query: string, options?: {
+    limit?: number;
+    project?: string;
+    threshold?: number;
+    existingResults?: SearchResult[];
+    queryEmbedding?: Float32Array | null;
+}): Promise<Memory[]>;