context-query

name: context-query description: > This skill should be used when users ask about their work context, what they're working on, recent activity, file relationships, or knowledge graph structure. Uses tastematter CLI (including graph-exec for structural graph queries) combined with grep/glob for context restoration. Every claim MUST cite a receipt ID for user verification.

Context Query Skill

Use tastematter CLI + grep + glob together for context restoration.

Core insight: The CLI finds WHICH files matter. Grep/Read find WHAT's in them.

Quick Start (90% of queries)

# 1. Full context for a topic (start here — one command does it all)
tastematter context "pixee" --format json

# 2. If you need to drill deeper, use targeted queries
tastematter query flex --files "*pixee*" --agg count,recency --format json

# 3. Read hot files to understand what they are
Read: <top_file_from_step_1>

# 4. Search content IN those files
Grep: pattern="hubspot|integration" path=<directory_from_step_1>

# 5. Check git for recent changes
git log --oneline -10 -- <hot_files>

Start with context for broad questions, drop to query subcommands for targeted drilldowns.

CLI Commands

Top-Level Commands

Query Subcommands

Always use --format json — table output truncates long paths.

The context Command

The highest-level query. One command gives you executive summary, heat, work clusters, insights, continuity, timeline, and suggested reads.

tastematter context "tastematter" --format json
tastematter context "pixee" --time 14d --format json

Response includes:

• executive_summary — status, work_tempo, hot_file_count, focus_ratio
• current_state — key_metrics, evidence (file excerpts)
• continuity — left_off_at, pending_items, chain_context
• work_clusters — co-accessed file groups with PMI scores
• suggested_reads — prioritized files (with surprise flag for unexpected)
• timeline — weekly focus areas with top files and access counts
• insights — abandoned file detection, anomalies
• verification — receipt_id, files/sessions/pairs analyzed
• quick_start — commands and directory structures from matching files

When to use context vs query:

The query heat Command

Shows file heat metrics with percentile-based classification.

tastematter query heat --time 30d --format json
tastematter query heat --files "*tastematter*" --sort specificity --format csv

Options:

-t, --time <TIME>      Long window: 30d (default), 14d, 60d, 90d
-f, --files <FILES>    File path pattern filter (glob-style)
-l, --limit <LIMIT>    Max results (default: 50)
-s, --sort <SORT>      Sort by: heat (default), specificity, velocity, name
    --format <FORMAT>  Output: table (default), json, compact, csv

Heat levels use percentile classification:

• Top 10% = HOT, 10-30% = WARM, 30-60% = COOL, Bottom 40% = COLD

Key fields: specificity (IDF-like), velocity, heat_score, heat_level

See references/heat-metrics-model.md for formula details and interpretation tables.

Graph Traversal: graph-exec Command

Executes JavaScript against an in-memory knowledge graph (markdown files with frontmatter + wiki-links). Uses Boa JS engine — pure Rust, no Node/bun.

tastematter graph-exec --graph <path-to-markdown-dir> '<javascript-code>'

The codemode Object (4 functions, all synchronous)

codemode.graph_search({ pattern, scope?, maxResults? })
  pattern: string        — regex to match
  scope: 'content' | 'frontmatter' | 'both' (default: 'both')
  maxResults: number     (default: 20)
  Returns: [{ path, matches: [{ line, content }], score, frontmatter }]

codemode.graph_traverse({ start, direction?, maxDepth?, filter? })
  start: string          — node name (filename without .md, e.g. "context-engineering")
  direction: 'outbound' | 'inbound' | 'both' (default: 'outbound')
  maxDepth: number       (default: 2)
  filter: { status?, domain?, tags? }
  Returns: { nodes: [{ path, name, depth, frontmatter }], edges: [{ from, to }] }

codemode.graph_read({ path, section?, maxLines? })
  path: string           — relative path (e.g. "technical/context-engineering.md")
  section: string        — extract named heading section only
  Returns: { path, content, frontmatter, outbound_links, inbound_links }

codemode.graph_query({ filter, sort?, limit? })
  filter: { status?, domain?, tags?, name?, validated_by? }
  sort: 'name' | 'last_updated' | 'status'
  limit: number          (default: 50)
  Returns: { nodes: [{ path, name, status, domain, tags, last_updated, link_count }], total }

