pulseed 0.0.1 → 0.1.0

package/dist/knowledge/memory-index.js

@@ -0,0 +1,134 @@
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import { z } from "zod";
+import { LessonEntrySchema, MemoryIndexSchema, } from "../types/memory-lifecycle.js";
+import { atomicWriteAsync, readJsonFileAsync, generateId } from "./memory-persistence.js";
+// ─── Index management ───
+export async function initializeIndex(memoryDir, layer) {
+    const indexPath = path.join(memoryDir, layer, "index.json");
+    try {
+        await fsp.access(indexPath);
+    }
+    catch {
+        const emptyIndex = MemoryIndexSchema.parse({
+            version: 1,
+            last_updated: new Date().toISOString(),
+            entries: [],
+        });
+        await fsp.mkdir(path.dirname(indexPath), { recursive: true });
+        await atomicWriteAsync(indexPath, emptyIndex);
+    }
+}
+export async function loadIndex(memoryDir, layer) {
+    const indexPath = path.join(memoryDir, layer, "index.json");
+    const raw = await readJsonFileAsync(indexPath, MemoryIndexSchema);
+    if (raw === null) {
+        return MemoryIndexSchema.parse({
+            version: 1,
+            last_updated: new Date().toISOString(),
+            entries: [],
+        });
+    }
+    return raw;
+}
+export async function saveIndex(memoryDir, layer, index) {
+    const indexPath = path.join(memoryDir, layer, "index.json");
+    try {
+        await fsp.mkdir(path.dirname(indexPath), { recursive: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+    const updated = MemoryIndexSchema.parse({
+        ...index,
+        last_updated: new Date().toISOString(),
+    });
+    await atomicWriteAsync(indexPath, updated);
+}
+export async function updateIndex(memoryDir, layer, entry) {
+    const index = await loadIndex(memoryDir, layer);
+    index.entries.push(entry);
+    await saveIndex(memoryDir, layer, index);
+}
+export async function removeFromIndex(memoryDir, layer, entryIds) {
+    const index = await loadIndex(memoryDir, layer);
+    index.entries = index.entries.filter((ie) => !entryIds.has(ie.entry_id));
+    await saveIndex(memoryDir, layer, index);
+}
+export async function removeGoalFromIndex(memoryDir, layer, goalId) {
+    const index = await loadIndex(memoryDir, layer);
+    index.entries = index.entries.filter((ie) => ie.goal_id !== goalId);
+    await saveIndex(memoryDir, layer, index);
+}
+export async function touchIndexEntry(memoryDir, layer, indexId) {
+    const index = await loadIndex(memoryDir, layer);
+    const now = new Date().toISOString();
+    const updated = index.entries.map((ie) => {
+        if (ie.id === indexId) {
+            return { ...ie, last_accessed: now, access_count: ie.access_count + 1 };
+        }
+        return ie;
+    });
+    await saveIndex(memoryDir, layer, { ...index, entries: updated });
+}
+export async function archiveOldestLongTermEntries(memoryDir) {
+    const index = await loadIndex(memoryDir, "long-term");
+    // Sort by last_accessed ascending (oldest first)
+    const sorted = [...index.entries].sort((a, b) => new Date(a.last_accessed).getTime() -
+        new Date(b.last_accessed).getTime());
+    // Archive oldest 10% of entries
+    const archiveCount = Math.max(1, Math.floor(sorted.length * 0.1));
+    const toArchive = sorted.slice(0, archiveCount);
+    const toArchiveIds = new Set(toArchive.map((ie) => ie.entry_id));
+    // Remove from active index
+    index.entries = index.entries.filter((ie) => !toArchiveIds.has(ie.entry_id));
+    await saveIndex(memoryDir, "long-term", index);
+}
+// ─── Lesson storage ───
+export async function storeLessonsLongTerm(memoryDir, goalId, lessons, sourceEntries) {
+    // 1. Store by-goal
+    const byGoalPath = path.join(memoryDir, "long-term", "lessons", "by-goal", `${goalId}.json`);
+    const existingByGoal = (await readJsonFileAsync(byGoalPath, z.array(LessonEntrySchema))) ?? [];
+    await atomicWriteAsync(byGoalPath, [...existingByGoal, ...lessons]);
+    // 2. Store by-dimension (for each unique dimension in source entries)
+    const allDimensions = new Set(sourceEntries.flatMap((e) => e.dimensions));
+    for (const dim of allDimensions) {
+        if (!dim)
+            continue;
+        const byDimPath = path.join(memoryDir, "long-term", "lessons", "by-dimension", `${dim}.json`);
+        const existingByDim = (await readJsonFileAsync(byDimPath, z.array(LessonEntrySchema))) ?? [];
+        // Store lessons that have this dimension's tag or are from these source entries
+        const relevantLessons = lessons.filter((l) => l.relevance_tags.includes(dim) ||
+            l.relevance_tags.length === 0 // include all if no tags
+        );
+        if (relevantLessons.length > 0) {
+            await atomicWriteAsync(byDimPath, [...existingByDim, ...relevantLessons]);
+        }
+    }
+    // 3. Store in global (all lessons are cross-goal knowledge)
+    const globalPath = path.join(memoryDir, "long-term", "lessons", "global.json");
+    const existingGlobal = (await readJsonFileAsync(globalPath, z.array(LessonEntrySchema))) ?? [];
+    await atomicWriteAsync(globalPath, [...existingGlobal, ...lessons]);
+    // 4. Update long-term index
+    const now = new Date().toISOString();
+    for (const lesson of lessons) {
+        await updateIndex(memoryDir, "long-term", {
+            id: generateId("ltidx"),
+            goal_id: goalId,
+            dimensions: sourceEntries
+                .filter((e) => lesson.source_loops.includes(`loop_${e.loop_number}`))
+                .flatMap((e) => e.dimensions),
+            tags: lesson.relevance_tags,
+            timestamp: lesson.extracted_at,
+            data_file: path.join("lessons", "by-goal", `${goalId}.json`),
+            entry_id: lesson.lesson_id,
+            last_accessed: now,
+            access_count: 0,
+            embedding_id: null,
+            memory_tier: "recall",
+        });
+    }
+}
+//# sourceMappingURL=memory-index.js.map

package/dist/knowledge/memory-index.js.map

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

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

@@ -0,0 +1,169 @@
+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";
+import type { IDriveScorer } from "./drive-score-adapter.js";
+export type { IDriveScorer } from "./drive-score-adapter.js";
+export { DriveScoreAdapter } from "./drive-score-adapter.js";
+/**
+ * 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);
+    private get compressionDeps();
+    private get selectionDeps();
+    /** Create directory structure for memory storage */
+    initializeDirectories(): Promise<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[];
+    }): Promise<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): Promise<{
+        shortTerm: ShortTermEntry[];
+        lessons: LessonEntry[];
+    }>;
+    /**
+     * Tier-aware variant of selectForWorkingMemory.
+     * Passes satisfiedDimensions, highDissatisfactionDimensions, and maxDissatisfaction
+     * to enable core↔recall promotion/demotion and dynamic budget allocation.
+     */
+    selectForWorkingMemoryTierAware(goalId: string, dimensions: string[], tags: string[], maxEntries: number, activeGoalIds: string[], completedGoalIds: string[], satisfiedDimensions: string[], highDissatisfactionDimensions: string[], maxDissatisfaction: number): Promise<{
+        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): Promise<StatisticalSummary | null>;
+    /**
+     * Run garbage collection to enforce size limits.
+     * Short-term: 10MB per goal (default). Long-term: 100MB total (default).
+     */
+    runGarbageCollection(): Promise<void>;
+}
+//# sourceMappingURL=memory-lifecycle.d.ts.map

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

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