@intentface/latch-memory 0.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intentface
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# @intentface/latch-memory
+
+Pluggable, platform-managed memory for Latch agents. Declare `memory` on an
+agent and the platform does all upkeep:
+
+1. **Always-loaded index** — a compiled `MEMORY.md` (≤100 lines, one fact per
+   line with date, provenance, and source links) is injected into the system
+   prompt every turn, plus standing instructions for the tools.
+2. **Episodic store + recall** — immutable, timestamped episode notes live in
+   the agent's own connection workspace: per-user scopes under the caller's
+   private root (`__private_root/_memory/<agent|_user>/u-<id>/`), `agent-org`
+   under the shared `_memory/<agent>/org/`;
+   the agent searches them on demand with `memory_search` (every recall is
+   usage-tracked — the retention signal) and saves explicit "remember this"
+   notes with `memory_save`.
+3. **Background consolidation** — a cron sweep extracts durable facts from
+   idle chats (`memory-extractor`, cheap model) and folds pending episodes
+   into the index (`memory-consolidator`), superseding and expiring entries.
+
+## Design invariants
+
+- **Scopes** (`agent-user` | `agent-org` | `user`) are hard boundaries: tools
+  are path-locked at construction, and consolidation never crosses a scope.
+  Per-user scopes live under the Loredex **private root** (owner-only ACL):
+  `__private_root/_memory/<agent>/u-<id>` for `agent-user`,
+  `__private_root/_memory/_user/u-<id>` for `user`. The `u-<id>` leaf is kept
+  even though the private root is already per-user: it keeps roots globally
+  unique (scope keys stay `${connection}:${root}`) and keeps users' stores
+  apart on a workspace-shared connection, where every caller resolves the
+  same private root.
+- **Non-destructive consolidation**: episodes are immutable; only the index is
+  rewritten, every rewrite snapshots the previous version first, and the
+  validator rejects any rewrite that silently drops a previously ACTIVE entry
+  (supersede/expire = move to `## Archive`; archived entries may be dropped
+  later — snapshots preserve history, so the size cap stays satisfiable).
+- **Graceful degradation**: an unreachable/unauthorized store means a turn
+  without memory, never a failed turn.
+- **Anti-hot-loop**: every job completion advances its eligibility timestamp —
+  success, failure, or "not actually memory-enabled".
+- **Extraction idempotency**: every completed extraction records an idempotency
+  key (`extractionRunKey` — content hash of the message window + the extraction
+  prompt version). An unchanged window never re-buys a run, and a run that
+  found NOTHING tombstones its content via the same key. Failed runs never
+  record a key, so they stay retryable. Bump `EXTRACTION_PROMPT_VERSION` to
+  invalidate old keys after a material prompt change.
+- **Provenance**: every fact is tagged `user-said` / `tool-derived` /
+  `user-requested`; the extractor is instructed to scrub secrets/PII.
+- **Trust marks**: extractor-written episodes carry `status: unverified`
+  frontmatter; index entries folded from them carry an `unverified` marker
+  (labeled — in the injected block and in search results — never hidden). The
+  consolidator promotes an entry only on later, independent corroboration.
+  Explicit `memory_save` notes are never marked unverified.
+- **Aliases + create-safety**: entries can carry `aka:` aliases (episodes:
+  `aliases:` frontmatter) for subjects with several names/spellings.
+  `memory_search` matches them exactly (NFKC/case/whitespace-normalized),
+  tags every hit with `matchedOn` evidence (`alias-exact` | `description` |
+  `body`), and derives a response-level `create_safety`
+  (`exists` | `probable` | `unknown`) that `memory_save` instructs the agent
+  to consult before creating anything new.
+- **Injection hardening**: memory text is LLM-authored from user conversation —
+  a prompt-injection persistence vector. At injection time (the `<memory>`
+  block, search snippets) it passes through `sanitizeMemoryText`, which
+  de-fangs envelope/role tags and strips a named set of known injection
+  phrasings. Volume reduction, not a guarantee — the standing instructions
+  additionally declare the envelope's content to be data, never instructions.
+
+## Pieces
+
+| Module | What it is |
+| --- | --- |
+| `types` / `scope` | `MemoryStore` seam, `ScopeRef` derivation (`scopeRefOf`) |
+| `store/loredex` | `MemoryStore` over a Loredex MCP connection (opens per op via the `ConnectionRegistry`; tolerant result parsing; no delete — snapshot + rewrite) |
+| `index-file` | MEMORY.md grammar: parse, `validateIndexRewrite`, id minting |
+| `provider` | `createMemoryProvider` → the runtime's `MemoryProvider` (TTL-cached index block + bound tools) |
+| `tools` | agent-facing `memory_search`/`memory_save` + scope-locked job tools |
+| `prompts/*` | injection block, extractor/consolidator instructions + prompt builders |
+| `jobs/types` | `MemoryJobStore` (implemented in `@intentface/latch-drizzle`: `createMemoryJobStore`) |
+
+The sweep itself is platform glue (`apps/latch-platform/src/lib/memory/sweep.ts`),
+following the Codex pattern: idle-gated parallel extraction, per-scope
+lease-serialized consolidation with cooldown + watermark, usage-based expiry
+(default 30 days unrecalled).
+
+## Wiring it into a host
+
+This package ships the ingredients, not the jobs — a host app (see
+`apps/latch-platform` for the reference implementation of every step) wires:
+
+1. **Tables + job store** — `@intentface/latch-drizzle`'s migrations create
+   `latch_memory_chat_state` / `latch_memory_scope_state` / `latch_memory_usage`;
+   build the store with `createMemoryJobStore(db)`.
+2. **Store + provider → runtime** — in the composition root:
+
+   ```ts
+   const memoryStore = createLoredexStore({ connections });
+   const memoryProvider = createMemoryProvider({
+     store: memoryStore,
+     scopeOf: ({ principal, agent, memory }) =>
+       scopeRefOf({ agent, memory, userId: principal.userId }),
+     recordUsage: (scopeKey, ids) => memoryJobs.recordUsage(scopeKey, ids, Date.now()),
+     onEpisodeWritten: (a) => memoryJobs.touchScope(/* mark scope dirty */),
+   });
+   const runtime = createRuntime({ ...rest, memory: memoryProvider });
+   ```
+
+   That alone gives every agent declaring `memory` the injected index block and
+   the `memory_search`/`memory_save` tools.
+3. **Two job agents** — register `memory-extractor` and `memory-consolidator`
+   as code agents (cheap model, no connections) built from the exported parts:
+   `EXTRACTOR_INSTRUCTIONS`/`CONSOLIDATOR_INSTRUCTIONS` + the scope-locked tool
+   factories (`memoryReadIndexTool`, `memoryWriteEpisodeTool`,
+   `memoryReadEpisodesTool`, `memoryWriteIndexTool`), bound from the sweep's
+   `turnContext`. Hide them from user-facing pickers (the platform reserves the
+   `memory-*` name prefix).
+4. **The sweep** — a cron-driven loop over `MemoryJobStore`: claim idle chats →
+   `runtime.runAgent("memory-extractor", …)` under the chat's own reconstructed
+   principal → advance the seq watermark; claim dirty scopes past cooldown →
+   `runtime.runAgent("memory-consolidator", …)` → clear consumed episodes.
+   Copy `apps/latch-platform/src/lib/memory/sweep.ts` — the always-advance
+   eligibility discipline (no hot loops) and the lease fencing live there.
+5. **Declare memory on agents** — `memory: { scope, connection }` in
+   `defineAgent` config or the UI agent record; the connection must be one the
+   agent itself declares.
+
+## Offline evals
+
+`evals/` holds the deterministic (zero-LLM, zero-network) evaluation
+foundation for this package:
+
+- **Synthetic corpus** — a seeded, byte-deterministic week of running-coach
+  conversations (`evals/corpus/`, seed 42, mulberry32 PRNG) with planted
+  contradictions, temporal supersessions, stale facts, paraphrased
+  prompt-injection attempts, and implicit preferences. Gold labels live in
+  `evals/fixtures/corpus/gold/`, referenced by `fixture_id`
+  (`<session>:<messageIndex>`).
+- **Retrieval benchmark** — a reference memory-file set
+  (`evals/fixtures/memory-files/`), sealed qrels (`evals/fixtures/qrels.json`;
+  the search path only ever sees a `PublicQuery {id, text}` projection), and a
+  pure scorer (P@k, R@k, MRR, graded nDCG@k, top-1).
+
+Commands (from `packages/memory/`):
+
+- `pnpm eval:memory-search` — run every qrels query through the real
+  `memory_search` tool over the in-memory store; prints a per-tier report and
+  rewrites the committed baseline
+  (`evals/results/memory-search-baseline.json`).
+- `pnpm eval:regen-fixtures` — regenerate all committed fixtures after a
+  deliberate template change (`determinism.test.ts` fails on any drift).
+
+The adversarial qrels tier (paraphrases sharing <30% content words with their
+target) is EXPECTED to score ~0 on keyword search — it exists to measure the
+gap, not to be tuned away.
+
+## Caveat
+
+Per-user scopes (`agent-user`, `user`) are stored under the caller's Loredex
+private root (owner-only ACL), which is real privacy **only when the
+connection authenticates as the end user**: on a workspace-shared connection
+every call resolves the connection identity's private root, not the end
+user's — all users' memory then lands in one private root, separated only by
+the `u-<id>` folder convention (as before, but now hidden from the rest of
+the workspace). Use a personal connection where per-user privacy matters.
+`agent-org` memory lives in the shared `_memory/**` tree by design.