Code Pattern: Use IIFEs

Functions are synchronous (not async). Wrap code in an IIFE:

# CORRECT — IIFE returns a value
tastematter graph-exec --graph 04_knowledge_base '(() => {
  const r = codemode.graph_query({ filter: { status: "canonical" } });
  return JSON.stringify({ total: r.total, names: r.nodes.map(n => n.name) });
})()'

# WRONG — bare return is a syntax error
tastematter graph-exec --graph 04_knowledge_base 'return codemode.graph_search({})'

# WRONG — async not needed (and Boa doesn't support top-level await)
tastematter graph-exec --graph 04_knowledge_base 'async () => { ... }'

Bash Escaping

Keep JS simple when passing inline. Avoid backslashes and nested quotes. If complex, use a heredoc:

tastematter graph-exec --graph 04_knowledge_base "$(cat <<'JSEOF'
(() => {
  const hubs = codemode.graph_query({ filter: {} });
  const sorted = hubs.nodes
    .sort((a, b) => (b.link_count.outbound + b.link_count.inbound) - (a.link_count.outbound + a.link_count.inbound))
    .slice(0, 10);
  return JSON.stringify(sorted.map(n => ({
    name: n.name,
    links: n.link_count.outbound + n.link_count.inbound
  })));
})()
JSEOF
)"

Common Graph Queries

# Top hubs by link count
tastematter graph-exec --graph 04_knowledge_base '(() => {
  const r = codemode.graph_query({ filter: {} });
  return JSON.stringify(r.nodes.sort((a,b) => (b.link_count.outbound+b.link_count.inbound)-(a.link_count.outbound+a.link_count.inbound)).slice(0,5).map(n => ({ name: n.name, out: n.link_count.outbound, in: n.link_count.inbound })));
})()'

# All canonical nodes
tastematter graph-exec --graph 04_knowledge_base '(() => {
  const r = codemode.graph_query({ filter: { status: "canonical" } });
  return JSON.stringify({ total: r.total, nodes: r.nodes.map(n => n.name) });
})()'

# Traverse outbound from a node
tastematter graph-exec --graph 04_knowledge_base '(() => {
  const r = codemode.graph_traverse({ start: "context-engineering", direction: "both", maxDepth: 1 });
  return JSON.stringify(r.nodes.map(n => ({ name: n.name, depth: n.depth })));
})()'

# Find orphan nodes (no links)
tastematter graph-exec --graph 04_knowledge_base '(() => {
  const r = codemode.graph_query({ filter: {} });
  const orphans = r.nodes.filter(n => n.link_count.outbound === 0 && n.link_count.inbound === 0);
  return JSON.stringify({ count: orphans.length, nodes: orphans.map(n => n.name) });
})()'

# Search then read (composition)
tastematter graph-exec --graph 04_knowledge_base '(() => {
  const results = codemode.graph_search({ pattern: "taste" });
  const top = results[0];
  const detail = codemode.graph_read({ path: top.path });
  return JSON.stringify({ path: detail.path, outbound: detail.outbound_links, inbound: detail.inbound_links });
})()'

MCP Alternative

If running inside Claude Code with the codemode-graph MCP server enabled, prefer the MCP tool over the CLI. The MCP tool description is embedded and the LLM gets the API right on the first call. Functions are async in MCP mode:

// MCP mode (async, tool description auto-loaded)
async () => {
  const results = await codemode.graph_search({ pattern: 'context' });
  return results[0];
}

When to Use graph-exec vs MCP vs grep/glob

Common Mistakes

Wrong: Expect semantic search

# DON'T - CLI searches file PATHS, not content
tastematter query flex --files "*notification design*"  # Won't find anything

Right: Use CLI for paths, grep for content

# DO - Find files first, then search content
tastematter query flex --files "*alert*" --format json  # Find alert-related files
Grep: pattern="notification|digest|slack" path=<results>  # Search content

Wrong: Only use CLI

