@mem-weave/server 0.2.0

package/dist/db/repositories/memory-repo.js

@@ -0,0 +1,294 @@
+import { randomUUID } from 'node:crypto';
+import { initialStrengthFromImportance, reinforcementBoost, tauFor } from '../../core/decay.js';
+const DEDUP_JACCARD_THRESHOLD = 0.8;
+export class MemoryRepo {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    create(input) {
+        return this.createDetailed(input).memory;
+    }
+    /**
+     * Same as `create`, but also reports whether the insert was a dedup
+     * hit. REST routes that want to show "merged with X" UI should use this.
+     */
+    createDetailed(input) {
+        // ── Dedup gate (server-side, LLM never knows) ─────────────────────────
+        // BM25 against the FTS5 index using title + summary + concepts. Zero
+        // embedding cost. Top-3 candidates are scored by Jaccard similarity on
+        // the concepts set. A hit means "this is a near-duplicate of an
+        // existing memory" → reinforce the existing one instead of inserting
+        // a new row. The existing memory's `last_reinforced_at` bumps, its
+        // `access_count` increments, and if the new content is richer we
+        // upgrade importance + content.
+        const dup = this.findNearDuplicate(input);
+        if (dup) {
+            const reinforced = this.reinforceExisting(dup, input);
+            return { memory: reinforced, deduped: true, reinforcedId: dup.id };
+        }
+        const now = Date.now();
+        const id = randomUUID();
+        const tier = input.importance >= 10 ? 'long' : input.importance >= 7 && input.confidence > 0.75 ? 'medium' : 'short';
+        const strength = initialStrengthFromImportance(input.importance);
+        const tau = tauFor(tier, input.importance);
+        const conceptsJson = JSON.stringify(input.concepts);
+        const filesJson = JSON.stringify(input.files);
+        const conceptsText = input.concepts.join(' ');
+        const tx = this.db.transaction(() => {
+            this.db.prepare(`
+        INSERT INTO memories (
+          id, tenant_id, tier, type, title, content, summary,
+          concepts_json, concepts_text, files_json, importance, confidence,
+          strength, source, scope_level, source_client, source_device_id,
+          source_session_id, tau, access_count, last_accessed_at,
+          last_reinforced_at, last_decay_at, reinforcement_score,
+          promoted_at, created_at, updated_at, deleted_at, eviction_reason
+        ) VALUES (
+          @id, @tenantId, @tier, @type, @title, @content, @summary,
+          @conceptsJson, @conceptsText, @filesJson, @importance, @confidence,
+          @strength, @source, @scopeLevel, @sourceClient, @sourceDeviceId,
+          @sourceSessionId, @tau, 0, NULL, NULL, @now, 0,
+          NULL, @now, @now, NULL, NULL
+        )
+      `).run({ ...input, id, tier, strength, tau, conceptsJson, conceptsText, filesJson, now });
+            const scopeStmt = this.db.prepare(`
+        INSERT INTO memory_scopes (memory_id, tenant_id, key, value, created_at)
+        VALUES (?, ?, ?, ?, ?)
+      `);
+            for (const scope of input.scopes)
+                scopeStmt.run(id, input.tenantId, scope.key, scope.value, now);
+        });
+        tx();
+        const created = this.getById(input.tenantId, id);
+        if (!created)
+            throw new Error(`Failed to create memory ${id}`);
+        return { memory: created, deduped: false };
+    }
+    getById(tenantId, id) {
+        const row = this.db.prepare('SELECT * FROM memories WHERE tenant_id = ? AND id = ? AND deleted_at IS NULL')
+            .get(tenantId, id);
+        if (!row)
+            return null;
+        const scopes = this.db.prepare('SELECT key, value FROM memory_scopes WHERE tenant_id = ? AND memory_id = ? ORDER BY key, value')
+            .all(tenantId, id);
+        return this.mapRow(row, scopes);
+    }
+    recordAccess(input) {
+        const now = Date.now();
+        const id = randomUUID();
+        const boost = reinforcementBoost({
+            usedInContext: input.usedInContext,
+            explicitReference: false,
+            userConfirmed: false
+        });
+        const tx = this.db.transaction(() => {
+            this.db.prepare(`
+        INSERT INTO access_logs (
+          id, tenant_id, memory_id, session_id, device_id,
+          source, query, rank, score, used_in_context, accessed_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(id, input.tenantId, input.memoryId, input.sessionId, input.deviceId, input.source, input.query, input.rank, input.score, input.usedInContext ? 1 : 0, now);
+            this.db.prepare(`
+        UPDATE memories
+        SET access_count = access_count + 1,
+            last_accessed_at = ?,
+            last_reinforced_at = CASE WHEN ? >= 0.1 THEN ? ELSE last_reinforced_at END,
+            reinforcement_score = min(1, reinforcement_score + ?),
+            strength = min(1, strength + ?),
+            updated_at = ?
+        WHERE tenant_id = ? AND id = ?
+      `).run(now, boost, now, boost, boost, now, input.tenantId, input.memoryId);
+        });
+        tx();
+    }
+    // ── internals ────────────────────────────────────────────────────────────
+    /**
+     * Find a near-duplicate of `input` already in the DB. Returns the
+     * candidate memory, or `null` if none qualifies.
+     *
+     * Strategy:
+     *   1. BM25 over `memory_fts` using the input's concepts as the query
+     *      (no embedding cost; FTS5 is < 1ms for a few MB of memories).
+     *      We OR the concepts (any-concept match) so we get a candidate set.
+     *   2. Take top-5 candidates within the same tenant.
+     *   3. For each, compute Jaccard similarity on the concepts set.
+     *   4. If best Jaccard >= DEDUP_JACCARD_THRESHOLD AND same `type`,
+     *      that's a duplicate.
+     *
+     * Why OR not AND on concepts? The new save's concepts might not all
+     * appear in the old memory (e.g. new concept added). We want a
+     * candidate pool to score with Jaccard, not an exact match.
+     * Why not BM25 score alone? FTS5 ranks by term frequency, not by
+     * "this is the same fact". A memory about "TypeScript" would BM25-match
+     * a memory about "TypeScript generics" highly, but they're not duplicates.
+     * Concepts-based Jaccard catches the actual semantic overlap.
+     */
+    findNearDuplicate(input) {
+        // Query with concepts only — title is too noisy. Sanitize to FTS5-safe
+        // tokens (lowercase, only word chars and hyphens/underscores).
+        const queryTokens = input.concepts
+            .map((c) => c.toLowerCase())
+            .filter((t) => t.length > 0 && /^[a-z0-9_-]+$/.test(t));
+        if (queryTokens.length === 0)
+            return null;
+        // OR-join: any concept matching is enough to surface a candidate.
+        const ftsQuery = queryTokens.map((t) => `"${t}"`).join(' OR ');
+        let rows;
+        try {
+            rows = this.db.prepare(`
+        SELECT m.id AS id, m.type AS type, m.concepts_json AS concepts
+        FROM memory_fts f
+        JOIN memories m ON m.rowid = f.rowid
+        WHERE memory_fts MATCH ?
+          AND m.tenant_id = ?
+          AND m.deleted_at IS NULL
+        ORDER BY rank
+        LIMIT 5
+      `).all(ftsQuery, input.tenantId);
+        }
+        catch {
+            // FTS5 syntax error (shouldn't happen with our sanitized query, but
+            // defend anyway). Fall through to "no dedup hit".
+            return null;
+        }
+        if (rows.length === 0)
+            return null;
+        const inputConcepts = new Set(input.concepts.map((c) => c.toLowerCase()));
+        let bestMatch = null;
+        for (const row of rows) {
+            // Type must match — a "fact" is never a duplicate of a "decision".
+            if (row.type !== input.type)
+                continue;
+            const existingConcepts = new Set(JSON.parse(row.concepts).map((c) => c.toLowerCase()));
+            const jaccard = jaccardSimilarity(inputConcepts, existingConcepts);
+            if (jaccard >= DEDUP_JACCARD_THRESHOLD && (!bestMatch || jaccard > bestMatch.score)) {
+                const mem = this.getById(input.tenantId, row.id);
+                if (mem)
+                    bestMatch = { memory: mem, score: jaccard };
+            }
+        }
+        return bestMatch?.memory ?? null;
+    }
+    /**
+     * Bump an existing memory's reinforcement signals and, if the incoming
+     * input carries more information (longer content, higher importance),
+     * upgrade the existing record's content + importance. Returns the
+     * updated memory.
+     *
+     * Writes an `access_logs` row with `source: 'dedup_reinforce'` so the
+     * audit trail is consistent with `recordAccess()` — operators can
+     * see "this memory was reinforced by a dedup hit" the same way they
+     * see regular retrievals.
+     */
+    reinforceExisting(existing, incoming) {
+        const now = Date.now();
+        const boost = reinforcementBoost({
+            usedInContext: true, // LLM just saw it via injection → count as used
+            explicitReference: false,
+            userConfirmed: false
+        });
+        // Decide whether to merge content. If incoming is strictly longer and
+        // has higher importance, upgrade. Otherwise just bump reinforcement
+        // and keep the existing content (it's already good enough).
+        const incomingIsRicher = incoming.content.length > existing.content.length * 1.25 ||
+            incoming.importance > existing.importance;
+        const tx = this.db.transaction(() => {
+            if (incomingIsRicher) {
+                // Merge: take the longer content + the max importance + the union of concepts + files
+                const mergedConcepts = Array.from(new Set([...existing.concepts, ...incoming.concepts]));
+                const mergedFiles = Array.from(new Set([...existing.files, ...incoming.files]));
+                const newImportance = Math.max(existing.importance, incoming.importance);
+                this.db.prepare(`
+          UPDATE memories
+          SET content = ?,
+              concepts_json = ?,
+              concepts_text = ?,
+              files_json = ?,
+              importance = ?,
+              access_count = access_count + 1,
+              last_accessed_at = ?,
+              last_reinforced_at = ?,
+              reinforcement_score = min(1, reinforcement_score + ?),
+              strength = min(1, strength + ?),
+              updated_at = ?
+          WHERE tenant_id = ? AND id = ?
+        `).run(incoming.content, JSON.stringify(mergedConcepts), mergedConcepts.join(' '), JSON.stringify(mergedFiles), newImportance, now, now, boost, boost, now, existing.tenantId, existing.id);
+            }
+            else {
+                this.db.prepare(`
+          UPDATE memories
+          SET access_count = access_count + 1,
+              last_accessed_at = ?,
+              last_reinforced_at = ?,
+              reinforcement_score = min(1, reinforcement_score + ?),
+              strength = min(1, strength + ?),
+              updated_at = ?
+          WHERE tenant_id = ? AND id = ?
+        `).run(now, now, boost, boost, now, existing.tenantId, existing.id);
+            }
+            // Audit log row — same shape as recordAccess() emits, so the
+            // /api/v1/memories/:id/access-logs endpoint surfaces dedup
+            // reinforcements uniformly with retrieval accesses.
+            this.db.prepare(`
+        INSERT INTO access_logs (
+          id, tenant_id, memory_id, session_id, device_id,
+          source, query, rank, score, used_in_context, accessed_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(randomUUID(), existing.tenantId, existing.id, incoming.sourceSessionId, incoming.sourceDeviceId, 'dedup_reinforce', null, null, null, 1, // usedInContext = true (the LLM was about to use it)
+            now);
+        });
+        tx();
+        const updated = this.getById(existing.tenantId, existing.id);
+        if (!updated)
+            throw new Error(`Failed to reinforce memory ${existing.id}`);
+        return updated;
+    }
+    mapRow(row, scopes) {
+        return {
+            id: row.id,
+            tenantId: row.tenant_id,
+            tier: row.tier,
+            type: row.type,
+            title: row.title,
+            content: row.content,
+            summary: row.summary,
+            concepts: JSON.parse(row.concepts_json),
+            files: JSON.parse(row.files_json),
+            importance: row.importance,
+            confidence: row.confidence,
+            strength: row.strength,
+            source: row.source,
+            scopeLevel: row.scope_level,
+            scopes,
+            sourceClient: row.source_client,
+            sourceDeviceId: row.source_device_id,
+            sourceSessionId: row.source_session_id,
+            tau: row.tau,
+            accessCount: row.access_count,
+            lastAccessedAt: row.last_accessed_at,
+            lastReinforcedAt: row.last_reinforced_at,
+            lastDecayAt: row.last_decay_at,
+            reinforcementScore: row.reinforcement_score,
+            promotedAt: row.promoted_at,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+            deletedAt: row.deleted_at,
+            evictionReason: row.eviction_reason
+        };
+    }
+}
+/**
+ * Jaccard similarity: |A ∩ B| / |A ∪ B|. Returns 0 if both sets are empty
+ * (we treat "no concepts" as "not similar to anything").
+ */
+function jaccardSimilarity(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const x of a)
+        if (b.has(x))
+            intersection++;
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}

package/dist/db/repositories/observation-repo.js

@@ -0,0 +1,65 @@
+import { randomUUID } from 'node:crypto';
+export class ObservationRepo {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    create(input) {
+        const id = randomUUID();
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO observations (id, session_id, tenant_id, hook_type, tool_name, tool_input, tool_output, timestamp, memory_id, processed)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0)
+    `).run(id, input.sessionId, input.tenantId, input.hookType, input.toolName, input.toolInput, input.toolOutput, now, input.memoryId);
+        return {
+            id,
+            sessionId: input.sessionId,
+            tenantId: input.tenantId,
+            hookType: input.hookType,
+            toolName: input.toolName,
+            toolInput: input.toolInput,
+            toolOutput: input.toolOutput,
+            timestamp: now,
+            memoryId: input.memoryId,
+            processed: false
+        };
+    }
+    getById(tenantId, id) {
+        const row = this.db.prepare(`
+      SELECT * FROM observations WHERE tenant_id = ? AND id = ?
+    `).get(tenantId, id);
+        if (!row)
+            return null;
+        return this.mapRow(row);
+    }
+    listUnprocessed(tenantId, limit) {
+        if (limit <= 0)
+            return [];
+        const rows = this.db.prepare(`
+      SELECT * FROM observations
+      WHERE tenant_id = ? AND processed = 0
+      ORDER BY timestamp ASC, rowid ASC
+      LIMIT ?
+    `).all(tenantId, limit);
+        return rows.map((r) => this.mapRow(r));
+    }
+    markProcessed(id, memoryId) {
+        this.db.prepare(`
+      UPDATE observations SET processed = 1, memory_id = ? WHERE id = ?
+    `).run(memoryId, id);
+    }
+    mapRow(row) {
+        return {
+            id: row.id,
+            sessionId: row.session_id,
+            tenantId: row.tenant_id,
+            hookType: row.hook_type,
+            toolName: row.tool_name,
+            toolInput: row.tool_input,
+            toolOutput: row.tool_output,
+            timestamp: row.timestamp,
+            memoryId: row.memory_id,
+            processed: row.processed === 1
+        };
+    }
+}

package/dist/db/repositories/session-repo.js

@@ -0,0 +1,81 @@
+import { randomUUID } from 'node:crypto';
+export class SessionRepo {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    create(input) {
+        const id = randomUUID();
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO sessions (id, tenant_id, device_id, source, title, summary, started_at, ended_at, observation_count)
+      VALUES (?, ?, ?, ?, ?, NULL, ?, NULL, 0)
+    `).run(id, input.tenantId, input.deviceId, input.source, input.title, now);
+        return {
+            id,
+            tenantId: input.tenantId,
+            deviceId: input.deviceId,
+            source: input.source,
+            title: input.title,
+            summary: null,
+            startedAt: now,
+            endedAt: null,
+            observationCount: 0
+        };
+    }
+    getById(tenantId, id) {
+        const row = this.db.prepare(`
+      SELECT * FROM sessions WHERE tenant_id = ? AND id = ?
+    `).get(tenantId, id);
+        if (!row)
+            return null;
+        return this.mapRow(row);
+    }
+    listRecent(tenantId, limit) {
+        if (limit <= 0)
+            return [];
+        const rows = this.db.prepare(`
+      SELECT * FROM sessions
+      WHERE tenant_id = ?
+      ORDER BY started_at DESC, rowid DESC
+      LIMIT ?
+    `).all(tenantId, limit);
+        return rows.map((r) => this.mapRow(r));
+    }
+    end(id) {
+        this.db.prepare(`
+      UPDATE sessions SET ended_at = ? WHERE id = ?
+    `).run(Date.now(), id);
+    }
+    listMemories(tenantId, sessionId) {
+        const rows = this.db.prepare(`
+      SELECT id, type, tier, title, summary, strength, importance, created_at
+      FROM memories
+      WHERE tenant_id = ? AND source_session_id = ? AND deleted_at IS NULL
+      ORDER BY created_at DESC
+    `).all(tenantId, sessionId);
+        return rows.map((r) => ({
+            id: r.id,
+            type: r.type,
+            tier: r.tier,
+            title: r.title,
+            summary: r.summary,
+            strength: r.strength,
+            importance: r.importance,
+            createdAt: r.created_at
+        }));
+    }
+    mapRow(row) {
+        return {
+            id: row.id,
+            tenantId: row.tenant_id,
+            deviceId: row.device_id,
+            source: row.source,
+            title: row.title,
+            summary: row.summary,
+            startedAt: row.started_at,
+            endedAt: row.ended_at,
+            observationCount: row.observation_count
+        };
+    }
+}

