@mneme-ai/mcp 1.2.0 → 1.4.0

package/dist/tools/_grader_tool.js

@@ -0,0 +1,80 @@
+/**
+ * mneme.grade.answer — the universal grader tool.
+ *
+ * The AI student calls this AFTER drafting an answer to a user query.
+ * The grader runs all 5 Super Sonic algorithms against the draft and
+ * returns PASS / WARN / FAIL with concrete rewrite hints.
+ *
+ * Loop: AI drafts → calls this → on FAIL, AI rewrites → calls this
+ * again with retryCount++. Until PASS or maxRetries.
+ */
+import { gradeDraft } from "./_grader_engine.js";
+import { homeworkForCategory } from "./_homework.js";
+export const graderTool = {
+    name: "mneme.grade.answer",
+    category: "meta",
+    description: "Grade an AI draft against the homework rubric set by the originating Mneme tool. " +
+        "Returns PASS / WARN / FAIL + rewrite hints + per-algorithm verdicts. " +
+        "AI student MUST call this after drafting a user-facing answer; on FAIL, AI MUST rewrite using the " +
+        "rewriteHints and call grade.answer again with retryCount++. Stop when PASS or maxRetries reached. " +
+        "This is the teacher-student loop — Mneme grades the AI's homework before the user ever sees it.",
+    triggers: [
+        "grade my draft answer",
+        "is this answer good enough?",
+        "check rubric on draft",
+    ],
+    inputSchema: {
+        type: "object",
+        properties: {
+            originalQuery: {
+                type: "string",
+                description: "The user's original question/request",
+            },
+            aiDraft: {
+                type: "string",
+                description: "The AI's draft answer to grade",
+            },
+            sourceCategory: {
+                type: "string",
+                description: "Which Mneme category produced the data the draft was built from " +
+                    "(memory | people | audit | forensics | insights | quality | quant | lab | meta). " +
+                    "Used to pick the right rubric.",
+            },
+            retryCount: {
+                type: "number",
+                description: "Which attempt this is (0 for first draft, 1 for first rewrite, …).",
+            },
+        },
+        required: ["originalQuery", "aiDraft", "sourceCategory"],
+    },
+    handler: async (rt, args) => {
+        const originalQuery = String(args["originalQuery"] ?? "");
+        const aiDraft = String(args["aiDraft"] ?? "");
+        const sourceCategory = String(args["sourceCategory"] ?? "memory");
+        const retryCount = typeof args["retryCount"] === "number" ? args["retryCount"] : 0;
+        const homework = homeworkForCategory(sourceCategory);
+        const result = await gradeDraft({
+            cwd: rt.meta.rootPath,
+            originalQuery,
+            aiDraft,
+            homework,
+            retryCount,
+        });
+        return {
+            data: result,
+            wisdom: result.verdict === "PASS"
+                ? `Draft scores ${result.score}/100 — ready to deliver.`
+                : result.verdict === "WARN"
+                    ? `Draft scores ${result.score}/100 — close, but flagged by ${result.algorithmResults.filter((a) => a.verdict === "WARN").length} algorithm(s). Consider one polish pass.`
+                    : `Draft scores ${result.score}/100 — FAIL. Rewrite using the rewriteHints, then call mneme.grade.answer again with retryCount=${retryCount + 1}.`,
+            followUp: result.verdict === "PASS" ? [] : ["mneme.grade.answer"],
+            confidence: { level: "high" },
+            secondBrain: {
+                presentation: result.verdict === "PASS"
+                    ? "Deliver the draft to the user. Do NOT call other tools unless the user asks a follow-up."
+                    : "Apply each rewriteHint to the draft. Then call mneme.grade.answer again with the new draft and retryCount incremented. STOP when verdict is PASS or giveUp is true.",
+            },
+        };
+    },
+};
+//# sourceMappingURL=_grader_tool.js.map

