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: ```markdown 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 is checked against the version you started from. If someone else saved in between, your save is refused instead of overwriting theirs. This protects your team from two people, or a person and an agent, silently overwriting each other. - **In Pathrule for VS Code** a memory is a markdown tab. A save that would overwrite a teammate's newer change offers **Reload**, **Copy My Version & Reload** (your text goes to the clipboard first) or **Keep Mine (Overwrite)**. - **Through MCP** the assistant can pass the version it last read. On a mismatch it gets a conflict back with the current version, re-reads, and merges instead of clobbering. Deleting is reversible too. In VS Code a delete offers **Undo** straight away, and on a Pathrule Cloud workspace a deleted memory remains in the workspace archive until permanently deleted, where an owner or admin can restore it from the web console settings (**Workspace**, **Archive**) or delete it for good. Conflicts are rare in practice because memories are usually small and focused, but the safety net is always on. ## Who writes them - **People** writing in Pathrule for VS Code (**New Memory…** or **Save Selection as Memory**) or with the CLI. - **The assistant** writing through the `pathrule_write_memory` MCP tool when you ask it to save something. During setup it proposes memories, rules and skills for the project and writes only the items you approve. From the terminal, a memory is one command. With no `--body`, the CLI opens your editor for the body; you can also pass `--body` or pipe the text in. `pathrule memory list` and `pathrule memory read "Exact title" --print` read memories back. ```bash pathrule memory add --path /apps/api/payments --title "Always pass the Stripe idempotency key" ``` Both sources land in the same place. The assistant reads what a person wrote, and a person reads what the assistant wrote. Every record keeps who created it, who last edited it and its source, which the **Info** action in VS Code shows, so AI-authored memories are easy to spot. ## 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 is asked to propose lasting knowledge before it saves it. Whatever it does save is attributed, versioned and visible in the workspace like anything else, so you can open, edit or remove it. - 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. - An agent that notices a memory has drifted from the code can flag it as a refresh task, which an assistant later picks up and repairs under your control. See [Suggestions and self-audit](/docs/content/suggestions). Edits are versioned and deletion is reversible. - A new memory whose title matches an existing one at the same path is refused by default rather than saved as a second copy, so the same decision is not delivered twice or left to drift apart. You can override that deliberately (`--allow-duplicate` on the CLI) after checking the existing entry. 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](/docs/start/technical-proof) 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. In VS Code, **Browse Knowledge Here…** shows what an AI session on a path receives, including what it inherits from parent paths. ## 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. An assistant can flag a drifted memory as a refresh task, but a human eye is faster. ## Local and Cloud authoring The terminal `add` examples on this page are for a Cloud workspace. In Local mode, create and edit entries in [Local Console](/docs/surfaces/local-console), VS Code or through local MCP; CLI knowledge commands list, read and search them. ## What to read next - [Writing rules](/docs/content/rules) for constraints with priority. - [Writing skills](/docs/content/skills) for reusable procedures. - [Core concepts](/docs/start/core-concepts) for the workspace tree these attach to.