package/dist/db/repositories/stats-repo.js

@@ -0,0 +1,92 @@
+import { ConsolidationRunRepo } from './consolidation-run-repo.js';
+const DAY_MS = 24 * 60 * 60 * 1000;
+export class StatsRepo {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    getStats(tenantId) {
+        const now = Date.now();
+        const startOfDay = now - (now % DAY_MS);
+        // Totals
+        const totalsRow = this.db.prepare(`
+      SELECT
+        (SELECT COUNT(*) FROM memories WHERE tenant_id = ?) AS memories,
+        (SELECT COUNT(*) FROM memories WHERE tenant_id = ? AND deleted_at IS NULL) AS activeMemories,
+        (SELECT COUNT(*) FROM sessions WHERE tenant_id = ?) AS sessions,
+        (SELECT COUNT(*) FROM observations WHERE tenant_id = ?) AS observations,
+        (SELECT COUNT(*) FROM edges WHERE tenant_id = ?) AS edges,
+        (SELECT COUNT(*) FROM devices WHERE tenant_id = ?) AS devices
+    `).get(tenantId, tenantId, tenantId, tenantId, tenantId, tenantId);
+        // By tier (non-deleted only)
+        const tierRows = this.db.prepare(`
+      SELECT tier, COUNT(*) AS c
+      FROM memories WHERE tenant_id = ? AND deleted_at IS NULL
+      GROUP BY tier
+    `).all(tenantId);
+        const byTier = { short: 0, medium: 0, long: 0 };
+        for (const r of tierRows)
+            byTier[r.tier] = r.c;
+        // By type (non-deleted only)
+        const typeRows = this.db.prepare(`
+      SELECT type, COUNT(*) AS c
+      FROM memories WHERE tenant_id = ? AND deleted_at IS NULL
+      GROUP BY type
+    `).all(tenantId);
+        const byType = {
+            fact: 0, decision: 0, preference: 0, event: 0, project_context: 0,
+            lesson: 0, code_pattern: 0, bug: 0, workflow: 0
+        };
+        for (const r of typeRows)
+            byType[r.type] = r.c;
+        // Today
+        const todayNewRow = this.db.prepare(`
+      SELECT COUNT(*) AS c FROM memories
+      WHERE tenant_id = ? AND created_at >= ?
+    `).get(tenantId, startOfDay);
+        // Recent projects: pull from memory_scopes
+        const projectRows = this.db.prepare(`
+      SELECT value AS project, COUNT(DISTINCT memory_id) AS c
+      FROM memory_scopes
+      WHERE tenant_id = ? AND key = 'project'
+      GROUP BY value
+      ORDER BY c DESC
+      LIMIT 10
+    `).all(tenantId);
+        const recentProjects = projectRows.map((r) => ({ project: r.project, count: r.c }));
+        // Last consolidation
+        const runRepo = new ConsolidationRunRepo(this.db);
+        const latestRun = runRepo.latestForTenant(tenantId);
+        const lastConsolidation = latestRun
+            ? { id: latestRun.id, startedAt: latestRun.startedAt, summary: latestRun.summary }
+            : null;
+        // Today consolidation stats
+        const todayConsRow = this.db.prepare(`
+      SELECT
+        COALESCE(SUM(promoted_count), 0) AS promoted,
+        COALESCE(SUM(evicted_count), 0) AS evicted
+      FROM consolidation_runs
+      WHERE tenant_id = ? AND started_at >= ?
+    `).get(tenantId, startOfDay);
+        return {
+            totals: {
+                memories: totalsRow.memories,
+                activeMemories: totalsRow.activeMemories,
+                sessions: totalsRow.sessions,
+                observations: totalsRow.observations,
+                edges: totalsRow.edges,
+                devices: totalsRow.devices
+            },
+            byTier,
+            byType,
+            today: {
+                promoted: todayConsRow.promoted,
+                evicted: todayConsRow.evicted,
+                newMemories: todayNewRow.c,
+                injectBundles: 0 // v1: not tracked
+            },
+            recentProjects,
+            lastConsolidation
+        };
+    }
+}

