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 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 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/. 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. See Examples 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.
• Done when: the requested lifecycle action (capture/promote/demote/archive/query/purge) is applied, memory/hot-cache.md is within the 80-line / 25KB limit, and the affected memory paths are reported back to the user.
• 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 Promotion & Demotion Rules 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; provides light-user guidance based on Quick Status when next_action items are available
• PostToolUse: warns when memory/hot-cache.md exceeds the 80-line / 25KB limit; enforces the auditor artifact-gate on memory/audits/ writes; offers an optional quality check after user-facing content edits
• 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.

Decision Gates

Stop and ask the user when:

• A purge (Art 17 / CCPA) is requested — present the matched files and the redaction-vs-delete choice, and only act on confirmed matches. Never auto-delete memory.
• A memory/decisions.md entry needed to answer a query has approved_by: skill_inferred or a missing field — surface it as ADVISORY and confirm before treating it as authoritative.
• A referenced term is not found in any memory layer — ask for clarification rather than guessing.

Continue silently (never stop for):

• Routine promotion/demotion that follows the temperature lifecycle rules.
• Hot-cache trimming suggestions when over the 80-line / 25KB limit (recommend, don't block).
• Missing optional tool data when auto-populating — record what is available and proceed.

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

Templates: Hot Cache Template · Glossary Template

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 memory/glossary.md

• Is it defined as project terminology?
• Is it a custom segment or shorthand?

Step 3: 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 4: 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 → extract the keyword list → run the ranking check → update memory/hot-cache.md and memory/monitoring/rank-history/YYYY-MM-DD-ranks.csv.

3. Promotion & Demotion Logic

Reference: See Promotion & Demotion Rules 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 Update Triggers & Integration 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:

1. Line count check: Count lines in memory/hot-cache.md. If >80, list oldest entries for archival. 2. Byte check: If hot-cache exceeds 25KB, warn and recommend trimming long entries. 3. Staleness scan: List memory files older than 30 days that have not been referenced. Recommend archival for files >90 days. 4. 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 Examples 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), and practical limitations (concurrent access, cold storage retrieval, data freshness).

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: 1. Greps all files under memory/ (including memory/archive/) for the entity name, slug, or domain 2. Presents matches to user for confirmation 3. Deletes or anonymizes confirmed matches across all surfaces:

