stellar-memory 0.5.0

package/dist/engine/embedding.d.ts

@@ -0,0 +1,44 @@
+/**
+ * embedding.ts — Local text embedding using Transformers.js
+ *
+ * Uses the all-MiniLM-L6-v2 model (384 dimensions) for generating dense
+ * vector representations of memory text. The model runs entirely in-process
+ * via @xenova/transformers — no API key or network call required after the
+ * initial model download (~90 MB, cached in ~/.cache/huggingface).
+ *
+ * Design:
+ *   - Singleton pipeline: the model is loaded once and reused.
+ *   - generateEmbedding() returns a normalized Float32Array.
+ *   - Supports Korean + English mixed text (multilingual tokenizer).
+ *   - Input is capped at MAX_CHARS to avoid excessive tokenization.
+ */
+/**
+ * Reset the singleton pipeline (for testing purposes).
+ * Allows tests to inject a mock pipeline via _setPipelineForTest().
+ */
+export declare function _resetPipeline(): void;
+/**
+ * Inject a mock pipeline (for unit tests that don't want to download the model).
+ * The mock must be callable: mock(text, options) → { data: Float32Array }
+ */
+export declare function _setPipelineForTest(mock: unknown): void;
+/**
+ * Generate a 384-dimensional embedding vector for the given text.
+ *
+ * The returned Float32Array is L2-normalized so that cosine similarity
+ * reduces to a simple dot product.
+ *
+ * Text preprocessing:
+ *   - Trims whitespace
+ *   - Caps at MAX_CHARS characters to stay within the tokenizer limit
+ *   - Collapses excessive whitespace runs
+ */
+export declare function generateEmbedding(text: string): Promise<Float32Array>;
+/**
+ * Preprocess text before tokenization:
+ *   1. Trim
+ *   2. Collapse internal whitespace runs to a single space
+ *   3. Truncate to MAX_CHARS
+ */
+export declare function preprocessText(text: string): string;
+//# sourceMappingURL=embedding.d.ts.map

package/dist/engine/embedding.js

