memwarden 0.0.1

package/dist/functions/hybrid-search.js

@@ -0,0 +1,205 @@
+//
+// Reciprocal Rank Fusion (RRF) hybrid retrieval. Ported from the original
+// src/state/hybrid-search.ts, preserving the load-bearing constants and the
+// exact fusion math:
+//
+// RRF_K = 60
+// default weights: bm25Weight = 0.4, vectorWeight = 0.6, graphWeight = 0.3
+// combinedScore = Σ effectiveW_stream * (1 / (RRF_K + rank_stream))
+// missing-stream rank = Infinity (so its term is 1/(60+Inf) = 0)
+// weights are RENORMALIZED over only the streams that returned hits.
+//
+// PHASE-0 SCOPE: the vector and graph streams are stubbed empty (no
+// embedding provider, no knowledge graph wired yet). Because the
+// renormalization divides by the sum of only the streams that returned
+// hits, with both vector and graph empty the BM25 stream is renormalized
+// to weight 1.0 — identical to the original behavior when those streams
+// return nothing. When the vector provider lands in Phase 0b, pass a real
+// VectorIndex + EmbeddingProvider into the constructor and the second
+// stream lights up with no fusion-math change. The graph stream stays a
+// no-op until the graph layer is ported.
+import { memoryToObservation } from "./memory-utils.js";
+import { KV } from "../state/schema.js";
+const RRF_K = 60;
+export class HybridSearch {
+    bm25;
+    vector;
+    embeddingProvider;
+    kv;
+    bm25Weight;
+    vectorWeight;
+    graphWeight;
+    constructor(bm25, vector, embeddingProvider, kv, bm25Weight = 0.4, vectorWeight = 0.6, graphWeight = 0.3) {
+        this.bm25 = bm25;
+        this.vector = vector;
+        this.embeddingProvider = embeddingProvider;
+        this.kv = kv;
+        this.bm25Weight = bm25Weight;
+        this.vectorWeight = vectorWeight;
+        this.graphWeight = graphWeight;
+    }
+    async search(query, limit = 20) {
+        return this.tripleStreamSearch(query, limit);
+    }
+    async tripleStreamSearch(query, limit) {
+        const bm25Results = this.bm25.search(query, limit * 2);
+        // Vector stream. Stubbed empty in Phase 0 (no provider / empty index);
+        // the try/catch + size-guard mirror the original implementation so lighting up the
+        // provider later needs no change here.
+        let vectorResults = [];
+        if (this.vector && this.embeddingProvider && this.vector.size > 0) {
+            try {
+                const queryEmbedding = await this.embeddingProvider.embed(query);
+                vectorResults = this.vector.search(queryEmbedding, limit * 2);
+            }
+            catch {
+                // fall through to BM25-only
+            }
+        }
+        // Graph stream. Not ported in Phase 0; always empty.
+        const graphResults = [];
+        const scores = new Map();
+        bm25Results.forEach((r, i) => {
+            scores.set(r.obsId, {
+                bm25Rank: i + 1,
+                vectorRank: Infinity,
+                graphRank: Infinity,
+                sessionId: r.sessionId,
+                bm25Score: r.score,
+                vectorScore: 0,
+                graphScore: 0,
+            });
+        });
+        vectorResults.forEach((r, i) => {
+            const existing = scores.get(r.obsId);
+            if (existing) {
+                existing.vectorRank = i + 1;
+                existing.vectorScore = r.score;
+            }
+            else {
+                scores.set(r.obsId, {
+                    bm25Rank: Infinity,
+                    vectorRank: i + 1,
+                    graphRank: Infinity,
+                    sessionId: r.sessionId,
+                    bm25Score: 0,
+                    vectorScore: r.score,
+                    graphScore: 0,
+                });
+            }
+        });
+        graphResults.forEach((r, i) => {
+            const existing = scores.get(r.obsId);
+            if (existing) {
+                existing.graphRank = Math.min(existing.graphRank, i + 1);
+                existing.graphScore = Math.max(existing.graphScore, r.score);
+                if (r.graphContext && !existing.graphContext) {
+                    existing.graphContext = r.graphContext;
+                }
+            }
+            else {
+                scores.set(r.obsId, {
+                    bm25Rank: Infinity,
+                    vectorRank: Infinity,
+                    graphRank: i + 1,
+                    sessionId: r.sessionId,
+                    bm25Score: 0,
+                    vectorScore: 0,
+                    graphScore: r.score,
+                    ...(r.graphContext !== undefined
+                        ? { graphContext: r.graphContext }
+                        : {}),
+                });
+            }
+        });
+        const hasVector = vectorResults.length > 0;
+        const hasGraph = graphResults.length > 0;
+        let effectiveBm25W = this.bm25Weight;
+        let effectiveVectorW = hasVector ? this.vectorWeight : 0;
+        let effectiveGraphW = hasGraph ? this.graphWeight : 0;
+        // Renormalize over only the streams that returned hits. With both the
+        // vector and graph streams empty (Phase 0) this leaves BM25 at 1.0.
+        const totalW = effectiveBm25W + effectiveVectorW + effectiveGraphW;
+        if (totalW > 0) {
+            effectiveBm25W /= totalW;
+            effectiveVectorW /= totalW;
+            effectiveGraphW /= totalW;
+        }
+        const combined = Array.from(scores.entries()).map(([obsId, s]) => ({
+            obsId,
+            sessionId: s.sessionId,
+            bm25Score: s.bm25Score,
+            vectorScore: s.vectorScore,
+            graphScore: s.graphScore,
+            graphContext: s.graphContext,
+            combinedScore: effectiveBm25W * (1 / (RRF_K + s.bm25Rank)) +
+                effectiveVectorW * (1 / (RRF_K + s.vectorRank)) +
+                effectiveGraphW * (1 / (RRF_K + s.graphRank)),
+        }));
+        combined.sort((a, b) => b.combinedScore - a.combinedScore);
+        const retrievalDepth = Math.max(limit, 20);
+        const diversified = this.diversifyBySession(combined, retrievalDepth);
+        const enriched = await this.enrichResults(diversified, retrievalDepth);
+        return enriched.slice(0, limit);
+    }
+    diversifyBySession(results, limit, maxPerSession = 3) {
+        const selected = [];
+        const sessionCounts = new Map();
+        for (const r of results) {
+            const count = sessionCounts.get(r.sessionId) || 0;
+            if (count >= maxPerSession)
+                continue;
+            selected.push(r);
+            sessionCounts.set(r.sessionId, count + 1);
+            if (selected.length >= limit)
+                break;
+        }
+        if (selected.length < limit) {
+            for (const r of results) {
+                if (selected.length >= limit)
+                    break;
+                if (!selected.some((s) => s.obsId === r.obsId)) {
+                    selected.push(r);
+                }
+            }
+        }
+        return selected;
+    }
+    async enrichResults(results, limit) {
+        const sliced = results.slice(0, limit);
+        const observations = await Promise.all(sliced.map(async (r) => {
+            const obs = await this.kv
+                .get(KV.observations(r.sessionId), r.obsId)
+                .catch(() => null);
+            if (obs)
+                return obs;
+            // Fallback: indexed entry may originate from mem::remember, which
+            // writes to KV.memories with a synthetic sessionId. Coerce the
+            // Memory record into a CompressedObservation so saved memories
+            // still surface.
+            const mem = await this.kv
+                .get(KV.memories, r.obsId)
+                .catch(() => null);
+            return mem ? memoryToObservation(mem) : null;
+        }));
+        const enriched = [];
+        for (let i = 0; i < sliced.length; i++) {
+            const obs = observations[i];
+            const src = sliced[i];
+            if (obs) {
+                enriched.push({
+                    observation: obs,
+                    bm25Score: src.bm25Score,
+                    vectorScore: src.vectorScore,
+                    graphScore: src.graphScore,
+                    combinedScore: src.combinedScore,
+                    sessionId: src.sessionId,
+                    ...(src.graphContext !== undefined
+                        ? { graphContext: src.graphContext }
+                        : {}),
+                });
+            }
+        }
+        return enriched;
+    }
+}

