memoryrail 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,10 @@
 # MemoryRail
 
-**Git-native project memory for coding agents.**
+[![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.
 
@@ -45,14 +49,13 @@ Six types: `decision`, `constraint`, `gotcha`, `attempt` (tried and failed, with
 
 ## Install
 
-Not published to npm yet. From a clone:
+Needs Node 20 or newer.
 
 ```sh
-git clone https://github.com/OutVersus/memoryrail && cd memoryrail
-npm install && npm run build && npm link   # puts `memoryrail` on your PATH
+npm install -g memoryrail    # puts `memoryrail` on your PATH
 ```
 
-Once published, every `memoryrail ...` below can be run as `npx memoryrail ...`.
+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
 
@@ -69,6 +72,8 @@ git add .memoryrail AGENTS.md CLAUDE.md .mcp.json && git commit -m "Add project
 
 ## 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
@@ -116,7 +121,7 @@ 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]
+memoryrail sync [--check] [--also <path>]...
 memoryrail lint [--strict] [--no-git] [--json]
 memoryrail doctor
 memoryrail install <claude|cursor|all> [--npx]
@@ -156,7 +161,9 @@ memoryrail precheck --staged --fail || echo "Review the memories above before co
 - **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. Other MCP clients need the config added by hand (see above).
+- `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

package/dist/cli.js

@@ -11,7 +11,7 @@ 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 { sync } from "./sync.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
@@ -48,6 +48,8 @@ Commands:
   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
@@ -319,8 +321,9 @@ async function run(argv) {
             return 0;
         }
         case "sync": {
-            const { values } = parse({ check: { type: "boolean" } });
-            const changes = sync(openStore(), { check: values.check });
+            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}`);

package/dist/doctor.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { CLIENT_FILES, isInstalled } from "./install.js";
 import { lint } from "./lint.js";
-import { sync } from "./sync.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) {
@@ -42,6 +42,15 @@ export function doctor(store) {
         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(", ")}`);

package/dist/sync.d.ts

@@ -14,6 +14,8 @@ export interface SyncChange {
     path: string;
     action: "created" | "updated" | "unchanged";
 }
+/** Codex stops reading AGENTS.md after this many bytes by default (project_doc_max_bytes). */
+export declare const CODEX_DOC_LIMIT_BYTES: number;
 export declare function sync(store: Store, opts?: {
     check?: boolean;
     targets?: Target[];

package/dist/sync.js

@@ -60,11 +60,16 @@ function applyBlock(existing, block, preamble = "") {
         return existing.slice(0, s) + block + existing.slice(e + END.length);
     return existing.replace(/\s+$/, "") + `\n\n${block}\n`;
 }
+/** Codex stops reading AGENTS.md after this many bytes by default (project_doc_max_bytes). */
+export const CODEX_DOC_LIMIT_BYTES = 32 * 1024;
 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 abs = path.resolve(store.root, t.path);
+        if (!abs.startsWith(store.root + path.sep)) {
+            throw new Error(`refusing to write outside the repository: ${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) {

package/docs/CLIENTS.md

@@ -0,0 +1,163 @@
+# Connect your agent
+
+MemoryRail reaches an agent in two ways:
+
+1. **The MCP server** (`memoryrail serve`): the agent calls tools like `precheck`, `recall` and `remember`. This is the full experience.
+2. **Generated instruction files** (`memoryrail sync`): your rules, decisions and failed attempts are written into `AGENTS.md`, `CLAUDE.md` and `.cursor/rules/memoryrail.mdc`. Agents that read those files see the memory even without MCP, but can't write to it.
+
+Install the CLI first: `npm install -g memoryrail` (Node 20 or newer). Then pick your client below.
+
+> **How much of this is tested.** The server is tested with the official MCP SDK client over stdio, and the config shapes below were checked against each vendor's documentation (linked in each section, checked 2026-10-10). We have **not** run Codex or any Copilot surface against MemoryRail ourselves. If a snippet doesn't work, please open an issue with the client version and the error.
+
+## How the server finds your memory
+
+The server looks for `.memoryrail/` starting in the directory the client launches it in, then walks up. If your client launches servers somewhere else (a user-level config shared by many projects, or a cloud runner), point it at the repo:
+
+```
+memoryrail serve --root /path/to/repo
+```
+
+or set `MEMORYRAIL_ROOT=/path/to/repo` in the server's environment.
+
+## Claude Code
+
+```sh
+memoryrail install claude
+```
+
+This adds a `memoryrail` server to the project's `.mcp.json`, keeping any other servers. Restart Claude Code. `CLAUDE.md` is updated by `memoryrail sync`.
+
+## Cursor
+
+```sh
+memoryrail install cursor
+```
+
+This adds the server to `.cursor/mcp.json`. `memoryrail sync` also writes `.cursor/rules/memoryrail.mdc` (always applied).
+
+## OpenAI Codex
+
+Codex reads MCP servers from `~/.codex/config.toml`, or from `.codex/config.toml` in a project (trusted projects only). Add one with the CLI:
+
+```sh
+codex mcp add memoryrail -- memoryrail serve
+```
+
+or edit the TOML:
+
+```toml
+[mcp_servers.memoryrail]
+command = "memoryrail"
+args = ["serve"]
+```
+
+If you haven't installed MemoryRail globally, use `command = "npx"` and `args = ["-y", "memoryrail", "serve"]`. The server looks for `.memoryrail/` from the directory Codex launches it in (we haven't confirmed which directory that is for a user-level config), so for a single project you can pin it with `args = ["serve", "--root", "/path/to/repo"]`.
+
+**Instructions:** Codex reads `AGENTS.md` from the project root down to your working directory, which `memoryrail sync` writes. By default Codex **stops reading after 32 KiB** of combined instructions (`project_doc_max_bytes`), so a large memory can be silently cut off. `memoryrail doctor` warns when `AGENTS.md` passes 32 KiB; archive stale memories (`memoryrail forget <ref>`) or raise the limit in your Codex config.
+
+Sources: [Codex MCP](https://developers.openai.com/codex/mcp), [Codex AGENTS.md](https://developers.openai.com/codex/guides/agents-md).
+
+## GitHub Copilot
+
+Copilot has several surfaces, and they are configured differently.
+
+### Copilot in VS Code
+
+Create `.vscode/mcp.json` in the workspace. The top-level key is `servers` (not `mcpServers`):
+
+```json
+{
+  "servers": {
+    "memoryrail": {
+      "type": "stdio",
+      "command": "memoryrail",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+MCP tools are available in Copilot's agent mode. VS Code starts the server with the workspace folder as its working directory by default, so no `--root` is needed.
+
+Source: [VS Code MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).
+
+### Copilot CLI
+
+```sh
+copilot mcp add memoryrail -- memoryrail serve
+```
+
+This writes to `~/.copilot/mcp-config.json`. To configure it by hand, or per project in `.github/mcp.json`, the top-level key is `mcpServers` and each server has a `type`:
+
+```json
+{
+  "mcpServers": {
+    "memoryrail": {
+      "type": "local",
+      "command": "memoryrail",
+      "args": ["serve"],
+      "tools": ["*"]
+    }
+  }
+}
+```
+
+Copilot CLI can also read a project-level `.mcp.json`, but expects its own format. The entry that `memoryrail install claude` writes has no `type` field, which the Copilot CLI docs show, so use `copilot mcp add` or the JSON above for Copilot CLI instead of relying on that file.
+
+Source: [Adding MCP servers for GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers).
+
+### Copilot cloud agent (assigned issues and pull requests)
+
+The cloud agent doesn't read a file from your repo for MCP. A repository administrator pastes JSON into the repository's settings on GitHub.com (under Copilot, in the cloud/coding agent section; the exact menu name has changed between releases). `tools` is required:
+
+```json
+{
+  "mcpServers": {
+    "memoryrail": {
+      "type": "local",
+      "command": "npx",
+      "args": ["-y", "memoryrail", "serve"],
+      "tools": ["resume", "precheck", "recall", "list_memories"]
+    }
+  }
+}
+```
+
+Notes:
+
+- The cloud agent runs on GitHub's side, not on your machine, so MemoryRail isn't installed there. Use `npx`.
+- The example allows **read-only** tools. Add `"remember"` and `"handoff"` to let the agent write memory; its changes then appear in the pull request for you to review. Turning on `memoryrail config review agents` makes those writes wait for your approval.
+- The cloud agent supports MCP **tools** only, not resources or prompts. MemoryRail exposes tools only, so nothing is lost.
+- **Not verified:** which directory the cloud agent starts MCP servers in. If the server reports that it can't find `.memoryrail/`, add `"--root", "."` or the checkout path to `args`.
+
+Source: [Configure MCP servers for the Copilot cloud agent](https://docs.github.com/en/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp).
+
+### Copilot instructions
+
+- The Copilot cloud agent and Copilot CLI read `AGENTS.md` from the repository root, which `memoryrail sync` writes. ([Changelog](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/))
+- Copilot also reads **`.github/copilot-instructions.md`**. `sync` doesn't write that file by default. To have it written there too, add `--also`:
+
+  ```sh
+  memoryrail sync --also .github/copilot-instructions.md
+  ```
+
+  Pass the same flag to `sync --check` in CI. Existing content in that file is kept; MemoryRail only manages the block between its markers. ([Copilot custom instructions](https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot))
+
+## Any other MCP client
+
+Register this as a stdio server in the client's MCP config:
+
+```
+command: memoryrail
+args:    serve
+```
+
+Clients differ in file name and top-level key (`mcpServers` or `servers`) and some require a `type`; check the client's docs. If the client can't use MCP, the same commands work in a terminal (`memoryrail precheck "..." --file path`), and any tool that reads `AGENTS.md` still gets the summary from `memoryrail sync`.
+
+## Check it worked
+
+```sh
+memoryrail doctor
+```
+
+reports whether memory is valid, synced, and registered for Claude Code or Cursor (it doesn't detect Codex or Copilot config). To test the server itself, ask your agent to call `list_memories`; it should return the memories in the repo.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memoryrail",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Git-native project memory for coding agents. Plain Markdown in your repo, readable by people and any MCP-capable agent.",
   "license": "MIT",
   "type": "module",