stellar-memory 0.5.0

package/dist/engine/orbit.js

@@ -0,0 +1,249 @@
+/**
+ * orbit.ts — Core importance function and orbital mechanics
+ *
+ * Implements the celestial mechanics metaphor:
+ *   - High importance  → small orbital distance (close to the sun)
+ *   - Low importance   → large orbital distance (far from the sun, fading)
+ *   - Access boost     → pulls a memory closer when it is recalled
+ *   - Decay            → memories drift outward over time via recency score
+ */
+import { ORBIT_ZONES } from './types.js';
+import { keywordRelevance, hybridRelevance } from './gravity.js';
+import { getMemoriesByProject, updateMemoryOrbit, insertOrbitLog, getSunState, cleanupOrbitLog, } from '../storage/queries.js';
+import { getDatabase } from '../storage/database.js';
+import { corona } from './corona.js';
+import { qualityOrbitAdjustment } from './quality.js';
+import { getProceduralDecayMultiplier } from './procedural.js';
+// ---------------------------------------------------------------------------
+// Scoring primitives
+// ---------------------------------------------------------------------------
+/**
+ * Calculate recency score using exponential decay.
+ *
+ * Formula: 0.5 ^ (hoursSince / effectiveHalfLife)
+ *   - At t=0          → score = 1.0
+ *   - At t=halfLife   → score = 0.5
+ *   - At t=2×halfLife → score = 0.25
+ *
+ * Procedural memories use a slower decay rate (halfLife / 0.3 ≈ 240h for default 72h)
+ * so hard-won knowledge persists longer.
+ *
+ * Returns a value in [0, 1].
+ */
+export function recencyScore(lastAccessedAt, createdAt, halfLifeHours = 72, memoryType) {
+    const referenceTime = lastAccessedAt ?? createdAt;
+    // Append 'Z' only when there is no existing timezone designator so that
+    // Date.parse interprets bare ISO strings as UTC rather than local time.
+    const normalized = /[Zz]$|[+-]\d{2}:\d{2}$/.test(referenceTime)
+        ? referenceTime
+        : referenceTime + 'Z';
+    const refMs = new Date(normalized).getTime();
+    if (isNaN(refMs))
+        throw new Error(`Invalid reference date: "${referenceTime}"`);
+    const now = new Date();
+    const hoursSince = (now.getTime() - refMs) / (1000 * 60 * 60);
+    // Procedural memories decay ~3.3x slower than normal
+    const effectiveHalfLife = memoryType === 'procedural'
+        ? halfLifeHours / getProceduralDecayMultiplier()
+        : halfLifeHours;
+    return Math.pow(0.5, Math.max(0, hoursSince) / effectiveHalfLife);
+}
+/**
+ * Calculate frequency score using logarithmic saturation.
+ *
+ * Formula: log(1 + count) / log(1 + saturationPoint)
+ *   - Grows quickly for the first few accesses.
+ *   - Plateaus as count approaches saturationPoint.
+ *
+ * Returns a value in [0, 1].
+ */
+export function frequencyScore(accessCount, saturationPoint = 20) {
+    if (saturationPoint <= 0)
+        throw new Error('saturationPoint must be positive');
+    return Math.min(1.0, Math.log(1 + accessCount) / Math.log(1 + saturationPoint));
+}
+// ---------------------------------------------------------------------------
+// Composite importance
+// ---------------------------------------------------------------------------
+/**
+ * Calculate overall importance from all four components.
+ *
+ * Weights are configured via StellarConfig and must sum to 1.0 for a
+ * meaningful 0–1 total (they do in the defaults: 0.30+0.20+0.30+0.20=1.00).
+ */
+export function calculateImportance(memory, sunText, config) {
+    const weights = config.weights;
+    const weightSum = weights.recency + weights.frequency + weights.impact + weights.relevance;
+    if (Math.abs(weightSum - 1.0) > 0.01) {
+        throw new Error(`Weights must sum to 1.0, got ${weightSum.toFixed(3)}`);
+    }
+    const rec = recencyScore(memory.last_accessed_at, memory.created_at, config.decayHalfLifeHours, memory.type);
+    const freq = frequencyScore(memory.access_count, config.frequencySaturationPoint);
+    const imp = memory.impact;
+    // Combine content + tags so tags act as relevance boosters.
+    const memoryText = memory.content + ' ' + memory.tags.join(' ');
+    // Attempt to load embeddings synchronously from the vec table for hybrid relevance.
+    // Falls back to keyword-only if embeddings are unavailable.
+    let rel;
+    try {
+        const db = getDatabase();
+        const memRow = db.prepare('SELECT embedding FROM memory_vec WHERE memory_id = ?').get(memory.id);
+        const sunState = getSunState(memory.project);
+        const sunText2 = sunState
+            ? [sunState.current_work, ...sunState.recent_decisions, ...sunState.next_steps].join(' ')
+            : sunText;
+        if (memRow?.embedding) {
+            const memEmbedding = new Float32Array(memRow.embedding.buffer, memRow.embedding.byteOffset, memRow.embedding.byteLength / 4);
+            // Look up the sun embedding via the most-recent sun memory, if available.
+            const sunRow = db.prepare(`SELECT mv.embedding FROM memory_vec mv
+         JOIN memories m ON m.id = mv.memory_id
+         WHERE m.project = ? AND m.deleted_at IS NULL
+         ORDER BY m.importance DESC LIMIT 1`).get(memory.project);
+            const sunEmbedding = sunRow?.embedding
+                ? new Float32Array(sunRow.embedding.buffer, sunRow.embedding.byteOffset, sunRow.embedding.byteLength / 4)
+                : undefined;
+            rel = hybridRelevance(memoryText, sunText2, memEmbedding, sunEmbedding);
+        }
+        else {
+            rel = keywordRelevance(memoryText, sunText);
+        }
+    }
+    catch {
+        rel = keywordRelevance(memoryText, sunText);
+    }
+    const total = config.weights.recency * rec +
+        config.weights.frequency * freq +
+        config.weights.impact * imp +
+        config.weights.relevance * rel;
+    return {
+        recency: rec,
+        frequency: freq,
+        impact: imp,
+        relevance: rel,
+        total: Math.min(1.0, Math.max(0.0, total)),
+    };
+}
+// ---------------------------------------------------------------------------
+// Distance mapping
+// ---------------------------------------------------------------------------
+/**
+ * Convert importance (0–1) to orbital distance (0.1–100).
+ *
+ * Uses quadratic mapping so that:
+ *   - importance = 1.0 → distance ≈ 0.1  (core / working memory)
+ *   - importance = 0.0 → distance = 100  (Oort cloud / nearly forgotten)
+ *
+ * The quadratic curve creates a non-linear relationship: a memory must fall
+ * significantly in importance before it drifts noticeably outward, which
+ * mirrors how cognitive salience works in practice.
+ */
+export function importanceToDistance(importance) {
+    const MIN_DISTANCE = 0.1;
+    const MAX_DISTANCE = 100.0;
+    const clamped = Math.min(1.0, Math.max(0.0, importance));
+    const normalized = Math.pow(1 - clamped, 2);
+    return MIN_DISTANCE + normalized * (MAX_DISTANCE - MIN_DISTANCE);
+}
+/**
+ * Inverse of importanceToDistance — derive importance from a given distance.
+ *
+ * Used when a user manually drags a memory to a new orbital position.
+ */
+export function distanceToImportance(distance) {
+    const MIN_DISTANCE = 0.1;
+    const MAX_DISTANCE = 100.0;
+    const clamped = Math.min(MAX_DISTANCE, Math.max(MIN_DISTANCE, distance));
+    const normalized = (clamped - MIN_DISTANCE) / (MAX_DISTANCE - MIN_DISTANCE);
+    return Math.max(0.0, Math.min(1.0, 1 - Math.sqrt(normalized)));
+}
+/**
+ * Return the orbit zone label for a given distance.
+ *
+ * Iterates ORBIT_ZONES in definition order (core → forgotten) and returns the
+ * first zone whose [min, max) range contains the distance. Falls back to
+ * the 'forgotten' label for any distance at or beyond 70.
+ */
+export function getOrbitZone(distance) {
+    for (const [, zone] of Object.entries(ORBIT_ZONES)) {
+        if (distance >= zone.min && distance < zone.max) {
+            return zone.label;
+        }
+    }
+    // Beyond all defined zones — treat as forgotten.
+    return ORBIT_ZONES.forgotten.label;
+}
+// ---------------------------------------------------------------------------
+// Access boost
+// ---------------------------------------------------------------------------
+/**
+ * Apply access boost — pull a memory closer when it is recalled.
+ *
+ * The boost is proportional to the current distance so that:
+ *   - Far-away memories (high distance) receive a large absolute pull.
+ *   - Close memories (low distance) are nudged only slightly.
+ *
+ * MIN_BOOST ensures even core memories get a small reward.
+ * The floor of 0.1 prevents distance from going below the core minimum.
+ */
+export function applyAccessBoost(currentDistance) {
+    const BOOST_FACTOR = 0.3;
+    const MIN_BOOST = 0.5;
+    const pull = Math.max(MIN_BOOST, currentDistance * BOOST_FACTOR);
+    return Math.max(0.1, currentDistance - pull);
+}
+// ---------------------------------------------------------------------------
+// Full orbit recalculation
+// ---------------------------------------------------------------------------
+/**
+ * Run a full orbit recalculation for all memories in a project.
+ *
+ * Called during stellar_commit and stellar_orbit. For each non-deleted memory:
+ *   1. Compute new importance using current sun context.
+ *   2. Map importance → distance.
+ *   3. If the distance shifted by more than 0.01, persist the change and log it.
+ *
+ * Returns every OrbitChange that was actually written.
+ */
+export function recalculateOrbits(project, config) {
+    const memories = getMemoriesByProject(project);
+    if (memories.length === 0) {
+        return [];
+    }
+    // Build sun context text for relevance scoring.
+    const sunState = getSunState(project);
+    const sunText = sunState
+        ? [sunState.current_work, ...sunState.recent_decisions, ...sunState.next_steps].join(' ')
+        : '';
+    const changes = [];
+    for (const memory of memories) {
+        const components = calculateImportance(memory, sunText, config);
+        const newImportance = components.total;
+        // Apply quality-based orbit adjustment: low-quality memories drift further out
+        const qualityScore = memory.quality_score ?? 0.5;
+        const newDistance = importanceToDistance(newImportance) * qualityOrbitAdjustment(qualityScore);
+        const velocity = newDistance - memory.distance;
+        // Skip negligible drifts to avoid write churn.
+        if (Math.abs(velocity) <= 0.01) {
+            continue;
+        }
+        const change = {
+            memory_id: memory.id,
+            project,
+            old_distance: memory.distance,
+            new_distance: newDistance,
+            old_importance: memory.importance,
+            new_importance: newImportance,
+            trigger: 'decay',
+        };
+        updateMemoryOrbit(memory.id, newDistance, newImportance, velocity);
+        insertOrbitLog(change);
+        changes.push(change);
+    }
+    // Prune orbit log entries older than 90 days to prevent unbounded growth.
+    cleanupOrbitLog(90);
+    // Refresh the corona cache after orbit recalculation so distance changes
+    // are reflected in the in-memory tier immediately.
+    corona.warmup(project);
+    return changes;
+}
+//# sourceMappingURL=orbit.js.map