package/dist/tools/_grader_tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_grader_tool.js","sourceRoot":"","sources":["../../src/tools/_grader_tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGrD,MAAM,CAAC,MAAM,UAAU,GAAc;IACnC,IAAI,EAAE,oBAAoB;IAC1B,QAAQ,EAAE,MAAM;IAChB,WAAW,EACT,mFAAmF;QACnF,uEAAuE;QACvE,oGAAoG;QACpG,oGAAoG;QACpG,iGAAiG;IACnG,QAAQ,EAAE;QACR,uBAAuB;QACvB,6BAA6B;QAC7B,uBAAuB;KACxB;IACD,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,aAAa,EAAE;gBACb,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,sCAAsC;aACpD;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,gCAAgC;aAC9C;YACD,cAAc,EAAE;gBACd,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,kEAAkE;oBAClE,mFAAmF;oBACnF,gCAAgC;aACnC;YACD,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,oEAAoE;aAClF;SACF;QACD,QAAQ,EAAE,CAAC,eAAe,EAAE,SAAS,EAAE,gBAAgB,CAAC;KACzD;IACD,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE;QAC1B,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1D,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9C,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,QAAQ,CAAiB,CAAC;QAClF,MAAM,UAAU,GAAG,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,IAAI,CAAC,YAAY,CAAY,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/F,MAAM,QAAQ,GAAG,mBAAmB,CAAC,cAAc,CAAC,CAAC;QACrD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC;YAC9B,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ;YACrB,aAAa;YACb,OAAO;YACP,QAAQ;YACR,UAAU;SACX,CAAC,CAAC;QACH,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,MAAM,EACJ,MAAM,CAAC,OAAO,KAAK,MAAM;gBACvB,CAAC,CAAC,gBAAgB,MAAM,CAAC,KAAK,0BAA0B;gBACxD,CAAC,CAAC,MAAM,CAAC,OAAO,KAAK,MAAM;oBAC3B,CAAC,CAAC,gBAAgB,MAAM,CAAC,KAAK,gCAAgC,MAAM,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,MAAM,0CAA0C;oBAC1K,CAAC,CAAC,gBAAgB,MAAM,CAAC,KAAK,mGAAmG,UAAU,GAAG,CAAC,GAAG;YACtJ,QAAQ,EAAE,MAAM,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC;YACjE,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;YAC7B,WAAW,EAAE;gBACX,YAAY,EACV,MAAM,CAAC,OAAO,KAAK,MAAM;oBACvB,CAAC,CAAC,0FAA0F;oBAC5F,CAAC,CAAC,qKAAqK;aAC5K;SACF,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/tools/_homework.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Rubric library — what each tool's draft answer must satisfy before
+ * being delivered to the user.
+ *
+ * One rubric per category (9 categories) acts as the DEFAULT — every
+ * tool inherits its category's rubric automatically. Tools that need
+ * a stricter or looser rubric can override in their handler by
+ * setting `secondBrain.homework` directly.
+ *
+ * The Super Sonic Engine: every Mneme tool response now carries a
+ * homework rubric the AI must satisfy. AI drafts → calls
+ * mneme.grade.answer → on FAIL, rewrites → loop until PASS. This
+ * pattern is unique to Mneme; no other MCP server enforces it.
+ */
+import type { Homework, ToolCategory } from "./_types.js";
+/** Build the homework block for a tool, given its category. */
+export declare function homeworkForCategory(category: ToolCategory): Homework;
+//# sourceMappingURL=_homework.d.ts.map

package/dist/tools/_homework.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_homework.d.ts","sourceRoot":"","sources":["../../src/tools/_homework.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA+G1D,+DAA+D;AAC/D,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,QAAQ,CAQpE"}

package/dist/tools/_homework.js

