@mem-weave/server 0.2.0

package/dist/retrieval/vector-search.js

@@ -0,0 +1,91 @@
+import { getVecTableName, VECTOR_DEFAULT_DIMENSIONS } from '../db/database.js';
+/**
+ * Vector similarity search using sqlite-vec.
+ *
+ * Returns the top-`limit` memories in the tenant whose stored embedding is
+ * closest to `queryVector` (L2 distance, then converted to similarity
+ * = 1 / (1 + distance) for downstream fusion).
+ */
+export function vectorSearch(db, tenantId, queryVector, limit, dimensions = VECTOR_DEFAULT_DIMENSIONS) {
+    if (limit <= 0 || queryVector.length === 0)
+        return [];
+    if (queryVector.length !== dimensions) {
+        // Mismatched dimensions — degrade gracefully.
+        return [];
+    }
+    const tableName = getVecTableName(dimensions);
+    // Verify the vec table exists; if not, vector search returns empty.
+    const exists = db
+        .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name=?`)
+        .get(tableName);
+    if (!exists)
+        return [];
+    const float32 = new Float32Array(queryVector);
+    // Use a subquery: sqlite-vec's `MATCH` operator only works on the
+    // outermost virtual table in a query. Wrapping the vec search as a
+    // subquery lets us join the result against `memories` for scope/type filters.
+    const rows = db.prepare(`
+    SELECT
+      m.id, m.tenant_id, m.tier, m.type, m.title, m.content, m.summary,
+      m.concepts_json, m.files_json, m.importance, m.confidence, m.strength,
+      m.source, m.scope_level, m.source_client, m.source_device_id,
+      m.source_session_id, m.tau, m.access_count, m.last_accessed_at,
+      m.last_reinforced_at, m.last_decay_at, m.reinforcement_score,
+      m.promoted_at, m.created_at, m.updated_at, m.deleted_at, m.eviction_reason,
+      v.distance AS vec_distance
+    FROM (
+      SELECT memory_id, tenant_id, distance
+      FROM ${tableName}
+      WHERE embedding MATCH ? AND k = ?
+    ) v
+    JOIN memories m ON m.id = v.memory_id
+    WHERE v.tenant_id = ? AND m.deleted_at IS NULL
+    ORDER BY v.distance
+    LIMIT ?
+  `).all(float32, limit, tenantId, limit);
+    return rows.map((row) => {
+        const distance = Number(row.vec_distance);
+        return {
+            memory: rowToMemory(row),
+            distance,
+            similarity: similarityFromL2(distance)
+        };
+    });
+}
+function rowToMemory(row) {
+    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
+    };
+}
+/** L2 distance → [0, 1] similarity. */
+export function similarityFromL2(distance) {
+    return 1 / (1 + distance);
+}

package/dist/server/auth.js

@@ -0,0 +1,80 @@
+import { createHash } from 'node:crypto';
+import { openDatabase } from '../db/database.js';
+import { DeviceRepo } from '../db/repositories/device-repo.js';
+/**
+ * Hash an API key for storage/comparison. v1 supports two strategies:
+ * - 'plain': identity (no hash) — convenient for local dev / tests
+ * - 'sha256': SHA-256 of the key — safer for production
+ */
+export function hashApiKey(key, strategy = 'plain') {
+    if (strategy === 'sha256')
+        return createHash('sha256').update(key).digest('hex');
+    return key;
+}
+/**
+ * Extract a Bearer token from the `Authorization` header.
+ * Returns `null` if missing or malformed.
+ */
+export function extractBearerToken(authorization) {
+    if (!authorization)
+        return null;
+    const m = /^Bearer\s+(.+)$/i.exec(authorization);
+    return m ? m[1].trim() : null;
+}
+/**
+ * Registers an `onRequest` hook that enforces Bearer-token authentication on
+ * `/api/v1/*` routes (except `/api/v1/health`).
+ *
+ * Behavior:
+ * - `config.requireAuth === false`: skip auth, leave `request.authDevice` undefined.
+ *   This is the v1 default for developer convenience.
+ * - `config.requireAuth === true`: require a valid Bearer token; otherwise 401.
+ *   Also calls `device.touch(id)` to update `lastSeenAt`.
+ *
+ * On success, `request.authDevice` is populated and downstream handlers can
+ * use `request.tenantId` and `request.deviceId` for tenant isolation.
+ */
+export function registerAuthMiddleware(app, options) {
+    const deviceRepo = new DeviceRepo(openDatabase(options.dbPath));
+    const hashStrategy = options.config.requireAuth ? 'sha256' : 'plain';
+    // Build a "default device" record on the fly when requireAuth is disabled,
+    // so the rest of the system can still treat the request as authenticated.
+    const defaultTenantId = 'tenant_default';
+    app.addHook('onRequest', async (request, reply) => {
+        const url = request.routeOptions?.url ?? request.url;
+        if (!url.startsWith('/api/v1/'))
+            return;
+        if (url === '/api/v1/health')
+            return;
+        if (!options.config.requireAuth) {
+            // Dev mode: synthesize a default device identity.
+            request.authDevice = {
+                deviceId: 'dev-device',
+                tenantId: defaultTenantId,
+                type: 'rest',
+                name: 'dev-local'
+            };
+            return;
+        }
+        const token = extractBearerToken(request.headers.authorization);
+        if (!token) {
+            return reply.code(401).send({
+                error: { code: 'UNAUTHORIZED', message: 'Missing Bearer token' }
+            });
+        }
+        const hash = hashApiKey(token, hashStrategy);
+        const device = deviceRepo.findByKeyHash(hash);
+        if (!device) {
+            return reply.code(401).send({
+                error: { code: 'UNAUTHORIZED', message: 'Invalid API key' }
+            });
+        }
+        deviceRepo.touch(device.id);
+        request.authDevice = {
+            deviceId: device.id,
+            tenantId: device.tenantId,
+            type: device.type,
+            name: device.name
+        };
+    });
+}

package/dist/server/bootstrap.js

@@ -0,0 +1,28 @@
+import { expandPath, loadConfig } from '../core/config.js';
+import { createHttpServer } from './http.js';
+import { startConsolidationScheduler } from './scheduler.js';
+import { logger } from './logger.js';
+const configPath = process.env.MEMWEAVE_CONFIG;
+const config = loadConfig(configPath);
+const dbPath = expandPath(config.storage.path);
+const app = await createHttpServer({ dbPath, configPath });
+// Background consolidation: every 6 hours, also run once on startup so any
+// pending promotions/evictions are applied. Disable by setting MEMWEAVE_NO_SCHEDULER=1.
+if (process.env.MEMWEAVE_NO_SCHEDULER !== '1') {
+    const scheduler = startConsolidationScheduler({
+        dbPath,
+        intervalMs: 6 * 60 * 60 * 1000,
+        runOnStart: true,
+        onRun: (r) => {
+            logger.info({ event: 'consolidation', ...r }, r.summary);
+        }
+    });
+    // Stop the scheduler gracefully on process exit
+    const shutdown = () => {
+        scheduler.stop();
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+}
+await app.listen({ host: config.server.host, port: config.server.port });
+logger.info({ host: config.server.host, port: config.server.port }, 'memweave server listening');

package/dist/server/http.js

@@ -0,0 +1,77 @@
+import Fastify from 'fastify';
+import fastifyStatic from '@fastify/static';
+import { ZodError } from 'zod';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { openDatabase } from '../db/database.js';
+import { registerInjectionRoute } from '../rest/routes/injection.js';
+import { registerMemoriesRoute } from '../rest/routes/memories.js';
+import { registerStatsRoute } from '../rest/routes/stats.js';
+import { registerSessionsRoute } from '../rest/routes/sessions.js';
+import { registerObservationsRoute } from '../rest/routes/observations.js';
+import { registerConsolidationRoute } from '../rest/routes/consolidation.js';
+import { registerDevicesRoute } from '../rest/routes/devices.js';
+import { registerSettingsRoute } from '../rest/routes/settings.js';
+export async function createHttpServer(options) {
+    const app = Fastify({ logger: false });
+    const db = openDatabase(options.dbPath);
+    db.prepare('INSERT OR IGNORE INTO tenants (id, name, api_key_hash, created_at) VALUES (?, ?, ?, ?)')
+        .run('tenant_default', 'default', 'dev-local-key', Date.now());
+    app.addHook('onClose', async () => db.close());
+    app.setErrorHandler((error, _request, reply) => {
+        if (error instanceof ZodError) {
+            return reply.code(400).send({
+                error: {
+                    code: 'VALIDATION_ERROR',
+                    message: 'Request validation failed',
+                    details: error.issues
+                }
+            });
+        }
+        return reply.code(500).send({
+            error: { code: 'INTERNAL_ERROR', message: 'Internal server error' }
+        });
+    });
+    app.get('/api/v1/health', async () => ({ ok: true, service: 'memweave-server' }));
+    registerMemoriesRoute(app, options.dbPath);
+    registerInjectionRoute(app, options.dbPath);
+    registerStatsRoute(app, options.dbPath);
+    registerSessionsRoute(app, options.dbPath);
+    registerObservationsRoute(app, options.dbPath);
+    registerConsolidationRoute(app, options.dbPath);
+    registerDevicesRoute(app, options.dbPath);
+    registerSettingsRoute(app, options.configPath);
+    // Serve the Web UI (SPA) at /ui/*
+    // web/ builds to ../dist/web/ relative to the repo root.
+    // We resolve from this file's location so the path is stable regardless of cwd.
+    const here = dirname(fileURLToPath(import.meta.url));
+    // src/server → ../../ → repo root → dist/web
+    const webDist = resolve(here, '../../dist/web');
+    if (existsSync(webDist)) {
+        await app.register(fastifyStatic, {
+            root: webDist,
+            prefix: '/ui/',
+            decorateReply: true
+        });
+        // SPA fallback: any GET under /ui/* that didn't match a file → index.html
+        app.setNotFoundHandler((request, reply) => {
+            if (request.url.startsWith('/ui/') && request.method === 'GET') {
+                return reply.sendFile('index.html');
+            }
+            return reply.code(404).send({ error: { code: 'NOT_FOUND', message: 'No route' } });
+        });
+    }
+    else {
+        // Dev mode: tell the user how to build the SPA.
+        app.get('/ui/*', async (_req, reply) => {
+            return reply.code(503).send({
+                error: {
+                    code: 'UI_NOT_BUILT',
+                    message: 'Run `npm run web:build` (or `npm run web:dev` on :5173) to serve the SPA.'
+                }
+            });
+        });
+    }
+    return app;
+}

package/dist/server/logger.js

@@ -0,0 +1,36 @@
+/**
+ * Shared structured logger. Built on pino (already a dependency). The
+ * Fastify server has its own pino instance internally (`logger: false`
+ * in `http.ts` disables it for now; can be enabled later). This module
+ * is for *operational* logging from CLI, scheduler, workers, and the
+ * OpenCode plugin.
+ *
+ * Why pino and not console.*?
+ *   - Structured (JSON) output — operators can pipe to jq / log aggregators
+ *   - Level filtering via LOG_LEVEL env (default: info)
+ *   - Child loggers for per-tenant / per-run context
+ *   - Benchmarks ~5x faster than console.* under load
+ *
+ * Usage:
+ *   import { logger } from './logger.js';
+ *   logger.info({ memoryId, action: 'reinforced' }, 'memory reinforced');
+ *   logger.warn({ err }, 'consolidation failed');
+ */
+import pino from 'pino';
+const LOG_LEVEL = process.env.LOG_LEVEL ?? 'info';
+const options = {
+    level: LOG_LEVEL,
+    // Pretty-print only in dev; in production, leave as JSON for log shippers.
+    // We avoid pino-pretty as a hard dep to keep install lean.
+    base: { service: 'memweave' },
+    timestamp: pino.stdTimeFunctions.isoTime
+};
+export const logger = pino(options);
+/**
+ * Create a child logger with a fixed context (e.g., tenantId, runId).
+ * Use this for sub-operations that should share context across multiple
+ * log lines.
+ */
+export function childLogger(bindings) {
+    return logger.child(bindings);
+}

package/dist/server/rate-limiter.js

@@ -0,0 +1,81 @@
+/**
+ * In-process token-bucket rate limiter. One bucket per (key, window) pair.
+ * No external dependency; suitable for single-node MemWeave deployments.
+ *
+ * If you ever scale to multi-node, swap this for a Redis-backed limiter.
+ * The interface (`RateLimiter.consume(key)` returning boolean) is the
+ * only thing callers depend on.
+ */
+export class RateLimiter {
+    buckets = new Map();
+    capacity;
+    refillPerMs;
+    sweepIntervalMs;
+    sweepTimer = null;
+    constructor(config) {
+        this.capacity = config.capacity;
+        this.refillPerMs = config.refillPerSecond / 1000;
+        this.sweepIntervalMs = config.sweepIntervalMs ?? 60_000;
+        // Periodic GC of buckets that have been idle longer than the time to
+        // fully refill. Prevents the map from growing unbounded over the
+        // process lifetime in long-running deployments.
+        this.sweepTimer = setInterval(() => this.sweep(), this.sweepIntervalMs);
+        if (typeof this.sweepTimer.unref === 'function')
+            this.sweepTimer.unref();
+    }
+    /**
+     * Attempt to consume one token. Returns whether the call is allowed.
+     */
+    consume(key, now = Date.now()) {
+        let bucket = this.buckets.get(key);
+        if (!bucket) {
+            bucket = { tokens: this.capacity, lastRefillMs: now, lastSeenMs: now };
+            this.buckets.set(key, bucket);
+        }
+        else {
+            // Refill: add (elapsed * refillPerMs), capped at capacity.
+            const elapsed = Math.max(0, now - bucket.lastRefillMs);
+            const refilled = elapsed * this.refillPerMs;
+            if (refilled > 0) {
+                bucket.tokens = Math.min(this.capacity, bucket.tokens + refilled);
+                bucket.lastRefillMs = now;
+            }
+            bucket.lastSeenMs = now;
+        }
+        if (bucket.tokens >= 1) {
+            bucket.tokens -= 1;
+            return { allowed: true, remaining: Math.floor(bucket.tokens), retryAfterSec: 0 };
+        }
+        // Compute how long until we have >= 1 token.
+        const deficit = 1 - bucket.tokens;
+        const retryAfterSec = Math.max(1, Math.ceil(deficit / this.refillPerMs / 1000));
+        return { allowed: false, remaining: 0, retryAfterSec };
+    }
+    /**
+     * For tests / observability. Returns the number of live buckets.
+     */
+    size() {
+        return this.buckets.size;
+    }
+    /**
+     * Stop the sweep timer. Call before shutdown to allow the process to exit
+     * cleanly.
+     */
+    dispose() {
+        if (this.sweepTimer) {
+            clearInterval(this.sweepTimer);
+            this.sweepTimer = null;
+        }
+    }
+    sweep() {
+        const now = Date.now();
+        // A bucket that hasn't been touched for the time-to-full-refill is
+        // indistinguishable from a fresh one — drop it.
+        const fullRefillMs = this.capacity / this.refillPerMs;
+        for (const [key, bucket] of this.buckets) {
+            if (now - bucket.lastSeenMs > fullRefillMs * 2) {
+                this.buckets.delete(key);
+            }
+        }
+    }
+}

package/dist/server/scheduler.js

@@ -0,0 +1,99 @@
+import { openDatabase } from '../db/database.js';
+import { runConsolidation } from '../workers/consolidator.js';
+import { ConsolidationRunRepo } from '../db/repositories/consolidation-run-repo.js';
+import { logger } from './logger.js';
+/**
+ * Starts a background consolidation loop. Returns a handle with stop() and runNow().
+ *
+ * Default interval: 6 hours. Default: does NOT run on start (set `runOnStart: true` to run once immediately).
+ *
+ * Each run is persisted to the `consolidation_runs` table so the Web UI's
+ * Sleep page can render a history.
+ */
+export function startConsolidationScheduler(options) {
+    const interval = options.intervalMs ?? 6 * 60 * 60 * 1000;
+    const tenantId = options.tenantId ?? 'tenant_default';
+    let stopped = false;
+    let timer = null;
+    async function runOnce() {
+        const startedAt = Date.now();
+        const db = openDatabase(options.dbPath);
+        try {
+            const result = runConsolidation(db, tenantId);
+            const endedAt = Date.now();
+            // Persist the run for the Sleep UI page. Swallow errors so the scheduler
+            // loop stays alive even if the runs table is somehow missing.
+            try {
+                const runRepo = new ConsolidationRunRepo(db);
+                runRepo.record({
+                    tenantId,
+                    startedAt,
+                    endedAt,
+                    promoted: result.promotedIds,
+                    evicted: result.evictedIds,
+                    merged: result.mergedPairs,
+                    edgesCreated: 0,
+                    contradictionFound: 0,
+                    dryRun: false,
+                    summary: result.summary
+                });
+            }
+            catch (err) {
+                logger.warn({ err: err.message }, 'failed to record consolidation run');
+            }
+            const payload = {
+                promoted: result.promoted,
+                evicted: result.evicted,
+                summary: result.summary,
+                timestamp: endedAt
+            };
+            options.onRun?.(payload);
+            return payload;
+        }
+        finally {
+            db.close();
+        }
+    }
+    const runNow = runOnce;
+    function schedule() {
+        if (stopped)
+            return;
+        timer = setTimeout(async () => {
+            try {
+                await runOnce();
+            }
+            catch (err) {
+                // Swallow errors in background; the next interval will try again.
+                // We intentionally do not throw here to keep the scheduler alive.
+                logger.error({ err }, 'consolidation run failed');
+            }
+            schedule();
+        }, interval);
+    }
+    // Listen for abort
+    if (options.signal) {
+        if (options.signal.aborted) {
+            stopped = true;
+        }
+        else {
+            options.signal.addEventListener('abort', () => {
+                stopped = true;
+                if (timer)
+                    clearTimeout(timer);
+            });
+        }
+    }
+    if (options.runOnStart) {
+        void runOnce();
+    }
+    schedule();
+    const handle = {
+        stop() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+        },
+        runNow
+    };
+    return handle;
+}

package/dist/workers/association.js

@@ -0,0 +1,41 @@
+import { EDGE_EXTRACT_SYSTEM, buildEdgeExtractPrompt } from '../prompts/edge-extract.js';
+import { logger } from '../server/logger.js';
+function isValidEdge(candidate) {
+    if (typeof candidate !== 'object' || candidate === null)
+        return false;
+    const c = candidate;
+    return (typeof c.targetMemoryId === 'string' &&
+        typeof c.type === 'string' &&
+        typeof c.reason === 'string' &&
+        typeof c.confidence === 'number');
+}
+export async function extractEdges(provider, newMemory, existingMemories) {
+    if (existingMemories.length === 0)
+        return [];
+    let raw;
+    try {
+        const prompt = buildEdgeExtractPrompt(newMemory, existingMemories);
+        raw = await provider.call(EDGE_EXTRACT_SYSTEM, prompt);
+    }
+    catch (err) {
+        logger.warn({ err }, 'provider call failed');
+        return [];
+    }
+    if (!raw.trim())
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        logger.warn('failed to parse JSON response');
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const existingIds = new Set(existingMemories.map(m => m.id));
+    return parsed
+        .filter(isValidEdge)
+        .filter(e => e.confidence >= 0.6)
+        .filter(e => existingIds.has(e.targetMemoryId));
+}

package/dist/workers/compressor.js

@@ -0,0 +1,14 @@
+import { COMPRESSION_SYSTEM, buildCompressionPrompt } from '../prompts/compression.js';
+export async function compressObservation(provider, input) {
+    const prompt = buildCompressionPrompt(input);
+    const raw = await provider.call(COMPRESSION_SYSTEM, prompt);
+    if (!raw.trim())
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}