Add an explicit memory maintenance and session audit workflow

[ssheld]

Summary

agent-vault already contains strong session-start and session-end requirements, but the memory-maintenance behavior is spread across several sections and relies heavily on implicit judgment. We should add an explicit, vendor-neutral memory maintenance workflow so generated projects have a clearer process for keeping canonical memory files current.

This is conceptually similar to what Claude's claude-md-management plugin is trying to automate, but here it should remain markdown-first, portable, and repo-local.

Planning Metadata

• Priority: High
• Estimated effort: Medium
• Suggested order: 1 of 4, since this is the most central improvement to the template's core purpose

Why this matters

• The scaffold tells agents to update many files, but it does not yet provide a compact "memory audit" pass that helps them decide what changed and where it belongs.
• In practice, the risk is not missing a file entirely; it is writing the right fact to the wrong place, or leaving durable decisions buried in a scratch note or PR conversation.
• An explicit maintenance workflow would reinforce the distinction between temporary working memory and canonical project memory.
• This fits the repository's core purpose more directly than most other plugin-derived ideas.

Proposed scope

• Add a Memory Maintenance or Memory Audit section to scaffold/agent-vault/shared-rules.md.
• Mirror that guidance into scaffold/agent-vault/AGENTS.md.
• Define a repeatable end-of-session pass that asks, at minimum:
  • What changed in the code or docs?
  • What durable context should be added to context-log.md?
  • Are there new unresolved items for open-questions.md?
  • Was a durable decision made that needs a decision record and decision-log.md update?
  • Was there a mistake pattern worth recording in lessons.md?
  • Is a handoff note needed?
• Clarify the intended role of each canonical file versus context/scratchpad.md.
• Consider whether a lightweight checklist template would help, for example a Session Wrap-Up Checklist or similar reusable note.
• Update scaffold docs if the workflow materially changes how generated projects are expected to maintain memory.

Candidate files

• scaffold/agent-vault/shared-rules.md
• scaffold/agent-vault/AGENTS.md
• Potentially one new template under scaffold/agent-vault/Templates/
• scaffold/agent-vault/README.md
• README.md

Candidate guidance areas

• How to distinguish temporary notes from durable project memory.
• How to decide whether information belongs in:
  • context-log.md
  • design-log/
  • daily/
  • open-questions.md
  • decision-log.md and decisions/
  • lessons.md
  • context/handoffs/
• A short audit sequence to run before finalizing work.
• Examples of common failure modes:
  • decision buried in a design-log note only
  • open question left in a PR thread instead of open-questions.md
  • scratchpad content never promoted into canonical files
  • handoff state missing despite meaningful unfinished work

Open questions

• Should this live purely in rules text, or also in a reusable checklist template?
• Is a lightweight helper script worthwhile, or is that too much automation for the repository's goals?
• Should the audit language be mandatory for substantive work or presented as strongly recommended guidance?

Non-goals

• Do not introduce an external database, index, or non-markdown memory store.
• Do not make agent-vault dependent on a specific model, client, or plugin system.
• Do not turn this into a general-purpose task tracker; stay focused on project context hygiene.

Success criteria

• Generated projects have a clear, explicit memory-maintenance pass instead of relying only on scattered requirements.
• The distinction between temporary notes and canonical memory is easier to follow.
• The workflow reduces ambiguity about where session outcomes should be recorded.
• Policy mirrors remain in sync.

Validation ideas

• bash scripts/check-policy-mirrors.sh
• If new templates are added, verify they appear correctly in a freshly generated scaffold.

Context

This issue comes from evaluating useful patterns in official Claude Code plugins while keeping agent-vault vendor-neutral. The goal is to capture the useful maintenance workflow in normal project docs rather than through Claude-specific packaging.

Reference inspiration:

• claude-md-management plugin: https://raw.githubusercontent.com/anthropics/claude-plugins-official/main/plugins/claude-md-management/README.md
• Official plugin directory: https://github.com/anthropics/claude-plugins-official

