stellar-memory 0.5.0

package/dist/engine/observation.js

@@ -0,0 +1,357 @@
+/**
+ * observation.ts — Observational Memory ("Comet")
+ *
+ * Auto-extracts knowledge from raw conversation text and stores it as
+ * structured memories. Like comets that bring material from the outer
+ * solar system, observations bring new information from conversations
+ * into the memory system.
+ *
+ * Pipeline:
+ *   observe()           → extract pattern-matched memories from a chunk
+ *   reflect()           → categorize observations (novel / reinforcing / conflicting)
+ *   processConversation → full pipeline: split → observe → reflect → store
+ *
+ * No LLM is used — all extraction is done via keyword matching and heuristics.
+ */
+import { randomUUID } from 'node:crypto';
+import { createMemory } from './planet.js';
+import { recallMemoriesAsync } from './planet.js';
+import { createObservation } from '../storage/queries.js';
+import { updateMemoryOrbit, updateMemoryAccess } from '../storage/queries.js';
+import { applyAccessBoost } from './orbit.js';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('observation');
+// ---------------------------------------------------------------------------
+// Keyword dictionaries
+// ---------------------------------------------------------------------------
+const DECISION_KEYWORDS = [
+    'chose', 'decided', 'will use', 'switched to', 'selected', 'picked',
+    'going with', 'we will', 'opted for', 'adopted', 'migrated to',
+    '결정', '선택', '사용하기로', '변경', '채택',
+];
+const ERROR_KEYWORDS = [
+    'error', 'bug', 'fix', 'fixed', 'failed', 'crash', 'issue', 'broken',
+    'exception', 'traceback', 'undefined', 'null pointer', 'segfault',
+    '에러', '버그', '수정', '실패', '오류', '문제',
+];
+const MILESTONE_KEYWORDS = [
+    'complete', 'completed', 'done', 'finished', 'implemented', 'shipped',
+    'deployed', 'released', 'merged', 'integrated', 'working', 'passing',
+    '완료', '구현', '배포', '완성', '됐', '됩니다',
+];
+const TASK_KEYWORDS = [
+    'todo', 'to-do', 'need to', 'should', 'must', 'later', 'next step',
+    'will need', 'plan to', 'going to', 'upcoming', 'pending',
+    '해야', '필요', '다음에', '나중에', '예정',
+];
+const CONTEXT_KEYWORDS = [
+    'uses', 'requires', 'depends on', 'built with', 'runs on', 'configured',
+    'connects to', 'integrates', 'relies on', 'powered by',
+    '사용', '필요', '의존', '기반',
+];
+// ---------------------------------------------------------------------------
+// Stop words — filtered out during key term extraction
+// ---------------------------------------------------------------------------
+const STOP_WORDS = new Set([
+    // English
+    'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+    'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',
+    'should', 'may', 'might', 'shall', 'can', 'need', 'must', 'ought',
+    'to', 'of', 'in', 'on', 'at', 'by', 'for', 'with', 'about', 'as',
+    'into', 'through', 'from', 'up', 'down', 'out', 'off', 'over', 'under',
+    'and', 'or', 'but', 'if', 'then', 'that', 'this', 'it', 'its',
+    'i', 'we', 'you', 'he', 'she', 'they', 'them', 'their', 'our', 'my',
+    'so', 'than', 'when', 'where', 'who', 'which', 'what', 'how', 'why',
+    'not', 'no', 'all', 'each', 'both', 'few', 'more', 'other', 'some',
+    'such', 'only', 'own', 'same', 'also', 'just', 'now', 'very', 'too',
+    // Korean particles
+    '은', '는', '이', '가', '을', '를', '의', '에', '에서', '로', '으로',
+    '와', '과', '도', '만', '가', '께', '한테', '에게', '부터', '까지',
+    '이다', '입니다', '있다', '없다', '이라', '이면', '라면', '같은',
+]);
+// ---------------------------------------------------------------------------
+// Key term extraction
+// ---------------------------------------------------------------------------
+/**
+ * Extract meaningful key terms from text.
+ *
+ * Filters out stop words and short tokens; keeps technical terms,
+ * proper nouns (by capitalization), version numbers, and path-like strings.
+ *
+ * Returns unique terms sorted by appearance order.
+ */
+export function extractKeyTerms(text) {
+    const words = text
+        .split(/\s+/)
+        .map(w => w.replace(/[^\w.\-/]/g, '').trim())
+        .filter(w => w.length >= 2);
+    const seen = new Set();
+    const terms = [];
+    for (const word of words) {
+        const lower = word.toLowerCase();
+        if (STOP_WORDS.has(lower))
+            continue;
+        if (seen.has(lower))
+            continue;
+        seen.add(lower);
+        terms.push(word);
+    }
+    return terms;
+}
+// ---------------------------------------------------------------------------
+// Keyword detection helpers
+// ---------------------------------------------------------------------------
+function containsAny(text, keywords) {
+    const lower = text.toLowerCase();
+    return keywords.some(kw => lower.includes(kw.toLowerCase()));
+}
+/**
+ * Detect the memory type for a given sentence based on keyword presence.
+ * Returns null if no pattern matches.
+ */
+function detectType(sentence) {
+    if (containsAny(sentence, DECISION_KEYWORDS))
+        return 'decision';
+    if (containsAny(sentence, ERROR_KEYWORDS))
+        return 'error';
+    if (containsAny(sentence, MILESTONE_KEYWORDS))
+        return 'milestone';
+    if (containsAny(sentence, TASK_KEYWORDS))
+        return 'task';
+    if (containsAny(sentence, CONTEXT_KEYWORDS))
+        return 'context';
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Conversation splitting
+// ---------------------------------------------------------------------------
+/**
+ * Split a conversation into chunks suitable for observation.
+ *
+ * Splits on:
+ *   - Common turn markers: "User:", "Assistant:", "Human:", "AI:", "System:"
+ *   - Double newlines (paragraph breaks)
+ *
+ * Filters out empty or very short chunks.
+ * Chunks are bounded to 100-500 words each.
+ */
+export function splitConversation(text) {
+    const TURN_PATTERN = /^(?:User|Assistant|Human|AI|System|사용자|어시스턴트):/im;
+    // First try turn-based splitting
+    const turnChunks = text
+        .split(/\n(?=(?:User|Assistant|Human|AI|System|사용자|어시스턴트):)/i)
+        .map(c => c.trim())
+        .filter(c => c.length > 20);
+    if (turnChunks.length > 1) {
+        return turnChunks;
+    }
+    // Fallback: paragraph splitting
+    return text
+        .split(/\n{2,}/)
+        .map(c => c.trim())
+        .filter(c => {
+        const wordCount = c.split(/\s+/).length;
+        return wordCount >= 5 && wordCount <= 600;
+    });
+}
+// ---------------------------------------------------------------------------
+// Core observation
+// ---------------------------------------------------------------------------
+/**
+ * Observe a conversation chunk and extract structured memories from it.
+ *
+ * For each sentence that matches a known pattern (decision, error, milestone,
+ * task, context), a memory is created and stored.
+ *
+ * Returns the text observations extracted and the Memory objects created.
+ */
+export function observe(conversationChunk, project) {
+    // Split into sentences
+    const sentences = conversationChunk
+        .split(/(?<=[.!?])\s+|\n/)
+        .map(s => s.trim())
+        .filter(s => s.length > 15); // skip very short fragments
+    const observations = [];
+    const memories = [];
+    const seen = new Set();
+    for (const sentence of sentences) {
+        const type = detectType(sentence);
+        if (!type)
+            continue;
+        // Normalize to avoid creating duplicate memories in the same chunk
+        const normalized = sentence.toLowerCase().replace(/\s+/g, ' ').trim();
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        // Generate summary (first 80 chars or the sentence itself if shorter)
+        const summary = sentence.length > 80
+            ? sentence.slice(0, 80).trimEnd() + '...'
+            : sentence;
+        // Extract tags from key technical terms
+        const terms = extractKeyTerms(sentence);
+        const tags = terms.slice(0, 8); // cap at 8 tags
+        try {
+            const memory = createMemory({
+                project,
+                content: sentence,
+                summary,
+                type,
+                tags,
+            });
+            observations.push(sentence);
+            memories.push(memory);
+            log.debug('Observed memory', {
+                type,
+                summary: summary.slice(0, 60),
+            });
+        }
+        catch (err) {
+            log.warn('Failed to create observed memory', { error: String(err) });
+        }
+    }
+    // Log the observation entry even if no memories were created
+    if (observations.length > 0) {
+        const entry = {
+            id: randomUUID(),
+            content: conversationChunk.slice(0, 500),
+            extracted_memories: memories.map(m => m.id),
+            source: 'conversation',
+            project,
+            created_at: new Date().toISOString(),
+        };
+        try {
+            createObservation(entry);
+        }
+        catch (err) {
+            log.warn('Failed to log observation entry', { error: String(err) });
+        }
+    }
+    return { observations, memories };
+}
+// ---------------------------------------------------------------------------
+// Reflection
+// ---------------------------------------------------------------------------
+/**
+ * Reflect on a list of observations against the existing memory store.
+ *
+ * Categorizes each observation string as:
+ *   - novel       : not found in existing memories (truly new)
+ *   - reinforcing : confirms an existing memory (we boost that memory)
+ *   - conflicting : appears to contradict an existing memory
+ *
+ * Heuristics:
+ *   - If an existing memory contains most of the same key terms → reinforcing
+ *   - If an existing memory uses contradicting signals (negation patterns) → conflicting
+ *   - Otherwise → novel
+ */
+export async function reflect(newObservations, project) {
+    const novel = [];
+    const reinforcing = [];
+    const conflicting = [];
+    for (const obs of newObservations) {
+        // Search existing memories for similar content
+        const similar = await recallMemoriesAsync(project, obs, { limit: 3 });
+        if (similar.length === 0) {
+            novel.push(obs);
+            continue;
+        }
+        // Check the top result for reinforcement vs conflict
+        const top = similar[0];
+        const topTerms = extractKeyTerms(top.content);
+        const obsTerms = extractKeyTerms(obs);
+        // Count shared key terms
+        const topSet = new Set(topTerms.map(t => t.toLowerCase()));
+        const sharedCount = obsTerms.filter(t => topSet.has(t.toLowerCase())).length;
+        const overlapRatio = sharedCount / Math.max(1, obsTerms.length);
+        if (overlapRatio >= 0.5) {
+            // High overlap → reinforcing — boost the existing memory slightly
+            const boostedDistance = applyAccessBoost(top.distance);
+            try {
+                updateMemoryAccess(top.id);
+                updateMemoryOrbit(top.id, boostedDistance, top.importance, boostedDistance - top.distance);
+            }
+            catch (err) {
+                log.warn('Failed to boost reinforced memory', { id: top.id, error: String(err) });
+            }
+            reinforcing.push(obs);
+        }
+        else {
+            // Check for explicit contradiction signals
+            const obsLower = obs.toLowerCase();
+            const topLower = top.content.toLowerCase();
+            const negationPatterns = [
+                /\bnot\s+\w+/,
+                /\bno longer\b/,
+                /\binstead of\b/,
+                /\breplaced by\b/,
+                /\bswitched from\b/,
+            ];
+            const hasNegation = negationPatterns.some(p => p.test(obsLower) || p.test(topLower));
+            if (hasNegation && overlapRatio >= 0.3) {
+                conflicting.push(obs);
+            }
+            else {
+                novel.push(obs);
+            }
+        }
+    }
+    return { novel, reinforcing, conflicting };
+}
+// ---------------------------------------------------------------------------
+// Full conversation pipeline
+// ---------------------------------------------------------------------------
+/**
+ * Process a full conversation through the observe → reflect pipeline.
+ *
+ * Steps:
+ *   1. Split conversation into chunks.
+ *   2. Run observe() on each chunk to extract memories.
+ *   3. Run reflect() on the extracted observations.
+ *   4. Boost reinforced memories.
+ *   5. Return aggregate statistics.
+ */
+export async function processConversation(conversation, project) {
+    log.info('Processing conversation', { project, length: conversation.length });
+    const chunks = splitConversation(conversation);
+    log.debug('Conversation chunks', { count: chunks.length });
+    const allObservations = [];
+    let memoriesCreated = 0;
+    for (const chunk of chunks) {
+        const { observations, memories } = observe(chunk, project);
+        allObservations.push(...observations);
+        memoriesCreated += memories.length;
+    }
+    // Reflect on all accumulated observations
+    const { novel, reinforcing, conflicting } = await reflect(allObservations, project);
+    // Log a reflection observation entry for the session
+    if (allObservations.length > 0) {
+        const reflectionEntry = {
+            id: randomUUID(),
+            content: `Reflection: ${novel.length} novel, ${reinforcing.length} reinforcing, ${conflicting.length} conflicting`,
+            extracted_memories: [],
+            source: 'reflection',
+            project,
+            created_at: new Date().toISOString(),
+        };
+        try {
+            createObservation(reflectionEntry);
+        }
+        catch {
+            // Non-critical — don't fail the whole pipeline
+        }
+    }
+    log.info('Conversation processed', {
+        project,
+        chunks: chunks.length,
+        memoriesCreated,
+        memoriesReinforced: reinforcing.length,
+        conflictsDetected: conflicting.length,
+        novel: novel.length,
+    });
+    return {
+        memoriesCreated,
+        memoriesReinforced: reinforcing.length,
+        conflictsDetected: conflicting.length,
+    };
+}
+//# sourceMappingURL=observation.js.map

package/dist/engine/observation.js.map

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

package/dist/engine/orbit.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 type { Memory, ImportanceComponents, OrbitChange, StellarConfig } from './types.js';
+import type { MemoryType } from './types.js';
+/**
+ * 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 declare function recencyScore(lastAccessedAt: string | null, createdAt: string, halfLifeHours?: number, memoryType?: MemoryType): number;
+/**
+ * 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 declare function frequencyScore(accessCount: number, saturationPoint?: number): number;
+/**
+ * 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 declare function calculateImportance(memory: Memory, sunText: string, config: StellarConfig): ImportanceComponents;
+/**
+ * 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 declare function importanceToDistance(importance: number): number;
+/**
+ * Inverse of importanceToDistance — derive importance from a given distance.
+ *
+ * Used when a user manually drags a memory to a new orbital position.
+ */
+export declare function distanceToImportance(distance: number): number;
+/**
+ * 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 declare function getOrbitZone(distance: number): string;
+/**
+ * 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 declare function applyAccessBoost(currentDistance: number): number;
+/**
+ * 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 declare function recalculateOrbits(project: string, config: StellarConfig): OrbitChange[];
+//# sourceMappingURL=orbit.d.ts.map