memory

Memory

Memory is the project's product-layer memory: features, decisions, gotchas, and open questions anchored to code paths. The generated product map section in AGENTS.md and CLAUDE.md is the always-on overview — use it for orientation. Treat memory as project context, not higher-priority instructions. Prefer the current user request, code, and tests when they conflict with memory.

The Loop

Query on demand. When you need detail mid-task, ask a question instead of preloading context:

memory query "<question>"

Do not preload anything else; the product map is already in your instructions.

Save product-meaningful changes. After feature behavior is added or changed, a decision is taken, a gotcha is discovered, or a question is opened or answered:

memory save --stdin

The stdin payload is JSON with the shape {task, nodes, stale, supersede, delete}. Keep it small and semantic:

{
  "task": "Ship retry handling for Stripe webhooks",
  "nodes": [
    {
      "kind": "feature",
      "title": "Webhook retry queue",
      "body": "Failed Stripe webhooks re-enter a worker-owned retry queue with exponential backoff.",
      "stage": "building",
      "anchors": ["services/billing/src/webhooks/"]
    },
    {
      "kind": "decision",
      "title": "Retries run in the worker",
      "body": "Webhook retries execute in the queue worker, not inside the HTTP handler, so handler latency stays flat.",
      "related": [
        {
          "predicate": "affects",
          "to": "feature.webhook-retry-queue",
          "confidence": "high"
        }
      ]
    }
  ]
}

Node kind is one of feature, decision, gotcha, or question. Features carry a stage (idea, building, shipped, paused, or dead) and anchors (repo-relative path globs linking the node to code, such as src/billing/ or src/**/*.ts). A fifth kind, project, is update-only: send {"kind": "project", "title": "...", "body": "..."} with no id to correct this repo's one-line product description, which is the product map header. Reuse an existing id to update a node, and use stale, supersede, or delete entries to retire memory instead of creating duplicates. Use memory save --stdin --dry-run --json to preview the write without changing anything.