squish-memory 1.0.2 → 1.2.0

package/packages/cli/src/commands/recall.ts

@@ -0,0 +1,99 @@
+/**
+ * Recall Command - Get memory by ID or search
+ * 
+ * Usage: squish recall "query-or-uuid" [--pretty]
+ */
+
+import { Command } from 'commander';
+import { getMemory, search } from '../../../../core/memory/memories.js';
+import { shouldReturnRawFallback } from '../../../../core/ingestion/signal-engine.js';
+import { getMemorySnapshot } from '../../../../core/snapshots/retrieval.js';
+
+export function registerRecallCommand(program: Command) {
+  program
+    .command('recall <query>')
+    .description('Search or get memory by ID')
+    .option('-t, --type <type>', 'Filter by memory type')
+    .option('--place <place>', 'Filter by place (inbox, ref, wip, sandbox, board, sparks, archive)')
+    .option('-l, --limit <number>', 'Max results', '5')
+    .option('-P, --pretty', 'Human-friendly output', false)
+    .option('-p, --project <project>', 'Project path')
+    .action(async (query: string, options: any) => {
+      try {
+        const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(query);
+        
+        let result;
+        
+        if (isUuid) {
+          const memory = await getMemory(query);
+          if (!memory) {
+            console.error(JSON.stringify({ ok: false, error: 'Memory not found' }));
+            process.exit(1);
+          }
+          result = [memory];
+        } else {
+          const limit = parseInt(options.limit) || 5;
+          const memories = await search({
+            query,
+            project: options.project,
+            limit,
+            type: options.type,
+            placeType: options.place
+          });
+          result = await Promise.all(memories.map(async (memory) => {
+            const metadata = (memory.metadata ?? {}) as Record<string, unknown>;
+            const rawFallbackSnapshotId = typeof metadata.rawFallbackSnapshotId === 'string'
+              ? metadata.rawFallbackSnapshotId
+              : typeof (metadata.signal as Record<string, unknown> | undefined)?.rawFallbackSnapshotId === 'string'
+                ? String((metadata.signal as Record<string, unknown>).rawFallbackSnapshotId)
+                : undefined;
+            const nuanceSuppressed = Boolean(
+              metadata.nuanceSuppressed ??
+              (metadata.signal as Record<string, unknown> | undefined)?.nuanceSuppressed
+            );
+
+            if (shouldReturnRawFallback({
+              query,
+              hasRawFallback: Boolean(rawFallbackSnapshotId),
+              nuanceSuppressed,
+            }) && rawFallbackSnapshotId) {
+              const snapshot = await getMemorySnapshot(rawFallbackSnapshotId);
+              return {
+                ...memory,
+                rawFallback: snapshot?.content ?? null,
+              };
+            }
+
+            return memory;
+          }));
+        }
+
+        if (options.pretty) {
+          console.log(`\nFound ${result.length} memories:\n`);
+          result.forEach((r, i) => {
+            console.log(`${i + 1}. [${r.type}] ${r.content?.substring(0, 100)}...`);
+            console.log(`   Tags: ${r.tags?.join(', ') || 'none'}`);
+            console.log(`   Similarity: ${r.similarity?.toFixed(3) || 'N/A'}`);
+            console.log(`   ID: ${r.id}`);
+            console.log(`   Created: ${r.createdAt || 'unknown'}\n`);
+          });
+        } else {
+          console.log(JSON.stringify({
+            ok: true,
+            count: result.length,
+            results: result.map(r => ({
+              id: r.id,
+              type: r.type,
+              content: r.content,
+              tags: r.tags,
+              similarity: r.similarity,
+              createdAt: r.createdAt
+            }))
+          }, null, 2));
+        }
+      } catch (error: any) {
+        console.error(JSON.stringify({ ok: false, error: error.message }));
+        process.exit(1);
+      }
+    });
+}

package/packages/cli/src/commands/recent.ts

