memwarden 0.0.1

package/dist/functions/cjk-segmenter.js

@@ -0,0 +1,120 @@
+//
+// CJK-aware segmentation for the BM25 tokenizer. CJK text has no spaces, so a
+// run of Han/Kana/Hangul is segmented before tokenizing. Chinese and Japanese
+// use optional native segmenters (@node-rs/jieba, tiny-segmenter) loaded
+// lazily via createRequire; when they are absent the run is kept whole (search
+// still works, just coarser) so there are no required new dependencies. Korean
+// is split into Hangul blocks with a plain regex (no dependency).
+import { createRequire } from "node:module";
+const req = createRequire(import.meta.url);
+const ANY_CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u;
+const HAN = /\p{Script=Han}/u;
+const KANA = /[\p{Script=Hiragana}\p{Script=Katakana}]/u;
+const HANGUL = /\p{Script=Hangul}/u;
+const CJK_RUN = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]+/gu;
+const HANGUL_BLOCK = /[가-힯]+/g;
+export function hasCjk(text) {
+    return ANY_CJK.test(text);
+}
+export function detectScript(text) {
+    if (HAN.test(text))
+        return "han";
+    if (KANA.test(text))
+        return "kana";
+    if (HANGUL.test(text))
+        return "hangul";
+    return "other";
+}
+const hinted = new Set();
+function hintOnce(key, message) {
+    if (hinted.has(key))
+        return;
+    hinted.add(key);
+    process?.stderr?.write?.(`memwarden: ${message}\n`);
+}
+const loaded = new Map();
+function loadJieba() {
+    if (loaded.has("jieba"))
+        return loaded.get("jieba") ?? null;
+    let cut = null;
+    try {
+        const mod = req("@node-rs/jieba");
+        let inst;
+        try {
+            inst = mod.Jieba.withDict(req("@node-rs/jieba/dict").dict);
+        }
+        catch {
+            inst = new mod.Jieba();
+        }
+        cut = (t) => inst.cut(t, true);
+    }
+    catch {
+        hintOnce("jieba", "install @node-rs/jieba to improve Chinese search; using whole-string tokens for now");
+    }
+    loaded.set("jieba", cut);
+    return cut;
+}
+function loadJa() {
+    if (loaded.has("ja"))
+        return loaded.get("ja") ?? null;
+    let cut = null;
+    try {
+        const Ctor = req("tiny-segmenter");
+        const inst = new Ctor();
+        cut = (t) => inst.segment(t);
+    }
+    catch {
+        hintOnce("tiny-segmenter", "install tiny-segmenter to improve Japanese search; using whole-string tokens for now");
+    }
+    loaded.set("ja", cut);
+    return cut;
+}
+function nonEmpty(tokens) {
+    const out = [];
+    for (const t of tokens) {
+        const v = t.trim();
+        if (v)
+            out.push(v);
+    }
+    return out;
+}
+function segmentRun(run) {
+    if (HANGUL.test(run)) {
+        return [...run.matchAll(HANGUL_BLOCK)].map((m) => m[0]);
+    }
+    const cut = KANA.test(run) ? loadJa() : loadJieba();
+    if (!cut)
+        return [run];
+    try {
+        return nonEmpty(cut(run));
+    }
+    catch {
+        return [run];
+    }
+}
+export function segmentCjk(text) {
+    if (!hasCjk(text))
+        return [text];
+    const out = [];
+    let at = 0;
+    for (const m of text.matchAll(CJK_RUN)) {
+        const start = m.index ?? 0;
+        if (start > at) {
+            const gap = text.slice(at, start).trim();
+            if (gap)
+                out.push(gap);
+        }
+        out.push(...segmentRun(m[0]));
+        at = start + m[0].length;
+    }
+    if (at < text.length) {
+        const tail = text.slice(at).trim();
+        if (tail)
+            out.push(tail);
+    }
+    return out;
+}
+export function __resetCjkSegmenterStateForTests() {
+    hinted.clear();
+    loaded.clear();
+}

package/dist/functions/compress-synthetic.d.ts

@@ -0,0 +1,2 @@
+import type { RawObservation, CompressedObservation } from "./types.js";
+export declare function buildSyntheticCompression(raw: RawObservation): CompressedObservation;

package/dist/functions/compress-synthetic.js

