memory

Memory - Read & Access Operations

Unified read-side memory skill with subcommands for searching, loading, syncing, history, and visualization.

Cross-session read strategy (Opus 5 / CC 2.1.111+): Opus 5 reads filesystem memory reliably across sessions. When loading context at session start, prefer the layered read order:

1. ~/.claude/projects/<slug>/memory/MEMORY.md (durable index — load first, always)
2. .claude/chain/state.json + most recent NN-*.json handoff (session continuation)
3. MCP mcp__memory__search_nodes for anything the filesystem index doesn't answer (typed graph traversal)

Layer 1 is cheap (small index file), Layer 2 is scoped (session-specific), Layer 3 is selective (only when needed). Avoid dumping the full knowledge graph into context — use the index to narrow the search first.

Argument Resolution

SUBCOMMAND = "$ARGUMENTS[0]"  # First token: search, load, history, viz, status
QUERY = "$ARGUMENTS[1]"       # Second token onward: search query or flags
# $ARGUMENTS is the full string (CC 2.1.59 indexed access)

Usage

CRITICAL: Use AskUserQuestion When No Subcommand

If invoked without a subcommand, ask the user what they want:

Subcommands

Load details: Read("references/memory-commands.md") for full usage, flags, output formats, and context-aware result limits for each subcommand.

Scheduled Sweeps (cron)

Nightly KG staleness report

Cron job in .github/workflows/memory-staleness.yml runs nightly at 04:00 UTC. Calls scripts/staleness_cron.py to scan ALL memory MCP entities, flag those whose latest observation timestamp is older than 30 days, and write a Markdown report to docs/reports/memory-staleness-YYYY-MM-DD.md.

Auto-skip conditions (all exit 0, all WARN-logged):

Report contents:

• Total / stale / fresh entity counts
• Top N stale entries sorted by staleness (no-timestamp first, then oldest → newest)
• Each row: name, entityType, age in days, observations count
• Suggested actions per age bucket (>90d review, >180d archive candidate)

Treats entities with no parsable timestamp as stale — operator intervention is the right outcome (backfill last_read observation OR prune).

Pure helpers (parse_iso_timestamp, latest_observation_timestamp, is_stale, build_report_payload, render_markdown) live in sibling staleness_lib.py for unit-testability.

Mirrors Yonatan-HQ/hq-ext-plugin#194 (audio_podcast) and orchestkit#1886 (post-synth podcast) + #1887 (memory writeback) pattern. Unblocked by Yonatan-HQ/core#993 (yg-mcp-core 0.3.0).

Workflow

1. Parse Subcommand

2. Execute Subcommand

Route to appropriate handler based on subcommand.

3. Report Results

Format output appropriate to the operation.

Rules Quick Reference

Session Resume

Load details: Read("references/session-resume-patterns.md") for CC 2.1.31 resume hints, context capture before ending, and resume workflows for PRs, issues, and implementations.

Related Skills

• ork:remember - Store decisions and patterns (write-side)

Error Handling

• If graph empty for viz: Show helpful message about using remember
• If subcommand invalid: Show usage help
• If memory files corrupt: Report and offer repair
• If search query empty: Show recent entities instead
• If no search results: Suggest alternatives