144 lines
4.8 KiB
TypeScript
144 lines
4.8 KiB
TypeScript
/**
|
|
* PersistentSonaCoordinator - SONA learning with RVF persistence
|
|
*
|
|
* Wraps RvfLearningStore to provide an in-memory pattern bank with
|
|
* brute-force cosine similarity, trajectory buffering, EWC tracking,
|
|
* and automatic periodic persistence to disk.
|
|
*
|
|
* This is intentionally decoupled from the ruvector SONA classes:
|
|
* it defines its own compatible types and delegates persistence to
|
|
* RvfLearningStore.
|
|
*
|
|
* @module @claude-flow/memory/persistent-sona
|
|
*/
|
|
import type { PatternRecord, TrajectoryRecord } from './rvf-learning-store.js';
|
|
export interface PersistentSonaConfig {
|
|
/** Path to the RVF learning store file */
|
|
storePath: string;
|
|
/** Cosine similarity threshold for pattern matching (default: 0.85) */
|
|
patternThreshold?: number;
|
|
/** Maximum buffered trajectories before oldest are evicted (default: 1000) */
|
|
maxTrajectoryBuffer?: number;
|
|
/** Auto-persist interval in ms (default: 30000) */
|
|
autoPersistInterval?: number;
|
|
/** Enable verbose logging (default: false) */
|
|
verbose?: boolean;
|
|
}
|
|
/**
|
|
* Coordinates SONA learning with persistent storage.
|
|
*
|
|
* @example
|
|
* ```typescript
|
|
* const sona = new PersistentSonaCoordinator({
|
|
* storePath: './data/sona-learning.rvls',
|
|
* });
|
|
* await sona.initialize();
|
|
*
|
|
* // Store a pattern
|
|
* const id = sona.storePattern('query_response', embedding);
|
|
*
|
|
* // Find similar patterns
|
|
* const matches = sona.findSimilarPatterns(queryEmbedding, 5);
|
|
*
|
|
* // Record a trajectory
|
|
* sona.recordTrajectory({ id: 'traj-1', steps: [...], outcome: 'success', ... });
|
|
*
|
|
* // Periodic background learning
|
|
* const result = sona.runBackgroundLoop();
|
|
*
|
|
* await sona.shutdown();
|
|
* ```
|
|
*/
|
|
export declare class PersistentSonaCoordinator {
|
|
private store;
|
|
private patterns;
|
|
private trajectoryBuffer;
|
|
private ewcState;
|
|
private patternThreshold;
|
|
private maxTrajectoryBuffer;
|
|
private verbose;
|
|
private initialized;
|
|
constructor(config: PersistentSonaConfig);
|
|
/**
|
|
* Initialize by loading persisted state from the RVF store.
|
|
*/
|
|
initialize(): Promise<void>;
|
|
/**
|
|
* Store a new pattern and return its ID.
|
|
*
|
|
* @param type - Pattern type (e.g. 'query_response', 'routing')
|
|
* @param embedding - The pattern embedding vector
|
|
* @param metadata - Optional extra metadata (currently unused, reserved)
|
|
* @returns The generated pattern ID
|
|
*/
|
|
storePattern(type: string, embedding: number[], metadata?: Record<string, unknown>): string;
|
|
/**
|
|
* Find the k most similar patterns above the configured threshold.
|
|
* Uses brute-force cosine similarity (suitable for small pattern sets).
|
|
*/
|
|
findSimilarPatterns(embedding: number[], k?: number): PatternRecord[];
|
|
/**
|
|
* Record a pattern usage outcome. Updates the success rate using an
|
|
* exponential moving average (alpha = 0.1).
|
|
*/
|
|
recordPatternUsage(patternId: string, success: boolean): void;
|
|
/**
|
|
* Remove patterns that have low success rates after sufficient usage.
|
|
*
|
|
* @returns The number of patterns pruned
|
|
*/
|
|
prunePatterns(minSuccessRate?: number, minUseCount?: number): number;
|
|
/**
|
|
* Buffer a completed trajectory for later processing.
|
|
* When the buffer exceeds maxTrajectoryBuffer, the oldest entries
|
|
* are evicted.
|
|
*/
|
|
recordTrajectory(trajectory: TrajectoryRecord): void;
|
|
/**
|
|
* Process buffered trajectories to extract new patterns.
|
|
* Successful and partial trajectories are mined for high-confidence
|
|
* steps; new patterns are stored if they are sufficiently different
|
|
* from existing ones.
|
|
*
|
|
* After processing, the trajectory buffer is cleared and low-performing
|
|
* patterns are pruned.
|
|
*
|
|
* @returns Summary of the learning pass
|
|
*/
|
|
runBackgroundLoop(): {
|
|
patternsLearned: number;
|
|
trajectoriesProcessed: number;
|
|
};
|
|
/**
|
|
* Flush current in-memory state to the RVF store on disk.
|
|
*/
|
|
persist(): Promise<void>;
|
|
/**
|
|
* Persist state and shut down the store.
|
|
*/
|
|
shutdown(): Promise<void>;
|
|
/**
|
|
* Return a summary of the coordinator's current state.
|
|
*/
|
|
getStats(): {
|
|
patterns: number;
|
|
avgSuccessRate: number;
|
|
trajectoriesBuffered: number;
|
|
ewcTasksLearned: number;
|
|
};
|
|
/**
|
|
* Extract patterns from a trajectory's high-confidence steps.
|
|
* A step produces a new pattern only if no sufficiently similar
|
|
* pattern already exists.
|
|
*/
|
|
private extractPatternsFromTrajectory;
|
|
/**
|
|
* Deterministic hash-based embedding for pattern extraction.
|
|
* This is a lightweight stand-in for a real embedding model,
|
|
* matching the approach used in SonaCoordinator.
|
|
*/
|
|
private createHashEmbedding;
|
|
private ensureInitialized;
|
|
private log;
|
|
}
|
|
//# sourceMappingURL=persistent-sona.d.ts.map
|