conatus 0.1.0

package/dist/memory-lifecycle.d.ts

@@ -0,0 +1,244 @@
+import type { ILLMClient } from "./llm/llm-client.js";
+import type { IEmbeddingClient } from "./embedding-client.js";
+import type { VectorIndex } from "./vector-index.js";
+import type { ShortTermEntry, LessonEntry, StatisticalSummary, CompressionResult, RetentionConfig, MemoryDataType } from "./types/memory-lifecycle.js";
+/**
+ * Minimal interface for drive-based memory management.
+ * Allows MemoryLifecycleManager to query dissatisfaction scores
+ * without depending on the full DriveScorer module.
+ */
+export interface IDriveScorer {
+    /**
+     * Returns a dissatisfaction score [0, 1+] for a dimension.
+     * Used to determine compression delays.
+     */
+    getDissatisfactionScore(dimension: string): number;
+}
+/**
+ * DriveScoreAdapter adapts DriveScore[] output from DriveScorer
+ * to the IDriveScorer interface expected by MemoryLifecycleManager.
+ *
+ * Usage:
+ *   const adapter = new DriveScoreAdapter();
+ *   // After each drive scoring step in CoreLoop:
+ *   adapter.update(driveScores);
+ *   // MemoryLifecycleManager reads via getDissatisfactionScore()
+ */
+export declare class DriveScoreAdapter implements IDriveScorer {
+    private readonly scores;
+    /**
+     * Replace the stored drive scores with the latest batch.
+     * Each entry must have a dimension_name and dissatisfaction score.
+     */
+    update(driveScores: Array<{
+        dimension_name: string;
+        dissatisfaction: number;
+    }>): void;
+    /**
+     * Returns the stored dissatisfaction score for the given dimension.
+     * Returns 0 if the dimension is unknown (safe default: no delay inflation).
+     */
+    getDissatisfactionScore(dimension: string): number;
+}
+/**
+ * MemoryLifecycleManager handles the 3-tier memory model:
+ *   - Working Memory: view/selection from Short-term + Long-term (1 session lifetime)
+ *   - Short-term Memory: raw data, configurable retention (default: 100 loops)
+ *   - Long-term Memory: compressed lessons + statistics (permanent)
+ *
+ * Directory layout:
+ *   <base>/memory/short-term/goals/<goal_id>/{experience-log,observations,strategies,tasks}.json
+ *   <base>/memory/short-term/index.json
+ *   <base>/memory/long-term/lessons/by-goal/<goal_id>.json
+ *   <base>/memory/long-term/lessons/by-dimension/<dim>.json
+ *   <base>/memory/long-term/lessons/global.json
+ *   <base>/memory/long-term/statistics/<goal_id>.json
+ *   <base>/memory/long-term/index.json
+ *   <base>/memory/archive/<goal_id>/{lessons,statistics}.json
+ */
+export declare class MemoryLifecycleManager {
+    private readonly baseDir;
+    private readonly memoryDir;
+    private readonly llmClient;
+    private readonly config;
+    private readonly embeddingClient?;
+    private readonly vectorIndex?;
+    private readonly driveScorer?;
+    private readonly earlyCompressionCandidates;
+    constructor(baseDir: string, llmClient: ILLMClient, config?: Partial<RetentionConfig>, embeddingClient?: IEmbeddingClient, vectorIndex?: VectorIndex, driveScorer?: IDriveScorer);
+    /** Create directory structure for memory storage */
+    initializeDirectories(): void;
+    /**
+     * Record an entry to short-term memory.
+     * Appends to the appropriate data file and updates the short-term index.
+     */
+    recordToShortTerm(goalId: string, dataType: MemoryDataType, data: Record<string, unknown>, options?: {
+        loopNumber?: number;
+        dimensions?: string[];
+        tags?: string[];
+    }): ShortTermEntry;
+    /**
+     * Compress short-term entries to long-term using LLM-based pattern extraction.
+     * Never deletes short-term data if LLM compression fails.
+     */
+    compressToLongTerm(goalId: string, dataType: MemoryDataType): Promise<CompressionResult>;
+    /**
+     * Select relevant entries for working memory.
+     * Phase 1: tag exact-match + recency sort.
+     * Phase 2 (5.2b): semantic search fallback via VectorIndex if tag results are insufficient.
+     * Phase 2 (5.2c): includes cross-goal lessons (up to 25% of budget).
+     */
+    selectForWorkingMemory(goalId: string, dimensions: string[], tags: string[], maxEntries?: number): {
+        shortTerm: ShortTermEntry[];
+        lessons: LessonEntry[];
+    };
+    /**
+     * Dissatisfaction drive: delay compression up to 2x for high-dissatisfaction dimensions.
+     * For each dimension, if dissatisfaction > 0.7, delay_factor = 1 + dissatisfaction (max 2.0).
+     * Returns map of dimension -> delay_factor.
+     */
+    getCompressionDelay(driveScores: Array<{
+        dimension: string;
+        dissatisfaction: number;
+    }>): Map<string, number>;
+    /**
+     * Deadline drive: boost Working Memory priority up to 30%.
+     * For each dimension, bonus = min(deadline * 0.3, 0.3).
+     * Returns map of dimension -> bonus_factor.
+     */
+    getDeadlineBonus(driveScores: Array<{
+        dimension: string;
+        deadline: number;
+    }>): Map<string, number>;
+    /**
+     * SatisficingJudge hook: mark satisfied dimensions for early compression.
+     * Records these dimensions as candidates for early compression.
+     */
+    markForEarlyCompression(goalId: string, satisfiedDimensions: string[]): void;
+    /**
+     * Return the set of dimensions marked for early compression for a goal.
+     */
+    getEarlyCompressionCandidates(goalId: string): Set<string>;
+    /**
+     * Compute a relevance score for a short-term entry given a context.
+     *
+     * Score = tag_match_ratio * drive_weight * freshness_factor
+     *   - tag_match_ratio  = matching tags / total unique tags (0 if no tags)
+     *   - drive_weight     = DriveScorer dissatisfaction score for first matching
+     *                        dimension (1.0 if no DriveScorer or no dimensions)
+     *   - freshness_factor = Math.exp(-daysSinceCreation / 30)
+     */
+    relevanceScore(entry: ShortTermEntry, context: {
+        goalId: string;
+        dimensions: string[];
+        tags: string[];
+    }): number;
+    /**
+     * Compute the effective retention period for a goal/dimension combination.
+     *
+     * If DriveScorer is available:
+     *   dissatisfaction > 0.7 → retention_period * 2.0
+     *   dissatisfaction > 0.4 → retention_period * 1.5
+     *   otherwise             → retention_period
+     * If no DriveScorer → retention_period (unchanged).
+     */
+    compressionDelay(goalId: string, dimension: string): number;
+    /**
+     * Hook called when the SatisficingJudge determines a dimension is satisfied.
+     * Marks the dimension for early compression if satisfied, clears the mark if not.
+     */
+    onSatisficingJudgment(goalId: string, dimension: string, isSatisfied: boolean): void;
+    /**
+     * Search long-term lessons across ALL goals using semantic search.
+     * Falls back to tag-based global search if VectorIndex is unavailable.
+     *
+     * @param query  - natural language search query
+     * @param topK   - maximum number of lessons to return (default 5)
+     */
+    searchCrossGoalLessons(query: string, topK?: number): Promise<LessonEntry[]>;
+    /**
+     * Semantic variant of selectForWorkingMemory.
+     * Uses VectorIndex.search() to find semantically relevant entries.
+     * Applies deadline bonus to relevance scores.
+     * Falls back to existing sync method if no vectorIndex available.
+     */
+    selectForWorkingMemorySemantic(goalId: string, query: string, dimensions: string[], tags: string[], maxEntries?: number, driveScores?: Array<{
+        dimension: string;
+        dissatisfaction: number;
+        deadline: number;
+    }>): Promise<{
+        shortTerm: ShortTermEntry[];
+        lessons: LessonEntry[];
+    }>;
+    /**
+     * Apply retention policy — check each data type and trigger compression if needed.
+     * Phase 2 (5.2a): uses compressionDelay() per dimension for drive-based retention.
+     */
+    applyRetentionPolicy(goalId: string): Promise<CompressionResult[]>;
+    /**
+     * Handle goal completion or cancellation.
+     * Compresses all remaining short-term data, then archives.
+     */
+    onGoalClose(goalId: string, reason: "completed" | "cancelled"): Promise<void>;
+    /**
+     * Read and return the statistical summary for a goal.
+     */
+    getStatistics(goalId: string): StatisticalSummary | null;
+    /**
+     * Run garbage collection to enforce size limits.
+     * Short-term: 10MB per goal (default). Long-term: 100MB total (default).
+     */
+    runGarbageCollection(): Promise<void>;
+    private initializeIndex;
+    private loadIndex;
+    private saveIndex;
+    private updateIndex;
+    private removeFromIndex;
+    private removeGoalFromIndex;
+    private touchIndexEntry;
+    private archiveOldestLongTermEntries;
+    private storeLessonsLongTerm;
+    private updateStatistics;
+    private mergeTaskStats;
+    private mergeDimStats;
+    private computeTrend;
+    private computePeriod;
+    private compressAllRemainingToLongTerm;
+    private queryLessons;
+    /**
+     * Query lessons from ALL goals except the specified goalId.
+     * Used for cross-goal knowledge transfer in selectForWorkingMemory.
+     */
+    private queryCrossGoalLessons;
+    /**
+     * Call LLM to extract recurring patterns from a set of short-term entries.
+     */
+    private extractPatterns;
+    /**
+     * Call LLM to convert extracted patterns into structured LessonEntry objects.
+     */
+    private distillLessons;
+    /**
+     * Validate compression quality.
+     * MVP check: lesson_count >= failure_count * 0.5
+     */
+    private validateCompressionQuality;
+    private atomicWrite;
+    private readJsonFile;
+    /**
+     * Map MemoryDataType to the corresponding short-term JSON file path.
+     */
+    private getDataFile;
+    private generateId;
+    /**
+     * Compute total size of a directory recursively in bytes.
+     */
+    private getDirectorySize;
+    /**
+     * Get the retention loop limit for a goal, considering goal_type_overrides.
+     * Since goalId does not encode goal type in MVP, use default unless caller
+     * configures an override keyed by goalId prefix.
+     */
+    private getRetentionLimit;
+}
+//# sourceMappingURL=memory-lifecycle.d.ts.map

package/dist/memory-lifecycle.d.ts.map

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