agent-working-memory 0.3.0

package/dist/storage/sqlite.d.ts

@@ -0,0 +1,116 @@
+/**
+ * SQLite storage layer — persistence for engrams, associations, and eval events.
+ *
+ * Uses better-sqlite3 for synchronous, fast, embedded storage.
+ * FTS5 provides BM25 full-text search for the activation pipeline.
+ */
+import type { Engram, EngramCreate, EngramStage, Association, AssociationType, SearchQuery, ActivationEvent, StagingEvent, Episode, TaskStatus, TaskPriority, ConsciousState, CheckpointRow } from '../types/index.js';
+export declare class EngramStore {
+    private db;
+    constructor(dbPath?: string);
+    private init;
+    createEngram(input: EngramCreate): Engram;
+    getEngram(id: string): Engram | null;
+    getEngramsByAgent(agentId: string, stage?: EngramStage, includeRetracted?: boolean): Engram[];
+    touchEngram(id: string): void;
+    updateStage(id: string, stage: EngramStage): void;
+    updateConfidence(id: string, confidence: number): void;
+    updateEmbedding(id: string, embedding: number[]): void;
+    retractEngram(id: string, retractedBy: string | null): void;
+    deleteEngram(id: string): void;
+    /**
+     * Time warp — shift all timestamps backward by ms milliseconds.
+     * Used for testing time-dependent behavior (decay, forgetting).
+     * Returns count of records shifted.
+     */
+    timeWarp(agentId: string, ms: number): number;
+    searchBM25(agentId: string, query: string, limit?: number): Engram[];
+    /**
+     * BM25 search returning rank scores alongside engrams.
+     * FTS5 rank is negative (lower = better match).
+     * We normalize to 0-1 where higher = better.
+     */
+    searchBM25WithRank(agentId: string, query: string, limit?: number): {
+        engram: Engram;
+        bm25Score: number;
+    }[];
+    search(query: SearchQuery): Engram[];
+    /**
+     * Get the most recently created engram for an agent (for temporal adjacency edges).
+     */
+    getLatestEngram(agentId: string, excludeId?: string): Engram | null;
+    updateTaskStatus(id: string, status: TaskStatus): void;
+    updateTaskPriority(id: string, priority: TaskPriority): void;
+    updateBlockedBy(id: string, blockedBy: string | null): void;
+    /**
+     * Get tasks for an agent, optionally filtered by status.
+     * Results ordered by priority (urgent > high > medium > low), then creation date.
+     */
+    getTasks(agentId: string, status?: TaskStatus): Engram[];
+    /**
+     * Get the next actionable task — highest priority that's not blocked or done.
+     */
+    getNextTask(agentId: string): Engram | null;
+    upsertAssociation(fromId: string, toId: string, weight: number, type?: AssociationType, confidence?: number): Association;
+    getAssociation(fromId: string, toId: string): Association | null;
+    getAssociationsFor(engramId: string): Association[];
+    countAssociationsFor(engramId: string): number;
+    getWeakestAssociation(engramId: string): Association | null;
+    deleteAssociation(id: string): void;
+    getAllAssociations(agentId: string): Association[];
+    getEvictionCandidates(agentId: string, limit: number): Engram[];
+    getActiveCount(agentId: string): number;
+    getStagingCount(agentId: string): number;
+    getExpiredStaging(): Engram[];
+    logActivationEvent(event: ActivationEvent): void;
+    logStagingEvent(event: StagingEvent): void;
+    logRetrievalFeedback(activationEventId: string | null, engramId: string, useful: boolean, context: string): void;
+    getRetrievalPrecision(agentId: string, windowHours?: number): number;
+    getStagingMetrics(agentId: string): {
+        promoted: number;
+        discarded: number;
+        expired: number;
+    };
+    getActivationStats(agentId: string, windowHours?: number): {
+        count: number;
+        avgLatencyMs: number;
+        p95LatencyMs: number;
+    };
+    getConsolidatedCount(agentId: string): number;
+    private rowToEngram;
+    private rowToAssociation;
+    createEpisode(input: {
+        agentId: string;
+        label: string;
+        embedding?: number[];
+    }): Episode;
+    getEpisode(id: string): Episode | null;
+    getEpisodesByAgent(agentId: string): Episode[];
+    getActiveEpisode(agentId: string, windowMs?: number): Episode | null;
+    addEngramToEpisode(engramId: string, episodeId: string): void;
+    getEngramsByEpisode(episodeId: string): Engram[];
+    updateEpisodeEmbedding(id: string, embedding: number[]): void;
+    getEpisodeCount(agentId: string): number;
+    private rowToEpisode;
+    /**
+     * Find engrams whose tags contain any of the given tag values.
+     * Used for entity-bridge retrieval: given entity tags from top results,
+     * find other engrams mentioning the same entities.
+     */
+    findEngramsByTags(agentId: string, tags: string[], excludeIds?: Set<string>): Engram[];
+    updateAutoCheckpointWrite(agentId: string, engramId: string): void;
+    updateAutoCheckpointRecall(agentId: string, context: string, engramIds: string[]): void;
+    touchActivity(agentId: string): void;
+    saveCheckpoint(agentId: string, state: ConsciousState): void;
+    getCheckpoint(agentId: string): CheckpointRow | null;
+    markConsolidation(agentId: string, mini: boolean): void;
+    getActiveAgents(): Array<{
+        agentId: string;
+        lastActivityAt: Date;
+        writeCount: number;
+        recallCount: number;
+        lastConsolidationAt: Date | null;
+    }>;
+    close(): void;
+}
+//# sourceMappingURL=sqlite.d.ts.map

package/dist/storage/sqlite.d.ts.map

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