memoryrail 0.0.0-stage → 0.1.0

package/dist/search.js

@@ -0,0 +1,104 @@
+import { refOf } from "./refs.js";
+const STOPWORDS = new Set("a an and are as at be by for from has have how in is it its of on or that the this to was we what when where which with you your do does did not no can i".split(" "));
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 1 && !STOPWORDS.has(t))
+        .map(stem);
+}
+function stem(t) {
+    if (t.length > 4 && t.endsWith("ies"))
+        return t.slice(0, -3) + "y";
+    if (t.length > 3 && t.endsWith("s") && !t.endsWith("ss"))
+        return t.slice(0, -1);
+    return t;
+}
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+const K1 = 1.2;
+const B = 0.75;
+function termFreq(m) {
+    const tf = new Map();
+    const add = (text, weight) => {
+        for (const t of tokenize(text))
+            tf.set(t, (tf.get(t) ?? 0) + weight);
+    };
+    add(m.title, 3);
+    add(m.tags.join(" "), 3);
+    add(m.links.join(" "), 1);
+    add(m.body, 1);
+    return tf;
+}
+/** BM25 over title/tags/links/body, with a mild recency boost. */
+export function rank(memories, query, now = new Date()) {
+    const qTerms = [...new Set(tokenize(query))];
+    const docs = memories.map((m) => ({ m, tf: termFreq(m) }));
+    const lens = docs.map((d) => [...d.tf.values()].reduce((a, b) => a + b, 0));
+    const avg = lens.reduce((a, b) => a + b, 0) / Math.max(1, lens.length) || 1;
+    const n = docs.length;
+    return docs
+        .map((d, i) => {
+        let score = 0;
+        for (const term of qTerms) {
+            const f = d.tf.get(term) ?? 0;
+            if (!f)
+                continue;
+            const df = docs.reduce((c, x) => c + (x.tf.has(term) ? 1 : 0), 0);
+            const idf = Math.log(1 + (n - df + 0.5) / (df + 0.5));
+            score += idf * ((f * (K1 + 1)) / (f + K1 * (1 - B + B * ((lens[i] ?? 0) / avg))));
+        }
+        const ageDays = Math.max(0, (now.getTime() - Date.parse(d.m.updated)) / 86_400_000);
+        const recency = Math.exp(-ageDays / 90);
+        return { memory: d.m, score: score * (1 + 0.25 * recency) + 0.001 * recency };
+    })
+        .sort((a, b) => b.score - a.score || Date.parse(b.memory.updated) - Date.parse(a.memory.updated));
+}
+export function renderMemory(m) {
+    const head = `### [${refOf(m)}] ${m.title}`;
+    const meta = [`${m.type}`, `id: ${m.id}`];
+    if (m.tags.length)
+        meta.push(`tags: ${m.tags.join(", ")}`);
+    if (m.links.length)
+        meta.push(`files: ${m.links.join(", ")}`);
+    if (m.status !== "active")
+        meta.push(`status: ${m.status}`);
+    return [head, m.body, meta.length ? `_${meta.join(" · ")}_` : ""].filter(Boolean).join("\n");
+}
+export function recall(all, opts = {}) {
+    const limit = opts.limit ?? 8;
+    const budget = opts.budget ?? 1500;
+    const pool = all.filter((m) => (opts.includeInactive || m.status === "active") && (!opts.types?.length || opts.types.includes(m.type)));
+    const pinned = pool
+        .filter((m) => m.pinned)
+        .sort((a, b) => Date.parse(b.updated) - Date.parse(a.updated))
+        .map((memory) => ({ memory, score: Number.POSITIVE_INFINITY }));
+    const rest = pool.filter((m) => !m.pinned);
+    const query = opts.query?.trim() ?? "";
+    const ranked = query
+        ? rank(rest, query, opts.now).filter((h) => h.score > 0.01)
+        : rank(rest, "", opts.now);
+    const ordered = [...pinned, ...ranked];
+    const hits = [];
+    const parts = [];
+    let used = 0;
+    let truncated = false;
+    for (const hit of ordered) {
+        if (hits.length >= limit) {
+            truncated = true;
+            break;
+        }
+        const text = renderMemory(hit.memory);
+        const cost = estimateTokens(text);
+        // Always return at least one result, then respect the budget.
+        if (hits.length > 0 && used + cost > budget) {
+            truncated = true;
+            break;
+        }
+        hits.push(hit);
+        parts.push(text);
+        used += cost;
+    }
+    return { hits, rendered: parts.join("\n\n"), truncated };
+}

