Context Orchestrator

A unified context extraction system that intelligently routes queries to three specialized CLI tools based on intent classification.

Quick Start

Commands (use directly):

• /context [query] - All sources in parallel (personal + research + code)
• /limitless [query] - Personal memory (lifelogs, meetings, conversations)
• /research [query] - Online documentation (facts, APIs, guides)
• /pieces [query] - Local code context (snippets, LTM, history)

Auto-Detection: The hook detects context-relevant prompts and suggests CLI commands.

Maintenance: See README.md for configuration, debugging, and upgrade instructions.

Context Sources

Slash Commands

Intent Classification

Domain Patterns

personal_context:
  patterns:
    - "what did (I|we) (discuss|talk|say|mention)"
    - "meeting|conversation|daily|yesterday|last week"
    - "lifelog|pendant|recording"
    - "(told me|mentioned|said) about"
  primary_cli: limitless
  fallback: pieces (if code-related)

online_research:
  patterns:
    - "documentation|docs for|how to"
    - "fact-check|verify|confirm|is it true"
    - "api|sdk|library|framework"
    - "best practice|implementation guide"
    - "pex|medical|grounding"
  primary_cli: research
  fallback: pieces (for code examples)

local_context:
  patterns:
    - "my code|code I wrote|my implementation"
    - "saved|snippet|previous solution"
    - "ltm|long-term memory|work history"
    - "what was I working on"
  primary_cli: pieces
  fallback: limitless (for discussion context)

Routing Decision Tree

User Request
    │
    ├── Explicit Command?
    │   ├── /context → Parallel Mode (all sources)
    │   ├── /limitless → Single Mode (limitless)
    │   ├── /research → Single Mode (research)
    │   └── /pieces → Single Mode (pieces)
    │
    ├── Intent Detection (from hook signal)
    │   ├── Personal patterns → limitless
    │   ├── Research patterns → research
    │   ├── Local patterns → pieces
    │   └── Multiple matches → Parallel Mode
    │
    └── No Clear Signal
        └── Skip (no external context needed)

Orchestration Modes

Single Source Mode

Use when intent clearly maps to one CLI:

mode: single
process:
  1. Identify primary CLI from intent
  2. Construct appropriate command
  3. Execute and capture output
  4. Return structured context
latency: 1-5 seconds

Parallel Mode

Use for /context or multi-domain queries:

mode: parallel
process:
  1. Spawn subagents for each relevant CLI
  2. Execute extractions in parallel
  3. Collect and merge results
  4. Deduplicate and rank by relevance
latency: Max of individual CLIs (5-15 seconds)

Augmented Mode (with Deep-Research)

Use when integrating with deep-research skill:

mode: augmented
process:
  1. Pre-enrichment: Gather personal/local context
  2. Hand off to deep-research Phase 1
  3. Use research CLI as primary in Phase 3
  4. Include pieces patterns in triangulation
integration_point: Phase 0 pre-enrichment

CLI Command Reference

Limitless (Personal Context)

# SEMANTIC SEARCH (Recommended) - Vector-based similarity
limitless semantic-search "ICU critical care" --types Lifelog,Chat,Person --limit 5 --json

# Hybrid search (semantic + full-text)
limitless search "medical exam" --mode hybrid --json

# Full-text search (keyword)
limitless lifelogs search "query" --limit 10 --format json

# Get today's snapshot
limitless workflow daily $(date +%Y-%m-%d) --format json

# Get recent activity (last N hours)
limitless workflow recent --hours 24 --format json

# Cross-source search
limitless workflow search "query" --format json

# Graph query (for relationships - FalkorDBLite)
limitless graph query "MATCH (p:Person)-[:SPOKE_IN]->(l:Lifelog) RETURN p.name, count(l) ORDER BY count(l) DESC LIMIT 5"

# Check embedding status
limitless index status

Research (Online Context)

# Technical documentation
research docs -t "query" -k "framework" --format json

# Fact verification
research fact-check -t "claim to verify" --graph

# Medical/PEX grounding
research pex-grounding -t "medical query"

# SDK/API reference
research sdk-api -t "api question"

# Academic search
research academic -t "research topic"

Pieces (Local Context)

# Ask with LTM (Long-Term Memory)
pieces ask "query" --ltm

# Semantic code search
pieces search --mode ncs "pattern"

# With file context
pieces ask "query" -f file1.py file2.py

# With saved materials
pieces ask "query" -m 1 2 3

# Full-text search
pieces search --mode fts "exact text"

Subagent Invocation

When spawning subagents for CLI extraction:

limitless_agent:
  type: general-purpose
  prompt: "Extract personal context using limitless CLI. Query: {query}"
  spec: agents/limitless-agent.md

research_agent:
  type: researcher
  prompt: "Extract online documentation using research CLI. Query: {query}"
  spec: agents/research-agent.md

pieces_agent:
  type: general-purpose
  prompt: "Extract local code context using pieces CLI. Query: {query}"
  spec: agents/pieces-agent.md

Session Caching

Cache Strategy

cache_location: ~/.claude/.context-cache/session-context.json

ttl_by_source:
  limitless: 30 minutes  # Personal data stable
  research: 60 minutes   # Docs change slowly
  pieces: 15 minutes     # Active development

cache_key_format: "{source}:{command_type}:{query_hash}"

