@loompad/cli 0.1.0

package/dist/core/brain-extract.js

@@ -0,0 +1,248 @@
+/**
+ * Phase 2 — learning from a turn.
+ *
+ * Phases 0 and 1 gave the brain units and retrieval, both deterministic. This is
+ * where memories start arriving on their own: when an agent finishes a turn, an
+ * ADE reads the transcript and proposes what to remember, reconciled against
+ * what's already known.
+ *
+ * The shape is mem0's, adapted (see docs/proposals/brain.md):
+ *   - retrieve the candidates a new fact might collide with (phase 1);
+ *   - show them to the extractor INTEGER-MAPPED, never by real id — a
+ *     hallucinated "7" is detectable and droppable; a hallucinated uuid is
+ *     silent corruption (mem0 main.py:889);
+ *   - the extractor returns ADD / UPDATE / FORGET / NONE;
+ *   - every ADD/UPDATE must quote the span it came from, and that span is
+ *     verified IN CODE to appear in the turn — the cheapest hallucination guard
+ *     there is, and the one mem0 doesn't have.
+ *
+ * The LLM is injected as an `engine` (a prompt → text function), so all of the
+ * logic here — mapping, parsing, evidence-checking, applying — is pure and
+ * tested without a model. The default engine is the logged-in Claude CLI, the
+ * same no-API-key path distill.ts already uses.
+ */
+import { MEMORY_KINDS } from "./brain.js";
+import { retrieveFrom } from "./brain-index.js";
+const MEMORY_KIND_SET = new Set(MEMORY_KINDS);
+/** Whitespace-insensitive containment — the extractor may reflow what it quotes. */
+function normalizeForMatch(s) {
+    return s.replace(/\s+/g, " ").trim().toLowerCase();
+}
+/**
+ * Does the quoted span actually appear in the turn?
+ *
+ * The whole anti-hallucination guarantee rests on this one check. Whitespace is
+ * normalised (the model reflows), but the words have to be there. A short quote
+ * is too easy to satisfy by accident, so anything under a few characters is
+ * rejected outright.
+ */
+export function evidenceInTurn(evidence, turn) {
+    const e = normalizeForMatch(evidence);
+    if (e.length < 8)
+        return false;
+    return normalizeForMatch(turn).includes(e);
+}
+// ---------------------------------------------------------------------------
+// The prompt
+// ---------------------------------------------------------------------------
+export const EXTRACT_SYSTEM = `You extract durable engineering memory from one agent turn in a software project.
+
+Return ONLY facts that will still matter next week: constraints reality imposes, decisions and why, conventions this repo follows, plain facts about how things are, and — most valuable — failures (what was tried and did not work, so nobody burns the time again). Skip chit-chat, restated instructions, and anything true only for this minute.
+
+You are given EXISTING memories, each under an integer id. Use them ONLY to avoid duplicates and to correct what's now wrong:
+- ADD a new memory when the turn reveals something not already known.
+- UPDATE an existing memory (by its integer id) when the turn shows it was incomplete or has changed. Keep the id.
+- FORGET an existing memory (by its integer id) when the turn shows it is now false.
+- Otherwise NONE.
+
+Rules, strictly:
+- Every ADD and UPDATE MUST include "evidence": a short verbatim quote FROM THE TURN that the memory is based on. If you can't quote it from the turn, don't write it.
+- Each memory is ONE self-contained sentence that reads true with no surrounding context.
+- Use ONLY the integer ids shown for UPDATE/FORGET. Never invent an id.
+- kind is one of: constraint, decision, convention, fact, failure.
+
+Respond with JSON only, no prose:
+{"ops":[{"op":"ADD","text":"...","kind":"failure","evidence":"...","confidence":0.9},{"op":"UPDATE","id":"2","text":"...","evidence":"..."},{"op":"FORGET","id":"5","reason":"..."},{"op":"NONE"}]}`;
+export function buildExtractionPrompt(turn, candidates) {
+    const existing = candidates.length
+        ? candidates
+            .map((c) => `  ${JSON.stringify(c.intId)}: ${JSON.stringify(c.memory.text)}`)
+            .join("\n")
+        : "  (none)";
+    return [
+        "EXISTING memories (integer id: text):",
+        existing,
+        "",
+        "THE TURN (an agent's work — the user's ask and the agent's actions/reply):",
+        turn.length > 12_000 ? turn.slice(0, 12_000) + "\n…(truncated)" : turn,
+        "",
+        "Extract memory as JSON per the system instructions.",
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Parsing the engine's reply
+// ---------------------------------------------------------------------------
+function stripFences(s) {
+    return s.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "").trim();
+}
+/** Pull the ops array out of the engine's reply, tolerantly. */
+export function parseExtraction(response) {
+    const text = stripFences(response || "").trim();
+    if (!text)
+        return [];
+    let obj;
+    try {
+        obj = JSON.parse(text);
+    }
+    catch {
+        // The model wrapped the JSON in prose — grab the first {...} block.
+        const m = text.match(/\{[\s\S]*\}/);
+        if (!m)
+            return [];
+        try {
+            obj = JSON.parse(m[0]);
+        }
+        catch {
+            return [];
+        }
+    }
+    const rawOps = Array.isArray(obj)
+        ? obj
+        : Array.isArray(obj?.ops)
+            ? obj.ops
+            : [];
+    const ops = [];
+    for (const raw of rawOps) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const r = raw;
+        const op = String(r.op ?? "").toUpperCase();
+        if (op === "ADD" && typeof r.text === "string" && typeof r.evidence === "string") {
+            const kind = String(r.kind ?? "fact");
+            ops.push({
+                op: "ADD",
+                text: r.text,
+                kind: (MEMORY_KIND_SET.has(kind) ? kind : "fact"),
+                ...(Array.isArray(r.entities) ? { entities: r.entities.map(String) } : {}),
+                ...(typeof r.confidence === "number" ? { confidence: r.confidence } : {}),
+                evidence: r.evidence,
+            });
+        }
+        else if (op === "UPDATE" && r.id != null && typeof r.text === "string" && typeof r.evidence === "string") {
+            ops.push({
+                op: "UPDATE",
+                id: String(r.id),
+                text: r.text,
+                ...(typeof r.confidence === "number" ? { confidence: r.confidence } : {}),
+                evidence: r.evidence,
+            });
+        }
+        else if (op === "FORGET" && r.id != null) {
+            ops.push({ op: "FORGET", id: String(r.id), reason: String(r.reason ?? "the turn showed it is no longer true") });
+        }
+        // NONE and anything malformed are simply ignored.
+    }
+    return ops;
+}
+/**
+ * Apply the extractor's ops to the brain, dropping anything that fails a guard.
+ *
+ * The guards, in order: an ADD/UPDATE with no verifiable evidence span is a
+ * hallucination and is dropped; an UPDATE/FORGET whose integer id isn't in the
+ * candidate set is a hallucinated reference and is dropped; a real id maps back
+ * to its uuid before touching the store.
+ */
+export function applyExtraction(brain, ops, turn, candidates, opts) {
+    const byInt = new Map(candidates.map((c) => [c.intId, c.memory]));
+    const res = { added: [], updated: [], forgotten: [], dropped: [] };
+    const prov = { agentId: opts.by, eventId: opts.eventId, ts: Date.now() };
+    for (const op of ops) {
+        if (op.op === "ADD") {
+            if (!evidenceInTurn(op.evidence, turn)) {
+                res.dropped.push({ op, reason: "evidence not found in the turn" });
+                continue;
+            }
+            const { memory, created } = brain.add({
+                kind: op.kind,
+                text: op.text,
+                ...(op.entities ? { entities: op.entities } : {}),
+                ...(op.confidence !== undefined ? { confidence: op.confidence } : {}),
+                evidence: op.evidence,
+                ...(opts.chat ? { scope: { chat: opts.chat } } : {}),
+                provenance: prov,
+            });
+            if (created)
+                res.added.push(memory);
+            else
+                res.dropped.push({ op, reason: "already known (hash match)" });
+        }
+        else if (op.op === "UPDATE") {
+            const target = byInt.get(op.id);
+            if (!target) {
+                res.dropped.push({ op, reason: `no candidate with id ${op.id}` });
+                continue;
+            }
+            if (!evidenceInTurn(op.evidence, turn)) {
+                res.dropped.push({ op, reason: "evidence not found in the turn" });
+                continue;
+            }
+            try {
+                const updated = brain.update(target.id, { text: op.text, ...(op.confidence !== undefined ? { confidence: op.confidence } : {}), evidence: op.evidence }, opts.by);
+                res.updated.push(updated);
+            }
+            catch (err) {
+                res.dropped.push({ op, reason: err instanceof Error ? err.message : String(err) });
+            }
+        }
+        else if (op.op === "FORGET") {
+            const target = byInt.get(op.id);
+            if (!target) {
+                res.dropped.push({ op, reason: `no candidate with id ${op.id}` });
+                continue;
+            }
+            if (brain.forget(target.id, op.reason, opts.by))
+                res.forgotten.push(target.id);
+        }
+    }
+    return res;
+}
+/**
+ * Learn from one turn: retrieve candidates, ask the engine, apply the ops.
+ *
+ * Non-throwing by contract — a broken or slow extractor must never be able to
+ * take down the turn that triggered it (the same rule distill.ts follows). Any
+ * failure returns an empty result.
+ */
+export async function extractFromTurn(brain, turn, opts) {
+    const empty = { added: [], updated: [], forgotten: [], dropped: [] };
+    if (!turn.trim())
+        return empty;
+    // Candidates: what a new fact from this turn might collide with. Query is the
+    // turn itself plus the files it touched — exactly what phase 1 ranks on.
+    const hits = retrieveFrom(brain.all(), {
+        query: turn.slice(0, 4000),
+        ...(opts.files?.length ? { files: opts.files } : {}),
+        ...(opts.chat ? { chat: opts.chat } : {}),
+        limit: opts.candidateLimit ?? 10,
+    });
+    const candidates = hits.map((h, i) => ({ intId: String(i), memory: h.memory }));
+    let reply;
+    try {
+        reply = await opts.engine({
+            system: EXTRACT_SYSTEM,
+            user: buildExtractionPrompt(turn, candidates),
+        });
+    }
+    catch {
+        return empty; // extractor unavailable — the turn is unaffected
+    }
+    const ops = parseExtraction(reply);
+    if (!ops.length)
+        return empty;
+    return applyExtraction(brain, ops, turn, candidates, {
+        by: opts.agentId,
+        eventId: opts.eventId ?? 0,
+        ...(opts.chat ? { chat: opts.chat } : {}),
+    });
+}
+//# sourceMappingURL=brain-extract.js.map

