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

Command	Purpose
init	First-time setup — parse sessions, build chains, index files
context <query>	Start here. Composed query across flex, heat, chains, sessions, timeline, co-access
query <subcommand>	Targeted queries (flex, heat, chains, etc.)
intel health	Check intel service health
intel name-chain <id>	Name a chain using AI
daemon status	Show daemon sync state + registration
daemon once	Run a single sync cycle

Query Subcommands

Command	Purpose
query flex --files "*pattern*"	Find files by path pattern
query flex --time 7d	Find files touched in time window
query heat --time 30d	File heat metrics (specificity, velocity, score, level)
query co-access <file>	Find files accessed together
query session <id>	All files in a session
query sessions --time 7d	Session-grouped data
query chains	List conversation chains
query timeline --time 7d	Timeline data for visualization
query verify <receipt>	Verify a previous query result
query receipts	List recent query receipts

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:

Need	Use
"What's happening with project X?"	context "X"
"What files are hot right now?"	query heat
"Find files matching a pattern"	query flex --files
"What did I work on this week?"	query flex --time 7d
"Show me session history"	query sessions
"What files go with this one?"	query co-access <file>

---

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

Need	Use
Structural queries (hubs, clusters, orphans, traversal)	graph-exec or MCP
Simple file search by name	Glob
Content search	Grep
File activity/heat over time	tastematter query heat
Co-access patterns	tastematter query co-access
Full project context	tastematter context

---

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

Need	Tool
Broad project context	tastematter context "<topic>"
Find files by path pattern	tastematter query flex --files
File heat/activity metrics	tastematter query heat
Find files by content	Grep
Read file contents	Read
Find files by name glob	Glob
Check recent changes	git log

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

Helps	Doesn't Help
"What files did I touch for project X?"	"What was I thinking about?"
"When was this file last accessed?"	"Why did I make this change?"
"What files are related to this one?"	"What's the best architecture for X?"
"What's the status of this work?"	"How should I fix this bug?"
"What files are hot/cold right now?"	"What's in my calendar?"

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

Command	Purpose
query search <term>	Keyword search in file paths
query file <path>	History for specific file
query co-access <path>	Files accessed with target
query chains	List conversation chains
query verify <receipt>	Verify a receipt
query receipts	List recent receipts

All support --format json.

Non-Query Commands

Command	Purpose
init	First-time setup (parse sessions + build chains + index files)
sync-git	Sync git commits from repository
parse-sessions	Parse JSONL session files (advanced)
build-chains	Build chain graph from sessions (advanced)
index-files	Build inverted file index (advanced)
watch	Watch directory for file changes
daemon once	Run single sync cycle
daemon start	Start daemon (foreground)
daemon status	Show sync state + registration
daemon install	Install daemon to run on login
daemon uninstall	Remove daemon from login
intel health	Check intel service health
intel name-chain <id>	Name a chain using AI
serve	Start HTTP API server

---

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