memoryrail 0.0.0-stage → 0.1.0

package/dist/frontmatter.js

@@ -0,0 +1,57 @@
+/**
+ * Minimal frontmatter codec. Values are written as JSON, which is a valid
+ * subset of YAML, so the files stay readable by any YAML tooling while this
+ * package needs no YAML dependency.
+ */
+export function parse(text) {
+    const src = text.replace(/\r\n/g, "\n");
+    if (!src.startsWith("---\n")) {
+        throw new Error("missing frontmatter (file must start with ---)");
+    }
+    const rest = src.slice(4);
+    let end = rest.indexOf("\n---\n");
+    let bodyStart;
+    if (end !== -1) {
+        bodyStart = end + 5;
+    }
+    else if (rest.endsWith("\n---")) {
+        end = rest.length - 4;
+        bodyStart = rest.length;
+    }
+    else if (rest.startsWith("---\n")) {
+        end = 0;
+        bodyStart = 4;
+    }
+    else {
+        throw new Error("unterminated frontmatter (missing closing ---)");
+    }
+    const data = {};
+    const block = end === 0 ? "" : rest.slice(0, end);
+    for (const [i, line] of block.split("\n").entries()) {
+        if (!line.trim() || line.trimStart().startsWith("#"))
+            continue;
+        const m = /^([A-Za-z_][\w-]*):[ \t]*(.*)$/.exec(line);
+        if (!m)
+            throw new Error(`invalid frontmatter line ${i + 2}: ${line}`);
+        data[m[1]] = parseValue(m[2]);
+    }
+    return { data, body: rest.slice(bodyStart).replace(/^\n+/, "").replace(/\s+$/, "") };
+}
+function parseValue(raw) {
+    const v = raw.trim();
+    if (v === "")
+        return "";
+    try {
+        return JSON.parse(v);
+    }
+    catch {
+        return v;
+    }
+}
+export function stringify(data, body) {
+    const lines = Object.entries(data)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}: ${JSON.stringify(v)}`);
+    const trimmed = body.replace(/\s+$/, "");
+    return `---\n${lines.join("\n")}\n---\n${trimmed ? `\n${trimmed}\n` : ""}`;
+}

package/dist/git.d.ts

@@ -0,0 +1,4 @@
+/** Paths staged for the next commit (empty outside a git repo). */
+export declare function stagedFiles(root: string): string[];
+/** Time of the last commit touching `file`, or null if unknown (no git, untracked, ...). */
+export declare function lastCommitTime(root: string, file: string): Date | null;

package/dist/git.js

@@ -0,0 +1,34 @@
+import { execFileSync } from "node:child_process";
+/** Paths staged for the next commit (empty outside a git repo). */
+export function stagedFiles(root) {
+    try {
+        return execFileSync("git", ["diff", "--cached", "--name-only", "--diff-filter=ACMRD"], {
+            cwd: root,
+            stdio: ["ignore", "pipe", "ignore"],
+            encoding: "utf8",
+        })
+            .split("\n")
+            .map((s) => s.trim())
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+/** Time of the last commit touching `file`, or null if unknown (no git, untracked, ...). */
+export function lastCommitTime(root, file) {
+    try {
+        const out = execFileSync("git", ["log", "-1", "--format=%cI", "--", file], {
+            cwd: root,
+            stdio: ["ignore", "pipe", "ignore"],
+            encoding: "utf8",
+        }).trim();
+        if (!out)
+            return null;
+        const d = new Date(out);
+        return Number.isNaN(d.getTime()) ? null : d;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/handoff.d.ts

@@ -0,0 +1,13 @@
+import type { Memory, NewMemory } from "./types.js";
+export interface HandoffInput {
+    title?: string;
+    summary: string;
+    next?: string[];
+    links?: string[];
+    tags?: string[];
+}
+export declare function handoffToMemory(input: HandoffInput, now?: Date): NewMemory;
+/** A paste-ready prompt that brings a fresh agent up to speed. */
+export declare function resumePrompt(memories: Memory[], opts?: {
+    recentDecisions?: number;
+}): string;

package/dist/handoff.js

@@ -0,0 +1,35 @@
+import { renderMemory } from "./search.js";
+export function handoffToMemory(input, now = new Date()) {
+    const summary = input.summary.trim();
+    if (!summary)
+        throw new Error("handoff needs a summary of what was done");
+    const next = (input.next ?? []).map((n) => n.trim()).filter(Boolean);
+    const body = next.length ? `${summary}\n\n### Next steps\n${next.map((n) => `- ${n}`).join("\n")}` : summary;
+    return {
+        type: "session",
+        title: input.title?.trim() || `Session ${now.toISOString().slice(0, 16).replace("T", " ")}`,
+        body,
+        links: input.links,
+        tags: input.tags,
+    };
+}
+function section(heading, items, render = renderMemory) {
+    return items.length ? `## ${heading}\n\n${items.map(render).join("\n\n")}` : "";
+}
+const newest = (a, b) => Date.parse(b.updated) - Date.parse(a.updated);
+/** A paste-ready prompt that brings a fresh agent up to speed. */
+export function resumePrompt(memories, opts = {}) {
+    const active = memories.filter((m) => m.status === "active");
+    const of = (t) => active.filter((m) => m.type === t).sort(newest);
+    const lastSession = of("session")[0];
+    const parts = [
+        "You are resuming work on an existing project. Below is the project memory recorded by previous sessions. Treat constraints as rules, decisions as settled unless told otherwise, and gotchas as mistakes not to repeat.",
+        lastSession ? section("Last session", [lastSession]) : "",
+        section("Open threads", of("thread")),
+        section("Constraints", of("constraint")),
+        section("Recent decisions", of("decision").slice(0, opts.recentDecisions ?? 5)),
+        section("Gotchas", of("gotcha")),
+        "When you finish, record what you did and what is next with `memoryrail handoff`, and log any new decision with `memoryrail remember`.",
+    ];
+    return parts.filter(Boolean).join("\n\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export * from "./types.js";
+export { parse as parseFrontmatter, stringify as stringifyFrontmatter } from "./frontmatter.js";
+export { Store, findRoot, initRoot, openStore, slugify, DIR_NAME, MEMORIES_DIR, FORMAT_VERSION } from "./store.js";
+export { recall, rank, tokenize, renderMemory, estimateTokens } from "./search.js";
+export type { Hit, RecallOptions, RecallResult } from "./search.js";
+export { lint } from "./lint.js";
+export type { Issue, Severity } from "./lint.js";
+export { sync, renderBlock, DEFAULT_TARGETS } from "./sync.js";
+export type { SyncChange, Target } from "./sync.js";
+export { handoffToMemory, resumePrompt } from "./handoff.js";
+export type { HandoffInput } from "./handoff.js";
+export { precheck } from "./precheck.js";
+export type { PrecheckInput, PrecheckResult, Warning } from "./precheck.js";
+export { refOf } from "./refs.js";
+export { scanSecrets, SecretError } from "./secrets.js";
+export type { SecretFinding } from "./secrets.js";
+export { installMcp, isInstalled, serverEntry } from "./install.js";
+export type { Client, InstallResult } from "./install.js";
+export { doctor } from "./doctor.js";
+export type { Check } from "./doctor.js";
+export { readConfig, writeConfig } from "./store.js";
+export type { Config } from "./store.js";
+export { VERSION } from "./version.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+export * from "./types.js";
+export { parse as parseFrontmatter, stringify as stringifyFrontmatter } from "./frontmatter.js";
+export { Store, findRoot, initRoot, openStore, slugify, DIR_NAME, MEMORIES_DIR, FORMAT_VERSION } from "./store.js";
+export { recall, rank, tokenize, renderMemory, estimateTokens } from "./search.js";
+export { lint } from "./lint.js";
+export { sync, renderBlock, DEFAULT_TARGETS } from "./sync.js";
+export { handoffToMemory, resumePrompt } from "./handoff.js";
+export { precheck } from "./precheck.js";
+export { refOf } from "./refs.js";
+export { scanSecrets, SecretError } from "./secrets.js";
+export { installMcp, isInstalled, serverEntry } from "./install.js";
+export { doctor } from "./doctor.js";
+export { readConfig, writeConfig } from "./store.js";
+export { VERSION } from "./version.js";

package/dist/install.d.ts

@@ -0,0 +1,21 @@
+export type Client = "claude" | "cursor";
+export declare const CLIENT_FILES: Record<Client, string>;
+export interface InstallResult {
+    client: Client;
+    file: string;
+    action: "created" | "updated" | "unchanged";
+}
+export declare function serverEntry(opts?: {
+    npx?: boolean;
+}): {
+    command: string;
+    args: string[];
+};
+/**
+ * Register the MemoryRail MCP server in a client's project config, keeping
+ * every other server and setting in the file. Refuses to touch invalid JSON.
+ */
+export declare function installMcp(root: string, client: Client, opts?: {
+    npx?: boolean;
+}): InstallResult;
+export declare function isInstalled(root: string, client: Client): boolean;

package/dist/install.js

@@ -0,0 +1,50 @@
+import fs from "node:fs";
+import path from "node:path";
+export const CLIENT_FILES = {
+    claude: ".mcp.json", // Claude Code project-scoped MCP servers
+    cursor: ".cursor/mcp.json",
+};
+export function serverEntry(opts = {}) {
+    return opts.npx ? { command: "npx", args: ["-y", "memoryrail", "serve"] } : { command: "memoryrail", args: ["serve"] };
+}
+/**
+ * Register the MemoryRail MCP server in a client's project config, keeping
+ * every other server and setting in the file. Refuses to touch invalid JSON.
+ */
+export function installMcp(root, client, opts = {}) {
+    const rel = CLIENT_FILES[client];
+    const abs = path.join(root, rel);
+    const entry = serverEntry(opts);
+    let doc = {};
+    const exists = fs.existsSync(abs);
+    if (exists) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(abs, "utf8"));
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+                throw new Error("not an object");
+            doc = parsed;
+        }
+        catch (e) {
+            throw new Error(`${rel} is not valid JSON (${e instanceof Error ? e.message : String(e)}); fix it first. Nothing was changed.`);
+        }
+    }
+    const servers = doc["mcpServers"] && typeof doc["mcpServers"] === "object" && !Array.isArray(doc["mcpServers"])
+        ? doc["mcpServers"]
+        : {};
+    if (JSON.stringify(servers["memoryrail"]) === JSON.stringify(entry)) {
+        return { client, file: rel, action: "unchanged" };
+    }
+    const next = { ...doc, mcpServers: { ...servers, memoryrail: entry } };
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, JSON.stringify(next, null, 2) + "\n");
+    return { client, file: rel, action: exists ? "updated" : "created" };
+}
+export function isInstalled(root, client) {
+    try {
+        const doc = JSON.parse(fs.readFileSync(path.join(root, CLIENT_FILES[client]), "utf8"));
+        return Boolean(doc.mcpServers && "memoryrail" in doc.mcpServers);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lint.d.ts

@@ -0,0 +1,14 @@
+import type { Store } from "./store.js";
+export type Severity = "error" | "warning";
+export interface Issue {
+    severity: Severity;
+    rule: string;
+    id?: string;
+    file?: string;
+    message: string;
+}
+export interface LintOptions {
+    /** Check linked files against git history. Disabled in tests without a repo. */
+    git?: boolean;
+}
+export declare function lint(store: Store, opts?: LintOptions): Issue[];

package/dist/lint.js

@@ -0,0 +1,86 @@
+import fs from "node:fs";
+import path from "node:path";
+import { lastCommitTime } from "./git.js";
+import { scanSecrets } from "./secrets.js";
+import { tokenize } from "./search.js";
+function jaccard(a, b) {
+    if (!a.size || !b.size)
+        return 0;
+    let inter = 0;
+    for (const x of a)
+        if (b.has(x))
+            inter++;
+    return inter / (a.size + b.size - inter);
+}
+export function lint(store, opts = {}) {
+    const issues = [];
+    const { memories, errors } = store.loadAll();
+    for (const e of errors) {
+        issues.push({ severity: "error", rule: "invalid-file", file: e.file, message: e.message });
+    }
+    const byId = new Map(memories.map((m) => [m.id, m]));
+    const active = memories.filter((m) => m.status === "active");
+    for (const m of memories) {
+        const secrets = scanSecrets(m.title, m.body, ...m.tags, ...m.links);
+        if (secrets.length) {
+            issues.push({
+                severity: "error",
+                rule: "secret",
+                id: m.id,
+                message: `looks like it contains a secret (${secrets.map((s) => s.rule).join(", ")}); remove it and rotate the credential`,
+            });
+        }
+    }
+    for (const m of memories) {
+        if (m.supersededBy) {
+            const next = byId.get(m.supersededBy);
+            if (!next) {
+                issues.push({ severity: "error", rule: "dangling-supersede", id: m.id, message: `superseded_by points to missing memory ${m.supersededBy}` });
+            }
+            else if (next.supersedes !== m.id && next.status !== "proposed") {
+                issues.push({ severity: "warning", rule: "supersede-mismatch", id: m.id, message: `${next.id} does not point back via supersedes` });
+            }
+            if (m.status === "active") {
+                issues.push({ severity: "warning", rule: "supersede-status", id: m.id, message: "has superseded_by but status is still active" });
+            }
+        }
+        if (m.supersedes && !byId.has(m.supersedes)) {
+            issues.push({ severity: "error", rule: "dangling-supersede", id: m.id, message: `supersedes missing memory ${m.supersedes}` });
+        }
+    }
+    for (const m of active) {
+        for (const link of m.links) {
+            const abs = path.resolve(store.root, link);
+            if (!abs.startsWith(store.root + path.sep) && abs !== store.root) {
+                issues.push({ severity: "error", rule: "link-outside-repo", id: m.id, message: `link escapes the repository: ${link}` });
+                continue;
+            }
+            if (!fs.existsSync(abs)) {
+                issues.push({ severity: "warning", rule: "stale-link", id: m.id, message: `linked path no longer exists: ${link}` });
+                continue;
+            }
+            if (opts.git !== false) {
+                const changed = lastCommitTime(store.root, link);
+                if (changed && changed.getTime() > Date.parse(m.updated)) {
+                    issues.push({
+                        severity: "warning",
+                        rule: "maybe-stale",
+                        id: m.id,
+                        message: `${link} changed after this memory was last updated; review it`,
+                    });
+                }
+            }
+        }
+    }
+    const sets = active.map((m) => ({ m, t: new Set(tokenize(m.title)) }));
+    for (let i = 0; i < sets.length; i++) {
+        for (let j = i + 1; j < sets.length; j++) {
+            const a = sets[i];
+            const b = sets[j];
+            if (a.m.type === b.m.type && jaccard(a.t, b.t) >= 0.8) {
+                issues.push({ severity: "warning", rule: "possible-duplicate", id: a.m.id, message: `very similar to ${b.m.id}; merge or supersede one` });
+            }
+        }
+    }
+    return issues;
+}

package/dist/mcp.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Store } from "./store.js";
+export declare function createServer(store: Store): McpServer;
+export declare function serveStdio(store: Store): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,87 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { handoffToMemory, resumePrompt } from "./handoff.js";
+import { precheck } from "./precheck.js";
+import { refOf } from "./refs.js";
+import { recall } from "./search.js";
+import { DURABLE_TYPES, MEMORY_TYPES } from "./types.js";
+import { VERSION } from "./version.js";
+const typeEnum = z.enum(MEMORY_TYPES);
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const fail = (e) => ({
+    isError: true,
+    content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
+});
+/** Run a tool body, turning thrown errors into MCP tool errors instead of crashing the server. */
+function guard(fn) {
+    return (args) => {
+        try {
+            return text(fn(args));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    };
+}
+export function createServer(store) {
+    const server = new McpServer({ name: "memoryrail", version: VERSION });
+    server.tool("recall", "Search this project's memory (decisions, constraints, gotchas, open threads, past sessions). Call this at the start of a task and before changing an area you have not touched. Returns the most relevant active memories within a token budget.", {
+        query: z.string().optional().describe("What you are about to work on. Omit for the most recent and pinned memories."),
+        types: z.array(typeEnum).optional().describe("Restrict to these memory types."),
+        limit: z.number().int().positive().max(50).optional(),
+        budget: z.number().int().positive().max(20000).optional().describe("Approximate token budget for the response."),
+    }, guard(({ query, types, limit, budget }) => {
+        const r = recall(store.list(), { query, types, limit, budget });
+        if (!r.hits.length)
+            return "No matching memories.";
+        return r.rendered + (r.truncated ? "\n\n(More results exist: raise limit or budget, or narrow the query.)" : "");
+    }));
+    server.tool("remember", "Record something future sessions must know. Use 'decision' for choices and their reasons, 'constraint' for rules to follow, 'gotcha' for traps, 'attempt' for an approach that was tried and FAILED (say why, so nobody retries it), 'thread' for unfinished work. Pass supersedes to replace an earlier memory instead of duplicating it. Never include secrets, tokens or passwords: they are rejected. If the project requires review, durable memories are saved as proposed until a human approves them.", {
+        type: typeEnum,
+        title: z.string().min(1).describe("One line. State the conclusion, not the topic."),
+        body: z.string().optional().describe("Why, and anything needed to apply it."),
+        tags: z.array(z.string()).optional(),
+        links: z.array(z.string()).optional().describe("Repo-relative files this is about, so staleness can be detected."),
+        pinned: z.boolean().optional().describe("Always surface this memory. Use sparingly."),
+        supersedes: z.string().optional().describe("Id of an earlier memory this replaces."),
+    }, guard((input) => {
+        const gated = store.config().review === "agents" && DURABLE_TYPES.includes(input.type);
+        const m = store.add({ ...input, status: gated ? "proposed" : "active" });
+        return gated
+            ? `Proposed ${m.type} ${refOf(m)}: ${m.id}. It is not active until a human runs \`memoryrail approve ${refOf(m)}\`.`
+            : `Saved ${m.type} ${refOf(m)}: ${m.id}`;
+    }));
+    server.tool("precheck", "Call BEFORE you change code. Given what you plan to do and the files you will touch, returns the project's constraints, previously failed approaches, gotchas and decisions that apply. Cite what you rely on as [per REF]; if your plan conflicts with a constraint or decision, stop and ask the user.", {
+        plan: z.string().optional().describe("What you are about to do, in plain words."),
+        files: z.array(z.string()).optional().describe("Repo-relative paths you are about to change."),
+    }, guard(({ plan, files }) => precheck(store.list(), { plan, files }).rendered));
+    server.tool("list_memories", "List memory ids and titles, newest first. Use recall for content.", { types: z.array(typeEnum).optional(), include_inactive: z.boolean().optional() }, guard(({ types, include_inactive }) => {
+        const items = store
+            .list()
+            .filter((m) => (include_inactive || m.status === "active") && (!types?.length || types.includes(m.type)))
+            .sort((a, b) => Date.parse(b.updated) - Date.parse(a.updated));
+        return items.length ? items.map((m) => `${refOf(m)}  [${m.type}] ${m.title}`).join("\n") : "No memories yet.";
+    }));
+    server.tool("forget", "Archive a memory that is wrong or no longer relevant. It stays in git history. For a thread that is finished, use resolve_thread instead.", { id: z.string() }, guard(({ id }) => `Archived ${store.setStatus(store.resolveId(id).id, "archived").id}`));
+    server.tool("resolve_thread", "Mark an open thread as resolved.", { id: z.string() }, guard(({ id }) => {
+        const m = store.resolveId(id);
+        if (m.type !== "thread")
+            throw new Error(`${m.id} is a ${m.type}, not a thread`);
+        return `Resolved ${store.setStatus(m.id, "resolved").id}`;
+    }));
+    server.tool("handoff", "Call at the end of a session: what you did, what is unfinished, and the next steps. The next session's resume prompt starts from this.", {
+        summary: z.string().min(1),
+        next: z.array(z.string()).optional().describe("Concrete next steps."),
+        title: z.string().optional(),
+        links: z.array(z.string()).optional(),
+    }, guard((input) => `Recorded handoff: ${store.add(handoffToMemory(input)).id}`));
+    server.tool("resume", "Get a prompt summarizing the last session, open threads, constraints, recent decisions and gotchas. Call this first in a new session.", {}, guard(() => resumePrompt(store.list())));
+    return server;
+}
+export async function serveStdio(store) {
+    const server = createServer(store);
+    await server.connect(new StdioServerTransport());
+    // stdout carries the protocol; log to stderr only.
+    process.stderr.write(`memoryrail MCP server ready (root: ${store.root})\n`);
+}

package/dist/precheck.d.ts

@@ -0,0 +1,23 @@
+import { type Memory } from "./types.js";
+export interface Warning {
+    memory: Memory;
+    reasons: string[];
+}
+export interface PrecheckInput {
+    /** What you are about to do, in plain words. */
+    plan?: string;
+    /** Repo-relative paths you are about to change. */
+    files?: string[];
+    limit?: number;
+    now?: Date;
+}
+export interface PrecheckResult {
+    warnings: Warning[];
+    rendered: string;
+}
+/**
+ * Before acting: which rules, failed attempts, gotchas and decisions bear on
+ * this plan or these files? Surfaces what the project already learned so the
+ * agent does not repeat a dead end or break a constraint.
+ */
+export declare function precheck(all: Memory[], input: PrecheckInput): PrecheckResult;

package/dist/precheck.js

@@ -0,0 +1,66 @@
+import { refOf } from "./refs.js";
+import { rank } from "./search.js";
+import { DURABLE_TYPES } from "./types.js";
+/** Most binding first: rules, then things that already failed, then traps, then choices. */
+const ORDER = ["constraint", "attempt", "gotcha", "decision"];
+function normalize(p) {
+    return p.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function touching(m, files) {
+    const hits = [];
+    for (const link of m.links.map(normalize)) {
+        for (const f of files)
+            if (f === link || f.startsWith(link + "/"))
+                hits.push(f);
+    }
+    return [...new Set(hits)];
+}
+function condense(body, max = 240) {
+    const flat = body.replace(/\s+/g, " ").trim();
+    return flat.length > max ? flat.slice(0, max - 1).trimEnd() + "…" : flat;
+}
+/**
+ * Before acting: which rules, failed attempts, gotchas and decisions bear on
+ * this plan or these files? Surfaces what the project already learned so the
+ * agent does not repeat a dead end or break a constraint.
+ */
+export function precheck(all, input) {
+    const files = (input.files ?? []).map(normalize).filter(Boolean);
+    const pool = all.filter((m) => m.status === "active" && DURABLE_TYPES.includes(m.type));
+    const plan = input.plan?.trim() ?? "";
+    const scores = new Map();
+    if (plan)
+        for (const h of rank(pool, plan, input.now))
+            if (h.score > 0.01)
+                scores.set(h.memory.id, h.score);
+    const warnings = [];
+    for (const m of pool) {
+        const reasons = [];
+        if (m.pinned && m.type === "constraint")
+            reasons.push("pinned rule");
+        const hits = touching(m, files);
+        if (hits.length)
+            reasons.push(`about ${hits.join(", ")}`);
+        if (scores.has(m.id))
+            reasons.push("matches your plan");
+        if (reasons.length)
+            warnings.push({ memory: m, reasons });
+    }
+    const weight = (w) => ORDER.indexOf(w.memory.type) * 10 - (touching(w.memory, files).length ? 5 : 0) - (scores.get(w.memory.id) ?? 0) / 100;
+    warnings.sort((a, b) => weight(a) - weight(b) || a.memory.id.localeCompare(b.memory.id));
+    const shown = warnings.slice(0, input.limit ?? 12);
+    if (!shown.length) {
+        return { warnings: [], rendered: "No relevant constraints, failed attempts, gotchas or decisions found for this plan." };
+    }
+    const lines = [
+        "Check these before you proceed. Cite what you rely on as [per REF]. If your plan conflicts with a constraint or decision, stop and ask.",
+        "",
+        ...shown.map((w) => {
+            const body = condense(w.memory.body);
+            return `- [${refOf(w.memory)}] (${w.memory.type}) ${w.memory.title} — ${w.reasons.join("; ")}${body ? `\n    ${body}` : ""}`;
+        }),
+    ];
+    if (warnings.length > shown.length)
+        lines.push("", `(${warnings.length - shown.length} more; narrow the plan or files)`);
+    return { warnings: shown, rendered: lines.join("\n") };
+}

package/dist/refs.d.ts

@@ -0,0 +1,8 @@
+import type { Memory } from "./types.js";
+/**
+ * A short, stable handle for citing a memory, e.g. `DEC-a3f9`.
+ * Derived from the id, so it is never stored and two branches can never
+ * allocate the same counter value.
+ */
+export declare function refOf(m: Pick<Memory, "id" | "type">): string;
+export declare const REF_PATTERN: RegExp;

package/dist/refs.js

@@ -0,0 +1,18 @@
+import { createHash } from "node:crypto";
+const PREFIX = {
+    decision: "DEC",
+    constraint: "CON",
+    gotcha: "GOT",
+    attempt: "ATT",
+    thread: "THR",
+    session: "SES",
+};
+/**
+ * A short, stable handle for citing a memory, e.g. `DEC-a3f9`.
+ * Derived from the id, so it is never stored and two branches can never
+ * allocate the same counter value.
+ */
+export function refOf(m) {
+    return `${PREFIX[m.type]}-${createHash("sha1").update(m.id).digest("hex").slice(0, 4)}`;
+}
+export const REF_PATTERN = /^[A-Za-z]{3}-[0-9a-f]{4}$/;

package/dist/search.d.ts

@@ -0,0 +1,25 @@
+import type { Memory, MemoryType } from "./types.js";
+export declare function tokenize(text: string): string[];
+export declare function estimateTokens(text: string): number;
+export interface RecallOptions {
+    query?: string;
+    types?: MemoryType[];
+    limit?: number;
+    /** Approximate token budget for the rendered output. */
+    budget?: number;
+    includeInactive?: boolean;
+    now?: Date;
+}
+export interface Hit {
+    memory: Memory;
+    score: number;
+}
+export interface RecallResult {
+    hits: Hit[];
+    rendered: string;
+    truncated: boolean;
+}
+/** BM25 over title/tags/links/body, with a mild recency boost. */
+export declare function rank(memories: Memory[], query: string, now?: Date): Hit[];
+export declare function renderMemory(m: Memory): string;
+export declare function recall(all: Memory[], opts?: RecallOptions): RecallResult;