package/dist/core/brain-extract.js.map

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

package/dist/core/brain-index.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Retrieval — finding the memories a turn is actually about.
+ *
+ * Two channels, unioned:
+ *
+ *   entities — exact matches on the literal strings a codebase is made of:
+ *              src/core/git.ts, AgentBase, EADDRINUSE, #42. High precision,
+ *              zero cost, and available because our domain's entities are
+ *              strings that appear verbatim rather than noun phrases someone
+ *              has to infer.
+ *   BM25     — ordinary lexical scoring over the lemmatised text, for the
+ *              memories nobody thought to tag.
+ *
+ * The union is the whole point, and it's where this consciously parts company
+ * with the reference. mem0 builds its candidate set from the dense results only
+ * (`main.py:1622`) and then lets BM25 and entity boosts re-rank *within* it —
+ * so a memory BM25 matches perfectly but vector search missed is unreachable at
+ * any score. That isn't hybrid retrieval, it's dense recall wearing a hybrid
+ * costume. With no dense channel at all, our recall IS entities ∪ BM25; if
+ * either finds something, it's a candidate.
+ *
+ * Two more things worth taking from mem0, and two worth refusing:
+ *
+ *   take:   memory_count_weight (`main.py:1758`) — an inverse-quadratic IDF
+ *           surrogate. An entity linked to one memory weighs 1.0; to a hundred,
+ *           0.09. Common entities suppress themselves. Ten lines, no corpus
+ *           statistics, no tuning.
+ *   take:   over-fetch before the cut, so scoring has room to reorder.
+ *   refuse: its query-dependent divisor (`scoring.py:97`), which makes a score
+ *           mean different things in different queries — a memory scoring 0.9 on
+ *           semantics alone drops to 0.45 the moment some *other* memory in the
+ *           same query happens to match a keyword. Ours is fixed.
+ *   refuse: filtering expiry after the top-k cut (`main.py:1626`), where dead
+ *           rows silently eat the recall budget. Ours are gone before we rank.
+ */
+import type { Brain, Memory } from "./brain.js";
+export interface RetrieveOpts {
+    /** Free text — a task description, a prompt, a turn. */
+    query?: string;
+    /** Files in play. From turn_diff, the file tree, or whatever the task names. */
+    files?: string[];
+    /** Only memories scoped to this agent (or to nobody). */
+    agent?: string;
+    /** Only memories scoped to this chat (or to nobody). */
+    chat?: string;
+    limit?: number;
+    /** Drop anything the extractor wasn't sure about. */
+    minConfidence?: number;
+    /** Show the arithmetic. For tests and for the Brain tab. */
+    explain?: boolean;
+}
+export interface ScoreDetail {
+    bm25: number;
+    entity: number;
+    kindBias: number;
+    matchedEntities: string[];
+    final: number;
+}
+export interface Hit {
+    memory: Memory;
+    score: number;
+    detail?: ScoreDetail;
+}
+/**
+ * An inverted index over a set of memories.
+ *
+ * Rebuilt from the fold rather than maintained incrementally. At project scale —
+ * hundreds to low thousands of memories — building it is well under a
+ * millisecond, and an index that can't drift from its source is worth more than
+ * one that's marginally faster to update. If that stops being true the shape
+ * here doesn't change; only when we rebuild does.
+ */
+export declare class MemoryIndex {
+    /** term → memory id → term frequency */
+    private postings;
+    /** entity (lowercased) → memory ids */
+    private entities;
+    private lengths;
+    private avgLen;
+    private docs;
+    constructor(memories: Memory[]);
+    private byId;
+    get size(): number;
+    /** Standard BM25. Returns id → score for every doc matching any term. */
+    bm25(query: string): Map<string, number>;
+    /**
+     * Entity postings, IDF-weighted the way mem0 does it (`main.py:1758`): an
+     * entity linked to n memories contributes 1/(1+0.001·(n-1)²). One memory →
+     * full weight; a hundred → nearly nothing. So `src/types.ts`, which half the
+     * memories will mention, stops drowning out the one that matters, without
+     * anyone maintaining a stoplist.
+     *
+     * Per-memory contributions take the max rather than the sum — matching two
+     * entities shouldn't outrank matching one that's far more specific.
+     */
+    entityHits(terms: string[]): Map<string, {
+        score: number;
+        matched: string[];
+    }>;
+    memory(id: string): Memory | undefined;
+}
+/**
+ * Pull the entity-ish strings out of a query.
+ *
+ * Looser than brain.ts's extractEntities, and deliberately so: that one guards
+ * what gets *stored*, where a wrong entity poisons the index forever. This one
+ * only guards what gets *looked up*, where a wrong guess costs one failed Map
+ * lookup. Asymmetric stakes, asymmetric strictness.
+ */
+export declare function queryEntities(query: string, files?: string[]): string[];
+/**
+ * Find the memories relevant to a piece of work.
+ *
+ * Pure over the memories handed in — the Brain owns the fold, this owns the
+ * ranking, and neither needs the other to be a class.
+ */
+export declare function retrieveFrom(memories: Memory[], opts: RetrieveOpts): Hit[];
+/** The same, against a live Brain. */
+export declare function retrieve(brain: Brain, opts: RetrieveOpts): Hit[];
+/**
+ * Render retrieved memories into a brief for an agent taking the baton.
+ *
+ * Grouped by kind with constraints and failures first, because those are the
+ * ones that prevent damage — the reader should hit "don't do X, it breaks Y"
+ * before "the port is 7420". Returns "" for no memories, so a caller can append
+ * it unconditionally.
+ */
+export declare function compileBrief(memories: Memory[]): string;