@intentface/latch-memory 0.9.1

package/dist/tools.js

@@ -0,0 +1,389 @@
+import { tool, jsonSchema } from "ai";
+import { IndexValidationError, MEMORY_INDEX_FILENAME, parseIndex } from "./index-file.js";
+import { isUnderScopeRoot } from "./scope.js";
+import { schemaSectionWarnings } from "./schema.js";
+import { createSafetyOf, entryEvidence, EVIDENCE_RANK } from "./search-evidence.js";
+import { sanitizeMemoryText } from "./sanitize.js";
+/** One scope's search pass: backend hits + index-evidence merge + synthetic hits. */
+async function searchOneScope(bound, query, limit) {
+    const hits = await bound.store.search(bound.principal, bound.scope, query, limit);
+    // Evidence pass over the compiled index: the backend ranks free text,
+    // but create_safety needs EXACT signals (normalized alias equality) the
+    // backend can't provide — so match active entries ourselves and merge,
+    // strongest signal winning per result. Index unavailability degrades to
+    // body-only evidence, never a failed search.
+    let entries = [];
+    try {
+        const index = await bound.store.readIndex(bound.principal, bound.scope);
+        if (index)
+            entries = parseIndex(index).entries.filter((e) => !e.archived);
+    }
+    catch {
+        // body-only evidence
+    }
+    const evidenceById = new Map();
+    for (const e of entries) {
+        const evidence = entryEvidence(query, e);
+        if (evidence)
+            evidenceById.set(e.id, evidence);
+    }
+    const unverifiedIds = new Set(entries.filter((e) => e.unverified).map((e) => e.id));
+    const results = hits.map((h) => {
+        let matchedOn = "body";
+        // Trust mark: label (never hide) hits on unverified entries/episodes.
+        let unverified = /^status:\s*unverified\b/m.test(h.snippet);
+        for (const id of h.memoryIds) {
+            const evidence = evidenceById.get(id);
+            if (evidence && EVIDENCE_RANK[evidence] > EVIDENCE_RANK[matchedOn]) {
+                matchedOn = evidence;
+            }
+            if (unverifiedIds.has(id))
+                unverified = true;
+        }
+        return {
+            path: h.path,
+            snippet: sanitizeMemoryText(h.snippet),
+            matchedOn,
+            ...(unverified ? { unverified: true } : {}),
+        };
+    });
+    // Index entries with evidence the backend didn't surface (e.g. an alias
+    // spelled differently than the stored text ranks): synthesize a hit from
+    // the entry line itself so the exact match is never lost.
+    const surfacedIds = new Set(hits.flatMap((h) => h.memoryIds));
+    const syntheticIds = [];
+    for (const e of entries) {
+        const evidence = evidenceById.get(e.id);
+        if (!evidence || surfacedIds.has(e.id))
+            continue;
+        syntheticIds.push(e.id);
+        results.push({
+            path: `${bound.scope.root}/${MEMORY_INDEX_FILENAME}`,
+            snippet: sanitizeMemoryText(e.raw),
+            matchedOn: evidence,
+            ...(e.unverified ? { unverified: true } : {}),
+        });
+    }
+    const recalledIds = Array.from(new Set([...hits.flatMap((h) => h.memoryIds), ...syntheticIds]));
+    return { results, recalledIds };
+}
+export function memorySearchTool(targets, opts) {
+    const multi = targets.length > 1;
+    return tool({
+        description: "Search your long-term episodic memory (notes from past sessions plus archived facts). " +
+            "Use it when the conversation touches something you may already know — a preference, " +
+            "an earlier decision, an ongoing issue — before asking the user to repeat themselves. " +
+            (multi
+                ? "It searches every one of your memory levels at once; each hit is tagged with its level. "
+                : "") +
+            "Search is keyword-based: prefer the vocabulary of your memory index (in your " +
+            "instructions) — its exact terms and aliases match best — and when no index line " +
+            "obviously matches, keep the user's key words in the query too. " +
+            "Each hit carries matchedOn evidence (alias-exact | description | body) and the response " +
+            "carries create_safety — consult it before creating anything with memory_save.",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                query: { type: "string", description: "What to look for (topic, name, event)." },
+                limit: { type: "number", description: multi ? "Max results per level (default 6)." : "Max results (default 6)." },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        }),
+        execute: async ({ query, limit }) => {
+            // Fan out across levels; a single-target search returns exactly the
+            // classic shape (no level tags). Per-level failures degrade to empty
+            // results rather than failing the whole search.
+            const perScope = await Promise.all(targets.map(async (t) => {
+                try {
+                    return { t, ...(await searchOneScope(t.bound, query, limit ?? 6)) };
+                }
+                catch {
+                    return { t, results: [], recalledIds: [] };
+                }
+            }));
+            const merged = perScope.flatMap(({ t, results }) => results.map((r) => (multi ? { level: t.level, ...r } : r)));
+            // create_safety spans ALL levels: an exact match anywhere means the
+            // memory exists — the safe signal for memory_save dedup.
+            const create_safety = createSafetyOf(merged.map((r) => r.matchedOn));
+            if (opts?.recordUsage) {
+                for (const { t, recalledIds } of perScope) {
+                    if (recalledIds.length === 0)
+                        continue;
+                    // Fire-and-forget: retention bookkeeping must never fail or slow recall.
+                    void Promise.resolve(opts.recordUsage(t.bound.scope.key, recalledIds)).catch(() => { });
+                }
+            }
+            return merged.length > 0
+                ? { hits: merged, create_safety }
+                : { hits: [], create_safety, note: "no matching memories" };
+        },
+    });
+}
+export function memorySaveTool(bound, opts) {
+    return tool({
+        description: "Save a durable note to your long-term memory NOW — use when the user explicitly asks " +
+            "you to remember something, or states a lasting fact, preference, or decision. " +
+            "Search first: call memory_search and only save something NEW when its create_safety " +
+            'is not "exists". When it IS "exists", update the existing memory instead — save a ' +
+            "correction/update note that names it (quote its [m-…] id) rather than restating the " +
+            "fact as if new. Not for transient task details.",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                note: {
+                    type: "string",
+                    description: "The durable fact(s) to remember, stated plainly (1-5 sentences).",
+                },
+                slug: {
+                    type: "string",
+                    description: "Short kebab-case topic for the note's filename (e.g. 'race-goal').",
+                },
+            },
+            required: ["note"],
+            additionalProperties: false,
+        }),
+        execute: async ({ note, slug }) => {
+            const meta = {
+                agent: opts.agent,
+                extractedAt: new Date().toISOString(),
+                provenance: "user-requested",
+            };
+            const written = await bound.store.writeEpisode(bound.principal, bound.scope, {
+                slug: slug ?? "remember",
+                meta,
+                summary: note.slice(0, 120),
+                body: `## Facts\n- (user-requested) ${note.replace(/\n+/g, " ").trim()}`,
+            });
+            if (!written)
+                return { saved: false, error: "memory store unreachable" };
+            opts.invalidate?.();
+            if (opts.onEpisodeWritten) {
+                void Promise.resolve(opts.onEpisodeWritten(written)).catch(() => { });
+            }
+            return { saved: true, path: written.path };
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Job-facing tools (extractor / consolidator)
+// ---------------------------------------------------------------------------
+export function memoryReadIndexTool(bound) {
+    return tool({
+        description: "Read the current compiled memory index (MEMORY.md) for this scope. " +
+            "Returns null when no index exists yet.",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        }),
+        execute: async () => {
+            const index = await bound.store.readIndex(bound.principal, bound.scope);
+            return { index: index ?? null };
+        },
+    });
+}
+/**
+ * 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 function memoryReadIndexesTool(targets) {
+    return tool({
+        description: "Read the current compiled memory index (MEMORY.md) of every memory level in your task. " +
+            "Returns null for levels with no index yet.",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        }),
+        execute: async () => {
+            const indexes = await Promise.all(targets.map(async (t) => {
+                const index = await t.bound.store.readIndex(t.bound.principal, t.bound.scope);
+                return { level: t.level, index: index ?? null };
+            }));
+            return { indexes };
+        },
+    });
+}
+export function memoryWriteEpisodeTool(targets, opts) {
+    const multi = targets.length > 1;
+    const levels = targets.map((t) => t.level);
+    return tool({
+        description: "Write ONE immutable episode file capturing the durable memories from this transcript" +
+            (multi
+                ? " for ONE memory level. Call at most once per level, and only for levels with something durable to store."
+                : ". Call at most once per run, and only when there is something durable to store."),
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                // Always accepted — the extractor prompt says "call with that level's
+                // `level` value" regardless of level count, and a single-target
+                // binding routes everything to its one scope anyway. Only REQUIRED
+                // when there is a real choice to make.
+                level: {
+                    type: "string",
+                    enum: levels,
+                    description: "The memory level this episode belongs to (see your task).",
+                },
+                slug: {
+                    type: "string",
+                    description: "Short kebab-case topic for the filename (e.g. 'calf-strain-week2').",
+                },
+                summary: { type: "string", description: "One-line summary of the episode." },
+                happened: {
+                    type: "string",
+                    description: "2-4 sentences of session context (optional).",
+                },
+                facts: {
+                    type: "array",
+                    description: "The durable facts, each tagged with its origin.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            text: { type: "string" },
+                            provenance: { type: "string", enum: ["user-said", "tool-derived"] },
+                        },
+                        required: ["text", "provenance"],
+                        additionalProperties: false,
+                    },
+                },
+                aliases: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Alternate lookup terms for the facts: names/spellings/nicknames of entities " +
+                        "(e.g. ['Robert Smith', 'Bob']) plus everyday recall keys when a fact's own " +
+                        "wording is technical or unusual (e.g. 'coffee' for a caffeine rule) — so " +
+                        "later keyword recall matches any form.",
+                },
+            },
+            required: [...(multi ? ["level"] : []), "slug", "summary", "facts"],
+            additionalProperties: false,
+        }),
+        execute: async ({ level, slug, summary, happened, facts, aliases }) => {
+            // Route to the requested level; a single-target binding ignores the
+            // param (there is nowhere else to go).
+            const target = multi ? targets.find((t) => t.level === level) : targets[0];
+            if (!target) {
+                return {
+                    saved: false,
+                    error: `unknown level ${JSON.stringify(level)} — this run's levels are: ${levels.join(", ")}`,
+                };
+            }
+            const bound = target.bound;
+            // An empty facts list is not a store failure — the model chose to write
+            // nothing. Left unreported so it stays a normal zero-yield run rather
+            // than forcing a retry.
+            if (facts.length === 0)
+                return { saved: false, error: "no facts provided" };
+            const provs = new Set(facts.map((f) => f.provenance));
+            const provenance = provs.size === 1 ? [...provs][0] : "mixed";
+            const meta = {
+                chat: opts.chatId,
+                agent: opts.agent,
+                extractedAt: new Date().toISOString(),
+                provenance,
+                ...(aliases?.length ? { aliases } : {}),
+                // Trust mark: everything the background extractor writes is
+                // machine-inferred until the consolidator sees corroboration —
+                // explicit memory_save episodes carry no status.
+                status: "unverified",
+            };
+            const body = [
+                ...(happened ? ["## What happened", happened.trim(), ""] : []),
+                "## Facts",
+                ...facts.map((f) => `- (${f.provenance}) ${f.text.replace(/\n+/g, " ").trim()}`),
+            ].join("\n");
+            const written = await bound.store.writeEpisode(bound.principal, bound.scope, {
+                slug,
+                meta,
+                summary,
+                body,
+            });
+            if (!written) {
+                opts.onWriteAttempt?.(false);
+                return { saved: false, error: "memory store unreachable" };
+            }
+            opts.onWriteAttempt?.(true);
+            if (opts.onEpisodeWritten) {
+                void Promise.resolve(opts.onEpisodeWritten({ level: target.level, scope: bound.scope, ...written })).catch(() => { });
+            }
+            return { saved: true, ...(multi ? { level: target.level } : {}), path: written.path };
+        },
+    });
+}
+export function memoryReadEpisodesTool(bound) {
+    return tool({
+        description: "Read episode files by path (the paths listed in your task).",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                paths: { type: "array", items: { type: "string" } },
+            },
+            required: ["paths"],
+            additionalProperties: false,
+        }),
+        execute: async ({ paths }) => {
+            // Scope lock: only paths strictly under this scope's root are readable
+            // (segment-wise — a bare startsWith would pass `root-evil/x` and `..`).
+            const inScope = paths.filter((p) => isUnderScopeRoot(bound.scope.root, p));
+            const episodes = await bound.store.readEpisodes(bound.principal, bound.scope, inScope);
+            return { episodes };
+        },
+    });
+}
+export function memoryWriteIndexTool(bound, opts) {
+    // Schema adherence is ADVISORY: the first off-schema rewrite gets bounced
+    // once through the problems loop so the model can self-correct; after that
+    // the write always proceeds (with warnings) — a sweep must never wedge on
+    // schema drift, unlike the hard rules validateIndexRewrite enforces.
+    let schemaNudged = false;
+    return tool({
+        description: "Replace the compiled memory index (MEMORY.md) with a new version. The previous " +
+            "version is snapshotted automatically. The rewrite is validated: hard line cap, no " +
+            "duplicate ids, and no previously-active entry may disappear (move superseded/expired " +
+            "entries under '## Archive'). On rejection you get the problems back — fix and retry.",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                content: { type: "string", description: "The complete new MEMORY.md content." },
+            },
+            required: ["content"],
+            additionalProperties: false,
+        }),
+        execute: async ({ content }) => {
+            const warnings = opts?.schema ? schemaSectionWarnings(opts.schema, content) : [];
+            if (warnings.length > 0 && !schemaNudged) {
+                schemaNudged = true;
+                // Counts as a FAILED attempt: nothing was stored, so a model that
+                // gives up right after the nudge must not read as "nothing needed
+                // writing" — that would consume pending episodes with no index write.
+                opts?.onWriteAttempt?.(false);
+                return {
+                    ok: false,
+                    problems: warnings.map((w) => `${w} (schema advisory — fix, or resubmit as-is to override)`),
+                };
+            }
+            try {
+                await bound.store.writeIndex(bound.principal, bound.scope, content);
+                opts?.invalidate?.();
+                opts?.onWriteAttempt?.(true);
+                return warnings.length > 0 ? { ok: true, warnings } : { ok: true };
+            }
+            catch (error) {
+                opts?.onWriteAttempt?.(false);
+                if (error instanceof IndexValidationError) {
+                    return { ok: false, problems: error.problems };
+                }
+                return {
+                    ok: false,
+                    error: String(error),
+                    // The model's own instructions say to re-read and retry once; say it
+                    // here too, where it lands next to the failure it applies to.
+                    retry: "Call memory_read_index, rebuild the rewrite on what it returns now, and retry once.",
+                };
+            }
+        },
+    });
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,130 @@
+import type { MemoryConfig } from "@intentface/latch-core";
+/**
+ * Where a memory came from. Tool-derived facts are less trustworthy than
+ * things the user said directly (a prompt-injection persistence vector), so
+ * every stored fact carries its origin and the consolidator preserves it.
+ */
+export type Provenance = "user-said" | "tool-derived" | "user-requested" | "mixed";
+/**
+ * A resolved memory scope: WHERE one memory store lives.
+ *
+ * - `key` is the canonical scope identity used everywhere outside the store
+ *   (DB rows, caches, leases): `${connection}:${root}`.
+ * - `root` is the folder inside the connection's workspace, e.g.
+ *   `__private_root/_memory/running-coach/u-usr123` for per-user scopes (the
+ *   `__private_root` head resolves to the authenticated caller's Loredex
+ *   private root) or `_memory/<agent>/org` for `agent-org`.
+ */
+export interface ScopeRef {
+    key: string;
+    connection: string;
+    root: string;
+}
+/** Frontmatter of one episode file. */
+export interface EpisodeMeta {
+    /** Source chat id (absent for `memory_save` episodes). */
+    chat?: string;
+    agent: string;
+    /** ISO timestamp; also drives the episode's filename stamp. */
+    extractedAt: string;
+    provenance: Provenance;
+    /**
+     * Alternate names/spellings/nicknames of entities the episode mentions —
+     * the consolidator carries them onto index entries (`aka:`) so recall
+     * matches any form.
+     */
+    aliases?: string[];
+    /**
+     * Trust mark: `unverified` on episodes written by the background extractor
+     * (auto-extracted, unconfirmed). Explicit `memory_save` episodes carry no
+     * status. The consolidator labels/promotes index entries accordingly.
+     */
+    status?: "unverified";
+}
+export interface MemorySearchHit {
+    path: string;
+    snippet: string;
+    /**
+     * Memory identities this hit touches, for usage/retention tracking: `[m-…]`
+     * entry ids found in the snippet plus the file path itself.
+     */
+    memoryIds: string[];
+}
+/**
+ * Thrown by `writeIndex` when the backing store can't be reached (unauthorized
+ * connection, missing workspace) — the one operation with no in-band way to
+ * signal "nothing was written". Distinguishable from `IndexValidationError`:
+ * this means "retry later", that means "fix the content and retry".
+ */
+export declare class MemoryStoreUnreachableError extends Error {
+    constructor(message?: string);
+}
+/**
+ * The storage seam. One implementation per backing (Loredex first); everything
+ * above it (provider, tools, jobs) is backend-agnostic.
+ *
+ * Contract: read-side operations NEVER throw for "store unreachable"
+ * (unauthorized connection, missing workspace) — they return `undefined`/empty
+ * so a memory failure degrades gracefully. `writeIndex` is the carve-out: it
+ * returns nothing, so unreachability there throws
+ * `MemoryStoreUnreachableError`. Operations MAY also throw for contract
+ * violations (e.g. an index rewrite that fails validation →
+ * `IndexValidationError`), which tool wrappers surface to the model as
+ * structured errors.
+ */
+export interface MemoryStore<P> {
+    /** Cheap probe: is the scope's backing reachable for this principal? */
+    available(principal: P, scope: ScopeRef): Promise<boolean>;
+    /** The compiled index (MEMORY.md) text, or undefined if absent/unreachable. */
+    readIndex(principal: P, scope: ScopeRef): Promise<string | undefined>;
+    /**
+     * Replace the compiled index. Snapshots the previous version to
+     * `archive/index-snapshots/` first and validates the rewrite via
+     * `validateIndexRewrite` (throws `IndexValidationError` on violation).
+     */
+    writeIndex(principal: P, scope: ScopeRef, text: string): Promise<void>;
+    /**
+     * Write one immutable episode file under `episodes/`. Returns its path, or
+     * undefined when the store is unreachable.
+     */
+    writeEpisode(principal: P, scope: ScopeRef, episode: {
+        slug: string;
+        meta: EpisodeMeta;
+        summary: string;
+        body: string;
+    }): Promise<{
+        path: string;
+        name: string;
+    } | undefined>;
+    /** Batch-read episode files by path (missing files are skipped). */
+    readEpisodes(principal: P, scope: ScopeRef, paths: string[]): Promise<Array<{
+        path: string;
+        text: string;
+    }>>;
+    /** Hybrid search scoped to this memory folder. */
+    search(principal: P, scope: ScopeRef, query: string, limit?: number): Promise<MemorySearchHit[]>;
+    /**
+     * Read one well-known auxiliary file by workspace-relative path (e.g. the
+     * shared user-level SCHEMA.md). Not scope-bound — callers pass fixed,
+     * code-owned paths only, never model-chosen ones. `undefined` when absent
+     * or unreachable (read-side never throws).
+     */
+    readFile(principal: P, args: {
+        connection: string;
+        path: string;
+    }): Promise<string | undefined>;
+    /**
+     * Create-or-replace one auxiliary file by workspace-relative path (schema
+     * editors). Ensures parent folders. Throws `MemoryStoreUnreachableError`
+     * when the backing can't be reached.
+     */
+    writeFile(principal: P, args: {
+        connection: string;
+        path: string;
+        content: string;
+        summary?: string;
+    }): Promise<void>;
+}
+/** Re-exported for convenience so platform code can import from one place. */
+export type { MemoryConfig };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,cAAc,GAAG,gBAAgB,GAAG,OAAO,CAAC;AAEnF;;;;;;;;;GASG;AACH,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;GAKG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,OAAO,SAA6B;CAIjD;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,wEAAwE;IACxE,SAAS,CAAC,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3D,+EAA+E;IAC/E,SAAS,CAAC,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACtE;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE;;;OAGG;IACH,YAAY,CACV,SAAS,EAAE,CAAC,EACZ,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAC1E,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;IACvD,oEAAoE;IACpE,YAAY,CACV,SAAS,EAAE,CAAC,EACZ,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAClD,kDAAkD;IAClD,MAAM,CACJ,SAAS,EAAE,CAAC,EACZ,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAChG;;;;OAIG;IACH,SAAS,CACP,SAAS,EAAE,CAAC,EACZ,IAAI,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5E,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,8EAA8E;AAC9E,YAAY,EAAE,YAAY,EAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * Thrown by `writeIndex` when the backing store can't be reached (unauthorized
+ * connection, missing workspace) — the one operation with no in-band way to
+ * signal "nothing was written". Distinguishable from `IndexValidationError`:
+ * this means "retry later", that means "fix the content and retry".
+ */
+export class MemoryStoreUnreachableError extends Error {
+    constructor(message = "memory store unreachable") {
+        super(message);
+        this.name = "MemoryStoreUnreachableError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAyDA;;;;;GAKG;AACH,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IACpD,YAAY,OAAO,GAAG,0BAA0B;QAC9C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@intentface/latch-memory",
+  "version": "0.9.1",
+  "description": "Latch agent memory — always-loaded compiled index, searchable episodic store, and background extraction/consolidation over a pluggable MemoryStore (Loredex-backed first).",
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "agents",
+    "llm",
+    "agent-memory"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@intentface/latch-core": "^0.9.1"
+  },
+  "peerDependencies": {
+    "ai": ">=7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "ai": "^7.0.2",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4",
+    "@intentface/latch-mcp": "0.9.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Intentface/intentface-latch.git",
+    "directory": "packages/memory"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "eval:memory-search": "tsx evals/run.ts",
+    "eval:auth-live": "tsx evals/live/auth.ts",
+    "eval:memory-search:live": "tsx evals/live/run-live.ts",
+    "eval:seed-live": "tsx evals/live/seed.ts",
+    "eval:regen-fixtures": "tsx evals/generate.ts"
+  }
+}