package/dist/functions/index.d.ts

@@ -0,0 +1,32 @@
+import type { ISdk } from "../kernel/index.js";
+import { StateKV } from "../state/kv.js";
+import { DedupMap } from "./dedup.js";
+export { registerObserveFunction } from "./observe.js";
+export { registerContextFunction } from "./context.js";
+export { registerSearchFunction } from "./search.js";
+export { registerForgetFunction } from "./forget.js";
+export { registerDoctorFunction } from "./doctor.js";
+export type { DoctorReport } from "./doctor.js";
+export { registerReceiptFunction } from "./receipt.js";
+export type { DeleteReceipt, ForgetResult } from "./receipt.js";
+export { registerDejaFixFunctions, recordFix, lookupFix, errorSignature, looksLikeResolvedFix, DEJAFIX_SCOPE, } from "./dejafix.js";
+export type { FixMemory, VerifiedFix, RecordFixInput } from "./dejafix.js";
+export { getSearchIndex, getVectorIndex, setVectorIndex, getEmbeddingProvider, setEmbeddingProvider, rebuildIndex, vectorIndexAddGuarded, makeVectorIndex, } from "./search.js";
+export { QuantizedVectorIndex } from "./quantized-vector-index.js";
+export type { QuantParams } from "./quantized-vector-index.js";
+export { persistVectorIndex, loadVectorIndex } from "./vector-persistence.js";
+export { DedupMap } from "./dedup.js";
+export interface RegisterCoreOptions {
+    /** Per-request context token budget. Defaults to config. */
+    tokenBudget?: number;
+    /** Max observations per session. Defaults to config. */
+    maxObservationsPerSession?: number;
+    /** Dedup map for the observe write path. Defaults to a fresh DedupMap. */
+    dedupMap?: DedupMap;
+}
+/**
+ * Register the three core functions against the kernel. The kernel
+ * routes the five state::* ids to its StateStore, so StateKV — constructed
+ * over the kernel here — is the persistence chokepoint all three share.
+ */
+export declare function registerCoreFunctions(sdk: ISdk, kv?: StateKV, opts?: RegisterCoreOptions): StateKV;

