stellar-memory 0.5.0

package/dist/engine/procedural.js

@@ -0,0 +1,259 @@
+/**
+ * procedural.ts — Procedural Memory ("Navigation Rules")
+ *
+ * Procedural memories are behavioral rules learned from patterns in other
+ * memories. They represent "how we do things here" — conventions, workflows,
+ * and recurring solutions extracted from observed repetition.
+ *
+ * Key behaviors:
+ *   - Pattern detection: group memories by tags, find groups with 3+ members
+ *   - Rule creation: procedural memories start with high impact (0.9)
+ *   - Slow decay: procedural memories decay at 30% of the normal rate
+ *   - Sun integration: top 5 rules appear in a dedicated section
+ */
+import { randomUUID, createHash } from 'node:crypto';
+import { getMemoriesByProject, insertMemory } from '../storage/queries.js';
+import { getConfig } from '../utils/config.js';
+import { recencyScore, frequencyScore, importanceToDistance, } from './orbit.js';
+// ---------------------------------------------------------------------------
+// Pattern detection
+// ---------------------------------------------------------------------------
+/**
+ * Group memories by individual tag. Only groups with 3+ memories are kept —
+ * anything below that threshold is not a stable enough pattern to act on.
+ */
+function findRepeatedPatterns(memories) {
+    const tagGroups = new Map();
+    for (const memory of memories) {
+        const tags = Array.isArray(memory.tags) ? memory.tags : [];
+        for (const tag of tags) {
+            if (!tagGroups.has(tag))
+                tagGroups.set(tag, []);
+            tagGroups.get(tag).push(memory);
+        }
+    }
+    // Only keep groups with 3+ memories
+    return new Map([...tagGroups].filter(([, mems]) => mems.length >= 3));
+}
+/**
+ * Extract the most representative keywords from a group of memories.
+ * Uses the most common non-trivial words across all content.
+ */
+function extractGroupKeywords(memories) {
+    const stopWords = new Set([
+        'the', 'a', 'an', 'is', 'it', 'in', 'on', 'at', 'to', 'for',
+        'of', 'and', 'or', 'but', 'with', 'from', 'that', 'this', 'was',
+        'are', 'be', 'been', 'been', 'by', 'as', 'not', 'use', 'used',
+    ]);
+    const wordCount = new Map();
+    for (const mem of memories) {
+        const words = (mem.content + ' ' + mem.summary)
+            .toLowerCase()
+            .split(/[\s,.\-:;()\[\]{}'"!?/\\]+/)
+            .filter(w => w.length > 3 && !stopWords.has(w));
+        for (const w of words) {
+            wordCount.set(w, (wordCount.get(w) ?? 0) + 1);
+        }
+    }
+    return [...wordCount.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([w]) => w);
+}
+/**
+ * Determine if a tag group shares a consistent memory type (majority rules).
+ */
+function dominantType(memories) {
+    const typeCounts = new Map();
+    for (const m of memories) {
+        typeCounts.set(m.type, (typeCounts.get(m.type) ?? 0) + 1);
+    }
+    const dominant = [...typeCounts.entries()].sort((a, b) => b[1] - a[1])[0];
+    if (!dominant)
+        return null;
+    // Return the dominant type only if it represents at least 60% of the group
+    return dominant[1] / memories.length >= 0.6 ? dominant[0] : null;
+}
+/**
+ * Detect patterns in the memory corpus that are strong enough to warrant
+ * a procedural rule.
+ *
+ * Returns one candidate per tag-group that has 3+ members, describing the
+ * observed pattern and suggesting a concrete rule.
+ */
+export function detectProceduralPattern(memories, project) {
+    const groups = findRepeatedPatterns(memories);
+    const results = [];
+    for (const [tag, groupMemories] of groups) {
+        const keywords = extractGroupKeywords(groupMemories);
+        const type = dominantType(groupMemories);
+        const frequency = groupMemories.length;
+        let pattern;
+        let suggestedRule;
+        if (type === 'error') {
+            pattern = `Repeated error pattern tagged "${tag}" (${frequency} occurrences)`;
+            suggestedRule = keywords.length > 0
+                ? `When encountering ${tag}-related issues: check ${keywords.slice(0, 3).join(', ')}`
+                : `When encountering ${tag}-related issues: review established fix pattern`;
+        }
+        else if (type === 'decision') {
+            pattern = `Recurring decision pattern tagged "${tag}" (${frequency} occurrences)`;
+            suggestedRule = keywords.length > 0
+                ? `For ${tag} decisions: consistently apply ${keywords.slice(0, 3).join(', ')}`
+                : `For ${tag} decisions: follow established decision criteria`;
+        }
+        else {
+            pattern = `Repeated context tagged "${tag}" across ${frequency} memories`;
+            suggestedRule = keywords.length > 0
+                ? `In ${project}: ${tag} work consistently involves ${keywords.slice(0, 3).join(', ')}`
+                : `In ${project}: ${tag} is a key recurring theme`;
+        }
+        results.push({ pattern, frequency, suggestedRule });
+    }
+    // Sort by frequency descending — strongest patterns first
+    return results.sort((a, b) => b.frequency - a.frequency);
+}
+// ---------------------------------------------------------------------------
+// Procedural memory creation
+// ---------------------------------------------------------------------------
+/**
+ * Create a procedural memory from a learned rule and its supporting evidence.
+ *
+ * Procedural memories:
+ *   - Use type 'procedural'
+ *   - Start with high impact (0.9) so they orbit close to the sun
+ *   - Include both the rule and the evidence that generated it
+ *   - Are tagged with 'procedural' plus terms extracted from the rule
+ */
+export function createProceduralMemory(rule, evidence, project) {
+    const config = getConfig();
+    const impact = 0.9;
+    const content = `Rule: ${rule}\nEvidence: ${evidence.join(', ')}`;
+    const summary = rule.length > 80 ? rule.slice(0, 80).trimEnd() + '…' : rule;
+    // Extract meaningful terms from the rule text for tags
+    const ruleWords = rule
+        .toLowerCase()
+        .split(/[\s,.:;()\-]+/)
+        .filter(w => w.length > 3);
+    const tags = ['procedural', ...new Set(ruleWords.slice(0, 4))];
+    // Compute initial importance (new procedural starts strong)
+    const now = new Date().toISOString();
+    const rec = recencyScore(null, now, config.decayHalfLifeHours);
+    const freq = frequencyScore(0, config.frequencySaturationPoint);
+    const rel = 0.5; // reasonable default for new procedural memory
+    const total = Math.min(1.0, config.weights.recency * rec +
+        config.weights.frequency * freq +
+        config.weights.impact * impact +
+        config.weights.relevance * rel);
+    const distance = importanceToDistance(total);
+    const contentHash = createHash('sha256').update(content).digest('hex');
+    return insertMemory({
+        id: randomUUID(),
+        project,
+        content,
+        summary,
+        type: 'procedural',
+        tags,
+        distance,
+        importance: total,
+        velocity: 0,
+        impact,
+        access_count: 0,
+        last_accessed_at: null,
+        metadata: { evidence_count: evidence.length },
+        content_hash: contentHash,
+        created_at: now,
+        updated_at: now,
+        deleted_at: null,
+    });
+}
+// ---------------------------------------------------------------------------
+// Retrieval
+// ---------------------------------------------------------------------------
+/**
+ * Get all procedural memories for a project, sorted by importance descending.
+ * These feed into the sun content formatter and the suggest logic.
+ */
+export function getProceduralMemories(project) {
+    const all = getMemoriesByProject(project);
+    return all
+        .filter(m => m.type === 'procedural')
+        .sort((a, b) => b.importance - a.importance);
+}
+// ---------------------------------------------------------------------------
+// Sun content formatting
+// ---------------------------------------------------------------------------
+/**
+ * Format procedural memories as a concise "Navigation Rules" section
+ * suitable for inclusion in the sun resource content.
+ *
+ * At most 5 rules are shown (most important first). Each rule is rendered
+ * as a single numbered line extracted from the content (the "Rule: ..." part).
+ */
+export function formatProceduralSection(memories) {
+    if (memories.length === 0)
+        return '';
+    const top = memories.slice(0, 5);
+    const lines = top.map((m, i) => {
+        // Extract just the rule line from "Rule: ...\nEvidence: ..."
+        const match = m.content.match(/^Rule:\s*(.+?)(\n|$)/);
+        const rule = match ? match[1].trim() : m.summary;
+        return `  ${i + 1}. ${rule}`;
+    });
+    return `Navigation Rules:\n${lines.join('\n')}`;
+}
+// ---------------------------------------------------------------------------
+// Decay multiplier
+// ---------------------------------------------------------------------------
+/**
+ * Procedural memories are hard-won knowledge and should be highly durable.
+ * Return 0.3 so that the effective half-life is ~3.3x longer than normal.
+ *
+ * Used by orbit.ts when calculating recency score for procedural memories:
+ *   effectiveHalfLife = baseHalfLife / getProceduralDecayMultiplier()
+ */
+export function getProceduralDecayMultiplier() {
+    return 0.3;
+}
+// ---------------------------------------------------------------------------
+// Rule suggestion
+// ---------------------------------------------------------------------------
+/**
+ * Analyse the last 50 memories and suggest concrete procedural rules.
+ *
+ * Returns candidates sorted by confidence (highest first). Confidence is
+ * the proportion of the tag-group that supports a consistent pattern.
+ *
+ * Skips rules that already exist as procedural memories (by rule text match).
+ */
+export function suggestRules(recentMemories) {
+    const sample = recentMemories.slice(0, 50);
+    const groups = findRepeatedPatterns(sample);
+    const results = [];
+    for (const [tag, groupMemories] of groups) {
+        const total = groupMemories.length;
+        const type = dominantType(groupMemories);
+        const keywords = extractGroupKeywords(groupMemories);
+        // Confidence: how consistently the group points in one direction
+        const confidence = Math.min(1.0, (total - 2) / 10 + (type ? 0.2 : 0));
+        let rule;
+        if (type === 'error') {
+            rule = keywords.length > 0
+                ? `When facing ${tag} errors: address ${keywords.slice(0, 2).join(' and ')}`
+                : `Document and track ${tag} error resolutions systematically`;
+        }
+        else if (type === 'decision') {
+            rule = keywords.length > 0
+                ? `For ${tag} decisions: apply ${keywords.slice(0, 2).join(' and ')} criteria`
+                : `Maintain consistent decision criteria for ${tag}`;
+        }
+        else {
+            rule = keywords.length > 0
+                ? `${tag} work follows pattern: ${keywords.slice(0, 3).join(', ')}`
+                : `Track ${tag} as a key recurring theme`;
+        }
+        results.push({ rule, confidence, evidence: groupMemories });
+    }
+    return results.sort((a, b) => b.confidence - a.confidence);
+}
+//# sourceMappingURL=procedural.js.map

package/dist/engine/procedural.js.map

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

package/dist/engine/quality.d.ts

@@ -0,0 +1,48 @@
+/**
+ * quality.ts — Memory Quality Scoring ("Planet Grading")
+ *
+ * Grades each memory on four dimensions:
+ *
+ *   - SPECIFICITY   : How much concrete detail does the content contain?
+ *   - ACTIONABILITY : Can someone act on this? Does it say *how*?
+ *   - UNIQUENESS    : Is this information available in other memories?
+ *   - FRESHNESS     : How recently was this memory verified / accessed?
+ *
+ * The overall score is a weighted average. Low-quality memories are pushed
+ * farther from the sun via qualityOrbitAdjustment().
+ *
+ * All scoring is purely algorithmic — no LLM calls.
+ */
+import type { Memory, QualityScore } from './types.js';
+/**
+ * Calculate the quality score for a single memory.
+ *
+ * If allMemories is provided, uniqueness is computed against those peers.
+ * Without it, uniqueness defaults to 0.5 (neutral).
+ */
+export declare function calculateQuality(memory: Memory, allMemories?: Memory[]): QualityScore;
+/**
+ * Score every non-deleted memory in a project and persist the results.
+ * Returns aggregate stats.
+ */
+export declare function scoreAllMemories(project: string): {
+    scored: number;
+    avgQuality: number;
+};
+/**
+ * Generate feedback tips for a newly stored memory.
+ *
+ * Returns null when the memory is already high quality (overall >= 0.7).
+ * Otherwise returns up to 2 actionable tips (in Korean, matching project locale).
+ */
+export declare function getQualityFeedback(quality: QualityScore): string | null;
+/**
+ * Return a distance multiplier based on quality.
+ *
+ * Low-quality memories drift outward to make room for high-quality ones.
+ *   - quality >= 0.7 : 1.0  (no adjustment)
+ *   - quality 0.4–0.7: 1.2  (slightly further)
+ *   - quality < 0.4  : 1.5  (noticeably further)
+ */
+export declare function qualityOrbitAdjustment(quality: number): number;
+//# sourceMappingURL=quality.d.ts.map

package/dist/engine/quality.js

@@ -0,0 +1,245 @@
+/**
+ * quality.ts — Memory Quality Scoring ("Planet Grading")
+ *
+ * Grades each memory on four dimensions:
+ *
+ *   - SPECIFICITY   : How much concrete detail does the content contain?
+ *   - ACTIONABILITY : Can someone act on this? Does it say *how*?
+ *   - UNIQUENESS    : Is this information available in other memories?
+ *   - FRESHNESS     : How recently was this memory verified / accessed?
+ *
+ * The overall score is a weighted average. Low-quality memories are pushed
+ * farther from the sun via qualityOrbitAdjustment().
+ *
+ * All scoring is purely algorithmic — no LLM calls.
+ */
+import { getMemoriesByProject, updateQualityScore } from '../storage/queries.js';
+// ---------------------------------------------------------------------------
+// Named-entity extraction
+// ---------------------------------------------------------------------------
+/**
+ * Extract named entities and technical identifiers from a block of text.
+ *
+ * Looks for:
+ *   - PascalCase / camelCase identifiers
+ *   - kebab-case and snake_case identifiers (length > 4)
+ *   - Semver / version numbers  (v1.2.3, ^2.0, ~3)
+ *   - File paths  (/foo/bar, ./src/index.ts, C:\...)
+ *   - URLs  (http://, https://)
+ */
+function extractNamedEntities(text) {
+    const found = [];
+    // PascalCase / camelCase
+    const camelPascal = text.match(/\b[A-Z][a-zA-Z0-9]{2,}\b|\b[a-z][a-z0-9]*[A-Z][a-zA-Z0-9]*\b/g);
+    if (camelPascal)
+        found.push(...camelPascal);
+    // kebab-case and snake_case (require at least one separator and 2+ segments)
+    const kebabSnake = text.match(/\b[a-z][a-z0-9]*(?:[-_][a-z0-9]+){1,}\b/g);
+    if (kebabSnake)
+        found.push(...kebabSnake.filter(t => t.length > 4));
+    // Version numbers
+    const versions = text.match(/\bv?\d+\.\d+(?:\.\d+)?(?:-[a-z0-9.]+)?\b|\^?\d+\.\d+|\~\d+\.\d+/gi);
+    if (versions)
+        found.push(...versions);
+    // File paths (Unix, Windows, relative)
+    const paths = text.match(/(?:\/[\w.\-]+){2,}|(?:\.\/)[\w.\-/]+|[A-Za-z]:\\[\w.\\\-]+/g);
+    if (paths)
+        found.push(...paths);
+    // URLs
+    const urls = text.match(/https?:\/\/[^\s)>"']+/g);
+    if (urls)
+        found.push(...urls);
+    return [...new Set(found)];
+}
+// ---------------------------------------------------------------------------
+// Specificity
+// ---------------------------------------------------------------------------
+function scoreSpecificity(memory) {
+    const text = memory.content + ' ' + memory.summary;
+    const namedEntities = extractNamedEntities(text);
+    const hasNumbers = /\b\d+(?:\.\d+)?\b/.test(text);
+    const hasPaths = /(?:\/[\w.\-]+){2,}|(?:\.\/)[\w.\-/]+|[A-Za-z]:\\[\w.\\\-]+/.test(text);
+    const contentLength = memory.content.length;
+    return Math.min(1.0, namedEntities.length * 0.1 +
+        (hasNumbers ? 0.2 : 0) +
+        (hasPaths ? 0.2 : 0) +
+        Math.min(0.3, contentLength / 500));
+}
+// ---------------------------------------------------------------------------
+// Actionability
+// ---------------------------------------------------------------------------
+const ACTION_VERBS_EN = [
+    'use', 'run', 'install', 'configure', 'fix', 'add', 'remove', 'update',
+    'set', 'enable', 'disable', 'check', 'ensure', 'avoid', 'always', 'never',
+    'prefer', 'call', 'import', 'export', 'create', 'delete', 'replace',
+];
+const ACTION_VERBS_KO = [
+    '사용', '실행', '설치', '수정', '추가', '삭제', '확인', '설정', '적용',
+    '피해야', '항상', '절대', '선호', '호출', '가져오기', '내보내기',
+];
+const INSTRUCTION_PATTERNS = [
+    /\bstep \d+\b/i,
+    /\b\d+\.\s+[A-Z]/, // numbered list "1. Do something"
+    /\bfirst\b.{0,30}\bthen\b/i,
+    /\bmake sure\b/i,
+    /\bdon['']t\b/i,
+    /\b하면\s/, // Korean conditional
+    /\b다음\s+단계\b/, // Korean "next step"
+];
+const CONDITIONAL_PATTERNS = [
+    /\bif\b.{1,60}\bthen\b/i,
+    /\bwhen\b.{1,60},\s/i,
+    /\bunless\b/i,
+    /\botherwise\b/i,
+    /\b이면\b/, // Korean conditional
+    /\b경우에\b/,
+];
+function scoreActionability(memory) {
+    const text = memory.content.toLowerCase();
+    const hasActionVerbEn = ACTION_VERBS_EN.some(v => text.includes(v));
+    const hasActionVerbKo = ACTION_VERBS_KO.some(v => memory.content.includes(v));
+    const hasActionVerb = hasActionVerbEn || hasActionVerbKo;
+    const hasInstruction = INSTRUCTION_PATTERNS.some(p => p.test(memory.content));
+    const hasConditional = CONDITIONAL_PATTERNS.some(p => p.test(memory.content));
+    return ((hasActionVerb ? 0.4 : 0) +
+        (hasInstruction ? 0.3 : 0) +
+        (hasConditional ? 0.3 : 0));
+}
+// ---------------------------------------------------------------------------
+// Uniqueness
+// ---------------------------------------------------------------------------
+/**
+ * Estimate similarity between two memories using tag overlap and
+ * summary keyword overlap as a lightweight proxy.
+ *
+ * Returns a value in [0, 1] where 1.0 = identical.
+ */
+function estimateSimilarity(a, b) {
+    const tagsA = new Set(Array.isArray(a.tags) ? a.tags : []);
+    const tagsB = new Set(Array.isArray(b.tags) ? b.tags : []);
+    const tagIntersection = [...tagsA].filter(t => tagsB.has(t)).length;
+    const tagUnion = new Set([...tagsA, ...tagsB]).size;
+    const tagOverlap = tagUnion > 0 ? tagIntersection / tagUnion : 0;
+    // Summary keyword overlap
+    const wordsA = new Set(a.summary.toLowerCase().split(/\s+/).filter(w => w.length > 3));
+    const wordsB = new Set(b.summary.toLowerCase().split(/\s+/).filter(w => w.length > 3));
+    const wordIntersection = [...wordsA].filter(w => wordsB.has(w)).length;
+    const wordUnion = new Set([...wordsA, ...wordsB]).size;
+    const wordOverlap = wordUnion > 0 ? wordIntersection / wordUnion : 0;
+    // Weighted combination: tags carry more signal than summary keywords
+    return tagOverlap * 0.6 + wordOverlap * 0.4;
+}
+function scoreUniqueness(memory, allMemories) {
+    if (!allMemories || allMemories.length === 0)
+        return 0.5;
+    const others = allMemories.filter(m => m.id !== memory.id);
+    if (others.length === 0)
+        return 1.0;
+    const maxSimilarity = Math.max(...others.map(o => estimateSimilarity(memory, o)));
+    return Math.max(0.0, 1.0 - maxSimilarity);
+}
+// ---------------------------------------------------------------------------
+// Freshness
+// ---------------------------------------------------------------------------
+function scoreFreshness(memory) {
+    const ref = memory.last_accessed_at ?? memory.created_at;
+    if (!ref)
+        return 0.1;
+    const normalized = /[Zz]$|[+-]\d{2}:\d{2}$/.test(ref) ? ref : ref + 'Z';
+    const refMs = new Date(normalized).getTime();
+    if (isNaN(refMs))
+        return 0.1;
+    const hoursSince = (Date.now() - refMs) / (1000 * 60 * 60);
+    if (hoursSince <= 24)
+        return 1.0;
+    if (hoursSince <= 168)
+        return 0.7; // 1 week
+    if (hoursSince <= 720)
+        return 0.4; // 1 month
+    return 0.2;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Calculate the quality score for a single memory.
+ *
+ * If allMemories is provided, uniqueness is computed against those peers.
+ * Without it, uniqueness defaults to 0.5 (neutral).
+ */
+export function calculateQuality(memory, allMemories) {
+    const specificity = scoreSpecificity(memory);
+    const actionability = scoreActionability(memory);
+    const uniqueness = scoreUniqueness(memory, allMemories);
+    const freshness = scoreFreshness(memory);
+    const overall = 0.30 * specificity +
+        0.25 * actionability +
+        0.25 * uniqueness +
+        0.20 * freshness;
+    return {
+        overall: Math.min(1.0, Math.max(0.0, overall)),
+        specificity: Math.min(1.0, Math.max(0.0, specificity)),
+        actionability: Math.min(1.0, Math.max(0.0, actionability)),
+        uniqueness: Math.min(1.0, Math.max(0.0, uniqueness)),
+        freshness: Math.min(1.0, Math.max(0.0, freshness)),
+    };
+}
+/**
+ * Score every non-deleted memory in a project and persist the results.
+ * Returns aggregate stats.
+ */
+export function scoreAllMemories(project) {
+    const memories = getMemoriesByProject(project);
+    if (memories.length === 0)
+        return { scored: 0, avgQuality: 0 };
+    let totalQuality = 0;
+    for (const memory of memories) {
+        const score = calculateQuality(memory, memories);
+        updateQualityScore(memory.id, score.overall);
+        totalQuality += score.overall;
+    }
+    return {
+        scored: memories.length,
+        avgQuality: totalQuality / memories.length,
+    };
+}
+/**
+ * Generate feedback tips for a newly stored memory.
+ *
+ * Returns null when the memory is already high quality (overall >= 0.7).
+ * Otherwise returns up to 2 actionable tips (in Korean, matching project locale).
+ */
+export function getQualityFeedback(quality) {
+    if (quality.overall >= 0.7)
+        return null;
+    const tips = [];
+    if (quality.specificity < 0.3) {
+        tips.push('이 기억을 더 구체적으로 작성하면 좋겠습니다. 구체적인 이름, 버전, 경로 등을 포함해주세요.');
+    }
+    if (quality.actionability < 0.3) {
+        tips.push('어떻게 행동해야 하는지 구체적인 단계를 포함하면 더 유용합니다.');
+    }
+    if (quality.uniqueness < 0.3) {
+        tips.push('유사한 기억이 이미 존재합니다. 기존 기억을 업데이트하는 것을 고려해주세요.');
+    }
+    if (tips.length === 0)
+        return null;
+    // Return at most 2 tips
+    return tips.slice(0, 2).join(' ');
+}
+/**
+ * Return a distance multiplier based on quality.
+ *
+ * Low-quality memories drift outward to make room for high-quality ones.
+ *   - quality >= 0.7 : 1.0  (no adjustment)
+ *   - quality 0.4–0.7: 1.2  (slightly further)
+ *   - quality < 0.4  : 1.5  (noticeably further)
+ */
+export function qualityOrbitAdjustment(quality) {
+    if (quality >= 0.7)
+        return 1.0;
+    if (quality >= 0.4)
+        return 1.2;
+    return 1.5;
+}
+//# sourceMappingURL=quality.js.map

package/dist/engine/quality.js.map

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

package/dist/engine/repository.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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.
+ */
+import type { Memory, MemoryType, SunState, OrbitChange } from './types.js';
+export interface InsertMemoryData {
+    id?: string;
+    project: string;
+    content: string;
+    summary?: string;
+    type?: MemoryType;
+    tags?: string[];
+    distance?: number;
+    importance?: number;
+    velocity?: number;
+    impact?: number;
+    access_count?: number;
+    last_accessed_at?: string | null;
+    metadata?: Record<string, unknown>;
+    source?: string | null;
+    source_path?: string | null;
+    source_hash?: string | null;
+    content_hash?: string | null;
+    created_at?: string;
+    updated_at?: string;
+    deleted_at?: string | null;
+}
+export interface MemoryRepository {
+    /** Persist a new memory and return the fully-resolved record. */
+    insert(data: InsertMemoryData): Memory;
+    /** Fetch a single memory by its UUID. Returns undefined if not found. */
+    getById(id: string): Memory | undefined;
+    /**
+     * Fetch multiple memories by a list of IDs in a single round-trip.
+     * Soft-deleted memories are excluded.
+     */
+    getByIds(ids: string[]): Memory[];
+    /**
+     * Fetch all non-deleted memories for a project, ordered by distance ASC.
+     */
+    getByProject(project: string): Memory[];
+    /**
+     * Find a non-deleted memory with the given content hash (SHA-256).
+     * Used for content-level deduplication in createMemory().
+     */
+    getByContentHash(project: string, hash: string): Memory | undefined;
+    /**
+     * Full-text search over memories in a project.
+     * Implementations may use FTS5, Postgres full-text, or any other backend.
+     */
+    search(project: string, query: string, limit: number): Memory[];
+    /** Increment access_count and refresh last_accessed_at. */
+    updateAccess(id: string): void;
+    /** Persist new orbital position after a physics recalculation. */
+    updateOrbit(id: string, distance: number, importance: number, velocity: number): void;
+    /** Soft-delete a memory (sets deleted_at; keeps the row for audit trails). */
+    softDelete(id: string): void;
+    /**
+     * Return up to `limit` non-deleted memories for the project ordered by
+     * distance ASC (closest to the sun first).
+     */
+    getNearestMemories(project: string, limit: number): Memory[];
+    /** Retrieve the sun (working context) for a project. */
+    getSunState(project: string): SunState | undefined;
+    /** Insert or update the sun state for a project. */
+    upsertSunState(state: SunState): void;
+    /** Append an orbit-change event for audit / analytics. */
+    insertOrbitLog(change: OrbitChange): void;
+    /** Remove orbit log entries older than `daysOld` days. */
+    cleanupOrbitLog(daysOld: number): void;
+}
+//# sourceMappingURL=repository.d.ts.map