project-memory

project-memory

An umbrella memory system for a project. Lives at project-memory/ at the project root so teammates see it immediately, and is committed to git so the memory travels with the code.

Today the only subsystem is project-memory/lesson-learned/ (per-session retrospectives). Future subsystems — decisions, glossaries, onboarding notes, whatever — land as sibling folders under project-memory/ and are auto-indexed by the same qmd collection.

Every new session is seeded from a capture-shape preset chosen by the agent at start — session (the standard 11-section retrospective) or spec (a lighter six-section template focused on the spec axis). Presets define which sections come pre-seeded; sections are additive, so a session can grow new sections later via scripts/promote_to_session.sh (spec → session widen) or by starting with --with-spec-axis (session preset with the spec axis included). See workflows/start-session.md for the decision rule.

Entry points — pick one and load that workflow

• First time in a project → workflows/bootstrap-memory.md. Check for project-memory/_CONTEXT.md; if missing, bootstrap before anything else.
• Starting a new mission → workflows/start-session.md. Pick --mode=session for open-ended work or --mode=spec when implementing a written specification; pass --with-spec-axis for gray-zone missions that mix the two. The workflow page has the full decision rule.
• Mission drifted past the spec mid-session → workflows/start-session.md#if-drift-happens-mid-session. Run scripts/promote_to_session.sh to widen the file additively — preserves all spec-axis content, adds the standard sections.
• Mid-session notable moment (steering, frustration, win, takeaway) → workflows/capture-moment.md.
• Mission ending → workflows/wrap-up-session.md.
• User asks about prior work ("have we seen this", "what did we learn about X") → workflows/query-memory.md.

Why this skill exists

Sessions produce valuable signal that gets lost the moment the chat closes: which prompts the user had to rewrite, which skills misfired, which frustration patterns repeat. A flat log captures that but can't be retrieved later. Tying capture to a qmd-backed index lets a future session semantically recall "we tried X for auth refactors last month and it failed because Y" without grepping blindly. Promoting the folder to project-memory/ at the project root also signals to teammates that this is a first-class knowledge surface — they can skim, contribute, and query it too.

File layout in every project

project-memory/
├── .gitignore                       # umbrella — ignores qmd sidecars (committed)
├── _CONTEXT.md                      # umbrella — qmd collection description (committed)
└── lesson-learned/                  # current subsystem
    ├── _INDEX.md                    # curated catalog, human-skimmable (committed)
    └── 2026-04-16/
        ├── _daily.md                # overview of the day's sessions
        ├── session-0915-refactor-auth.md
        └── session-1330-debug-build.md

_INDEX.md is subsystem-scoped because its content (Running Themes, Session Log) only makes sense for lessons. Future subsystems will have their own catalog shape. .gitignore and _CONTEXT.md live at the umbrella because they describe the whole qmd collection.

qmd integration

One qmd collection per project, name = <basename(cwd)>-memory. It is scoped to the entire project-memory/ umbrella with pattern **/*.md, so every subsystem under project-memory/ is indexed by the same collection — adding a new subsystem later requires no new qmd registration. Managed by scripts/bootstrap_memory.sh (register) and scripts/qmd_update.sh (re-index). Query anytime:

qmd query "<natural question>" -c "$(basename $PWD)-memory"
qmd search "<keywords>"        -c "$(basename $PWD)-memory"

If qmd is not installed, every read surface falls back to rg. Writes never depend on qmd. Full detail in references/qmd-integration.md.

Bundled scripts

Always prefer running scripts/*.sh over re-deriving the mechanics inline. The scripts encode slug generation, timestamp formatting, idempotent folder creation, section-aware inserts, and qmd calls. Each workflow file above calls out the exact script to invoke.

Scripts live under the skill itself. Invoke them via the absolute path to wherever the skill is installed, then run scripts/<name>.sh from that resolved skill directory.

Cross-agent note

This skill runs the same way across Claude Code, Codex, and Pi because everything important is done by shell scripts and tool-agnostic markdown edits. Resolve the installed skill directory first, then run scripts relative to that location. If you want the session frontmatter to record a specific harness, set LESSON_AGENT=claude-code, LESSON_AGENT=codex, LESSON_AGENT=pi, or LESSON_AGENT=other before invoking the scripts.

References (load only when needed)

• references/template-session.md — canonical session file template (mode: session). Read when running start-session or wrap-up-session.
• references/template-spec-session.md — lighter template for mode: spec (Spec Reference, Decisions, Deviations, Tradeoffs, Open Questions). Read when starting or wrapping up a spec-implementation mission.
• references/template-daily.md, references/template-index.md, references/template-context.md — seed templates, consumed by the scripts.
• references/frontmatter-schema.md — field definitions and allowed values. Read when editing frontmatter.
• references/qmd-integration.md — qmd command reference + fallback behaviour. Read before any qmd invocation.

Don't

• Don't auto-save approved "Candidates for memory save" — those go to ~/.claude/projects/.../memory/ only after the user explicitly confirms.
• Don't promote lessons into an Obsidian vault — project memory is project-scoped by design.
• Don't overwrite captured content; the capture script is append-only for a reason.