gnosys 4.0.0

package/dist/lib/lock.js

@@ -0,0 +1,145 @@
+/**
+ * Gnosys Lock — File-level locking for concurrent write safety.
+ *
+ * Prevents multiple agents (or agent + maintenance) from corrupting
+ * active markdown files during simultaneous writes. Uses a simple
+ * .gnosys/.config/write.lock file with PID tracking.
+ *
+ * Design: advisory lock with timeout + stale lock detection.
+ */
+import fs from "fs";
+import path from "path";
+const LOCK_FILENAME = "write.lock";
+const LOCK_TIMEOUT_MS = 30_000; // 30 seconds max wait
+const LOCK_POLL_MS = 50; // Poll every 50ms
+const LOCK_STALE_MS = 120_000; // Consider lock stale after 2 minutes
+/**
+ * Acquire a write lock for the given store path.
+ * Returns a release function that MUST be called when done.
+ *
+ * Usage:
+ *   const release = await acquireWriteLock(storePath, "maintain");
+ *   try {
+ *     // ... do writes ...
+ *   } finally {
+ *     release();
+ *   }
+ */
+export async function acquireWriteLock(storePath, operation = "write") {
+    const configDir = path.join(storePath, ".config");
+    const lockPath = path.join(configDir, LOCK_FILENAME);
+    // Ensure .config dir exists
+    try {
+        fs.mkdirSync(configDir, { recursive: true });
+    }
+    catch {
+        // Already exists
+    }
+    const startTime = Date.now();
+    while (true) {
+        // Try to acquire the lock
+        try {
+            // Check for existing lock
+            const existing = readLock(lockPath);
+            if (existing) {
+                // Check if stale (PID dead or too old)
+                if (isLockStale(existing)) {
+                    // Remove stale lock and retry
+                    try {
+                        fs.unlinkSync(lockPath);
+                    }
+                    catch {
+                        // Race condition — another process removed it
+                    }
+                }
+                else {
+                    // Lock is held by another process — wait
+                    if (Date.now() - startTime > LOCK_TIMEOUT_MS) {
+                        throw new Error(`Gnosys write lock timeout after ${LOCK_TIMEOUT_MS}ms. ` +
+                            `Lock held by PID ${existing.pid} for operation "${existing.operation}". ` +
+                            `If this is stale, delete ${lockPath}`);
+                    }
+                    await sleep(LOCK_POLL_MS);
+                    continue;
+                }
+            }
+            // Write lock file atomically
+            const lockInfo = {
+                pid: process.pid,
+                timestamp: Date.now(),
+                operation,
+            };
+            // Use writeFileSync with exclusive flag for atomic creation
+            fs.writeFileSync(lockPath, JSON.stringify(lockInfo), { flag: "wx" });
+            // Lock acquired — return release function
+            return () => {
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch {
+                    // Lock file already removed — that's fine
+                }
+            };
+        }
+        catch (err) {
+            const error = err;
+            if (error.code === "EEXIST") {
+                // Another process created the lock between our check and write
+                if (Date.now() - startTime > LOCK_TIMEOUT_MS) {
+                    throw new Error(`Gnosys write lock timeout after ${LOCK_TIMEOUT_MS}ms. ` +
+                        `Delete ${lockPath} if lock is stale.`);
+                }
+                await sleep(LOCK_POLL_MS);
+                continue;
+            }
+            throw err;
+        }
+    }
+}
+/**
+ * Read the current lock info, or null if no lock exists.
+ */
+function readLock(lockPath) {
+    try {
+        const raw = fs.readFileSync(lockPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a lock is stale (PID dead or too old).
+ */
+function isLockStale(lock) {
+    // Check if lock is too old
+    if (Date.now() - lock.timestamp > LOCK_STALE_MS) {
+        return true;
+    }
+    // Check if PID is still alive
+    try {
+        process.kill(lock.pid, 0); // Signal 0 = check if process exists
+        return false; // Process is alive
+    }
+    catch {
+        return true; // Process is dead
+    }
+}
+/**
+ * Enable WAL mode on a better-sqlite3 database instance.
+ * WAL (Write-Ahead Logging) allows concurrent reads during writes.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function enableWAL(db) {
+    try {
+        db.pragma("journal_mode = WAL");
+        db.pragma("busy_timeout = 5000"); // Wait up to 5s if DB is busy
+    }
+    catch {
+        // WAL not supported or DB not available
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=lock.js.map

package/dist/lib/lock.js.map

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

package/dist/lib/maintenance.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Gnosys Maintenance Engine — Keeps the vault clean and useful forever.
+ *
+ * Features:
+ *   - Duplicate detection (semantic similarity + title overlap)
+ *   - Stale marking (confidence decay based on days since last reinforced)
+ *   - Reinforcement (increment counter when memories are used)
+ *   - Auto-consolidation (LLM-powered merge of similar memories)
+ *
+ * All operations produce safe Git commits with rollback on failure.
+ */
+import { GnosysStore, Memory } from "./store.js";
+import { GnosysConfig } from "./config.js";
+import { GnosysResolver } from "./resolver.js";
+export interface MaintenanceOptions {
+    /** Show what would change without modifying anything */
+    dryRun?: boolean;
+    /** Automatically apply all changes (no interactive prompts) */
+    autoApply?: boolean;
+    /** Progress callback */
+    onProgress?: (step: string, current: number, total: number) => void;
+    /** Log callback */
+    onLog?: (level: "info" | "warn" | "action", message: string) => void;
+}
+export interface DuplicatePair {
+    memoryA: Memory;
+    memoryB: Memory;
+    similarity: number;
+    titleOverlap: number;
+}
+export interface StaleMemory {
+    memory: Memory;
+    originalConfidence: number;
+    decayedConfidence: number;
+    daysSinceReinforced: number;
+}
+export interface MaintenanceReport {
+    /** Total memories scanned */
+    totalMemories: number;
+    /** Duplicate pairs detected */
+    duplicates: DuplicatePair[];
+    /** Memories with decayed confidence below threshold */
+    staleMemories: StaleMemory[];
+    /** Average confidence across all active memories */
+    avgConfidence: number;
+    /** Average decayed confidence */
+    avgDecayedConfidence: number;
+    /** Number of memories that were consolidated */
+    consolidated: number;
+    /** Number of memories with updated decay */
+    decayUpdated: number;
+    /** Number of memories archived in this run */
+    archived: number;
+    /** Total memories in archive after this run */
+    totalArchived: number;
+    /** Actions taken (or that would be taken in dry run) */
+    actions: string[];
+}
+export declare class GnosysMaintenanceEngine {
+    private resolver;
+    private config;
+    private embeddings;
+    private provider;
+    constructor(resolver: GnosysResolver, config?: GnosysConfig);
+    /**
+     * Run the full maintenance cycle.
+     */
+    maintain(options?: MaintenanceOptions): Promise<MaintenanceReport>;
+    /**
+     * Find duplicate pairs using semantic similarity + title overlap.
+     */
+    private detectDuplicates;
+    /**
+     * Calculate decayed confidence for all memories.
+     * Formula: decayed = base_confidence * e^(-lambda * days_since_reinforced)
+     */
+    private calculateDecay;
+    /**
+     * Use LLM to merge two duplicate memories into one.
+     * Creates a new memory that supersedes both.
+     */
+    private consolidatePair;
+    /**
+     * Update a stale memory's confidence to its decayed value.
+     */
+    private updateDecayedConfidence;
+    /**
+     * Reinforce a memory — increment its usage counter and update last_reinforced.
+     * This is a lightweight operation called by search/ask/import.
+     */
+    static reinforce(store: GnosysStore, relativePath: string): Promise<void>;
+    /**
+     * Batch reinforce multiple memories (e.g., all results from a search).
+     * Lightweight — just updates counters, no LLM calls.
+     */
+    static reinforceBatch(store: GnosysStore, relativePaths: string[]): Promise<number>;
+    /**
+     * Archive old/low-confidence memories to archive.db.
+     */
+    private archiveOldMemories;
+    /**
+     * Get a quick health snapshot (used by gnosys doctor).
+     * No LLM calls, no embeddings loading — just frontmatter analysis.
+     */
+    getHealthReport(): Promise<{
+        totalActive: number;
+        totalArchived: number;
+        staleCount: number;
+        avgConfidence: number;
+        avgDecayedConfidence: number;
+        neverReinforced: number;
+        totalReinforcements: number;
+        archiveEligible: number;
+    }>;
+    /**
+     * Load all active (non-superseded, non-archived) memories from all stores.
+     */
+    private loadAllActiveMemories;
+}
+/**
+ * Format a maintenance report as a human-readable string.
+ */
+export declare function formatMaintenanceReport(report: MaintenanceReport): string;
+//# sourceMappingURL=maintenance.d.ts.map

package/dist/lib/maintenance.d.ts.map

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