@@ -0,0 +1,168 @@
+/**
+ * embedding.ts — Local text embedding using Transformers.js
+ *
+ * Uses the all-MiniLM-L6-v2 model (384 dimensions) for generating dense
+ * vector representations of memory text. The model runs entirely in-process
+ * via @xenova/transformers — no API key or network call required after the
+ * initial model download (~90 MB, cached in ~/.cache/huggingface).
+ *
+ * Design:
+ *   - Singleton pipeline: the model is loaded once and reused.
+ *   - generateEmbedding() returns a normalized Float32Array.
+ *   - Supports Korean + English mixed text (multilingual tokenizer).
+ *   - Input is capped at MAX_CHARS to avoid excessive tokenization.
+ */
+// @xenova/transformers uses a dynamic import pattern that is CJS-compatible
+// when called from Node.js ESM. We import the type for the pipeline function
+// and load it lazily.
+const MODEL_NAME = 'Xenova/all-MiniLM-L6-v2';
+const MAX_CHARS = 2000; // roughly 512 tokens for mixed Korean/English text
+// Lazily resolved singleton pipeline instance.
+// Typed as `unknown` to avoid pulling in the full @xenova/transformers types
+// at compile time (the package has non-standard type layouts that vary by version).
+let _pipeline = null;
+let _loading = null;
+// ── Progress tracking ────────────────────────────────────────────────────────
+let _downloadStartTime = 0;
+let _lastProgressPct = -1;
+let _currentFile = '';
+let _loggedFiles = new Set();
+function _formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function _formatTime(seconds) {
+    if (seconds < 60)
+        return `${Math.round(seconds)}s`;
+    return `${Math.floor(seconds / 60)}m ${Math.round(seconds % 60)}s`;
+}
+function _onDownloadProgress(info) {
+    const { status, file, progress, loaded, total } = info;
+    const fileName = (file ?? '').split('/').pop() ?? '';
+    if (status === 'initiate') {
+        if (_downloadStartTime === 0) {
+            _downloadStartTime = Date.now();
+            console.error('[stellar-memory] Downloading embedding model (~90 MB, first run only)...');
+            console.error('[stellar-memory] This will be cached for future sessions.');
+        }
+        // Reset per-file tracking when a new file starts
+        if (fileName && fileName !== _currentFile) {
+            _currentFile = fileName;
+            _lastProgressPct = -1;
+        }
+    }
+    if (status === 'progress' && progress != null && fileName) {
+        // Only show detailed progress for the main model file (onnx)
+        const isModelFile = fileName.endsWith('.onnx');
+        if (!isModelFile)
+            return;
+        const pct = Math.min(100, Math.round(progress));
+        if (pct > _lastProgressPct + 10 || (pct === 100 && _lastProgressPct < 100)) {
+            _lastProgressPct = pct;
+            const elapsed = (Date.now() - _downloadStartTime) / 1000;
+            const eta = pct > 0 ? (elapsed / pct) * (100 - pct) : 0;
+            const sizeInfo = loaded != null && total != null
+                ? `  ${_formatBytes(loaded)} / ${_formatBytes(total)}`
+                : '';
+            const etaInfo = eta > 1 ? `  ETA: ${_formatTime(eta)}` : '';
+            console.error(`[stellar-memory] Downloading [${fileName}]: ${pct}%${sizeInfo}${etaInfo}`);
+        }
+    }
+    if (status === 'done' && fileName && !_loggedFiles.has(fileName)) {
+        _loggedFiles.add(fileName);
+    }
+    if (status === 'ready') {
+        const elapsed = _downloadStartTime > 0
+            ? ` in ${((Date.now() - _downloadStartTime) / 1000).toFixed(1)}s`
+            : '';
+        console.error(`[stellar-memory] Embedding model ready${elapsed}`);
+        _downloadStartTime = 0;
+        _lastProgressPct = -1;
+        _currentFile = '';
+        _loggedFiles = new Set();
+    }
+}
+/**
+ * Load and cache the feature-extraction pipeline.
+ * Subsequent calls return the same promise / resolved value.
+ */
+async function getPipeline() {
+    if (_pipeline)
+        return _pipeline;
+    if (!_loading) {
+        _loading = (async () => {
+            // Dynamic import keeps this from failing at require()-time in environments
+            // where the model is not yet available (e.g., during unit tests that mock it).
+            const { pipeline, env } = await import('@xenova/transformers');
+            // Allow the model to be stored in the default HuggingFace cache directory.
+            // In CI/test environments TRANSFORMERS_CACHE can be set to override this.
+            if (process.env['TRANSFORMERS_CACHE']) {
+                env.cacheDir = process.env['TRANSFORMERS_CACHE'];
+            }
+            const pipe = await pipeline('feature-extraction', MODEL_NAME, {
+                quantized: true, // use the int8-quantized model for faster inference
+                progress_callback: _onDownloadProgress,
+            });
+            _pipeline = pipe;
+            return pipe;
+        })();
+    }
+    return _loading;
+}
+/**
+ * Reset the singleton pipeline (for testing purposes).
+ * Allows tests to inject a mock pipeline via _setPipelineForTest().
+ */
+export function _resetPipeline() {
+    _pipeline = null;
+    _loading = null;
+}
+/**
+ * Inject a mock pipeline (for unit tests that don't want to download the model).
+ * The mock must be callable: mock(text, options) → { data: Float32Array }
+ */
+export function _setPipelineForTest(mock) {
+    _pipeline = mock;
+    _loading = null;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Generate a 384-dimensional embedding vector for the given text.
+ *
+ * The returned Float32Array is L2-normalized so that cosine similarity
+ * reduces to a simple dot product.
+ *
+ * Text preprocessing:
+ *   - Trims whitespace
+ *   - Caps at MAX_CHARS characters to stay within the tokenizer limit
+ *   - Collapses excessive whitespace runs
+ */
+export async function generateEmbedding(text) {
+    const input = preprocessText(text);
+    const pipe = await getPipeline();
+    // @xenova/transformers returns a Tensor-like object. We use mean pooling
+    // (pooling_mode: 'mean') and then L2-normalize to get a unit vector.
+    const output = await pipe(input, {
+        pooling: 'mean',
+        normalize: true,
+    });
+    return new Float32Array(output.data);
+}
+/**
+ * Preprocess text before tokenization:
+ *   1. Trim
+ *   2. Collapse internal whitespace runs to a single space
+ *   3. Truncate to MAX_CHARS
+ */
+export function preprocessText(text) {
+    return text
+        .trim()
+        .replace(/\s+/g, ' ')
+        .slice(0, MAX_CHARS);
+}
+//# sourceMappingURL=embedding.js.map

package/dist/engine/embedding.js.map

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

package/dist/engine/gravity.d.ts

@@ -0,0 +1,63 @@
+/**
+ * gravity.ts — Relevance calculation (keyword + vector)
+ *
+ * Phase 1: keyword overlap between memory content and sun context.
+ * Phase 2: cosine vector similarity + hybrid score combining both.
+ *
+ * Hybrid formula:  0.7 × vectorRelevance + 0.3 × keywordRelevance
+ *
+ * The keyword score is retained as a fast fallback when embeddings are not
+ * available (e.g., during unit tests or before the model has loaded).
+ */
+/**
+ * Tokenize text: split by whitespace, lowercase, strip punctuation, filter
+ * words shorter than 2 characters.
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * Calculate keyword relevance between a memory and the current sun context.
+ *
+ * Algorithm:
+ *   1. Tokenize both texts.
+ *   2. Build a Set from sun tokens.
+ *   3. Count how many memory tokens appear in the sun set.
+ *   4. Score = min(1.0, overlap / max(3, sunTokens.length * 0.3))
+ *
+ * Returns a score between 0 and 1.
+ * Returns 0 if sunText is empty.
+ */
+export declare function keywordRelevance(memoryText: string, sunText: string): number;
+/**
+ * Cosine similarity between two Float32Arrays of equal length.
+ *
+ * Formula: dot(a, b) / (‖a‖ × ‖b‖)
+ *
+ * Returns a value in [-1, 1]; in practice [0, 1] for embeddings produced
+ * by all-MiniLM-L6-v2 (which are L2-normalized, so norm(a) = norm(b) = 1).
+ *
+ * Returns 0 for zero-length or mismatched vectors.
+ */
+export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+/**
+ * Vector relevance between a memory embedding and the sun (context) embedding.
+ *
+ * Wraps cosineSimilarity and converts the [-1, 1] cosine distance into a
+ * [0, 1] relevance score:  score = (similarity + 1) / 2
+ *
+ * For normalized embeddings (all-MiniLM-L6-v2), similarity is already [0, 1]
+ * in practice, but the rescaling ensures the contract is always satisfied.
+ *
+ * Returns 0 when either embedding is null/undefined.
+ */
+export declare function vectorRelevance(memoryEmbedding: Float32Array | null | undefined, sunEmbedding: Float32Array | null | undefined): number;
+/**
+ * Hybrid relevance: combines vector semantic similarity with keyword overlap.
+ *
+ *   score = VECTOR_WEIGHT × vectorRelevance + KEYWORD_WEIGHT × keywordRelevance
+ *
+ * Falls back gracefully:
+ *   - If embeddings are absent → pure keyword score.
+ *   - If sunText is empty      → pure vector score (if embedding available).
+ */
+export declare function hybridRelevance(memoryText: string, sunText: string, memoryEmbedding: Float32Array | null | undefined, sunEmbedding: Float32Array | null | undefined): number;
+//# sourceMappingURL=gravity.d.ts.map

package/dist/engine/gravity.js

@@ -0,0 +1,121 @@
+/**
+ * gravity.ts — Relevance calculation (keyword + vector)
+ *
+ * Phase 1: keyword overlap between memory content and sun context.
+ * Phase 2: cosine vector similarity + hybrid score combining both.
+ *
+ * Hybrid formula:  0.7 × vectorRelevance + 0.3 × keywordRelevance
+ *
+ * The keyword score is retained as a fast fallback when embeddings are not
+ * available (e.g., during unit tests or before the model has loaded).
+ */
+// Hybrid weighting constants
+const VECTOR_WEIGHT = 0.7;
+const KEYWORD_WEIGHT = 0.3;
+/**
+ * Tokenize text: split by whitespace, lowercase, strip punctuation, filter
+ * words shorter than 2 characters.
+ */
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/\s+/)
+        .map(word => word.replace(/[^\w]/g, ''))
+        .filter(word => word.length >= 2);
+}
+/**
+ * Calculate keyword relevance between a memory and the current sun context.
+ *
+ * Algorithm:
+ *   1. Tokenize both texts.
+ *   2. Build a Set from sun tokens.
+ *   3. Count how many memory tokens appear in the sun set.
+ *   4. Score = min(1.0, overlap / max(3, sunTokens.length * 0.3))
+ *
+ * Returns a score between 0 and 1.
+ * Returns 0 if sunText is empty.
+ */
+export function keywordRelevance(memoryText, sunText) {
+    if (!sunText || sunText.trim().length === 0) {
+        return 0;
+    }
+    const sunTokens = tokenize(sunText);
+    if (sunTokens.length === 0) {
+        return 0;
+    }
+    const sunSet = new Set(sunTokens);
+    const memoryTokens = tokenize(memoryText);
+    const memorySet = new Set(memoryTokens);
+    let overlap = 0;
+    for (const token of memorySet) {
+        if (sunSet.has(token)) {
+            overlap++;
+        }
+    }
+    const denominator = Math.max(5, sunTokens.length * 0.3);
+    return Math.min(1.0, overlap / denominator);
+}
+// ---------------------------------------------------------------------------
+// Vector relevance (Phase 2)
+// ---------------------------------------------------------------------------
+/**
+ * Cosine similarity between two Float32Arrays of equal length.
+ *
+ * Formula: dot(a, b) / (‖a‖ × ‖b‖)
+ *
+ * Returns a value in [-1, 1]; in practice [0, 1] for embeddings produced
+ * by all-MiniLM-L6-v2 (which are L2-normalized, so norm(a) = norm(b) = 1).
+ *
+ * Returns 0 for zero-length or mismatched vectors.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    if (denom === 0)
+        return 0;
+    // Clamp to [0, 1] — cosine can be slightly negative due to float rounding.
+    return Math.max(0, Math.min(1, dot / denom));
+}
+/**
+ * Vector relevance between a memory embedding and the sun (context) embedding.
+ *
+ * Wraps cosineSimilarity and converts the [-1, 1] cosine distance into a
+ * [0, 1] relevance score:  score = (similarity + 1) / 2
+ *
+ * For normalized embeddings (all-MiniLM-L6-v2), similarity is already [0, 1]
+ * in practice, but the rescaling ensures the contract is always satisfied.
+ *
+ * Returns 0 when either embedding is null/undefined.
+ */
+export function vectorRelevance(memoryEmbedding, sunEmbedding) {
+    if (!memoryEmbedding || !sunEmbedding)
+        return 0;
+    return Math.max(0, cosineSimilarity(memoryEmbedding, sunEmbedding));
+}
+/**
+ * Hybrid relevance: combines vector semantic similarity with keyword overlap.
+ *
+ *   score = VECTOR_WEIGHT × vectorRelevance + KEYWORD_WEIGHT × keywordRelevance
+ *
+ * Falls back gracefully:
+ *   - If embeddings are absent → pure keyword score.
+ *   - If sunText is empty      → pure vector score (if embedding available).
+ */
+export function hybridRelevance(memoryText, sunText, memoryEmbedding, sunEmbedding) {
+    const vecScore = vectorRelevance(memoryEmbedding, sunEmbedding);
+    const kwScore = keywordRelevance(memoryText, sunText);
+    // If we have no vector signal, fall back entirely to keywords.
+    if (!memoryEmbedding || !sunEmbedding)
+        return kwScore;
+    return Math.min(1.0, VECTOR_WEIGHT * vecScore + KEYWORD_WEIGHT * kwScore);
+}
+//# sourceMappingURL=gravity.js.map

