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.5 / CC 2.1.111+):** Opus 5.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 ```python 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 ```bash memory search <query> # Search knowledge graph memory load # Load context at session start memory history # View decision timeline memory viz # Visualize knowledge graph memory status # Show memory system health ``` --- ## CRITICAL: Use AskUserQuestion When No Subcommand If invoked without a subcommand, ask the user what they want: ```python AskUserQuestion( questions=[{ "question": "What memory operation do you need?", "header": "Operation", "options": [ {"label": "search", "description": "Search decisions and patterns in knowledge graph"}, {"label": "load", "description": "Load relevant context for this session"}, {"label": "history", "description": "Decision timeline + knowledge-graph viz (--mermaid)"}, {"label": "status", "description": "Check memory system health"} ], "multiSelect": false }] ) ``` --- ## Subcommands Load details: `Read("references/memory-commands.md")` for full usage, flags, output formats, and context-aware result limits for each subcommand. | Subcommand | Purpose | |------------|---------| | `search` | Search past decisions, patterns, entities. Supports `--category` (maps to metadata.category), `--limit`, `--agent` (scopes by agent_id), `--global` filter flags | | `load` | Auto-load relevant memories at session start. Supports `--project`, `--global` | | `history` | Decision timeline with table, Mermaid, or JSON output. Supports `--since`, `--mermaid` | | `viz` | Render knowledge graph as Mermaid diagram. See also `Read("references/mermaid-patterns.md")` | | `status` | Memory system health check | --- ## 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`. ```bash python3 ${CLAUDE_SKILL_DIR}/scripts/staleness_cron.py docs/reports/ \ --threshold-days 30 --limit 50 ``` Auto-skip conditions (all exit 0, all WARN-logged): | Skip reason | Trigger | |-------------|---------| | `yg-mcp-core not importable` | `yg-mcp-core>=0.3.0` not installed (orchestkit is public; yg-mcp-core lives on private `pypi.yonyon.ai` — HQ-only) | | `memory MCP unreachable` | memory MCP server down OR `.mcp.json` doesn't define `memory` | **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 ``` Extract first argument as subcommand If no subcommand -> AskUserQuestion Validate subcommand is one of: search, load, history, viz, status Parse remaining flags Check for --agent <agent-id> flag → agent_id: "ork:{agent-id}" ``` ### 2. Execute Subcommand Route to appropriate handler based on subcommand. ### 3. Report Results Format output appropriate to the operation. --- ## Rules Quick Reference | Rule | Impact | What It Covers | |------|--------|----------------| | entity-extraction-patterns (load `rules/entity-extraction-patterns.md`) | HIGH | Entity types, relation types, graph query semantics | | deduplication-strategy (load `rules/deduplication-strategy.md`) | HIGH | Edit-over-Write pattern, anchor-based insertion, verification | --- ## 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