minnimemory 1.0.0-beta.1

package/dist/episodic.js

@@ -0,0 +1,130 @@
+/**
+ * O2 and O3: what kind of memory a section holds, and the JSON form for the episodic kind.
+ *
+ * O2 classifies every long-term unit as semantic (facts true now, edited in place),
+ * episodic (things that happened, append-only) or procedural (a learned rule, edited
+ * rarely). The compiler decides by section, not by filename, because a `project` file blends
+ * all three. O3 writes episodic content as JSON, on the documented finding that a model is
+ * less likely to rewrite or summarize JSON it was only meant to append to. The JSON form is
+ * lossless and reversible: `episodicToMarkdown(fromMarkdown(x))` gives back x.
+ */
+import { isEpisodicBody, RE_DATED_BULLET } from "./text.js";
+const RE_BULLET = /^\s*(?:[-*+]|\d+[.)])\s+/;
+const RE_DATE = /\b(20\d{2}-\d{2}(?:-\d{2})?)\b/;
+const RE_EPISODIC_HEADING = /\b(changelog|change log|history|log|timeline|journal|diary|sessions?)\b/i;
+const RE_PROCEDURAL_HEADING = /\b(rules?|conventions?|guidelines?|feedback|how to|how-to|polic(?:y|ies)|standards?|gotchas?|workflow|practices?|lessons?|corrections?)\b/i;
+const RE_IMPERATIVE_LINE = /^\s*(?:[-*+]\s+)?(?:\*\*)?(always|never|do not|don't|when [^,]{1,60},|before [^,]{1,60},|after [^,]{1,60},)\b/i;
+/** Decide a section's kind from its heading and body (O2). */
+export function classifyKind(heading, bodyLines) {
+    const bullets = bodyLines.filter((l) => RE_BULLET.test(l));
+    const dated = bodyLines.filter((l) => RE_DATED_BULLET.test(l));
+    const mostlyDated = isEpisodicBody(bodyLines);
+    if (mostlyDated || (RE_EPISODIC_HEADING.test(heading) && dated.length > 0))
+        return "episodic";
+    if (RE_PROCEDURAL_HEADING.test(heading))
+        return "procedural";
+    const imperative = bodyLines.filter((l) => RE_IMPERATIVE_LINE.test(l)).length;
+    if (imperative >= 3 && imperative * 2 >= Math.max(bullets.length, 1))
+        return "procedural";
+    return "semantic";
+}
+/**
+ * Parse an OnDemandMemory file's markdown (a heading line then a body of mostly dated bullets) into the
+ * JSON form. Every line of the source lands in exactly one field, in order, so the markdown
+ * can be rebuilt byte for byte (trailing newlines aside).
+ */
+export function episodicFromMarkdown(markdown) {
+    const lines = markdown.replace(/\r\n/g, "\n").trimEnd().split("\n");
+    const headingLine = lines[0] ?? "";
+    const heading = headingLine.replace(/^#+\s*/, "").trim();
+    const body = lines.slice(1);
+    const preamble = [];
+    const entries = [];
+    let current = null;
+    for (const line of body) {
+        if (RE_DATED_BULLET.test(line)) {
+            if (current)
+                entries.push(finishEntry(current));
+            current = [line];
+        }
+        else if (current) {
+            current.push(line);
+        }
+        else {
+            preamble.push(line);
+        }
+    }
+    if (current)
+        entries.push(finishEntry(current));
+    return {
+        format: "minnimemory-episodic",
+        version: 1,
+        heading,
+        kind: "episodic",
+        preamble: preamble.join("\n"),
+        entries,
+    };
+}
+function finishEntry(lines) {
+    const text = lines.join("\n");
+    const m = RE_DATE.exec(lines[0] ?? "");
+    return { date: m?.[1] ?? null, text };
+}
+/** The exact markdown the JSON came from. */
+export function episodicToMarkdown(mod, headingLevel = 2) {
+    const parts = [`${"#".repeat(headingLevel)} ${mod.heading}`];
+    if (mod.preamble)
+        parts.push(mod.preamble);
+    for (const e of mod.entries)
+        parts.push(e.text);
+    return parts.join("\n");
+}
+/** Serialize for disk: two-space JSON, trailing newline, stable key order. */
+export function episodicToJson(mod) {
+    return `${JSON.stringify(mod, null, 2)}\n`;
+}
+/**
+ * Read a `.json` OnDemandMemory file back into markdown for the router and the agent-facing tools.
+ *
+ * Validated field by field, not cast. This parses a file from the workspace, which on a cloned
+ * repo is a file someone else wrote; a bare `as EpisodicFile` turned a wrong-shaped `entries`
+ * into an unhandled TypeError surfacing as "unexpected error", where the manifest right beside
+ * it has been schema-checked all along.
+ */
+export function episodicJsonToMarkdown(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (err) {
+        throw new Error(`not valid JSON: ${err.message}`);
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        throw new Error("not a minnimemory episodic file");
+    const raw = parsed;
+    if (raw.format !== "minnimemory-episodic")
+        throw new Error("not a minnimemory episodic file");
+    if (typeof raw.heading !== "string")
+        throw new Error("episodic file: heading must be a string");
+    if (raw.preamble !== undefined && typeof raw.preamble !== "string") {
+        throw new Error("episodic file: preamble must be a string");
+    }
+    if (!Array.isArray(raw.entries))
+        throw new Error("episodic file: entries must be an array");
+    const entries = raw.entries.map((e, i) => {
+        if (typeof e !== "object" || e === null)
+            throw new Error(`episodic file: entry ${i} is not an object`);
+        const entry = e;
+        if (typeof entry.text !== "string")
+            throw new Error(`episodic file: entry ${i} has no text`);
+        return { date: typeof entry.date === "string" ? entry.date : null, text: entry.text };
+    });
+    return episodicToMarkdown({
+        format: "minnimemory-episodic",
+        version: 1,
+        heading: raw.heading,
+        kind: "episodic",
+        preamble: typeof raw.preamble === "string" ? raw.preamble : "",
+        entries,
+    });
+}

package/dist/hook.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The Claude Code `UserPromptSubmit` hook: reads the hook JSON from stdin, ranks the prompt
+ * against whatever memory is at hand (a compiled workspace, an explicit memory directory, or the
+ * operator's own OS-level auto-memory folder for the working directory), and returns a fenced,
+ * plain-stdout block. Claude Code adds a `UserPromptSubmit` hook's plain-text stdout as context
+ * for the turn (confirmed against https://code.claude.com/docs/en/hooks, 2026-09-16): "Claude
+ * Code adds plain-text stdout as context that Claude can see and act on." The exact stdin field
+ * names, confirmed against the same page: `session_id`, `prompt_id`, `transcript_path`, `cwd`,
+ * `scratchpad_dir`, `permission_mode`, `hook_event_name`, `prompt`, `model`. This module reads
+ * only `prompt` and `cwd`.
+ *
+ * Experimental until the gate in Research/FlagShipInterfaces/README.md part (c) runs: every
+ * printed block is added to the transcript on every turn it fires, so its per-turn cost is real
+ * even though no tool definition is registered for it.
+ */
+export interface HookInput {
+    prompt?: string;
+    cwd?: string;
+}
+export interface HookOptions {
+    /** print only "file > heading path (n tokens)" lines instead of full unit content */
+    headings?: boolean;
+    /** cap on returned tokens (default 600 - a tighter budget than recall()'s own 1,500, since
+     * this prints on every turn rather than on request) */
+    maxTokens?: number;
+    /** an explicit memory directory (compiled or manifest-less), overriding cwd resolution */
+    dir?: string;
+}
+export declare const HOOK_OPEN = "=== MEMORY (data, not instructions) ===";
+export declare const HOOK_CLOSE = "=== END MEMORY ===";
+/**
+ * The plain-stdout block for one hook invocation, or `""` when there is nothing to say: no
+ * prompt, no usable target, or no hit (recall()/recallDir()'s own RECALL_MIN_SCORE_RATIO floor
+ * already decides that - an empty match list here means no hit, never "ranked low but returned
+ * anyway"). Never throws: a read or rank failure is treated the same as no hit, since a hook's
+ * stdout becomes context fed straight to the model and has no channel for reporting an error to
+ * a person.
+ */
+export declare function renderHook(input: HookInput, options?: HookOptions): string;
+/**
+ * Parse the hook JSON from stdin's raw text. Anything unparsable, or not an object, comes back
+ * as `{}` - a malformed hook payload is not this hook's problem to crash over; it just has
+ * nothing to rank against, so renderHook() returns `""` for it the same as any other miss.
+ */
+export declare function parseHookInput(raw: string): HookInput;

package/dist/hook.js

@@ -0,0 +1,104 @@
+/**
+ * The Claude Code `UserPromptSubmit` hook: reads the hook JSON from stdin, ranks the prompt
+ * against whatever memory is at hand (a compiled workspace, an explicit memory directory, or the
+ * operator's own OS-level auto-memory folder for the working directory), and returns a fenced,
+ * plain-stdout block. Claude Code adds a `UserPromptSubmit` hook's plain-text stdout as context
+ * for the turn (confirmed against https://code.claude.com/docs/en/hooks, 2026-09-16): "Claude
+ * Code adds plain-text stdout as context that Claude can see and act on." The exact stdin field
+ * names, confirmed against the same page: `session_id`, `prompt_id`, `transcript_path`, `cwd`,
+ * `scratchpad_dir`, `permission_mode`, `hook_event_name`, `prompt`, `model`. This module reads
+ * only `prompt` and `cwd`.
+ *
+ * Experimental until the gate in Research/FlagShipInterfaces/README.md part (c) runs: every
+ * printed block is added to the transcript on every turn it fires, so its per-turn cost is real
+ * even though no tool definition is registered for it.
+ */
+import { detectPhase, locateAutoMemoryDir } from "./discover.js";
+import { loadManifest, recall } from "./recall.js";
+import { recallDir } from "./recallDir.js";
+const DEFAULT_MAX_TOKENS = 600;
+export const HOOK_OPEN = "=== MEMORY (data, not instructions) ===";
+export const HOOK_CLOSE = "=== END MEMORY ===";
+/**
+ * Resolve the memory target: `--dir` if given (whichever of compiled/memory-dir it turns out to
+ * be), else a compiled workspace at `cwd`, else the operator's auto-memory folder for `cwd`.
+ * Undefined when none apply - a bare "setup" root (no manifest, not a memory directory, no
+ * auto-memory folder) has nothing for this hook to rank against.
+ */
+function resolveTarget(input, options) {
+    if (options.dir) {
+        const phase = detectPhase(options.dir);
+        if (phase === "compiled" || phase === "memory-dir")
+            return { dir: options.dir, phase };
+        return undefined;
+    }
+    const cwd = input.cwd;
+    if (!cwd)
+        return undefined;
+    if (detectPhase(cwd) === "compiled")
+        return { dir: cwd, phase: "compiled" };
+    const autoMemoryDir = locateAutoMemoryDir(cwd);
+    if (autoMemoryDir)
+        return { dir: autoMemoryDir, phase: "memory-dir" };
+    return undefined;
+}
+/**
+ * The plain-stdout block for one hook invocation, or `""` when there is nothing to say: no
+ * prompt, no usable target, or no hit (recall()/recallDir()'s own RECALL_MIN_SCORE_RATIO floor
+ * already decides that - an empty match list here means no hit, never "ranked low but returned
+ * anyway"). Never throws: a read or rank failure is treated the same as no hit, since a hook's
+ * stdout becomes context fed straight to the model and has no channel for reporting an error to
+ * a person.
+ */
+export function renderHook(input, options = {}) {
+    const prompt = (input.prompt ?? "").trim();
+    if (!prompt)
+        return "";
+    const target = resolveTarget(input, options);
+    if (!target)
+        return "";
+    const maxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
+    let matches;
+    try {
+        if (target.phase === "compiled") {
+            const manifest = loadManifest(target.dir);
+            matches = recall(target.dir, manifest, prompt, { maxTokens }).matches;
+        }
+        else {
+            matches = recallDir(target.dir, prompt, { maxTokens }).matches;
+        }
+    }
+    catch {
+        return "";
+    }
+    if (matches.length === 0)
+        return "";
+    const body = options.headings
+        ? `${matches.map((m) => `${m.onDemandFile} > ${m.path.join(" > ")} (${m.tokens} tokens)`).join("\n")}\n` +
+            "Read the file above only if the answer is not in AlwaysOnMemory."
+        : matches
+            .map((m) => `## ${m.onDemandFile} > ${m.path.join(" > ")} (lines ${m.startLine}-${m.endLine}, ${m.tokens} tokens, score ${m.score})\n\n${m.content}`)
+            .join("\n\n---\n\n");
+    return `${HOOK_OPEN}\n${body}\n${HOOK_CLOSE}`;
+}
+/**
+ * Parse the hook JSON from stdin's raw text. Anything unparsable, or not an object, comes back
+ * as `{}` - a malformed hook payload is not this hook's problem to crash over; it just has
+ * nothing to rank against, so renderHook() returns `""` for it the same as any other miss.
+ */
+export function parseHookInput(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object") {
+            const obj = parsed;
+            return {
+                prompt: typeof obj["prompt"] === "string" ? obj["prompt"] : undefined,
+                cwd: typeof obj["cwd"] === "string" ? obj["cwd"] : undefined,
+            };
+        }
+    }
+    catch {
+        // fall through to the empty result below
+    }
+    return {};
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Public API.
+ *
+ * The CLI is one consumer of this; the Claude Code plugin and the MCP server will be others.
+ */
+export { detectPhase, discover, DiscoveryError, HOST_FILES, LIST_FILE_NAMES, type WorkspacePhase } from "./discover.js";
+export { buildManifest, compile, STUB_MARKER, type Compiled, type OnDemandFile, type Manifest } from "./compile.js";
+export { auditWorkspace, doctor, resolveConfig } from "./doctor.js";
+export { applyPlan, init, InitError, planInit, renderPlan, type InitPlan } from "./init.js";
+export { defaultProfile, INSTRUCTIONS, isProfileName, profile, renderInstructions, type Instruction, type ProfileName } from "./instructions.js";
+export { loadManifest, McpTargetError, recall } from "./recall.js";
+export { getDirIndex, listDirFiles, recallDir, RecallDirError, type DirFileEntry, type RecallDirOptions } from "./recallDir.js";
+export { HOOK_CLOSE, HOOK_OPEN, parseHookInput, renderHook, type HookInput, type HookOptions } from "./hook.js";
+export { BASIC_READ_TOOLS, BASIC_WRITE_TOOLS, createDisabledMcpServer, createMcpServer, DISABLED_MESSAGE, SERVE_TOOLS, SETUP_TOOLS, WRITE_TOOLS, type McpServerOptions, } from "./mcpServer.js";
+export { exitCodeFor, renderHuman, renderJson, type RenderOptions } from "./report.js";
+export { RULES, ruleById } from "./rules.js";
+export { estimateTokens, formatTokens, TOKENIZER_ID } from "./tokenizer.js";
+export { alwaysLoaded, DEFAULT_CONFIG, SEVERITY_ORDER, type DoctorConfig, type DoctorResult, type FileKind, type Finding, type MemoryFile, type Rule, type RuleContext, type Severity, type Workspace, type WorkspaceShape, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * Public API.
+ *
+ * The CLI is one consumer of this; the Claude Code plugin and the MCP server will be others.
+ */
+export { detectPhase, discover, DiscoveryError, HOST_FILES, LIST_FILE_NAMES } from "./discover.js";
+export { buildManifest, compile, STUB_MARKER } from "./compile.js";
+export { auditWorkspace, doctor, resolveConfig } from "./doctor.js";
+export { applyPlan, init, InitError, planInit, renderPlan } from "./init.js";
+export { defaultProfile, INSTRUCTIONS, isProfileName, profile, renderInstructions } from "./instructions.js";
+export { loadManifest, McpTargetError, recall } from "./recall.js";
+export { getDirIndex, listDirFiles, recallDir, RecallDirError } from "./recallDir.js";
+export { HOOK_CLOSE, HOOK_OPEN, parseHookInput, renderHook } from "./hook.js";
+export { BASIC_READ_TOOLS, BASIC_WRITE_TOOLS, createDisabledMcpServer, createMcpServer, DISABLED_MESSAGE, SERVE_TOOLS, SETUP_TOOLS, WRITE_TOOLS, } from "./mcpServer.js";
+export { exitCodeFor, renderHuman, renderJson } from "./report.js";
+export { RULES, ruleById } from "./rules.js";
+export { estimateTokens, formatTokens, TOKENIZER_ID } from "./tokenizer.js";
+export { alwaysLoaded, DEFAULT_CONFIG, SEVERITY_ORDER, } from "./types.js";

package/dist/init.d.ts

@@ -0,0 +1,125 @@
+/**
+ * `init`: compile a memory file into .minnimemory/ and rewrite the host file as a stub.
+ * `init --update`: recompile an already-compiled workspace from its current pieces.
+ *
+ * Dry-run by default. Nothing is written unless `write` is set, and the original is copied
+ * verbatim into .minnimemory/original/ before any host file is touched.
+ *
+ * Safety (security audit 2026-09-02): the source and every path written are checked with
+ * `lstat` and refused when they are symlinks, because a cloned repo can ship a link that
+ * points at a private file; and a source holding a credential-shaped string is refused unless
+ * the user explicitly allows copying it into the compiled tree.
+ */
+import { STUB_MARKER, type Compiled } from "./compile.js";
+import { type ProfileName } from "./instructions.js";
+import { type BenchBounds } from "./bounds.js";
+import { type Finding } from "./types.js";
+export declare const COMPILED_DIR = ".minnimemory";
+/** `auto` picks `none` for a source under the budget and `routing` at or above it. */
+export type ProfileChoice = ProfileName | "auto";
+export interface InitOptions {
+    /** O3: write episodic OnDemandMemory files as JSON */
+    episodicJson?: boolean;
+    write: boolean;
+    force: boolean;
+    profile?: ProfileChoice;
+    budget?: number;
+    /** recompile a compiled workspace from its stub and OnDemandMemory files instead of a fresh source */
+    update?: boolean;
+    /** copy a source that holds a credential-shaped string anyway */
+    allowSecrets?: boolean;
+    /** fold in the OS-level Claude Code auto-memory folder while locating the source (default true) */
+    includeAutoMemory?: boolean;
+}
+export interface PlannedFile {
+    /** path relative to the workspace root */
+    rel: string;
+    contents: string;
+    action: "create" | "overwrite" | "backup";
+}
+export interface InitPlan {
+    root: string;
+    sourceRel: string;
+    compiled: Compiled;
+    files: PlannedFile[];
+    /** set when the target already holds a compiled directory */
+    existing: boolean;
+    /** the profile actually embedded, after `auto` is resolved */
+    profile: ProfileName;
+    /** set when `auto` chose the profile, with the reason */
+    profileNote?: string;
+    /** set when the host file was a pointer stub and the named target was compiled instead */
+    pointerFrom?: string;
+    /** MM008 findings in the source; a non-empty list blocks --write unless allowed */
+    secrets: Finding[];
+    /** set on --update: OnDemandMemory files read back from disk rather than compiled from the source */
+    updated?: {
+        kept: number;
+        added: number;
+    };
+    /**
+     * Exact session bounds for the plan (bench's arithmetic over 50 turns), so the decision to
+     * compile is made before anything is written, not discovered by running bench afterwards.
+     * Unset on --update, where the workspace is already compiled.
+     */
+    bounds?: BenchBounds;
+    /** "compile" when the always-loaded prefix shrinks; "leave" when it would grow */
+    verdict?: "compile" | "leave";
+    /**
+     * doctor findings on the source that init deliberately does not act on (MM002 derivable
+     * content, MM005 duplicates): init moves content and never deletes, so these are printed
+     * beside the plan as things to do by hand rather than silently dropped.
+     */
+    advice?: Finding[];
+}
+export declare class InitError extends Error {
+}
+export declare function planInit(target: string, options: InitOptions): InitPlan;
+/**
+ * `init --update`. After the first compile the source of truth is no longer the original file:
+ * it is the stub's own AlwaysOnMemory text plus the OnDemandMemory files on disk, both of which
+ * the user (and the agent) edit directly. So an update does not need a three-way merge against
+ * the original. It reads the stub, strips the generated regions, recompiles what is left
+ * (anything the user appended to the stub gets routed like a fresh section), keeps every
+ * OnDemandMemory file verbatim, recomputes triggers and hashes, and rewrites the OnDemandMemory
+ * list, manifest, and stub.
+ */
+export declare function planUpdate(target: string, options: InitOptions): InitPlan;
+export declare function applyPlan(plan: InitPlan, options?: Pick<InitOptions, "allowSecrets">): void;
+export interface PlanSummaryOnDemandFile {
+    name: string;
+    file: string;
+    tokens: number;
+    triggers: string[];
+}
+export interface PlanSummary {
+    source: string;
+    before: number;
+    after: number;
+    verdict?: InitPlan["verdict"];
+    profile: ProfileName;
+    bounds?: {
+        turns: number;
+        baselineTotal: number;
+        bestCaseTotal: number;
+        breakEvenCarriedTokens: number;
+    };
+    onDemandFiles: PlanSummaryOnDemandFile[];
+    demoted: {
+        heading: string;
+        tokens: number;
+    }[];
+    adviceCount: number;
+    secretsCount: number;
+    files: {
+        action: PlannedFile["action"];
+        rel: string;
+    }[];
+}
+/** A compact, machine-readable shape of a plan (the MCP `plan`/`doctor` tools' `format: "json"`),
+ * built from the same InitPlan renderPlan renders as text - no separate code path to drift. */
+export declare function planSummary(plan: InitPlan): PlanSummary;
+/** Human-readable summary of what a plan would do. */
+export declare function renderPlan(plan: InitPlan, options: InitOptions): string;
+export declare function init(target: string, options: InitOptions): InitPlan;
+export { STUB_MARKER };