qmemory - SKILL.md Agent Skill

name: qmemory description: Capture a durable lesson from this work into persistent memory — a non-obvious gotcha, a confirmed convention, or feedback worth re-applying on future tasks. Use when you learn something that should outlive the session; qship runs it as Step 11.7 to record review/bug lessons.

Knowledge Item Memory Storage

Review the current conversation and extract generic, reusable lessons worth carrying into future sessions. Save them through Claude Code's auto-memory system so they show up automatically next time.

This skill is the manual end-of-conversation companion to the auto-memory system already described in your system prompt. Defer to that system as the source of truth — this skill just walks you through running it deliberately at session end. If anything here conflicts with the auto-memory rules in the system prompt, the system prompt wins.

Where memories live

Use the auto-memory directory for the current project — do not hardcode a path. It's the directory referenced as the memory location in the system prompt's auto-memory section (typically ~/.claude/projects/<project-slug>/memory/). The index file is MEMORY.md in that same directory.

If you cannot determine the project's memory directory from the system prompt, ask the user before writing anything.

What to extract (and what to skip)

Worth saving — anything that will help a future session that doesn't have this conversation's context:

Corrections — the user told you to stop doing X, or to do Y instead. Save the rule + the why.
Validated non-obvious successes — you took an unusual approach, the user confirmed it ("yes, exactly", "perfect, keep doing that"), and a future Claude wouldn't guess this from the code alone. These are easy to miss because they're quiet — watch for them.
Project facts with a deadline or owner — merge freezes, who's driving an initiative, the reason behind a rewrite. Convert relative dates to absolute (Thursday → 2026-05-07).
External system pointers — "bugs live in Linear project X", "oncall watches dashboard Y".
User profile signals — role, expertise, what framings they prefer.

Do NOT save (these are derivable or ephemeral, even if the user asks):

Code patterns, file paths, conventions, architecture — grep/Read the codebase next time.
Git history, recent commits, who-changed-what — git log/git blame is authoritative.
Debug solutions or fix recipes — the fix is in the commit, the reasoning in the message.
Anything already in CLAUDE.md.
In-progress task state, current conversation context, today's TODO list.

If the user asks you to save something on this list, push back: ask what was surprising or non-obvious about it — that's the part worth keeping, if anything.

Memory types and body structure

Pick the type that fits, and match the body structure to the type. The structures differ on purpose — feedback and project decay or get edge-cased, so they need a why you can audit later; user and reference are simpler facts.

Type	Use for	Body structure
`feedback`	Rules about how to work — corrections and validated successes	Rule (one sentence). Then Why: (the incident or reasoning). Then How to apply: (when this kicks in).
`project`	Time-bound facts: initiatives, deadlines, motivations	Fact (one sentence). Then Why: (the driving constraint). Then How to apply: (how it shapes future suggestions).
`user`	Stable info about the user — role, expertise, preferences	Free-form prose. No Why/How needed.
`reference`	Pointers to external systems	Free-form prose: where it lives, what it's for, when to consult it.

File format

---
name: Short descriptive title
description: One-line hook used to decide relevance later — be specific
type: feedback | project | user | reference
---

<body — structure depends on type, see table above>

Filename: prefix by type — feedback_<topic>.md, project_<topic>.md, user_<topic>.md, reference_<topic>.md. Topic should be terse and semantic, not chronological.

Updating MEMORY.md

MEMORY.md is the index, not a memory. Each entry is one line, under ~150 chars, in this exact format:

- [Title](filename.md) — one-line hook

No frontmatter. Lines past 200 get truncated by the loader, so keep it tight. Group entries under the existing semantic headers (## Key Learnings, ## Codebase Patterns, etc.) — don't add chronological sections.

Before writing — check for duplicates and staleness

Read MEMORY.md to see what already exists.
If a similar memory exists:
- Update it rather than creating a new one. Tighten the rule, refresh the why with the new incident, extend How to apply if the scope has grown.
- If the new lesson contradicts an existing memory, the new one wins — edit the old file (or delete it) rather than letting both sit.
If a memory is clearly outdated by what you saw this session (file moved, flag removed, person changed roles), fix or remove it while you're in there.

Worked examples

Feedback — correction

---
name: Don't mock the database in integration tests
description: Integration tests must hit a real DB; mocking masked a broken migration last quarter
type: feedback
---

Integration tests in this repo must run against a real database, not a mock.

**Why:** Q4 incident — mocked tests passed but the prod migration failed because the mock didn't enforce the same constraints. Mocks made the bug invisible until rollout.

**How to apply:** When adding tests under `tests/integration/**`, wire them to the real test DB fixture. Save mocking for unit-test scope only.

Feedback — validated success (don't skip these)

---
name: Bundle related refactors into one PR in this area
description: User confirmed a single bundled PR was preferable to splitting — splits would have been churn
type: feedback
---

For refactors touching the matchers module, prefer one bundled PR over several small ones.

**Why:** I split a similar refactor into 4 PRs and the user pushed back — said the splits created review churn without isolating risk, since the changes only made sense together. The bundled approach was confirmed correct on the next attempt.

**How to apply:** When refactoring across `matchers/*.py`, default to one PR. Split only if a piece can land and be reviewed independently with real value.

Project — time-bound fact

---
name: Mobile release freeze 2026-05-07
description: Non-critical merges paused after 2026-05-07 for mobile release branch cut
type: project
---

Merge freeze for non-critical changes begins 2026-05-07 ahead of the mobile release branch cut.

**Why:** Mobile team is cutting the release branch and wants a stable base — every late merge forces a re-cut.

**How to apply:** For any non-critical PR planned after 2026-05-07, flag the freeze to the user and offer to defer or scope down. Critical fixes still go through.

Reference

---
name: Pipeline bugs tracked in Linear PIPELINE
description: Linear project PIPELINE is where pipeline-related bugs live
type: reference
---

Pipeline bugs and ingestion incidents are tracked in the Linear project `PIPELINE`. Check there for context on tickets, prior fixes, and ongoing investigations before opening a new bug.

Deliverable for this run

Identify the project's memory directory from the auto-memory system context (don't hardcode).
Read MEMORY.md to load what already exists.
Extract 2–5 lessons from this session, drawing from corrections AND validated successes. Skip anything on the "do not save" list.
For each lesson: check for an existing memory to update first; otherwise write a new file with type-appropriate frontmatter + body.
Update MEMORY.md — one line per new entry, under the right semantic header, under 150 chars.
Report back: list each title, whether it was new or an update, and one sentence on why it's worth keeping.