package/dist/extraction-key.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The idempotency key for one extraction window. Hashes role + text only
+ * (order-preserving, unambiguously framed), deliberately NOT `seq`: a
+ * re-sequenced chat (legacy heal, replay) still hashes the same, which is
+ * exactly the duplicate-run case the key exists to suppress. Bumping
+ * `EXTRACTION_PROMPT_VERSION` changes every key, so already-tombstoned
+ * windows become extractable again under the new prompt.
+ *
+ * `opts.schemaFingerprint` (see `schemasFingerprint`) covers the run's level
+ * set and per-level schemas the same way: a schema edit — or a level added or
+ * removed — changes the key, so the same content becomes re-extractable under
+ * the new configuration.
+ */
+export declare function extractionRunKey(messages: ReadonlyArray<{
+    role: string;
+    text: string;
+}>, opts?: {
+    schemaFingerprint?: string;
+}): string;
+//# sourceMappingURL=extraction-key.d.ts.map

package/dist/extraction-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extraction-key.d.ts","sourceRoot":"","sources":["../src/extraction-key.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACvD,IAAI,CAAC,EAAE;IAAE,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAE,GACpC,MAAM,CAIR"}

package/dist/extraction-key.js

@@ -0,0 +1,43 @@
+import { EXTRACTION_PROMPT_VERSION } from "./prompts/extractor.js";
+/**
+ * Extraction-run idempotency keys.
+ *
+ * A key fingerprints WHAT an extraction run processed: the content of the
+ * message window plus the extraction prompt version. The sweep persists the
+ * key of the last COMPLETED run per chat (`last_extracted_key`) and skips a
+ * new paid run whenever the next window hashes to the same key (watermark
+ * reset, replayed rows) — including runs that yielded zero memories, where
+ * the recorded key doubles as a tombstone so the same content is never
+ * re-extracted. FAILED runs (LLM error/timeout) never record a key, so they
+ * stay eligible for retry.
+ */
+/** FNV-1a 64-bit, hex — deterministic, dependency-free (Node/edge safe). */
+function fnv1a64(input) {
+    let h = 0xcbf29ce484222325n;
+    const prime = 0x100000001b3n;
+    const mask = 0xffffffffffffffffn;
+    for (let i = 0; i < input.length; i++) {
+        h ^= BigInt(input.charCodeAt(i));
+        h = (h * prime) & mask;
+    }
+    return h.toString(16).padStart(16, "0");
+}
+/**
+ * The idempotency key for one extraction window. Hashes role + text only
+ * (order-preserving, unambiguously framed), deliberately NOT `seq`: a
+ * re-sequenced chat (legacy heal, replay) still hashes the same, which is
+ * exactly the duplicate-run case the key exists to suppress. Bumping
+ * `EXTRACTION_PROMPT_VERSION` changes every key, so already-tombstoned
+ * windows become extractable again under the new prompt.
+ *
+ * `opts.schemaFingerprint` (see `schemasFingerprint`) covers the run's level
+ * set and per-level schemas the same way: a schema edit — or a level added or
+ * removed — changes the key, so the same content becomes re-extractable under
+ * the new configuration.
+ */
+export function extractionRunKey(messages, opts) {
+    const payload = messages.map((m) => `${m.role}\u0000${m.text}`).join("\u0001");
+    const suffix = opts?.schemaFingerprint ? `:${opts.schemaFingerprint}` : "";
+    return `x${EXTRACTION_PROMPT_VERSION}:${fnv1a64(payload)}${suffix}`;
+}
+//# sourceMappingURL=extraction-key.js.map