package/dist/functions/index.js

@@ -0,0 +1,44 @@
+//
+// Barrel + single registration entrypoint for the core functions
+// (mem::observe, mem::context, mem::search). The boot path (src/index.ts)
+// constructs the StateKV over the kernel and calls registerCoreFunctions to
+// wire all three against the kernel's function registry in one step.
+import { StateKV } from "../state/kv.js";
+import { registerObserveFunction } from "./observe.js";
+import { registerContextFunction } from "./context.js";
+import { registerSearchFunction } from "./search.js";
+import { registerForgetFunction } from "./forget.js";
+import { registerDoctorFunction } from "./doctor.js";
+import { registerDejaFixFunctions } from "./dejafix.js";
+import { registerReceiptFunction } from "./receipt.js";
+import { DedupMap } from "./dedup.js";
+import { getTokenBudget, getMaxObservationsPerSession } from "./config.js";
+export { registerObserveFunction } from "./observe.js";
+export { registerContextFunction } from "./context.js";
+export { registerSearchFunction } from "./search.js";
+export { registerForgetFunction } from "./forget.js";
+export { registerDoctorFunction } from "./doctor.js";
+export { registerReceiptFunction } from "./receipt.js";
+export { registerDejaFixFunctions, recordFix, lookupFix, errorSignature, looksLikeResolvedFix, DEJAFIX_SCOPE, } from "./dejafix.js";
+export { getSearchIndex, getVectorIndex, setVectorIndex, getEmbeddingProvider, setEmbeddingProvider, rebuildIndex, vectorIndexAddGuarded, makeVectorIndex, } from "./search.js";
+export { QuantizedVectorIndex } from "./quantized-vector-index.js";
+export { persistVectorIndex, loadVectorIndex } from "./vector-persistence.js";
+export { DedupMap } from "./dedup.js";
+/**
+ * Register the three core functions against the kernel. The kernel
+ * routes the five state::* ids to its StateStore, so StateKV — constructed
+ * over the kernel here — is the persistence chokepoint all three share.
+ */
+export function registerCoreFunctions(sdk, kv = new StateKV(sdk), opts = {}) {
+    const tokenBudget = opts.tokenBudget ?? getTokenBudget();
+    const maxObs = opts.maxObservationsPerSession ?? getMaxObservationsPerSession();
+    const dedupMap = opts.dedupMap ?? new DedupMap();
+    registerObserveFunction(sdk, kv, dedupMap, maxObs);
+    registerContextFunction(sdk, kv, tokenBudget);
+    registerSearchFunction(sdk, kv);
+    registerForgetFunction(sdk, kv);
+    registerDoctorFunction(sdk, kv);
+    registerDejaFixFunctions(sdk, kv);
+    registerReceiptFunction(sdk, kv);
+    return kv;
+}

package/dist/functions/keyed-mutex.d.ts