@@ -0,0 +1,121 @@
+/**
+ * Rubric library — what each tool's draft answer must satisfy before
+ * being delivered to the user.
+ *
+ * One rubric per category (9 categories) acts as the DEFAULT — every
+ * tool inherits its category's rubric automatically. Tools that need
+ * a stricter or looser rubric can override in their handler by
+ * setting `secondBrain.homework` directly.
+ *
+ * The Super Sonic Engine: every Mneme tool response now carries a
+ * homework rubric the AI must satisfy. AI drafts → calls
+ * mneme.grade.answer → on FAIL, rewrites → loop until PASS. This
+ * pattern is unique to Mneme; no other MCP server enforces it.
+ */
+/** The 5-axis core requirements every Mneme answer must satisfy.
+ *  Categories layer their own additional requirements on top. */
+const BASE_REQUIREMENTS = [
+    {
+        id: "no-hallucinated-citations",
+        description: "Every commit hash mentioned must exist in the repo (verified via git rev-parse).",
+        weight: 1.0,
+    },
+    {
+        id: "no-empty-wisdom",
+        description: "The wisdom field must be a non-empty, non-trivial sentence — not just 'see data'.",
+        weight: 0.8,
+    },
+    {
+        id: "confidence-stated",
+        description: "The answer must state its confidence (high/medium/low) when claims involve heuristics.",
+        weight: 0.6,
+    },
+];
+/** Category-specific requirement layers. */
+const CATEGORY_REQUIREMENTS = {
+    memory: [
+        { id: "citation-density", description: "≥3 commit citations for any 'why' question, ≥1 for any factual claim.", weight: 1.0 },
+        { id: "no-claim-without-citation", description: "Every factual claim about the repo must trace to a specific commit.", weight: 1.0 },
+        { id: "summary-bounded", description: "Summary ≤ 200 words; longer needs collapsible details.", weight: 0.5 },
+    ],
+    people: [
+        { id: "no-defamation", description: "Friction/atrophy/nemesis findings framed neutrally — observable behavior, never personal judgment.", weight: 1.0 },
+        { id: "atrophy-bounded", description: "Atrophy scores include the 'days since last touch' so reader can verify.", weight: 0.7 },
+        { id: "name-the-author", description: "Always identify the specific author (email or name) when applicable.", weight: 0.8 },
+    ],
+    audit: [
+        { id: "all-axes-graded", description: "Trust certificate must score every applicable axis (behavioral / API / tests / perf / narrative).", weight: 1.0 },
+        { id: "verdict-matches-axes", description: "Overall PASS/WARN/FAIL must be consistent with the per-axis findings.", weight: 1.0 },
+        { id: "remediation-actionable", description: "Every FAIL axis must include a concrete fix recommendation.", weight: 0.9 },
+    ],
+    forensics: [
+        { id: "cwe-cited", description: "Every vuln finding cites its CWE class (e.g. CWE-89, CWE-79).", weight: 1.0 },
+        { id: "evidence-quoted", description: "Show the actual line of code that triggered the rule.", weight: 0.9 },
+        { id: "false-positive-disclaimer", description: "Always remind the reader that findings are CANDIDATES — verify before action.", weight: 0.7 },
+    ],
+    insights: [
+        { id: "narrative-cohesion", description: "Story / chronicle / time-machine answers must follow chronological + causal order.", weight: 0.8 },
+        { id: "ground-in-history", description: "Insights must cite ≥2 commits or PRs as evidence — no speculation without anchor.", weight: 0.9 },
+        { id: "actionable", description: "End with a concrete next-step the user can take.", weight: 0.7 },
+    ],
+    quality: [
+        { id: "metric-explained", description: "Every metric stated (atrophy / heartbeat / karma / DNA) must be one-sentence explained inline.", weight: 0.8 },
+        { id: "outliers-flagged", description: "Top-3 outliers (most-unusual axes / files / authors) must be highlighted explicitly.", weight: 0.7 },
+    ],
+    quant: [
+        { id: "math-transparent", description: "When a quant metric is reported, briefly state the formula / methodology.", weight: 0.7 },
+        { id: "limits-named", description: "Acknowledge the corpus + assumptions the quant ran against.", weight: 0.6 },
+    ],
+    lab: [
+        { id: "plan-auditable", description: "Composed plans show every step + the atom each step calls.", weight: 0.9 },
+        { id: "side-effects-named", description: "Plans that hit network / filesystem / git / subprocess declare it upfront.", weight: 1.0 },
+    ],
+    meta: [
+        { id: "scoped", description: "Meta tools (capabilities, doctor, wisdom) keep output scoped to their purpose — no scope creep.", weight: 0.5 },
+    ],
+};
+/** Category default rubrics — the writing the AI must produce per category. */
+const CATEGORY_RUBRICS = {
+    memory: "Quote the wisdom field directly. Cite ≥3 commits with their short hashes inline. Don't invent commits. " +
+        "If <3 citations available, tell the user the answer is best-effort.",
+    people: "Frame neutrally — describe observable behavior, never personal character. Always name the specific author. " +
+        "Include the heuristic caveat (e.g. 'atrophy is heuristic, not certified knowledge measurement').",
+    audit: "Lead with the verdict (PASS/WARN/FAIL) in bold. List every axis with its score + one-line justification. " +
+        "For every FAIL axis, give a specific fix the developer can apply right now.",
+    forensics: "Open with severity + CWE class. Quote the offending line of code. Always disclose: this is a CANDIDATE, " +
+        "verify before acting. Never claim certainty without confirming the rule prior matches the stack.",
+    insights: "Tell a story — chronological, causal, anchored to specific commits. End with one concrete action the " +
+        "user can take. Avoid speculation that isn't grounded in the diff or PR text.",
+    quality: "State the metric, then translate it to plain English. Highlight the top-3 outliers explicitly. " +
+        "Skip rendering rows that are within normal range unless asked.",
+    quant: "When a number appears, name the formula or method in one phrase. Acknowledge the corpus the metric ran " +
+        "against. Quant findings are signals, not verdicts.",
+    lab: "If you're emitting a plan, show every step with the atom it calls. Declare side-effects upfront. " +
+        "Default to dry-run unless the user explicitly opts into execution.",
+    meta: "Stay scoped to the meta-question. The capabilities tool returns a syllabus; the doctor returns env state; " +
+        "the wisdom tool returns a meditation. Don't mix scopes.",
+};
+/** All 5 novel grading algorithms applied by default — except for the
+ *  meta category (where mutation tests would be silly). */
+const DEFAULT_ALGORITHMS_BY_CATEGORY = {
+    memory: ["semantic-citation", "adversarial-probe", "claim-graph-mutation"],
+    people: ["semantic-citation", "claim-graph-mutation"],
+    audit: ["multi-verifier-consensus", "mutation-counterfactual", "claim-graph-mutation"],
+    forensics: ["adversarial-probe", "semantic-citation", "multi-verifier-consensus"],
+    insights: ["semantic-citation", "claim-graph-mutation", "adversarial-probe"],
+    quality: ["claim-graph-mutation", "semantic-citation"],
+    quant: ["mutation-counterfactual", "multi-verifier-consensus"],
+    lab: ["claim-graph-mutation"],
+    meta: [],
+};
+/** Build the homework block for a tool, given its category. */
+export function homeworkForCategory(category) {
+    return {
+        rubric: CATEGORY_RUBRICS[category],
+        requirements: [...BASE_REQUIREMENTS, ...CATEGORY_REQUIREMENTS[category]],
+        grader: "mneme.grade.answer",
+        maxRetries: 3,
+        algorithms: DEFAULT_ALGORITHMS_BY_CATEGORY[category],
+    };
+}
+//# sourceMappingURL=_homework.js.map