@@ -0,0 +1,57 @@
+/**
+ * Recent Command - Get recent memories by period
+ * 
+ * Usage: squish recent [--period today] [--limit 10]
+ */
+
+import { Command } from 'commander';
+import { getRecent } from '../../../../core/memory/memories.js';
+import { filterByDateRange } from '../../../../core/lib/utils.js';
+
+export function registerRecentCommand(program: Command) {
+  program
+    .command('recent')
+    .description('Recent memories (today/yesterday/thisweek/7days/30days)')
+    .option('--period <period>', 'Period: today, yesterday, thisweek, 7days, 14days, 30days, 90days', 'today')
+    .option('-l, --limit <number>', 'Max results', '10')
+    .option('-p, --project <project>', 'Project path', process.cwd())
+    .option('-P, --pretty', 'Human-friendly output', false)
+    .action(async (options: any) => {
+      try {
+        const limit = parseInt(options.limit) || 10;
+        const allRecent = await getRecent(options.project, 500);
+        
+        const periodMap: Record<string, [string, string]> = {
+          today: ['today', 'now'],
+          yesterday: ['yesterday', 'today'],
+          thisweek: ['this week', 'now'],
+          '7days': ['7 days', 'now'],
+          '14days': ['14 days', 'now'],
+          '30days': ['30 days', 'now'],
+          '90days': ['90 days', 'now'],
+        };
+        
+        const [since, until] = periodMap[options.period] || [options.period, 'now'];
+        const filtered = filterByDateRange(allRecent, since, until);
+        const results = filtered.slice(0, limit);
+
+        if (options.pretty) {
+          console.log(`\nRecent memories (${options.period}):\n`);
+          results.forEach((r, i) => {
+            console.log(`${i + 1}. [${r.type}] ${r.content?.substring(0, 100)}...`);
+            console.log(`   ${r.createdAt || 'unknown'}\n`);
+          });
+        } else {
+          console.log(JSON.stringify({
+            ok: true,
+            period: options.period,
+            count: results.length,
+            results
+          }, null, 2));
+        }
+      } catch (error: any) {
+        console.error(JSON.stringify({ ok: false, error: error.message }));
+        process.exit(1);
+      }
+    });
+}

package/packages/cli/src/commands/remember.ts

