memwarden 0.0.1

package/dist/daemon/ensure.d.ts

@@ -0,0 +1,12 @@
+export declare const DAEMON_ENTRY: string;
+/** The stable, user-global brain location (one memory across every tool). */
+export declare function defaultDataDir(): string;
+export declare function daemonAlive(url: string): Promise<boolean>;
+export type EnsureResult = "already" | "started" | "failed";
+/**
+ * Ensure the daemon at `url` is up, spawning it if not. Idempotent and
+ * race-safe: concurrent callers may both spawn, but the daemon exits 0 on
+ * EADDRINUSE (see index.ts) so the loser simply goes away and the winner
+ * serves. Returns once the daemon answers /livez or the timeout elapses.
+ */
+export declare function ensureDaemon(url: string, dataDir?: string, timeoutMs?: number): Promise<EnsureResult>;

package/dist/daemon/ensure.js

@@ -0,0 +1,54 @@
+//
+// Daemon lifecycle — the self-healing core. ensureDaemon makes the daemon
+// reachable: if it isn't, spawn it detached (so it outlives the caller's
+// shell) pointed at a stable global brain, and wait for it to answer. Shared
+// by the CLI (`memwarden up`) and the MCP server (which revives a dead daemon
+// on demand), so any entry point can bring the brain back with no human in
+// the loop.
+import { spawn } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// dist/daemon/ensure.js -> dist/index.js
+export const DAEMON_ENTRY = join(dirname(fileURLToPath(import.meta.url)), "..", "index.js");
+/** The stable, user-global brain location (one memory across every tool). */
+export function defaultDataDir() {
+    return process.env.MEMWARDEN_DATA_DIR ?? join(homedir(), ".memwarden");
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function daemonAlive(url) {
+    try {
+        const res = await fetch(`${url}/memwarden/livez`);
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ensure the daemon at `url` is up, spawning it if not. Idempotent and
+ * race-safe: concurrent callers may both spawn, but the daemon exits 0 on
+ * EADDRINUSE (see index.ts) so the loser simply goes away and the winner
+ * serves. Returns once the daemon answers /livez or the timeout elapses.
+ */
+export async function ensureDaemon(url, dataDir = defaultDataDir(), timeoutMs = 15000) {
+    if (await daemonAlive(url))
+        return "already";
+    // libSQL won't create the data directory; make it so the daemon can open
+    // its db instead of crashing on boot.
+    mkdirSync(dataDir, { recursive: true });
+    const child = spawn(process.execPath, [DAEMON_ENTRY], {
+        detached: true,
+        stdio: "ignore",
+        env: { ...process.env, MEMWARDEN_DATA_DIR: dataDir },
+    });
+    child.unref();
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        await sleep(250);
+        if (await daemonAlive(url))
+            return "started";
+    }
+    return "failed";
+}

package/dist/daemon/service.d.ts

@@ -0,0 +1,15 @@
+export interface ServiceResult {
+    kind: "launchd" | "systemd" | "unsupported";
+    ok: boolean;
+    path?: string;
+    message: string;
+}
+/**
+ * Install + start the supervised daemon for this platform. Best-effort. When
+ * `secret` is provided it is baked into the service environment so the
+ * login-launched daemon enforces auth (otherwise a managed daemon would run
+ * open even though the CLI generated a secret).
+ */
+export declare function installService(dataDir: string, secret?: string): ServiceResult;
+/** Stop + remove the supervised daemon. Best-effort. */
+export declare function uninstallService(): ServiceResult;

package/dist/daemon/service.js

@@ -0,0 +1,210 @@
+//
+// OS service installer — the crash/reboot self-heal. Registers the daemon
+// with the platform supervisor so it starts at login and restarts if it
+// dies, with no human in the loop:
+//   macOS  ~/Library/LaunchAgents/ai.memwarden.daemon.plist  (launchd)
+//   Linux  ~/.config/systemd/user/memwarden.service          (systemd --user)
+//
+// KeepAlive/Restart are set to "restart on FAILURE only" (SuccessfulExit
+// false / on-failure). That pairs with the daemon's clean exit(0) on
+// EADDRINUSE: if another instance already holds the port, the supervised one
+// exits cleanly and is NOT relaunched (no crash loop); a real crash (non-zero
+// exit) IS relaunched. Best-effort: any failure returns ok:false so `up`
+// falls back to a detached spawn.
+import { execFileSync } from "node:child_process";
+import { chmodSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { DAEMON_ENTRY } from "./ensure.js";
+const LABEL = "ai.memwarden.daemon";
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function plistPath(home) {
+    return join(home, "Library", "LaunchAgents", `${LABEL}.plist`);
+}
+function systemdPath(home) {
+    return join(home, ".config", "systemd", "user", "memwarden.service");
+}
+// XML-escape a value before interpolating it into the plist (the secret is
+// base64url so it has no XML metacharacters, but be defensive).
+function xmlEscape(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+function macPlist(node, dataDir, secret) {
+    const log = join(dataDir, "daemon.log");
+    // The managed daemon resolves its auth secret from MEMWARDEN_SECRET, so it
+    // must be in the service environment or a login-launched daemon would run
+    // open. Only emitted when a secret was resolved.
+    const secretEntry = secret
+        ? `\n    <key>MEMWARDEN_SECRET</key><string>${xmlEscape(secret)}</string>`
+        : "";
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${node}</string>
+    <string>${DAEMON_ENTRY}</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>MEMWARDEN_DATA_DIR</key><string>${dataDir}</string>${secretEntry}
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key>
+  <dict><key>SuccessfulExit</key><false/></dict>
+  <key>StandardOutPath</key><string>${log}</string>
+  <key>StandardErrorPath</key><string>${log}</string>
+</dict>
+</plist>
+`;
+}
+function systemdUnit(node, dataDir, secret) {
+    // Same reason as the plist: the managed daemon needs MEMWARDEN_SECRET in its
+    // environment to enforce auth. Only emitted when a secret was resolved.
+    const secretEnv = secret
+        ? `\nEnvironment=MEMWARDEN_SECRET=${secret}`
+        : "";
+    return `[Unit]
+Description=memwarden memory daemon
+After=network.target
+
+[Service]
+ExecStart=${node} ${DAEMON_ENTRY}
+Environment=MEMWARDEN_DATA_DIR=${dataDir}${secretEnv}
+Restart=on-failure
+RestartSec=2
+
+[Install]
+WantedBy=default.target
+`;
+}
+/**
+ * Install + start the supervised daemon for this platform. Best-effort. When
+ * `secret` is provided it is baked into the service environment so the
+ * login-launched daemon enforces auth (otherwise a managed daemon would run
+ * open even though the CLI generated a secret).
+ */
+export function installService(dataDir, secret) {
+    const home = homedir();
+    const node = process.execPath;
+    try {
+        mkdirSync(dataDir, { recursive: true });
+    }
+    catch {
+        // non-fatal; the write below will surface a real error if the dir is bad
+    }
+    if (process.platform === "darwin") {
+        const path = plistPath(home);
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, macPlist(node, dataDir, secret), "utf8");
+            // Lock the plist down: it now carries the secret in plaintext.
+            try {
+                chmodSync(path, 0o600);
+            }
+            catch {
+                // best-effort
+            }
+            try {
+                execFileSync("launchctl", ["unload", path], { stdio: "ignore" });
+            }
+            catch {
+                // not previously loaded — fine
+            }
+            execFileSync("launchctl", ["load", "-w", path], { stdio: "ignore" });
+            return {
+                kind: "launchd",
+                ok: true,
+                path,
+                message: "starts at login, restarts on crash",
+            };
+        }
+        catch (err) {
+            return { kind: "launchd", ok: false, path, message: errMsg(err) };
+        }
+    }
+    if (process.platform === "linux") {
+        const path = systemdPath(home);
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, systemdUnit(node, dataDir, secret), "utf8");
+            // Lock the unit down: it now carries the secret in plaintext.
+            try {
+                chmodSync(path, 0o600);
+            }
+            catch {
+                // best-effort
+            }
+            execFileSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
+            execFileSync("systemctl", ["--user", "enable", "--now", "memwarden"], {
+                stdio: "ignore",
+            });
+            return {
+                kind: "systemd",
+                ok: true,
+                path,
+                message: "starts at login, restarts on crash",
+            };
+        }
+        catch (err) {
+            return { kind: "systemd", ok: false, path, message: errMsg(err) };
+        }
+    }
+    return {
+        kind: "unsupported",
+        ok: false,
+        message: `no supported service manager for ${process.platform}`,
+    };
+}
+/** Stop + remove the supervised daemon. Best-effort. */
+export function uninstallService() {
+    const home = homedir();
+    if (process.platform === "darwin") {
+        const path = plistPath(home);
+        try {
+            try {
+                execFileSync("launchctl", ["unload", path], { stdio: "ignore" });
+            }
+            catch {
+                // not loaded
+            }
+            rmSync(path, { force: true });
+            return { kind: "launchd", ok: true, path, message: "removed" };
+        }
+        catch (err) {
+            return { kind: "launchd", ok: false, path, message: errMsg(err) };
+        }
+    }
+    if (process.platform === "linux") {
+        const path = systemdPath(home);
+        try {
+            try {
+                execFileSync("systemctl", ["--user", "disable", "--now", "memwarden"], {
+                    stdio: "ignore",
+                });
+            }
+            catch {
+                // not enabled
+            }
+            rmSync(path, { force: true });
+            return { kind: "systemd", ok: true, path, message: "removed" };
+        }
+        catch (err) {
+            return { kind: "systemd", ok: false, path, message: errMsg(err) };
+        }
+    }
+    return {
+        kind: "unsupported",
+        ok: false,
+        message: `no supported service manager for ${process.platform}`,
+    };
+}

package/dist/embedding/index.d.ts

@@ -0,0 +1,10 @@
+import type { EmbeddingProvider } from "../functions/types.js";
+export { LocalEmbeddingProvider } from "./local-embedding.js";
+export declare function getEmbeddingProviderName(): "local" | "none";
+export declare function getEmbeddingModel(): string;
+/**
+ * Build the configured embedding provider, or null for BM25-only mode.
+ * Construction is cheap (no model load); the model loads lazily on first
+ * embed, or eagerly via warmup() at boot.
+ */
+export declare function createEmbeddingProvider(): EmbeddingProvider | null;

package/dist/embedding/index.js

@@ -0,0 +1,33 @@
+//
+// Embedding provider selection. memwarden's vector stream (and therefore
+// the TurboQuant-compressed semantic memory that distinguishes it) only
+// lights up when a provider is configured here.
+//
+//   MEMWARDEN_EMBEDDING_PROVIDER = local (default) | none
+//   MEMWARDEN_EMBEDDING_MODEL    = Xenova/all-MiniLM-L6-v2 (default)
+//
+// "local" runs entirely on-device (see local-embedding.ts). "none" keeps
+// memwarden in BM25-only mode. Cloud providers (openai, voyage) can be
+// added here later behind the same interface without touching callers.
+import { LocalEmbeddingProvider } from "./local-embedding.js";
+export { LocalEmbeddingProvider } from "./local-embedding.js";
+export function getEmbeddingProviderName() {
+    const raw = (process.env.MEMWARDEN_EMBEDDING_PROVIDER ?? "local")
+        .trim()
+        .toLowerCase();
+    return raw === "none" ? "none" : "local";
+}
+export function getEmbeddingModel() {
+    const raw = process.env.MEMWARDEN_EMBEDDING_MODEL?.trim();
+    return raw && raw.length > 0 ? raw : "Xenova/all-MiniLM-L6-v2";
+}
+/**
+ * Build the configured embedding provider, or null for BM25-only mode.
+ * Construction is cheap (no model load); the model loads lazily on first
+ * embed, or eagerly via warmup() at boot.
+ */
+export function createEmbeddingProvider() {
+    if (getEmbeddingProviderName() === "none")
+        return null;
+    return new LocalEmbeddingProvider(getEmbeddingModel());
+}

package/dist/embedding/local-embedding.d.ts

@@ -0,0 +1,14 @@
+import type { EmbeddingProvider } from "../functions/types.js";
+export declare class LocalEmbeddingProvider implements EmbeddingProvider {
+    readonly name: string;
+    readonly dimensions: number;
+    private model;
+    private extractor;
+    private loading;
+    constructor(model?: string);
+    private ensure;
+    /** Warm the model so the first observe/search doesn't pay the load. */
+    warmup(): Promise<void>;
+    embed(text: string): Promise<Float32Array>;
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+}

package/dist/embedding/local-embedding.js

@@ -0,0 +1,80 @@
+//
+// Local, in-process embedding provider. Runs a sentence-transformer
+// (all-MiniLM-L6-v2, 384-dim) through transformers.js on the WASM/WebGPU
+// backend — no Python, no CUDA, no native compilation, so it preserves
+// memwarden's zero-native-dependency, self-custody promise. The model
+// (~23MB ONNX) is downloaded once on first use and cached on disk.
+//
+// transformers.js is an OPTIONAL dependency, loaded lazily via a dynamic
+// import with a variable specifier so the core typechecks and the test
+// suite runs without it installed. If it is absent, embed() throws a clear
+// message and the vector stream stays off (BM25 keeps working) — the
+// guarded add path in search.ts soft-fails, it never breaks observe.
+const DEFAULT_MODEL = "Xenova/all-MiniLM-L6-v2";
+const MINILM_DIMS = 384;
+// Known output dimensions for the models we ship as presets. Anything else
+// is probed from the first embedding.
+const KNOWN_DIMS = {
+    "Xenova/all-MiniLM-L6-v2": 384,
+    "Xenova/bge-small-en-v1.5": 384,
+    "Xenova/nomic-embed-text-v1": 768,
+};
+export class LocalEmbeddingProvider {
+    name;
+    dimensions;
+    model;
+    extractor = null;
+    loading = null;
+    constructor(model = DEFAULT_MODEL) {
+        this.model = model;
+        this.name = `local:${model}`;
+        this.dimensions = KNOWN_DIMS[model] ?? MINILM_DIMS;
+    }
+    // Lazily construct the feature-extraction pipeline. The import uses a
+    // variable specifier on purpose: it keeps tsc from resolving the optional
+    // package at build time and isolates the heavy load to first use.
+    async ensure() {
+        if (this.extractor)
+            return this.extractor;
+        if (!this.loading) {
+            this.loading = (async () => {
+                const specifier = "@huggingface/transformers";
+                let mod;
+                try {
+                    mod = (await import(specifier));
+                }
+                catch {
+                    throw new Error("Local embeddings require the optional '@huggingface/transformers' package. " +
+                        "Install it with: npm install @huggingface/transformers");
+                }
+                const pipeline = mod.pipeline;
+                if (typeof pipeline !== "function") {
+                    throw new Error("@huggingface/transformers did not export a usable 'pipeline'");
+                }
+                const extractor = await pipeline("feature-extraction", this.model);
+                this.extractor = extractor;
+                return extractor;
+            })();
+        }
+        return this.loading;
+    }
+    /** Warm the model so the first observe/search doesn't pay the load. */
+    async warmup() {
+        await this.ensure();
+    }
+    async embed(text) {
+        const extractor = await this.ensure();
+        const out = await extractor(text, { pooling: "mean", normalize: true });
+        const row = out.tolist()[0];
+        if (!row)
+            throw new Error("embedding extraction returned no rows");
+        return Float32Array.from(row);
+    }
+    async embedBatch(texts) {
+        if (texts.length === 0)
+            return [];
+        const extractor = await this.ensure();
+        const out = await extractor(texts, { pooling: "mean", normalize: true });
+        return out.tolist().map((row) => Float32Array.from(row));
+    }
+}

package/dist/functions/access-tracker.d.ts

@@ -0,0 +1,13 @@
+import type { StateKV } from "../state/kv.js";
+export interface AccessLog {
+    memoryId: string;
+    count: number;
+    lastAt: string;
+    recent: number[];
+}
+export declare function emptyAccessLog(memoryId: string): AccessLog;
+export declare function normalizeAccessLog(raw: unknown): AccessLog;
+export declare function getAccessLog(kv: StateKV, memoryId: string): Promise<AccessLog>;
+export declare function recordAccess(kv: StateKV, memoryId: string, timestampMs?: number): Promise<void>;
+export declare function recordAccessBatch(kv: StateKV, memoryIds: string[], timestampMs?: number): Promise<void>;
+export declare function deleteAccessLog(kv: StateKV, memoryId: string): Promise<void>;

package/dist/functions/access-tracker.js

@@ -0,0 +1,92 @@
+//
+// Access-frequency tracking for retention scoring. search.ts and context.ts
+// call recordAccessBatch fire-and-forget after assembling results, so later
+// retention/decay can weight memories by how recently they were used. Each
+// per-memory write is serialized through the keyed mutex, and every failure is
+// swallowed: access tracking must never break a read.
+import { KV } from "../state/schema.js";
+import { withKeyedLock } from "./keyed-mutex.js";
+import { logger } from "./logger.js";
+const RECENT_CAP = 20;
+export function emptyAccessLog(memoryId) {
+    return { memoryId, count: 0, lastAt: "", recent: [] };
+}
+export function normalizeAccessLog(raw) {
+    const r = (raw ?? {});
+    const count = typeof r.count === "number" && Number.isFinite(r.count)
+        ? Math.max(0, Math.floor(r.count))
+        : 0;
+    const recentAll = Array.isArray(r.recent)
+        ? r.recent.filter((n) => typeof n === "number" && Number.isFinite(n))
+        : [];
+    const recent = recentAll.slice(-RECENT_CAP);
+    return {
+        memoryId: typeof r.memoryId === "string" ? r.memoryId : "",
+        // count can never be below the number of timestamps we actually hold
+        count: Math.max(count, recent.length),
+        lastAt: typeof r.lastAt === "string" ? r.lastAt : "",
+        recent,
+    };
+}
+export async function getAccessLog(kv, memoryId) {
+    try {
+        const raw = await kv.get(KV.accessLog, memoryId);
+        if (!raw)
+            return emptyAccessLog(memoryId);
+        const log = normalizeAccessLog(raw);
+        if (!log.memoryId)
+            log.memoryId = memoryId;
+        return log;
+    }
+    catch {
+        return emptyAccessLog(memoryId);
+    }
+}
+function keyFor(memoryId) {
+    return `mem:access:${memoryId}`;
+}
+export async function recordAccess(kv, memoryId, timestampMs) {
+    if (!memoryId)
+        return;
+    const ts = timestampMs ?? Date.now();
+    try {
+        await withKeyedLock(keyFor(memoryId), async () => {
+            const log = await getAccessLog(kv, memoryId);
+            log.count += 1;
+            log.lastAt = new Date(ts).toISOString();
+            log.recent.push(ts);
+            if (log.recent.length > RECENT_CAP) {
+                log.recent = log.recent.slice(-RECENT_CAP);
+            }
+            await kv.set(KV.accessLog, memoryId, log);
+        });
+    }
+    catch (err) {
+        try {
+            logger.warn("recordAccess failed", {
+                memoryId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        catch {
+            // the side path must never throw
+        }
+    }
+}
+export async function recordAccessBatch(kv, memoryIds, timestampMs) {
+    if (!memoryIds || memoryIds.length === 0)
+        return;
+    const ts = timestampMs ?? Date.now();
+    const ids = [...new Set(memoryIds.filter(Boolean))];
+    await Promise.allSettled(ids.map((id) => recordAccess(kv, id, ts)));
+}
+export async function deleteAccessLog(kv, memoryId) {
+    if (!memoryId)
+        return;
+    try {
+        await withKeyedLock(keyFor(memoryId), () => kv.delete(KV.accessLog, memoryId));
+    }
+    catch {
+        // best-effort, idempotent
+    }
+}

package/dist/functions/audit.d.ts

@@ -0,0 +1,46 @@
+export type StoreKind = "sqlite" | "markdown" | "json";
+export interface ForeignMemory {
+    id: string;
+    title: string;
+    text: string;
+    /** File references found in (or stored alongside) the memory. */
+    files: string[];
+    /** ISO timestamp when the memory was recorded, if the store has one. */
+    timestamp?: string;
+    /** Where in the store this came from (table, file, array index). */
+    origin: string;
+}
+export type AuditStatus = "missing" | "drifted" | "present" | "unanchored";
+export interface AuditFinding {
+    id: string;
+    title: string;
+    origin: string;
+    status: AuditStatus;
+    detail: string;
+}
+export interface AuditReport {
+    store: string;
+    kind: StoreKind;
+    root: string;
+    total: number;
+    /** Number of memories that carried at least one checkable file reference. */
+    anchored: number;
+    uniqueFiles: number;
+    missing: AuditFinding[];
+    drifted: AuditFinding[];
+    present: number;
+    unanchored: number;
+    /** True when at least one memory had a timestamp, so drift was checkable. */
+    driftCheckable: boolean;
+}
+/** Extract file references from free text. Exported for tests. */
+export declare function extractFileRefs(text: string): {
+    pathRefs: string[];
+    bareRefs: string[];
+};
+export declare function detectStoreKind(path: string): StoreKind;
+export declare function loadStore(path: string): Promise<{
+    kind: StoreKind;
+    memories: ForeignMemory[];
+}>;
+export declare function auditStore(storePath: string, root: string): Promise<AuditReport>;

package/dist/functions/cjk-segmenter.d.ts

@@ -0,0 +1,6 @@
+type Script = "han" | "kana" | "hangul" | "other";
+export declare function hasCjk(text: string): boolean;
+export declare function detectScript(text: string): Script;
+export declare function segmentCjk(text: string): string[];
+export declare function __resetCjkSegmenterStateForTests(): void;
+export {};