Memory, Rules, Skills

Writing memories

What memories are, when to write them, and how to scope them so your assistant surfaces them at the right time.

A memory is a short markdown note your team writes down so the assistant can read it later. Memories live at a workspace path, and they only surface when the assistant is working under that path. They are the most common content type in Pathrule and the easiest to start with.

This page covers when to write a memory, how to structure it, and how scope and versioning work.

When to write a memory

Reach for a memory when you have a piece of knowledge that is not obvious from the code and is likely to come up again.

Decisions. "We use Postgres on Supabase for everything in this repo. Do not bring in an ORM. Use the supabase-js client directly."
Gotchas. "If you change the orders.status enum you must run the data migration before the schema migration. The order is reversed from the rest of the schema."
Postmortems. "On 2026-04-12 we shipped a webhook handler that double charged customers because we did not check the Stripe idempotency key. Always pass it now."
Conventions. "Tests live next to the file they test, not under a parallel __tests__ directory."
Tribal knowledge. "Only one person remembers why this flag exists. It is still required because of a runtime quirk in upstream."

Skip memories for things the code already says clearly, things that change weekly, or things that are entirely personal preference.

Structure

Every memory has a title and a markdown body. Keep both small.

Title: short, declarative, fits in a sidebar. "Postgres only. No ORM." beats "Notes on database access patterns".
Body: the smallest amount of markdown that makes the point. Bullets are usually clearer than paragraphs. Include one example if it helps.

There is no required template, but a useful default is:

The constraint or fact in one sentence.

Why:
- The reason this matters or the incident that prompted it.

How to apply:
- The concrete thing the assistant should do when the topic comes up.

Path scope

The path is half the memory. It decides where the memory surfaces.

A memory at /apps/api/payments surfaces for any work under apps/api/payments.
A memory at /apps/api surfaces for the whole api directory.
A memory at / surfaces everywhere in the workspace.

Pick the most specific path that still covers the cases you want. A workspace level memory about payments noise is worse than a payments folder memory about payments.

Versioning and concurrent edits

Every save returns a version token. The next save must carry that token, otherwise it conflicts. This protects your team from two people overwriting each other.

When the UI sees a conflict, it shows three options: keep mine, take theirs, or run a three way merge.
When the assistant tries to update via MCP, it gets a clear error and can either retry with the latest version or hand the conflict back to the user.

Conflicts are rare in practice because memories are usually small and focused, but the safety net is always on.

Who writes them

Humans writing in Pathrule Web or Pathrule Studio.
The assistant writing through the pathrule_write_memory MCP tool when the user asks it to save something. The runtime tags the source as claude (or the relevant client) so you can see which memories were AI authored.

Both sources land in the same place. The assistant reads what the human wrote, and the human reads what the assistant wrote.

Reading versus citing

The assistant usually sees only the memory title in the hook injected context. When it wants the full body it calls pathrule_read_memory with the id. This keeps the default payload small and lets the assistant pay for the bytes only when they matter.

When you read memories in the UI, you see both the title list and the bodies. The same index drives both surfaces.

Anti patterns

One huge "all my notes" memory. Split by topic and scope. Smaller and path scoped beats long and global every time.
Memories that say what the code already says. The assistant can read the code. Reserve memories for the why and the gotcha.
Stale memories. Update or delete them when the underlying decision changes. Pathrule's self-audit will flag obvious stale items, but a human eye is faster.