Memory Manage

<!-- MEMORY-CONTRACT v1 -->

Memory contract

Standing contract for every invocable command. Rendered once per command

file into the per-tool envelope by config-export command mode. Expresses

cross-session persistence in tool-neutral prose — it issues NO tool-specific

call, so it passes the export STRIP guard verbatim.

This command persists its work across sessions through engram, registered as an MCP server in this tool. Use this tool's own engram memory tools to honor the contract below — do not assume any other persistence layer.

Recall before acting

When the first input is a continuation keyword ("listo", "dale", "seguimos", "ready", "where did we leave off", "qué sigue"), DO NOT start fresh. First search engram for prior work on this change — by the change name and by recent topic keys — then summarize what you found and continue from there. Skipping the search and asking "what can I help with?" means you ignored existing context.

Validate after saving

After any save, verify it actually persisted: search engram back for the key or a unique phrase you just wrote. A tool response of "saved" is NOT proof the row landed. If the verifying search does not return the row, retry once; if it still fails, tell the user the save failed — never report "saved" on the tool response alone.

Summarize at close

Before ending a session, write a session summary to engram (goal, what was done, decisions, next steps, relevant files) so the next session can recover context. Recovery is never automatic — every session must search engram to find prior state.

When engram is unreachable

If engram is not installed or not on PATH, memory operations cannot persist. When that happens, emit a visible warning to the user that engram was not found (not installed / not on PATH) and that this session's work will NOT survive. DO NOT report memory as saved, and DO NOT proceed silently as if persistence had occurred. See the install prerequisite in the onboarding docs to enable engram.

Skill Logic: memory-manage

Unified management of the ai-context/ memory layer. Three modes: init, update,

maintain. Tool-neutral logic — no harness-specific wiring.

Mode Detection

Determine the mode from the invocation:

• /memory-init or "initialize memory" or "generate ai-context" → init mode
• /memory-update or "update memory" or "sync memory" or "record session" → update mode
• /memory-maintain or "maintain memory" or "memory housekeeping" or "clean ai-context" → maintain mode

---

Mode: init

Creates the 5 core ai-context/ files from scratch by reading the project.

Use when: Project has no ai-context/ yet, or you want to regenerate from scratch.

Process

1. Project inventory: Read configuration files, folder structure, README, representative source files, tests, CI/CD configs. 2. Generate files:

• ai-context/stack.md — tech stack, versions, key tools
• ai-context/architecture.md — architectural decisions and rationale
• ai-context/conventions.md — naming patterns, code conventions
• ai-context/known-issues.md — known bugs, tech debt, gotchas
• ai-context/changelog-ai.md — empty, ready for session entries

3. Feature stubs: Scan for bounded contexts (directories with domain logic). Create ai-context/features/_template.md and stub files for discovered domains. 4. Report: List files created and coverage summary.

---

Mode: update

Incrementally updates ai-context/ with work done in the current session.

Use when: After completing significant work (SDD cycles, architecture changes, bug fixes).

Process

1. Analyze session: Review what changed — files created/modified, decisions made, bugs fixed, conventions established. 2. Update relevant files:

• ai-context/stack.md — new dependencies, version changes
• ai-context/architecture.md — new decisions, pattern changes
• ai-context/conventions.md — new naming patterns, style changes
• ai-context/known-issues.md — new issues found, resolved issues marked
• ai-context/changelog-ai.md — append entry with date, summary, files affected
• ai-context/features/<domain>.md — update if relevant domain was touched

3. Preserve: Never overwrite [manual] sections. Only update [auto-updated] markers.

---

Mode: maintain

Periodic housekeeping: archive old entries, separate resolved issues, detect gaps.

Use when: changelog-ai.md is long (30+ entries), known-issues has resolved items, or at the start of a new project phase.

Process

1. Changelog archival: If changelog-ai.md has more than 30 entries, move older entries to changelog-ai-archive.md. 2. Known-issues cleanup: Move resolved items from known-issues.md to known-issues-archive.md. 3. Index generation: Create/update ai-context/index.md listing all ai-context/ files with one-line descriptions. 4. Gap detection: Check if the project instruction file references ai-context/ files that don't exist. Report gaps. 5. Dry-run first: Present all proposed changes, require user confirmation before applying.

---

Rules

• Init mode MUST NOT run if ai-context/ already exists — warn and suggest update mode instead
• Update mode MUST NOT create new core files — only modify existing ones
• Maintain mode MUST present dry-run before any destructive action (archival, moves)
• All modes are read-heavy, write-light — the goal is accurate, concise documentation
• Never overwrite [manual] sections in any file
• Feature file updates follow the format defined by the feature-domain-expert reference skill