project-memory

Project Memory

Retrieval policy: memory is mandatory for non-trivial planning, architecture, recurring bugs, policy decisions and project-history questions. If skipped, state the supervibe-retrieval-decision-policy reason explicitly.

Design Memory Taxonomy

Design intelligence writes only accepted, rejected, or learned decisions into existing memory categories. Use tags such as design, brand, ux, a11y, tokens, prototype, slides, collateral, and rejected. Do not create a separate design memory root.

When to invoke

BEFORE starting any non-trivial task — feature, bug fix, refactor, design decision. Especially BEFORE invoking supervibe:brainstorming or supervibe:writing-plans.

This skill is the library card catalog for the project's accumulated wisdom. Without consulting it, every task starts from zero — that's wasted effort across the lifetime of the project.

Expert Operating Standard

Follow docs/references/skill-expert-operating-standard.md: start from source of truth, preserve retrieval evidence, apply scope safety, use real producers with runtime receipts for durable delegated outputs, verify before completion claims, and keep confidence below gate when evidence is partial.

Step 0 — Read source of truth (required)

1. Verify .supervibe/memory/ exists; if not, propose supervibe:add-memory is needed first
2. Read .supervibe/memory/index.json (auto-generated by scripts/build-memory-index.mjs)
3. Identify task topic + relevant tags

Memory structure (project-memory v1)

.supervibe/memory/ contains 5 categories of markdown files:

.supervibe/memory/
├── index.json              # auto-generated tag→entries index
├── decisions/              # PRD decision sections lived shorter than full PRD decision section; tactical choices
│   └── <date>-<slug>.md
├── patterns/               # reusable patterns observed/established
│   └── <slug>.md
├── incidents/              # postmortem learnings (compressed)
│   └── <date>-<slug>.md
├── learnings/              # general project insights from any agent
│   └── <slug>.md
└── solutions/              # how-we-solved-X catalog
    └── <slug>.md

Each entry has frontmatter:

---
id: <slug>
type: decision | pattern | incident | learning | solution
date: YYYY-MM-DD
tags: [billing, stripe, idempotency, redis-cache]
related: [other-entry-ids]
agent: <which agent created — for traceability>
confidence: <0-10 — quality of this memory entry>
---

Decision tree

Search strategy:
1. Tag-overlap search — match task topic tags against memory entry tags
   ├─ ≥3 matching entries → read top 3 by tag-overlap score
   ├─ 1-2 matching entries → read all matching
   └─ 0 matches → fallback to grep:

2. Grep fallback — search markdown content for task keywords
   ├─ Found → read top 5 by relevance
   └─ Not found → return "no prior memory; consider this novel territory"

3. Type filter (when applicable):
   - "Have we made this decision before?" → search decisions/
   - "Is there a pattern for this?" → search patterns/
   - "Did we have an incident like this?" → search incidents/
   - "Have we solved similar before?" → search solutions/

Procedure

1. Step 0 — verify memory exists, load index
2. Identify topic + tags from current task context
3. Search (decision tree above)
4. For each found entry:
   • Read full content
   • Check confidence: field — only treat as authoritative if ≥9
   • Check freshness, stale, supersededBy and contradictionIds from scripts/search-memory.mjs
   • Check date: — flag if >180 days (may be stale; verify still applicable)
5. Synthesize findings into context for the requesting agent:

   📚 Project memory matches:
   
   1. [decision] 2026-03-15 — billing-idempotency-via-redis-lock
      Tags: billing, idempotency, redis-cache
      Summary: We chose Redis SETNX for idempotency keys (5-min TTL) over DB-row-lock because billing DB write throughput was bottleneck.
      Confidence: 10
      Read full: .supervibe/memory/decisions/2026-03-15-billing-idempotency-via-redis-lock.md
   
   2. [solution] 2026-04-01 — stripe-webhook-replay-protection
      ...
   
   3. [pattern] reusable: queue-job-with-idempotency
      ...
   
   Recommendation: <how findings apply to current task>
   

6. Return to caller (brainstorming / writing-plans / etc.) with memory-informed context

Output contract

Returns:

• List of relevant memory entries (≤5) with: id, type, date, tags, summary, confidence, file path
• Synthesized recommendation for current task
• "No prior memory" if 0 matches (still valuable signal — novel work)

Guard rails

• DO NOT: invent memory entries that don't exist (anti-hallucination)
• DO NOT: treat low-confidence entries (<9) as authoritative — flag uncertainty
• DO NOT: ignore stale-date warnings — old decisions may be obsolete
• DO NOT: use superseded or contradictory memory as final evidence without citing the newer/current entry
• DO NOT: return >5 entries (signal-to-noise degrades)
• ALWAYS: cite file path so user can read full entry
• ALWAYS: pass through to caller; this skill informs but doesn't decide

Verification

• index.json read successfully
• Tag-overlap or grep evidence shown
• Citations include file paths
• Stale-date warnings emitted when applicable

Related

• supervibe:add-memory — writes new memory entries (this skill READS only)
• agents/_meta/memory-curator — maintains memory hygiene
• supervibe:brainstorming — primary consumer (reads memory before exploring)
• supervibe:writing-plans — secondary consumer (reads patterns before planning)