@project-ava-supernova/core 0.2.71

package/dist/memory/memory-manager.d.ts

@@ -0,0 +1,232 @@
+import type { PlatformMemorySync, SemanticMatch } from './platform-sync.js';
+import type { EmbeddingService } from './embedding-service.js';
+import type { MemoryEntry, MemoryStore, MemorySaveOptions, MemoryRecallOptions, MemoryRecallResult, MemoryStoreSummary, MemoryConsolidationGroup, ProjectBrain } from './types.js';
+import { MemoryGraph } from './graph-engine.js';
+import { ProceduralObserver } from './procedural.js';
+import { AmbientCaptureManager } from './ambient-capture.js';
+export declare class MemoryManager {
+    private readonly globalDir;
+    private readonly projectDir;
+    private sync?;
+    private globalStore;
+    private projectStore;
+    private globalIndex;
+    private projectIndex;
+    /** When true, skip all platform sync — memories stay on disk only. Default: true (local-first). */
+    private localOnly;
+    private graphGlobal;
+    private graphProject;
+    private graphInitialized;
+    private initGraphPromise;
+    private proceduralGlobal;
+    private proceduralProject;
+    private ambientGlobal;
+    private ambientProject;
+    private projectBrainCache;
+    private embeddingService;
+    private embeddingStoreGlobal;
+    private embeddingStoreProject;
+    private readonly SYNC_DEBOUNCE_MS;
+    private readonly syncTimers;
+    private readonly syncInFlight;
+    private readonly syncDirty;
+    constructor(opts: {
+        globalDir: string;
+        projectRoot?: string;
+        sync?: PlatformMemorySync;
+        localOnly?: boolean;
+        embeddingService?: EmbeddingService;
+    });
+    /** Resolves once the v3 graph layer has finished initializing. */
+    private ensureGraphReady;
+    /**
+     * Initialize the v3 graph layer. Creates MemoryGraph instances for
+     * global + project scopes, runs auto-migration from v2 if needed,
+     * and sets up procedural observers + ambient capture managers.
+     */
+    private initGraph;
+    /** Get the project brain brief for session-start injection. */
+    getProjectBrain(): ProjectBrain | null;
+    /** Get the graph instance for a scope (for direct graph operations). */
+    getGraph(scope: 'global' | 'project'): MemoryGraph | null;
+    /** Get the procedural observer for a scope. */
+    getProceduralObserver(scope: 'global' | 'project'): ProceduralObserver | null;
+    /** Get the ambient capture manager for a scope. */
+    getAmbientCapture(scope: 'global' | 'project'): AmbientCaptureManager | null;
+    private embeddingStore;
+    /** Embed a node's content and stash the vector. Background; never throws. */
+    private embedNode;
+    /**
+     * Backfill embeddings for active graph nodes missing a vector, so recall can
+     * span the whole memory (not just newly-saved entries). Resumable (only
+     * fills gaps), batched (flush + yield every N), and bails fast if the
+     * endpoint is down (breaker trips → embed returns null). Fire-and-forget on
+     * init; also callable from maintenance.
+     */
+    runEmbeddingBackfill(signal?: AbortSignal): Promise<void>;
+    /** Run confidence decay + forgetting pass on both graphs. Called on session end. */
+    runMaintenance(): Promise<void>;
+    /** Save all graph state to disk (called at end of session). */
+    saveGraphs(): Promise<void>;
+    /** Load global memory store, migrating from v1 if needed. */
+    loadGlobalStore(): Promise<MemoryStore>;
+    /** Load project memory store, migrating from v1 if needed. */
+    loadProjectStore(): Promise<MemoryStore | null>;
+    /** Load both stores and format for system prompt injection. */
+    loadAll(context?: string, branch?: string): Promise<string>;
+    /** Load global memory as markdown string (v1 compat). */
+    loadGlobalMemory(): Promise<string | null>;
+    /** Load project memory as markdown string (v1 compat). */
+    loadProjectMemory(): Promise<string | null>;
+    /** Overwrite global memory with raw markdown (v1 compat — used by dashboard). */
+    saveGlobalMemory(content: string): Promise<void>;
+    /** Overwrite project memory with raw markdown (v1 compat — used by dashboard). */
+    saveProjectMemory(content: string): Promise<void>;
+    /** Append raw markdown entry (v1 compat). */
+    appendGlobal(entry: string): Promise<void>;
+    /** Append raw markdown entry (v1 compat). */
+    appendProject(entry: string): Promise<void>;
+    /** Save a new memory entry with TF-IDF conflict detection. Returns the saved entry. */
+    saveEntry(opts: MemorySaveOptions): Promise<MemoryEntry>;
+    /** Update an existing memory entry by ID. */
+    updateEntry(scope: 'global' | 'project', id: string, updates: Partial<Pick<MemoryEntry, 'content' | 'category' | 'tags' | 'branch' | 'directoryScope'>>): Promise<MemoryEntry | null>;
+    /** Delete a memory entry by ID. */
+    deleteEntry(scope: 'global' | 'project', id: string): Promise<boolean>;
+    /**
+     * Delete ALL entries from a scope. Permanent.
+     */
+    clearAll(scope: 'global' | 'project'): Promise<void>;
+    /**
+     * Delete ALL entries from ALL scopes — global + current project + all known projects.
+     * Reads the project registry to find every project memory file.
+     */
+    clearEverything(): Promise<void>;
+    /**
+     * Search memories with TF-IDF ranking + temporal relevance scoring.
+     * Falls back to substring for exact matches, then semantic via platform.
+     */
+    recall(opts: MemoryRecallOptions): Promise<MemoryRecallResult[]>;
+    /**
+     * Archive stale entries (not recalled in 90+ days).
+     * Returns the number of entries archived.
+     */
+    archiveStaleEntries(scope: 'global' | 'project'): Promise<number>;
+    /**
+     * Restore an archived entry back to active status.
+     */
+    restoreEntry(scope: 'global' | 'project', id: string): Promise<boolean>;
+    /**
+     * Archive a single entry by ID.
+     */
+    archiveEntry(scope: 'global' | 'project', id: string): Promise<boolean>;
+    /**
+     * Find groups of related entries that could be consolidated.
+     * Uses TF-IDF similarity to cluster entries within the same category.
+     * Returns groups sorted by number of related entries (largest first).
+     */
+    findConsolidationGroups(scope: 'global' | 'project'): MemoryConsolidationGroup[];
+    /**
+     * Get stale entries for a scope (for dashboard review).
+     */
+    getStaleEntries(scope: 'global' | 'project'): Promise<MemoryEntry[]>;
+    /**
+     * Get archived entries for a scope.
+     */
+    getArchivedEntries(scope: 'global' | 'project'): Promise<MemoryEntry[]>;
+    /** Get summary statistics for a store. */
+    getSummary(scope: 'global' | 'project'): Promise<MemoryStoreSummary>;
+    /** Get all entries for a scope (for dashboard display). */
+    getEntries(scope: 'global' | 'project'): Promise<MemoryEntry[]>;
+    /** Get graph stats for the dashboard (v3). */
+    getGraphStats(scope: 'global' | 'project'): {
+        activeNodes: number;
+        archivedNodes: number;
+        edges: number;
+        avgConfidence: number;
+        categories: Record<string, number>;
+        contradictions: number;
+        proceduralPatterns: number;
+        crystallisedPatterns: number;
+    } | null;
+    /** Get contradictions for the dashboard resolution UI (v3). */
+    getContradictions(scope: 'global' | 'project'): Array<{
+        nodeA: MemoryEntry;
+        nodeB: MemoryEntry;
+        similarity: number;
+        edgeId: string;
+    }>;
+    /** Get procedural patterns for the dashboard (v3). */
+    getProceduralPatterns(scope: 'global' | 'project'): import('./types.js').ProceduralPattern[];
+    /** Get file path for a scope (for display). */
+    getPath(scope: 'global' | 'project'): string | null;
+    /**
+     * Pull latest memories from the platform and merge into local store.
+     * Remote entries win conflicts (by updatedAt). Returns count of new/updated entries.
+     */
+    pullLatest(scope: 'global' | 'project'): Promise<number>;
+    /** Invalidate cached stores and TF-IDF indexes. */
+    clearCache(): void;
+    loadRelevantMemories(context: string, limit?: number): Promise<SemanticMatch[]>;
+    private loadStore;
+    private persistStore;
+    /** Rebuild TF-IDF index from a store's entries. */
+    private rebuildIndex;
+    /**
+     * Compute composite relevance score combining TF-IDF match quality,
+     * recency, and recall frequency. Returns 0–1.
+     */
+    private computeRelevance;
+    /** Convert v1 markdown to v2 structured store. */
+    private migrateFromV1;
+    /** Parse markdown content into structured entries. */
+    private markdownToEntries;
+    /**
+     * Fix corrupt entries where content is a JSON store blob.
+     * Replaces them with the actual entries from inside the blob.
+     * Returns true if any entries were fixed.
+     */
+    private cleanBlobEntries;
+    /** Infer a category from content using keyword heuristics. */
+    private inferCategory;
+    /** Find an existing entry that conflicts with new content using TF-IDF similarity. */
+    private findConflict;
+    /** Filter entries to active (non-archived), optionally respecting branch scope. */
+    private filterActive;
+    /** Format entries for system prompt (compact, category-grouped). */
+    private formatEntriesForPrompt;
+    /** Format entries as flat markdown (for v1 compat and human-readable mirror). */
+    private formatEntriesAsMarkdown;
+    /** Check if an entry is stale (not recalled in 90+ days). */
+    private isStale;
+    /** Atomic write with lock: acquire lock → temp file → rename → release. */
+    private writeSafe;
+    /** Set the localOnly flag at runtime (e.g. when user toggles the setting). */
+    setLocalOnly(value: boolean): void;
+    /**
+     * Fire-and-forget sync entries to platform. Never throws.
+     *
+     * Schedules a debounced sync — multiple calls in quick succession (e.g.
+     * the Memory Agent saving 5 entries in a loop) coalesce into a single
+     * sync 2 seconds after the last mutation. This eliminates the 5x parallel
+     * racing-syncs flood that was saturating the client's HTTP connection
+     * pool and stalling the LLM stream.
+     *
+     * The `entries` parameter is intentionally ignored — the actual sync
+     * reads the latest store at execution time so we always push current
+     * state, never stale snapshots.
+     */
+    private syncEntries;
+    /** Coalesce sync calls into a debounced execution per scope. */
+    private scheduleSync;
+    /**
+     * Execute one sync for a scope. If a sync is already in flight, mark the
+     * scope dirty so the running sync schedules another pass when it finishes.
+     * Reads the latest store at execution time so we always push current state.
+     */
+    private runSync;
+    /** Register the current project in the global project registry. */
+    private registerProject;
+    /** Load the project registry — all known project paths. */
+    private loadProjectRegistry;
+}
+//# sourceMappingURL=memory-manager.d.ts.map

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

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