package/dist/engine/orbit.js.map

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

package/dist/engine/planet.d.ts

@@ -0,0 +1,64 @@
+/**
+ * planet.ts — Memory (planet) management
+ *
+ * Memories are "planets" orbiting the sun. This module handles:
+ *   - createMemory  : place a new memory into orbit.
+ *   - recallMemories: search memories and apply access boost to results (hybrid).
+ *   - forgetMemory  : push a memory to the Oort cloud or soft-delete it.
+ *
+ * Phase 2: Hybrid search
+ *   createMemory kicks off an async background embedding job so that the
+ *   synchronous call returns immediately while the vector index is populated
+ *   without blocking the caller.
+ *
+ *   recallMemories merges FTS5 keyword results with vector KNN results using
+ *   Reciprocal Rank Fusion (RRF), then deduplicates and re-ranks.
+ */
+import type { Memory, MemoryType } from './types.js';
+/**
+ * Create a new memory planet and place it in initial orbit.
+ *
+ * Initial placement uses static component values because the memory has just
+ * been created and has no access history or proven relevance yet:
+ *   - recency    = 1.0  (brand new)
+ *   - frequency  = 0.0  (never recalled)
+ *   - impact     = type-specific default (or caller-supplied)
+ *   - relevance  = 0.0  (no context yet; updated on next commit)
+ *
+ * The resulting distance positions the memory in the inner zone for high-impact
+ * types (decisions, milestones) and further out for lower-impact types.
+ */
+export declare function createMemory(data: {
+    project: string;
+    content: string;
+    summary?: string;
+    type?: MemoryType;
+    impact?: number;
+    tags?: string[];
+}): Memory;
+/**
+ * Forget a memory.
+ *
+ * Modes:
+ *   - 'push'  : Push the memory to the Oort cloud (distance ≈ 95 AU).
+ *               The memory remains searchable but will rarely surface.
+ *   - 'delete': Soft-delete the memory (sets deleted_at; excluded from queries).
+ */
+export declare function forgetMemory(memoryId: string, mode: 'push' | 'delete'): void;
+/**
+ * Async tiered recall: 3-tier pipeline from corona cache → FTS5 → full hybrid.
+ *
+ * Tier 1: Corona cache (0ms) — core + near zone, token matching
+ * Tier 2: Active zone FTS5 (1-5ms) — distance 5.0–15.0
+ * Tier 3: Full hybrid FTS5 + vector (5-50ms) — distance 15.0+
+ *
+ * Early exit: if Tier 1 fills the requested limit, Tier 2 and 3 are skipped.
+ */
+export declare function recallMemoriesAsync(project: string, query: string, options?: {
+    type?: MemoryType | 'all';
+    minDistance?: number;
+    maxDistance?: number;
+    limit?: number;
+    excludeIds?: Set<string>;
+}): Promise<Memory[]>;
+//# sourceMappingURL=planet.d.ts.map