Writing memories

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 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.

How memory quality stays reviewable

Pathrule keeps a memory narrow and inspectable through several independent controls:

• General documentation is offered during setup rather than imported automatically. Live instruction files, their import chain, tool rules and decision records have stronger evidence that they are active knowledge.
• An agent proposes lasting knowledge and writes it only after approval.
• Path scope limits where the entry can surface, and an entry outside the current path still has to clear the relevance floor.
• Measured usage may reorder qualifying entries, but it cannot lift an unrelated memory past that floor.
• Self-audit raises stale, conflicting, unused or path-invalid entries for review. Edits are versioned and deletion is reversible.

The resulting operating model is a small set of narrow, reviewable decisions and gotchas, not a large archive copied into the workspace. See How Pathrule proves hard claims for the full technical contract.

Reading versus citing

The most relevant memories arrive as full bodies the assistant can act on directly. Less certain candidates arrive as titles with ids; the assistant reads one in full with pathrule_read_memory before relying on it. This keeps uncertain material out of the default payload without turning strong matches into extra round trips.

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.

What to read next

• Writing rules for constraints with priority.
• Writing skills for reusable procedures.
• Core concepts for the workspace tree these attach to.