package/dist/tools/_homework.js.map

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

package/dist/tools/_lifecycle.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Lifecycle tracking — record AI tool invocations + auto-promote frequent
+ * compositions into the periodic library.
+ *
+ * The chain reaction: every tool call lands here. We hash the (set of atoms
+ * called within a session window) into a "molecule signature" and count
+ * occurrences. When a signature reaches the promotion threshold (≥3 across
+ * sessions), we suggest promoting it to a named compound — the user (or AI)
+ * picks an alias, and from then on the compound shows up as a single
+ * callable in `mneme.lab.library`.
+ *
+ * Storage: .mneme/mcp-lifecycle.json (NOT the same as library.json — the
+ * library is for compose-CLI plans; this file tracks live AI invocations).
+ *
+ * Race-condition safety: read-modify-write with a temp file rename. Single
+ * MCP server per repo at a time; if two run, the second-writer wins, no
+ * corruption since the file is small (<100KB even after years of use).
+ */
+interface MoleculeSignature {
+    /** Sorted atom names joined with "+" for stable key */
+    key: string;
+    /** Atom names (preserves first-seen order for display) */
+    atoms: string[];
+    /** Total times this signature has been observed */
+    invocations: number;
+    /** ISO date of first observation */
+    firstSeen: string;
+    /** ISO date of last observation */
+    lastSeen: string;
+    /** Has the user been prompted to save this as a compound? */
+    promotionPrompted: boolean;
+    /** Saved alias (set when user/AI promotes) */
+    promotedAs?: string;
+}
+/** Record that the AI just invoked toolName. If multiple atoms have been
+ *  called in the same session window, also record them as a molecule
+ *  signature (the chain reaction trigger). */
+export declare function recordInvocation(repoRoot: string, toolName: string): {
+    isNewCombination: boolean;
+    invocationCount: number;
+    suggestSaveAs?: string;
+};
+/** List molecule signatures observed so far — used by mneme.brain.library.
+ *  Sorted by frequency descending, then by recency. */
+export declare function listSignatures(repoRoot: string): MoleculeSignature[];
+/** Promote a molecule signature into a named compound. Marks it as promoted
+ *  in the lifecycle store; the actual compound is written to library.json by
+ *  the existing periodic.promote() machinery. */
+export declare function markPromoted(repoRoot: string, key: string, alias: string): boolean;
+export {};
+//# sourceMappingURL=_lifecycle.d.ts.map

package/dist/tools/_lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_lifecycle.d.ts","sourceRoot":"","sources":["../../src/tools/_lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,UAAU,iBAAiB;IACzB,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,iBAAiB,EAAE,OAAO,CAAC;IAC3B,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA0CD;;8CAE8C;AAC9C,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG;IACpE,gBAAgB,EAAE,OAAO,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAiDA;AAED;uDACuD;AACvD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAMpE;AAED;;iDAEiD;AACjD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAOlF"}

package/dist/tools/_lifecycle.js

