@intentface/latch-memory 0.9.1

package/dist/store/memory.d.ts

@@ -0,0 +1,31 @@
+import type { MemorySearchHit, MemoryStore } from "../types.js";
+/**
+ * In-memory `MemoryStore`: a `Map<path, text>` behind the store seam, with a
+ * deterministic keyword (BM25-style, NO embeddings) search. Two consumers:
+ *
+ * - tests that need a real store without a Loredex connection;
+ * - the offline retrieval evals (`evals/`), which measure the real
+ *   `memory_search` tool over this store.
+ *
+ * Determinism is a hard requirement (the evals byte-compare reports across
+ * runs): no `Date.now()`, no `Math.random()` — episode filenames come from
+ * `meta.extractedAt`, snapshot names from a monotonic counter, and search
+ * ties break on lexicographic path order.
+ */
+export interface InMemoryStoreHandle extends MemoryStore<unknown> {
+    /** The backing file map (path → text), exposed for seeding and assertions. */
+    readonly files: Map<string, string>;
+}
+export declare function createInMemoryStore(opts?: {
+    /** Seed files (workspace-relative path → markdown text). */
+    files?: Record<string, string> | Map<string, string>;
+}): InMemoryStoreHandle;
+/** Lowercase word tokens (len ≥ 2), stopwords removed. Exported for the evals. */
+export declare function contentTokens(text: string): string[];
+/**
+ * BM25-lite over (path, text) docs. The filename contributes tokens twice
+ * (title weight, mirroring how Loredex indexes file names alongside content).
+ * Fully deterministic: score desc, then path asc.
+ */
+export declare function keywordSearch(docs: Array<[path: string, text: string]>, query: string, limit: number): MemorySearchHit[];
+//# sourceMappingURL=memory.d.ts.map

package/dist/store/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/store/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,eAAe,EAAE,WAAW,EAAY,MAAM,aAAa,CAAC;AASvF;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,mBAAoB,SAAQ,WAAW,CAAC,OAAO,CAAC;IAC/D,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,wBAAgB,mBAAmB,CAAC,IAAI,CAAC,EAAE;IACzC,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtD,GAAG,mBAAmB,CA2EtB;AA0BD,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAKpD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,EACzC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,eAAe,EAAE,CAsCnB"}

package/dist/store/memory.js

