Memory Query Skill

This skill provides a unified command-line interface for querying semantic memory entities with complex yq patterns. All queries are accessed through the consolidated query-memory.sh script using subcommands.

Usage: Run: .claude/skills/query-memory/scripts/query-memory.sh <operation> <type> <arguments> [flags]

Context Loading Variables

This section defines critical context references that are reused in the following instructions

Paths and Identifiers

• SEMANTIC_BASE_PATH: .memory/semantic/
• QUERY_MEMORY_SKILL_PATH: .claude/skills/query-memory/
• QUERY_MEMORY_SCRIPTS_PATH: $QUERY_MEMORY_SKILL_PATH/scripts/

Files

• QUERY_MEMORY_SCRIPT: $QUERY_MEMORY_SCRIPTS_PATH/query-memory.sh

Workflows

1. Filter Content by Episode

Purpose: Extract all content from a semantic memory entity that was added during a specific episode.

Usage:

$QUERY_MEMORY_SCRIPT filter episode <episode_id> <entity_file_path> [--include-sources]

Arguments:

• episode_id - Episode identifier (e.g., 251107_EP_13)
• entity_file_path - Path to semantic memory YAML file (e.g., $SEMANTIC_BASE_PATH/people/saito.yaml)
• --include-sources - (Optional) Show source episode information

Output: Returns sections and entries filtered to only content from the specified episode. Excludes metadata and relationships sections. Shows section headers and organized content by topic.

Use Cases:

• Review what was captured from a recent semantic synthesis
• Audit memory additions from a specific conversation
• Verify synthesist correctly extracted content from an episode
• Understand what a particular conversation contributed to entity knowledge

---

2. Show Section (Token-Efficient Context Extraction) ⭐ Preferred Method

Purpose: Extract specific sections from a semantic memory entity with token-efficient formatting. Shows reinforcement counts [N] when content appears multiple times across episodes, revealing recurring themes and patterns.

Usage:

$QUERY_MEMORY_SCRIPT show section <entity_file_path> <section1> [section2] ... [--include-sources]

Arguments:

• entity_file_path - Path to semantic memory YAML file (e.g., $SEMANTIC_BASE_PATH/people/saito.yaml)
• section(s) - One or more section names to query (space-separated) (e.g., philosophies patterns)
• --include-sources - (Optional) Show source episodes instead of reinforcement counts

Available Sections:

• Simple sections: philosophies, facts, accomplishments, approaches, patterns, preferences
• Structured sections: decisions, tasks, requirements, constraints, suggestions

Output: Returns requested sections with section name and description, content organized by topic, reinforcement counts [N] for content appearing in multiple episodes, and filtered to exclude sources for token efficiency.

Understanding Reinforcement Counts:

• [2] means this content appeared in 2 different episodes
• No number means content appears in only 1 episode
• Higher counts indicate recurring, reinforced concepts

Use Cases:

• Load behavioral context at session start (philosophies, patterns, approaches, preferences)
• Query specific knowledge areas without loading entire memory file
• Identify reinforced patterns and principles across multiple sessions
• Token-efficient context loading for focused work
• This is the recommended method for most memory queries

---

3. Validate Semantic Memory YAML Syntax

Purpose: Validate that a YAML file is syntactically correct. Used by semantic-synthesist-reviewer during memory validation workflow.

Usage:

$QUERY_MEMORY_SCRIPT validate <yaml_file_path>

Arguments:

• yaml_file_path - Path to YAML file to validate (e.g., $SEMANTIC_BASE_PATH/people/saito.yaml)

Exit Codes:

• 0 - File is valid YAML
• 1 - Invalid arguments or file not found
• 2 - File is not valid YAML (syntax error)

Output: Returns success message if valid, error message with debugging instructions if invalid.

Use Cases:

• Validate semantic memory files before committing
• Catch YAML syntax errors in automated workflows
• Part of semantic-synthesist-reviewer validation checklist
• Pre-commit hooks for memory file validation