package/dist/extraction-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extraction-key.js","sourceRoot":"","sources":["../src/extraction-key.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AAEnE;;;;;;;;;;;GAWG;AAEH,4EAA4E;AAC5E,SAAS,OAAO,CAAC,KAAa;IAC5B,IAAI,CAAC,GAAG,mBAAmB,CAAC;IAC5B,MAAM,KAAK,GAAG,cAAc,CAAC;IAC7B,MAAM,IAAI,GAAG,mBAAmB,CAAC;IACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QACjC,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC;IACzB,CAAC;IACD,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAuD,EACvD,IAAqC;IAErC,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/E,MAAM,MAAM,GAAG,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3E,OAAO,IAAI,yBAAyB,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,MAAM,EAAE,CAAC;AACtE,CAAC"}

package/dist/index-file.d.ts

@@ -0,0 +1,77 @@
+import type { Provenance } from "./types.js";
+/**
+ * The compiled index (MEMORY.md): parsing, id minting, and the rewrite
+ * validator that makes consolidation non-destructive.
+ *
+ * Entry grammar (one line per fact):
+ *
+ *   - [m-7f3a] (2026-07-12, user-said) Prefers concise answers. ← episodes/2026-07-12-09-30-onboarding.md
+ *   - [m-9911] (2026-06-02, user-said; superseded 2026-07-20 by m-a1c2) Old fact. ← episodes/…
+ *
+ * Optional `;`-separated parenthetical tail markers (any order):
+ *   - `aka: Robert Smith, Bobby` — alternate names/spellings of the entry's
+ *     subject, matched exactly by memory_search;
+ *   - `unverified` — auto-extracted and not yet confirmed (trust mark; the
+ *     consolidator removes it on corroboration).
+ *
+ * Entries under a `## Archive` heading are archived (superseded/expired).
+ * The validator enforces the two invariants the research said matter most:
+ * a hard size cap, and "no entry ever silently disappears" — a rewrite may
+ * move an entry to Archive but never drop its id.
+ */
+export declare const MEMORY_INDEX_FILENAME = "MEMORY.md";
+/** Soft cap the consolidator is instructed to stay under. */
+export declare const INDEX_LINE_CAP = 100;
+/** Hard cap: rewrites longer than this are rejected outright. */
+export declare const INDEX_LINE_HARD_CAP = 120;
+export interface IndexEntry {
+    id: string;
+    /** YYYY-MM-DD the fact was recorded/updated. */
+    date?: string;
+    provenance?: Provenance;
+    /** Set when the parenthetical carries a `superseded <date> by <id>` marker. */
+    superseded?: {
+        date?: string;
+        by?: string;
+    };
+    /** Alternate names/spellings of the entry's subject (the `aka:` marker). */
+    aliases: string[];
+    /** True when the parenthetical carries the `unverified` trust mark. */
+    unverified: boolean;
+    text: string;
+    /** Source episode paths (the `← …` tail). */
+    sources: string[];
+    /** True when the entry sits under the `## Archive` heading. */
+    archived: boolean;
+    /** The entry line verbatim (for surfacing the entry as a search snippet). */
+    raw: string;
+}
+export interface ParsedIndex {
+    entries: IndexEntry[];
+    lineCount: number;
+    /** Lines that look like entries but don't parse — surfaced to the model. */
+    malformed: string[];
+}
+export declare function parseIndex(text: string): ParsedIndex;
+export declare class IndexValidationError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+/**
+ * Validate a proposed index rewrite against the previous version. Returns the
+ * problem list (empty = valid). Rules:
+ * - hard line cap (`INDEX_LINE_HARD_CAP`);
+ * - no duplicate entry ids;
+ * - every previously ACTIVE id must still be present (active or archived) —
+ *   supersede/expire is a MOVE to `## Archive`, never a silent delete;
+ * - previously ARCHIVED ids MAY be dropped: every rewrite snapshots the full
+ *   prior index first, so archived history stays recoverable while the cap
+ *   stays satisfiable (otherwise Archive would grow past the cap forever);
+ * - entry-shaped lines must parse.
+ */
+export declare function validateIndexRewrite(prev: string | undefined, next: string): string[];
+/** Mint a new entry id not already taken (6 hex chars, `m-` prefixed). */
+export declare function mintMemoryId(taken: ReadonlySet<string>): string;
+/** All `[m-…]` ids referenced in a blob of text (for usage tracking). */
+export declare function memoryIdsIn(text: string): string[];
+//# sourceMappingURL=index-file.d.ts.map