@@ -0,0 +1,156 @@
+import { isUnderScopeRoot } from "../scope.js";
+import { IndexValidationError, MEMORY_INDEX_FILENAME, memoryIdsIn, validateIndexRewrite, } from "../index-file.js";
+export function createInMemoryStore(opts) {
+    const files = new Map(opts?.files instanceof Map ? opts.files : Object.entries(opts?.files ?? {}));
+    let snapshotSeq = 0;
+    const indexPath = (scope) => `${scope.root}/${MEMORY_INDEX_FILENAME}`;
+    return {
+        files,
+        async available() {
+            return true;
+        },
+        async readIndex(_principal, scope) {
+            return files.get(indexPath(scope));
+        },
+        async writeIndex(_principal, scope, text) {
+            const prev = files.get(indexPath(scope));
+            const problems = validateIndexRewrite(prev, text);
+            if (problems.length > 0)
+                throw new IndexValidationError(problems);
+            if (prev !== undefined && prev.trim().length > 0) {
+                snapshotSeq += 1;
+                files.set(`${scope.root}/archive/index-snapshots/MEMORY-${String(snapshotSeq).padStart(4, "0")}.md`, prev);
+            }
+            files.set(indexPath(scope), text);
+        },
+        async writeEpisode(_principal, scope, episode) {
+            const dir = `${scope.root}/episodes`;
+            const stamp = episode.meta.extractedAt.slice(0, 16).replace("T", "-").replace(":", "-");
+            const slug = episode.slug
+                .replace(/[^a-zA-Z0-9_-]/g, "-")
+                .replace(/-{2,}/g, "-")
+                .replace(/^-+|-+$/g, "")
+                .slice(0, 48) || "note";
+            let name = `${stamp}-${slug}.md`;
+            // Same minute + same slug: disambiguate deterministically.
+            for (let n = 2; files.has(`${dir}/${name}`); n++)
+                name = `${stamp}-${slug}-${n}.md`;
+            const content = `${episodeFrontmatter(episode.meta)}\n\n${episode.body.trim()}\n`;
+            files.set(`${dir}/${name}`, content);
+            return { path: `${dir}/${name}`, name };
+        },
+        async readEpisodes(_principal, scope, paths) {
+            const out = [];
+            for (const path of paths) {
+                if (!isUnderScopeRoot(scope.root, path))
+                    continue;
+                const text = files.get(path);
+                if (text !== undefined)
+                    out.push({ path, text });
+            }
+            return out;
+        },
+        async search(_principal, scope, query, limit = 6) {
+            const docs = Array.from(files.entries())
+                .filter(([path]) => isUnderScopeRoot(scope.root, path))
+                .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+            return keywordSearch(docs, query, limit);
+        },
+        async readFile(_principal, { path }) {
+            return files.get(path);
+        },
+        async writeFile(_principal, { path, content }) {
+            files.set(path, content);
+        },
+    };
+}
+function episodeFrontmatter(meta) {
+    return [
+        "---",
+        ...(meta.chat ? [`chat: ${meta.chat}`] : []),
+        `agent: ${meta.agent}`,
+        `extracted_at: ${meta.extractedAt}`,
+        `provenance: ${meta.provenance}`,
+        "---",
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Deterministic keyword search (grep-style BM25-lite, no embeddings)
+// ---------------------------------------------------------------------------
+/** Minimal english stopword list — enough to keep filler words from scoring. */
+const STOPWORDS = new Set([
+    "a", "an", "and", "are", "as", "at", "be", "but", "by", "do", "does", "for",
+    "from", "has", "have", "he", "her", "his", "i", "in", "is", "it", "its",
+    "me", "my", "no", "not", "of", "on", "or", "our", "she", "so", "that",
+    "the", "their", "them", "they", "this", "to", "up", "was", "we", "what",
+    "when", "where", "which", "who", "will", "with", "you", "your",
+]);
+/** Lowercase word tokens (len ≥ 2), stopwords removed. Exported for the evals. */
+export function contentTokens(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length >= 2 && !STOPWORDS.has(t));
+}
+/**
+ * BM25-lite over (path, text) docs. The filename contributes tokens twice
+ * (title weight, mirroring how Loredex indexes file names alongside content).
+ * Fully deterministic: score desc, then path asc.
+ */
+export function keywordSearch(docs, query, limit) {
+    const queryTokens = Array.from(new Set(contentTokens(query)));
+    if (queryTokens.length === 0)
+        return [];
+    const indexed = docs.map(([path, text]) => {
+        const nameTokens = contentTokens(path.split("/").pop() ?? "");
+        const tokens = [...contentTokens(text), ...nameTokens, ...nameTokens];
+        const tf = new Map();
+        for (const t of tokens)
+            tf.set(t, (tf.get(t) ?? 0) + 1);
+        return { path, text, tf, length: tokens.length };
+    });
+    const n = indexed.length;
+    if (n === 0)
+        return [];
+    const avgLen = indexed.reduce((sum, d) => sum + d.length, 0) / n || 1;
+    const scored = indexed
+        .map((doc) => {
+        let score = 0;
+        for (const term of queryTokens) {
+            const tf = doc.tf.get(term) ?? 0;
+            if (tf === 0)
+                continue;
+            const df = indexed.reduce((c, d) => c + (d.tf.has(term) ? 1 : 0), 0);
+            const idf = Math.log(1 + (n - df + 0.5) / (df + 0.5));
+            // k1 = 1.2, b = 0.75 — the standard BM25 saturation curve.
+            score += idf * ((tf * 2.2) / (tf + 1.2 * (0.25 + 0.75 * (doc.length / avgLen))));
+        }
+        return { doc, score };
+    })
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score || (a.doc.path < b.doc.path ? -1 : 1));
+    return scored.slice(0, limit).map(({ doc }) => {
+        const snippet = bestSnippet(doc.text, queryTokens);
+        const memoryIds = memoryIdsIn(snippet);
+        if (/\/episodes\//.test(doc.path))
+            memoryIds.push(doc.path);
+        return { path: doc.path, snippet, memoryIds: Array.from(new Set(memoryIds)) };
+    });
+}
+/** The line matching the most query tokens (first on ties), capped at 240 chars. */
+function bestSnippet(text, queryTokens) {
+    let best = "";
+    let bestCount = 0;
+    for (const line of text.split("\n")) {
+        const lineTokens = new Set(contentTokens(line));
+        const count = queryTokens.reduce((c, t) => c + (lineTokens.has(t) ? 1 : 0), 0);
+        if (count > bestCount) {
+            best = line.trim();
+            bestCount = count;
+        }
+    }
+    if (!best)
+        best = text.split("\n").find((l) => l.trim().length > 0)?.trim() ?? "";
+    return best.length > 240 ? `${best.slice(0, 237)}…` : best;
+}
+//# sourceMappingURL=memory.js.map

package/dist/store/memory.js.map

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

package/dist/tools.d.ts

@@ -0,0 +1,91 @@
+import type { MemoryScope } from "@intentface/latch-core";
+import type { MemoryStore, ScopeRef } from "./types.js";
+/**
+ * Tool factories. Two families:
+ *
+ * - Agent-facing (`memory_search`, `memory_save`): merged into a memory-enabled
+ *   agent's turn by the provider.
+ * - Job-facing (`memory_read_index`, `memory_write_episode`,
+ *   `memory_read_episodes`, `memory_write_index`): given to the built-in
+ *   extractor/consolidator agents.
+ *
+ * Every factory binds `store + principal + scope` at construction — the model
+ * never chooses paths, so it cannot read or write outside its scope.
+ */
+export interface BoundScope<P> {
+    store: MemoryStore<P>;
+    principal: P;
+    scope: ScopeRef;
+}
+/**
+ * One participating memory level and its bound scope. Multi-level tools
+ * (`memory_search` fan-out, level-routed `memory_write_episode`,
+ * `memory_read_index` across levels) take an array of these; a single-element
+ * array behaves exactly like the classic single-scope binding.
+ */
+export interface LevelBoundScope<P> {
+    level: MemoryScope;
+    bound: BoundScope<P>;
+}
+/**
+ * Explicit (portable) shape for the authored tools — declaration emit cannot
+ * name the AI SDK's inferred `Tool<…>` type across package boundaries
+ * (TS2742), and agent configs only need `Record<string, unknown>` anyway.
+ */
+export interface MemoryTool {
+    description?: unknown;
+    inputSchema: unknown;
+    execute?: (input: never, options: never) => unknown;
+}
+export declare function memorySearchTool<P>(targets: LevelBoundScope<P>[], opts?: {
+    recordUsage?: (scopeKey: string, memoryIds: string[]) => void | Promise<void>;
+}): MemoryTool;
+export declare function memorySaveTool<P>(bound: BoundScope<P>, opts: {
+    agent: string;
+    onEpisodeWritten?: (args: {
+        path: string;
+        name: string;
+    }) => void | Promise<void>;
+    /** Invalidate the provider's cached index block for this scope. */
+    invalidate?: () => void;
+}): MemoryTool;
+export declare function memoryReadIndexTool<P>(bound: BoundScope<P>): MemoryTool;
+/**
+ * The extractor's cross-level index read: every participating level's compiled
+ * index in one call, so "what is already known" covers each level it may
+ * write to.
+ */
+export declare function memoryReadIndexesTool<P>(targets: LevelBoundScope<P>[]): MemoryTool;
+export declare function memoryWriteEpisodeTool<P>(targets: LevelBoundScope<P>[], opts: {
+    agent: string;
+    chatId?: string;
+    onEpisodeWritten?: (args: {
+        level: MemoryScope;
+        scope: ScopeRef;
+        path: string;
+        name: string;
+    }) => void | Promise<void>;
+    /**
+     * Outcome of each write attempt — the same three-way distinction
+     * `memoryWriteIndexTool` needs: episode written, nothing durable to write
+     * (never called), or the store refused. Only the last may tombstone the
+     * transcript window, and the run's answer can't tell them apart.
+     */
+    onWriteAttempt?: (ok: boolean) => void;
+}): MemoryTool;
+export declare function memoryReadEpisodesTool<P>(bound: BoundScope<P>): MemoryTool;
+export declare function memoryWriteIndexTool<P>(bound: BoundScope<P>, opts?: {
+    invalidate?: () => void;
+    /** This level's index-schema outline — advisory, see below. */
+    schema?: string;
+    /**
+     * Outcome of each write attempt. The caller needs it to tell three cases
+     * apart that all look identical from the run's answer: the index was
+     * rewritten, nothing needed changing (never called), and every attempt
+     * failed. Only the last one must keep the episodes pending for a retry —
+     * a model that gives up after a failed write still answers with a tidy
+     * summary, so the answer alone cannot be trusted as proof of a write.
+     */
+    onWriteAttempt?: (ok: boolean) => void;
+}): MemoryTool;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

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