• Canonical: memory/hot-cache.md, WARM notes, COLD/archive files, memory/entities/<slug>.md, memory/entities/candidates.md, audit aggregates, open loops
• Archive body scan: run grep -F "<entity-name>" memory/archive/*.md to catch the entity name regardless of frontmatter integrity (legacy or manually-moved files may lack clean frontmatter). 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.

4. 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 5. Logs the purge to memory/audits/gdpr-purges.md per the canonical schema in GDPR Purge Log Template (v9.9.9+) — required fields: purge_id, date, redacted_label, fingerprint, scope.{canonical,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. 6. 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

• Examples — Worked examples, advanced features, practical limitations, and the auditor handoff archive block format & rules
• Promotion & Demotion Rules — Full promotion/demotion table and action procedures
• Update Triggers & Integration — 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.

Memory Management Examples

---

Example 1: Update Rankings for Hero Keywords

User: "Update rankings for our hero keywords"

I'll update rankings for your hero keywords.
[Reads memory/hot-cache.md -> Hero Keywords section]
[If ~~SEO tool connected: runs automated ranking check]
[If manual: asks user for current rankings]

## Ranking Update - December 15, 2024

| Keyword | Previous | Current | Change | Target | Status |
|---------|----------|---------|--------|--------|--------|
| keyword research tools | #15 | #12 | up 3 | #5 | Improving |
| best seo software | #23 | #24 | down 1 | #10 | Stable |
| free backlink checker | #8 | #6 | up 2 | #3 | Near target |

### Updated Files
1. memory/hot-cache.md -> Hero Keywords table updated
2. memory/monitoring/rank-history/2024-12-15-ranks.csv -> New row added

### Recommendations
1. Push additional content/backlinks to "free backlink checker" to hit #3
2. Investigate "keyword research tools" +3 gain (replicate success)
3. Monitor "best seo software" for negative trends

Hot cache refreshed. Next ranking check: December 22, 2024.

---

Example 2: Glossary Lookup

User: "What does 'quick wins' mean in our project?"

[Check memory/hot-cache.md -> not found]
[Check memory/glossary.md -> found!]

**Quick Wins**
- **Definition**: Low-difficulty, high-value target keywords
- **Keyword Count**: 25
- **Context**: Keywords achievable for page 1 within 30-60 days due to low competition

Current list stored in: `memory/research/keywords/long-tail-keywords.md` (tagged "quick-win")

---

Example 3: Initialize Memory for New Project

User: "Set up memory for a new e-commerce site selling outdoor gear"

I'll set up the two-layer memory system.
[Creates: memory/glossary.md, memory/research/, memory/content/, memory/monitoring/, etc.]

To populate hot cache, I need:
1. **Target Keywords**: Top 10 hero keywords
2. **Primary Competitors**: Top 3-5 competitors
3. **Current Metrics**: DA, organic traffic, existing rankings
4. **Active Initiatives**: New categories, content campaigns, product focus
5. **Project Terminology**: Internal names, abbreviations, keyword segmentation

Once provided, I'll generate:
- memory/hot-cache.md, memory/glossary.md
- memory/research/keywords/ and memory/research/competitors/ structures
- memory/content/calendar/active-calendar.md

---

Advanced Features

• Smart Context Loading: Load full context for [campaign name]
• Memory Health Check: Run memory health check — orphaned files, missing timestamps, stale items
• Bulk Promotion/Demotion: Promote all keywords ranking in top 10 to hot cache
• Memory Snapshot: Create memory snapshot for [date/milestone]
• Cross-Project Memory: Compare memory with [other project]

---

Practical Limitations

• Concurrent access: Use timestamped filenames to avoid overwrites from parallel sessions.
• Cold storage retrieval: WARM/COLD files only load on demand. Hot cache is primary cross-session mechanism.
• Data freshness: Stale data (>90 days) should be flagged for refresh.

---

Auditor Handoff Archive Block Format

Append to monthly file (memory/audits/YYYY-MM.md), newest at bottom:

## YYYY-MM-DD · <target> · <framework>
- runbook_version: 1.1
- status: DONE | DONE_WITH_CONCERNS | BLOCKED
- framework: CORE-EEAT | CITE
- vetos_failed: [T04, R10]    # empty list [] if none
- veto_count: 2
- raw_overall: 78
- final_overall: 60            # or "n/a" if BLOCKED
- cap_applied: true
- audit_gap_types: [missing, shallow]  # distinct from entity-geo-handoff-schema.md's gap_type enum
- false_positive: false        # set true only on explicit user feedback
- audit_source: content-quality-auditor | domain-authority-auditor

Rules:

• One block per audit. Do not overwrite existing blocks.
• target is the URL or domain audited.
• runbook_version copied from current runbook header.
• false_positive is the ONLY field that can be flipped after initial write.
• GDPR/CCPA erasure is the exception: redact subject identifiers and replace them with a non-sensitive fingerprint while preserving scores, status, timestamps, and proof metadata.
• If monthly file doesn't exist, create with # Audit Archive — YYYY-MM header.

GDPR / CCPA Purge Log Schema (v9.9.9+)

memory/audits/gdpr-purges.md is an append-only log of every Art 17 / CCPA §1798.105 erasure executed by memory-management. The structured schema enables a compliance audit to verify scope, action, and reingest-blocking — without requiring access to the raw subject data (which has been redacted).

Why a template

Pre-v9.9.9: SKILL.md described the log surface but didn't enforce a structure. Sufficiently sloppy LLM sessions could write inconsistent entries (missing fingerprint, missing scope, missing action taken). Surfaced by the fintech persona testing of v9.9.9: "memory/audits/gdpr-purges.md schema is described but not formalized — counsel will want one."

This template is the canonical structure. Every purge entry MUST conform.

Entry schema

Append-only YAML list. One entry per purge invocation. Newest entries at the bottom.

- purge_id: 2026-05-06-001                   # YYYY-MM-DD-NNN, unique within day
  date: 2026-05-06                            # UTC date of the purge
  redacted_label: "Subject-A1B2"              # NEVER store raw subject. Use a salted, non-reversible label.
  fingerprint: "sha256:8f9c...3e21"           # Salted SHA-256 of (subject_name + project_salt). Truncated 8-byte prefix OK.
  scope:                                       # Where the purge ran
    - canonical:
        - memory/hot-cache.md
        - memory/research/competitors/acme-2024.md
        - memory/audits/domain/acme-cite.md
        - memory/entities/acme-corp.md
    - archive:
        - memory/archive/2026-05-01-acme-2024.md  # if archived pre-purge, body scrubbed
  action: anonymize                            # delete | anonymize | structural-preserve
  action_detail: |
    Replaced "Jane Doe" string with "[REDACTED]" in 14 lines across 9 files.
  legal_basis: art_17_request                  # art_17_request | ccpa_1798.105 | proactive_data_minimization
  malformed_archives_processed: 0              # count of archives lacking clean frontmatter that were body-grepped
  override_used: false                         # true if user invoked any override (e.g., partial-skip for audit integrity)
  reingest_blocked: true                       # mirrors memory/privacy/tombstones.md entry — must always be true post-purge
  proof:
    grep_count_before: 14
    grep_count_after: 0
    files_modified: 9
    log_md_lines_appended: 1
  audit_signature: "automated"                 # automated | human-reviewed | dual-signed
  reviewer: null                                # human reviewer id if dual-signed; null otherwise

Field reference

Append procedure

memory-management writes a NEW entry to the bottom of memory/audits/gdpr-purges.md after every purge. The entry is generated from in-flight grep counts and action records, NOT inferred post-hoc. The proof.grep_count_before value is captured BEFORE the purge runs; grep_count_after is captured AFTER.

If the purge spans multiple days (e.g., user paused mid-action), each day's portion gets its own entry sharing the same redacted_label and fingerprint.

Auditor verification

A compliance auditor with read access to memory/audits/gdpr-purges.md can verify:

1. Coverage: scope arrays match the documented surface in SKILL.md GDPR step 3. 2. Mechanical proof: grep_count_before > 0 AND grep_count_after == 0 in canonical/archive scopes. 3. No raw data persistence: redacted_label and fingerprint only — confirm no plaintext name appears anywhere in the entry. 4. Reingest block: reingest_blocked: true AND tombstone exists at memory/privacy/tombstones.md matching the fingerprint. 5. Override accountability: override_used: true entries get extra scrutiny; the action_detail should explain what was preserved and why (typically audit integrity).

Cross-references

• memory-management SKILL.md GDPR section — purge procedure
• references/skill-contract.md — Write Paths table

History

• v9.9.9 (2026-05-06): initial template, addressing the v9.9.9 fintech-persona testing finding that the schema was undocumented.

Glossary Template

Use this template to create the project glossary at memory/glossary.md.

# [Project Name] - SEO Glossary
**Last Updated**: [Date]

## Brand Terms
| Term | Full Name | Context |
|------|-----------|---------|
| [abbreviation] | [full name] | [when/how used] |

## Product Names
| Internal Name | Public Name | Category |
|---------------|-------------|----------|
| [code name] | [market name] | [product type] |

## Custom Segments
| Segment Name | Definition | Keyword Count |
|--------------|------------|---------------|
| Hero KWs | Top 10 revenue-driving keywords | 10 |
| Quick Wins | Low-difficulty, high-value targets | 25 |
| Brand Defense | Brand + modifier combinations | 15 |

## Competitor Shorthand
| Shorthand | Full Domain | Notes |
|-----------|-------------|-------|
| Comp A | competitor-a.com | Main competitor, [industry] |

## Project Acronyms
| Acronym | Full Term | Definition |
|---------|-----------|------------|
| [ABC] | [Full term] | [project meaning] |

## Internal Jargon
| Phrase | Meaning | Example Usage |
|--------|---------|---------------|
| [phrase] | [definition] | "Check rankings for [phrase]" |

## Historical Context
- **Project started**: [Date]
- **Major algorithm updates**: [List with dates]
- **Site migrations/redesigns**: [List with dates]
- **Key milestones**: [List with dates]

Hot cache template (memory/hot-cache.md)

Use this template when initializing memory for a new SEO project. The HOT tier is the single file memory/hot-cache.md (auto-loaded every session via the SessionStart hook, hard limit 80 lines / 25KB). Do NOT place this content in the project root's CLAUDE.md.

# [Project Name] - SEO Memory (hot cache)
**Last Updated**: [Date] | **Project Status**: [Active/Maintenance/Growth]

## Active Target Keywords (Top 10-20)

### Hero Keywords (Priority 1)
| Keyword | Current Rank | Target Rank | Volume | Status |
|---------|--------------|-------------|--------|--------|
| [keyword 1] | #[X] | #[Y] | [vol] | [tracking/optimizing/achieved] |

### Secondary Keywords (Priority 2)
| Keyword | Current Rank | Target Rank | Volume | Status |
|---------|--------------|-------------|--------|--------|
| [keyword 1] | #[X] | #[Y] | [vol] | [tracking/optimizing/achieved] |

_Full keyword research: memory/research/keywords/_

## Primary Competitors (Top 3-5)
1. **[Competitor 1]** (DA: [X]) — Strengths: [brief] | Position: [ahead/behind/competitive]
2. **[Competitor 2]** (DA: [X]) — Strengths: [brief] | Position: [ahead/behind/competitive]

_Detailed analyses: memory/research/competitors/_

## Current Optimization Priorities
1. **[Priority 1]** — Status: [not started/in progress/completed] | Impact: [H/M/L] | Deadline: [date]
2. **[Priority 2]** — Status: [not started/in progress/completed] | Impact: [H/M/L] | Deadline: [date]

## Key Metrics Snapshot
**Last Metrics Update**: [Date]
| Metric | Current | Previous | Change | Target |
|--------|---------|----------|--------|--------|
| Organic Traffic | [X] | [X] | [+/-X%] | [target] |
| Avg. Position | [X] | [X] | [+/-X] | [target] |
| Page 1 Rankings | [X] | [X] | [+/-X] | [target] |
| Domain Authority | [X] | [X] | [+/-X] | [target] |
| CITE Score | [X] | [X] | [+/-X] | [target] |
| Last Audit Score | [score]/100 ([rating]) — [date] | [page] |
| Total Backlinks | [X] | [X] | [+/-X%] | [target] |

_Historical data: memory/monitoring/reports/ and memory/monitoring/rank-history/_

## Active Campaigns
### [Campaign Name 1]
- **Duration**: [Start] - [End] | **Goal**: [goal] | **Status**: [planning/active/completed] | **Progress**: [X]%
- **Key activities**: [brief list]

_Campaign plans and archives: memory/content/calendar/_

## Quick Reference Notes
- [Important note 1]
- [Important note 2]

_For project terminology, see: memory/glossary.md_

Promotion and Demotion Rules

Promotion Logic — Promote to hot cache when:

Keyword triggers: referenced in 3+ conversations within 7 days; significant movement (5+ positions); targeted in new active campaign; driving traffic spike. Competitor triggers: mentioned in 3+ recent analyses; showing aggressive SEO activity; launching competing content. Metric triggers: requested frequently; showing anomalous behavior; tied to active priority.

Promotion action: 1. Add item to relevant section in memory/hot-cache.md 2. Add note: "Promoted [date] - [reason]" 3. Keep detailed data in cold storage 4. Set reminder to review in 30 days

Demotion Logic — Demote to cold storage when:

Keyword triggers: not referenced in 30+ days; target rank achieved and stable 60+ days; no longer in active strategy; replaced by higher-priority target. Competitor triggers: no significant activity in 60+ days; fell out of top 5 by relevance; no longer targeting same keywords. Campaign triggers: completed 30+ days ago; cancelled or postponed indefinitely.

Demotion action: 1. Remove from memory/hot-cache.md 2. Archive full data in memory/[category]/archive/ 3. Add line: "Last reviewed [category]: [date]" 4. Keep 1-line summary if historically significant

Update Triggers & Cross-Skill Integration

Update Triggers

After Ranking Check

1. Update memory/hot-cache.md -> Hero Keywords table 2. Save snapshot to memory/monitoring/rank-history/YYYY-MM-DD-ranks.csv 3. Note significant movement keywords 4. Update "Last Metrics Update" date 5. If hero keyword moves +/-5 positions, create alert note

After Competitor Analysis

1. Update memory/hot-cache.md -> Primary Competitors section 2. Save report to memory/research/competitors/YYYY-MM-DD-analysis.md 3. Update competitor overview notes 4. Note new strategies in hot cache

After Audit (Technical/Content/Backlink)

1. Save report to memory/audits/[type]/YYYY-MM-DD-[audit-name].md 2. Extract top 3-5 action items -> hot cache Current Optimization Priorities 3. Update Key Metrics Snapshot if audit includes metrics 4. Create campaign entry if audit spawns new initiative

After Monthly/Quarterly Report

1. Save report to memory/monitoring/reports/[period]/YYYY-MM-report.md 2. Update all metrics in hot cache Key Metrics Snapshot 3. Demote stale hot cache items 4. Update campaign statuses 5. Archive completed campaigns

Archive Management

Monthly

1. Review hot cache for items not referenced in 30 days 2. Move stale items to cold storage 3. Create snapshot: memory/monitoring/snapshots/YYYY-MM-hot-cache-snapshot.md 4. Compress old rank-history exports 5. Update glossary with new terms

Quarterly

1. Review entire cold storage structure 2. Compress files older than 6 months 3. Create quarterly summary report 4. Audit active campaigns -> archive completed ones

Cross-Skill Memory Integration