invalidation:
  - New session starts
  - Explicit refresh request
  - TTL expiration

Cache Operations

# Check cache before CLI invocation
cache_key = f"{source}:{hash(query)}"
if cached := get_cache(cache_key):
    if not expired(cached):
        return cached.result

# After successful extraction
set_cache(cache_key, result, ttl=TTL_BY_SOURCE[source])

Integration with Deep-Research

Phase 0 Pre-Enrichment

When deep-research is invoked, optionally gather context first:

phase_0_context:
  trigger: User has relevant personal/local background

  actions:
    personal_background:
      cli: limitless
      query: "Search for relevant conversations about {topic}"

    local_patterns:
      cli: pieces
      query: "Find related code I've written about {topic}"

  output:
    format: Context briefing for Phase 1 scoping
    content:
      - Relevant past discussions
      - Related code implementations
      - Known constraints from experience

Integration Points

Output Format

Structured Context Response

{
  "source": "limitless|research|pieces",
  "query": "original query",
  "results": [
    {
      "title": "Result title",
      "content": "Extracted content...",
      "metadata": {
        "timestamp": "ISO8601",
        "confidence": 0.85,
        "source_type": "lifelog|document|snippet"
      }
    }
  ],
  "cached": false,
  "latency_ms": 1234
}

Multi-Source Response

{
  "mode": "parallel",
  "sources": {
    "limitless": { ... },
    "research": { ... },
    "pieces": { ... }
  },
  "merged_context": "Synthesized context from all sources...",
  "total_latency_ms": 3456
}

Error Handling

CLI Unavailability

on_cli_unavailable:
  limitless: "Limitless CLI not configured. Skip personal context."
  research: "Research CLI not available. Skip online lookup."
  pieces: "Pieces not running. Skip local context."

fallback: Continue with available sources

Timeout Handling

timeouts:
  limitless: 10s
  research: 15s
  pieces: 8s

on_timeout:
  action: Return partial results
  message: "Context extraction timed out. Proceeding with available data."

Usage Examples

Example 1: Personal Memory Query

User: "What did John say about the API deadline in yesterday's meeting?"

Process:

1. Intent detector signals: {need_limitless: true, confidence: 0.9}
2. Route to limitless single-source mode
3. Execute: limitless lifelogs search "John API deadline" --limit 5 --format json
4. Return structured context with relevant excerpts

Example 2: Technical Documentation

User: "How do I implement WebSocket authentication in Bun?"

Process:

1. Intent detector signals: {need_research: true, confidence: 0.85}
2. Route to research single-source mode
3. Execute: research docs -t "WebSocket authentication" -k "bun" --format json
4. Return documentation with code examples

Example 3: Multi-Source Context

User: /context What approach should I use for the auth refactor?

Process:

1. Explicit /context command triggers parallel mode
2. Spawn three subagents:
   • limitless: "auth refactor discussions"
   • research: "auth best practices"
   • pieces: "previous auth implementations"
3. Collect and merge results
4. Return comprehensive context from all sources

Best Practices

1. Cache First: Always check session cache before CLI invocation
2. Limit Results: Use --limit flags to avoid context overflow
3. JSON Output: Prefer JSON format for structured parsing
4. Timeout Protection: Set reasonable timeouts per CLI
5. Graceful Degradation: Continue with available sources if one fails
6. Relevance Ranking: Prioritize results by confidence/relevance score

Requirements

This skill requires three CLI tools. Graceful degradation occurs if any are missing:

Verify availability: Run bash ~/.claude/hooks/session-context-primer.sh

Hooks Integration

This skill uses two hooks for automatic context detection:

UserPromptSubmit Hook

• File: ~/.claude/hooks/context-intent-detector.ts
• Trigger: Every user prompt
• Function: Pattern matching to detect context-relevant queries
• Output: JSON signal with detected sources and confidence
• Timeout: 1.5s

SessionStart Hook

• File: ~/.claude/hooks/session-context-primer.sh
• Trigger: Session initialization
• Function: Validates CLI availability and initializes cache
• Output: System prompt with available sources
• Timeout: 5s

Progressive Loading

This skill uses progressive disclosure to optimize context efficiency:

Troubleshooting

Skill Not Triggering

1. Verify hooks registered: grep context ~/.claude/settings.json
2. Check pattern matching: echo '{"prompt":"your query"}' | bun run ~/.claude/hooks/context-intent-detector.ts
3. Use explicit command: /context <query>

CLI Unavailable

1. Run session primer: bash ~/.claude/hooks/session-context-primer.sh
2. Check individual CLIs:
   • limitless config show (needs API key)
   • research --help
   • pieces mcp status (needs PiecesOS)

Subagents Timing Out

1. Increase timeout in settings.json (default 1.5-5s)
2. Check CLI latency individually
3. View cache: cat ~/.claude/.context-cache/session-context.json

Cache Issues

1. Clear cache: python3 ~/.claude/skill-db/context-orchestrator/scripts/cache-manager.py clear
2. View stats: python3 ~/.claude/skill-db/context-orchestrator/scripts/cache-manager.py stats

Additional Resources

• Configuration & Debugging: See README.md
• Deep-Research Integration: See DEEP-RESEARCH-INTEGRATION.md
• CLI Command Reference: See references/cli-commands.md
• Security Review: See docs/SECURITY-REVIEW.md
• Skill Metadata: See skill.yaml