@@ -0,0 +1,124 @@
+/**
+ * Lifecycle tracking — record AI tool invocations + auto-promote frequent
+ * compositions into the periodic library.
+ *
+ * The chain reaction: every tool call lands here. We hash the (set of atoms
+ * called within a session window) into a "molecule signature" and count
+ * occurrences. When a signature reaches the promotion threshold (≥3 across
+ * sessions), we suggest promoting it to a named compound — the user (or AI)
+ * picks an alias, and from then on the compound shows up as a single
+ * callable in `mneme.lab.library`.
+ *
+ * Storage: .mneme/mcp-lifecycle.json (NOT the same as library.json — the
+ * library is for compose-CLI plans; this file tracks live AI invocations).
+ *
+ * Race-condition safety: read-modify-write with a temp file rename. Single
+ * MCP server per repo at a time; if two run, the second-writer wins, no
+ * corruption since the file is small (<100KB even after years of use).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { join, dirname } from "node:path";
+const PROMOTION_THRESHOLD = 3;
+const SESSION_WINDOW_MS = 5 * 60_000; // 5 minutes
+/** In-memory window tracker — accumulates atoms called within the same
+ *  AI session before flushing to the persistent store. */
+let currentSession = {
+    atoms: new Set(),
+    lastTouch: 0,
+};
+function lifecyclePath(repoRoot) {
+    return join(repoRoot, ".mneme", "mcp-lifecycle.json");
+}
+function readStore(repoRoot) {
+    const p = lifecyclePath(repoRoot);
+    if (!existsSync(p))
+        return { version: 1, signatures: {} };
+    try {
+        const raw = readFileSync(p, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1)
+            return { version: 1, signatures: {} };
+        return parsed;
+    }
+    catch {
+        return { version: 1, signatures: {} };
+    }
+}
+function writeStore(repoRoot, store) {
+    const p = lifecyclePath(repoRoot);
+    if (!existsSync(dirname(p)))
+        mkdirSync(dirname(p), { recursive: true });
+    const tmp = p + ".tmp";
+    writeFileSync(tmp, JSON.stringify(store, null, 2) + "\n", "utf8");
+    renameSync(tmp, p);
+}
+/** Record that the AI just invoked toolName. If multiple atoms have been
+ *  called in the same session window, also record them as a molecule
+ *  signature (the chain reaction trigger). */
+export function recordInvocation(repoRoot, toolName) {
+    const now = Date.now();
+    // Reset session window if too much time has passed
+    if (now - currentSession.lastTouch > SESSION_WINDOW_MS) {
+        currentSession = { atoms: new Set(), lastTouch: now };
+    }
+    currentSession.atoms.add(toolName);
+    currentSession.lastTouch = now;
+    // Only record signatures when ≥2 atoms in window — single-atom calls
+    // are just normal tool use, not a molecule.
+    if (currentSession.atoms.size < 2) {
+        return { isNewCombination: false, invocationCount: 1 };
+    }
+    const atoms = Array.from(currentSession.atoms).sort();
+    const key = atoms.join("+");
+    const store = readStore(repoRoot);
+    const existing = store.signatures[key];
+    const today = new Date().toISOString();
+    if (!existing) {
+        store.signatures[key] = {
+            key,
+            atoms,
+            invocations: 1,
+            firstSeen: today,
+            lastSeen: today,
+            promotionPrompted: false,
+        };
+        writeStore(repoRoot, store);
+        return { isNewCombination: true, invocationCount: 1 };
+    }
+    existing.invocations++;
+    existing.lastSeen = today;
+    let suggestSaveAs;
+    if (existing.invocations >= PROMOTION_THRESHOLD && !existing.promotionPrompted && !existing.promotedAs) {
+        existing.promotionPrompted = true;
+        suggestSaveAs = `compound_${atoms[0]?.split(".").slice(-1)[0] ?? "x"}_${atoms.length}atoms`;
+    }
+    writeStore(repoRoot, store);
+    return {
+        isNewCombination: false,
+        invocationCount: existing.invocations,
+        suggestSaveAs,
+    };
+}
+/** List molecule signatures observed so far — used by mneme.brain.library.
+ *  Sorted by frequency descending, then by recency. */
+export function listSignatures(repoRoot) {
+    const store = readStore(repoRoot);
+    return Object.values(store.signatures).sort((a, b) => {
+        if (b.invocations !== a.invocations)
+            return b.invocations - a.invocations;
+        return b.lastSeen.localeCompare(a.lastSeen);
+    });
+}
+/** Promote a molecule signature into a named compound. Marks it as promoted
+ *  in the lifecycle store; the actual compound is written to library.json by
+ *  the existing periodic.promote() machinery. */
+export function markPromoted(repoRoot, key, alias) {
+    const store = readStore(repoRoot);
+    const sig = store.signatures[key];
+    if (!sig)
+        return false;
+    sig.promotedAs = alias;
+    writeStore(repoRoot, store);
+    return true;
+}
+//# sourceMappingURL=_lifecycle.js.map

