@mem-weave/server 0.2.0

package/README.md

@@ -0,0 +1,74 @@
+# @mem-weave/server
+
+**MemWeave local-first memory infrastructure for AI agents.** Structured memory, 4-layer retrieval (BM25 + vector + graph + causal), token-budgeted injection, server-side write deduplication, and background consolidation. Fastify REST API + CLI.
+
+This is the **server** half of the MemWeave stack. The complementary packages are:
+
+- **[@mem-weave/mcp](https://www.npmjs.com/package/@mem-weave/mcp)** — stdio MCP server exposing 10 tools
+- **[@mem-weave/opencode-plugin](https://www.npmjs.com/package/@mem-weave/opencode-plugin)** — OpenCode plugin that auto-injects memory + registers the MCP server
+
+## Install
+
+```bash
+npm install -g @mem-weave/server
+```
+
+## Quick start
+
+```bash
+# 1. Initialize a config + data dir in the current directory
+memweave init
+
+# 2. Start the server (foreground)
+memweave start
+
+# Server listens on http://127.0.0.1:3131 by default.
+# Health check:
+curl http://127.0.0.1:3131/api/v1/health
+# → {"ok":true,"service":"memweave-server"}
+```
+
+In another terminal, point an MCP client (e.g. `@mem-weave/opencode-plugin`) at `http://127.0.0.1:3131`.
+
+## CLI
+
+```
+memweave start           Start the HTTP server + background workers (default)
+memweave stop            Stop a running memweave-server (via PID file)
+memweave status          Probe /api/v1/health
+memweave init            Create default config, DB, and device key
+memweave doctor          Check dependencies, port, DB, embedding/LLM config
+memweave migrate         Run schema migration (idempotent)
+memweave backup [path]   Copy the SQLite DB to a snapshot file
+memweave help            Show help
+```
+
+> Note: the `mcp` subcommand was removed in v0.2. Install `@mem-weave/mcp` and run its `memweave-mcp` bin instead.
+
+## REST API
+
+All routes are prefixed `/api/v1/`. Selected endpoints:
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/health` | Liveness check |
+| `POST` | `/memories` | Create a memory (rate-limited per API key) |
+| `POST` | `/memories/search` | 4-layer hybrid search; `mode: 'compact' \| 'full'` |
+| `GET` | `/memories/:id` | Fetch one memory (full record, used by `memory_expand`) |
+| `PATCH` | `/memories/:id` | Edit title / content / summary / importance / confidence |
+| `DELETE` | `/memories/:id` | Soft-delete (`deleted_at`) with reason |
+| `POST` | `/inject` | Token-budgeted summary XML for a session/phase |
+| `GET` | `/stats` | Dashboard aggregates |
+| `GET` | `/sessions` | Recent sessions with observation counts |
+| `GET` | `/consolidation/runs` | Background "sleep" cycle history |
+| `POST` | `/consolidate` | Manually trigger a consolidation run |
+| `GET/POST/DELETE` | `/devices` | Device API key management |
+| `GET` | `/settings` | Server config (secrets masked) |
+
+## Programmatic use
+
+The server is also a TypeScript library. Importing the HTTP bootstrap from `@mem-weave/server/dist/server/bootstrap.js` boots everything in-process. See `src/server/bootstrap.ts` for the entry point.
+
+## License
+
+MIT

package/dist/cli-entry.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * MemWeave CLI entry point.
+ *
+ * This file is the executable for the `memweave` bin command. It parses
+ * argv, dispatches to the right command, and prints the result.
+ */
+import { parseCli, runCli, CliError } from './cli.js';
+async function main() {
+    let parsed;
+    try {
+        parsed = parseCli(process.argv);
+    }
+    catch (err) {
+        if (err instanceof CliError) {
+            // eslint-disable-next-line no-console
+            console.error(err.message);
+            process.exit(2);
+        }
+        throw err;
+    }
+    const result = await runCli({
+        command: parsed.command,
+        args: parsed.args,
+        env: process.env,
+        configPath: process.env.MEMWEAVE_CONFIG
+    });
+    // Print message + data, and exit non-zero on failure
+    if (result.message) {
+        if (result.ok) {
+            // eslint-disable-next-line no-console
+            console.log(result.message);
+        }
+        else {
+            // eslint-disable-next-line no-console
+            console.error(result.message);
+        }
+    }
+    if (result.data !== undefined) {
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify(result.data, null, 2));
+    }
+    process.exit(result.ok ? 0 : 1);
+}
+main().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error('memweave: unexpected error:', err);
+    process.exit(1);
+});

package/dist/cli.js

@@ -0,0 +1,53 @@
+/**
+ * MemWeave CLI 鈥?design spec 搂9.11.
+ *
+ * Subcommands (all optional; running without args shows help):
+ *
+ *   memweave start           Start the HTTP server + background workers (default)
+ *   memweave stop            Stop a running memweave-server (via PID file)
+ *   memweave status          Probe /api/v1/health
+ *   memweave init            Create default config, DB, and device key
+ *   memweave doctor          Check dependencies, port, DB, embedding/LLM config
+ *   memweave mcp             Start the stdio MCP shim
+ *   memweave migrate         Run schema migration (idempotent)
+ *   memweave backup [path]   Copy the SQLite DB to a snapshot file
+ *   memweave help            Show help
+ *
+ * Note: this file is the *parser / dispatcher*. The actual logic for each
+ * command lives in `./commands/`. The CLI never edits `bootstrap.ts` 鈥?the
+ * default `start` command simply invokes the existing server bootstrap.
+ */
+import { runCommand } from './commands/index.js';
+export function parseCli(argv) {
+    const [, , cmd, ...rest] = argv;
+    if (!cmd || cmd === '-h' || cmd === '--help')
+        return { command: 'help', args: [] };
+    if (cmd === '-v' || cmd === '--version' || cmd === 'version')
+        return { command: 'version', args: [] };
+    const known = ['start', 'stop', 'status', 'init', 'doctor', 'migrate', 'backup', 'help'];
+    if (cmd === 'mcp') {
+        throw new CliError('The `mcp` subcommand was removed in v0.2.\n' +
+            'Install the @mem-weave/mcp package and run its `memweave-mcp` bin instead:\n' +
+            '  npm install -g @mem-weave/mcp\n' +
+            '  memweave-mcp');
+    }
+    if (known.includes(cmd)) {
+        return { command: cmd, args: rest };
+    }
+    throw new CliError(`Unknown command: ${cmd}\nRun \`memweave help\` for usage.`);
+}
+export class CliError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CliError';
+    }
+}
+export async function runCli(invocation) {
+    const ctx = {
+        env: invocation.env,
+        args: invocation.args,
+        configPath: invocation.configPath
+    };
+    return runCommand(invocation.command, ctx);
+}
+export { runCommand } from './commands/index.js';