@@ -0,0 +1,139 @@
+/**
+ * Remember Command - Store a memory
+ * Auto-detects: learning vs note vs memory based on content patterns
+ * 
+ * Usage: squish remember "content" [--type observation] [--place sandbox] [--tags foo,bar] [--project /path]
+ */
+
+import { Command } from 'commander';
+import { rememberMemory } from '../../../../core/memory/memories.js';
+import { detectMemorySignals } from '../../../../core/memory/trigger-detector.js';
+import { pinMemory, unpinMemory } from '../../../../core/security/governance.js';
+
+export function registerRememberCommand(program: Command) {
+  program
+    .command('remember <content>')
+    .description('Store a memory (auto-detects learning/note/memory type)')
+    .option('-t, --type <type>', 'Memory type (observation, fact, decision, context, preference)', 'observation')
+    .option('-T, --tags <tags>', 'Comma-separated tags')
+    .option('-p, --project <project>', 'Project path', process.cwd())
+    .option('-s, --source <source>', 'Source (cli, voice, chat, document)', 'cli')
+    .option('-r, --reasoning <reasoning>', 'Why this memory is important')
+    .option('-c, --context <context>', 'What triggered this memory')
+    .option('-e, --examples <examples>', 'When to apply this knowledge')
+    .option('-x, --exceptions <exceptions>', 'When NOT to apply this')
+    .option('--place <place>', 'Place to assign (inbox, ref, wip, sandbox, board, sparks, archive)')
+    .option('-H, --hot', 'Store in hot tier (active)', false)
+    .option('-C, --cold', 'Store in cold tier (archived)', false)
+    .option('--pin', 'Pin memory to prevent pruning', false)
+    .option('--unpin', 'Unpin memory', false)
+    .option('--route <route>', 'Routing: auto, memory, learning, note', 'auto')
+    .option('--learning-type <type>', 'Learning type if routing to learning: success, failure, fix, insight')
+    .action(async (content: string, options: any) => {
+      const previousQuiet = process.env.SQUISH_QUIET;
+      process.env.SQUISH_QUIET = '1';
+      try {
+        const signals = detectMemorySignals(content);
+        
+        const tags = options.tags ? options.tags.split(',').map((t: string) => t.trim()) : [];
+        
+        // Auto-detect routing based on content patterns
+        let routing = options.route;
+        let routingReason = "";
+        
+        if (routing === "auto") {
+          const hasLessonPattern = /(\bfailed\s+because\b|\blesson\s+learned\b|\bnext\s+time\b|\broot\s+cause\b|\bsuccess\b.*\bbecause\b|\bi\s+learned\b|\binsight\b)/i.test(content);
+          const hasLearningType = /(\bsuccess\b|\bfailure\b|\bfix\b|\binsight\b)/i.test(content);
+          const hasHackPattern = /(\bHACK\b|\bworkaround\b|\btemporary\s+fix\b|\bFIXME\b|\bXXX\b)/i.test(content);
+          
+          if (hasLessonPattern || hasLearningType || hasHackPattern) {
+            routing = "learning";
+            routingReason = "Auto-detected as learning";
+          } else if (signals.suggestedType === 'task') {
+            routing = "memory";
+            routingReason = "Detected as task";
+          } else if (/\b(note|note\s+that|log)\b/i.test(content)) {
+            routing = "note";
+            routingReason = "Auto-detected as note";
+          } else {
+            routing = "memory";
+            routingReason = "Default to memory";
+          }
+        }
+        
+        const tier: 'hot' | 'cold' = options.cold ? 'cold' : 'hot';
+        
+        let result: any;
+        
+        if (routing === "learning") {
+          // Handle learning routing - import dynamically to avoid issues
+          const { createLearning } = await import('../../../../core/ingestion/learnings.js');
+          let learningType = options.learningType;
+          if (!learningType) {
+            if (/(\bsuccess\b|\bworked\b|\bfinished\b)/i.test(content)) learningType = "success";
+            else if (/(\bfailed\b|\berror\b|\bbroke\b)/i.test(content)) learningType = "failure";
+            else if (/(\bfix\b|\bworkaround\b|\bsolved\b)/i.test(content)) learningType = "fix";
+            else learningType = "insight";
+          }
+          result = await createLearning({
+            type: learningType,
+            content,
+            project: options.project,
+            autoLink: true
+          });
+        } else {
+          // Store as memory
+          result = await rememberMemory({
+            content,
+            project: options.project,
+            tags,
+            type: options.type || signals.suggestedType,
+            tier,
+            source: options.source,
+            reasoning: options.reasoning,
+            memoryContext: options.context,
+            examples: options.examples,
+            exceptions: options.exceptions
+          });
+          
+          if (options.pin) {
+            await pinMemory(result.id);
+          } else if (options.unpin) {
+            await unpinMemory(result.id);
+          }
+
+          // Auto-update knowledge graph (fire-and-forget)
+          try {
+            const { addMemoryToGraph } = await import('../../../../core/graph/graph-builder.js');
+            const graphResult = await addMemoryToGraph(result.id);
+            if (graphResult && graphResult.entitiesCreated > 0) {
+              console.error(`[Graph] Added ${graphResult.entitiesCreated} entities, ${graphResult.relationsCreated} relations`);
+            }
+          } catch (e: any) {
+            // Ignore graph errors - don't fail the remember command
+          }
+        }
+
+        console.log(JSON.stringify({
+          ok: true,
+          id: result.id,
+          routing,
+          type: routing === "learning" ? result.type : result.type,
+          tier: routing === "memory" ? tier : null,
+          place: options.place || null,
+          priority: signals.priority,
+          confidence: signals.confidence,
+          reason: routingReason
+        }, null, 2));
+      } catch (error: any) {
+        console.error(JSON.stringify({ ok: false, error: error.message }));
+        process.exit(1);
+      } finally {
+        if (previousQuiet === undefined) {
+          delete process.env.SQUISH_QUIET;
+        } else {
+          process.env.SQUISH_QUIET = previousQuiet;
+        }
+      }
+    });
+}