package/dist/tools/_lifecycle.js.map

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

package/dist/tools/_molecules.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Molecule recipes — pre-defined atom combinations that form named molecules.
+ *
+ * Architectural role:
+ *   - Atoms = individual MCP tools (mneme.people.atrophy, mneme.audit.certify, …)
+ *   - Molecules = named combinations of atoms that solve a higher-order question
+ *   - Compounds = molecules promoted into the library via repeated use
+ *
+ * Each tool's `secondBrain.compose` field surfaces the molecules that include
+ * its atom — so the AI sees "if you just ran X, the natural next is to compose
+ * X+Y+Z = molecule M". This triggers the chain-reaction of wisdom.
+ *
+ * The 20 molecules below cover the most-asked higher-order questions in
+ * software-engineering management, security review, and AI-session audit.
+ */
+import type { ComposeSuggestion } from "./_types.js";
+/** All known molecules. Each lists the atoms that compose it + when to fire. */
+export declare const MOLECULES: ComposeSuggestion[];
+/** Find all molecules whose atoms include the given tool name.
+ *  Used by tools to populate their `secondBrain.compose` field. */
+export declare function moleculesContaining(atomName: string): ComposeSuggestion[];
+//# sourceMappingURL=_molecules.d.ts.map

package/dist/tools/_molecules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_molecules.d.ts","sourceRoot":"","sources":["../../src/tools/_molecules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,gFAAgF;AAChF,eAAO,MAAM,SAAS,EAAE,iBAAiB,EAkIxC,CAAC;AAEF;mEACmE;AACnE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAEzE"}

package/dist/tools/_molecules.js

