Session Memory

Session Memory — Enforcement Rules

Domain: session-memory | Office: All (cross-office, always active) Version: 1.0.0 | Created: 2026-04-11 This skill CANNOT be disabled. It runs on every session.

Session Start Protocol

When any Claude session opens:

1. Check if .claude-sessions-memory/ exists in the project root
   • If NO: inform the user — "No session memory directory found. Run /mxm-new-project or copy templates/session-memory/ to .claude-sessions-memory/ to initialize."
   • Do NOT create files silently without user confirmation on a new project
2. Read .claude-sessions-memory/MEMORY.md (master index)
3. Read .claude-sessions-memory/project_current_state.md (last checkpoint)
4. Read .claude-sessions-memory/feedback_debugging_playbook.md (known issues — scan for OPEN status)
5. Read .claude-sessions-memory/handoff.md (last session open items)
6. Report session start summary:

SESSION MEMORY LOADED
  Last session : [date from handoff.md]
  Phase        : [current phase from project_current_state.md]
  Open tasks   : [count from handoff.md]
  Known issues : [count of OPEN entries in debugging playbook]
  Next step    : [next logical step from project_current_state.md]

7. Check .mxm-global/TASKS.md (if exists):
   • List P1 tasks due today or overdue
   • Suggest: "Next recommended task: [task] in [project] — [reason]"
   • If no tasks due: "No urgent tasks. Run /mxm-tasks to see full list."

During-Session Capture Rules

On Every ERROR or RETRY

Append to .claude-sessions-memory/feedback_debugging_playbook.md:

### [YYYY-MM-DD] — [Error Type / Short Label]

**Status:** OPEN | RESOLVED
**Context:** [what was being attempted when error occurred]
**Error:** [exact error message or description]
**Root Cause:** [diagnosed cause]
**Fix:** [what resolved it — or PENDING if unresolved]
**Prevention:** [how to avoid this class of error in future]
**Session:** [session date]

On Every ARCHITECTURE or PRODUCT DECISION

Append to .claude-sessions-memory/decision-log.md:

[YYYY-MM-DD] | [DECISION TITLE] | [rationale] | Alternatives considered: [list] | Decided by: [agent/user]

On Every Significant FILE WRITE

Check .claude-sessions-memory/reference_key_files.md — if the file is new and architecturally significant, add a row to the table.

Significance threshold: config files, schema files, agent definitions, skill files, migration scripts, test fixtures, environment templates.

Also flag the file for inclusion in the next auto-inventory scan (see auto-inventory.md).

On Every TASK COMPLETION

Mark the task done in .claude-sessions-memory/progress.md and .claude-sessions-memory/task_plan.md. Do not leave completed items in the active queue.

Session End Protocol

Before ending ANY session, execute in order:

1. Update progress.md — mark all items completed this session as DONE, move in-progress items to carry-forward
2. Update project_current_state.md — write the latest phase, completed work, active tasks, risks, and next logical step
3. Update handoff.md with:
   • Date of this session
   • Summary of what was accomplished
   • Open tasks (carry-forward)
   • Key decisions made this session
   • Exact next step for the next session
   • Any BLOCKED items and their blockers
4. Append to feedback files if any errors or lessons occurred during the session
5. Update MEMORY.md index if new files were created this session
6. Write .claude-sessions-memory/session-[YYYY-MM-DD].md with full session summary
7. Offer a continuation handoff prompt (ADR-023) — ALWAYS ask "Generate a continuation handoff prompt for a fresh window? (y/n)". Proactively recommend YES when you self-assess context is heavy (long transcript · high tool-call volume · compaction already fired · many files touched) — phrase it as judgement, NEVER a fabricated context percentage. If yes → run /mxm-handoff: fill templates/continuation-prompt.template.md from VERIFIED state only, write .claude-sessions-memory/CONTINUATION-PROMPT.md, and print it inline. The prompt points to source-of-truth + forces verification (the files win); it never embeds stale counts/HEADs. This is the portable (fresh-window) cousin of auto-compact.md (same-conversation compaction).

Session file format:

---
name: Session [YYYY-MM-DD]
description: [one-line summary of what was done]
type: project
---

## Session Summary — [YYYY-MM-DD]

### Completed
- [item]

### Decisions Made
- [decision] — rationale: [rationale]

### Files Modified
- [path] — [what changed]

### Open Items (carry-forward)
- [item]

### Next Session Start Point
[exact instruction for where to begin]

Staleness Prevention (runs after session memory writes)

After completing all session end writes, check for stale global state:

Current working project (full check)

1. .mxm-global/TASKS.md — mark completed tasks done
2. .mxm-global/GLOBAL-CONTEXT.md — update project count if changed
3. .mxm-global/portfolio-registry/project_state.md — verify this project listed at correct version
4. .claude-sessions-memory/file_inventory.md — run auto-inventory diff
5. Version sync — check current project's version files for drift (warn user if mismatch)

Other portfolio projects (light check)

6. For each project in portfolio registry: check mxm_version in their manifest
7. If behind current Maxim version: add update task to .mxm-global/TASKS.md
8. Do NOT auto-fix other projects — only log the staleness

Rule: don't warn — fix it. If TASKS.md has stale entries, update them. If project_state.md is outdated, rewrite it. Only version mismatches in OTHER projects get logged as tasks (not auto-fixed).

Deduplication Rules

If a duplicate is found at a non-canonical location:

1. Read non-canonical content
2. Merge (append) into canonical file
3. Backup original to .mxm-backup/[filename]-[date]
4. Log dedup action in decision-log.md
5. Inform the user — never silently delete

Template Initialization

To initialize session memory for a new project, copy all files from: templates/session-memory/ → .claude-sessions-memory/

Then edit each file to replace placeholder values with project-specific content.

Standard file set:

• MEMORY.md
• project_current_state.md
• feedback_debugging_playbook.md
• feedback_lessons_learned.md
• reference_key_files.md
• handoff.md (blank — created on first session end)
• progress.md (blank — created on first session end)
• task_plan.md (blank — created on first session end)
• decision-log.md (blank — created on first session end)

Copyright (c) 2026 iSystematic Inc. Maxim product. BSL 1.1.