package/dist/db/repositories/vector-repo.js

@@ -0,0 +1,55 @@
+import { getVecTableName, VECTOR_DEFAULT_DIMENSIONS } from '../database.js';
+export class VectorRepo {
+    db;
+    dimensions;
+    constructor(db, dimensions = VECTOR_DEFAULT_DIMENSIONS) {
+        this.db = db;
+        this.dimensions = dimensions;
+    }
+    /**
+     * Upsert a single embedding. Inserts a new row or replaces an existing one
+     * (matching by memory_id).
+     */
+    upsert(memoryId, tenantId, vector) {
+        if (vector.length !== this.dimensions) {
+            throw new Error(`Vector dimensions mismatch: expected ${this.dimensions}, got ${vector.length}`);
+        }
+        const tableName = getVecTableName(this.dimensions);
+        const exists = this.db
+            .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name=?`)
+            .get(tableName);
+        if (!exists) {
+            // Vec table not present (sqlite-vec unavailable); silently no-op.
+            return;
+        }
+        // sqlite-vec's vec0 primary-key behavior is rowid-based; use a manual
+        // delete-then-insert to guarantee a clean replacement. We wrap in a
+        // transaction for atomicity.
+        const tx = this.db.transaction(() => {
+            this.db.prepare(`DELETE FROM ${tableName} WHERE memory_id = ?`).run(memoryId);
+            this.db.prepare(`
+        INSERT INTO ${tableName} (memory_id, tenant_id, embedding)
+        VALUES (?, ?, ?)
+      `).run(memoryId, tenantId, new Float32Array(vector));
+        });
+        tx();
+    }
+    /** Remove the embedding for a memory. */
+    delete(memoryId) {
+        const tableName = getVecTableName(this.dimensions);
+        this.db.prepare(`
+      DELETE FROM ${tableName} WHERE memory_id = ?
+    `).run(memoryId);
+    }
+    /** Count embeddings in the vec table. */
+    count() {
+        const tableName = getVecTableName(this.dimensions);
+        const exists = this.db
+            .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name=?`)
+            .get(tableName);
+        if (!exists)
+            return 0;
+        const row = this.db.prepare(`SELECT COUNT(*) as cnt FROM ${tableName}`).get();
+        return row.cnt;
+    }
+}