package/dist/index-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-file.d.ts","sourceRoot":"","sources":["../src/index-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,eAAO,MAAM,qBAAqB,cAAc,CAAC;AACjD,6DAA6D;AAC7D,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,+EAA+E;IAC/E,UAAU,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,4EAA4E;IAC5E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,uEAAuE;IACvE,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,+DAA+D;IAC/D,QAAQ,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AASD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAwEpD;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;gBAChB,QAAQ,EAAE,MAAM,EAAE;CAK/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAiCrF;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,CAO/D;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAElD"}

package/dist/index-file.js

@@ -0,0 +1,169 @@
+/**
+ * The compiled index (MEMORY.md): parsing, id minting, and the rewrite
+ * validator that makes consolidation non-destructive.
+ *
+ * Entry grammar (one line per fact):
+ *
+ *   - [m-7f3a] (2026-07-12, user-said) Prefers concise answers. ← episodes/2026-07-12-09-30-onboarding.md
+ *   - [m-9911] (2026-06-02, user-said; superseded 2026-07-20 by m-a1c2) Old fact. ← episodes/…
+ *
+ * Optional `;`-separated parenthetical tail markers (any order):
+ *   - `aka: Robert Smith, Bobby` — alternate names/spellings of the entry's
+ *     subject, matched exactly by memory_search;
+ *   - `unverified` — auto-extracted and not yet confirmed (trust mark; the
+ *     consolidator removes it on corroboration).
+ *
+ * Entries under a `## Archive` heading are archived (superseded/expired).
+ * The validator enforces the two invariants the research said matter most:
+ * a hard size cap, and "no entry ever silently disappears" — a rewrite may
+ * move an entry to Archive but never drop its id.
+ */
+export const MEMORY_INDEX_FILENAME = "MEMORY.md";
+/** Soft cap the consolidator is instructed to stay under. */
+export const INDEX_LINE_CAP = 100;
+/** Hard cap: rewrites longer than this are rejected outright. */
+export const INDEX_LINE_HARD_CAP = 120;
+// Id charset is deliberately wider than what `mintMemoryId` produces (hex):
+// the consolidator model mints ids itself and "hex-looking" ids like m-g8d7e9
+// are common. Ids are opaque keys — uniqueness matters, the alphabet doesn't,
+// and rejecting them sends the model into pointless rewrite loops.
+const ENTRY_RE = /^\s*-\s*\[(m-[0-9a-z]{4,8})\]\s*\(([^)]*)\)\s*(.*)$/;
+const PROVENANCES = new Set(["user-said", "tool-derived", "user-requested", "mixed"]);
+export function parseIndex(text) {
+    const lines = text.split("\n");
+    const entries = [];
+    const malformed = [];
+    let archived = false;
+    for (const line of lines) {
+        if (/^##\s+archive\b/i.test(line.trim())) {
+            archived = true;
+            continue;
+        }
+        if (/^##\s+/.test(line.trim()) && !/^##\s+archive\b/i.test(line.trim())) {
+            // A new section after Archive would be unusual, but honor it.
+            if (archived && !/archive/i.test(line))
+                archived = false;
+            continue;
+        }
+        const looksLikeEntry = /^\s*-\s*\[m-/.test(line);
+        const m = ENTRY_RE.exec(line);
+        if (!m) {
+            if (looksLikeEntry)
+                malformed.push(line.trim());
+            continue;
+        }
+        const [, id, paren, rest] = m;
+        // Parenthetical: `<date>, <provenance>[; superseded <date> by <id>]` — parse
+        // leniently; a hand-edited index must not break recall.
+        const [head, ...tailParts] = paren.split(";").map((s) => s.trim());
+        const headBits = head.split(",").map((s) => s.trim());
+        const date = /^\d{4}-\d{2}-\d{2}$/.test(headBits[0] ?? "") ? headBits[0] : undefined;
+        const prov = headBits.find((b) => PROVENANCES.has(b));
+        let superseded;
+        const supersededPart = tailParts.find((p) => /^superseded\b/i.test(p));
+        if (supersededPart) {
+            const sd = /(\d{4}-\d{2}-\d{2})/.exec(supersededPart)?.[1];
+            // Bounded lookahead: an overlong id (m-abcdefghi) must not silently
+            // truncate into a valid-looking — but wrong — supersession pointer.
+            const by = /\bby\s+(m-[0-9a-z]{4,8})(?![0-9A-Za-z])/.exec(supersededPart)?.[1];
+            superseded = { date: sd, by };
+        }
+        const akaPart = tailParts.find((p) => /^aka\s*:/i.test(p));
+        const aliases = akaPart
+            ? akaPart
+                .replace(/^aka\s*:/i, "")
+                .split(",")
+                .map((a) => a.trim())
+                .filter(Boolean)
+            : [];
+        const unverified = tailParts.some((p) => /^unverified$/i.test(p));
+        // The `← sources` tail (allow plain "<-" as a fallback for hand edits).
+        const arrowSplit = rest.split(/\s*(?:←|<-)\s*/);
+        const text_ = (arrowSplit[0] ?? "").trim();
+        const sources = arrowSplit.length > 1
+            ? arrowSplit
+                .slice(1)
+                .join(",")
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean)
+            : [];
+        entries.push({
+            id,
+            date,
+            provenance: prov,
+            superseded,
+            aliases,
+            unverified,
+            text: text_,
+            sources,
+            archived,
+            raw: line.trim(),
+        });
+    }
+    return { entries, lineCount: lines.length, malformed };
+}
+export class IndexValidationError extends Error {
+    problems;
+    constructor(problems) {
+        super(`Index rewrite rejected:\n- ${problems.join("\n- ")}`);
+        this.name = "IndexValidationError";
+        this.problems = problems;
+    }
+}
+/**
+ * Validate a proposed index rewrite against the previous version. Returns the
+ * problem list (empty = valid). Rules:
+ * - hard line cap (`INDEX_LINE_HARD_CAP`);
+ * - no duplicate entry ids;
+ * - every previously ACTIVE id must still be present (active or archived) —
+ *   supersede/expire is a MOVE to `## Archive`, never a silent delete;
+ * - previously ARCHIVED ids MAY be dropped: every rewrite snapshots the full
+ *   prior index first, so archived history stays recoverable while the cap
+ *   stays satisfiable (otherwise Archive would grow past the cap forever);
+ * - entry-shaped lines must parse.
+ */
+export function validateIndexRewrite(prev, next) {
+    const problems = [];
+    const parsed = parseIndex(next);
+    if (parsed.lineCount > INDEX_LINE_HARD_CAP) {
+        problems.push(`index is ${parsed.lineCount} lines — the hard cap is ${INDEX_LINE_HARD_CAP} ` +
+            `(target ≤ ${INDEX_LINE_CAP}). Merge or archive entries instead of growing the index.`);
+    }
+    for (const line of parsed.malformed) {
+        problems.push(`malformed entry line (expected \`- [m-<4-8 lowercase letters/digits>] ` +
+            `(<YYYY-MM-DD>, <provenance>) <fact> ← <sources>\`): "${line}"`);
+    }
+    const seen = new Set();
+    for (const e of parsed.entries) {
+        if (seen.has(e.id))
+            problems.push(`duplicate entry id: ${e.id}`);
+        seen.add(e.id);
+    }
+    if (prev) {
+        const prevActive = parseIndex(prev)
+            .entries.filter((e) => !e.archived)
+            .map((e) => e.id);
+        const missing = prevActive.filter((id) => !seen.has(id));
+        if (missing.length > 0) {
+            problems.push(`active entries silently deleted: ${missing.join(", ")} — move superseded/expired ` +
+                `entries under "## Archive" instead of removing them.`);
+        }
+    }
+    return problems;
+}
+/** Mint a new entry id not already taken (6 hex chars, `m-` prefixed). */
+export function mintMemoryId(taken) {
+    for (;;) {
+        const id = `m-${Math.floor(Math.random() * 0xffffff)
+            .toString(16)
+            .padStart(6, "0")}`;
+        if (!taken.has(id))
+            return id;
+    }
+}
+/** All `[m-…]` ids referenced in a blob of text (for usage tracking). */
+export function memoryIdsIn(text) {
+    return Array.from(new Set(Array.from(text.matchAll(/\[(m-[0-9a-z]{4,8})\]/g), (m) => m[1])));
+}
+//# sourceMappingURL=index-file.js.map

