memoryrail 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MemoryRail contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,197 @@
-# Temporary Holding Version
+# MemoryRail
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/memoryrail)](https://www.npmjs.com/package/memoryrail)
+[![CI](https://github.com/OutVersus/memoryrail/actions/workflows/ci.yml/badge.svg)](https://github.com/OutVersus/memoryrail/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Git-native project memory for coding agents.** Website: [memoryrail.si](https://memoryrail.si)
+
+Decisions, constraints, gotchas and failed attempts live in your repo as plain Markdown. People can read and review them in a PR. Any agent that speaks MCP (Claude Code, Cursor, Codex, Copilot, Aider, ...) can read and write them, and gets warned before it repeats a mistake.
+
+- **Warns before a mistake repeats.** `memoryrail precheck` takes what an agent is about to do and the files it will touch, and returns the rules, failed attempts, gotchas and decisions that apply.
+- **Plain files, no database.** `.memoryrail/memories/*.md`, one memory per file. Diff it, grep it, review it.
+- **Travels with the repo.** Clone it and the memory comes along. Branches carry their own memory.
+- **One source, every agent.** `memoryrail sync` keeps `AGENTS.md`, `CLAUDE.md` and `.cursor/rules` in step, so you maintain one memory instead of three config files.
+- **Safe to commit.** Text that looks like a secret is refused. An optional review gate holds agent-written memories until you approve them.
+- **Local and private.** No account, no server, no network calls.
+- **Stays honest.** Memories link to files; `memoryrail lint` flags the ones whose files changed or vanished. New decisions *supersede* old ones instead of overwriting them.
+
+> Status: **0.1, early.** The format is specified ([docs/SPEC.md](docs/SPEC.md)) and may change before 1.0.
+
+## What it looks like
+
+```
+$ memoryrail precheck "cache images on disk" --file src/images/a.ts
+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.
+
+- [CON-5413] (constraint) Never commit .env files — pinned rule
+- [ATT-f485] (attempt) Caching images locally violates the provider TOS — about
+  src/images/a.ts; matches your plan
+    We cached originals to speed up the gallery. Provider flagged it; had to purge.
+```
+
+Each memory is a small file you can read and edit by hand:
+
+```markdown
+---
+id: "20261010-caching-images-locally-violates-the-provider-tos"
+type: "attempt"
+title: "Caching images locally violates the provider TOS"
+status: "active"
+links: ["src/images"]
+---
+
+We cached originals to speed up the gallery. The provider flagged it and we had to purge.
+```
+
+Six types: `decision`, `constraint`, `gotcha`, `attempt` (tried and failed, with why), `thread` (unfinished work), `session` (end-of-session handoff).
+
+## Install
+
+Needs Node 20 or newer.
+
+```sh
+npm install -g memoryrail    # puts `memoryrail` on your PATH
+```
+
+Or run any command without installing, as `npx memoryrail <command>`. Note that `memoryrail install` registers the server as the command `memoryrail`, so that needs the global install; use `memoryrail install claude --npx` to register `npx -y memoryrail serve` instead.
+
+## Quick start
+
+```sh
+memoryrail init
+memoryrail remember "Use Drizzle over Prisma" --type decision \
+  --body "Edge deploys need a small runtime." --link src/db.ts
+memoryrail remember "Never commit .env files" --type constraint --pin
+memoryrail sync            # writes AGENTS.md, CLAUDE.md, .cursor/rules/memoryrail.mdc
+memoryrail install claude  # registers the MCP server in .mcp.json (or: cursor, all)
+memoryrail doctor          # checks that everything is valid, safe, synced and wired up
+git add .memoryrail AGENTS.md CLAUDE.md .mcp.json && git commit -m "Add project memory"
+```
+
+## Connect an agent (MCP)
+
+Setup for **Claude Code, Cursor, OpenAI Codex and GitHub Copilot** (VS Code, CLI and the cloud agent) is in [docs/CLIENTS.md](docs/CLIENTS.md). The short version for Claude Code and Cursor:
+
+```sh
+# Claude Code or Cursor, written into the repo's own config (keeps other servers)
+memoryrail install claude      # .mcp.json
+memoryrail install cursor      # .cursor/mcp.json
+```
+
+Or by hand in any MCP client config (Claude Desktop, ...):
+
+```json
+{
+  "mcpServers": {
+    "memoryrail": { "command": "memoryrail", "args": ["serve"] }
+  }
+}
+```
+
+The server uses the nearest `.memoryrail/` above its working directory, or pass `--root <path>`.
+
+| Tool | Use |
+|---|---|
+| `resume` | Call first in a session: last handoff, open threads, constraints, recent decisions, gotchas |
+| `precheck` | Call before changing code: the rules, failed attempts, gotchas and decisions that apply to a plan or files |
+| `recall` | Search memory for what you are about to work on (token-budgeted) |
+| `remember` | Record a decision, constraint, gotcha, failed attempt or thread; `supersedes` replaces an old one |
+| `handoff` | Call last: what was done and the next steps |
+| `list_memories`, `forget`, `resolve_thread` | Housekeeping |
+
+## The workflow
+
+1. **Start:** the agent calls `resume` (or you run `memoryrail resume` and paste the output).
+2. **Work:** it calls `precheck` before changing code, `recall "<area>"` for detail, and `remember` when it decides something, hits a trap, or watches an approach fail. It cites what it relies on as `[per DEC-a3f9]` and stops to ask if its plan conflicts with a constraint or decision.
+3. **Finish:** it calls `handoff` with a summary and next steps.
+4. **Review:** memory changes show up in the git diff like any other change. `memoryrail sync` and `memoryrail lint` run in CI.
+
+## CLI
+
+```
+memoryrail init
+memoryrail remember <title> [--type decision|constraint|gotcha|attempt|thread|session] [--body ..] [--stdin]
+                            [--tag ..] [--link <path>] [--pin] [--supersedes <id>] [--propose]
+memoryrail precheck [plan] [--file <path>]... [--staged] [--fail] [--json]
+memoryrail recall [query] [--type ..] [--limit n] [--budget tokens] [--all] [--json]
+memoryrail list | show <id> | resolve <id> | forget <id> [--delete]
+memoryrail review | approve <id>... [--all] | reject <id>...
+memoryrail config review [off|agents]
+memoryrail handoff --summary <text> [--next <step>]... [--title ..] [--link ..]
+memoryrail resume
+memoryrail sync [--check] [--also <path>]...
+memoryrail lint [--strict] [--no-git] [--json]
+memoryrail doctor
+memoryrail install <claude|cursor|all> [--npx]
+memoryrail serve [--root <path>]
+```
+
+Anywhere an id is accepted you can use the id, any unambiguous prefix, or the short ref shown in output (`DEC-a3f9`).
+
+### Review gate
+
+By default an agent's memories are active immediately and you review them in git. For more control:
+
+```sh
+memoryrail config review agents
+```
+
+Now decisions, constraints, gotchas and failed attempts written over MCP are saved as *proposed*. They are ignored by `recall`, `precheck` and `sync` until you run `memoryrail review` and then `approve` or `reject`. A proposal that supersedes an older memory leaves it untouched until approved.
+
+### Git hook
+
+`precheck --staged --fail` exits 3 when a staged file has a relevant failed attempt, gotcha or decision. Pinned rules alone never fail it.
+
+```sh
+# .git/hooks/pre-commit
+memoryrail precheck --staged --fail || echo "Review the memories above before committing." >&2
+```
+
+### CI
+
+```yaml
+- run: npx memoryrail sync --check   # generated agent files are up to date
+- run: npx memoryrail lint --strict  # no stale links, duplicates, secrets or broken files
+```
+
+## Limitations
+
+- **Search is lexical** (BM25 over title, tags, links and body, with a mild recency boost). It has no synonym or semantic matching, so `recall "database"` will not find a memory that only says "Postgres". Write titles that state the conclusion in the words you would search for, and use tags. Optional embeddings are planned.
+- `maybe-stale` relies on git history; it is skipped outside a git repository.
+- **The secret scanner is a pattern check, not a guarantee.** It catches common key formats and `password = ...` assignments, and it will miss secrets in unusual shapes. Treat it as a safety net, and don't paste credentials into memory.
+- `install` configures Claude Code and Cursor only. For Codex and Copilot, follow [docs/CLIENTS.md](docs/CLIENTS.md); those snippets come from the vendors' documentation and haven't been run against MemoryRail by us.
+- Codex stops reading `AGENTS.md` after 32 KiB by default. `memoryrail doctor` warns when yours gets that large.
+- This is an early release (0.x). The format and commands may change before 1.0, and it has had little use on real projects so far. Please open issues.
+- The memory is only as good as what agents and people record. MemoryRail makes recording cheap and reviewable; it does not do it for you.
+
+## Library
+
+```ts
+import { openStore, recall, precheck, sync } from "memoryrail";
+
+const store = openStore();
+store.add({ type: "gotcha", title: "Run migrations before seeding" });
+console.log(recall(store.list(), { query: "migrations" }).rendered);
+console.log(precheck(store.list(), { plan: "seed the database", files: ["db/seed.ts"] }).rendered);
+sync(store);
+```
+
+## Credits
+
+MemoryRail borrows ideas, not code, from three open-source projects: [projectmem](https://github.com/riponcm/projectmem) (warn before a failed approach is repeated; a doctor command), [agent-memory](https://github.com/xChuCx/agent-memory) (a human review gate, secret scanning, one-command client setup) and [Memory Trail](https://github.com/frmoretto/memory-trail) (short citable decision ids, "stop if it conflicts"). Look at them too; they take different approaches.
+
+## Contributing
+
+```sh
+npm install
+npm test
+npm run build
+```
+
+Issues and PRs welcome. Changes to the on-disk format must update [docs/SPEC.md](docs/SPEC.md) and the JSON Schema.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,367 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { doctor } from "./doctor.js";
+import { stagedFiles } from "./git.js";
+import { handoffToMemory, resumePrompt } from "./handoff.js";
+import { CLIENT_FILES, installMcp } from "./install.js";
+import { lint } from "./lint.js";
+import { precheck } from "./precheck.js";
+import { refOf } from "./refs.js";
+import { recall, renderMemory } from "./search.js";
+import { Store, DIR_NAME, initRoot, openStore, writeConfig } from "./store.js";
+import { DEFAULT_TARGETS, sync } from "./sync.js";
+import { VERSION } from "./version.js";
+import { isMemoryType, MEMORY_TYPES } from "./types.js";
+const HELP = `memoryrail ${VERSION} — git-native project memory for coding agents
+
+Usage: memoryrail <command> [options]
+
+Commands:
+  init                         Create .memoryrail/ in the current directory
+  remember <title>             Record a memory
+      --type <t>                 ${MEMORY_TYPES.join(" | ")} (default: decision)
+      --body <text>              Details (or --stdin to read from stdin)
+      --tag <t>                  Repeatable
+      --link <path>              Repo file this is about (repeatable); enables staleness checks
+      --pin                      Always include in recall and sync
+      --supersedes <id>          Replace an earlier memory, keeping its history
+      --propose                  Save as proposed; takes effect after \`approve\`
+      --allow-secrets            Skip the secret scan (humans only)
+  precheck [plan]              Before acting: which rules, failed attempts and gotchas apply?
+      --file <path>              Repeatable   --staged (use files staged in git)
+      --fail                     Exit 3 if anything relevant is found (for git hooks)   --json
+  recall [query]               Search memories, ranked and token-budgeted
+      --type <t>                 Repeatable filter
+      --limit <n>   --budget <tokens>   --all (include superseded/archived)   --json
+  list                         List memories (--type, --all, --json)
+  show <id>                    Print one memory (id, prefix, or ref like DEC-a3f9)
+  review                       Show memories waiting for approval
+  approve <id>... | --all      Accept proposed memories
+  reject <id>...               Discard proposed memories
+  config [review [off|agents]] Show or set the review gate for agent-written memories
+  resolve <id>                 Mark a thread resolved
+  forget <id>                  Archive a memory (--delete to remove the file)
+  handoff                      Record an end-of-session summary
+      --summary <text>  (or --stdin)   --title <t>   --next <step> (repeatable)   --link <path>
+  resume                       Print a prompt that brings a fresh agent up to speed
+  sync                         Write AGENTS.md, CLAUDE.md and .cursor/rules from memory
+      --check                    Exit 1 if generated files are out of date (for CI)
+      --also <path>              Also write the block into this file (repeatable), e.g.
+                                 .github/copilot-instructions.md
+  lint                         Find stale links, duplicates, and broken files
+      --strict                   Treat warnings as errors   --no-git   --json
+  doctor                       Health check: valid, safe, synced, and reachable by agents
+  install <claude|cursor|all>  Register the MCP server in the repo's client config (--npx)
+  serve                      Run the MCP server over stdio
+
+Run from anywhere inside a repo; the nearest .memoryrail/ is used.
+Docs: https://memoryrail.si`;
+class UsageError extends Error {
+}
+function readStdin() {
+    return fs.readFileSync(0, "utf8");
+}
+function parseTypes(values) {
+    if (!values?.length)
+        return undefined;
+    return values.map((v) => {
+        if (!isMemoryType(v))
+            throw new UsageError(`unknown type "${v}". Use one of: ${MEMORY_TYPES.join(", ")}`);
+        return v;
+    });
+}
+function toInt(v, name) {
+    if (v === undefined)
+        return undefined;
+    const n = Number(v);
+    if (!Number.isInteger(n) || n <= 0)
+        throw new UsageError(`--${name} must be a positive integer`);
+    return n;
+}
+function out(s) {
+    process.stdout.write(s.endsWith("\n") ? s : s + "\n");
+}
+function line(m) {
+    const status = m.status === "active" ? "" : ` [${m.status}]`;
+    return `${refOf(m).padEnd(8)} ${m.type.padEnd(10)} ${m.title}${status}`;
+}
+async function run(argv) {
+    const [cmd, ...rest] = argv;
+    if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+        out(HELP);
+        return 0;
+    }
+    if (cmd === "--version" || cmd === "-v") {
+        out(VERSION);
+        return 0;
+    }
+    const parse = (options) => parseArgs({ args: rest, options, allowPositionals: true, strict: true });
+    switch (cmd) {
+        case "init": {
+            const { created } = initRoot(process.cwd());
+            out(created ? `Created ${DIR_NAME}/ — try: memoryrail remember "Use X over Y" --type decision` : `${DIR_NAME}/ already exists`);
+            return 0;
+        }
+        case "remember": {
+            const { values, positionals } = parse({
+                type: { type: "string" },
+                body: { type: "string" },
+                stdin: { type: "boolean" },
+                tag: { type: "string", multiple: true },
+                link: { type: "string", multiple: true },
+                pin: { type: "boolean" },
+                supersedes: { type: "string" },
+                propose: { type: "boolean" },
+                "allow-secrets": { type: "boolean" },
+            });
+            const title = positionals.join(" ").trim();
+            if (!title)
+                throw new UsageError('usage: memoryrail remember "<title>" [--type decision] [--body ...]');
+            const type = parseTypes([values.type ?? "decision"])[0];
+            const body = values.stdin ? readStdin() : values.body;
+            const m = openStore().add({
+                type,
+                title,
+                body,
+                tags: values.tag,
+                links: values.link,
+                pinned: values.pin,
+                supersedes: values.supersedes,
+                status: values.propose ? "proposed" : "active",
+                allowSecrets: values["allow-secrets"],
+            });
+            out(m.status === "proposed"
+                ? `Proposed ${m.type} ${refOf(m)}: ${m.id}\nIt takes effect after \`memoryrail approve ${refOf(m)}\`.`
+                : `Saved ${m.type} ${refOf(m)}: ${m.id}`);
+            return 0;
+        }
+        case "precheck": {
+            const { values, positionals } = parse({
+                file: { type: "string", multiple: true },
+                staged: { type: "boolean" },
+                fail: { type: "boolean" },
+                json: { type: "boolean" },
+            });
+            const store = openStore();
+            const files = [...(values.file ?? []), ...(values.staged ? stagedFiles(store.root) : [])];
+            const plan = positionals.join(" ");
+            if (!plan.trim() && !files.length) {
+                throw new UsageError('usage: memoryrail precheck "<what you plan to do>" [--file <path>]... | --staged');
+            }
+            const result = precheck(store.list(), { plan, files });
+            out(values.json ? JSON.stringify(result.warnings.map((w) => ({ ref: refOf(w.memory), reasons: w.reasons, memory: w.memory })), null, 2) : result.rendered);
+            // Pinned rules are always listed; they alone must not fail a hook, or every commit would be blocked.
+            const specific = result.warnings.some((w) => w.reasons.some((r) => r !== "pinned rule"));
+            return values.fail && specific ? 3 : 0;
+        }
+        case "review": {
+            parse({});
+            const proposed = openStore()
+                .list()
+                .filter((m) => m.status === "proposed")
+                .sort((a, b) => Date.parse(a.created) - Date.parse(b.created));
+            if (!proposed.length) {
+                out("Nothing waiting for review.");
+                return 0;
+            }
+            out(proposed.map((m) => `${renderMemory(m)}${m.supersedes ? `\n_would supersede: ${m.supersedes}_` : ""}`).join("\n\n"));
+            out(`\n${proposed.length} waiting. \`memoryrail approve <ref>\` to accept, \`memoryrail reject <ref>\` to discard.`);
+            return 0;
+        }
+        case "approve": {
+            const { values, positionals } = parse({ all: { type: "boolean" } });
+            const store = openStore();
+            const ids = values.all ? store.list().filter((m) => m.status === "proposed").map((m) => m.id) : positionals;
+            if (!ids.length)
+                throw new UsageError("usage: memoryrail approve <id|ref>... | --all");
+            for (const id of ids) {
+                const m = store.approve(id);
+                out(`Approved ${refOf(m)}: ${m.title}`);
+            }
+            return 0;
+        }
+        case "reject": {
+            const { positionals } = parse({});
+            if (!positionals.length)
+                throw new UsageError("usage: memoryrail reject <id|ref>...");
+            const store = openStore();
+            for (const id of positionals)
+                out(`Rejected ${store.reject(id).title}`);
+            return 0;
+        }
+        case "config": {
+            const { positionals } = parse({});
+            const store = openStore();
+            const [key, value] = positionals;
+            if (!key) {
+                out(JSON.stringify(store.config(), null, 2));
+                return 0;
+            }
+            if (key !== "review")
+                throw new UsageError(`unknown setting "${key}". Available: review`);
+            if (value === undefined) {
+                out(store.config().review);
+                return 0;
+            }
+            if (value !== "off" && value !== "agents")
+                throw new UsageError("review must be `off` or `agents`");
+            writeConfig(store.root, { ...store.config(), review: value });
+            out(value === "agents"
+                ? "Review gate on: decisions, constraints, gotchas and failed attempts written by agents over MCP wait for `memoryrail approve`."
+                : "Review gate off: agent-written memories take effect immediately (review them in git).");
+            return 0;
+        }
+        case "doctor": {
+            parse({});
+            const checks = doctor(openStore());
+            const mark = { ok: "ok  ", warn: "warn", fail: "FAIL" };
+            for (const c of checks)
+                out(`${mark[c.status]}  ${c.name.padEnd(10)} ${c.detail}`);
+            return checks.some((c) => c.status === "fail") ? 1 : 0;
+        }
+        case "install": {
+            const { values, positionals } = parse({ npx: { type: "boolean" } });
+            const target = positionals[0];
+            const clients = target === "all" ? Object.keys(CLIENT_FILES) : target && target in CLIENT_FILES ? [target] : [];
+            if (!clients.length)
+                throw new UsageError(`usage: memoryrail install <${Object.keys(CLIENT_FILES).join("|")}|all> [--npx]`);
+            const store = openStore();
+            for (const c of clients) {
+                const r = installMcp(store.root, c, { npx: values.npx });
+                out(`${r.action}: ${r.file}`);
+            }
+            out("Restart the client so it picks up the new MCP server.");
+            return 0;
+        }
+        case "recall": {
+            const { values, positionals } = parse({
+                type: { type: "string", multiple: true },
+                limit: { type: "string" },
+                budget: { type: "string" },
+                all: { type: "boolean" },
+                json: { type: "boolean" },
+            });
+            const result = recall(openStore().list(), {
+                query: positionals.join(" "),
+                types: parseTypes(values.type),
+                limit: toInt(values.limit, "limit"),
+                budget: toInt(values.budget, "budget"),
+                includeInactive: values.all,
+            });
+            if (values.json) {
+                out(JSON.stringify(result.hits.map((h) => h.memory), null, 2));
+            }
+            else {
+                out(result.rendered || "No matching memories.");
+                if (result.truncated)
+                    out("\n(more results available: raise --limit or --budget)");
+            }
+            return 0;
+        }
+        case "list": {
+            const { values } = parse({ type: { type: "string", multiple: true }, all: { type: "boolean" }, json: { type: "boolean" } });
+            const types = parseTypes(values.type);
+            const items = openStore()
+                .list()
+                .filter((m) => (values.all || m.status === "active") && (!types || types.includes(m.type)))
+                .sort((a, b) => Date.parse(b.updated) - Date.parse(a.updated));
+            out(values.json ? JSON.stringify(items, null, 2) : items.length ? items.map(line).join("\n") : "No memories yet.");
+            return 0;
+        }
+        case "show": {
+            const { positionals } = parse({});
+            if (!positionals[0])
+                throw new UsageError("usage: memoryrail show <id>");
+            out(renderMemory(openStore().resolveId(positionals[0])));
+            return 0;
+        }
+        case "resolve": {
+            const { positionals } = parse({});
+            if (!positionals[0])
+                throw new UsageError("usage: memoryrail resolve <id>");
+            const store = openStore();
+            const target = store.resolveId(positionals[0]);
+            if (target.type !== "thread")
+                throw new UsageError(`only threads can be resolved; ${target.id} is a ${target.type}`);
+            out(`Resolved ${store.setStatus(target.id, "resolved").id}`);
+            return 0;
+        }
+        case "forget": {
+            const { values, positionals } = parse({ delete: { type: "boolean" } });
+            if (!positionals[0])
+                throw new UsageError("usage: memoryrail forget <id> [--delete]");
+            const store = openStore();
+            if (values.delete)
+                out(`Deleted ${store.remove(positionals[0]).id}`);
+            else
+                out(`Archived ${store.setStatus(store.resolveId(positionals[0]).id, "archived").id}`);
+            return 0;
+        }
+        case "handoff": {
+            const { values } = parse({
+                summary: { type: "string" },
+                stdin: { type: "boolean" },
+                title: { type: "string" },
+                next: { type: "string", multiple: true },
+                link: { type: "string", multiple: true },
+                tag: { type: "string", multiple: true },
+            });
+            const summary = values.stdin ? readStdin() : values.summary;
+            if (!summary?.trim())
+                throw new UsageError('usage: memoryrail handoff --summary "what you did" [--next "step"]...');
+            const m = openStore().add(handoffToMemory({ title: values.title, summary, next: values.next, links: values.link, tags: values.tag }));
+            out(`Recorded handoff: ${m.id}\nNext session: run \`memoryrail resume\` for a prompt.`);
+            return 0;
+        }
+        case "resume": {
+            parse({});
+            out(resumePrompt(openStore().list()));
+            return 0;
+        }
+        case "sync": {
+            const { values } = parse({ check: { type: "boolean" }, also: { type: "string", multiple: true } });
+            const targets = [...DEFAULT_TARGETS, ...(values.also ?? []).map((p) => ({ path: p }))];
+            const changes = sync(openStore(), { check: values.check, targets });
+            const pending = changes.filter((c) => c.action !== "unchanged");
+            for (const c of changes)
+                out(`${values.check && c.action !== "unchanged" ? "out of date" : c.action}: ${c.path}`);
+            if (values.check && pending.length) {
+                process.stderr.write("Generated files are out of date. Run `memoryrail sync` and commit the result.\n");
+                return 1;
+            }
+            return 0;
+        }
+        case "lint": {
+            const { values } = parse({ strict: { type: "boolean" }, "no-git": { type: "boolean" }, json: { type: "boolean" } });
+            const issues = lint(openStore(), { git: !values["no-git"] });
+            if (values.json)
+                out(JSON.stringify(issues, null, 2));
+            else if (!issues.length)
+                out("No issues found.");
+            else
+                for (const i of issues)
+                    out(`${i.severity.padEnd(7)} ${i.rule.padEnd(20)} ${i.id ?? i.file ?? ""}  ${i.message}`);
+            const failing = issues.some((i) => i.severity === "error" || (values.strict && i.severity === "warning"));
+            return failing ? 1 : 0;
+        }
+        case "serve": {
+            const { values } = parse({ root: { type: "string" } });
+            const root = values.root ? path.resolve(values.root) : undefined;
+            const { serveStdio } = await import("./mcp.js");
+            await serveStdio(root ? new Store(root) : openStore());
+            return -1; // keep the process alive; the transport owns it now
+        }
+        default:
+            throw new UsageError(`unknown command "${cmd}". Run \`memoryrail help\`.`);
+    }
+}
+run(process.argv.slice(2)).then((code) => {
+    if (code >= 0)
+        process.exitCode = code;
+}, (err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`memoryrail: ${msg}\n`);
+    process.exitCode = err instanceof UsageError ? 2 : 1;
+});

package/dist/doctor.d.ts

@@ -0,0 +1,8 @@
+import { type Store } from "./store.js";
+export interface Check {
+    status: "ok" | "warn" | "fail";
+    name: string;
+    detail: string;
+}
+/** One-shot health report: is memory present, valid, safe, synced and reachable by agents? */
+export declare function doctor(store: Store): Check[];

package/dist/doctor.js

@@ -0,0 +1,64 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CLIENT_FILES, isInstalled } from "./install.js";
+import { lint } from "./lint.js";
+import { CODEX_DOC_LIMIT_BYTES, sync } from "./sync.js";
+import { DIR_NAME, FORMAT_VERSION } from "./store.js";
+/** One-shot health report: is memory present, valid, safe, synced and reachable by agents? */
+export function doctor(store) {
+    const checks = [];
+    const add = (status, name, detail) => checks.push({ status, name, detail });
+    const config = store.config();
+    if (config.version === FORMAT_VERSION)
+        add("ok", "format", `${DIR_NAME}/ uses format version ${config.version}`);
+    else
+        add("fail", "format", `config says version ${config.version}; this tool reads version ${FORMAT_VERSION}`);
+    const { memories, errors } = store.loadAll();
+    if (errors.length)
+        add("fail", "files", `${errors.length} unreadable memory file(s); run \`memoryrail lint\``);
+    else
+        add("ok", "files", `${memories.length} memor${memories.length === 1 ? "y" : "ies"}, all valid`);
+    const issues = lint(store);
+    const secrets = issues.filter((i) => i.rule === "secret");
+    if (secrets.length)
+        add("fail", "secrets", `${secrets.length} memory file(s) look like they contain a secret; remove it and rotate the credential`);
+    else
+        add("ok", "secrets", "no secrets detected");
+    const otherErrors = issues.filter((i) => i.severity === "error" && i.rule !== "secret" && i.rule !== "invalid-file");
+    const warnings = issues.filter((i) => i.severity === "warning");
+    if (otherErrors.length)
+        add("fail", "integrity", `${otherErrors.length} error(s); run \`memoryrail lint\``);
+    else if (warnings.length)
+        add("warn", "freshness", `${warnings.length} warning(s) (stale links, duplicates); run \`memoryrail lint\``);
+    else
+        add("ok", "freshness", "no stale links or duplicates");
+    const proposed = memories.filter((m) => m.status === "proposed").length;
+    if (proposed)
+        add("warn", "review", `${proposed} proposed memor${proposed === 1 ? "y is" : "ies are"} waiting; run \`memoryrail review\``);
+    else
+        add("ok", "review", config.review === "agents" ? "review gate on, nothing waiting" : "review gate off (agent writes go live; review them in git)");
+    const drift = sync(store, { check: true }).filter((c) => c.action !== "unchanged");
+    if (drift.length)
+        add("warn", "sync", `${drift.map((d) => d.path).join(", ")} out of date; run \`memoryrail sync\``);
+    else
+        add("ok", "sync", "AGENTS.md, CLAUDE.md and Cursor rules are up to date");
+    try {
+        const bytes = fs.statSync(path.join(store.root, "AGENTS.md")).size;
+        if (bytes > CODEX_DOC_LIMIT_BYTES) {
+            add("warn", "size", `AGENTS.md is ${Math.round(bytes / 1024)} KiB; Codex stops reading it after 32 KiB by default. Archive stale memories or raise project_doc_max_bytes`);
+        }
+    }
+    catch {
+        /* no AGENTS.md yet; the sync check above already says so */
+    }
+    const wired = Object.keys(CLIENT_FILES).filter((c) => isInstalled(store.root, c));
+    if (wired.length)
+        add("ok", "agents", `MCP server registered for: ${wired.join(", ")}`);
+    else
+        add("warn", "agents", "no MCP client configured in this repo; run `memoryrail install claude` or `install cursor`");
+    if (fs.existsSync(path.join(store.root, ".git")))
+        add("ok", "git", "inside a git repository");
+    else
+        add("warn", "git", "not a git repository; memory will not be versioned or reviewable");
+    return checks;
+}