[ssheld]

Now that #50 is merged, I think it is useful to sharpen the scope of this issue.

#50 solved the baseline enforcement problem:

• did the agent update required session metadata at all before commit?

I think #32 is the next layer up:

• did the agent update the right memory artifact?
• did durable information get promoted out of context/scratchpad.md, daily notes, design-log notes, or PR discussion into canonical memory?
• is it clear what belongs in each file versus what is only temporary working context?

My current recommendation is to make v1 of this issue rules-first, not automation-first.

Proposed v1 scope

1. Add a Memory Audit or Memory Maintenance section to scaffold/agent-vault/shared-rules.md.
2. Mirror it into scaffold/agent-vault/AGENTS.md.
3. Add a compact routing model for where different kinds of information belong.
4. Add a short mandatory end-of-session audit pass for substantive work.
5. Update the note-role docs (README.md, note folder READMEs, maybe template comments) so the routing model is reinforced outside the main rules file.

What I think the routing model should say

• context-log.md
  • canonical current state and session-level changes that future sessions need to know first
• design-log/
  • detailed session notes, investigations, implementation notes, decisions-in-progress, validation notes
• daily/
  • short-lived same-day working context; useful, but not authoritative by itself
• open-questions.md
  • unresolved items that still need follow-up, ownership, or research
• decision-log.md + decisions/
  • durable decisions that change how the project should be built, operated, or reasoned about
• context/handoffs/
  • transfer package when work pauses or changes hands with meaningful unfinished context
• lessons.md
  • recurring mistake patterns and prevention rules
• context/scratchpad.md
  • temporary only; never authoritative

Proposed end-of-session audit

For substantive work, before finishing ask:

1. What changed that future sessions need to know?
2. What belongs in context-log.md as current state?
3. What detailed implementation context belongs in design-log/ but not in the context log?
4. Are there unresolved items that now belong in open-questions.md?
5. Was a durable decision made that now belongs in decisions/ and decision-log.md?
6. Did this session reveal a repeatable mistake pattern for lessons.md?
7. If work is pausing, is a handoff note required and linked from context-log.md?

What I would defer from v1

I would defer these until after the routing model is agreed:

• new helper scripts
• a committed checklist artifact like Session Wrap-Up Checklist.md
• more hook/CI enforcement beyond what Session-end checklist is advisory, not enforced — agents skip metadata on rushed commits #50 already added

Reason: I think the main unresolved problem is judgment/routing, not missing automation. If we automate before the model is clear, we risk creating more process without reducing ambiguity.

Questions for consensus

1. Should the first iteration be rules-only, or rules plus a reusable checklist template?
2. Should the memory audit be mandatory for all substantive work?
3. Should daily/ remain explicitly supplemental rather than canonical?
4. Should context-log.md be treated as “current state / what changed” while design-log/ is “details / reasoning / investigation”?
5. Should we defer new automation until after the routing model is agreed?
6. Are there specific failure modes we want called out explicitly in the policy text (for example: decision buried only in design-log, open question left only in PR thread, scratchpad content never promoted, missing handoff despite unfinished work)?

If this general direction seems right, I think the implementation can stay fairly small and focused:

• one rules change
• one mirror update
• a few doc clarifications
• no new runtime artifact or helper script in the first PR

[ssheld]

Reviewed the issue description, the scoping comment, and the current state of shared-rules.md, the context-log.md template, and open-questions.md. Feedback below, organized by the scoping comment's structure.

General direction

The rules-first, defer-automation approach is the right call. The gap this fills — helping agents route information to the right canonical file — is fundamentally a judgment problem, not an enforcement problem. #50 already handles enforcement for the "did you update at all?" layer.

Routing model feedback

The proposed routing model is clear and mostly matches how the files are already described in shared-rules.md lines 50–65. Two observations:

