# Project Memory

> Operate inside a markdown memory vault: orient at session start, write durable notes correctly, and close a session out so context carries forward. Encodes the read-before-write protocol, frontmatter rules, journal naming, git safety rails and evidence-first session close. TRIGGER when the user says "wake up", "calibrate", "start session", "what's the state", "log this", "save this decision", "remember this", "wrap up", "close out", "end session"; when they reference the vault; or before editing any file under a tracked project. SKIP for one-off factual questions that need no durable record, for building or deploying (use the project's own deploy procedure), and for authoring or auditing skills themselves (use skill-authoring craft notes). This skill owns the vault.

- Skill: `brinshadewater/project-memory` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add brinshadewater/project-memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/brinshadewater/project-memory/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: BrinShadewater (https://skillmd.com/u/brinshadewater)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/brinshadewater/project-memory

---


# Project Memory

**The vault is the data. This skill is the discipline.**

The vault is usually fine. The failure mode is agent discipline in using it — context
gets dropped at session close, volatile facts get recalled instead of checked, and the
next session burns time relearning what should already be known.

Set `AGENT_VAULT` to your vault root. Three flows; pick the one that matches.

---

## Flow 1: WAKE UP (orient at session start)

**Trigger when:** the user says "wake up" / "calibrate" / "what's the state" / "let's
work on X"; they name a project you have no context on; you are about to touch a tracked
project file; or you are in a fresh conversation and the workspace is the vault.

1. **Read `00_WakeUp/NEXT_ACTIONS.md` first.** The ranked list of what is actually
   outstanding. Read it **before proposing work and before quoting any planning
   document** — plans go stale in both directions, and **proposing already-finished work
   is the specific failure this prevents.**

2. **Read `00_WakeUp/CURRENT_CONTEXT.md`.** Paths and host context. It deliberately
   does **not** record live git state; that is computed fresh.

3. **Read `10_Rules/operating-rules.md`.** If a later instruction contradicts one of
   these, the rule wins — say so and ask.

4. **Read `10_Rules/verification-discipline.md`** if you are about to audit, sweep, or
   report on the state of anything.

5. **If touching a project, read its home note** in `50_Projects/`. Path, stack, status,
   conventions, open questions, safe next actions. **Read this before asking the user
   anything — most answers are already here.**

6. **Read the policy that matches the work:** code edits → `git-safety.md`; anything
   unattended → `automation-safety.md`; scripting on Windows → `windows-scripting.md`;
   more than one agent → `multi-agent-handoff.md`.

7. **Skim the last one to three journal entries** in `90_Journal/` (filenames sort by
   date). They tell you what was actually done recently, which often differs from what a
   project note's `updated:` field suggests.

8. **Verify, do not trust.** Memory is a snapshot. Before acting on a recalled fact —
   branch state, file paths, what is installed — check it. **Recall is a starting point,
   not ground truth.**

9. **Summarise back.** "I'm oriented on X. Here's what's open, here's what I'd suggest
   next. Want me to verify state first?" Then ask only for what is genuinely missing.

### Four git traps that give confident wrong answers

Use `scripts/git_status_capture.py`, which handles all four, rather than improvising:

- **Repos nest one level down.** A project folder is often not the repo. Scanning one
  level reports it unversioned.
- **Worktrees live outside the project tree.** No directory scan finds them.
  `git worktree list`.
- **No upstream does not mean no remote.** A branch can diverge from a remote holding
  most of the history. `git remote -v`.
- **A configured upstream does not mean the commits were pushed.** `git status` reports
  ahead/behind for the *current branch only*. Ask
  `git rev-list --count <branch> --not --remotes` per branch, and `git stash list` for
  the fourth hiding place.

**Before reporting that anything is missing, establish that you searched everywhere it
could be.** An absence is a claim about the whole search space.

---

## Flow 2: WRITE (create or update notes)

**Trigger when:** the user says "log this" / "save this decision" / "remember this"; a
durable decision was made; meaningful work was done; or a project's state shifted.

**Pick the destination first.** Getting this right is what makes the vault searchable
later.

| Note type | Lives in | When |
|---|---|---|
| Journal entry | `90_Journal/YYYY-MM-DD-topic.md` | session work, audits, activity |
| Decision record | `30_Decisions/` (`templates/decision-record.md`) | choices affecting architecture, stack, hosting, money, public messaging, security |
| Project home update | `50_Projects/{Project}.md` | durable state change, not micro-experiments |
| New project home | `50_Projects/{New}.md` (`templates/project-home.md`) | starting on something new |
| Inbox dump | `20_Inbox/` | raw fragments to triage; promote upward later |
| Knowledge / policy | `40_Knowledge/` | durable knowledge that is not a decision |

**But check the destination ladder first** (`10_Rules/operating-rules.md`). If a *skill*
governed the work and the lesson is procedural, **the lesson belongs in that skill, not
in a note.** A skill fires automatically next time; a note has to be found first.

**Frontmatter is load-bearing.** Schema in `schema.md`. Required: `title`, `created`,
`updated`, `privacy`. Required when the note asserts anything volatile: `verify`.

- Validate before saving: `python scripts/lint_frontmatter.py <note>`
- Scaffold journal entries: `python scripts/scaffold_journal.py --topic "slug" --project "Name" --agent claude`

**Write guards** (full list in `40_Knowledge/policies/memory-write-guards.md`):

- Never store credentials. Ever.
- Never record a negative capability claim — "X is broken" hardens into a false refusal
  months after X is fixed. **Capture the fix, never the failure.**
- Never record environment-dependent failures or transient errors that resolved.
- Brainstorming goes to `20_Inbox/` and only gets promoted once the user confirms.
- Mark uncertain claims `confidence: low`.
- Ask before saving anything personal, financial, legal, medical, or safety-affecting.
  Default no.

**If you run a retrieval index, refresh it after writing — and verify the refresh.** A
sync that reports success is not proof a note is retrievable. One setup here was
silently unretrievable for eight weeks while every sync reported fine: the collection
had never been registered, and nothing ever checked. **Check the index's own listing,
not the sync's exit code.**

---

## Flow 3: CLOSE OUT (end a meaningful session)

**Trigger when:** the user says "wrap up" / "close out" / "we're done"; meaningful work
finished; you are about to lose context; or a commit, deploy, audit or decision happened.

**This flow is evidence-first. Read state before writing anything, never from recall.**

1. **Capture git state.** `python scripts/git_status_capture.py <project>`. Paste the
   output. Do not type it from memory — that is the entire point of the step.

2. **Create the journal entry** from `templates/session-close.md`, or scaffold it.

3. **Fill in every section.** What changed, files touched, git state, decisions, open
   questions, safe next actions, search anchors. **An empty section should say
   "Nothing", explicitly** — a blank is indistinguishable from a step that was skipped.

4. **Update the project home note.** Bump `updated:`, add a `### YYYY-MM-DD - topic`
   work-log entry, refresh open questions and next actions. **The project note is what
   gets searched first**; durable changes belong there, not only in the journal.

5. **If a decision was made, write the decision record.** Do it now. This is the step
   that never happens later, and an empty decisions folder is the normal outcome of
   intending to do it later.

6. **If the session revealed something about how the user works, refresh the user
   model.** Not every session does — most produce project facts, not user facts. But
   when they correct your *approach* rather than your output, override a recommendation,
   or react to how work was handed back, that is user-model signal and nothing else
   captures it.

   **Rewrite that section, never append**, so it stays a current picture rather than a
   log of every small preference. And keep the confidence honest: a handful of sessions
   is a small sample.

7. **If the project keeps a `WORK-LOG.md`, append to it.**

8. **Report what you saved.** "Closed out — wrote `90_Journal/X.md`, updated
   `50_Projects/Y.md`. Open questions: [...]. Safe next actions: [...]."

---

## Report vocabulary

When reporting on a multi-step run, these seven states are distinct and collapsing them
loses real information. **"Could not verify" and "nothing found" sharing a bucket is the
dangerous one.**

`completed` · `nothing found` · `not applicable` · `skipped` · `failed` ·
`could not verify` · `awaiting approval`

Give **lists, not counts** — "3 notes updated" is unauditable, the three filenames are
not. Answer **per category**, using the literal word "Nothing" rather than consolidating
absences into prose. **Report before asking**: deliver what you have, then ask your
question.

## Hard rails

1. **Never push without explicit approval**, per push. Not "the change is small", not
   "they approved one yesterday".
2. **Never edit directly on the default branch** when the repo tracks a remote.
3. **Never overwrite, reset, revert, or delete uncommitted work.** Ask.
4. **Never store secrets in the vault.** Not even temporarily.
5. **Never promote brainstorming to strategy** without confirmation.
6. **Never propagate stale memory.** If memory and current state disagree, trust
   current state and fix the memory.

## When in doubt

Read more of the vault before acting. One extra file read costs far less than
overwriting someone's work, dropping context, or storing a secret. If the answer is
genuinely not in the vault, ask — do not guess at hard rails.