stellar-memory 0.5.0

package/dist/engine/repository.js

@@ -0,0 +1,13 @@
+/**
+ * engine/repository.ts — MemoryRepository abstraction
+ *
+ * Defines the storage contract for memories and sun state.
+ * The engine and use-case layers depend only on this interface,
+ * making the concrete storage backend swappable (SQLite today,
+ * Python v1 or a remote API tomorrow).
+ *
+ * Dependency rule: this file lives in the engine layer and MUST NOT
+ * import from storage/, infrastructure, or framework packages.
+ */
+export {};
+//# sourceMappingURL=repository.js.map

package/dist/engine/repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.js","sourceRoot":"","sources":["../../src/engine/repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/engine/sun.d.ts

@@ -0,0 +1,61 @@
+/**
+ * sun.ts — Sun state management
+ *
+ * The "sun" is the gravitational centre of the memory system: it holds the
+ * current working context (what the AI is doing right now).  Every memory
+ * planet orbits the sun at a distance inversely proportional to its relevance
+ * to the current work.
+ *
+ * Responsibilities:
+ *   - commitToSun  : persist a new work snapshot and create decision memories.
+ *   - getSunContent: produce the formatted MCP resource text within token budget.
+ *   - formatSunContent: pure formatter used by getSunContent and tests.
+ */
+import type { SunState, Memory } from './types.js';
+/**
+ * Get the current sun content formatted for an MCP resource.
+ * Guaranteed to stay under the configured sunTokenBudget.
+ */
+export declare function getSunContent(project: string): string;
+/**
+ * Update the sun state from a commit.
+ *
+ * Steps:
+ *   1. Fetch or initialise sun state for the project.
+ *   2. Merge the incoming data (new fields overwrite old ones).
+ *   3. Auto-create a 'decision' memory planet for each supplied decision.
+ *   4. Count tokens and persist via upsertSunState.
+ */
+export declare function commitToSun(project: string, data: {
+    current_work: string;
+    decisions: string[];
+    next_steps: string[];
+    errors: string[];
+    context?: string;
+}): void;
+/**
+ * Format sun state into readable text for the MCP resource.
+ *
+ * Sections are added in priority order. Each section is checked against the
+ * remaining token budget before being appended (progressive truncation).
+ * This ensures the most critical context always fits regardless of budget.
+ *
+ * New priority order (Corona-aware):
+ *   1. Header
+ *   2. CORE IDENTITY — core zone memories (instant recall, ~40% budget)
+ *   3. WORKING ON (current_work, ~10%)
+ *   4. ACTIVE CONTEXT — near zone memories (~25%)
+ *   5. RECENT DECISIONS / NEXT STEPS / ACTIVE ISSUES (~25%)
+ */
+export declare function formatSunContent(sun: SunState, coreMemories: Memory[], nearMemories: Memory[]): string;
+/**
+ * Automatically commit the sun state from recent memories when the
+ * MCP server process is shutting down.
+ *
+ * This prevents session context from being lost when Claude's process
+ * ends (e.g., SIGTERM from Claude Desktop, pipe close from Claude Code).
+ *
+ * Uses synchronous DB calls only — async is unsafe in exit handlers.
+ */
+export declare function autoCommitOnClose(project: string): void;
+//# sourceMappingURL=sun.d.ts.map

package/dist/engine/sun.js

