memory-management

$2a

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 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.

#### 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.

#### 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.

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 custom segment or shorthand?

Step 4: Check Cold Storage

• Search memory/archive/ first for dated YYYY-MM-DD- archived files.

• If the archive points to a source category, follow that trail back to memory/research/, memory/audits/, or memory/monitoring/.

• Treat COLD findings as historical unless refreshed by the current session.

Step 5: Ask User

-

If not found in any layer, ask for clarification

-

Log the new term in glossary if it's project-specific

-

Decision provenance (v8.0.1+): when loading memory/decisions.md, verify each entry has approved_by: user. Entries with approved_by: skill_inferred or missing field are treated as ADVISORY — surface to user before using as authoritative. Auditor-class skills (content-quality-auditor, domain-authority-auditor) MUST ignore non-user-approved decisions when determining verdict. See skill-contract.md §Promotion Rules.

Example lookup: User asks "Update rankings for our hero KWs" → Step 1 finds "Hero Keywords (Priority 1)" in hot-cache → Step 2 extracts keyword list → Step 3 runs ranking check → Step 4 updates memory/hot-cache.md and memory/monitoring/rank-history/YYYY-MM-DD-ranks.csv.

3. Promotion & Demotion Logic

Reference: See references/promotion-demotion-rules.md for detailed promotion/demotion triggers (keywords, competitors, metrics, campaigns) and the action procedures for each.

4. Update Triggers, Archive Management & Cross-Skill Integration

Reference: See references/update-triggers-integration.md for the complete update procedures after ranking checks, competitor analyses, audits, and reports; monthly/quarterly archive routines; and integration points with all 8 connected skills (keyword-research, rank-tracker, competitor-analysis, content-gap-analysis, seo-content-writer, content-quality-auditor, domain-authority-auditor).

5. Memory Hygiene Checks

When invoked for review or cleanup:

• Line count check: Count lines in memory/hot-cache.md. If >80, list oldest entries for archival.

• Byte check: If hot-cache exceeds 25KB, warn and recommend trimming long entries.

• Staleness scan: List memory files older than 30 days that have not been referenced. Recommend archival for files >90 days.

• Frontmatter audit: Check that all memory files (except hot-cache.md) have name, description, and type in their frontmatter. Report any missing fields.

6. Save Results

Ask "Save these results for future sessions?" — if yes, write YYYY-MM-DD-<topic>.md to memory/. Add veto issues to memory/hot-cache.md only from auditor handoff or explicit user approval.

Examples, Advanced Features & Practical Limitations

Reference: See references/examples.md for three complete examples (hero keyword rankings, glossary lookup, e-commerce project init), advanced features (smart context loading, memory health check, bulk promotion/demotion, memory snapshot, cross-project memory, wiki lint), and practical limitations (concurrent access, cold storage retrieval, data freshness, wiki compilation).

GDPR / Privacy Compliance

memory/ may store third-party personal data — entity names, founder bios, LinkedIn profiles, author/journalist names surfaced by entity-optimizer or research skills. Under GDPR Art 4(1) (applies to processing of personal data of EU/EEA/UK residents regardless of where the controller is located), these qualify as "personal data". The user is the data controller. Non-EU users without EU/EEA/UK data subjects may still face analogous obligations under CCPA/CPRA (California), PIPEDA (Canada), LGPD (Brazil), or other national regimes. Not legal advice.

Retention policy

• WARM files: archive to memory/archive/ after 90 days unreferenced (default lifecycle)

• COLD archive: never auto-deleted, but eligible for Art 17 erasure requests

• All files: user MUST honor Art 17 requests from data subjects (individuals named in memory)

Deletion flow (Art 17 / CCPA §1798.105)

Invoke: memory-management purge <entity-name-or-slug>

This skill then:

• Greps all files under memory/ (including memory/archive/) for the entity name, slug, or domain

• Presents matches to user for confirmation

• Deletes or anonymizes confirmed matches across canonical and derived surfaces:

• Canonical: memory/hot-cache.md, WARM notes, COLD/archive files, memory/entities/<slug>.md, memory/entities/candidates.md, memory/geo-feedback/, audit aggregates, open loops

• Wiki layer: compiled memory/wiki/ pages, memory/wiki/log.md, memory/wiki/log-archive/, memory/wiki/.unresolved.md, memory/wiki/.drift-log, memory/wiki/.retire-day-log

• Phase 3 archive reverse-link scan (v9.9.9+): grep -l "originally_at:.*<entity>" memory/archive/*.md AND grep -l "retired_because_compiled:.*<entity>" memory/archive/*.md — purge entity name, originally_at path string, AND retired_because_compiled path string from any matched archive frontmatter

• **.unresolved.md value-field scrub** (v9.9.9+): the .unresolved.md schema stores value_a: / value_b: as freeform values. If the entity name appears as a VALUE (e.g., value_a: "CEO is Jane Doe") rather than as the contradiction's entity: field, the standard entity-name grep catches it via line-match. Confirm by running grep -F "<entity-name>" memory/wiki/.unresolved.md AND scrubbing each match (replace value with redacted label, preserve the contradiction structure for audit integrity).

• Malformed archive handling (v9.9.9+): some archives may lack originally_at: (legacy / manually-mv'd files) or contain non-printable bytes in the field. The reverse-link grep silently skips these, creating compliance ghosts. Mitigation: ALSO run grep -F "<entity-name>" memory/archive/*.md body-content grep — catches the entity name regardless of frontmatter integrity. If a malformed archive is touched by the purge, log it explicitly to memory/audits/gdpr-purges.md so a compliance audit can verify scope.

• Removes or refreshes derived wiki indexes so purged names do not reappear from cached pages

• Writes a tombstone to memory/privacy/tombstones.md with redacted label, salted non-reversible fingerprint, date, scope, and reingest_blocked: true; never store the raw subject

• Logs the purge to memory/audits/gdpr-purges.md per the canonical schema in references/gdpr-purge-log-template.md (v9.9.9+) — required fields: purge_id, date, redacted_label, fingerprint, scope.{canonical,wiki,archive}, action, action_detail, legal_basis, proof.{grep_count_before,grep_count_after}, reingest_blocked: true, audit_signature. Auditor-verifiable structure: never raw subject; mechanical grep-count proof; cross-referenced to tombstone fingerprint.

• For auditor archives, redact subject identifiers while preserving score/status/proof metadata required for audit integrity

Lawful basis reminder

Before writing a third-party person to memory/entities/, the user must have one lawful basis per GDPR Art 6 (where GDPR applies — see scope note above): consent, legitimate_interest, contract, or equivalent. Advisory — this skill does not enforce, and does not substitute for legal review.

Reference Materials

• references/examples.md — Worked examples, advanced features, practical limitations, and the auditor handoff archive block format & rules

• references/promotion-demotion-rules.md — Full promotion/demotion table and action procedures

• references/update-triggers-integration.md — Update procedures, archive routines, and cross-skill integration points

• CORE-EEAT Content Benchmark — Content quality scoring stored in memory

• CITE Domain Rating — Domain authority scoring stored in memory

Next Best Skill

Primary: keyword-research — seed or refresh campaign strategy with current demand signals.