package/packages/cli/src/commands/run.ts

@@ -0,0 +1,58 @@
+/**
+ * Run Command - Start Squish web UI
+ *
+ * Usage:
+ *   squish run web                   - Start web UI
+ *   squish run web --port <port>    - Custom port (default: 37777)
+ *   squish run web --open           - Open browser automatically
+ */
+
+import { Command } from 'commander';
+import { spawn } from 'child_process';
+import { join } from 'path';
+
+export function registerRunCommand(program: Command) {
+  const run = new Command('run');
+  run.description('Start Squish services');
+
+  run
+    .command('web')
+    .description('Start Squish web UI')
+    .option('-p, --port <port>', 'Port for web UI', '37777')
+    .option('-o, --open', 'Open browser automatically', false)
+    .action(async (options: any) => {
+      const port = parseInt(options.port || '37777', 10);
+      if (isNaN(port) || port < 1 || port > 65535) {
+        console.error(`Error: Invalid port number: ${options.port}`);
+        process.exit(1);
+      }
+
+      const url = `http://localhost:${port}`;
+
+      console.log(`\x1b[36mStarting Squish web UI on ${url}...\x1b[0m`);
+
+      // Spawn bun to run the server - keep it in foreground like `bun run dev`
+      const child = spawn('bun', ['run', 'webui/server.ts'], {
+        cwd: process.cwd(),
+        stdio: 'inherit',
+        env: { ...process.env, SQUISH_WEB_PORT: String(port) }
+      });
+
+      // Handle browser open
+      if (options.open) {
+        const start = process.platform === 'darwin' ? 'open' : 
+                      process.platform === 'win32' ? 'start' : 'xdg-open';
+        setTimeout(() => spawn(start, [url], { detached: true }), 1500);
+      }
+
+      // Keep process alive and forward signals
+      child.on('close', (code) => {
+        process.exit(code || 0);
+      });
+
+      process.on('SIGINT', () => child.kill('SIGTERM'));
+      process.on('SIGTERM', () => child.kill('SIGTERM'));
+    });
+
+  program.addCommand(run);
+}

package/packages/cli/src/commands/stale.ts

@@ -0,0 +1,43 @@
+/**
+ * Stale Command - Show stale memories
+ * 
+ * Usage: squish stale [--days 30] [--limit 20]
+ */
+
+import { Command } from 'commander';
+import { getRecent } from '../../../../core/memory/memories.js';
+
+export function registerStaleCommand(program: Command) {
+  program
+    .command('stale')
+    .description('Show stale memories (old, low-confidence, or rarely accessed)')
+    .option('-d, --days <number>', 'Show memories older than N days', '30')
+    .option('-l, --limit <number>', 'Max results', '20')
+    .option('-p, --project <project>', 'Project path', process.cwd())
+    .action(async (options: any) => {
+      try {
+        const days = parseInt(options.days) || 30;
+        const cutoffDate = new Date(Date.now() - days * 86400000);
+        const results = await getRecent(options.project, 500);
+        
+        const stale = results.filter((m: any) => {
+          const created = m.createdAt ? new Date(m.createdAt) : null;
+          const isOld = created && created < cutoffDate;
+          const isLowConfidence = m.confidenceLevel === 'outdated' || m.confidenceLevel === 'speculative';
+          const hasLowImportance = (m.importance || 50) < 40;
+          return isOld || isLowConfidence || hasLowImportance;
+        });
+        
+        const limited = stale.slice(0, parseInt(options.limit) || 20);
+        console.log(JSON.stringify({
+          ok: true,
+          totalStale: stale.length,
+          count: limited.length,
+          memories: limited
+        }, null, 2));
+      } catch (error: any) {
+        console.error(JSON.stringify({ ok: false, error: error.message }));
+        process.exit(1);
+      }
+    });
+}