package/dist/engine/gravity.js.map

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

package/dist/engine/multiproject.d.ts

@@ -0,0 +1,75 @@
+/**
+ * multiproject.ts — Multi-Project Galaxy management
+ *
+ * Manages runtime project switching and cross-project knowledge sharing.
+ * Universal memories are memories marked to appear in ALL project recall results.
+ *
+ * State: currentProject is the one mutable singleton in this module.
+ *        All other functions are pure queries or side-effectful writes to the DB.
+ */
+import type { Memory } from './types.js';
+/**
+ * Return the currently active project name.
+ */
+export declare function getCurrentProject(): string;
+/**
+ * Switch the active project at runtime without restarting.
+ *
+ * Returns info about the transition so callers can report it to the user.
+ */
+export declare function switchProject(project: string): {
+    previous: string;
+    current: string;
+    memoryCount: number;
+};
+/**
+ * Create a new project by seeding a sun_state entry for it.
+ * If the project already has a sun_state, returns created=false.
+ */
+export declare function createProject(name: string): {
+    project: string;
+    created: boolean;
+};
+/**
+ * List all projects with basic statistics.
+ * Always includes 'default' even if it has no memories yet.
+ */
+export declare function listAllProjects(): Array<{
+    project: string;
+    memoryCount: number;
+    lastUpdated: string;
+    hasUniversal: boolean;
+}>;
+/**
+ * Mark (or unmark) a memory as universal.
+ * Universal memories surface in recall results for all projects.
+ */
+export declare function markUniversal(memoryId: string, isUniversal: boolean): void;
+/**
+ * Get universal memories relevant to a project.
+ * Filters out memories that already belong to the current project
+ * (no need to surface them twice) and sorts by importance.
+ */
+export declare function getUniversalContext(project: string, limit?: number): Memory[];
+/**
+ * Detect memories that are strong candidates to become universal.
+ *
+ * Criteria:
+ *   - type = 'procedural' (behavioral rules are generally universal)
+ *   - type = 'context' with generic technical content (no project-specific terms)
+ *   - importance > 0.8 (highly important knowledge tends to be broadly applicable)
+ *   - not already marked universal
+ */
+export declare function detectUniversalCandidates(project: string): Memory[];
+/**
+ * Detailed statistics for a single project.
+ */
+export declare function getProjectStats(project: string): {
+    memoryCount: number;
+    zoneDistribution: Record<string, number>;
+    typeDistribution: Record<string, number>;
+    universalCount: number;
+    oldestMemory: string;
+    newestMemory: string;
+};
+//# sourceMappingURL=multiproject.d.ts.map