context-orchestrator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Context Orchestrator

上下文协调器

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

一个统一的上下文提取系统，可根据意图分类智能地将查询路由到三个专用CLI工具。

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 [查询语句]
```
- 并行检索所有源（个人+研究+代码）
```
/limitless [查询语句]
```
- 个人记忆上下文（生活日志、会议、对话）
```
/research [查询语句]
```
- 在线文档上下文（事实资料、API、指南）
```
/pieces [查询语句]
```
- 本地代码上下文（代码片段、长期记忆LTM、开发历史）

自动检测：钩子会检测与上下文相关的提示，并建议对应的CLI命令。

维护：配置、调试和升级说明请查看

README.md

。

Context Sources

数据源

Source	CLI	Data Type	Best For
Personal	`limitless`	Life transcripts, meetings, conversations	"What did I discuss...", "Yesterday's meeting..."
Online	`research`	Documentation, facts, academic papers	"How to implement...", "Verify that..."
Local	`pieces`	Code snippets, work history, LTM	"My previous implementation...", "Code I wrote..."

数据源	CLI工具	数据类型	适用场景
个人数据源	`limitless`	生活记录文本、会议记录、对话内容	"我之前讨论过什么..."、"昨天的会议..."
在线数据源	`research`	文档、事实资料、学术论文	"如何实现..."、"验证是否..."
本地数据源	`pieces`	代码片段、工作历史、长期记忆LTM	"我之前的实现方案..."、"我写的代码..."

Slash Commands

斜杠命令

Command	Description	Mode
`/context [query]`	Multi-source extraction	Parallel (all relevant)
`/limitless [query]`	Personal life context	Single (limitless)
`/research [query]`	Online documentation	Single (research)
`/pieces [query]`	Local code context	Single (pieces)

命令	描述	模式
`/context [查询语句]`	多源上下文提取	并行模式（所有相关源）
`/limitless [查询语句]`	个人生活上下文	单源模式（仅limitless）
`/research [查询语句]`	在线文档上下文	单源模式（仅research）
`/pieces [查询语句]`	本地代码上下文	单源模式（仅pieces）

Intent Classification

意图分类

Domain Patterns

领域模式

yaml

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)

yaml

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)

用户请求
    │
    ├── 是否为显式命令？
    │   ├── /context → 并行模式（所有源）
    │   ├── /limitless → 单源模式（仅limitless）
    │   ├── /research → 单源模式（仅research）
    │   └── /pieces → 单源模式（仅pieces）
    │
    ├── 意图检测（来自钩子信号）
    │   ├── 匹配个人模式 → 路由到limitless
    │   ├── 匹配研究模式 → 路由到research
    │   ├── 匹配本地模式 → 路由到pieces
    │   └── 匹配多个模式 → 并行模式
    │
    └── 无明确信号
        └── 跳过（无需外部上下文）

Orchestration Modes

协调模式

Single Source Mode

单源模式

Use when intent clearly maps to one CLI:

yaml

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

当意图明确匹配某个CLI时使用：

yaml

mode: single
process:
  1. 根据意图确定主CLI工具
  2. 构造合适的命令
  3. 执行并捕获输出
  4. 返回结构化上下文
latency: 1-5 seconds

Parallel Mode

并行模式

Use for

/context

or multi-domain queries:

yaml

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)

用于

/context

命令或跨领域查询：

yaml

mode: parallel
process:
  1. 为每个相关CLI生成子代理
  2. 并行执行提取操作
  3. 收集并合并结果
  4. 去重并按相关性排序
latency: Max of individual CLIs (5-15 seconds)

Augmented Mode (with Deep-Research)

增强模式（结合深度研究）

Use when integrating with deep-research skill:

yaml

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

当与深度研究技能集成时使用：

yaml

mode: augmented
process:
  1. 预增强：收集个人/本地上下文
  2. 移交到深度研究第1阶段
  3. 在第3阶段将research CLI作为主工具
  4. 在三角验证中加入pieces模式
integration_point: Phase 0 pre-enrichment

CLI Command Reference

CLI命令参考

Limitless (Personal Context)

Limitless（个人上下文）

bash

undefined

bash

undefined

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)

获取近期活动（最近N小时）

limitless workflow recent --hours 24 --format json

Cross-source search

跨源搜索

limitless workflow search "query" --format json

Graph query (for relationships - FalkorDBLite)

图查询（用于关系查询 - 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

undefined

limitless index status

undefined

Research (Online Context)

Research（在线上下文）

bash

undefined

bash

undefined

Technical documentation

技术文档查询

research docs -t "query" -k "framework" --format json

Fact verification

事实验证

research fact-check -t "claim to verify" --graph

Medical/PEX grounding

医学/PEX基础验证

research pex-grounding -t "medical query"

SDK/API reference

SDK/API参考查询

research sdk-api -t "api question"

Academic search

学术搜索

research academic -t "research topic"

undefined

research academic -t "research topic"

undefined

Pieces (Local Context)

Pieces（本地上下文）

bash

undefined

bash

undefined

Ask with LTM (Long-Term Memory)

结合长期记忆LTM查询

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"

undefined

pieces search --mode fts "exact text"

undefined

Subagent Invocation

子代理调用

When spawning subagents for CLI extraction:

yaml

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

为CLI提取操作生成子代理时：

yaml

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

缓存策略

yaml

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

yaml

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

缓存操作

python

undefined

python

undefined

Check cache before CLI invocation

在调用CLI前检查缓存

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

undefined

set_cache(cache_key, result, ttl=TTL_BY_SOURCE[source])

undefined

Integration with Deep-Research

与深度研究的集成

Phase 0 Pre-Enrichment

第0阶段：预增强

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

yaml

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

当调用深度研究时，可先收集上下文：

yaml

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

集成点

Deep-Research Phase	Context Integration
Phase 1 (Scoping)	Include personal context as background
Phase 3 (Querying)	Use research CLI as primary retrieval
Phase 4 (Triangulation)	Add pieces code patterns as evidence

深度研究阶段	上下文集成方式
第1阶段（范围界定）	将个人上下文作为背景信息纳入
第3阶段（查询执行）	使用research CLI作为主要检索工具
第4阶段（三角验证）	将pieces代码模式作为证据加入

Output Format

输出格式

Structured Context Response

结构化上下文响应

json

{
  "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
}

json

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

多源响应

json

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

json

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

Error Handling

错误处理

CLI Unavailability

CLI不可用

yaml

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

yaml

on_cli_unavailable:
  limitless: "Limitless CLI未配置。跳过个人上下文检索。"
  research: "Research CLI不可用。跳过在线查询。"
  pieces: "Pieces未运行。跳过本地上下文检索。"

fallback: Continue with available sources

Timeout Handling

超时处理

yaml

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

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

yaml

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

示例1：个人记忆查询

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

Process:

Intent detector signals:
```
{need_limitless: true, confidence: 0.9}
```
Route to limitless single-source mode

Execute:

limitless lifelogs search "John API deadline" --limit 5 --format json

Return structured context with relevant excerpts

用户："昨天的会议中，John关于API截止日期说了什么？"

流程：

意图检测器发出信号：
```
{need_limitless: true, confidence: 0.9}
```
路由到limitless单源模式

执行命令：

limitless lifelogs search "John API deadline" --limit 5 --format json

返回包含相关片段的结构化上下文

Example 2: Technical Documentation

示例2：技术文档查询

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

Process:

Intent detector signals:
```
{need_research: true, confidence: 0.85}
```
Route to research single-source mode

Execute:

research docs -t "WebSocket authentication" -k "bun" --format json

Return documentation with code examples

用户："如何在Bun中实现WebSocket身份验证？"

流程：

意图检测器发出信号：
```
{need_research: true, confidence: 0.85}
```
路由到research单源模式

执行命令：

research docs -t "WebSocket authentication" -k "bun" --format json

返回包含代码示例的文档内容

Example 3: Multi-Source Context

示例3：多源上下文查询

User:

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

Process:

Explicit
```
/context
```
command triggers parallel mode
Spawn three subagents:
- limitless: "auth refactor discussions"
- research: "auth best practices"
- pieces: "previous auth implementations"
Collect and merge results
Return comprehensive context from all sources

用户：

/context 我应该采用什么方法来重构身份验证功能？

流程：

显式的
```
/context
```
命令触发并行模式
生成三个子代理：
- limitless："身份验证重构相关讨论"
- research："身份验证最佳实践"
- pieces："之前的身份验证实现方案"
收集并合并结果
返回来自所有源的综合上下文

Best Practices

最佳实践

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

优先查缓存：调用CLI前始终检查会话缓存
限制结果数量：使用
```
--limit
```
参数避免上下文过载
优先JSON输出：选择JSON格式以便结构化解析
设置超时保护：为每个CLI设置合理的超时时间
优雅降级：若某个源不可用，继续使用可用源的结果
相关性排序：按置信度/相关性分数优先展示结果

Requirements

依赖要求

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

CLI	Installation	Required For
`limitless`	`bun run ~/Projects/limitless-cli/bin/limitless.ts`	Personal context
`research`	`~/.local/bin/research`	Online documentation
`pieces`	`/opt/homebrew/bin/pieces` + PiecesOS running	Local code/LTM

Verify availability: Run

bash ~/.claude/hooks/session-context-primer.sh

本技能需要三个CLI工具。若缺少其中某个，系统会自动优雅降级：

CLI工具	安装方式	用途
`limitless`	`bun run ~/Projects/limitless-cli/bin/limitless.ts`	个人上下文检索
`research`	`~/.local/bin/research`	在线文档检索
`pieces`	`/opt/homebrew/bin/pieces` + 运行PiecesOS	本地代码/长期记忆LTM检索

验证可用性：运行

bash ~/.claude/hooks/session-context-primer.sh

Hooks Integration

钩子集成

This skill uses two hooks for automatic context detection:

本技能使用两个钩子实现自动上下文检测：

UserPromptSubmit Hook

UserPromptSubmit钩子

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

文件路径：

~/.claude/hooks/context-intent-detector.ts

触发时机：每次用户提交提示时
功能：通过模式匹配检测与上下文相关的查询
输出：包含检测到的数据源和置信度的JSON信号
超时时间：1.5秒

SessionStart Hook

SessionStart钩子

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

文件路径：

~/.claude/hooks/session-context-primer.sh

触发时机：会话初始化时
功能：验证CLI可用性并初始化缓存
输出：包含可用数据源的系统提示
超时时间：5秒

Progressive Loading

渐进式加载

This skill uses progressive disclosure to optimize context efficiency:

File	Purpose	When Loaded
`SKILL.md`	Quick start, command reference	Always (main skill)
`README.md`	Configuration, debugging, upgrades	On maintenance request
`agents/*.md`	Subagent specifications	When parallel mode triggered
`references/*.md`	Detailed CLI documentation	When deep reference needed
`scripts/*.py`	Cache/metrics utilities	On explicit invocation

本技能采用渐进式披露策略优化上下文效率：

文件	用途	加载时机
`SKILL.md`	快速开始、命令参考	始终加载（主技能文档）
`README.md`	配置、调试、升级说明	收到维护请求时加载
`agents/*.md`	子代理规范	触发并行模式时加载
`references/*.md`	详细CLI文档	需要深度参考时加载
`scripts/*.py`	缓存/指标工具	显式调用时加载

Troubleshooting

故障排除

Skill Not Triggering

技能未触发

Verify hooks registered:
```
grep context ~/.claude/settings.json
```

Check pattern matching:

echo '{"prompt":"your query"}' | bun run ~/.claude/hooks/context-intent-detector.ts

Use explicit command:
```
/context <query>
```

验证钩子已注册：
```
grep context ~/.claude/settings.json
```

检查模式匹配：

echo '{"prompt":"你的查询语句"}' | bun run ~/.claude/hooks/context-intent-detector.ts

使用显式命令：
```
/context <查询语句>
```

CLI Unavailable

CLI工具不可用

Run session primer:

bash ~/.claude/hooks/session-context-primer.sh

Check individual CLIs:

```
limitless config show
```
(needs API key)
```
research --help
```
```
pieces mcp status
```
(needs PiecesOS)

运行会话初始化脚本：

bash ~/.claude/hooks/session-context-primer.sh

单独检查每个CLI：
- ```
limitless config show
```
  （需要API密钥）
- ```
research --help
```
- ```
pieces mcp status
```
  （需要运行PiecesOS）

Subagents Timing Out

子代理超时

Increase timeout in settings.json (default 1.5-5s)
Check CLI latency individually

View cache:

cat ~/.claude/.context-cache/session-context.json

在settings.json中增加超时时间（默认1.5-5秒）
单独检查每个CLI的延迟

查看缓存内容：

cat ~/.claude/.context-cache/session-context.json

Cache Issues

缓存问题

Clear cache:

python3 ~/.claude/skill-db/context-orchestrator/scripts/cache-manager.py clear

View stats:

python3 ~/.claude/skill-db/context-orchestrator/scripts/cache-manager.py stats

清除缓存：

python3 ~/.claude/skill-db/context-orchestrator/scripts/cache-manager.py clear

查看缓存统计：

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

配置与调试：查看README.md
深度研究集成：查看DEEP-RESEARCH-INTEGRATION.md
CLI命令参考：查看references/cli-commands.md
安全审查：查看docs/SECURITY-REVIEW.md
技能元数据：查看skill.yaml