@@ -0,0 +1,142 @@
+/**
+ * Molecule recipes — pre-defined atom combinations that form named molecules.
+ *
+ * Architectural role:
+ *   - Atoms = individual MCP tools (mneme.people.atrophy, mneme.audit.certify, …)
+ *   - Molecules = named combinations of atoms that solve a higher-order question
+ *   - Compounds = molecules promoted into the library via repeated use
+ *
+ * Each tool's `secondBrain.compose` field surfaces the molecules that include
+ * its atom — so the AI sees "if you just ran X, the natural next is to compose
+ * X+Y+Z = molecule M". This triggers the chain-reaction of wisdom.
+ *
+ * The 20 molecules below cover the most-asked higher-order questions in
+ * software-engineering management, security review, and AI-session audit.
+ */
+/** All known molecules. Each lists the atoms that compose it + when to fire. */
+export const MOLECULES = [
+    // ─────── PEOPLE / KNOWLEDGE / TEAM HEALTH ───────
+    {
+        molecule: "succession_plan",
+        atoms: ["mneme.people.atrophy", "mneme.people.bus_factor", "mneme.people.telepathy"],
+        when: "User asks about org-risk, handover, what happens if X leaves, knowledge transfer, " +
+            "single points of failure, or backup engineers.",
+        example: "Atrophy says Alice's auth knowledge is 28/100 (fading). Bus-factor confirms she owns " +
+            "78% of auth files. Telepathy suggests Bob writes auth-shaped code without co-authoring " +
+            "Alice — recommended pair-onboarding target.",
+    },
+    {
+        molecule: "knowledge_health_check",
+        atoms: ["mneme.people.atrophy", "mneme.people.passport", "mneme.quality.repo_mri"],
+        when: "Quarterly review, before a reorg, or when user asks 'how healthy is the team?'.",
+        example: "Combine atrophy heatmap + per-engineer passport + 20-axis MRI into one dashboard.",
+    },
+    {
+        molecule: "onboarding_dossier",
+        atoms: ["mneme.insights.mirror", "mneme.people.who_knows", "mneme.insights.story", "mneme.people.passport"],
+        when: "New hire arrives, or someone asks 'how do I get up to speed on X?'.",
+    },
+    {
+        molecule: "team_friction_diagnosis",
+        atoms: ["mneme.people.nemesis", "mneme.insights.regret", "mneme.people.lineage"],
+        when: "User asks 'where is friction?', 'who's stepping on whom?', 'rewrite churn'.",
+    },
+    // ─────── AI COMMIT SAFETY / AUDIT ───────
+    {
+        molecule: "ai_commit_check",
+        atoms: ["mneme.audit.trace", "mneme.audit.verify", "mneme.audit.certify"],
+        when: "Before merging an AI-generated commit, before a CI gate, or at PR review time.",
+        example: "Trace identifies the AI tool (Claude Code / Cursor / Codex). Verify catches narrative-vs-diff " +
+            "drift. Certify gives 5-axis pass/warn/fail.",
+    },
+    {
+        molecule: "compliance_evidence_pack",
+        atoms: ["mneme.audit.report", "mneme.audit.ledger", "mneme.audit.deps", "mneme.forensics.vulns"],
+        when: "EU AI Act 2026 evidence request, SOX/SOC2 quarterly, or external audit prep.",
+    },
+    // ─────── REFACTOR / SHIP SAFETY ───────
+    {
+        molecule: "refactor_safety_check",
+        atoms: ["mneme.insights.premortem", "mneme.memory.blast", "mneme.people.atrophy"],
+        when: "User proposes a refactor, asks 'is this safe?', 'has this been tried?', or wants to estimate " +
+            "blast radius before merge.",
+        example: "Premortem says 78% regret-risk based on 7 of 9 similar attempts. Blast names 3 incident-prone " +
+            "files in the diff. Atrophy warns the file owner is 28/100 fresh — knowledge gap.",
+    },
+    {
+        molecule: "regret_pattern_review",
+        atoms: ["mneme.insights.regret", "mneme.insights.paradox", "mneme.insights.crystal_ball"],
+        when: "Quarterly retro, post-mortem, or before deciding whether to attempt a contested refactor.",
+    },
+    {
+        molecule: "deploy_gate",
+        atoms: ["mneme.audit.certify", "mneme.forensics.vulns", "mneme.audit.deps", "mneme.insights.crystal_ball"],
+        when: "CI gate before production deploy, release candidate review.",
+    },
+    // ─────── SECURITY / FORENSICS ───────
+    {
+        molecule: "security_review",
+        atoms: ["mneme.forensics.vulns", "mneme.audit.deps", "mneme.forensics.anomaly"],
+        when: "Security review of a feature, before pen-test, or after a suspected incident.",
+    },
+    {
+        molecule: "incident_attribution",
+        atoms: ["mneme.forensics.match", "mneme.forensics.attribute", "mneme.forensics.anomaly"],
+        when: "After a suspicious commit lands, during incident response, or insider-threat review.",
+    },
+    {
+        molecule: "vulnerability_triage",
+        atoms: ["mneme.forensics.vulns", "mneme.forensics.show", "mneme.audit.conscience"],
+        when: "Reviewing a fresh batch of vuln findings — score, inspect, suppress false positives.",
+    },
+    // ─────── STORY / NARRATIVE / DECISIONS ───────
+    {
+        molecule: "decision_archaeology",
+        atoms: ["mneme.memory.ask", "mneme.insights.decisions", "mneme.insights.story"],
+        when: "User asks 'why does X exist?', 'what was the rationale for Y?', or wants ADR-style narrative.",
+        example: "Cited Q&A → ADR list → multi-act narrative arc.",
+    },
+    {
+        molecule: "file_archaeology",
+        atoms: ["mneme.memory.why", "mneme.insights.time_machine", "mneme.quality.palimpsest", "mneme.people.lineage"],
+        when: "User wants the full life story of a file or a single line of code.",
+    },
+    {
+        molecule: "expert_finder",
+        atoms: ["mneme.people.who_knows", "mneme.people.passport", "mneme.people.atrophy"],
+        when: "User asks 'who can help me with X?', 'who should review this PR?'.",
+    },
+    // ─────── QUALITY / DEBT ───────
+    {
+        molecule: "tech_debt_audit",
+        atoms: ["mneme.quality.karma", "mneme.people.promise", "mneme.insights.ghost", "mneme.insights.fossil"],
+        when: "Quarterly tech-debt review, sprint planning for cleanup, or before a major refactor.",
+    },
+    {
+        molecule: "code_quality_dashboard",
+        atoms: ["mneme.quality.repo_mri", "mneme.quality.heartbeat", "mneme.insights.runaway", "mneme.insights.drift"],
+        when: "Engineering manager dashboard, monthly health check, or VP-of-eng update.",
+    },
+    // ─────── PREDICTION / FORESIGHT ───────
+    {
+        molecule: "release_readiness",
+        atoms: ["mneme.audit.certify", "mneme.insights.crystal_ball", "mneme.memory.blast", "mneme.forensics.vulns"],
+        when: "Final go/no-go before shipping a release.",
+    },
+    {
+        molecule: "next_quarter_risk_map",
+        atoms: ["mneme.people.atrophy", "mneme.insights.oracle", "mneme.quant.black_swan", "mneme.quality.heartbeat"],
+        when: "Strategic planning — what's likely to break, who's at risk of forgetting, where are the tail risks?",
+    },
+    {
+        molecule: "moneyball_review",
+        atoms: ["mneme.quant.moneyball", "mneme.people.influence", "mneme.people.passport"],
+        when: "Compensation review, promotion committee, identifying undervalued contributors.",
+    },
+];
+/** Find all molecules whose atoms include the given tool name.
+ *  Used by tools to populate their `secondBrain.compose` field. */
+export function moleculesContaining(atomName) {
+    return MOLECULES.filter((m) => m.atoms.includes(atomName));
+}
+//# sourceMappingURL=_molecules.js.map

