pulseed 0.1.4 → 0.1.5

package/dist/memory-lifecycle.d.ts

@@ -1,244 +0,0 @@
-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

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