@hilbras/remembra 0.2.0 → 0.4.0

package/dist/retrieval.js

@@ -1,12 +1,18 @@
+import { cosine } from "./embeddings.js";
 /**
- * Layered retrieval (decision from Q4):
- *   1. Roles always pass (they are instructions).
- *   2. Scope match (global + current scope beat other scopes).
- *   3. Importance, recency, and keyword overlap contribute to the score.
+ * Layered retrieval (decisions Q4 + v2-Q3):
  *
- * Embeddings can replace the keyword part later without changing callers.
+ * Hard gates (never bypassed by scores):
+ *   - roles always pass (+1000)
+ *   - other scopes' memories are excluded entirely
+ *
+ * Ranking:
+ *   - embeddings ON (queryVec provided): semantic similarity is the primary
+ *     signal; importance + recency act as modifiers; keywords still help as
+ *     a tie-breaker for memories missing vectors.
+ *   - embeddings OFF: keyword overlap is the primary signal (v1 behavior).
  */
-export function search(memories, q) {
+export function search(memories, q, queryVec) {
     const now = Date.now();
     const terms = (q.query ?? "")
         .toLowerCase()
@@ -14,38 +20,64 @@ export function search(memories, q) {
         .filter((t) => t.length > 1);
     const scored = memories
         .filter((m) => (q.type ? m.type === q.type : true))
-        .map((m) => ({ m, score: score(m, terms, q.scope, now) }))
+        .map((m) => ({ m, score: score(m, terms, q.scope, now, queryVec) }))
         .filter(({ m, score }) => m.type === "role" || score > 0)
         .sort((a, b) => b.score - a.score || b.m.updatedAt.localeCompare(a.m.updatedAt));
     return scored.slice(0, q.limit ?? 10).map(({ m }) => m);
 }
-function score(m, terms, scope, now) {
+function score(m, terms, scope, now, queryVec) {
     let s = 0;
+    // --- hard gates ---
     if (m.type === "role")
         s += 1000;
+    if (scope && m.scope !== scope && m.scope !== "global")
+        return 0; // no cross-project leaks
     if (m.scope === "global")
         s += 100;
     if (scope && m.scope === scope)
         s += 150;
-    if (scope && m.scope !== scope && m.scope !== "global")
-        return 0; // other projects' memories don't leak in
-    s += m.importance * 10;
-    // Recency: half-life of ~30 days.
-    const ageDays = (now - Date.parse(m.updatedAt)) / 86_400_000;
-    if (!Number.isNaN(ageDays))
-        s += Math.max(0, 20 - ageDays / 3);
-    // Keyword overlap over content + tags.
-    if (terms.length > 0) {
-        const hay = (m.content + " " + m.tags.join(" ")).toLowerCase();
-        let hits = 0;
-        for (const t of terms)
-            if (hay.includes(t))
-                hits++;
-        s += (hits / terms.length) * 60;
+    // --- semantic mode (embeddings on) ---
+    if (queryVec && queryVec.length > 0) {
+        if (m.embedding && m.embedding.length > 0) {
+            // Primary signal: cosine similarity (0..1 → up to +100).
+            const sim = Math.max(0, cosine(queryVec, m.embedding));
+            s += sim * 100;
+            // Similarity gate: near-zero matches only survive on role/scope strength.
+            if (sim < 0.05 && m.type !== "role" && m.scope !== "global" && scope !== m.scope)
+                return 0;
+        }
+        else {
+            // Memory without a vector: fall back to keyword scoring for it.
+            s += keywordScore(m, terms);
+        }
+        // Modifiers (smaller weight than keywords-only mode).
+        s += m.importance * 4;
+        s += recencyScore(m, now) * 0.5;
+        return s;
     }
-    else {
+    // --- keyword mode (embeddings off — v1 behavior) ---
+    s += m.importance * 10;
+    s += recencyScore(m, now);
+    if (terms.length > 0)
+        s += keywordScore(m, terms);
+    else
         s += 10; // no query: everything eligible scores a little
-    }
     return s;
 }
+function recencyScore(m, now) {
+    const ageDays = (now - Date.parse(m.updatedAt)) / 86_400_000;
+    if (Number.isNaN(ageDays))
+        return 0;
+    return Math.max(0, 20 - ageDays / 3);
+}
+function keywordScore(m, terms) {
+    if (terms.length === 0)
+        return 0;
+    const hay = (m.content + " " + m.tags.join(" ")).toLowerCase();
+    let hits = 0;
+    for (const t of terms)
+        if (hay.includes(t))
+            hits++;
+    return (hits / terms.length) * 60;
+}
 //# sourceMappingURL=retrieval.js.map

package/dist/retrieval.js.map

@@ -1 +1 @@
-{"version":3,"file":"retrieval.js","sourceRoot":"","sources":["../src/retrieval.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"retrieval.js","sourceRoot":"","sources":["../src/retrieval.ts"],"names":[],"mappings":"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"}

package/dist/service.d.ts

@@ -1,16 +1,65 @@
 import { MemoryStore } from "./store.js";
-import { MemoryType } from "./types.js";
+import { MemoryType, Memory } from "./types.js";
+import { EmbeddingProvider } from "./embeddings.js";
+import { LlmProvider, ExtractedMemory } from "./llm.js";
+export interface DigestResult {
+    extracted: number;
+    stored: Memory[];
+    skippedDuplicates: number;
+    merged: number;
+    ids: string[];
+}
+export interface MaintainResult {
+    archived: string[];
+    deleted: string[];
+    embedded: number;
+    revived?: number;
+}
+interface ServiceDeps {
+    embeddingProvider?: EmbeddingProvider;
+    llmProvider?: LlmProvider;
+    /** Injection points for tests. */
+    embedFn?: (text: string) => Promise<number[]>;
+    extractFn?: (transcript: string) => Promise<ExtractedMemory[]>;
+    mergeFn?: (newContent: string, existing: {
+        type: string;
+        content: string;
+    }) => Promise<{
+        action: "store";
+    } | {
+        action: "skip";
+    } | {
+        action: "merge";
+        content: string;
+    }>;
+    /** How often the opportunistic decay pass may run on search (ms). Default 1h. */
+    decayIntervalMs?: number;
+    /** Active memory unused for this many days gets archived. Default 90. */
+    archiveAfterDays?: number;
+    /** Archived memory older than this gets auto-deleted. Default 365. */
+    archiveTtlDays?: number;
+}
 /**
  * Transport-agnostic handlers. Both the MCP tools and the HTTP API
  * call into this module, so behavior is guaranteed to match.
  */
 export declare class MemoryService {
     readonly db: MemoryStore;
-    constructor(db: MemoryStore);
+    private readonly embedFn?;
+    private readonly extractFn;
+    private readonly mergeFn;
+    private readonly decayIntervalMs;
+    private readonly archiveAfterDays;
+    private readonly archiveTtlDays;
+    private lastDecayRun;
+    private decayRunning;
+    constructor(db: MemoryStore, deps?: ServiceDeps);
+    get embeddingsEnabled(): boolean;
+    private maybeEmbed;
     store(input: unknown): Promise<{
         id: string;
         message: string;
-        memory: import("./types.js").Memory;
+        memory: Memory;
     }>;
     search(q: {
         query?: string;
@@ -19,17 +68,39 @@ export declare class MemoryService {
         limit?: number;
     }): Promise<{
         text: string;
-        results: import("./types.js").Memory[];
+        results: Memory[];
     }>;
     list(q: {
         scope?: string;
         type?: MemoryType;
+        includeArchived?: boolean;
     }): Promise<{
         text: string;
-        memories: import("./types.js").Memory[];
+        memories: Memory[];
     }>;
     forget(id: string): Promise<{
         ok: boolean;
         text: string;
     }>;
+    /**
+     * Session digest (v2) with contradiction-merge (v3):
+     * extract worth-keeping memories, skip exact duplicates, and let the LLM
+     * merge items that evolved from a stored memory (superseded text preserved).
+     */
+    digest(opts: {
+        transcript: string;
+        scope?: string;
+        source?: string;
+    }): Promise<DigestResult>;
+    /**
+     * Explicit maintenance (decision v3-Q1): decay sweep + vector backfill.
+     * Exposed as the `memory_maintain` tool, POST /maintain, and the CLI.
+     */
+    maintain(): Promise<MaintainResult>;
+    /** Decay lifecycle: unused actives → archived → auto-deleted past TTL. */
+    private decayPass;
+    private maybeRunDecay;
+    /** Pick the most similar stored memory of the same type+scope for merge comparison. */
+    private findCandidate;
 }
+export {};

package/dist/service.js

@@ -1,16 +1,52 @@
 import { search } from "./retrieval.js";
 import { StoreInput } from "./types.js";
+import { resolveEmbeddingProvider, embedText, cosine } from "./embeddings.js";
+import { resolveLlmProvider, extractMemories, resolveMerge, } from "./llm.js";
 /**
  * Transport-agnostic handlers. Both the MCP tools and the HTTP API
  * call into this module, so behavior is guaranteed to match.
  */
 export class MemoryService {
     db;
-    constructor(db) {
+    embedFn;
+    extractFn;
+    mergeFn;
+    decayIntervalMs;
+    archiveAfterDays;
+    archiveTtlDays;
+    lastDecayRun = 0;
+    decayRunning = false;
+    constructor(db, deps = {}) {
         this.db = db;
+        const emb = deps.embeddingProvider ?? resolveEmbeddingProvider();
+        const llm = deps.llmProvider ?? resolveLlmProvider();
+        this.embedFn =
+            deps.embedFn ??
+                (emb === "none" ? undefined : async (text) => embedText(text, emb));
+        this.extractFn = deps.extractFn ?? (async (t) => extractMemories(t, llm));
+        this.mergeFn = deps.mergeFn ?? ((n, e) => resolveMerge(n, e, llm));
+        this.decayIntervalMs = deps.decayIntervalMs ?? 3_600_000; // 1h
+        this.archiveAfterDays = deps.archiveAfterDays ?? Number(process.env.REMEMBRA_ARCHIVE_AFTER_DAYS ?? 90);
+        this.archiveTtlDays = deps.archiveTtlDays ?? Number(process.env.REMEMBRA_ARCHIVE_TTL_DAYS ?? 365);
+    }
+    get embeddingsEnabled() {
+        return this.embedFn !== undefined;
+    }
+    async maybeEmbed(text) {
+        if (!this.embedFn)
+            return undefined;
+        try {
+            return await this.embedFn(text);
+        }
+        catch (err) {
+            console.error(`Remembra: embedding failed (${err instanceof Error ? err.message : err}); continuing without`);
+            return undefined;
+        }
     }
     async store(input) {
-        const memory = await this.db.store(StoreInput.parse(input));
+        const parsed = StoreInput.parse(input);
+        const embedding = await this.maybeEmbed(parsed.content);
+        const memory = await this.db.store(parsed, embedding);
         return {
             id: memory.id,
             message: `Stored ${memory.type} memory ${memory.id} (scope: ${memory.scope})`,
@@ -18,7 +54,15 @@ export class MemoryService {
         };
     }
     async search(q) {
-        const results = search(await this.db.all(), q);
+        let queryVec = null;
+        if (q.query && this.embedFn)
+            queryVec = (await this.maybeEmbed(q.query)) ?? null;
+        const results = search(await this.db.all(), q, queryVec);
+        // Refresh decay clocks for memories that surfaced (fire-and-forget).
+        for (const m of results)
+            this.db.touch(m.id).catch(() => { });
+        // Opportunistic decay pass, debounced (decision v3-Q1: piggyback on search).
+        this.maybeRunDecay();
         const text = results.length === 0
             ? "No matching memories."
             : results
@@ -27,7 +71,7 @@ export class MemoryService {
         return { text, results };
     }
     async list(q) {
-        let memories = await this.db.all();
+        let memories = await this.db.all(q.includeArchived ?? false);
         if (q.scope)
             memories = memories.filter((m) => m.scope === q.scope || m.scope === "global");
         if (q.type)
@@ -35,12 +79,188 @@ export class MemoryService {
         memories.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
         const text = memories.length === 0
             ? "No memories stored yet."
-            : memories.map((m) => `[${m.id}] ${m.type} (${m.scope}): ${m.content.split("\n")[0]}`).join("\n");
+            : memories
+                .map((m) => `[${m.id}]${m.archivedAt ? " [archived]" : ""} ${m.type} (${m.scope}): ${m.content.split("\n")[0]}`)
+                .join("\n");
         return { text, memories };
     }
     async forget(id) {
         const ok = await this.db.forget(id);
         return { ok, text: ok ? `Deleted memory ${id}.` : `No memory with id ${id}.` };
     }
+    /**
+     * Session digest (v2) with contradiction-merge (v3):
+     * extract worth-keeping memories, skip exact duplicates, and let the LLM
+     * merge items that evolved from a stored memory (superseded text preserved).
+     */
+    async digest(opts) {
+        const extracted = await this.extractFn(opts.transcript);
+        const active = await this.db.all();
+        const archived = await this.db.all(true).then((all) => all.filter((m) => m.archivedAt));
+        const seen = new Set(active.map((m) => dedupKey(m.type, m.content, m.scope)));
+        const stored = [];
+        let skippedDuplicates = 0;
+        let merged = 0;
+        for (const item of extracted) {
+            const scope = item.scope ?? opts.scope ?? "global";
+            const key = dedupKey(item.type, item.content, scope);
+            // Exact duplicate → skip (or revive if it had decayed).
+            if (seen.has(key)) {
+                skippedDuplicates++;
+                continue;
+            }
+            const archivedDup = archived.find((m) => dedupKey(m.type, m.content, scope) === key);
+            if (archivedDup) {
+                const revived = await this.db.revive(archivedDup.id);
+                if (revived) {
+                    seen.add(key);
+                    merged++; // counted as a revival/refresh
+                    continue;
+                }
+            }
+            // Evolved fact → LLM decides: store fresh, skip, or merge.
+            const itemVec = (await this.maybeEmbed(item.content)) ?? null;
+            const candidate = this.findCandidate(item, scope, [...active, ...archived], itemVec);
+            if (candidate) {
+                const decision = await this.mergeFn(item.content, {
+                    type: candidate.type,
+                    content: candidate.content,
+                });
+                if (decision.action === "skip") {
+                    skippedDuplicates++;
+                    continue;
+                }
+                if (decision.action === "merge") {
+                    const now = new Date().toISOString().slice(0, 10);
+                    const old = candidate.content.split("\n")[0];
+                    const content = `${decision.content}\n\n> superseded (${now}): ${old}`;
+                    const embedding = await this.maybeEmbed(decision.content);
+                    await this.db.update({ ...candidate, content, embedding, source: opts.source ?? candidate.source });
+                    merged++;
+                    // Re-index dedup set against the new content.
+                    seen.delete(dedupKey(candidate.type, candidate.content, candidate.scope));
+                    seen.add(dedupKey(candidate.type, decision.content, candidate.scope));
+                    continue;
+                }
+                // action: "store" → fall through and store fresh
+            }
+            seen.add(key);
+            const { memory } = await this.store({
+                type: item.type,
+                content: item.content,
+                scope,
+                tags: item.tags,
+                importance: item.importance,
+                source: opts.source,
+            });
+            stored.push(memory);
+        }
+        return {
+            extracted: extracted.length,
+            stored,
+            skippedDuplicates,
+            merged,
+            ids: stored.map((m) => m.id),
+        };
+    }
+    /**
+     * Explicit maintenance (decision v3-Q1): decay sweep + vector backfill.
+     * Exposed as the `memory_maintain` tool, POST /maintain, and the CLI.
+     */
+    async maintain() {
+        const result = await this.decayPass();
+        // Vector backfill: embed active memories stored while embeddings were off.
+        if (this.embedFn) {
+            const active = await this.db.all();
+            for (const m of active) {
+                if (m.embedding && m.embedding.length > 0)
+                    continue;
+                const vec = await this.maybeEmbed(m.content);
+                if (vec) {
+                    await this.db.update({ ...m, embedding: vec });
+                    result.embedded++;
+                }
+            }
+        }
+        return result;
+    }
+    /** Decay lifecycle: unused actives → archived → auto-deleted past TTL. */
+    async decayPass() {
+        const now = Date.now();
+        const archiveCutoff = now - this.archiveAfterDays * 86_400_000;
+        const ttlCutoff = now - this.archiveTtlDays * 86_400_000;
+        const result = { archived: [], deleted: [], embedded: 0 };
+        const active = await this.db.all();
+        for (const m of active) {
+            if (m.type === "role")
+                continue; // standing instructions never decay
+            const lastActive = Date.parse(m.lastSeen ?? m.updatedAt);
+            if (Number.isFinite(lastActive) && lastActive < archiveCutoff) {
+                await this.db.archive(m.id);
+                result.archived.push(m.id);
+            }
+        }
+        const archived = (await this.db.all(true)).filter((m) => m.archivedAt);
+        for (const m of archived) {
+            const archivedAt = Date.parse(m.archivedAt);
+            if (Number.isFinite(archivedAt) && archivedAt < ttlCutoff) {
+                await this.db.forget(m.id);
+                result.deleted.push(m.id);
+            }
+        }
+        return result;
+    }
+    maybeRunDecay() {
+        if (this.decayRunning)
+            return;
+        if (Date.now() - this.lastDecayRun < this.decayIntervalMs)
+            return;
+        this.lastDecayRun = Date.now();
+        this.decayRunning = true;
+        this.decayPass()
+            .catch((err) => console.error("Remembra: decay pass failed:", err))
+            .finally(() => {
+            this.decayRunning = false;
+        });
+    }
+    /** Pick the most similar stored memory of the same type+scope for merge comparison. */
+    findCandidate(item, scope, pool, itemVec) {
+        let best = null;
+        let bestScore = 0;
+        for (const m of pool) {
+            if (m.type !== item.type || m.scope !== scope)
+                continue;
+            const score = candidateSimilarity(item.content, m, itemVec);
+            if (score > bestScore) {
+                bestScore = score;
+                best = m;
+            }
+        }
+        // Threshold: must be clearly about the same thing before spending an LLM call.
+        return bestScore >= 0.4 ? best : null;
+    }
+}
+/** Normalized identity for exact-match dedup. */
+function dedupKey(type, content, scope) {
+    return `${type}|${scope}|${content.toLowerCase().replace(/\s+/g, " ").trim()}`;
+}
+/** Similarity: embeddings (cosine) when both sides have vectors, else keyword overlap. */
+function candidateSimilarity(newContent, m, itemVec) {
+    if (itemVec && m.embedding && m.embedding.length === itemVec.length) {
+        // Cosine is typically 0..1 for normalized-ish text vectors; scale to our 0..1 threshold.
+        return Math.max(0, cosine(itemVec, m.embedding));
+    }
+    const terms = new Set(newContent
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((t) => t.length > 3));
+    if (terms.size === 0)
+        return 0;
+    const hay = m.content.toLowerCase();
+    let hits = 0;
+    for (const t of terms)
+        if (hay.includes(t))
+            hits++;
+    return hits / terms.size;
 }
 //# sourceMappingURL=service.js.map

package/dist/service.js.map

@@ -1 +1 @@
-{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts

@@ -1,23 +1,33 @@
 import { Memory, StoreInput } from "./types.js";
 /**
- * File-based memory store.
+ * File-based memory store (source of truth — no database).
  *
  * Layout (default root: ~/.remembra):
- *   global/<id>.md            — memories valid everywhere
- *   scopes/<scope>/<id>.md    — memories scoped to a project/workspace
+ *   global/<id>.md            — active memories, valid everywhere
+ *   scopes/<scope>/<id>.md    — active memories scoped to a project/workspace
+ *   archived/global/<id>.md   — archived memories (out of search, listed with flag)
+ *   archived/scopes/<scope>/  — archived scoped memories
  *
- * Each file is markdown with YAML-ish frontmatter for human readability
- * and simple greppability.
+ * Each file is markdown with frontmatter for human readability and greppability.
+ * Maintenance runs opportunistically on search + via `memory_maintain`.
  */
 export declare class MemoryStore {
     private readonly root;
     constructor(root: string);
     static defaultRoot(): string;
     private fileFor;
-    store(input: StoreInput): Promise<Memory>;
+    store(input: StoreInput, embedding?: number[]): Promise<Memory>;
     forget(id: string): Promise<boolean>;
-    /** Load every memory across all scopes (global + scoped). */
-    all(): Promise<Memory[]>;
+    /** Load active memories (excludes archived). Pass includeArchived for everything. */
+    all(includeArchived?: boolean): Promise<Memory[]>;
     get(id: string): Promise<Memory | null>;
+    /** Move a memory to the archived tree (sets archivedAt). */
+    archive(id: string): Promise<Memory | null>;
+    /** Bring an archived memory back into active search. */
+    revive(id: string): Promise<Memory | null>;
+    /** Persist changes to an existing memory (merge/update path). */
+    update(memory: Memory): Promise<Memory>;
+    /** Record that a memory surfaced in search (decay refresh). Cheap: no-op if seen <1h ago. */
+    touch(id: string): Promise<void>;
     private findFile;
 }