package/dist/secrets.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Memory is committed to git and fed back to models, so a secret written once
+ * is published and re-sent forever. Scan on write and refuse.
+ *
+ * Findings carry only the rule name, never the matched text.
+ */
+export interface SecretFinding {
+    rule: string;
+}
+export declare function scanSecrets(...texts: Array<string | undefined>): SecretFinding[];
+export declare class SecretError extends Error {
+    readonly findings: SecretFinding[];
+    constructor(findings: SecretFinding[]);
+}

package/dist/secrets.js

@@ -0,0 +1,42 @@
+/**
+ * Memory is committed to git and fed back to models, so a secret written once
+ * is published and re-sent forever. Scan on write and refuse.
+ *
+ * Findings carry only the rule name, never the matched text.
+ */
+const MIXED = String.raw `(?=[^\s'"]*\d)(?=[^\s'"]*[A-Za-z])[^\s'"]{8,}`;
+const RULES = [
+    ["private-key", /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+    ["aws-access-key", /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/],
+    ["github-token", /\b(?:gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,})\b/],
+    ["slack-token", /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/],
+    ["stripe-key", /\b[rs]k_live_[A-Za-z0-9]{16,}\b/],
+    ["google-api-key", /\bAIza[0-9A-Za-z_-]{35}\b/],
+    ["anthropic-key", /\bsk-ant-[A-Za-z0-9_-]{20,}\b/],
+    ["openai-key", /\bsk-(?:proj-)?[A-Za-z0-9_-]{32,}\b/],
+    ["jwt", /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/],
+    ["url-credentials", /\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]{3,}@/i],
+    [
+        "credential-assignment",
+        new RegExp(String.raw `\b(?:password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key|auth)\w*\s*[:=]\s*['"]?${MIXED}`, "i"),
+    ],
+];
+export function scanSecrets(...texts) {
+    const found = new Set();
+    for (const t of texts) {
+        if (!t)
+            continue;
+        for (const [rule, re] of RULES)
+            if (re.test(t))
+                found.add(rule);
+    }
+    return [...found].map((rule) => ({ rule }));
+}
+export class SecretError extends Error {
+    findings;
+    constructor(findings) {
+        super(`refusing to save: looks like it contains a secret (${findings.map((f) => f.rule).join(", ")}). ` +
+            `Describe where the secret lives instead of what it is. Humans can override with --allow-secrets.`);
+        this.findings = findings;
+    }
+}

package/dist/store.d.ts

@@ -0,0 +1,50 @@
+import { type Memory, type NewMemory, type Status } from "./types.js";
+export declare const DIR_NAME = ".memoryrail";
+export declare const MEMORIES_DIR = "memories";
+export declare const FORMAT_VERSION = 1;
+export interface LoadError {
+    file: string;
+    message: string;
+}
+export interface Config {
+    version: number;
+    /**
+     * `agents`: durable memories written over MCP start as `proposed` and need
+     * `memoryrail approve`. `off`: they are active immediately (git review only).
+     */
+    review: "off" | "agents";
+}
+export declare function readConfig(root: string): Config;
+export declare function writeConfig(root: string, config: Config): void;
+/** Walk up from `start` looking for a directory that contains `.memoryrail/`. */
+export declare function findRoot(start?: string): string | null;
+export declare function initRoot(root: string): {
+    created: boolean;
+};
+export declare function slugify(s: string): string;
+export declare class Store {
+    readonly root: string;
+    constructor(root: string);
+    get dir(): string;
+    private file;
+    /** Load every memory, reporting files that fail validation instead of throwing. */
+    loadAll(): {
+        memories: Memory[];
+        errors: LoadError[];
+    };
+    list(): Memory[];
+    get(id: string): Memory | undefined;
+    config(): Config;
+    /** Resolve an exact id, a short ref like `DEC-a3f9`, or an unambiguous id prefix. */
+    resolveId(idOrPrefix: string): Memory;
+    add(input: NewMemory): Memory;
+    /** Accept a proposed memory. Applies its supersession, if any. */
+    approve(idOrRef: string): Memory;
+    /** Discard a proposed memory. */
+    reject(idOrRef: string): Memory;
+    setStatus(idOrPrefix: string, status: Status): Memory;
+    /** Permanently delete a memory file. Prefer `setStatus(id, "archived")`. */
+    remove(idOrPrefix: string): Memory;
+    private write;
+}
+export declare function openStore(start?: string): Store;

