Memory Store

Use Memory Store for durable project knowledge, not transient scratch work. Treat stored memories as reviewable project notes that may be read by future agents and humans.

Never manually read, write, edit, rename, delete, migrate, or repair files inside .memory-store except through the Memory Store MCP tools. Always use the MCP server for reading and writing memories, including initialization, search, get, new, update, and delete. Do not use shell commands, scripts, filesystem APIs, or direct text edits as a shortcut around the MCP interface.

This skill is mandatory for project work. Always use it when researching a project, applying code edits, changing behavior, or validating a fix. Before making assumptions or edits, search Memory Store for relevant context with terms from the project, component, file path, feature, error, or user request. If relevant memories exist, read them before acting.

Keep notes small and focused. Prefer one durable fact, decision, convention, or debugging result per note, roughly one paragraph at most. This is a lenient guideline rather than a byte limit, but if a note needs multiple sections, long excerpts, or a full explanation, split it into smaller memories or put it in committed project docs instead.

Workflow

1. Search before researching or editing. Use search with the project term, component, file path, feature, decision, or error text to find relevant context before applying code changes.
2. If the project is not initialized yet, run init once before creating, updating, or searching memories. Treat missing .memory-store/metadata.toml as not initialized.
3. Read exact candidates with get before updating them.
4. Use new to create a paragraph-sized atomic note; Memory Store generates the Cuid2 key.
5. Use returned or searched keys only as opaque identifiers for get and update.
6. Use update for existing notes with expected_revision from get or search.
7. Delete or repurpose outdated, duplicate, or over-broad notes through MCP tools instead of leaving misleading memory behind.
8. When a feature or meaningful code change is complete, create or update a memory that says what changed, why it was done that way, who requested it, and what reason or goal the request served.
9. During the work, note down useful context that future humans, operators, or agents should know.
10. Keep notes concise, factual, and scoped to the project.

Tool Semantics

• init {}: create .memory-store and metadata for the current project. Run this when the project has no .memory-store/metadata.toml; it is safe to rerun.
• new { content, tags? }: create a new note with a generated Cuid2 key. It fails when the project is not initialized; run init first.
• get { key }: fetch a note's Markdown body, metadata, path, and revision.
• update { key, expected_revision, operations }: edit the body only. It fails if the note is missing, the revision changed, or a replace operation is ambiguous.
• delete { key, expected_revision }: delete a note after confirming the current revision. Use this for outdated, duplicate, or misleading notes that should not remain discoverable.
• search { query, limit?, offset? }: search notes using FFF-backed content and fuzzy search.

Keys are opaque identifiers, not taxonomy. Use FFF search, note content, and tags for discovery; use returned keys only to read or update exact notes.

If MCP tools are unavailable, report that Memory Store is unavailable in the current session and ask for the MCP server to be installed or configured. Do not emulate Memory Store by editing .memory-store files directly.

Updates

Prefer exact structured edits:

{
  "key": "generated-cuid2-key-from-get-or-search",
  "expected_revision": "revision-from-get",
  "operations": [
    {
      "op": "replace",
      "old": "Plaintext storage is probably fine.",
      "new": "Plaintext Markdown is the canonical storage format."
    },
    {
      "op": "append",
      "text": "\n\nSearch indexes are cache-only and may be rebuilt.\n"
    }
  ]
}

Do not use fuzzy or best-effort edits. If an exact replace fails, read the note again and produce a new precise operation.

When a memory is outdated, first decide whether it should be repurposed or deleted. Repurpose with update when the same durable fact still exists but needs correction. Delete with delete when the note is obsolete, duplicated, misleading, too broad to salvage, or belongs in committed docs instead.

What To Store

Store:

• Paragraph-sized project decisions and rationale
• Local setup facts and commands that were verified
• Debugging outcomes with exact symptoms and fixes
• Repo conventions that are not obvious from code
• Durable implementation notes future agents should honor
• Completed feature notes: what changed, why it was done that way, who requested it, and the request's reason or goal
• Useful operator context for later humans, such as deployment caveats, local workflows, operational gotchas, release steps, and non-obvious constraints

Do not store:

• Secrets, tokens, credentials, private keys, or personal data
• Temporary task checklists
• Unverified guesses
• Large notes, full docs, large logs, or copied source files
• Information that belongs in committed docs instead

When a note records uncertainty, say so directly and include what evidence would verify it.