@loompad/cli 0.1.0

package/dist/core/brain-index.js

@@ -0,0 +1,338 @@
+/**
+ * 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 { isExpired, lemmatize } from "./brain.js";
+/** BM25 constants. The literature's defaults; we have no corpus to tune on. */
+const K1 = 1.2;
+const B = 0.75;
+/** How much a matched entity can contribute, before IDF weighting. */
+const ENTITY_WEIGHT = 0.5;
+/** Fixed, so scores mean the same thing across queries. */
+const MAX_SCORE = 1 + ENTITY_WEIGHT;
+/**
+ * Constraints and failures outrank facts at equal score. Getting burned by the
+ * same footgun twice is worse than not knowing a detail, so when the ranking is
+ * a coin flip, break it toward the memory that prevents damage.
+ */
+const KIND_BIAS = {
+    constraint: 0.06,
+    failure: 0.06,
+    decision: 0.03,
+    convention: 0.02,
+    fact: 0,
+    task: 0,
+};
+function tokens(text) {
+    return lemmatize(text).split(" ").filter(Boolean);
+}
+/** Entities are matched case-insensitively; everything else is exact. */
+function entKey(s) {
+    return s.trim().toLowerCase();
+}
+/**
+ * The keys one entity is findable under.
+ *
+ * A path gets its basename too, because people say "the backtick thing in
+ * app-page.ts" and mean src/daemon/app-page.ts. Without this the precision
+ * channel only fires when someone types the whole path, which is exactly when
+ * they least need help finding it.
+ *
+ * The basename is a separate key with its own posting list, so its IDF weight
+ * is computed on its own merits: if four files are named index.ts, "index.ts"
+ * suppresses itself and the full paths stay sharp.
+ */
+function entAliases(e) {
+    const k = entKey(e);
+    if (!k)
+        return [];
+    if (!k.includes("/"))
+        return [k];
+    const base = k.split("/").pop();
+    return base && base !== k ? [k, base] : [k];
+}
+/**
+ * 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 class MemoryIndex {
+    /** term → memory id → term frequency */
+    postings = new Map();
+    /** entity (lowercased) → memory ids */
+    entities = new Map();
+    lengths = new Map();
+    avgLen = 0;
+    docs = [];
+    constructor(memories) {
+        let total = 0;
+        for (const m of memories) {
+            this.docs.push(m);
+            const toks = m.lemmas ? m.lemmas.split(" ").filter(Boolean) : tokens(m.text);
+            this.lengths.set(m.id, toks.length);
+            total += toks.length;
+            for (const t of toks) {
+                let p = this.postings.get(t);
+                if (!p)
+                    this.postings.set(t, (p = new Map()));
+                p.set(m.id, (p.get(m.id) ?? 0) + 1);
+            }
+            for (const e of m.entities) {
+                for (const k of entAliases(e)) {
+                    let s = this.entities.get(k);
+                    if (!s)
+                        this.entities.set(k, (s = new Set()));
+                    s.add(m.id);
+                }
+            }
+        }
+        this.avgLen = memories.length ? total / memories.length : 0;
+        this.byId = new Map(memories.map((m) => [m.id, m]));
+    }
+    byId;
+    get size() {
+        return this.docs.length;
+    }
+    /** Standard BM25. Returns id → score for every doc matching any term. */
+    bm25(query) {
+        const scores = new Map();
+        const N = this.docs.length;
+        if (!N)
+            return scores;
+        for (const term of new Set(tokens(query))) {
+            const posting = this.postings.get(term);
+            if (!posting)
+                continue;
+            const df = posting.size;
+            // +0.5/+1 smoothing keeps idf positive for a term in every document,
+            // which would otherwise go negative and *penalise* a match.
+            const idf = Math.log(1 + (N - df + 0.5) / (df + 0.5));
+            for (const [id, tf] of posting) {
+                const len = this.lengths.get(id) ?? 0;
+                const norm = this.avgLen > 0 ? 1 - B + B * (len / this.avgLen) : 1;
+                const score = idf * ((tf * (K1 + 1)) / (tf + K1 * norm));
+                scores.set(id, (scores.get(id) ?? 0) + score);
+            }
+        }
+        return scores;
+    }
+    /**
+     * 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) {
+        const out = new Map();
+        for (const term of new Set(terms.map(entKey).filter(Boolean))) {
+            const ids = this.entities.get(term);
+            if (!ids)
+                continue;
+            const n = ids.size;
+            const weight = 1 / (1 + 0.001 * (n - 1) ** 2);
+            const score = ENTITY_WEIGHT * weight;
+            for (const id of ids) {
+                const cur = out.get(id);
+                if (!cur)
+                    out.set(id, { score, matched: [term] });
+                else {
+                    cur.matched.push(term);
+                    cur.score = Math.max(cur.score, score);
+                }
+            }
+        }
+        return out;
+    }
+    memory(id) {
+        return this.byId.get(id);
+    }
+}
+/**
+ * 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 function queryEntities(query, files = []) {
+    const out = new Set(files.map((f) => f.trim()).filter(Boolean));
+    for (const m of query.matchAll(/\b[\w@.-]+(?:\/[\w@.-]+)+\b/g))
+        out.add(m[0]);
+    for (const m of query.matchAll(/\b[\w-]+\.(?:ts|tsx|js|jsx|json|md|py|rs|go|sh|yml|yaml|toml)\b/g))
+        out.add(m[0]);
+    for (const m of query.matchAll(/\b[A-Za-z][a-z0-9]+(?:[A-Z][a-z0-9]+)+\b/g))
+        out.add(m[0]);
+    for (const m of query.matchAll(/\b[A-Z][A-Z0-9]{2,}(?:_[A-Z0-9]+)*\b/g))
+        out.add(m[0]);
+    for (const m of query.matchAll(/#\d+\b/g))
+        out.add(m[0]);
+    for (const m of query.matchAll(/`([^`\n]{2,60})`/g))
+        if (m[1])
+            out.add(m[1]);
+    // A file's basename is worth trying too: "git.ts" should find memories about
+    // src/core/git.ts even when the query never spells the path out.
+    for (const f of files) {
+        const base = f.split("/").pop();
+        if (base && base !== f)
+            out.add(base);
+    }
+    return [...out];
+}
+/**
+ * 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 function retrieveFrom(memories, opts) {
+    const now = Date.now();
+    const limit = opts.limit ?? 12;
+    // Filter FIRST — scope, confidence, expiry — so dead and out-of-scope rows
+    // never consume the ranking budget. mem0 does this after its over-fetch and
+    // silently loses recall to rows that were never eligible.
+    const live = memories.filter((m) => {
+        if (isExpired(m, now))
+            return false;
+        if (opts.minConfidence !== undefined && m.confidence < opts.minConfidence)
+            return false;
+        if (opts.agent && m.scope.agent && m.scope.agent !== opts.agent)
+            return false;
+        if (opts.chat && m.scope.chat && m.scope.chat !== opts.chat)
+            return false;
+        return true;
+    });
+    if (!live.length)
+        return [];
+    const index = new MemoryIndex(live);
+    const query = opts.query ?? "";
+    const ents = queryEntities(query, opts.files ?? []);
+    const bm = query.trim() ? index.bm25(query) : new Map();
+    const eh = ents.length ? index.entityHits(ents) : new Map();
+    // The union. Either channel alone is enough to be a candidate.
+    const ids = new Set([...bm.keys(), ...eh.keys()]);
+    if (!ids.size)
+        return [];
+    // BM25 is unbounded, so normalise against the best hit in this query to get
+    // it onto the same 0..1 footing as the entity channel. Relative-to-best is
+    // honest here in a way mem0's adaptive divisor isn't: it rescales the axis,
+    // it doesn't change what the total can mean.
+    let maxBm = 0;
+    for (const s of bm.values())
+        if (s > maxBm)
+            maxBm = s;
+    const hits = [];
+    for (const id of ids) {
+        const memory = index.memory(id);
+        if (!memory)
+            continue;
+        const bmNorm = maxBm > 0 ? (bm.get(id) ?? 0) / maxBm : 0;
+        const ent = eh.get(id);
+        const bias = KIND_BIAS[memory.kind] ?? 0;
+        const raw = bmNorm + (ent?.score ?? 0);
+        const final = Math.min(1, raw / MAX_SCORE + bias);
+        hits.push({
+            memory,
+            score: final,
+            ...(opts.explain
+                ? {
+                    detail: {
+                        bm25: round(bmNorm),
+                        entity: round(ent?.score ?? 0),
+                        kindBias: bias,
+                        matchedEntities: ent?.matched ?? [],
+                        final: round(final),
+                    },
+                }
+                : {}),
+        });
+    }
+    hits.sort((a, b) => b.score - a.score || b.memory.updatedAt - a.memory.updatedAt);
+    return hits.slice(0, limit);
+}
+function round(n) {
+    return Math.round(n * 1000) / 1000;
+}
+/** The same, against a live Brain. */
+export function retrieve(brain, opts) {
+    return retrieveFrom(brain.all(), opts);
+}
+const KIND_LABEL = {
+    constraint: "Constraints reality imposes",
+    failure: "Known failures — do not repeat these",
+    decision: "Decisions and why",
+    convention: "How this project does things",
+    fact: "Facts about the project",
+    task: "Task notes",
+};
+/**
+ * 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 function compileBrief(memories) {
+    if (!memories.length)
+        return "";
+    const order = ["constraint", "failure", "decision", "convention", "fact", "task"];
+    const byKind = new Map();
+    for (const m of memories) {
+        const arr = byKind.get(m.kind);
+        if (arr)
+            arr.push(m);
+        else
+            byKind.set(m.kind, [m]);
+    }
+    const lines = ["## What this project has learned (relevant to the work at hand)"];
+    for (const kind of order) {
+        const ms = byKind.get(kind);
+        if (!ms?.length)
+            continue;
+        lines.push("", `### ${KIND_LABEL[kind]}`);
+        for (const m of ms)
+            lines.push(`- ${m.text}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=brain-index.js.map

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

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

package/dist/core/brain.d.ts

@@ -0,0 +1,214 @@
+/**
+ * The brain — memory as units instead of a sliding window.
+ *
+ * What was here before (and still is, next door in memory.ts) concatenates:
+ * every ADE's CLAUDE.md, truncated at 8k, plus the last 40 decisions, plus the
+ * last 30 messages, glued together and handed to whoever takes the baton. That
+ * is a recency window, not a memory. Nothing is learned from a turn, nothing is
+ * reconciled when two facts disagree, nothing is retrieved because it's
+ * relevant, and nothing is ever forgotten — growth is bounded by truncation,
+ * which throws away the durable architectural facts first and keeps the last
+ * thirty lines of chatter.
+ *
+ * This module is the other thing: addressable units that can be added, updated,
+ * forgotten, and looked up by what they're about.
+ *
+ * There is no new store. A memory IS three event kinds in the log that already
+ * exists — memory_add / memory_update / memory_forget. Current state is a fold
+ * over them; history is a filter over the same bytes; and the two cannot drift
+ * apart, because they are the same bytes. mem0 needs a second SQLite database
+ * to get the history that falls out of this for free. types.ts has said from
+ * the beginning that the log is the source of truth and everything else is a
+ * projection of it — this is that, taken literally.
+ *
+ * Phase 0 (this file) and phase 1 (retrieval, brain-index.ts) are deterministic
+ * and LLM-free by design: prove the store and the recall before spending a
+ * token on extraction. See docs/proposals/brain.md.
+ */
+import type { EventLog } from "./eventlog.js";
+import type { LoomEvent } from "../types.js";
+/**
+ * The taxonomy is where this has to diverge hardest from mem0, whose categories
+ * are personal — preferences, relationships, health. These are engineering.
+ *
+ * `failure` is the one nobody builds and the one that pays for the rest.
+ * Negative knowledge is the most expensive kind to re-derive and the least
+ * likely to get written down: every hour lost to "we already tried that" is a
+ * failure memory that didn't exist. This repo's own history is full of them.
+ */
+export type MemoryKind = "constraint" | "decision" | "convention" | "fact" | "failure" | "task";
+export declare const MEMORY_KINDS: MemoryKind[];
+/** Injected memories are load-bearing, so they have to clear a bar. */
+export declare const CONFIDENCE_FLOOR = 0.6;
+export interface MemoryProvenance {
+    /** Who learned it. "user" when a human typed it. */
+    agentId: string;
+    /** The event it came from — one click back to the turn that produced it. */
+    eventId: number;
+    ts: number;
+}
+export interface Memory {
+    id: string;
+    kind: MemoryKind;
+    /** One self-contained sentence. Must read true with no surrounding context. */
+    text: string;
+    /**
+     * Literal strings this is about: file paths, symbols, agent ids, error codes.
+     * mem0 has to run spaCy NER over prose and then fuzzy-match embeddings at 0.95
+     * to decide two restaurant names are the same place. Ours are exact strings
+     * that appear verbatim in the repo, so an index is a Map and a lookup is a
+     * `get`. That is the whole reason lexical retrieval is enough here.
+     */
+    entities: string[];
+    scope: {
+        chat?: string;
+        agent?: string;
+        task?: string;
+    };
+    provenance: MemoryProvenance;
+    /** Below CONFIDENCE_FLOOR: visible in the Brain tab, never injected. */
+    confidence: number;
+    /**
+     * The verbatim span this was extracted from. Phase 2 verifies it appears in
+     * the source turn and drops the memory if it doesn't — the cheapest
+     * hallucination guard there is, and it costs one `includes`.
+     */
+    evidence?: string;
+    /** Lemmatised copy for BM25. Never shown to anyone. */
+    lemmas: string;
+    /** md5(text) — lets us skip an LLM call for something we already know. */
+    hash: string;
+    createdAt: number;
+    updatedAt: number;
+    /** `task` memories die with their run; constraints and failures never do. */
+    expiresAt?: number;
+}
+/** What a caller hands us. The derived fields are ours to compute. */
+export interface NewMemory {
+    kind: MemoryKind;
+    text: string;
+    entities?: string[];
+    scope?: {
+        chat?: string;
+        agent?: string;
+        task?: string;
+    };
+    provenance: MemoryProvenance;
+    confidence?: number;
+    evidence?: string;
+    expiresAt?: number;
+}
+export interface MemoryPatch {
+    text?: string;
+    kind?: MemoryKind;
+    entities?: string[];
+    confidence?: number;
+    evidence?: string;
+    expiresAt?: number;
+}
+/** One line of a memory's life, straight out of the log. */
+export interface MemoryHistoryEntry {
+    op: "add" | "update" | "forget";
+    eventId: number;
+    ts: number;
+    by: string;
+    text?: string;
+    reason?: string;
+}
+export interface ListOpts {
+    kind?: MemoryKind;
+    chat?: string;
+    agent?: string;
+    /** Include expired memories. Off by default — they're dead to retrieval. */
+    includeExpired?: boolean;
+    minConfidence?: number;
+    limit?: number;
+}
+export declare function memoryHash(text: string): string;
+export declare function newMemoryId(): string;
+/**
+ * Poor man's lemmatiser. mem0 runs spaCy for this; we are not shipping a 500MB
+ * model to stem a hundred sentences, and for identifier-heavy text the crude
+ * rules do nearly as well.
+ *
+ * Deliberately keeps the raw token alongside the stem when they differ, which
+ * is the same trick mem0 plays for -ing forms (`lemmatization.py:47`): "running"
+ * should match both a query for "run" and a query for "running", and we can't
+ * tell which the user meant. Keeping both costs one token in the index.
+ */
+export declare function lemmatize(text: string): string;
+/**
+ * Entities we can find without a model, because in a codebase they're literal.
+ *
+ * Paths, dotted/slashed identifiers, CamelCase symbols, SCREAMING_CASE error
+ * codes, #123 issue refs. Deliberately conservative: a wrong entity is worse
+ * than a missing one, because entities are the high-precision retrieval channel
+ * and polluting them poisons it.
+ */
+export declare function extractEntities(text: string): string[];
+/**
+ * Rebuild current state from the log.
+ *
+ * Order matters and is the log's, not ours: an update to a forgotten memory is
+ * a no-op, and a memory added twice keeps the first id. Both fall out of
+ * replaying in id order, which is why this reads the log rather than keeping a
+ * parallel Map that could disagree with it.
+ */
+export declare function foldMemories(events: LoomEvent[]): Map<string, Memory>;
+export declare function isExpired(m: Memory, now?: number): boolean;
+/**
+ * A project's memory. Reads and writes through the event log; holds a folded
+ * cache so `list`/`retrieve` don't replay history on every call, and keeps the
+ * cache honest by subscribing to the log rather than by trusting its own writes.
+ */
+export declare class Brain {
+    private log;
+    private cache;
+    private unsubscribe;
+    constructor(log: EventLog);
+    close(): void;
+    private state;
+    /** Every live memory, newest first. */
+    all(): Memory[];
+    get(id: string): Memory | undefined;
+    /** Is this already known? Cheap enough to call before spending an LLM turn. */
+    findByHash(hash: string): Memory | undefined;
+    list(opts?: ListOpts): Memory[];
+    /**
+     * Learn something.
+     *
+     * Deduplicates on hash before writing: the same fact arriving twice is not
+     * two memories. Returns the existing one when that happens, so a caller can
+     * tell "already knew that" from "learned that" — which is exactly the signal
+     * phase 2 needs to skip an extraction call.
+     */
+    add(input: NewMemory): {
+        memory: Memory;
+        created: boolean;
+    };
+    /** Correct something we already believe. */
+    update(id: string, patch: MemoryPatch, by: string): Memory;
+    /**
+     * Forget something.
+     *
+     * The memory leaves the fold; the log keeps every byte. That asymmetry is the
+     * point — "why did it ever think that" stays answerable after the answer is
+     * "it doesn't any more". A reason is required, because a tombstone with no
+     * reason is how you end up re-learning the same wrong thing next week.
+     */
+    forget(id: string, reason: string, by: string): boolean;
+    /**
+     * Everything that ever happened to one memory, including its death.
+     *
+     * This is a filter over the same events the fold reads. mem0 keeps a whole
+     * second SQLite database for it (`storage.py`), and pays for the two to
+     * disagree — its batch path drops actor_id and role that its single path
+     * records.
+     */
+    history(id: string): MemoryHistoryEntry[];
+    stats(): {
+        total: number;
+        byKind: Record<string, number>;
+        expired: number;
+    };
+}