memory-management

Memory Management

This skill implements a three-tier memory system (HOT/WARM/COLD) for SEO and GEO projects. HOT memory (80 lines max) loads automatically every session via the SessionStart hook. WARM memory loads on demand per skill. COLD memory is archived data queried only when explicitly requested. The skill manages the full lifecycle: capture, promote, demote, and archive.

What This Skill Does

Manages a three-tier memory lifecycle (HOT/WARM/COLD) with automatic promotion, demotion, and archival. Also maintains the wiki index layer, open-loop tracking, and cross-skill aggregation.

Quick Start

Start with one of these prompts. Finish with a hot-cache update plan and a handoff summary using the repository format in Skill Contract.

Initialize Wiki Index

Refresh wiki index

Build wiki index for [project name]

Generates memory/wiki/index.md from existing WARM files. Required once to enable wiki features; subsequent refreshes happen automatically.

Initialize Memory Structure

Set up SEO memory for [project name]

Initialize memory structure for a new [industry] website optimization project

Update After Analysis

Update memory after ranking check for [keyword group]

Refresh hot cache with latest competitor analysis findings

Query Stored Context

What are our hero keywords?

Show me the last ranking update date for [keyword category]

Look up our primary competitors and their domain authority

Promotion and Demotion

Promote [keyword] to hot cache

Archive stale data that hasn't been referenced in 30+ days

Glossary Management

Add [term] to project glossary: [definition]

What does [internal jargon] mean in this project?

Skill Contract

Expected output: a memory update plan, hot-cache changes, and a short handoff summary.

• Reads: current campaign facts, new findings from other skills, approved decisions, and the shared State Model.
• Writes: updates to memory/hot-cache.md, memory/open-loops.md, memory/decisions.md, and related memory/ folders. Manages WARM-to-COLD archival in memory/archive/. Compiles memory/wiki/index.md (auto-refreshed) and wiki compiled pages (user-confirmed). Sole writer of wiki (with delegated auto-refresh): memory-management owns all wiki writes semantically. For performance, the narrowly-scoped memory/wiki/index.md auto-refresh is delegated to the PostToolUse hook in hooks/hooks.json. Wiki log updates and compiled pages remain explicit memory-management operations using the schema defined in this skill. Auditor handoff archiving (v7.1.0+): when triggered by a direct user request or an auditor's explicit "Save these results?" yes-response, append a structured block to memory/audits/YYYY-MM.md. The Stop hook never initiates memory writes. The archive is consumed by /aaron:guard --evals and maintainer calibration for auditor cap review tied to ADR-001. See references/examples.md for the exact archive block format and rules.
• Promotes: durable strategy, blockers, terminology, entity candidates, and major deltas. Applies temperature lifecycle rules: promote to HOT on high reference frequency, demote on staleness.
• Primary next skill: use the Next Best Skill below when the project memory baseline is ready for active work.

Handoff Summary

Emit the standard shape from skill-contract.md §Handoff Summary Format.

Temperature Lifecycle Rules

See references/promotion-demotion-rules.md for the full promotion/demotion table and action procedures.

Hook Integration

This skill's behavior is reinforced by the library's prompt-based hooks:

• SessionStart: loads memory/hot-cache.md, reminds of stale open loops; loads memory/wiki/<project>/index.md (or global index.md) if it exists; provides light-user guidance based on Quick Status when next_action items are available
• PostToolUse: after any WARM file write, silently refreshes memory/wiki/index.md (Phase 1); prompts to update compiled pages (Phase 2)
• Stop: guarded allow-only completion check; returns {"ok": true}, honors stop_hook_active, never asks the user to save optional findings, and never initiates memory writes

Data Sources

With tools: auto-populate from ~~SEO tool, ~~analytics, ~~search console. Without tools: ask user for keywords, competitors, metrics, campaigns, and terminology. See CONNECTORS.md.

Instructions

When a user requests SEO memory management:

1. Initialize Memory Structure

For new projects, create the directory structure defined in the State Model. Key directories: memory/ (decisions, open-loops, glossary, entities, research, content, audits, monitoring) plus memory/wiki/ (auto-managed compiled index with optional per-project subdirectories).

Templates: hot-cache-template.md · glossary-template.md · Wiki design archive

Wiki Layer

memory-management owns wiki schema and is the sole semantic writer. See [wiki-runbook.md](references/wiki-runbook.md) for execution detail.

Phase 1 — Index (auto-refreshed)

PostToolUse hook silently rebuilds memory/wiki/index.md after WARM writes. Index rows: precise (score/status/next_action/mtime) + best-effort (summary). Project-scoped index at memory/wiki/<project>/index.md. See [wiki-runbook.md §1](references/wiki-runbook.md).

Phase 2 — Compiled Pages (user-confirmed)

On user request or 3+ WARM mentions of an entity, generate memory/wiki/<project>/<type>-<slug>.md with source SHA-256 hashes. Contradictions resolved via SessionStart conversational prompt, not file editing. Write log entry to memory/wiki/log.md. See [wiki-runbook.md §2-§5](references/wiki-runbook.md).

Phase 3 — User-Initiated Retirement

WARM files fully covered by compiled wiki pages may be retired to memory/archive/. Always user-confirmed via /aaron:guard --wiki --retire-preview followed by explicit memory-management invocation. COLD files receive originally_at / retired_on / retired_because_compiled frontmatter to preserve recovery path. Single retire call hard-capped at 5 files. See [wiki-runbook.md §7](references/wiki-runbook.md).

2. Context Lookup Flow

When a user references something unclear, follow this lookup sequence:

Step 1: Check memory/hot-cache.md (hot cache)

• Is it in active keywords?
• Is it in primary competitors?
• Is it in current priorities or campaigns?

Step 2: Check Wiki Index (memory/wiki/index.md or project-level) — locate relevant WARM files

Step 3: Check memory/glossary.md

• Is it defined as project terminology?
• Is it a c