package/dist/store.js

@@ -0,0 +1,273 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse, stringify } from "./frontmatter.js";
+import { REF_PATTERN, refOf } from "./refs.js";
+import { SecretError, scanSecrets } from "./secrets.js";
+import { isMemoryType, isStatus, } from "./types.js";
+export const DIR_NAME = ".memoryrail";
+export const MEMORIES_DIR = "memories";
+export const FORMAT_VERSION = 1;
+export function readConfig(root) {
+    const file = path.join(root, DIR_NAME, "config.json");
+    let raw = {};
+    try {
+        raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        /* fall through to defaults */
+    }
+    return {
+        version: typeof raw["version"] === "number" ? raw["version"] : FORMAT_VERSION,
+        review: raw["review"] === "agents" ? "agents" : "off",
+    };
+}
+export function writeConfig(root, config) {
+    fs.writeFileSync(path.join(root, DIR_NAME, "config.json"), JSON.stringify(config, null, 2) + "\n");
+}
+/** Walk up from `start` looking for a directory that contains `.memoryrail/`. */
+export function findRoot(start = process.cwd()) {
+    const env = process.env["MEMORYRAIL_ROOT"];
+    if (env)
+        return fs.existsSync(path.join(env, DIR_NAME)) ? path.resolve(env) : null;
+    let dir = path.resolve(start);
+    for (;;) {
+        if (fs.existsSync(path.join(dir, DIR_NAME, "config.json")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export function initRoot(root) {
+    const base = path.join(root, DIR_NAME);
+    const config = path.join(base, "config.json");
+    fs.mkdirSync(path.join(base, MEMORIES_DIR), { recursive: true });
+    if (fs.existsSync(config))
+        return { created: false };
+    writeConfig(root, { version: FORMAT_VERSION, review: "off" });
+    fs.writeFileSync(path.join(base, MEMORIES_DIR, ".gitkeep"), "");
+    return { created: true };
+}
+export function slugify(s) {
+    return (s
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48)
+        .replace(/-+$/, "") || "memory");
+}
+function stringList(v) {
+    if (v === undefined || v === null || v === "")
+        return [];
+    if (Array.isArray(v))
+        return v.map((x) => String(x));
+    return [String(v)];
+}
+function toMemory(data, body, fileId) {
+    const id = data["id"] === undefined ? fileId : String(data["id"]);
+    if (id !== fileId)
+        throw new Error(`id "${id}" does not match file name "${fileId}"`);
+    if (!isMemoryType(data["type"]))
+        throw new Error(`invalid or missing type: ${String(data["type"])}`);
+    const status = data["status"] ?? "active";
+    if (!isStatus(status))
+        throw new Error(`invalid status: ${String(status)}`);
+    if (typeof data["title"] !== "string" || !data["title"].trim())
+        throw new Error("missing title");
+    const created = String(data["created"] ?? "");
+    const updated = String(data["updated"] ?? created);
+    if (Number.isNaN(Date.parse(created)))
+        throw new Error(`invalid created date: ${created}`);
+    if (Number.isNaN(Date.parse(updated)))
+        throw new Error(`invalid updated date: ${updated}`);
+    const m = {
+        id,
+        type: data["type"],
+        title: data["title"].trim(),
+        status,
+        created,
+        updated,
+        tags: stringList(data["tags"]),
+        links: stringList(data["links"]),
+        pinned: data["pinned"] === true,
+        body,
+    };
+    if (data["supersedes"])
+        m.supersedes = String(data["supersedes"]);
+    if (data["superseded_by"])
+        m.supersededBy = String(data["superseded_by"]);
+    return m;
+}
+function serialize(m) {
+    return stringify({
+        id: m.id,
+        type: m.type,
+        title: m.title,
+        status: m.status,
+        created: m.created,
+        updated: m.updated,
+        tags: m.tags,
+        links: m.links,
+        pinned: m.pinned ? true : undefined,
+        supersedes: m.supersedes,
+        superseded_by: m.supersededBy,
+    }, m.body);
+}
+export class Store {
+    root;
+    constructor(root) {
+        this.root = path.resolve(root);
+    }
+    get dir() {
+        return path.join(this.root, DIR_NAME, MEMORIES_DIR);
+    }
+    file(id) {
+        return path.join(this.dir, `${id}.md`);
+    }
+    /** Load every memory, reporting files that fail validation instead of throwing. */
+    loadAll() {
+        const memories = [];
+        const errors = [];
+        if (!fs.existsSync(this.dir))
+            return { memories, errors };
+        for (const name of fs.readdirSync(this.dir).sort()) {
+            if (!name.endsWith(".md"))
+                continue;
+            const file = path.join(DIR_NAME, MEMORIES_DIR, name);
+            try {
+                const { data, body } = parse(fs.readFileSync(path.join(this.dir, name), "utf8"));
+                memories.push(toMemory(data, body, name.slice(0, -3)));
+            }
+            catch (e) {
+                errors.push({ file, message: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        return { memories, errors };
+    }
+    list() {
+        return this.loadAll().memories;
+    }
+    get(id) {
+        if (!/^[\w.-]+$/.test(id))
+            return undefined;
+        return this.list().find((m) => m.id === id);
+    }
+    config() {
+        return readConfig(this.root);
+    }
+    /** Resolve an exact id, a short ref like `DEC-a3f9`, or an unambiguous id prefix. */
+    resolveId(idOrPrefix) {
+        const all = this.list();
+        const exact = all.find((m) => m.id === idOrPrefix);
+        if (exact)
+            return exact;
+        if (REF_PATTERN.test(idOrPrefix)) {
+            const wanted = idOrPrefix.toUpperCase().slice(0, 3) + idOrPrefix.slice(3).toLowerCase();
+            const byRef = all.filter((m) => refOf(m) === wanted);
+            if (byRef.length === 1)
+                return byRef[0];
+            if (byRef.length > 1)
+                throw new Error(`ref "${idOrPrefix}" is ambiguous: ${byRef.map((m) => m.id).join(", ")}`);
+        }
+        const matches = all.filter((m) => m.id.startsWith(idOrPrefix));
+        if (matches.length === 1)
+            return matches[0];
+        if (matches.length === 0)
+            throw new Error(`no memory with id "${idOrPrefix}"`);
+        throw new Error(`id prefix "${idOrPrefix}" is ambiguous: ${matches.map((m) => m.id).join(", ")}`);
+    }
+    add(input) {
+        const title = input.title.trim();
+        if (!title)
+            throw new Error("title is required");
+        if (!input.allowSecrets) {
+            const findings = scanSecrets(title, input.body, ...(input.tags ?? []), ...(input.links ?? []));
+            if (findings.length)
+                throw new SecretError(findings);
+        }
+        const prior = input.supersedes ? this.resolveId(input.supersedes) : undefined;
+        const status = input.status ?? "active";
+        const now = new Date().toISOString();
+        const stamp = now.slice(0, 10).replace(/-/g, "");
+        const base = `${stamp}-${slugify(title)}`;
+        let id = base;
+        for (let n = 2; fs.existsSync(this.file(id)); n++)
+            id = `${base}-${n}`;
+        const m = {
+            id,
+            type: input.type,
+            title,
+            status,
+            created: now,
+            updated: now,
+            tags: dedupe(input.tags ?? []),
+            links: dedupe((input.links ?? []).map(normalizeLink)),
+            pinned: input.pinned ?? false,
+            body: (input.body ?? "").trim(),
+        };
+        if (prior)
+            m.supersedes = prior.id;
+        this.write(m);
+        // A proposal must not retire the old memory until a human approves it.
+        if (prior && status === "active")
+            this.write({ ...prior, status: "superseded", supersededBy: id, updated: now });
+        return m;
+    }
+    /** Accept a proposed memory. Applies its supersession, if any. */
+    approve(idOrRef) {
+        const m = this.resolveId(idOrRef);
+        if (m.status !== "proposed")
+            throw new Error(`${m.id} is ${m.status}, not proposed`);
+        const now = new Date().toISOString();
+        const active = { ...m, status: "active", updated: now };
+        const prior = m.supersedes ? this.list().find((x) => x.id === m.supersedes) : undefined;
+        this.write(active);
+        if (prior && prior.status === "active") {
+            this.write({ ...prior, status: "superseded", supersededBy: m.id, updated: now });
+        }
+        return active;
+    }
+    /** Discard a proposed memory. */
+    reject(idOrRef) {
+        const m = this.resolveId(idOrRef);
+        if (m.status !== "proposed")
+            throw new Error(`${m.id} is ${m.status}, not proposed`);
+        fs.rmSync(this.file(m.id));
+        return m;
+    }
+    setStatus(idOrPrefix, status) {
+        const m = this.resolveId(idOrPrefix);
+        const next = { ...m, status, updated: new Date().toISOString() };
+        this.write(next);
+        return next;
+    }
+    /** Permanently delete a memory file. Prefer `setStatus(id, "archived")`. */
+    remove(idOrPrefix) {
+        const m = this.resolveId(idOrPrefix);
+        fs.rmSync(this.file(m.id));
+        return m;
+    }
+    write(m) {
+        fs.mkdirSync(this.dir, { recursive: true });
+        const target = this.file(m.id);
+        const tmp = `${target}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, serialize(m));
+        fs.renameSync(tmp, target);
+    }
+}
+function dedupe(xs) {
+    return [...new Set(xs.map((x) => x.trim()).filter(Boolean))];
+}
+function normalizeLink(p) {
+    return p.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+}
+export function openStore(start) {
+    const root = findRoot(start);
+    if (!root) {
+        throw new Error("no .memoryrail/ found in this directory or any parent. Run `memoryrail init` first.");
+    }
+    return new Store(root);
+}

package/dist/sync.d.ts

@@ -0,0 +1,20 @@
+import type { Store } from "./store.js";
+import type { Memory } from "./types.js";
+export declare const START = "<!-- memoryrail:start -->";
+export declare const END = "<!-- memoryrail:end -->";
+export interface Target {
+    path: string;
+    /** Text to place before the managed block when the file is created from scratch. */
+    preamble?: string;
+}
+export declare const DEFAULT_TARGETS: Target[];
+/** Deterministic: the same memories always render the same block, so `sync --check` is stable. */
+export declare function renderBlock(memories: Memory[]): string;
+export interface SyncChange {
+    path: string;
+    action: "created" | "updated" | "unchanged";
+}
+export declare function sync(store: Store, opts?: {
+    check?: boolean;
+    targets?: Target[];
+}): SyncChange[];

package/dist/sync.js

@@ -0,0 +1,81 @@
+import fs from "node:fs";
+import path from "node:path";
+import { refOf } from "./refs.js";
+export const START = "<!-- memoryrail:start -->";
+export const END = "<!-- memoryrail:end -->";
+export const DEFAULT_TARGETS = [
+    { path: "AGENTS.md" },
+    { path: "CLAUDE.md" },
+    {
+        path: ".cursor/rules/memoryrail.mdc",
+        preamble: "---\ndescription: Project memory managed by MemoryRail\nalwaysApply: true\n---\n\n",
+    },
+];
+const SECTIONS = [
+    { type: "constraint", heading: "Constraints" },
+    { type: "decision", heading: "Decisions" },
+    { type: "gotcha", heading: "Gotchas" },
+    { type: "attempt", heading: "Failed approaches (do not retry without a new reason)" },
+    { type: "thread", heading: "Open threads" },
+];
+const PER_SECTION = 25;
+function condense(body, max = 280) {
+    const flat = body.replace(/\s+/g, " ").trim();
+    return flat.length > max ? flat.slice(0, max - 1).trimEnd() + "…" : flat;
+}
+function byPriority(a, b) {
+    return Number(b.pinned) - Number(a.pinned) || Date.parse(b.updated) - Date.parse(a.updated) || a.id.localeCompare(b.id);
+}
+/** Deterministic: the same memories always render the same block, so `sync --check` is stable. */
+export function renderBlock(memories) {
+    const lines = [
+        START,
+        "## Project memory (managed by MemoryRail)",
+        "",
+        "_Generated from `.memoryrail/`. Do not edit between these markers: change the memories, then run `memoryrail sync`._",
+    ];
+    for (const { type, heading } of SECTIONS) {
+        const items = memories
+            .filter((m) => m.type === type && m.status === "active")
+            .sort(byPriority)
+            .slice(0, PER_SECTION);
+        if (!items.length)
+            continue;
+        lines.push("", `### ${heading}`);
+        for (const m of items) {
+            const detail = condense(m.body);
+            const files = m.links.length ? ` (files: ${m.links.join(", ")})` : "";
+            lines.push(`- [${refOf(m)}] **${m.title}**${detail ? ` — ${detail}` : ""}${files}`);
+        }
+    }
+    lines.push("", "How to use this memory:", "- Before changing code, run `memoryrail precheck \"<what you plan to do>\" --file <path>` (or the MCP `precheck` tool). Use `memoryrail recall \"<topic>\"` for detail.", "- Cite the memory you rely on as `[per DEC-xxxx]`. If your plan conflicts with a constraint or decision, stop and ask instead of proceeding.", "- Record new decisions, approaches that failed, and gotchas with `memoryrail remember`. Finish a session with `memoryrail handoff`.", END);
+    return lines.join("\n");
+}
+function applyBlock(existing, block, preamble = "") {
+    if (existing === null)
+        return `${preamble}${block}\n`;
+    const s = existing.indexOf(START);
+    const e = existing.indexOf(END);
+    if (s !== -1 && e > s)
+        return existing.slice(0, s) + block + existing.slice(e + END.length);
+    return existing.replace(/\s+$/, "") + `\n\n${block}\n`;
+}
+export function sync(store, opts = {}) {
+    const block = renderBlock(store.list());
+    const changes = [];
+    for (const t of opts.targets ?? DEFAULT_TARGETS) {
+        const abs = path.join(store.root, t.path);
+        const existing = fs.existsSync(abs) ? fs.readFileSync(abs, "utf8").replace(/\r\n/g, "\n") : null;
+        const next = applyBlock(existing, block, t.preamble);
+        if (existing === next) {
+            changes.push({ path: t.path, action: "unchanged" });
+            continue;
+        }
+        changes.push({ path: t.path, action: existing === null ? "created" : "updated" });
+        if (!opts.check) {
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, next);
+        }
+    }
+    return changes;
+}

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+export declare const MEMORY_TYPES: readonly ["decision", "constraint", "gotcha", "attempt", "thread", "session"];
+export type MemoryType = (typeof MEMORY_TYPES)[number];
+/** Durable knowledge: what review mode gates and what precheck checks against. */
+export declare const DURABLE_TYPES: readonly MemoryType[];
+export declare const STATUSES: readonly ["active", "proposed", "superseded", "archived", "resolved"];
+export type Status = (typeof STATUSES)[number];
+export interface Memory {
+    id: string;
+    type: MemoryType;
+    title: string;
+    status: Status;
+    created: string;
+    updated: string;
+    tags: string[];
+    /** Repo-relative paths this memory is about. Used for staleness checks. */
+    links: string[];
+    /** Pinned memories are always returned first by recall. */
+    pinned: boolean;
+    supersedes?: string;
+    supersededBy?: string;
+    body: string;
+}
+export interface NewMemory {
+    type: MemoryType;
+    title: string;
+    body?: string;
+    tags?: string[];
+    links?: string[];
+    pinned?: boolean;
+    supersedes?: string;
+    /** `proposed` waits for human approval and is invisible to recall and sync. Default `active`. */
+    status?: "active" | "proposed";
+    /** Skip the secret scan. For deliberate human use only; never exposed over MCP. */
+    allowSecrets?: boolean;
+}
+export declare function isMemoryType(v: unknown): v is MemoryType;
+export declare function isStatus(v: unknown): v is Status;

package/dist/types.js

@@ -0,0 +1,10 @@
+export const MEMORY_TYPES = ["decision", "constraint", "gotcha", "attempt", "thread", "session"];
+/** Durable knowledge: what review mode gates and what precheck checks against. */
+export const DURABLE_TYPES = ["decision", "constraint", "gotcha", "attempt"];
+export const STATUSES = ["active", "proposed", "superseded", "archived", "resolved"];
+export function isMemoryType(v) {
+    return typeof v === "string" && MEMORY_TYPES.includes(v);
+}
+export function isStatus(v) {
+    return typeof v === "string" && STATUSES.includes(v);
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** Read from package.json so the CLI, the MCP server and npm can never disagree. */
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,4 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+/** Read from package.json so the CLI, the MCP server and npm can never disagree. */
+export const VERSION = require("../package.json").version;