@@ -0,0 +1,104 @@
+//
+// Zero-LLM compression: turn a RawObservation into a CompressedObservation
+// with heuristics only (no model call, no token spend). This is the default
+// observe path until an LLM provider is wired in. It classifies the tool,
+// pulls out any file paths, and builds a short narrative.
+// tool-name keyword -> observation type, in priority order
+const TOOL_KINDS = [
+    ["web_fetch", ["fetch", "http", "web"]],
+    ["search", ["grep", "search", "glob", "find"]],
+    ["command_run", ["bash", "shell", "exec", "run"]],
+    ["file_edit", ["edit", "update", "patch", "replace"]],
+    ["file_write", ["write", "create"]],
+    ["file_read", ["read", "view"]],
+    ["subagent", ["task", "agent"]],
+];
+const FILE_KEYS = ["file_path", "filepath", "path", "filePath", "file", "pattern"];
+// split camelCase / kebab / spaces into a normalized underscore form
+function normalizeToolName(name) {
+    return name
+        .replace(/([a-z])([A-Z])/g, "$1_$2")
+        .replace(/[-\s]+/g, "_")
+        .toLowerCase();
+}
+function mentions(normalized, word) {
+    return (new RegExp(`(^|_)${word}(_|$)`).test(normalized) ||
+        normalized === word ||
+        normalized.startsWith(word) ||
+        normalized.endsWith(word));
+}
+function classify(toolName, hookType) {
+    if (hookType === "post_tool_failure")
+        return "error";
+    if (hookType === "prompt_submit")
+        return "conversation";
+    if (hookType === "subagent_stop" || hookType === "task_completed")
+        return "subagent";
+    if (hookType === "notification")
+        return "notification";
+    if (!toolName)
+        return "other";
+    const n = normalizeToolName(toolName);
+    for (const [kind, words] of TOOL_KINDS) {
+        if (words.some((w) => mentions(n, w)))
+            return kind;
+    }
+    return "other";
+}
+function filePaths(input) {
+    if (!input || typeof input !== "object")
+        return [];
+    const o = input;
+    const found = new Set();
+    for (const key of FILE_KEYS) {
+        const v = o[key];
+        if (typeof v === "string" && v.length > 0 && v.length < 512)
+            found.add(v);
+    }
+    return [...found];
+}
+function asText(v) {
+    if (v == null)
+        return "";
+    if (typeof v === "string")
+        return v;
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+function clip(s, max) {
+    return s.length > max ? s.slice(0, max - 1) + "…" : s;
+}
+export function buildSyntheticCompression(raw) {
+    const toolName = raw.toolName ?? raw.hookType;
+    const inputText = asText(raw.toolInput);
+    const outputText = asText(raw.toolOutput);
+    const narrative = [raw.userPrompt ?? "", inputText, outputText]
+        .filter((s) => s.length > 0)
+        .join(" | ");
+    const result = {
+        id: raw.id,
+        sessionId: raw.sessionId,
+        timestamp: raw.timestamp,
+        type: classify(toolName, raw.hookType),
+        title: clip(toolName || "observation", 80),
+        facts: [],
+        narrative: clip(narrative, 400),
+        concepts: [],
+        files: filePaths(raw.toolInput),
+        importance: 5,
+        confidence: 0.3,
+    };
+    if (inputText)
+        result.subtitle = clip(inputText, 120);
+    if (raw.modality)
+        result.modality = raw.modality;
+    if (raw.imageData)
+        result.imageData = raw.imageData;
+    if (raw.agentId)
+        result.agentId = raw.agentId;
+    return result;
+}

package/dist/functions/config.d.ts

@@ -0,0 +1,68 @@
+/** Default per-request context token budget. */
+export declare function getTokenBudget(): number;
+/** Max observations retained per session before mem::observe refuses more. */
+export declare function getMaxObservationsPerSession(): number;
+/**
+ * The session's agentId source when no session row exists yet. Trimmed and
+ * capped at 128 chars.
+ */
+export declare function getAgentId(): string | undefined;
+/**
+ * Per-observation LLM compression is opt-in. When false (the default)
+ * mem::observe takes the zero-LLM synthetic-compression path. No LLM
+ * provider is wired in the core, so this is effectively always false here,
+ * but the flag is reserved for when the model layer lands.
+ */
+export declare function isAutoCompressEnabled(): boolean;
+/** Memory slots are an optional context-injection feature, off by default. */
+export declare function isSlotsEnabled(): boolean;
+/** Auto-injection (SessionStart hook, Déjà Fix hook, proxy). Default on. */
+export declare function isInjectEnabled(): boolean;
+/** Auto-capture (PostToolUse hook, proxy tee). Default on. */
+export declare function isCaptureEnabled(): boolean;
+/** Where the brain lives. */
+export declare function getDataDir(): string;
+/**
+ * Per-project exclusion: `<dataDir>/excluded` holds one absolute path per
+ * line (written by `memwarden exclude`). A cwd inside any excluded path is
+ * excluded — capture AND injection, every automatic surface, so an excluded
+ * project never reaches the brain and the brain never reaches it. Read on
+ * every call (the file is tiny and the daemon is long-lived; a stale cache
+ * here would mean "exclude" takes effect only on restart — the classic
+ * excluded-but-not-really bug).
+ */
+export declare function isProjectExcluded(cwd: string | undefined): boolean;
+/**
+ * The shared secret used by the api-auth middleware. When unset (no env var and
+ * no persisted secret file) the API is open (absent secret = continue). The
+ * daemon and every local client resolve it identically through this function.
+ */
+export declare function getSecret(): string | undefined;
+/**
+ * TurboQuant vector quantization (arXiv:2504.19874): the vector index
+ * stores 2/4-bit codes instead of full Float32 embeddings (~8-16x smaller).
+ * This is memwarden's distinguishing storage layer, so it is ON BY DEFAULT
+ * whenever an embedding provider is active — there is no reason to hold
+ * full-precision vectors once semantic memory is on. Set
+ * MEMWARDEN_QUANT_VECTOR=false to force the full-precision baseline, or
+ * =true to force it on even without a provider (e.g. tests).
+ */
+export declare function isQuantizedVectorEnabled(): boolean;
+/** Bits per dimension for the quantized index. 4 (default) or 2. */
+export declare function getQuantBits(): 2 | 4;
+/**
+ * Rescore depth: how many asymmetric-pass candidates get re-ranked with
+ * exact cosine. 0 (default) disables rescore and drops full vectors from
+ * memory entirely — the max-compression configuration.
+ */
+export declare function getQuantRescoreDepth(): number;
+/** Rotation seed; same seed reproduces the identical rotation everywhere. */
+export declare function getQuantSeed(): string;
+/** Upstream OpenAI-compatible base URL, e.g. https://api.openai.com/v1. */
+export declare function getUpstreamUrl(): string | undefined;
+/** API key forwarded to the upstream as `Authorization: Bearer`. */
+export declare function getUpstreamKey(): string | undefined;
+/** Port the memory proxy listens on. Defaults to 3113. */
+export declare function getProxyPort(): number;
+/** The proxy runs only once an upstream is configured to forward to. */
+export declare function isProxyEnabled(): boolean;

package/dist/functions/config.js

@@ -0,0 +1,231 @@
+//
+// Config shim. Reads process.env directly; only the handful of
+// flags the core functions consult are modelled here.
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { canonicalizePath } from "./paths.js";
+function env(name) {
+    const v = process.env[name];
+    return v !== undefined ? v : undefined;
+}
+function flag(name) {
+    return env(name) === "true";
+}
+/** Default per-request context token budget. */
+export function getTokenBudget() {
+    const raw = env("MEMWARDEN_TOKEN_BUDGET");
+    if (!raw)
+        return 2000;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : 2000;
+}
+/** Max observations retained per session before mem::observe refuses more. */
+export function getMaxObservationsPerSession() {
+    const raw = env("MEMWARDEN_MAX_OBSERVATIONS_PER_SESSION");
+    if (!raw)
+        return 10000;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : 10000;
+}
+/**
+ * The session's agentId source when no session row exists yet. Trimmed and
+ * capped at 128 chars.
+ */
+export function getAgentId() {
+    const raw = env("MEMWARDEN_AGENT_ID");
+    if (!raw)
+        return undefined;
+    const agentId = raw.trim().slice(0, 128);
+    return agentId || undefined;
+}
+/**
+ * Per-observation LLM compression is opt-in. When false (the default)
+ * mem::observe takes the zero-LLM synthetic-compression path. No LLM
+ * provider is wired in the core, so this is effectively always false here,
+ * but the flag is reserved for when the model layer lands.
+ */
+export function isAutoCompressEnabled() {
+    return flag("MEMWARDEN_AUTO_COMPRESS");
+}
+/** Memory slots are an optional context-injection feature, off by default. */
+export function isSlotsEnabled() {
+    return flag("MEMWARDEN_SLOTS");
+}
+// --- injection / capture switches -----------------------------------
+//
+// Users must be able to turn the automatic paths off — per environment via
+// MEMWARDEN_INJECT / MEMWARDEN_CAPTURE, and per project via the excluded
+// list. The switches gate the AUTOMATIC paths only (hooks, proxy); explicit
+// asks (/recall, the MCP tools, the CLI) always work — turning off
+// auto-inject must not lobotomize deliberate recall.
+function offFlag(name) {
+    const v = (env(name) ?? "").trim().toLowerCase();
+    return v === "off" || v === "false" || v === "0";
+}
+/** Auto-injection (SessionStart hook, Déjà Fix hook, proxy). Default on. */
+export function isInjectEnabled() {
+    return !offFlag("MEMWARDEN_INJECT");
+}
+/** Auto-capture (PostToolUse hook, proxy tee). Default on. */
+export function isCaptureEnabled() {
+    return !offFlag("MEMWARDEN_CAPTURE");
+}
+/** Where the brain lives. */
+export function getDataDir() {
+    return env("MEMWARDEN_DATA_DIR") ?? join(homedir(), ".memwarden");
+}
+/**
+ * Per-project exclusion: `<dataDir>/excluded` holds one absolute path per
+ * line (written by `memwarden exclude`). A cwd inside any excluded path is
+ * excluded — capture AND injection, every automatic surface, so an excluded
+ * project never reaches the brain and the brain never reaches it. Read on
+ * every call (the file is tiny and the daemon is long-lived; a stale cache
+ * here would mean "exclude" takes effect only on restart — the classic
+ * excluded-but-not-really bug).
+ */
+export function isProjectExcluded(cwd) {
+    if (!cwd)
+        return false;
+    let lines;
+    try {
+        const path = join(getDataDir(), "excluded");
+        if (!existsSync(path))
+            return false;
+        lines = readFileSync(path, "utf8").split("\n");
+    }
+    catch {
+        return false;
+    }
+    // Canonicalize both sides so /tmp vs /private/tmp (and trailing-slash)
+    // spellings of the same directory still match — the same rule recall
+    // scoping uses (see paths.ts).
+    const target = canonicalizePath(cwd);
+    if (!target)
+        return false;
+    for (const line of lines) {
+        const raw = line.trim();
+        if (!raw || raw.startsWith("#"))
+            continue;
+        const ex = canonicalizePath(raw);
+        if (!ex)
+            continue;
+        if (target === ex || target.startsWith(ex.endsWith("/") ? ex : ex + "/"))
+            return true;
+    }
+    return false;
+}
+// The CLI (`memwarden up`) persists the generated secret to <dataDir>/secret.
+// The daemon spawned by `up` inherits MEMWARDEN_SECRET via env, but short-lived
+// clients launched by the agent host — the Claude Code hook runs in the user's
+// shell, manually-started MCP servers — won't have that env. Without a fallback
+// they'd call a secured daemon with no Bearer and silently 401 (auto-recall dies
+// with no error). So resolution is: env first, then the persisted secret file.
+// Read the file at most once per process (the secret is stable for its lifetime).
+let cachedFileSecret = null; // null = not yet read
+function persistedSecret() {
+    if (cachedFileSecret !== null)
+        return cachedFileSecret;
+    cachedFileSecret = undefined;
+    try {
+        const dataDir = env("MEMWARDEN_DATA_DIR") ?? join(homedir(), ".memwarden");
+        const path = join(dataDir, "secret");
+        if (existsSync(path)) {
+            const s = readFileSync(path, "utf8").trim();
+            if (s)
+                cachedFileSecret = s;
+        }
+    }
+    catch {
+        // Best-effort: an unreadable/absent file leaves the API open, exactly as
+        // before this fallback existed.
+    }
+    return cachedFileSecret;
+}
+/**
+ * The shared secret used by the api-auth middleware. When unset (no env var and
+ * no persisted secret file) the API is open (absent secret = continue). The
+ * daemon and every local client resolve it identically through this function.
+ */
+export function getSecret() {
+    const fromEnv = env("MEMWARDEN_SECRET");
+    if (fromEnv && fromEnv.trim())
+        return fromEnv.trim();
+    return persistedSecret();
+}
+/**
+ * TurboQuant vector quantization (arXiv:2504.19874): the vector index
+ * stores 2/4-bit codes instead of full Float32 embeddings (~8-16x smaller).
+ * This is memwarden's distinguishing storage layer, so it is ON BY DEFAULT
+ * whenever an embedding provider is active — there is no reason to hold
+ * full-precision vectors once semantic memory is on. Set
+ * MEMWARDEN_QUANT_VECTOR=false to force the full-precision baseline, or
+ * =true to force it on even without a provider (e.g. tests).
+ */
+export function isQuantizedVectorEnabled() {
+    const raw = env("MEMWARDEN_QUANT_VECTOR");
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    // Unset: follow the embedding provider. Read the env directly to avoid a
+    // config<->embedding import cycle.
+    const provider = (process.env.MEMWARDEN_EMBEDDING_PROVIDER ?? "local")
+        .trim()
+        .toLowerCase();
+    return provider !== "none";
+}
+/** Bits per dimension for the quantized index. 4 (default) or 2. */
+export function getQuantBits() {
+    return env("MEMWARDEN_QUANT_BITS") === "2" ? 2 : 4;
+}
+/**
+ * Rescore depth: how many asymmetric-pass candidates get re-ranked with
+ * exact cosine. 0 (default) disables rescore and drops full vectors from
+ * memory entirely — the max-compression configuration.
+ */
+export function getQuantRescoreDepth() {
+    const raw = env("MEMWARDEN_QUANT_RESCORE");
+    if (!raw)
+        return 0;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : 0;
+}
+/** Rotation seed; same seed reproduces the identical rotation everywhere. */
+export function getQuantSeed() {
+    return env("MEMWARDEN_QUANT_SEED") ?? "memwarden-tq-v1";
+}
+// --- memory proxy (the universal cross-tool layer) -----------------
+//
+// The OpenAI-compatible gateway. Any tool that lets you point at a custom
+// base URL — Cursor, Continue, Cline, raw SDK apps — routes its model
+// calls through memwarden, which injects relevant memory and captures the
+// exchange. The model behind it can be local (Ollama :11434/v1, LM Studio
+// :1234/v1) or paid (OpenAI, OpenRouter, Together); the proxy is blind to
+// which, so it is one memory layer for all of them. The proxy is OFF until
+// an upstream is configured (it has nothing to forward to otherwise).
+/** Upstream OpenAI-compatible base URL, e.g. https://api.openai.com/v1. */
+export function getUpstreamUrl() {
+    const raw = env("MEMWARDEN_UPSTREAM_URL");
+    if (!raw)
+        return undefined;
+    const trimmed = raw.trim().replace(/\/+$/, "");
+    return trimmed || undefined;
+}
+/** API key forwarded to the upstream as `Authorization: Bearer`. */
+export function getUpstreamKey() {
+    const raw = env("MEMWARDEN_UPSTREAM_KEY");
+    return raw && raw.trim() ? raw.trim() : undefined;
+}
+/** Port the memory proxy listens on. Defaults to 3113. */
+export function getProxyPort() {
+    const raw = env("MEMWARDEN_PROXY_PORT");
+    if (!raw)
+        return 3113;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : 3113;
+}
+/** The proxy runs only once an upstream is configured to forward to. */
+export function isProxyEnabled() {
+    return getUpstreamUrl() !== undefined;
+}

package/dist/functions/conflicts.d.ts

@@ -0,0 +1,19 @@
+import type { CompressedObservation } from "./types.js";
+export interface MemoryConflict {
+    olderId: string;
+    olderTitle: string;
+    newerId: string;
+    newerTitle: string;
+    subject: string;
+    olderClaim: string;
+    newerClaim: string;
+    reason: string;
+}
+/**
+ * Advisory contradiction report for mem::doctor. Deliberately conservative:
+ * simple subject/relation/value claims, clause-local negation, and a high bar
+ * for value conflicts so reworded facts, abbreviations, and different
+ * attributes of one subject don't fire. NEVER used to drop memory from recall
+ * — recall only firewalls STALE memory.
+ */
+export declare function detectConflicts(observations: CompressedObservation[], limit?: number): MemoryConflict[];