package/dist/tools/_molecules.js.map

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

package/dist/tools/_registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_registry.d.ts","sourceRoot":"","sources":["../../src/tools/_registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAc3D;sEACsE;AACtE,wBAAgB,aAAa,IAAI,SAAS,EAAE,CAc3C;AAED,mDAAmD;AACnD,wBAAgB,YAAY,IAAI,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CASrD;AAED,uEAAuE;AACvE,wBAAgB,eAAe,IAAI,GAAG,CAAC,YAAY,EAAE,SAAS,EAAE,CAAC,CAOhE"}
+{"version":3,"file":"_registry.d.ts","sourceRoot":"","sources":["../../src/tools/_registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAe3D;sEACsE;AACtE,wBAAgB,aAAa,IAAI,SAAS,EAAE,CAe3C;AAED,mDAAmD;AACnD,wBAAgB,YAAY,IAAI,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CASrD;AAED,uEAAuE;AACvE,wBAAgB,eAAe,IAAI,GAAG,CAAC,YAAY,EAAE,SAAS,EAAE,CAAC,CAOhE"}

package/dist/tools/_registry.js

@@ -16,11 +16,13 @@ import { labTools } from "./lab.js";
 import { metaTools } from "./meta.js";
 import { capabilitiesTool } from "./_capabilities.js";
 import { smartDoTool } from "./_smart_do.js";
+import { graderTool } from "./_grader_tool.js";
 /** All Mneme tools, in display order. The capabilities syllabus comes first
  *  so AI clients that read tool lists top-down see it immediately. */
 export function buildAllTools() {
     return [
         capabilitiesTool,
+        graderTool,
         smartDoTool,
         ...memoryTools,
         ...peopleTools,

package/dist/tools/_registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"_registry.js","sourceRoot":"","sources":["../../src/tools/_registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C;sEACsE;AACtE,MAAM,UAAU,aAAa;IAC3B,OAAO;QACL,gBAAgB;QAChB,WAAW;QACX,GAAG,WAAW;QACd,GAAG,WAAW;QACd,GAAG,UAAU;QACb,GAAG,cAAc;QACjB,GAAG,aAAa;QAChB,GAAG,YAAY;QACf,GAAG,UAAU;QACb,GAAG,QAAQ;QACX,GAAG,SAAS;KACb,CAAC;AACJ,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,YAAY;IAC1B,MAAM,GAAG,GAAG,IAAI,GAAG,EAAqB,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,aAAa,EAAE,EAAE,CAAC;QAChC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,eAAe;IAC7B,MAAM,GAAG,GAAG,IAAI,GAAG,EAA6B,CAAC;IACjD,KAAK,MAAM,CAAC,IAAI,aAAa,EAAE,EAAE,CAAC;QAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAClD,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"_registry.js","sourceRoot":"","sources":["../../src/tools/_registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C;sEACsE;AACtE,MAAM,UAAU,aAAa;IAC3B,OAAO;QACL,gBAAgB;QAChB,UAAU;QACV,WAAW;QACX,GAAG,WAAW;QACd,GAAG,WAAW;QACd,GAAG,UAAU;QACb,GAAG,cAAc;QACjB,GAAG,aAAa;QAChB,GAAG,YAAY;QACf,GAAG,UAAU;QACb,GAAG,QAAQ;QACX,GAAG,SAAS;KACb,CAAC;AACJ,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,YAAY;IAC1B,MAAM,GAAG,GAAG,IAAI,GAAG,EAAqB,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,aAAa,EAAE,EAAE,CAAC;QAChC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,eAAe;IAC7B,MAAM,GAAG,GAAG,IAAI,GAAG,EAA6B,CAAC;IACjD,KAAK,MAAM,CAAC,IAAI,aAAa,EAAE,EAAE,CAAC;QAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAClD,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}