@pellux/goodvibes-sdk 0.18.14 → 0.18.16

package/dist/_internal/platform/state/memory-store-helpers.js

@@ -0,0 +1,149 @@
+export function createSchema(db) {
+    db.run('PRAGMA foreign_keys = ON');
+    db.run(`
+    CREATE TABLE IF NOT EXISTS memory_records (
+      id         TEXT PRIMARY KEY,
+      scope      TEXT NOT NULL DEFAULT 'project',
+      cls        TEXT NOT NULL,
+      summary    TEXT NOT NULL,
+      detail     TEXT,
+      tags       TEXT NOT NULL DEFAULT '[]',
+      provenance TEXT NOT NULL DEFAULT '[]',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+    db.run(`
+    CREATE TABLE IF NOT EXISTS memory_links (
+      from_id  TEXT NOT NULL,
+      to_id    TEXT NOT NULL,
+      relation TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      PRIMARY KEY (from_id, to_id, relation),
+      FOREIGN KEY(from_id) REFERENCES memory_records(id) ON DELETE CASCADE,
+      FOREIGN KEY(to_id) REFERENCES memory_records(id) ON DELETE CASCADE
+    )
+  `);
+    ensureColumn(db, 'memory_records', 'scope TEXT NOT NULL DEFAULT \'project\'', 'scope');
+    ensureColumn(db, 'memory_records', 'review_state TEXT NOT NULL DEFAULT \'fresh\'', 'review_state');
+    ensureColumn(db, 'memory_records', 'confidence INTEGER NOT NULL DEFAULT 60', 'confidence');
+    ensureColumn(db, 'memory_records', 'reviewed_at INTEGER', 'reviewed_at');
+    ensureColumn(db, 'memory_records', 'reviewed_by TEXT', 'reviewed_by');
+    ensureColumn(db, 'memory_records', 'stale_reason TEXT', 'stale_reason');
+    db.run(`CREATE INDEX IF NOT EXISTS idx_memory_cls ON memory_records(cls)`);
+    db.run(`CREATE INDEX IF NOT EXISTS idx_memory_scope ON memory_records(scope)`);
+    db.run(`CREATE INDEX IF NOT EXISTS idx_memory_created ON memory_records(created_at)`);
+}
+export function ensureColumn(db, table, columnSql, columnName) {
+    const rows = db.exec(`PRAGMA table_info(${table})`);
+    const existing = new Set();
+    if (rows[0]) {
+        const nameIndex = rows[0].columns.indexOf('name');
+        for (const value of rows[0].values) {
+            if (nameIndex >= 0) {
+                existing.add(String(value[nameIndex]));
+            }
+        }
+    }
+    if (!existing.has(columnName)) {
+        db.run(`ALTER TABLE ${table} ADD COLUMN ${columnSql}`);
+    }
+}
+export function rowToRecord(columns, values) {
+    const row = Object.fromEntries(columns.map((column, index) => [column, values[index]]));
+    return {
+        id: String(row.id),
+        scope: normalizeScope(row.scope),
+        cls: String(row.cls),
+        summary: String(row.summary),
+        ...(typeof row.detail === 'string' && row.detail.trim() ? { detail: row.detail.trim() } : {}),
+        tags: safeParseJson(row.tags, []),
+        provenance: safeParseJson(row.provenance, []),
+        reviewState: normalizeReviewState(row.review_state),
+        confidence: clampConfidence(row.confidence),
+        ...(typeof row.reviewed_at === 'number' ? { reviewedAt: Number(row.reviewed_at) } : {}),
+        ...(typeof row.reviewed_by === 'string' && row.reviewed_by.trim() ? { reviewedBy: row.reviewed_by.trim() } : {}),
+        ...(typeof row.stale_reason === 'string' && row.stale_reason.trim() ? { staleReason: row.stale_reason.trim() } : {}),
+        createdAt: Number(row.created_at),
+        updatedAt: Number(row.updated_at),
+    };
+}
+export function normalizeReviewState(value) {
+    return value === 'reviewed' || value === 'stale' || value === 'contradicted' ? value : 'fresh';
+}
+export function normalizeScope(value) {
+    return value === 'session' || value === 'team' ? value : 'project';
+}
+export function clampConfidence(value) {
+    const numeric = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(numeric) ? Math.max(0, Math.min(100, Math.round(numeric))) : 60;
+}
+export function isReviewFlagged(record) {
+    return record.reviewState === 'stale' || record.reviewState === 'contradicted';
+}
+export function isReviewCandidate(record) {
+    return record.reviewState === 'fresh'
+        || record.reviewState === 'reviewed'
+        || record.reviewState === 'stale'
+        || record.reviewState === 'contradicted';
+}
+export function reviewQueueScore(record) {
+    let score = 0;
+    if (record.reviewState === 'fresh')
+        score += 40;
+    if (record.reviewState === 'stale')
+        score += 20;
+    if (record.reviewState === 'contradicted')
+        score += 10;
+    score += Math.max(0, 100 - record.confidence);
+    score += Math.min(20, record.tags.length * 3);
+    score += Math.min(20, record.provenance.length * 4);
+    return score;
+}
+export function scoreRecord(record, filter) {
+    let score = record.confidence;
+    if (filter.query) {
+        const query = filter.query.toLowerCase();
+        if (record.summary.toLowerCase().includes(query))
+            score += 30;
+        if (record.detail?.toLowerCase().includes(query))
+            score += 20;
+    }
+    if (filter.semantic)
+        score += 15;
+    if (filter.tags?.length)
+        score += Math.min(25, filter.tags.length * 5);
+    if (isReviewFlagged(record))
+        score -= 20;
+    return score;
+}
+export function recordMatchesPostSqlFilter(record, filter) {
+    if (filter.provenanceKinds?.length) {
+        if (!record.provenance.some((entry) => filter.provenanceKinds.includes(entry.kind)))
+            return false;
+    }
+    if (filter.reviewState) {
+        const states = Array.isArray(filter.reviewState) ? filter.reviewState : [filter.reviewState];
+        if (!states.includes(record.reviewState))
+            return false;
+    }
+    if (filter.staleOnly && !isReviewFlagged(record))
+        return false;
+    return true;
+}
+export function safeParseJson(raw, fallback) {
+    if (typeof raw !== 'string')
+        return fallback;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+export function memoryLink(fromId, toId, relation, createdAt) {
+    return { fromId, toId, relation, createdAt };
+}
+export function memoryDoctorReport(vector, embeddings, checkedAt) {
+    return { vector, embeddings, checkedAt };
+}

package/dist/_internal/platform/state/memory-store.d.ts

@@ -0,0 +1,176 @@
+/**
+ * MemoryStore — project memory substrate.
+ *
+ * Durable, provenance-rich memory for decisions, constraints, incidents, and
+ * patterns. Backed by SQLite via SQLiteStore. Survives process restarts and is
+ * queryable by runtime/panel/context enrichment consumers.
+ *
+ * Provenance links can reference: session, turn, task, event, or file.
+ */
+import { type MemoryVectorStats } from './memory-vector-store.js';
+import { MemoryEmbeddingProviderRegistry, type MemoryEmbeddingDoctorReport } from './memory-embeddings.js';
+export type MemoryClass = 'decision' | 'constraint' | 'incident' | 'pattern' | 'fact' | 'risk' | 'runbook' | 'architecture' | 'ownership';
+export type MemoryScope = 'session' | 'project' | 'team';
+export type MemoryReviewState = 'fresh' | 'reviewed' | 'stale' | 'contradicted';
+export type ProvenanceLinkKind = 'session' | 'turn' | 'task' | 'event' | 'file';
+export interface ProvenanceLink {
+    kind: ProvenanceLinkKind;
+    /** The referenced identifier (session ID, turn number, task ID, event ID, or file path). */
+    ref: string;
+    /** Optional human-readable label. */
+    label?: string;
+}
+export interface MemoryRecord {
+    /** Auto-assigned, unique within the store. */
+    id: string;
+    /** Scope of the record for retrieval and sharing workflows. */
+    scope: MemoryScope;
+    /** Memory class — governs retrieval priority and display grouping. */
+    cls: MemoryClass;
+    /** Brief summary (one sentence). */
+    summary: string;
+    /** Optional expanded detail. */
+    detail?: string;
+    /** Tags for search and grouping. */
+    tags: string[];
+    /** Provenance links back to the source context. */
+    provenance: ProvenanceLink[];
+    /** Operator/state review signal. */
+    reviewState: MemoryReviewState;
+    /** Confidence score from 0-100. Higher means the record is more trusted for retrieval. */
+    confidence: number;
+    /** Last explicit review timestamp, if any. */
+    reviewedAt?: number;
+    /** Reviewer identity, if recorded. */
+    reviewedBy?: string;
+    /** If stale/contradicted, why. */
+    staleReason?: string;
+    /** Creation timestamp (epoch ms). */
+    createdAt: number;
+    /** Last updated timestamp (epoch ms). */
+    updatedAt: number;
+}
+export interface MemoryLink {
+    /** ID of the source record. */
+    fromId: string;
+    /** ID of the target record. */
+    toId: string;
+    /** Human-readable relationship label, e.g. "caused", "supersedes". */
+    relation: string;
+    /** Creation timestamp (epoch ms). */
+    createdAt: number;
+}
+export interface MemorySearchFilter {
+    scope?: MemoryScope;
+    cls?: MemoryClass;
+    tags?: string[];
+    /** Full-text substring match on summary and detail. */
+    query?: string;
+    /** Use the sqlite-vec semantic index for query ranking when available. */
+    semantic?: boolean;
+    /** Return records created after this timestamp. */
+    since?: number;
+    /** Match a specific review state or a small set of states. */
+    reviewState?: MemoryReviewState | MemoryReviewState[];
+    /** Minimum confidence threshold, 0-100. */
+    minConfidence?: number;
+    /** Restrict to records with at least one matching provenance kind. */
+    provenanceKinds?: ProvenanceLinkKind[];
+    /** Convenience flag for review queue retrieval. */
+    staleOnly?: boolean;
+    limit?: number;
+}
+export interface MemoryAddOptions {
+    scope?: MemoryScope;
+    cls: MemoryClass;
+    summary: string;
+    detail?: string;
+    tags?: string[];
+    provenance?: ProvenanceLink[];
+    review?: {
+        state?: MemoryReviewState;
+        confidence?: number;
+        reviewedAt?: number;
+        reviewedBy?: string;
+        staleReason?: string;
+    };
+}
+export interface MemoryReviewPatch {
+    state?: MemoryReviewState;
+    confidence?: number;
+    reviewedBy?: string;
+    staleReason?: string;
+}
+export interface MemoryBundle {
+    schemaVersion: 'v1';
+    exportedAt: number;
+    scope: MemoryScope | 'all';
+    recordCount: number;
+    linkCount: number;
+    records: MemoryRecord[];
+    links: MemoryLink[];
+}
+export interface MemoryImportResult {
+    importedRecords: number;
+    skippedRecords: number;
+    importedLinks: number;
+}
+export interface MemorySemanticSearchResult {
+    record: MemoryRecord;
+    distance: number;
+    similarity: number;
+    score: number;
+}
+export interface MemoryStoreOptions {
+    embeddingRegistry: MemoryEmbeddingProviderRegistry;
+    enableVectorIndex?: boolean;
+    vectorDbPath?: string;
+}
+export interface MemoryDoctorReport {
+    readonly vector: MemoryVectorStats;
+    readonly embeddings: MemoryEmbeddingDoctorReport;
+    readonly checkedAt: number;
+}
+export { MemoryRegistry } from './memory-registry.js';
+export declare class MemoryStore {
+    private sqlite;
+    private vectorIndex;
+    private ready;
+    private rebuildVectorIndexPromise;
+    private readonly embeddingRegistry;
+    constructor(dbPath: string | undefined, options: MemoryStoreOptions);
+    init(): Promise<void>;
+    get isReady(): boolean;
+    /** Add a new memory record. Returns the created record. */
+    add(opts: MemoryAddOptions): Promise<MemoryRecord>;
+    /** Retrieve a single record by ID. */
+    get(id: string): MemoryRecord | null;
+    /** Search records with an optional filter. */
+    search(filter?: MemorySearchFilter): MemoryRecord[];
+    searchSemantic(filter?: MemorySearchFilter): MemorySemanticSearchResult[];
+    reviewQueue(limit?: number): MemoryRecord[];
+    exportBundle(filter?: MemorySearchFilter): MemoryBundle;
+    importBundle(bundle: MemoryBundle): Promise<MemoryImportResult>;
+    /** Create a directed link between two records. */
+    link(fromId: string, toId: string, relation: string): Promise<MemoryLink | null>;
+    /** Get all links where this record is either source or target. */
+    linksFor(id: string): MemoryLink[];
+    /** Update mutable fields of an existing record. */
+    update(id: string, patch: {
+        scope?: MemoryScope;
+        summary?: string;
+        detail?: string;
+        tags?: string[];
+    }): MemoryRecord | null;
+    review(id: string, patch: MemoryReviewPatch): MemoryRecord | null;
+    /** Delete a record and all its links. */
+    delete(id: string): boolean;
+    rebuildVectorIndex(): MemoryVectorStats;
+    rebuildVectorIndexAsync(): Promise<MemoryVectorStats>;
+    vectorStats(): MemoryVectorStats;
+    doctor(): Promise<MemoryDoctorReport>;
+    save(): Promise<boolean>;
+    close(): void;
+    private persist;
+}
+//# sourceMappingURL=memory-store.d.ts.map

package/dist/_internal/platform/state/memory-store.d.ts.map

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