1. context-log.md has a dual identity that the routing model should resolve.

The current template has both a "Current Snapshot" section (living state) and chronological "Entries" (append-only log). The scoping comment proposes it as "current state / what changed" — but that only works if the Current Snapshot is actively maintained, not just initialized at bootstrap and left to rot.

The routing model should explicitly say whether:

• The Current Snapshot section is maintained as living state every session (updated, not just appended to)
• Older entries can be archived or summarized once their state is captured in the snapshot
• There's a growth boundary (e.g., keep the last N entries, or entries from the current milestone)

Without this, context-log.md becomes an unbounded append-only log and agents will stop reading past the first few entries.

2. The daily/ vs design-log/ distinction could be sharper.

The routing model says daily is "short-lived same-day working context" and design-log is "detailed session notes, investigations, implementation notes." In practice, both get created per-session for substantive work. The routing guidance should clarify:

• daily = what happened today (brief, factual, cross-session if multiple sessions in one day)
• design-log = why and how (investigation details, trade-off analysis, validation notes that someone might reference weeks later)

This helps agents decide where a given fact goes when it could plausibly live in either.

End-of-session audit feedback

The 7-question audit is solid. Three gaps I'd suggest closing:

1. Add a resolution/removal pass, not just an addition pass.

The current questions all ask "what should be added?" but don't prompt for:

• Checking off resolved items in open-questions.md
• Updating decision status from proposed to accepted in decision-log.md
• Removing or marking stale entries in context-log.md

A session that resolves existing items is just as important to capture as one that creates new items.

2. Add an explicit scratchpad promotion question.

The current rules already say "move lasting information into canonical files before finishing" (shared-rules.md:65,74), but the proposed audit doesn't include a question like: "Is there anything in context/scratchpad.md that should be promoted to a canonical file?" This is one of the failure modes the issue already calls out.

3. Consider prompting for context-log.md Current Snapshot maintenance.

If the routing model treats Current Snapshot as living state (per point 1 above), the audit should ask: "Does the Current Snapshot in context-log.md still reflect reality, or does it need updating?"

Answers to the consensus questions

1. Rules-only first, or rules plus checklist template? Rules-only. A template can come in v2 once the routing model has been validated by a few real sessions. Premature templates risk becoming stale process artifacts.

2. Mandatory for substantive work? Yes. It's the qualitative complement to the Session-end checklist is advisory, not enforced — agents skip metadata on rushed commits #50 quantitative gate. The pattern is already established.

3. daily/ as supplemental? Yes. Daily notes are working context — useful for same-day continuity but not authoritative. The routing model should say so explicitly.

4. context-log.md as current state, design-log/ as details? Yes, with the caveat that "current state" means the Current Snapshot is actively maintained, not just that new entries are appended.

5. Defer automation? Yes. Agree with the reasoning that automating before the model is clear risks adding process without reducing ambiguity.

6. Call out failure modes explicitly? Strongly yes. The four failure modes in the issue body (decision buried in design-log, open question left in PR thread, scratchpad never promoted, missing handoff) are the most actionable part of this guidance. They give agents concrete anti-patterns to watch for. I'd add one more: "resolved open question never checked off, leading future sessions to re-investigate."

Presentation suggestion

Consider presenting the routing model as a compact decision-tree or table rather than just a flat list. Something like:

Information type	Primary destination	Also update
What changed (current state)	context-log.md Current Snapshot + new entry	—
Why / how (investigation, trade-offs)	design-log/	context-log.md entry (summary only)
Unresolved item	open-questions.md	context-log.md entry
Durable decision	decisions/ + decision-log.md	context-log.md entry
Mistake pattern	lessons.md	—
Unfinished work transfer	context/handoffs/	context-log.md (link to handoff)
Temporary scratch	context/scratchpad.md	Promote before session end

A table like this is more scannable than prose and easier for agents to reference during the audit pass.