Your AI agent already tried that.

MemoryRail keeps your project's decisions, failed attempts and rules as plain Markdown in the repo. Before your coding agent changes code, it checks them, so it doesn't repeat yesterday's mistake.

Install See how it works

Open source, MIT licensed. Version 0.1: early, so expect rough edges.

agent session (illustrative)precheck output is real

agent  I'll cache the gallery images on disk to speed things up.
$ 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.
 
agent  [per ATT-f485] Skipping the disk cache.
       Resizing on request instead.

Every session starts from zero

A coding agent doesn't remember last week. It reopens decisions you already settled, retries approaches that already failed, and breaks rules nobody wrote down where it could see them. You re-explain the project every time.

MemoryRail gives the project a memory. It is a folder in your repo, .memoryrail/, with one small Markdown file per memory. Agents read and write it through an MCP server or the command line. You review it in git, like any other change.

There is no database, no account and no server. Delete the folder and it's gone; commit it and it travels with every clone and branch.

.memoryrail/memories/20261010-caching-images-locally-violates-the-provider-tos.md

---
id: "20261010-caching-images-locally-…"
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 kinds of memory

Each one has a different job, so an agent can tell a rule from a story.

Memory types
decision	A choice that was made, and why.	Use Drizzle over Prisma: edge deploys need a small runtime.
constraint	A rule to follow. Pin it and it always applies.	Never commit .env files.
gotcha	A trap that already bit someone.	Stripe webhooks need the raw body.
attempt	An approach that was tried and failed, with the reason.	Caching images locally violates the provider TOS.
thread	Unfinished work or an open question.	Finish the auth migration.
session	What a session did and what comes next.	Set up the DB layer. Next: migrations, seed data.

One session, start to finish

Start: get briefed

The agent asks for a summary of where things stand: the last session, open threads, the rules, recent decisions and known traps.
```
$ memoryrail resume
```
Before changing code: check

The agent says what it plans to do and which files it will touch. MemoryRail returns the rules, failed attempts, gotchas and decisions that apply, most binding first. The agent cites them as [per DEC-a3f9] and stops to ask if its plan conflicts.
```
$ memoryrail precheck "move auth to sessions" --file src/auth
```
While working: record

When the agent decides something, hits a trap, or watches an approach fail, it writes that down. A new decision can replace an old one; the old one is kept as history, not overwritten.
```
$ memoryrail remember "Sessions over JWTs" --type decision --supersedes DEC-91c2
```
Finish: hand off

The agent leaves a short note: what it did and what's next. The next session, with any agent, starts from it.
```
$ memoryrail handoff --summary "Token table done" --next "Wire up logout"
```

Your agent talks to MemoryRail through an MCP server (memoryrail serve) with eight tools, or runs the same commands in a terminal. memoryrail sync also writes the current rules and decisions into AGENTS.md, CLAUDE.md and Cursor rules, so tools that don't speak MCP still see them.

Memory you can trust enough to act on

Bad memory is worse than none. These parts exist so the memory stays correct, safe and yours.

You review it like code

Every memory is a file, so every change shows up in the git diff and the pull request. Turn on the review gate and anything an agent writes waits for memoryrail approve before it takes effect.
Secrets are refused

Memory gets committed and replayed to models, so MemoryRail rejects text that looks like a private key, cloud or API token, or a password assignment. It names the rule that matched, never the value.
Stale memory gets flagged

A memory can point at the files it's about. If a file is deleted, or changed in git after the memory was written, memoryrail lint tells you to take another look.
History is kept

Changing your mind creates a new decision that supersedes the old one. Nothing is silently overwritten, and you can see what was believed and when.
One source for every agent

Keep one memory instead of three config files. sync keeps AGENTS.md, CLAUDE.md and Cursor rules current, and sync --check fails CI when they drift.
Local by default

No account, no server, no network calls. The MCP server talks to your agent over standard input and output on your own machine.

Other tools do parts of this

You have options. These open-source projects are close to MemoryRail, and we borrowed ideas from all three. Here is how each describes itself, and what we do differently.