@@ -0,0 +1,240 @@
+/**
+ * sun.ts — Sun state management
+ *
+ * The "sun" is the gravitational centre of the memory system: it holds the
+ * current working context (what the AI is doing right now).  Every memory
+ * planet orbits the sun at a distance inversely proportional to its relevance
+ * to the current work.
+ *
+ * Responsibilities:
+ *   - commitToSun  : persist a new work snapshot and create decision memories.
+ *   - getSunContent: produce the formatted MCP resource text within token budget.
+ *   - formatSunContent: pure formatter used by getSunContent and tests.
+ */
+import { getSunState, upsertSunState, getRecentMemories, } from '../storage/queries.js';
+import { estimateTokens } from '../utils/tokenizer.js';
+import { getConfig } from '../utils/config.js';
+import { createMemory } from './planet.js';
+import { corona } from './corona.js';
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Get the current sun content formatted for an MCP resource.
+ * Guaranteed to stay under the configured sunTokenBudget.
+ */
+export function getSunContent(project) {
+    const sun = getSunState(project);
+    if (!sun) {
+        return `[STELLAR MEMORY - project: ${project}]\n\nNo memories committed yet. Use stellar_commit to record your current work.`;
+    }
+    // Read from the corona in-memory cache instead of hitting the DB.
+    const coreMemories = corona.getCoreMemories();
+    const nearMemories = corona.getNearMemories();
+    return formatSunContent(sun, coreMemories, nearMemories);
+}
+/**
+ * Update the sun state from a commit.
+ *
+ * Steps:
+ *   1. Fetch or initialise sun state for the project.
+ *   2. Merge the incoming data (new fields overwrite old ones).
+ *   3. Auto-create a 'decision' memory planet for each supplied decision.
+ *   4. Count tokens and persist via upsertSunState.
+ */
+export function commitToSun(project, data) {
+    const config = getConfig();
+    // Persist each decision as its own memory planet so it enters the orbital
+    // system and can be recalled later.
+    for (const decision of data.decisions) {
+        if (decision.trim().length > 0) {
+            createMemory({
+                project,
+                content: decision,
+                type: 'decision',
+            });
+        }
+    }
+    // Build the updated sun state object.
+    const now = new Date().toISOString();
+    const existing = getSunState(project);
+    const updated = {
+        project,
+        content: data.current_work,
+        current_work: data.current_work,
+        recent_decisions: data.decisions,
+        next_steps: data.next_steps,
+        active_errors: data.errors,
+        project_context: data.context ?? (existing?.project_context ?? ''),
+        token_count: 0, // computed below
+        last_commit_at: now,
+        updated_at: now,
+    };
+    // Calculate token usage for the formatted sun content so the consumer can
+    // make informed truncation decisions.
+    const coreMemories = corona.getCoreMemories();
+    const nearMemories = corona.getNearMemories();
+    const formatted = formatSunContent(updated, coreMemories, nearMemories);
+    updated.token_count = estimateTokens(formatted);
+    // Warn in dev if we exceed the budget — the consumer (getSunContent) is
+    // responsible for truncation, but we record the real count here.
+    if (updated.token_count > config.sunTokenBudget) {
+        process.stderr.write(`[sun] token count ${updated.token_count} exceeds budget ${config.sunTokenBudget} for project "${project}"\n`);
+    }
+    upsertSunState(updated);
+}
+// ---------------------------------------------------------------------------
+// Formatter
+// ---------------------------------------------------------------------------
+/**
+ * Format sun state into readable text for the MCP resource.
+ *
+ * Sections are added in priority order. Each section is checked against the
+ * remaining token budget before being appended (progressive truncation).
+ * This ensures the most critical context always fits regardless of budget.
+ *
+ * New priority order (Corona-aware):
+ *   1. Header
+ *   2. CORE IDENTITY — core zone memories (instant recall, ~40% budget)
+ *   3. WORKING ON (current_work, ~10%)
+ *   4. ACTIVE CONTEXT — near zone memories (~25%)
+ *   5. RECENT DECISIONS / NEXT STEPS / ACTIVE ISSUES (~25%)
+ */
+export function formatSunContent(sun, coreMemories, nearMemories) {
+    const config = getConfig();
+    const budget = config.sunTokenBudget;
+    const MAX_CORE_DISPLAY = 5;
+    const MAX_NEAR_DISPLAY = 5;
+    const SUMMARY_LIMIT = 80;
+    /** Truncate summary to SUMMARY_LIMIT characters. */
+    const truncSummary = (s) => s.length > SUMMARY_LIMIT ? s.slice(0, SUMMARY_LIMIT).trimEnd() + '…' : s;
+    // Build candidate sections in priority order.
+    const sections = [];
+    // 1. Header — always included. Add [STALE] warning if last commit > 24h ago.
+    let header = `[STELLAR MEMORY - project: ${sun.project}]`;
+    if (sun.last_commit_at) {
+        const lastCommitMs = new Date(/[Zz]$|[+-]\d{2}:\d{2}$/.test(sun.last_commit_at)
+            ? sun.last_commit_at
+            : sun.last_commit_at + 'Z').getTime();
+        const hoursSince = (Date.now() - lastCommitMs) / (1000 * 60 * 60);
+        if (hoursSince > 24) {
+            header += ` [STALE — last commit ${Math.floor(hoursSince)}h ago. Run commit to refresh.]`;
+        }
+    }
+    sections.push(header);
+    // 2. CORE IDENTITY — core zone memories (distance < 1.0 AU).
+    // Compressed format: [TYPE] summary (no AU distance — saves tokens)
+    if (coreMemories.length > 0) {
+        const displayed = coreMemories.slice(0, MAX_CORE_DISPLAY);
+        const lines = displayed
+            .map(m => `  [${m.type.toUpperCase()}] ${truncSummary(m.summary)}`)
+            .join('\n');
+        const overflow = coreMemories.length > MAX_CORE_DISPLAY
+            ? `\n  (+${coreMemories.length - MAX_CORE_DISPLAY} more)`
+            : '';
+        sections.push(`\nCORE (${coreMemories.length}):\n${lines}${overflow}`);
+    }
+    // 3. Current work.
+    if (sun.current_work && sun.current_work.trim().length > 0) {
+        sections.push(`\nWORKING ON:\n${sun.current_work.trim()}`);
+    }
+    // 4. ACTIVE CONTEXT — near zone memories (1.0-5.0 AU).
+    if (nearMemories.length > 0) {
+        const displayed = nearMemories.slice(0, MAX_NEAR_DISPLAY);
+        const lines = displayed
+            .map(m => `  [${m.type.toUpperCase()}] ${truncSummary(m.summary)}`)
+            .join('\n');
+        const overflow = nearMemories.length > MAX_NEAR_DISPLAY
+            ? `\n  (+${nearMemories.length - MAX_NEAR_DISPLAY} more)`
+            : '';
+        sections.push(`\nNEAR (${nearMemories.length}):\n${lines}${overflow}`);
+    }
+    // 5. Recent decisions (max 3).
+    const decisions = sun.recent_decisions.slice(0, 3);
+    if (decisions.length > 0) {
+        const lines = decisions.map((d, i) => `  ${i + 1}. ${d}`).join('\n');
+        sections.push(`\nRECENT DECISIONS:\n${lines}`);
+    }
+    // 6. Next steps (max 3).
+    const steps = sun.next_steps.slice(0, 3);
+    if (steps.length > 0) {
+        const lines = steps.map((s, i) => `  ${i + 1}. ${s}`).join('\n');
+        sections.push(`\nNEXT STEPS:\n${lines}`);
+    }
+    // 7. Active issues (max 2).
+    const errors = sun.active_errors.slice(0, 2);
+    if (errors.length > 0) {
+        const lines = errors.map((e, i) => `  ${i + 1}. ${e}`).join('\n');
+        sections.push(`\nACTIVE ISSUES:\n${lines}`);
+    }
+    // Progressive truncation: accumulate sections until we hit the token budget.
+    let result = '';
+    for (const section of sections) {
+        const candidate = result + (result.length > 0 ? '\n' : '') + section;
+        if (estimateTokens(candidate) > budget) {
+            // This section would push us over — stop here.
+            break;
+        }
+        result = candidate;
+    }
+    // Always return at least the header even if it alone exceeds the budget
+    // (highly unlikely but handles pathological configs).
+    if (result.length === 0) {
+        result = sections[0] ?? `[STELLAR MEMORY - project: ${sun.project}]`;
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Auto-commit on process exit
+// ---------------------------------------------------------------------------
+/**
+ * Automatically commit the sun state from recent memories when the
+ * MCP server process is shutting down.
+ *
+ * This prevents session context from being lost when Claude's process
+ * ends (e.g., SIGTERM from Claude Desktop, pipe close from Claude Code).
+ *
+ * Uses synchronous DB calls only — async is unsafe in exit handlers.
+ */
+export function autoCommitOnClose(project) {
+    try {
+        const recent = getRecentMemories(project, 3);
+        if (recent.length === 0)
+            return;
+        // Group by type
+        const byType = new Map();
+        for (const m of recent) {
+            const list = byType.get(m.type) ?? [];
+            list.push(m.summary);
+            byType.set(m.type, list);
+        }
+        // Build auto-commit fields
+        const current_work = byType.get('context')?.slice(0, 3).join('; ')
+            ?? byType.get('task')?.slice(0, 3).join('; ')
+            ?? `${recent.length} memories from last session`;
+        const decisions = byType.get('decision')?.slice(0, 5) ?? [];
+        const next_steps = byType.get('task')?.slice(0, 5) ?? [];
+        const errors = byType.get('error')?.slice(0, 3) ?? [];
+        const now = new Date().toISOString();
+        const existing = getSunState(project);
+        const updated = {
+            project,
+            content: current_work,
+            current_work,
+            recent_decisions: decisions,
+            next_steps,
+            active_errors: errors,
+            project_context: existing?.project_context ?? '',
+            token_count: 0,
+            last_commit_at: now,
+            updated_at: now,
+        };
+        upsertSunState(updated);
+        process.stderr.write(`[stellar-memory] Auto-committed sun state on shutdown (${recent.length} recent memories)\n`);
+    }
+    catch (err) {
+        // Exit handler must never throw — silently log and continue
+        process.stderr.write(`[stellar-memory] Auto-commit failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+//# sourceMappingURL=sun.js.map

package/dist/engine/sun.js.map

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

package/dist/engine/temporal.d.ts

@@ -0,0 +1,67 @@
+/**
+ * temporal.ts — Temporal Awareness engine
+ *
+ * Tracks when facts become valid/invalid over time. Memories can have
+ * temporal bounds (valid_from, valid_until) and can supersede each other
+ * when a concept evolves (e.g., "Chose Redis" → "Switched to Valkey").
+ *
+ * All functions are pure (no classes), following the project style.
+ */
+import type { Memory } from './types.js';
+/**
+ * Set temporal validity bounds on a memory.
+ *
+ * - validFrom:  ISO date string. If omitted, the memory is valid from creation.
+ * - validUntil: ISO date string. Setting this marks the fact as no longer current.
+ */
+export declare function setTemporalBounds(memoryId: string, validFrom?: string, validUntil?: string): void;
+/**
+ * Mark oldMemoryId as superseded by newMemoryId.
+ *
+ * Sets the old memory's valid_until to now and records superseded_by.
+ * Uses the existing queries.supersedMemory() helper.
+ */
+export declare function supersedeMemory(oldMemoryId: string, newMemoryId: string): void;
+/**
+ * Return the set of memories that were active at the given timestamp.
+ *
+ * A memory is active if:
+ *   valid_from IS NULL OR valid_from <= timestamp
+ *   AND (valid_until IS NULL OR valid_until > timestamp)
+ *
+ * Results are sorted by importance descending.
+ */
+export declare function getContextAtTime(project: string, timestamp: string): Memory[];
+/**
+ * Follow the superseded_by chain forward from memoryId and also walk
+ * backward to find the earliest ancestor.
+ *
+ * Returns the full lineage in chronological order (oldest first).
+ */
+export declare function getEvolutionChain(memoryId: string): Memory[];
+/**
+ * Detect whether newMemory should supersede an existing memory.
+ *
+ * Heuristics (no LLM required):
+ *   1. Same memory type (especially 'decision')
+ *   2. High keyword overlap (>70% shared key terms)
+ *   3. Content contains a "switch" signal ("switched from", "replaced", "instead of", etc.)
+ *   4. Existing memory has not already been superseded
+ *
+ * Returns the memory that should be superseded, or null.
+ */
+export declare function detectSupersession(newMemory: Memory, existingMemories: Memory[]): Memory | null;
+/**
+ * Build a concise textual summary of temporal state for the sun resource.
+ *
+ * Includes:
+ *   - Count of active vs superseded memories
+ *   - Recent supersession events (last 5)
+ */
+export declare function getTemporalSummary(project: string): string;
+/**
+ * Extract meaningful key terms from lowercased text.
+ * Filters out common stop words and short tokens.
+ */
+export declare function extractKeyTerms(text: string): Set<string>;
+//# sourceMappingURL=temporal.d.ts.map