squish-memory 1.0.2 → 1.2.0

package/dist/core/memory/importance.d.ts

@@ -1,17 +1,8 @@
 /**
  * Importance Scoring System
- *
- * Calculates and manages memory importance scores (0-100) with temporal decay.
- * Based on research from Mnemosyne architecture and ReMe (Memory Replay).
- *
- * Scoring factors:
- * - Base score: 50 (neutral)
- * - Recency boost: decays over time (exponential decay)
- * - Access frequency: more frequently accessed = higher importance
- * - Type weighting: decisions > facts > preferences > context > observations
- * - User flags: pinned/protected memories get maximum importance
+ * Calculates and manages memory importance scores (0-100) with temporal decay
  */
-import type { Memory } from '../../drizzle/schema.js';
+import type { Memory } from '../../db/drizzle/schema.js';
 export interface ImportanceScore {
     score: number;
     components: {
@@ -35,14 +26,6 @@ export declare function calculateImportance(memory: Partial<Memory>): Importance
  * Used when memory is accessed or modified
  */
 export declare function updateImportanceScore(memoryId: string, incrementAccess?: boolean): Promise<number>;
-/**
- * Decay importance scores for old memories
- * Should be run periodically (e.g., daily) to reduce scores of stale memories
- *
- * This function applies exponential decay to all memories that haven't been
- * recalculated recently, keeping the system's importance scores current.
- */
-export declare function decayImportanceScores(projectId?: string): Promise<number>;
 /**
  * Get low-importance memories that are candidates for consolidation
  * These are old, rarely accessed memories with low importance scores
@@ -60,9 +43,4 @@ export declare function setImportanceScore(memoryId: string, score: number): Pro
  * Pin a memory to prevent decay and consolidation
  */
 export declare function pinMemory(memoryId: string, pinned?: boolean): Promise<void>;
-/**
- * Calculate cosine similarity between two vectors
- * Re-exported for use in consolidation
- */
-export declare function cosineSimilarity(vecA: number[], vecB: number[]): number;
 //# sourceMappingURL=importance.d.ts.map

package/dist/core/memory/importance.js

@@ -1,20 +1,9 @@
 /**
  * Importance Scoring System
- *
- * Calculates and manages memory importance scores (0-100) with temporal decay.
- * Based on research from Mnemosyne architecture and ReMe (Memory Replay).
- *
- * Scoring factors:
- * - Base score: 50 (neutral)
- * - Recency boost: decays over time (exponential decay)
- * - Access frequency: more frequently accessed = higher importance
- * - Type weighting: decisions > facts > preferences > context > observations
- * - User flags: pinned/protected memories get maximum importance
+ * Calculates and manages memory importance scores (0-100) with temporal decay
  */
-import { createDatabaseClient } from '../database.js';
-import { getDb } from '../../db/index.js';
-import { getSchema } from '../../db/schema.js';
 import { eq } from 'drizzle-orm';
+import { getDbClient } from '../lib/db-client.js';
 /**
  * Type weights for importance scoring
  * Higher values = more important memory types
@@ -151,8 +140,7 @@ function generateImportanceExplanation(components, memory) {
  * Used when memory is accessed or modified
  */
 export async function updateImportanceScore(memoryId, incrementAccess = false) {
-    const db = createDatabaseClient(await getDb());
-    const schema = await getSchema();
+    const { db, schema } = await getDbClient();
     // Get current memory
     const memories = await db
         .select()
@@ -181,60 +169,12 @@ export async function updateImportanceScore(memoryId, incrementAccess = false) {
         .where(eq(schema.memories.id, memoryId));
     return importance.score;
 }
-/**
- * Decay importance scores for old memories
- * Should be run periodically (e.g., daily) to reduce scores of stale memories
- *
- * This function applies exponential decay to all memories that haven't been
- * recalculated recently, keeping the system's importance scores current.
- */
-export async function decayImportanceScores(projectId) {
-    const db = createDatabaseClient(await getDb());
-    const schema = await getSchema();
-    // Get memories that need recalculation
-    // (those not recalculated in the last 24 hours)
-    const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);
-    let memories;
-    if (projectId) {
-        memories = await db
-            .select()
-            .from(schema.memories)
-            .where(eq(schema.memories.projectId, projectId))
-            .all();
-    }
-    else {
-        memories = await db.select().from(schema.memories).all();
-    }
-    let updatedCount = 0;
-    for (const memory of memories) {
-        // Skip pinned/protected memories (they don't decay)
-        if (memory.isPinned || memory.isProtected) {
-            continue;
-        }
-        // Skip consolidated memories
-        if (memory.isConsolidated) {
-            continue;
-        }
-        // Recalculate importance (which includes recency decay)
-        const importance = calculateImportance(memory);
-        await db
-            .update(schema.memories)
-            .set({
-            importanceScore: importance.score,
-            lastImportanceRecalc: new Date(),
-        })
-            .where(eq(schema.memories.id, memory.id));
-        updatedCount++;
-    }
-    return updatedCount;
-}
 /**
  * Get low-importance memories that are candidates for consolidation
  * These are old, rarely accessed memories with low importance scores
  */
 export async function getLowImportanceMemories(projectId, options = {}) {
-    const db = createDatabaseClient(await getDb());
-    const schema = await getSchema();
+    const { db, schema } = await getDbClient();
     const { minAge = 90, // 90 days old by default
     maxImportance = 30, // importance score below 30
     limit = 100, } = options;
@@ -273,8 +213,7 @@ export async function setImportanceScore(memoryId, score) {
     if (score < 0 || score > 100) {
         throw new Error('Importance score must be between 0 and 100');
     }
-    const db = createDatabaseClient(await getDb());
-    const schema = await getSchema();
+    const { db, schema } = await getDbClient();
     await db
         .update(schema.memories)
         .set({
@@ -287,8 +226,7 @@ export async function setImportanceScore(memoryId, score) {
  * Pin a memory to prevent decay and consolidation
  */
 export async function pinMemory(memoryId, pinned = true) {
-    const db = createDatabaseClient(await getDb());
-    const schema = await getSchema();
+    const { db, schema } = await getDbClient();
     await db
         .update(schema.memories)
         .set({
@@ -299,27 +237,5 @@ export async function pinMemory(memoryId, pinned = true) {
     })
         .where(eq(schema.memories.id, memoryId));
 }
-/**
- * Calculate cosine similarity between two vectors
- * Re-exported for use in consolidation
- */
-export function cosineSimilarity(vecA, vecB) {
-    if (vecA.length !== vecB.length) {
-        return 0;
-    }
-    let dotProduct = 0;
-    let magnitudeA = 0;
-    let magnitudeB = 0;
-    for (let i = 0; i < vecA.length; i++) {
-        dotProduct += vecA[i] * vecB[i];
-        magnitudeA += vecA[i] * vecA[i];
-        magnitudeB += vecB[i] * vecB[i];
-    }
-    magnitudeA = Math.sqrt(magnitudeA);
-    magnitudeB = Math.sqrt(magnitudeB);
-    if (magnitudeA === 0 || magnitudeB === 0) {
-        return 0;
-    }
-    return dotProduct / (magnitudeA * magnitudeB);
-}
+// cosineSimilarity has been removed - import from core/utils/vector-operations.ts directly
 //# sourceMappingURL=importance.js.map

package/dist/core/memory/index.d.ts

@@ -1,3 +1,4 @@
+export * from './normalization.js';
 export * from './memories.js';
 export * from './memory-manager.js';
 export * from './serialization.js';

package/dist/core/memory/index.js

@@ -1,4 +1,5 @@
 // Memory feature - Store and manage memories
+export * from './normalization.js';
 export * from './memories.js';
 export * from './memory-manager.js';
 export * from './serialization.js';

package/dist/core/memory/loader.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Memory Loading Abstraction
+ * Unified utilities for loading memories by ID with configurable options
+ */
+import { type MemoryRecord } from './normalization.js';
+export interface LoadMemoryOptions {
+    incrementAccess?: boolean;
+    decrypt?: boolean;
+    normalize?: boolean;
+    includeSensitive?: boolean;
+}
+/**
+ * Load a single memory by ID with configurable options
+ */
+export declare function loadMemory(id: string, options?: LoadMemoryOptions): Promise<MemoryRecord | any | null>;
+/**
+ * Load multiple memories by IDs efficiently
+ * Returns a Map keyed by memory ID
+ */
+export declare function loadMemories(ids: string[], options?: LoadMemoryOptions): Promise<Map<string, any>>;
+/**
+ * Load a memory by ID with raw database access, no processing.
+ *
+ * This is for special cases that need the raw database row without
+ * normalization, decryption, or access count updates.
+ *
+ * @param id - Memory UUID
+ * @returns Raw database row or null if not found
+ */
+export declare function loadMemoryRaw(id: string): Promise<any | null>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/core/memory/loader.js

@@ -0,0 +1,141 @@
+/**
+ * Memory Loading Abstraction
+ * Unified utilities for loading memories by ID with configurable options
+ */
+import { eq, inArray } from 'drizzle-orm';
+import { getDbClient } from '../lib/db-client.js';
+import { decrypt } from '../security/encrypt.js';
+import { normalizeMemory } from './normalization.js';
+import { requireUuid } from '../lib/validation.js';
+/**
+ * Load a single memory by ID with configurable options
+ */
+export async function loadMemory(id, options = {}) {
+    const { incrementAccess = true, decrypt: shouldDecrypt = true, normalize = true, includeSensitive = false } = options;
+    // Validate UUID
+    requireUuid(id);
+    const { db, schema } = await getDbClient();
+    // Query the memory
+    const rows = await db.select().from(schema.memories).where(eq(schema.memories.id, id)).limit(1);
+    const row = rows[0];
+    if (!row)
+        return null;
+    // Increment access count if needed
+    if (incrementAccess) {
+        await db.update(schema.memories)
+            .set({
+            accessCount: (row.accessCount ?? 0) + 1,
+            lastAccessedAt: new Date(),
+        })
+            .where(eq(schema.memories.id, id));
+    }
+    // Determine content: decrypt if needed
+    let content = row.content;
+    let encryptedContent = row.encrypted_content;
+    let encryptionNonce = row.encryption_nonce;
+    if (shouldDecrypt && row.is_encrypted) {
+        try {
+            content = decrypt(encryptedContent, encryptionNonce);
+        }
+        catch (e) {
+            console.warn('Failed to decrypt memory', e);
+            content = row.content; // fallback to stored content (encrypted)
+        }
+    }
+    // Build result object
+    let result = { ...row, content };
+    // If not decrypting and includeSensitive, keep encrypted fields
+    if (!shouldDecrypt && includeSensitive) {
+        result.encrypted_content = encryptedContent;
+        result.encryption_nonce = encryptionNonce;
+    }
+    // If normalize, convert to MemoryRecord shape
+    if (normalize) {
+        return normalizeMemory(result);
+    }
+    // Otherwise return raw-ish row (with content possibly decrypted)
+    return result;
+}
+/**
+ * Load multiple memories by IDs efficiently
+ * Returns a Map keyed by memory ID
+ */
+export async function loadMemories(ids, options = {}) {
+    const { incrementAccess = true, decrypt: shouldDecrypt = true, normalize = true, includeSensitive = false } = options;
+    if (ids.length === 0) {
+        return new Map();
+    }
+    // Validate all UUIDs
+    for (const id of ids) {
+        requireUuid(id);
+    }
+    const { db, schema } = await getDbClient();
+    // Batch query using IN operator
+    const rows = await db
+        .select()
+        .from(schema.memories)
+        .where(inArray(schema.memories.id, ids));
+    // Create a map from id to row
+    const rowMap = new Map();
+    for (const row of rows) {
+        rowMap.set(row.id, row);
+    }
+    // Increment access counts if needed
+    if (incrementAccess) {
+        const now = new Date();
+        for (const row of rows) {
+            await db.update(schema.memories)
+                .set({
+                accessCount: (row.accessCount ?? 0) + 1,
+                lastAccessedAt: now,
+            })
+                .where(eq(schema.memories.id, row.id));
+        }
+    }
+    // Process each row according to options
+    const resultMap = new Map();
+    for (const row of rows) {
+        let content = row.content;
+        let encryptedContent = row.encrypted_content;
+        let encryptionNonce = row.encryption_nonce;
+        if (shouldDecrypt && row.is_encrypted) {
+            try {
+                content = decrypt(encryptedContent, encryptionNonce);
+            }
+            catch (e) {
+                console.warn('Failed to decrypt memory', e);
+                content = row.content;
+            }
+        }
+        let result = { ...row, content };
+        if (!shouldDecrypt && includeSensitive) {
+            result.encrypted_content = encryptedContent;
+            result.encryption_nonce = encryptionNonce;
+        }
+        if (normalize) {
+            resultMap.set(row.id, normalizeMemory(result));
+        }
+        else {
+            resultMap.set(row.id, result);
+        }
+    }
+    return resultMap;
+}
+/**
+ * Load a memory by ID with raw database access, no processing.
+ *
+ * This is for special cases that need the raw database row without
+ * normalization, decryption, or access count updates.
+ *
+ * @param id - Memory UUID
+ * @returns Raw database row or null if not found
+ */
+export async function loadMemoryRaw(id) {
+    // Validate UUID
+    requireUuid(id);
+    const { db, schema } = await getDbClient();
+    // Direct query without any processing
+    const rows = await db.select().from(schema.memories).where(eq(schema.memories.id, id)).limit(1);
+    return rows[0] || null;
+}
+//# sourceMappingURL=loader.js.map

package/dist/core/memory/markdown/markdown-storage.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Memory Markdown Storage
+ *
+ * Stores memories as markdown files in .squish/memory/
+ * Following Karpathy LLM Memory pattern:
+ * - raw/ : Append-only memory files (never edit)
+ * - processed/ : LLM-generated articles (future)
+ * - outputs/ : Query responses (future)
+ *
+ * Each memory = one .md file with YAML frontmatter
+ */
+import type { MemoryType } from '../memories.js';
+export interface MarkdownMemoryInput {
+    content: string;
+    type?: MemoryType;
+    tags?: string[];
+    reasoning?: string;
+    memoryContext?: string;
+    examples?: string;
+    exceptions?: string;
+    source?: string;
+    project?: string;
+}
+export interface MarkdownMemoryFile {
+    id: string;
+    type: MemoryType;
+    content: string;
+    tags: string[];
+    createdAt: string;
+    source?: string;
+    project?: string;
+    reasoning?: string;
+    memoryContext?: string;
+    examples?: string;
+    exceptions?: string;
+}
+/**
+ * Save a memory to memory raw folder
+ */
+export declare function saveToMarkdown(input: MarkdownMemoryInput): Promise<MarkdownMemoryFile>;
+/**
+ * Get all memories from memory raw folder
+ */
+export declare function getMarkdownMemories(options?: {
+    since?: Date;
+    until?: Date;
+    tags?: string[];
+    type?: MemoryType;
+    project?: string;
+}): Promise<MarkdownMemoryFile[]>;
+/**
+ * Get a specific memory by ID
+ */
+export declare function getMarkdownMemory(id: string): Promise<MarkdownMemoryFile | null>;
+/**
+ * Delete a memory from memory
+ */
+export declare function deleteMarkdownMemory(id: string): Promise<boolean>;
+/**
+ * Get memory storage stats
+ */
+export declare function getMemoryStats(): Promise<{
+    totalMemories: number;
+    byType: Record<string, number>;
+    byTag: Record<string, number>;
+    storageSizeBytes: number;
+}>;
+/**
+ * Check if memory storage is available
+ */
+export declare function isMemoryStorageAvailable(): boolean;
+//# sourceMappingURL=markdown-storage.d.ts.map

package/dist/core/memory/markdown/markdown-storage.js

@@ -0,0 +1,243 @@
+/**
+ * Memory Markdown Storage
+ *
+ * Stores memories as markdown files in .squish/memory/
+ * Following Karpathy LLM Memory pattern:
+ * - raw/ : Append-only memory files (never edit)
+ * - processed/ : LLM-generated articles (future)
+ * - outputs/ : Query responses (future)
+ *
+ * Each memory = one .md file with YAML frontmatter
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+import { logger } from '../../logger.js';
+import { getDataDir } from '../../../config.js';
+/**
+ * Get the memory base path (.squish/memory/)
+ */
+function getMemoryPath() {
+    return join(getDataDir(), 'memory');
+}
+/**
+ * Get the raw memories path (.squish/memory/raw/)
+ */
+function getRawPath() {
+    return join(getMemoryPath(), 'raw');
+}
+/**
+ * Ensure memory directory structure exists
+ */
+function ensureMemoryStructure() {
+    const dirs = [getMemoryPath(), getRawPath()];
+    for (const dir of dirs) {
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+            logger.info(`[MemoryStorage] Created directory: ${dir}`);
+        }
+    }
+}
+/**
+ * Format memory as markdown with YAML frontmatter
+ */
+function formatMemoryAsMarkdown(memory) {
+    const lines = [];
+    // YAML frontmatter
+    lines.push('---');
+    lines.push(`id: ${memory.id}`);
+    lines.push(`type: ${memory.type}`);
+    lines.push(`created: ${memory.createdAt}`);
+    if (memory.tags && memory.tags.length > 0) {
+        lines.push(`tags: [${memory.tags.join(', ')}]`);
+    }
+    if (memory.source) {
+        lines.push(`source: ${memory.source}`);
+    }
+    if (memory.project) {
+        lines.push(`project: ${memory.project}`);
+    }
+    if (memory.reasoning) {
+        lines.push(`reasoning: |`);
+        lines.push(memory.reasoning.split('\n').map(l => `  ${l}`).join('\n'));
+    }
+    if (memory.memoryContext) {
+        lines.push(`context: |`);
+        lines.push(memory.memoryContext.split('\n').map(l => `  ${l}`).join('\n'));
+    }
+    if (memory.examples) {
+        lines.push(`examples: |`);
+        lines.push(memory.examples.split('\n').map(l => `  ${l}`).join('\n'));
+    }
+    if (memory.exceptions) {
+        lines.push(`exceptions: |`);
+        lines.push(memory.exceptions.split('\n').map(l => `  ${l}`).join('\n'));
+    }
+    lines.push('---');
+    lines.push('');
+    lines.push(memory.content);
+    return lines.join('\n');
+}
+/**
+ * Parse markdown file to MarkdownMemoryFile
+ */
+function parseMarkdownFile(filePath) {
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        const match = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!match)
+            return null;
+        const frontmatter = match[1];
+        const body = content.slice(match[0].length).trim();
+        const memory = { content: body };
+        // Parse frontmatter lines
+        const lines = frontmatter.split('\n');
+        for (const line of lines) {
+            const colonIdx = line.indexOf(':');
+            if (colonIdx === -1)
+                continue;
+            const key = line.slice(0, colonIdx).trim();
+            let value = line.slice(colonIdx + 1).trim();
+            // Handle array values like tags: [tag1, tag2]
+            if (value.startsWith('[') && value.endsWith(']')) {
+                value = value.slice(1, -1);
+                memory[key] = value.split(',').map((t) => t.trim());
+            }
+            else if (value === 'true' || value === 'false') {
+                memory[key] = value === 'true';
+            }
+            else {
+                memory[key] = value;
+            }
+        }
+        return memory;
+    }
+    catch (error) {
+        logger.warn(`[MemoryStorage] Failed to parse ${filePath}: ${error}`);
+        return null;
+    }
+}
+/**
+ * Save a memory to memory raw folder
+ */
+export async function saveToMarkdown(input) {
+    ensureMemoryStructure();
+    const id = randomUUID();
+    const createdAt = new Date().toISOString();
+    const memory = {
+        id,
+        type: input.type || 'observation',
+        content: input.content,
+        tags: input.tags || [],
+        createdAt,
+        source: input.source,
+        project: input.project,
+        reasoning: input.reasoning,
+        memoryContext: input.memoryContext,
+        examples: input.examples,
+        exceptions: input.exceptions,
+    };
+    const filePath = join(getRawPath(), `${id}.md`);
+    writeFileSync(filePath, formatMemoryAsMarkdown(memory), 'utf-8');
+    logger.info(`[MemoryStorage] Saved memory to ${filePath}`);
+    return memory;
+}
+/**
+ * Get all memories from memory raw folder
+ */
+export async function getMarkdownMemories(options) {
+    ensureMemoryStructure();
+    const files = readdirSync(getRawPath()).filter(f => f.endsWith('.md'));
+    const memories = [];
+    for (const file of files) {
+        const filePath = join(getRawPath(), file);
+        const memory = parseMarkdownFile(filePath);
+        if (!memory)
+            continue;
+        const createdAt = new Date(memory.createdAt);
+        // Filter by date range
+        if (options?.since && createdAt < options.since)
+            continue;
+        if (options?.until && createdAt > options.until)
+            continue;
+        // Filter by tags
+        if (options?.tags && options.tags.length > 0) {
+            const hasTag = options.tags.some(t => memory.tags.includes(t));
+            if (!hasTag)
+                continue;
+        }
+        // Filter by type
+        if (options?.type && memory.type !== options.type)
+            continue;
+        // Filter by project
+        if (options?.project && memory.project !== options.project)
+            continue;
+        memories.push(memory);
+    }
+    // Sort by createdAt descending
+    memories.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+    return memories;
+}
+/**
+ * Get a specific memory by ID
+ */
+export async function getMarkdownMemory(id) {
+    const filePath = join(getRawPath(), `${id}.md`);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    return parseMarkdownFile(filePath);
+}
+/**
+ * Delete a memory from memory
+ */
+export async function deleteMarkdownMemory(id) {
+    const filePath = join(getRawPath(), `${id}.md`);
+    if (!existsSync(filePath)) {
+        return false;
+    }
+    unlinkSync(filePath);
+    logger.info(`[MemoryStorage] Deleted memory ${id}`);
+    return true;
+}
+/**
+ * Get memory storage stats
+ */
+export async function getMemoryStats() {
+    ensureMemoryStructure();
+    const files = readdirSync(getRawPath()).filter(f => f.endsWith('.md'));
+    const byType = {};
+    const byTag = {};
+    let storageSizeBytes = 0;
+    for (const file of files) {
+        const filePath = join(getRawPath(), file);
+        const stats = await import('fs').then(fs => fs.statSync(filePath));
+        storageSizeBytes += stats.size;
+        const memory = parseMarkdownFile(filePath);
+        if (!memory)
+            continue;
+        byType[memory.type] = (byType[memory.type] || 0) + 1;
+        for (const tag of memory.tags) {
+            byTag[tag] = (byTag[tag] || 0) + 1;
+        }
+    }
+    return {
+        totalMemories: files.length,
+        byType,
+        byTag,
+        storageSizeBytes,
+    };
+}
+/**
+ * Check if memory storage is available
+ */
+export function isMemoryStorageAvailable() {
+    try {
+        ensureMemoryStructure();
+        return existsSync(getRawPath());
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=markdown-storage.js.map