package/packages/cli/src/commands/stats.ts

@@ -0,0 +1,42 @@
+/**
+ * Stats Command - View memory statistics
+ * 
+ * Usage: squish stats [--project /path]
+ */
+
+import { Command } from 'commander';
+import { buildStatsState } from '../../../../core/runtime/trust-state.js';
+import { formatStatsReport } from '../../../../core/runtime/trust-report.js';
+
+export function registerStatsCommand(program: Command) {
+  program
+    .command('stats')
+    .description('View memory statistics')
+    .option('-p, --project <project>', 'Project path')
+    .option('--json', 'Emit machine-readable output', false)
+    .action(async (options: any) => {
+      const previousQuiet = process.env.SQUISH_QUIET;
+      if (options.json) {
+        process.env.SQUISH_QUIET = '1';
+      }
+      try {
+        const stats = await buildStatsState(options.project);
+        if (options.json) {
+          console.log(JSON.stringify({ ok: true, ...stats }, null, 2));
+          return;
+        }
+        console.log(formatStatsReport(stats));
+      } catch (error: any) {
+        console.error(JSON.stringify({ ok: false, error: error.message }));
+        process.exit(1);
+      } finally {
+        if (options.json) {
+          if (previousQuiet === undefined) {
+            delete process.env.SQUISH_QUIET;
+          } else {
+            process.env.SQUISH_QUIET = previousQuiet;
+          }
+        }
+      }
+    });
+}

package/packages/cli/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Squish CLI - Main Entry Point
+ * Universal Memory for AI Agents
+ * 
+ * Usage:
+ *   squish remember "Store this memory"
+ *   squish recall "query"
+ *   squish context --list-projects
+ */
+
+import { Command } from 'commander';
+
+// Import all commands
+import { registerRememberCommand } from './commands/remember.js';
+import { registerRecallCommand } from './commands/recall.js';
+import { registerRecentCommand } from './commands/recent.js';
+import { registerContextCommand } from './commands/context.js';
+import { registerStatsCommand } from './commands/stats.js';
+import { registerForgetCommand } from './commands/forget.js';
+import { registerLinkCommand } from './commands/link.js';
+import { registerStaleCommand } from './commands/stale.js';
+import { registerCleanCommand } from './commands/clean.js';
+import { registerMigrateCommand } from './commands/migrate.js';
+import { registerRunCommand } from './commands/run.js';
+import { registerDoctorCommand } from './commands/doctor.js';
+import { registerInspectCommand } from './commands/inspect.js';
+import { registerHealthCommand } from './commands/health.js';
+
+const program = new Command();
+
+program
+  .name('squish')
+  .description('Universal Memory for AI Agents - CLI')
+  .version('1.2.0');
+
+// Register all commands
+registerRememberCommand(program);
+registerRecallCommand(program);
+registerRecentCommand(program);
+registerContextCommand(program);
+registerStatsCommand(program);
+registerForgetCommand(program);
+registerLinkCommand(program);
+registerStaleCommand(program);
+registerCleanCommand(program);
+registerMigrateCommand(program);
+registerRunCommand(program);
+registerDoctorCommand(program);
+registerInspectCommand(program);
+registerHealthCommand(program);
+
+// Default: show help if no arguments
+if (process.argv.length === 2) {
+  program.parse(['node', 'squish', '--help']);
+} else {
+  program.parse();
+}

package/packages/cli/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noEmit": false,
+    "types": ["node"],
+    "paths": {
+      "@squish/core": ["../../core/*"],
+      "@squish/memory": ["../../core/memory/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/packages/mcp/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@squish/mcp",
+  "version": "1.2.0",
+  "description": "Squish MCP Server - Model Context Protocol Server",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "squish-mcp": "../../bin/squish-mcp.mjs"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "bun run src/index.ts",
+    "mcp:stdio": "bun run src/index.ts --stdio",
+    "mcp:http": "bun run src/index.ts --http"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^3.24.0",
+    "express": "^5.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^6.0.2"
+  }
+}