yonatangross 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:
~/.claude/projects/<slug>/memory/MEMORY.md(durable index — load first, always).claude/chain/state.json+ most recentNN-*.jsonhandoff (session continuation)- MCP
mcp__memory__search_nodesfor 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
/ork:memory search <query> # Search knowledge graph
/ork:memory load # Load context at session start
/ork:memory history # View decision timeline
/ork:memory viz # Visualize knowledge graph
/ork:memory status # Show memory system health
CRITICAL: Use AskUserQuestion When No Subcommand
If invoked without a subcommand, ask the user what they want:
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.
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 /ork: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