---

4. Show Relationships from Semantic Memory Entity

Purpose: Extract all relationships for an entity or filter by specific relationship type. Shows how entities connect to other entities, tools, concepts, etc.

Usage:

$QUERY_MEMORY_SCRIPT show relationship <entity_file_path> [type1] [type2] ...

Arguments:

• entity_file_path - Path to semantic memory YAML file (e.g., $SEMANTIC_BASE_PATH/people/saito.yaml)
• type(s) - (Optional) Filter by specific relationship type(s) (e.g., designed, collaborates_with)

Output: Returns all relationships or filtered relationships with total count, entity name, description, role, and source episode.

Use Cases:

• Discover what an entity has designed/created
• Find collaboration relationships
• See technology preferences and tool choices
• High specificity for context management - load only relevant relationships
• Understand entity's role in the system (architect, user, decision maker, etc.)

---

5. Show Metadata from Semantic Memory Entity

Purpose: Extract metadata fields from an entity without loading full content. Useful for quick status checks, summaries, or understanding entity evolution via source episodes.

Usage:

$QUERY_MEMORY_SCRIPT show metadata <entity_file_path> [field1] [field2] ...

Arguments:

• entity_file_path - Path to semantic memory YAML file (e.g., $SEMANTIC_BASE_PATH/people/saito.yaml)
• field(s) - (Optional) Specific metadata fields to extract

Available Fields:

• name - Entity name
• entity_classification - Entity type (person, agent, technology, concept, etc.)
• status - Status (active, review-needed, archived, etc.)
• created - Creation timestamp
• last_updated - Last update timestamp
• source_episodes - List of contributing episodes
• summary - Entity summary description

Output: Returns complete metadata section or only specified fields. Token-efficient when you only need specific information.

Use Cases:

• Quick entity status checks
• Get entity summary without loading full content
• Understand entity evolution via source episodes list
• Check when entity was last updated
• Token-efficient metadata-only queries

---

6. Search Topics Across Semantic Memory Entities

Purpose: Search for topics by name across one or more entities. Uses substring matching (contains) for flexible discovery. Find where specific concepts are discussed without knowing exact section.

Usage:

$QUERY_MEMORY_SCRIPT search topic <pattern> <entity_file_path> [entity_file_path2] ... [--include-sources]

Arguments:

• pattern - Search string to match against topic names (case-sensitive substring match)
• entity_file_path(s) - One or more semantic memory YAML files to search
• --include-sources - (Optional) Show source episodes for matched content

Output: Returns all topics containing the search string with entity name, section, section description, actual topic name, and full content with reinforcement counts.

Use Cases:

• Find all content about a concept without knowing exact topic names
• Cross-entity search to see different perspectives (Saito's philosophy vs Yuki's workflow)
• Discover related topics through substring matching ("Agent" finds Agent Design, Agent Behavior, Agent Naming, etc.)
• Token-efficient focused queries when you know the general topic area
• No need to remember exact section or topic name

---

7. Show Topics from Semantic Memory Entity

Purpose: Get a complete topic inventory grouped by section. Lightweight discovery tool showing what topics exist without loading full content.

Usage:

$QUERY_MEMORY_SCRIPT show topics <entity_file_path> [section1] [section2] ...

Arguments:

• entity_file_path - Semantic memory YAML file
• section(s) - (Optional) Filter to specific sections only

Output: Returns topic inventory organized by section with topic counts and topic name arrays. No content loaded - just topic names.

Use Cases:

• Quick discovery of what topics exist in an entity
• Filter topic inventory to specific sections
• Find topic names for use with search topic command
• Lightweight inventory check (no content loaded)
• See topic counts per section
• Use this first to discover topics, then search topic to get content

---

Notes

• All scripts require yq by mikefarah to be installed
• Scripts assume they're run from project root or use absolute paths
• Error messages go to stderr, results to stdout for clean piping
• Exit code 0 on success, 1 on error