Project	What it is	License
agent-memory	Go. Markdown in your repo with an MCP interface. Agent changes are staged, shown as a diff and applied after review. Scans for secrets and PII before writing.	Apache-2.0
projectmem	Python. A log of issues, attempts, fixes and decisions in `.projectmem/`, with an MCP server and a warning before an agent repeats an approach that already failed. Includes dashboards.	MIT
Memory Trail	A method with Markdown templates and a Claude skill, not a command-line tool. Records why decisions were made, with numbered decision ids and session logs.	CC BY 4.0

What MemoryRail does differently. One file per memory, so edits to different memories never touch the same file. Short refs like DEC-a3f9 that are derived from the id, so two branches can't hand out the same number. Decisions that supersede each other with history kept. Staleness checks against git. A published format spec and JSON Schema so other tools can read and write the same files. TypeScript on Node, no other runtime.

These are summaries from each project's own documentation. They change fast, so check the source. If we've got something wrong, tell us.

Try it in five minutes

You need Node 20 or newer. Install from npm, or run any command with npx memoryrail and skip the install.

Install
```
npm install -g memoryrail
```

Add memory to your project

# inside your own repo
memoryrail init
memoryrail remember "Use Drizzle over Prisma" --type decision --link src/db.ts
memoryrail remember "Never commit .env files" --type constraint --pin

Connect your agent

This adds MemoryRail to Claude Code's project config. Use cursor for Cursor, or all for both. Restart the client afterwards.
```
memoryrail install claude
memoryrail sync
memoryrail doctor
```

Commit it

git add .memoryrail AGENTS.md CLAUDE.md .mcp.json && git commit -m "Add project memory"

Questions

Does it send my code or memory anywhere?

No. MemoryRail makes no network calls. The CLI reads and writes files in your repo, and the MCP server talks to your agent over standard input and output on your machine. Your memory leaves only when you push it to a remote yourself.

How is this different from writing it all in CLAUDE.md?

A single instructions file is fine for a few rules, but it grows into a wall of text with no search, no history, no way to see what's out of date and no distinction between a rule and a story. MemoryRail keeps each memory separate and typed, checks them against your code, and still writes the important ones into CLAUDE.md and AGENTS.md for you.

What if an agent writes something wrong?

You'll see it in the diff like any other change. For more control, run memoryrail config review agents. Decisions, constraints, gotchas and failed attempts written by an agent then wait as proposals, and are ignored by search and sync until you approve them. A wrong memory can also be archived or superseded.

How does search work?

It matches words, ranked by relevance with a small boost for recent memories. It does not understand synonyms, so a search for "database" won't find a memory that only says "Postgres". Write titles that state the conclusion in the words you'd search for, and add tags. This is deliberate: it keeps MemoryRail small and fully offline, with nothing extra to install.

Will it cause merge conflicts?

Rarely. Each memory is its own file, so two branches only conflict if they edit the same memory. The generated block in AGENTS.md is rebuilt from the memories, so on a conflict you can resolve the memories and run memoryrail sync again.

Which agents does it work with?

Any agent that speaks MCP can use the server directly. memoryrail install sets that up for Claude Code and Cursor, and the setup guide covers OpenAI Codex and GitHub Copilot (VS Code, the CLI and the cloud agent). Those two come from the vendors' documentation; we haven't run them ourselves yet. Tools that read AGENTS.md get the generated summary but can't call the tools. Anything else can run the command-line commands.

Can other tools use the format?

Yes, that's the point of publishing it. Read the format spec and the JSON Schema.

Your AI agent already tried that.

Every session starts from zero

Six kinds of memory

One session, start to finish

Start: get briefed

Before changing code: check

While working: record

Finish: hand off

Memory you can trust enough to act on

You review it like code

Secrets are refused

Stale memory gets flagged

History is kept

One source for every agent

Local by default

Other tools do parts of this

Try it in five minutes

Install

Add memory to your project

Connect your agent

Commit it

Questions