/memory

name: memory
license: MIT
compatibility: "Claude Code 2.1.277+. Requires memory MCP server."
description: "Read-side memory: search past decisions, load context, timelines and graph views. Use when finding what memory holds. To store use remember; to clean up use dream."
argument-hint: "[subcommand] [query]"
context: inherit
user-invocable: true
allowed-tools: "Read Grep Glob Bash AskUserQuestion mcp__memory__search_nodes mcp__memory__read_graph"
effort: low
model: haiku
metadata:
  category: mcp-enhancement
  mcp-server: memory
  version: "2.0.1"
  author: "OrchestKit"
  complexity: "low"
  tags: "memory, graph, session, context, sync, visualization, history, search"
triggers:
  keywords: [memory, recall, "search memory", "past decisions", "knowledge graph", "load context", "prior decisions", "what did we decide"]
  examples:
    - "search my memory for past database decisions"
    - "what did we decide about pagination last time"
    - "show me the knowledge graph"
  anti-triggers: [remember, save, store, commit, implement, explore]
paths:
  - ".claude/memory/**"
  - ".claude/projects/**/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

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

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:

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