RYSH.md and project notes: durable memory for a workspace

Your agent relearns your repo every morning. rysh gives it two markdown files instead — RYSH.md and .rysh-notes.md, versioned in git.

Every morning, your AI agent wakes up with amnesia.

It doesn't remember that this repo uses make test, never go test directly. It doesn't remember that the migrations folder is hand-off-limits, that deploys go through staging first, or that the flaky integration suite needs the local NATS container up. You told it. Yesterday. And the day before. Each session starts with the same expensive ritual: the agent rediscovering — or worse, guessing — how your project actually works.

The industry's reflex answer is "memory": opaque, vendor-hosted, per-account recollection that you can't read, diff, or take with you.

rysh's answer is two markdown files.

Two files, two jobs

RYSH.md — the workspace's long-term memory. This is where the durable stuff lives: conventions, the commands that actually work, the landmines. The agent reads it as standing context, and it can maintain it through the memory_edit tool. Crucially, an edit to memory goes through the same discipline as an edit to code — it's a visible tool call, shown preview-first as a coloured diff you approve before anything touches disk. The agent proposes what it learned; you decide whether that's true.

.rysh-notes.md — the shared running notebook. Managed via the project_notes tool, this is the cross-pane scratchpad: higher churn, lower ceremony. What the profiling agent in pane 2 discovered about the slow query is exactly what the refactoring agent in pane 4 needs to know before it touches the repository layer. Notes are how findings travel between panes without anyone re-explaining. (For structured, key-addressed handoffs there's the context tool; notes are the prose channel.)

Rule of thumb: RYSH.md is what you'd want a new hire to know on day one. .rysh-notes.md is what you'd tell a teammate at lunch.

Memory as code

Here's the part we think matters most: both files live in your repo. Which means agent memory inherits, for free, every tool your team already trusts for text that matters:

• git diff your agent's brain. What did it learn this week? That's a diff, not a mystery.
• Review memory like code. An agent proposes a RYSH.md change; it lands as a visible edit; a human approves it — in the pane, or in an actual PR. A "memory PR" is a genuinely useful artifact: the agent believes deploys can skip staging on Fridays — do we agree? Catching a wrong belief in review is cheap. Catching it after three weeks of confidently wrong behavior is not.
• Revert bad memories. git revert. Done. Try that with a vendor's memory blob.
• Share by default. Clone the repo, get the memory. Every teammate's agents — and every teammate — start from the same understanding. Onboarding docs and agent memory converge into the same file, which is what good docs always wanted to be anyway.

Contrast this with hosted memory features: unexportable, unauditable, scoped to one account, and gone when you leave the platform. Your team's accumulated operational knowledge is exactly the asset you should own outright. In rysh it's markdown in git, on your infrastructure — self-hostable end to end, with rysh running on Claude under your own API key.

Patterns that earn their keep

The end-of-task debrief. Finish a piece of work with: "Update RYSH.md with anything you'd want to know next time." Ten seconds of prompt; compounding returns. The second time an agent hits the flaky-suite problem, the fix is already in memory — you'll review the diff it proposes and, half the time, learn something yourself.

Notes as team radio. Long debugging session across multiple panes? Have each agent log findings to .rysh-notes.md as it goes. The notebook becomes a live incident timeline that humans and agents both read — and it's still there next week when someone asks "how did we fix that?"

The prune. Periodically: "Read RYSH.md and propose cuts — anything stale, redundant, or too obvious to state." Memory that only grows is a liability (more on that below).

Honest edges

• It's markdown, not a knowledge graph. No embeddings, no relevance ranking. The agent gets the file. For a workspace's operating knowledge, we think plain prose you can read is the feature — but if you're expecting semantic recall over ten thousand documents, this is not that tool.
• Memory informs; it doesn't compel. A model can still occasionally ignore an instruction that's plainly written down. Fewer, sharper lines get followed better than sprawling ones — which is one more reason curation beats accumulation.
• Every line is a context tax. RYSH.md rides along in the agent's context, and rysh's own tooling is context-budget-conscious for the same reason. A memory file that grows forever quietly eats the budget your actual task needed. Keep it tight; prune on schedule.

The amnesia problem was never really about the model. It was about where the knowledge lived — in chat scrollback, in your head, in a vendor's database. Put it in versioned files the whole team and all the agents share, and the morning ritual disappears: the agent wakes up, reads the file, and already knows not to touch the migrations.

We're recruiting design partners. If your team is tired of re-teaching agents the same repo every session, come shape how workspace memory should work: rysh.ai/design-partner

Related: context store / recall: passing state between agents · A todo list your agents actually share