@@ -0,0 +1 @@
+export declare function withKeyedLock<T>(key: string, fn: () => Promise<T>): Promise<T>;

package/dist/functions/keyed-mutex.js

@@ -0,0 +1,21 @@
+//
+// Per-key serialization. Calls that share a key run one at a time, chained on
+// a promise so each waits for the previous to settle (whether it resolved or
+// threw). Used to serialize the observe write path per session so counters and
+// rollbacks stay race-free. Correct only for a single in-process instance; a
+// multi-process memwarden would need a real distributed lock.
+const chains = new Map();
+export function withKeyedLock(key, fn) {
+    const prior = chains.get(key) ?? Promise.resolve();
+    // Run after the prior call settles either way (pass fn for both branches).
+    const run = prior.then(fn, fn);
+    // A branch that never rejects, used both to keep the chain going past a
+    // failure and to release the key once nothing is queued behind it.
+    const settled = run.then(() => undefined, () => undefined);
+    chains.set(key, settled);
+    void settled.then(() => {
+        if (chains.get(key) === settled)
+            chains.delete(key);
+    });
+    return run;
+}

package/dist/functions/logger.d.ts

@@ -0,0 +1,6 @@
+export declare const logger: {
+    debug: (message: string, meta?: Record<string, unknown>) => void;
+    info: (message: string, meta?: Record<string, unknown>) => void;
+    warn: (message: string, meta?: Record<string, unknown>) => void;
+    error: (message: string, meta?: Record<string, unknown>) => void;
+};

package/dist/functions/logger.js

@@ -0,0 +1,37 @@
+//
+// Minimal structured logger: the info/warn/error/debug surface the rest of
+// the code calls, writing JSON lines to stderr so log output never corrupts a
+// stdout protocol stream. Level is gated by MEMWARDEN_LOG_LEVEL (default
+// "info").
+const LEVELS = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+function threshold() {
+    const raw = (process.env.MEMWARDEN_LOG_LEVEL ?? "info").toLowerCase();
+    return LEVELS[raw] ?? LEVELS.info;
+}
+function emit(level, message, meta) {
+    if (LEVELS[level] < threshold())
+        return;
+    const line = {
+        ts: new Date().toISOString(),
+        level,
+        message,
+        ...(meta ?? {}),
+    };
+    try {
+        process.stderr.write(`${JSON.stringify(line)}\n`);
+    }
+    catch {
+        // Logging must never throw into the call path.
+    }
+}
+export const logger = {
+    debug: (message, meta) => emit("debug", message, meta),
+    info: (message, meta) => emit("info", message, meta),
+    warn: (message, meta) => emit("warn", message, meta),
+    error: (message, meta) => emit("error", message, meta),
+};

package/dist/functions/memory-utils.d.ts

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

package/dist/functions/memory-utils.js

@@ -0,0 +1,29 @@
+//
+// Adapts a stored Memory into the CompressedObservation shape the search and
+// enrichment paths expect. A Memory has no real session, so it borrows its
+// first sessionId (or the literal "memory") as a synthetic key that
+// KV.memories lookups fall back on.
+export function memoryToObservation(memory) {
+    const obs = {
+        id: memory.id,
+        sessionId: memory.sessionIds?.[0] ?? "memory",
+        timestamp: memory.createdAt,
+        type: "decision",
+        title: memory.title,
+        facts: [memory.content],
+        narrative: memory.content,
+        concepts: memory.concepts,
+        files: memory.files,
+        importance: memory.strength,
+    };
+    // Carry provenance so Memory records go through Verified Recall too. If a
+    // record has no provenance but does reference files, synthesize a minimal
+    // one so at least deletion is detected (content drift needs captured hashes).
+    if (memory.provenance) {
+        obs.provenance = memory.provenance;
+    }
+    else if (memory.files && memory.files.length > 0) {
+        obs.provenance = { files: memory.files, command: "memory" };
+    }
+    return obs;
+}

package/dist/functions/observe.d.ts

@@ -0,0 +1,5 @@
+import { type ISdk } from "../kernel/index.js";
+import type { StateKV } from "../state/kv.js";
+import { DedupMap } from "./dedup.js";
+export declare function extractImage(d: unknown): string | undefined;
+export declare function registerObserveFunction(sdk: ISdk, kv: StateKV, dedupMap?: DedupMap, maxObservationsPerSession?: number): void;