package/dist/commands/backup.js

@@ -0,0 +1,28 @@
+import { copyFileSync, existsSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { loadConfig } from '../core/config.js';
+import { expandPath } from '../core/config.js';
+/**
+ * `memweave backup [path]` — copy the SQLite DB to a snapshot file.
+ *
+ * Uses SQLite's recommended "backup" semantics: a simple file copy. For
+ * very large DBs a proper `.backup` would be safer, but file copy is
+ * acceptable for v1 since we use WAL mode.
+ */
+export const backupCommand = async (ctx) => {
+    const config = loadConfig(ctx.configPath);
+    const dbPath = expandPath(config.storage.path);
+    if (!existsSync(dbPath)) {
+        return { ok: false, message: `Database file not found: ${dbPath}` };
+    }
+    const dest = ctx.args[0] ?? `${dbPath}.backup-${new Date().toISOString().replace(/[:.]/g, '-')}.db`;
+    mkdirSync(dirname(dest), { recursive: true });
+    copyFileSync(dbPath, dest);
+    const srcSize = statSync(dbPath).size;
+    return {
+        ok: true,
+        message: `Backed up ${dbPath} (${srcSize} bytes) to ${dest}`,
+        data: { source: dbPath, dest, size: srcSize }
+    };
+};

package/dist/commands/doctor.js

@@ -0,0 +1,108 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { loadConfig } from '../core/config.js';
+import { expandPath } from '../core/config.js';
+import { openDatabase } from '../db/database.js';
+/**
+ * `memweave doctor` — environment / configuration health check.
+ *
+ * Checks:
+ *  - config loads cleanly
+ *  - DB file is reachable and the schema applies
+ *  - port is free
+ *  - sqlite-vec extension loads (when used)
+ *  - LLM provider has a usable API key (when not noop)
+ *  - Embedding provider has a usable config (when not noop)
+ */
+export const doctorCommand = async (ctx) => {
+    const results = [];
+    // 1. Config loads
+    let config;
+    try {
+        config = loadConfig(ctx.configPath);
+        results.push({ name: 'config', ok: true, detail: 'loaded' });
+    }
+    catch (err) {
+        return { ok: false, message: 'Config load failed', data: { results, error: err.message } };
+    }
+    const dbPath = expandPath(config.storage.path);
+    // 2. DB open + schema
+    try {
+        const db = openDatabase(dbPath, { vectorDimensions: config.embedding.dimensions });
+        try {
+            const tables = db.prepare(`SELECT COUNT(*) as c FROM sqlite_master WHERE type='table'`).get();
+            results.push({ name: 'database', ok: true, detail: `${tables.c} tables; path=${dbPath}` });
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (err) {
+        results.push({ name: 'database', ok: false, detail: err.message });
+    }
+    // 3. Port available
+    try {
+        const probe = await fetch(`http://127.0.0.1:${config.server.port}/api/v1/health`, {
+            signal: AbortSignal.timeout(500)
+        });
+        if (probe.ok) {
+            results.push({ name: 'port', ok: true, detail: `port ${config.server.port} already serving (likely already running)` });
+        }
+        else {
+            results.push({ name: 'port', ok: true, detail: `port ${config.server.port} responding but not OK` });
+        }
+    }
+    catch {
+        results.push({ name: 'port', ok: true, detail: `port ${config.server.port} appears free` });
+    }
+    // 4. sqlite-vec
+    try {
+        const db = openDatabase(dbPath, { vectorDimensions: config.embedding.dimensions });
+        try {
+            const v = db.prepare(`SELECT vec_version() AS v`).get();
+            results.push({ name: 'sqlite-vec', ok: true, detail: v.v });
+        }
+        catch (err) {
+            results.push({ name: 'sqlite-vec', ok: false, detail: err.message });
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        results.push({ name: 'sqlite-vec', ok: false, detail: 'extension failed to load' });
+    }
+    // 5. LLM
+    if (config.llm.provider === 'openai-compatible') {
+        const hasKey = Boolean(config.llm.apiKey);
+        results.push({ name: 'llm', ok: hasKey, detail: hasKey ? 'apiKey set' : 'apiKey missing' });
+    }
+    else {
+        results.push({ name: 'llm', ok: true, detail: 'noop' });
+    }
+    // 6. Embedding
+    if (config.embedding.provider === 'openai-compatible') {
+        const ok = Boolean(config.embedding.apiKey) && Boolean(config.embedding.baseUrl);
+        results.push({ name: 'embedding', ok, detail: ok ? 'configured' : 'apiKey or baseUrl missing' });
+    }
+    else if (config.embedding.provider === 'local-xenova') {
+        results.push({ name: 'embedding', ok: true, detail: 'local-xenova (stub in v1)' });
+    }
+    else {
+        results.push({ name: 'embedding', ok: true, detail: 'noop' });
+    }
+    // 7. PID file existence (informational)
+    const pidPath = join(tmpdir(), 'memweave.pid');
+    results.push({
+        name: 'pid-file',
+        ok: true,
+        detail: existsSync(pidPath) ? `${pidPath} present` : 'none (server not started via CLI)'
+    });
+    const allOk = results.every((r) => r.ok);
+    return {
+        ok: allOk,
+        message: allOk ? 'All checks passed.' : 'Some checks failed.',
+        data: { results }
+    };
+};

package/dist/commands/help.js

@@ -0,0 +1,29 @@
+const HELP = `MemWeave — persistent cross-device memory for AI coding agents
+
+Usage:
+  memweave <command> [options]
+
+Commands:
+  start           Start the HTTP server + background workers
+  stop            Stop a running memweave-server (via PID file)
+  status          Probe /api/v1/health
+  init            Create default config, DB, and device key
+  doctor          Check dependencies, port, DB, embedding/LLM config
+  mcp             Start the stdio MCP shim
+  migrate         Apply schema (idempotent) and preview consolidation
+  backup [path]   Copy the SQLite DB to a snapshot file
+  help            Show this help
+  version         Print version
+
+Config (env or ~/.memweave/config.jsonc):
+  MEMWEAVE_CONFIG          Path to config.jsonc
+
+Examples:
+  memweave init
+  memweave doctor
+  memweave start
+  memweave backup ~/backups/memweave-$(date +%Y%m%d).db
+`;
+export const helpCommand = async (_ctx) => {
+    return { ok: true, message: HELP };
+};

package/dist/commands/index.js

@@ -0,0 +1,27 @@
+import { startCommand } from './start.js';
+import { stopCommand } from './stop.js';
+import { statusCommand } from './status.js';
+import { initCommand } from './init.js';
+import { doctorCommand } from './doctor.js';
+import { migrateCommand } from './migrate.js';
+import { backupCommand } from './backup.js';
+import { helpCommand } from './help.js';
+import { versionCommand } from './version.js';
+const handlers = {
+    start: startCommand,
+    stop: stopCommand,
+    status: statusCommand,
+    init: initCommand,
+    doctor: doctorCommand,
+    migrate: migrateCommand,
+    backup: backupCommand,
+    help: helpCommand,
+    version: versionCommand
+};
+export async function runCommand(command, ctx) {
+    const handler = handlers[command];
+    if (!handler) {
+        return { ok: false, message: `No handler for command: ${command}` };
+    }
+    return handler(ctx);
+}

package/dist/commands/init.js

@@ -0,0 +1,58 @@
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { loadConfig } from '../core/config.js';
+import { expandPath, expandEnv } from '../core/config.js';
+import { openDatabase } from '../db/database.js';
+const DEFAULT_CONFIG_JSONC = `{
+  // MemWeave config (JSONC: comments allowed)
+  "server": {
+    "host": "127.0.0.1",
+    "port": 3131
+  },
+  "storage": {
+    "path": "~/.memweave/data/memweave.db"
+  },
+  "auth": {
+    "defaultTenantName": "default",
+    "deviceApiKey": "REPLACE_WITH_RANDOM_KEY"
+  }
+}
+`;
+/**
+ * `memweave init` — create the config dir, default config file (if missing),
+ * the SQLite DB, and a default tenant + device with a random API key.
+ *
+ * Idempotent: re-running `init` won't clobber existing state. It only
+ * creates things that don't already exist.
+ */
+export const initCommand = async (ctx) => {
+    const configDir = join(homedir(), '.memweave');
+    mkdirSync(configDir, { recursive: true });
+    mkdirSync(join(configDir, 'data'), { recursive: true });
+    const configPath = ctx.configPath ?? join(configDir, 'config.jsonc');
+    if (!existsSync(configPath)) {
+        const apiKey = randomBytes(24).toString('hex');
+        const body = DEFAULT_CONFIG_JSONC.replace('REPLACE_WITH_RANDOM_KEY', apiKey);
+        writeFileSync(configPath, body, 'utf8');
+    }
+    const config = loadConfig(configPath);
+    const dbPath = expandPath(config.storage.path);
+    // Force env:// expansion in case the config uses placeholders
+    void expandEnv(config.auth.deviceApiKey);
+    // Open DB (applies schema) and ensure default tenant + device
+    const db = openDatabase(dbPath);
+    try {
+        db.prepare('INSERT OR IGNORE INTO tenants (id, name, api_key_hash, created_at) VALUES (?, ?, ?, ?)')
+            .run('tenant_default', config.auth.defaultTenantName, config.auth.deviceApiKey, Date.now());
+    }
+    finally {
+        db.close();
+    }
+    return {
+        ok: true,
+        message: `Initialized memweave at ${configDir}`,
+        data: { configPath, dbPath }
+    };
+};

package/dist/commands/migrate.js

@@ -0,0 +1,25 @@
+import { loadConfig } from '../core/config.js';
+import { expandPath } from '../core/config.js';
+import { openDatabase } from '../db/database.js';
+import { runConsolidation } from '../workers/consolidator.js';
+/**
+ * `memweave migrate` — apply the schema (idempotent: CREATE TABLE IF NOT EXISTS)
+ * and run a one-shot consolidation pass.
+ */
+export const migrateCommand = async (ctx) => {
+    const config = loadConfig(ctx.configPath);
+    const dbPath = expandPath(config.storage.path);
+    const db = openDatabase(dbPath);
+    try {
+        const tables = db.prepare(`SELECT COUNT(*) as c FROM sqlite_master WHERE type='table'`).get();
+        const consolidation = runConsolidation(db, 'tenant_default', { dryRun: true });
+        return {
+            ok: true,
+            message: `Schema applied. ${tables.c} tables present.`,
+            data: { dbPath, tableCount: tables.c, consolidationPreview: consolidation }
+        };
+    }
+    finally {
+        db.close();
+    }
+};

package/dist/commands/start.js

@@ -0,0 +1,29 @@
+import { loadConfig } from '../core/config.js';
+import { expandPath } from '../core/config.js';
+/**
+ * `memweave start` — load config, open DB, start HTTP server + schedulers.
+ *
+ * This delegates to the same `createHttpServer` + `startConsolidationScheduler`
+ * used by the legacy `src/server/bootstrap.ts`, so behavior is identical.
+ */
+export const startCommand = async (ctx) => {
+    const config = loadConfig(ctx.configPath);
+    const dbPath = expandPath(config.storage.path);
+    // Lazy import to avoid pulling fastify in tests of the parser itself.
+    const { createHttpServer } = await import('../server/http.js');
+    const { startConsolidationScheduler } = await import('../server/scheduler.js');
+    const app = await createHttpServer({ dbPath });
+    if (config.consolidation.enabled) {
+        startConsolidationScheduler({
+            dbPath,
+            intervalMs: config.consolidation.intervalHours * 60 * 60 * 1000,
+            runOnStart: true
+        });
+    }
+    await app.listen({ host: config.server.host, port: config.server.port });
+    return {
+        ok: true,
+        message: `memweave-server listening on ${config.server.host}:${config.server.port}`,
+        data: { host: config.server.host, port: config.server.port, dbPath }
+    };
+};

package/dist/commands/status.js

@@ -0,0 +1,19 @@
+import { loadConfig } from '../core/config.js';
+/**
+ * `memweave status` — probe the running memweave-server's health endpoint.
+ */
+export const statusCommand = async (ctx) => {
+    const config = loadConfig(ctx.configPath);
+    const url = `http://${config.server.host}:${config.server.port}/api/v1/health`;
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(3000) });
+        if (!res.ok) {
+            return { ok: false, message: `Health check returned ${res.status}` };
+        }
+        const data = await res.json();
+        return { ok: true, message: 'memweave-server is up.', data };
+    }
+    catch (err) {
+        return { ok: false, message: `Cannot reach ${url}: ${err.message}` };
+    }
+};

package/dist/commands/stop.js

@@ -0,0 +1,46 @@
+import { readFileSync, unlinkSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { loadConfig } from '../core/config.js';
+import { expandPath } from '../core/config.js';
+const PID_FILENAME = 'memweave.pid';
+/**
+ * `memweave stop` — read PID file, send SIGTERM, wait, SIGKILL fallback.
+ */
+export const stopCommand = async (ctx) => {
+    const config = loadConfig(ctx.configPath);
+    const dbPath = expandPath(config.storage.path);
+    const pidPath = join(tmpdir(), PID_FILENAME);
+    if (!existsSync(pidPath)) {
+        return { ok: true, message: 'No PID file found; nothing to stop.', data: { pidPath } };
+    }
+    const pid = Number.parseInt(readFileSync(pidPath, 'utf8').trim(), 10);
+    if (!Number.isFinite(pid) || pid <= 0) {
+        return { ok: false, message: `Invalid PID file: ${pidPath}` };
+    }
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch (err) {
+        return { ok: false, message: `Failed to send SIGTERM to PID ${pid}: ${err.message}` };
+    }
+    // Give it a moment to exit
+    await new Promise((r) => setTimeout(r, 500));
+    try {
+        process.kill(pid, 0);
+        // Still alive, escalate
+        process.kill(pid, 'SIGKILL');
+        await new Promise((r) => setTimeout(r, 200));
+    }
+    catch {
+        // Already dead
+    }
+    try {
+        unlinkSync(pidPath);
+    }
+    catch {
+        // ignore
+    }
+    void dbPath;
+    return { ok: true, message: `Sent SIGTERM/SIGKILL to PID ${pid}`, data: { pid } };
+};

package/dist/commands/version.js

@@ -0,0 +1,21 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+const PACKAGE_NAME = 'memweave';
+export const versionCommand = async (_ctx) => {
+    // Read the package.json of this workspace
+    let version = 'unknown';
+    try {
+        // The compiled dist layout puts package.json at the workspace root;
+        // tests are run from the workspace root, so process.cwd() works.
+        const pkgPath = join(process.cwd(), 'package.json');
+        if (existsSync(pkgPath)) {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            if (pkg.name === PACKAGE_NAME && pkg.version)
+                version = pkg.version;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return { ok: true, message: `${PACKAGE_NAME} ${version}` };
+};