# DON'T - You'll miss semantic understanding
tastematter query flex --files "*hubspot*"  # Returns files but not WHAT they do

Right: Combine tools

# DO - CLI narrows, Read/Grep understands
tastematter query flex --files "*hubspot*" --format json
Read: <top_result>  # Understand what the file actually does

Wrong: Skip context and go straight to query

# DON'T - You'll miss insights, clusters, and continuity
tastematter query flex --files "*pixee*" --format json

Right: Start broad, drill down

# DO - Get the full picture first
tastematter context "pixee" --format json
# THEN drill into specific areas if needed
tastematter query heat --files "*pixee*" --format json

Combining Tools

Workflow pattern:

context → full picture (summary, heat, clusters, insights)
    ↓
query heat/flex → drill into specific files or patterns
    ↓
Read → understand what files contain
    ↓
Grep → find specific concepts in content
    ↓
git log → understand evolution

Database Location

Canonical: ~/.context-os/context_os_events.db

If queries return empty results:

# Re-initialize (safe to run anytime — idempotent)
tastematter init

# Or check daemon status
tastematter daemon status

Citation Requirements

Every claim from query results MUST include receipt ID:

Found 147 Pixee files [q_7f3a2b]
To verify: tastematter query verify q_7f3a2b

When This Skill Helps vs Doesn't

For semantic understanding, READ the files. The CLI tells you which ones matter.

References

For advanced patterns:

• references/heat-metrics-model.md - Heat formula: specificity, exponential decay, percentile classification
• references/search-strategies.md - 9 multi-step search strategies (Pilot Drilling, Triangulation, etc.)
• references/query-patterns.md - Path substring patterns and result interpretation

CLI Full Reference

context (Composed Query — Start Here)

tastematter context <QUERY> [OPTIONS]

ARGUMENTS:
  <QUERY>            Search query (used as glob pattern *query*)

OPTIONS:
  -t, --time <TIME>      Time window (default: 30d)
  -l, --limit <LIMIT>    Max results per sub-query (default: 20)
      --format <FORMAT>  Output: json (default), compact, table

query flex (Targeted File Query)

tastematter query flex [OPTIONS]

OPTIONS:
  -f, --files <FILES>      File pattern (glob): "*pixee*", "*.py"
  -t, --time <TIME>        Time window: 7d (default), 14d, 30d
  -c, --chain <CHAIN>      Filter by chain ID
  -s, --session <SESSION>  Filter by session ID
  -a, --agg <AGG>          Aggregations: count, recency
  -l, --limit <LIMIT>      Max results (default: 20)
      --sort <SORT>        Order: count (default), recency
      --format <FORMAT>    Output: json (default), compact

query heat (File Heat Metrics)

tastematter query heat [OPTIONS]

OPTIONS:
  -t, --time <TIME>      Window: 30d (default), 14d, 60d, 90d
  -f, --files <FILES>    File pattern filter (glob-style)
  -l, --limit <LIMIT>    Max results (default: 50)
  -s, --sort <SORT>      Sort: heat (default), specificity, velocity, name
      --format <FORMAT>  Output: table (default), json, compact, csv

query timeline (Visualization Data)

tastematter query timeline [OPTIONS]

OPTIONS:
  -t, --time <TIME>      Time range: 7d (default), 14d, 30d
  -p, --files <FILES>    File pattern filter
  -c, --chain <CHAIN>    Filter by chain ID
  -l, --limit <LIMIT>    Max files (default: 30)
      --format <FORMAT>  Output: json (default), compact

query sessions (Session-Grouped)

tastematter query sessions [OPTIONS]

OPTIONS:
  -t, --time <TIME>      Time range: 7d (default), 14d, 30d
  -c, --chain <CHAIN>    Filter by chain ID
  -l, --limit <LIMIT>    Max sessions (default: 50)
      --format <FORMAT>  Output: json (default), compact

Other Query Commands

All support --format json.

Non-Query Commands

Last Updated: 2026-03-03 Version: 5.0 (Added graph-exec command: structural graph queries via Boa JS sandbox, codemode.* API reference, IIFE pattern, bash escaping guidance, common graph queries, MCP vs CLI guidance.)