memoryrail 0.0.0-stage → 0.1.1

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/docs/SPEC.md

@@ -0,0 +1,109 @@
+# MemoryRail format, version 1
+
+MemoryRail stores project memory as plain files in a repository so that people, git, and any AI coding agent can read and write it. This document is the contract. Tools that follow it interoperate, whether or not they use this package.
+
+## Layout
+
+```
+.memoryrail/
+  config.json              { "version": 1, "review": "off" }
+  memories/
+    20261010-use-drizzle-over-prisma.md
+    20261010-session-2026-10-10-17-30.md
+```
+
+A repository is a MemoryRail project if it contains `.memoryrail/config.json`. Tools locate the nearest one by walking up from the working directory.
+
+## Memory files
+
+One memory per file, named `<id>.md`. A file is YAML frontmatter followed by a free-form Markdown body.
+
+```markdown
+---
+id: "20261010-use-drizzle-over-prisma"
+type: "decision"
+title: "Use Drizzle over Prisma"
+status: "active"
+created: "2026-10-10T17:30:00.000Z"
+updated: "2026-10-10T17:30:00.000Z"
+tags: ["db"]
+links: ["src/db"]
+---
+
+Edge deploys need a small runtime, and Prisma's engine is too large.
+```
+
+Writers SHOULD encode every frontmatter value as JSON (which is valid YAML) so that files parse identically everywhere. Readers MUST accept any valid YAML scalar or flow sequence for these fields. The JSON Schema is at [`spec/memory.schema.json`](../spec/memory.schema.json).
+
+### Fields
+
+| Field | Required | Meaning |
+|---|---|---|
+| `id` | yes | Unique id. MUST equal the file name without `.md`. By convention `YYYYMMDD-slug`. |
+| `type` | yes | One of `decision`, `constraint`, `gotcha`, `attempt`, `thread`, `session`. |
+| `title` | yes | One line. State the conclusion, not the topic. |
+| `status` | yes | `active`, `proposed`, `superseded`, `archived`, or `resolved`. |
+| `created`, `updated` | yes | ISO 8601 timestamps. |
+| `tags` | no | Free-form labels. |
+| `links` | no | Repo-relative POSIX paths the memory is about. Used for staleness detection. MUST NOT escape the repository. |
+| `pinned` | no | If `true`, always surfaced first. Use sparingly. |
+| `supersedes` | no | Id of the memory this one replaces. |
+| `superseded_by` | no | Id of the memory that replaced this one. Set on the old memory. |
+
+Unknown fields MUST be preserved by tools that rewrite files.
+
+### Types
+
+- **decision**: a choice that was made and why. Treated as settled unless superseded.
+- **constraint**: a rule to follow (conventions, things not to touch).
+- **gotcha**: a mistake made once that should not be repeated.
+- **attempt**: an approach that was tried and **failed**, with why. Surfaced by `precheck` so nobody retries it without a new reason.
+- **thread**: unfinished work or an open question. Becomes `resolved` when done.
+- **session**: an end-of-session handoff: what was done and the next steps.
+
+### Lifecycle
+
+- Memories are never silently overwritten. To change a decision, create a new memory with `supersedes` set. The old one becomes `superseded` and gets `superseded_by`. Both stay in the repository, and git keeps the rest of the history.
+- `archived` means "wrong or no longer relevant"; `resolved` applies to threads.
+- `proposed` means written by an agent and **waiting for a human**. See Review gate.
+- Only `active` memories are returned by default and written into generated agent files.
+
+## Short refs
+
+Every memory has a short, citable handle: a three-letter type prefix and four hex characters of the SHA-1 of its `id`, e.g. `DEC-a3f9`. Prefixes: `DEC` decision, `CON` constraint, `GOT` gotcha, `ATT` attempt, `THR` thread, `SES` session. Refs are **derived, never stored**, so two branches cannot allocate the same one. Tools MUST accept a ref wherever an id is accepted, and MUST report an ambiguity instead of guessing if two memories share a ref.
+
+## Review gate
+
+`config.json` may set `"review": "agents"`. Then durable memories (`decision`, `constraint`, `gotcha`, `attempt`) written by an agent are saved with `status: "proposed"` and are ignored by recall, precheck and sync until a human approves them (`status: "active"`) or rejects them (file deleted). A proposal with `supersedes` does **not** change the superseded memory until approval. The default is `"off"`: agent writes are active immediately and are reviewed in git like any change.
+
+## Secrets
+
+Memory is committed and replayed into model context, so tools MUST refuse to write text that looks like a credential (private keys, cloud and API tokens, URL credentials, `password=...` style assignments) and SHOULD report which rule matched without echoing the value. A human-only override is allowed. Linters SHOULD flag existing files that match.
+
+## Precheck
+
+Given a plan (free text) and/or the files about to change, `precheck` returns the active `constraint`, `attempt`, `gotcha` and `decision` memories that apply, most binding first. A memory applies if it is a pinned constraint, if one of its `links` is the changed path or a directory containing it, or if its text matches the plan. Agents are instructed to cite what they rely on as `[per REF]` and to stop and ask if a plan conflicts with a constraint or decision.
+
+## Generated agent files
+
+`memoryrail sync` writes a managed block into `AGENTS.md`, `CLAUDE.md`, and `.cursor/rules/memoryrail.mdc`:
+
+```
+<!-- memoryrail:start -->
+...generated, deterministic...
+<!-- memoryrail:end -->
+```
+
+Content outside the markers is never modified. The block lists active memories with their refs, followed by short usage instructions (precheck first, cite refs, stop on conflict, record failures). It is a pure function of the memories, with no timestamps, so `memoryrail sync --check` can fail CI when it is out of date.
+
+## Staleness
+
+For each `active` memory and each entry in `links`:
+
+- the path does not exist: `stale-link` (warning)
+- the path's last git commit is newer than the memory's `updated`: `maybe-stale` (warning)
+- the path resolves outside the repository: `link-outside-repo` (error)
+
+## Versioning
+
+`config.json` carries `version`. Version 1 is this document. Breaking changes will increment it.

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "memoryrail",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "homepage": "https://memoryrail.si",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OutVersus/memoryrail.git"
+  },
+  "keywords": [
+    "mcp",
+    "ai-agents",
+    "memory",
+    "claude-code",
+    "cursor",
+    "agents-md",
+    "context"
+  ],
+  "bin": {
+    "memoryrail": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "spec",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "bugs": {
+    "url": "https://github.com/OutVersus/memoryrail/issues"
+  }
+}

package/spec/memory.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://memoryrail.si/spec/memory.schema.json",
+  "title": "MemoryRail memory (frontmatter)",
+  "description": "Schema for the frontmatter of a file in .memoryrail/memories/. Format version 1.",
+  "type": "object",
+  "required": ["id", "type", "title", "status", "created", "updated"],
+  "additionalProperties": true,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9._-]+$",
+      "description": "Must equal the file name without .md."
+    },
+    "type": { "enum": ["decision", "constraint", "gotcha", "attempt", "thread", "session"] },
+    "title": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["active", "proposed", "superseded", "archived", "resolved"] },
+    "created": { "type": "string", "format": "date-time" },
+    "updated": { "type": "string", "format": "date-time" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "links": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Repo-relative POSIX paths. Must not escape the repository."
+    },
+    "pinned": { "type": "boolean" },
+    "supersedes": { "type": "string" },
+    "superseded_by": { "type": "string" }
+  }
+}