stellar-memory 0.5.0

package/dist/cli/init.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * stellar-memory init — One-command setup for Stellar Memory MCP server.
+ *
+ * Usage:
+ *   npx stellar-memory init          # Configure Claude Code + download model
+ *   npx stellar-memory init --skip-model  # Skip embedding model download
+ */
+import { execSync, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+const CYAN = '\x1b[36m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+function log(msg) {
+    console.log(msg);
+}
+function success(msg) {
+    console.log(`${GREEN}✓${RESET} ${msg}`);
+}
+function warn(msg) {
+    console.log(`${YELLOW}!${RESET} ${msg}`);
+}
+function fail(msg) {
+    console.error(`${RED}✗${RESET} ${msg}`);
+}
+function checkNodeVersion() {
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    if (major < 22 || (major === 22 && minor < 5)) {
+        fail(`Node.js 22.5+ required (detected: ${process.versions.node})`);
+        log('  Upgrade: nvm install 22 && nvm use 22');
+        return false;
+    }
+    success(`Node.js ${process.versions.node}`);
+    return true;
+}
+function checkClaudeCLI() {
+    try {
+        execSync('claude --version', { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function configureMCP() {
+    if (!checkClaudeCLI()) {
+        warn('Claude CLI not found — skipping MCP auto-configuration');
+        log('');
+        log('  To manually configure, add to your MCP settings:');
+        log(`  ${CYAN}claude mcp add stellar-memory -- npx -y stellar-memory${RESET}`);
+        log('');
+        return false;
+    }
+    log('');
+    log('Configuring Claude MCP server...');
+    const result = spawnSync('claude', [
+        'mcp', 'add', 'stellar-memory', '--', 'npx', '-y', 'stellar-memory'
+    ], {
+        stdio: 'inherit',
+        shell: true,
+    });
+    if (result.status === 0) {
+        success('MCP server registered with Claude');
+        return true;
+    }
+    else {
+        warn('MCP auto-configuration failed');
+        log('  You can manually run:');
+        log(`  ${CYAN}claude mcp add stellar-memory -- npx -y stellar-memory${RESET}`);
+        return false;
+    }
+}
+async function downloadModel() {
+    log('');
+    log('Downloading embedding model (~90 MB, one-time)...');
+    const setupScript = resolve(ROOT, '..', 'scripts', 'setup.mjs');
+    // When installed via npm, scripts/ is at the package root
+    // When running from source, it's at ../scripts/
+    const candidates = [
+        resolve(ROOT, 'scripts', 'setup.mjs'), // npm installed (dist/scripts/)
+        resolve(ROOT, '..', 'scripts', 'setup.mjs'), // from source (src/../scripts/)
+    ];
+    const scriptPath = candidates.find(p => existsSync(p));
+    if (!scriptPath) {
+        // Fallback: run inline model download
+        try {
+            const { pipeline, env } = await import('@xenova/transformers');
+            env.cacheDir = process.env['TRANSFORMERS_CACHE'] ?? undefined;
+            await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', {
+                quantized: true,
+                progress_callback: (info) => {
+                    if (info.status === 'progress' && info.progress != null) {
+                        const pct = Math.round(info.progress);
+                        process.stdout.write(`\r  Downloading... ${pct}%   `);
+                    }
+                },
+            });
+            process.stdout.write('\r' + ' '.repeat(40) + '\r');
+            success('Embedding model downloaded');
+            return true;
+        }
+        catch (err) {
+            warn(`Model download failed: ${err.message}`);
+            log('  You can retry later: npx stellar-memory setup');
+            return false;
+        }
+    }
+    const result = spawnSync('node', [scriptPath], {
+        stdio: 'inherit',
+        shell: true,
+    });
+    if (result.status === 0) {
+        success('Embedding model ready');
+        return true;
+    }
+    else {
+        warn('Model download failed — you can retry: npm run setup');
+        return false;
+    }
+}
+async function main() {
+    log('');
+    log(`${BOLD}${CYAN}  Stellar Memory — Setup${RESET}`);
+    log(`  ${'─'.repeat(40)}`);
+    log('');
+    // 1. Check Node.js
+    if (!checkNodeVersion()) {
+        process.exit(1);
+    }
+    const args = process.argv.slice(2);
+    const skipModel = args.includes('--skip-model');
+    // 2. Download embedding model
+    if (!skipModel) {
+        await downloadModel();
+    }
+    else {
+        warn('Skipping model download (--skip-model)');
+    }
+    // 3. Configure MCP
+    configureMCP();
+    // 4. Done
+    log('');
+    log(`${BOLD}${GREEN}  Setup complete!${RESET}`);
+    log('');
+    log('  Stellar Memory will activate automatically in Claude Code.');
+    log('  Start a conversation and your memories will persist across sessions.');
+    log('');
+    log(`  ${CYAN}Dashboard:${RESET}  npx stellar-memory api   → http://localhost:21547`);
+    log(`  ${CYAN}Docs:${RESET}       https://stellar-memory.com`);
+    log('');
+}
+main().catch((err) => {
+    fail(`Setup failed: ${err.message}`);
+    process.exit(1);
+});
+//# sourceMappingURL=init.js.map

package/dist/cli/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"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"}

package/dist/engine/analytics.d.ts

@@ -0,0 +1,93 @@
+/**
+ * analytics.ts — Memory Analytics
+ *
+ * Purely computational analysis of memory usage patterns, health metrics,
+ * and insights derived from memory and orbit_log data.
+ *
+ * No side effects — all functions are read-only queries.
+ */
+import type { MemoryAnalytics } from './types.js';
+/**
+ * Get comprehensive analytics for a project.
+ * Wraps queries.getAnalytics() and ensures all fields are populated.
+ */
+export declare function getFullAnalytics(project: string): MemoryAnalytics;
+/**
+ * Memory survival analysis — how do memories fare over time?
+ *
+ * Groups memories by age bucket (days since creation) and reports:
+ *   - survivingCount: still in habitable zone or closer (distance < 15)
+ *   - accessedCount:  accessed at least once
+ *   - forgottenCount: pushed to Oort (distance >= 70) or soft-deleted
+ */
+export declare function getSurvivalCurve(project: string): Array<{
+    ageInDays: number;
+    survivingCount: number;
+    accessedCount: number;
+    forgottenCount: number;
+}>;
+/**
+ * Analyze orbit_log to find which memories have moved the most.
+ *
+ * Returns up to 20 memories sorted by movement activity (most log entries first).
+ */
+export declare function getOrbitMovements(project: string, days?: number): Array<{
+    memoryId: string;
+    summary: string;
+    movements: Array<{
+        timestamp: string;
+        oldDistance: number;
+        newDistance: number;
+        trigger: string;
+    }>;
+    netMovement: number;
+}>;
+/**
+ * Group memories by their primary tag to find topic clusters.
+ *
+ * For each tag, computes:
+ *   - memory count
+ *   - average importance
+ *   - average distance
+ *   - recent activity (accesses in last 7 days)
+ *
+ * Sorted by recent activity (most active clusters first).
+ */
+export declare function getTopicClusters(project: string): Array<{
+    topic: string;
+    memoryCount: number;
+    avgImportance: number;
+    avgDistance: number;
+    recentActivity: number;
+}>;
+/**
+ * Detect periodic access patterns from orbit_log entries.
+ *
+ * Heuristics:
+ *   - Daily pattern: a tag/group accessed multiple times in a day consistently
+ *   - Weekly pattern: accesses concentrated on specific day-of-week
+ *   - Burst pattern: high access concentration in recent days
+ */
+export declare function detectAccessPatterns(project: string): Array<{
+    pattern: string;
+    description: string;
+    frequency: string;
+}>;
+/**
+ * Compute health metrics and generate actionable recommendations.
+ */
+export declare function getMemoryHealth(project: string): {
+    totalMemories: number;
+    activeRatio: number;
+    staleRatio: number;
+    qualityAvg: number;
+    conflictRatio: number;
+    consolidationOpportunities: number;
+    recommendations: string[];
+};
+/**
+ * Compile all analytics into a readable text report.
+ * Suitable for display in terminal or chat.
+ */
+export declare function generateReport(project: string): string;
+//# sourceMappingURL=analytics.d.ts.map