package/dist/index-file.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @intentface/latch-memory
+ *
+ * Pluggable agent memory for Latch: an always-loaded compiled index injected
+ * into the system prompt, an episodic store searched on demand, and background
+ * extraction/consolidation over a `MemoryStore` seam (Loredex-backed first).
+ */
+export * from "./types.js";
+export * from "./scope.js";
+export * from "./schema.js";
+export * from "./index-file.js";
+export * from "./extraction-key.js";
+export * from "./search-evidence.js";
+export * from "./sanitize.js";
+export * from "./provider.js";
+export * from "./tools.js";
+export * from "./store/loredex.js";
+export * from "./store/memory.js";
+export * from "./prompts/inject.js";
+export * from "./prompts/extractor.js";
+export * from "./prompts/consolidator.js";
+export * from "./jobs/types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * @intentface/latch-memory
+ *
+ * Pluggable agent memory for Latch: an always-loaded compiled index injected
+ * into the system prompt, an episodic store searched on demand, and background
+ * extraction/consolidation over a `MemoryStore` seam (Loredex-backed first).
+ */
+export * from "./types.js";
+export * from "./scope.js";
+export * from "./schema.js";
+export * from "./index-file.js";
+export * from "./extraction-key.js";
+export * from "./search-evidence.js";
+export * from "./sanitize.js";
+export * from "./provider.js";
+export * from "./tools.js";
+export * from "./store/loredex.js";
+export * from "./store/memory.js";
+export * from "./prompts/inject.js";
+export * from "./prompts/extractor.js";
+export * from "./prompts/consolidator.js";
+export * from "./jobs/types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC"}