ContextStream MCP Server
官方跨工作階段的AI程式碼輔助工具持久記憶與語意搜尋
文件
文件 · 瀏覽章節
01 · 設定精靈
一個指令，完整設定。
執行一個指令即可完成驗證（瀏覽器/裝置登入）、建立 API 金鑰、產生規則，並為你的工具寫入正確的 MCP 設定（包含 VS Code 的 servers schema）。
terminal · terminal · macOS / Linux
curl -fsSL https://contextstream.io/scripts/mcp.sh | bash
terminal · powershell · Windows
irm https://contextstream.io/scripts/mcp.ps1 | iex
已經安裝過了？重新執行設定精靈
terminal · terminal · 重新執行
contextstream-mcp setup
功能說明： 寫入 MCP 設定（VS Code servers、Cursor/Cline 等 mcpServers）、產生規則（標準/增強），並可將專案連結至工作區。
整合工具集： 設定精靈預設會配置約 11 個整合領域工具（約減少 75% token 用量）。可選用：router 模式（約 2 個 meta-tool，最精簡）。請參閱完整工具目錄。
預覽變更而不寫入檔案：contextstream-mcp setup --dry-run
團隊工作流程
共享記憶、技能與情境浮現。
團隊帳號獲得的遠不止共享專案。在 contextstream-mcp setup 期間，設定精靈會偵測團隊功能並浮現工作區提示。在你的編輯器中，每次 session(action="context") 呼叫都可以包含團隊建議、治理提示、優先級訊號以及連結的產出物。
選擇共享工作區
在設定期間將每個儲存庫連結至團隊工作區，讓索引、決策和工單保持同步。
分享團隊技能
skill(action="share", scope="team") 會發布可重複使用的工作流程，隊友在 session(action="context") 中會自動配對。
切換執行範圍
雙情境帳號可在 MCP 中使用 --account-mode=team|personal|auto 或 session set_account_mode。
使用實體追蹤工作
工單、交接、事件和發布使用索引參考——跨工作階段和隊友皆可持久保存。
預設為託管遠端。 本機二進位 MCP 僅供復原使用——在明確需要時設定 CONTEXTSTREAM_ALLOW_LOCAL_MCP=1。請參閱團隊設定了解邀請/角色，以及登入後檢查清單。
CLI 捷徑
非互動式指令（CI 與重新整理）。
在升級、團隊入職、憑證輪換或工作區變更後，無需互動精靈即可執行這些指令——也會在 contextstream-mcp --help 中浮現。
| 指令 | 使用時機 |
|---|---|
| contextstream-mcp update-hooks --scope=global | 升級或加入團隊工作區後——重新整理 PreToolUse/UserPromptSubmit hooks。 |
| contextstream-mcp update-rules --scope=all | 使用最新的團隊工作流程指引重新產生 .cursorrules / CLAUDE.md / AGENTS.md。 |
| contextstream-mcp update-configs --scope=global | API 金鑰或工作區變更後重新寫入 MCP 設定。 |
| contextstream-mcp migrate-remote --scope=all | 將舊版本機 stdio 設定轉換為託管遠端傳輸。 |
| contextstream-mcp detect-editors --format=json | 腳本化偵測已安裝的編輯器（引導/CI）。 |
| contextstream-mcp generate-configs --transport=remote --preauth | 輸出 JSON 設定內容而不寫入檔案。 |
| contextstream-mcp configure --transcripts=on --scope=all | 非互動式設定轉錄擷取預設值。 |
terminal · 帳號模式 · 團隊 vs 個人
# Default: follow account (auto)
contextstream-mcp --account-mode=auto
# Force team-scoped reads/writes
contextstream-mcp --account-mode=team
# Or set once in shell profile:
export CONTEXTSTREAM_ACCOUNT_MODE=team
02 · 手動設定
依客戶端設定。
請根據客戶端使用正確的格式（VS Code 使用 servers；許多其他客戶端使用 mcpServers）。
整合工具集： 預設情況下，伺服器會公開約 11 個整合領域工具（相較於舊版細粒度工具，約減少 75% token 用量）。若需更少的工具，請在 env 區塊中加入 "CONTEXTSTREAM_PROGRESSIVE_MODE": "true"，以使用約 2 個路由 meta-tool。請參閱完整工具目錄。
跳轉至你的工具
Cursor / VS CodeWindsurfCodex CLIOpenCode CLIClaude CodeClaude DesktopClineKilo CodeRoo CodeAntigravity
什麼是 MCP？
一個開放的通訊協定，專為 AI 設計。
模型上下文協定 (MCP) 是一項開放標準，允許 AI 助理連接外部工具和資料來源。透過 ContextStream 的 MCP 伺服器，你的 AI 工具可以：
- 記住跨工作階段的對話和決策
- 以語意方式搜尋你的程式碼庫和文件
- 建立並查詢知識圖譜
- 在不同的 AI 工具之間共享情境
自然語言
只需開口問。AI 會處理工具。
你不需要記住工具名稱或直接呼叫它們。只需用簡單的英文描述你的需求，你的 AI 助理就會自動使用正確的工具。
自然地提問
- · "工作階段摘要"
- · "我們對身份驗證做了什麼決定？"
- · "記住我們正在使用 PostgreSQL"
- · "搜尋付款程式碼"
AI 處理其餘部分
- · 自動尋找相關情境
- · 需要時回憶過去的決策
- · 將重要資訊儲存到記憶體
- · 搜尋程式碼和文件
範例 · "工作階段摘要"
AI 理解你的意圖，並在幕後呼叫適當的 ContextStream 工具。
先決條件
你需要準備什麼。
- 一個 ContextStream 帳號（設定精靈可以透過瀏覽器登入建立 API 金鑰）。
豐富情境
GitHub + Slack 整合
MCP 為你的 AI 提供持久記憶。連接 GitHub 和 Slack 能讓記憶更加豐富——你的 AI 在回答問題時可以自動參考 PR、議題和團隊討論。
自動情境豐富化
當你呼叫 context_smart 或 session_smart_search 時，相關的 GitHub 議題、PR 和 Slack 討論會自動包含在內。無需額外工具。
GitHubSync 議題、PR、發布和評論。決策會自動從討論中提取。SlackSync 頻道和討論串。高參與度的對話會被評分並優先處理。
提示範例
- · "我們對身份驗證做了什麼決定？" — 從 GitHub 議題 + Slack 討論串中尋找決策
- · "顯示付款系統的近期活動" — 浮現 PR、議題和團隊討論
- · "我們從上次停機中學到了什麼教訓？" — 從 Slack 和 GitHub 擷取洞察
- · "給我一份 GitHub 活動的週摘要" — 使用
integration(provider="github", action="summary", ...) - · "搜尋所有整合中有關資料庫遷移的討論" — 使用
integration(provider="all", action="search", ...) - · "給我一份跨所有來源的團隊週摘要" — 使用
integration(provider="all", action="summary", ...)
整合工具動作快速參考
使用 integration(provider="github|slack|all", action="...")
GitHub (provider="github")
action="stats"— 統計資料和同步狀態action="search"— 使用狀態/時間範圍篩選器搜尋action="activity"— 活動摘要（天數篩選）action="knowledge"— 提取的決策/經驗教訓action="summary"— 每週/每月摘要action="repos"— 列出已同步的儲存庫action="issues"— 列出議題/PR
Slack (provider="slack")
action="stats"— 統計資料和同步狀態action="search"— 使用頻道/時間範圍篩選器搜尋action="discussions"— 高參與度討論串action="knowledge"— 提取的決策/經驗教訓action="summary"— 每週/每月摘要action="channels"— 列出已同步的頻道
跨來源 (provider="all")
action="status"— 檢查所有已連接整合的同步狀態和健康狀況action="search"— 在一個查詢中跨所有已連接整合進行搜尋action="summary"— 跨所有來源的統一活動摘要（天數篩選）action="knowledge"— 從所有來源取得決策、經驗教訓和洞察
客戶端 · Cursor / VS Code
Cursor / VS Code
Cursor 和 VS Code 使用不同的 MCP 設定 schema。Cursor 仍使用本機 MCP 程序，但 VS Code/Copilot 現在可以直接透過 HTTP 使用託管的 ContextStream MCP。
terminal · .cursor/mcp.json（專案）或 ~/.cursor/mcp.json（全域）
{
"mcpServers": {
"contextstream": {
"command": "contextstream-mcp",
"env": {
"CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
"CONTEXTSTREAM_API_KEY": "your_api_key"
}
}
}
}
建議用於 VS Code / Copilot：一鍵遠端安裝
安裝託管的 ContextStream MCP，讓 VS Code 在首次使用時處理 OAuth。無需在本機二進位檔或 API 金鑰存在於 .vscode/mcp.json 中。
terminal · .vscode/mcp.json（VS Code 原生 MCP，遠端）
{
"servers": {
"contextstream": {
"type": "http",
"url": "https://mcp.contextstream.io/mcp?default_context_mode=fast"
}
}
}
偏好命令列？使用 code --add-mcp 新增遠端伺服器
terminal · terminal
code --add-mcp '{"name":"contextstream","type":"http","url":"https://mcp.contextstream.io/mcp?default_context_mode=fast"}'
首次使用時，VS Code 應會提示授權 ContextStream，然後自動完成設定。
自行託管？將相同的遠端設定指向你自己的 MCP 閘道 URL，而非 https://mcp.contextstream.io/mcp?default_context_mode=fast。
客戶端 · OpenCode CLI
OpenCode CLI
若要將 ContextStream 與 OpenCode CLI 搭配使用，請將 MCP 伺服器設定新增至你的 ~/.config/opencode/opencode.json 檔案（或專案根目錄中的 opencode.json）：
terminal · ~/.config/opencode/opencode.json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"contextstream": {
"type": "local",
"command": ["contextstream-mcp"],
"enabled": true,
"environment": {
"CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
"CONTEXTSTREAM_API_KEY": "your_api_key"
}
}
}
}
編輯設定後，重新啟動 OpenCode 以便載入 ContextStream MCP 伺服器。
客戶端 · Codex CLI
Codex CLI
若要將 ContextStream 與 Codex CLI 搭配使用，請將 MCP 伺服器設定新增至你的 ~/.codex/config.toml 檔案：
terminal · ~/.codex/config.toml
[mcp_servers.contextstream]
command = "contextstream-mcp"
args = []
[mcp_servers.contextstream.env]
CONTEXTSTREAM_API_URL = "https://api.contextstream.io"
CONTEXTSTREAM_API_KEY = "your_api_key"
編輯設定後，重新啟動 Codex 以便載入 ContextStream MCP 伺服器。
客戶端 · Claude Code
Claude Code (CLI)
在你的專案目錄中執行此指令，將 ContextStream 新增至 Claude Code：
terminal · terminal
claude mcp add --transport stdio contextstream --env CONTEXTSTREAM_API_URL=https://api.contextstream.io --env CONTEXTSTREAM_API_KEY=your_api_key -- contextstream-mcp
Windows 注意事項（原生 Windows，非 WSL）：在 -- 之後使用 cmd /c contextstream-mcp。
替代方案：add-json (stdio)
terminal · terminal · add-json
claude mcp add-json contextstream \
'{"type":"stdio","command":"contextstream-mcp","args":[],"env":{"CONTEXTSTREAM_API_URL":"https://api.contextstream.io","CONTEXTSTREAM_API_KEY":"your_api_key"}}'
提示：對於團隊設定，建議使用已提交的 .mcp.json 檔案（專案範圍），而非將金鑰嵌入 shell 歷史記錄中。
這會將 ContextStream 新增至你專案路徑下的 ~/.claude.json，使其在該目錄中工作時可用。
MCP 範圍選項
- · 本機（預設）：僅限你個人，僅限目前專案 → 儲存在專案路徑下的
~/.claude.json。 - · 使用者（
--scope user）：僅限你個人，所有專案 → 全域儲存在~/.claude.json。 - · 專案（
--scope project）：與團隊共享 → 儲存在專案根目錄的.mcp.json（提交至 git）。
對於團隊共享，使用專案範圍來建立可提交至 git 的 .mcp.json 檔案：
terminal · .mcp.json（專案範圍）
{
"mcpServers": {
"contextstream": {
"command": "contextstream-mcp",
"env": {
"CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
"CONTEXTSTREAM_API_KEY": "your_api_key"
}
}
}
}
新增 MCP 伺服器後，重新啟動 Claude Code 以使變更生效。使用 claude mcp list 驗證伺服器是否已載入。對於來自 .mcp.json 的專案範圍伺服器，Claude Code 會在首次使用時提示核准。
客戶端 · Claude Desktop
Claude Desktop（圖形化應用程式）
將 ContextStream 新增至 Claude Desktop 應用程式：
macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
Windows： %APPDATA%\Claude\claude_desktop_config.json
terminal · claude_desktop_config.json
{
"mcpServers": {
"contextstream": {
"command": "contextstream-mcp",
"env": {
"CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
"CONTEXTSTREAM_API_KEY": "your_api_key"
}
}
}
}
編輯設定後，結束並重新啟動 Claude Desktop 以使變更生效。
客戶端 · Windsurf
Windsurf
透過編輯全域 MCP 設定檔將 ContextStream 新增至 Windsurf：
設定檔： ~/.codeium/windsurf/mcp_config.json
terminal · ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"contextstream": {
"command": "contextstream-mcp",
"env": {
"CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
"CONTEXTSTREAM_API_KEY": "your_api_key"
}
}
}
}
規則檔案
- · 全域：
~/.codeium/windsurf/memories/global_rules.md - · 專案：
.windsurf/rules/contextstream.md
Windsurf 支援 hooks 以自動強制執行 ContextStream 規則。編輯設定後，重新啟動 Windsurf 以使變更生效。
客戶端 · Cline
Cline
將 ContextStream 新增至你的 Cline MCP 設定。點擊 Cline 中的 MCP Servers 圖示，選擇「Configure」分頁，然後點擊「Configure MCP Servers」進行編輯：
terminal · cline_mcp_settings.json
{
"mcpServers": {
"contextstream": {
"command": "contextstream-mcp",
"env": {
"CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
"CONTEXTSTREAM_API_KEY": "your_api_key"
}
}
}
}
編輯設定後，重新啟動 Cline 以使變更生效。你也可以使用 alwaysAllow 來自動核准特定工具。
客戶端 · Kilo Code
Kilo Code
將 ContextStream 新增至你的 Kilo Code MCP 設定。你可以全域或按專案設定 MCP 伺服器：
全域： 點擊 Settings → MCP Servers → Installed → Edit Global MCP 以開啟 mcp_settings.json
專案： 專案根目錄中的 .kilocode/mcp.json
terminal · .kilocode/mcp.json（或 mcp_settings.json）
{
"mcpServers": {
"contextstream": {
"command": "contextstream-mcp",
"env": {
"CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
"CONTEXTSTREAM_API_KEY": "your_api_key"
}
}
}
}
專案層級設定優先於全域設定。編輯後重新啟動 Kilo Code。
客戶端 · Roo Code
Roo Code
將 ContextStream 新增至你的 Roo Code MCP 設定。你可以全域或按專案設定 MCP 伺服器：
全域： 點擊設定圖示 → Edit Global MCP 以開啟 mcp_settings.json
專案： 專案根目錄中的 .roo/mcp.json
terminal · .roo/mcp.json（或 mcp_settings.json）
{
"mcpServers": {
"contextstream": {
"command": "contextstream-mcp",
"env": {
"CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
"CONTEXTSTREAM_API_KEY": "your_api_key"
}
}
}
}
專案層級設定優先於全域設定。編輯後重新啟動 Roo Code。
客戶端 · Antigravity
Antigravity (Google)
Antigravity 使用專案範圍的 .mcp.json 檔案，格式與 Cursor/Claude Desktop 相同：
terminal · .mcp.json（專案根目錄）
{
"mcpServers": {
"contextstream": {
"command": "contextstream-mcp",
"env": {
"CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
"CONTEXTSTREAM_API_KEY": "your_api_key"
}
}
}
}
Windows 使用者：使用 cmd 包裝器
terminal · .mcp.json（Windows）
{
"mcpServers": {
"contextstream": {
"command": "cmd",
"args": ["/c", "contextstream-mcp"],
"env": {
"CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
"CONTEXTSTREAM_API_KEY": "your_api_key"
}
}
}
}
規則檔案
- · 全域：
~/.gemini/GEMINI.md - · 工作區：
.agent/rules/contextstream.md
透過「...」選單 →「MCP Servers」→「View raw config」存取以驗證你的設定。編輯後重新啟動 Antigravity。
編輯器規則
改善自動 ContextStream 使用
建議
ContextStream 的自動情境功能會在你使用任何 ContextStream 工具時自動載入工作區情境。然而，AI 助理可能不會總是主動儲存決策或回憶過去的情境。新增編輯器 AI 規則可提高一致性，並確保 AI 在整個對話過程中自動擷取決策、偏好設定和重要情境。
重要：MCP 工具命名慣例
不同的 AI 工具對 MCP 工具使用不同的命名慣例。使用錯誤的格式將導致找不到工具。
| AI 工具 | 格式 | 範例 |
|---|---|---|
| Claude Code | mcp____ | mcp__contextstream__session_init |
| Codex CLI / OpenCode CLI | （原始名稱） | session_init |
| Cursor / Windsurf / Cline | （原始名稱） | session_init |
| Kilo Code / Roo Code | （原始名稱） | session_init |
摘要： 只有 Claude Code 使用 mcp__contextstream__ 前綴。所有其他工具使用原始工具名稱。
你可以在兩個層級新增 ContextStream 規則：全域（適用於所有專案）或專案（適用於單一專案）。
全域規則（所有專案）
新增一次，它們就會自動套用至每個專案：
| 編輯器 | 全域規則位置 |
|---|---|
| Cursor | Settings → General → Rules for AI |
| Windsurf | ~/.codeium/windsurf/memories/global_rules.md |
| Cline | ~/Documents/Cline/Rules/ |
| Kilo Code | ~/.kilocode/rules/ |
| Roo Code | ~/.roo/rules/ |
| Claude Code | ~/.claude/CLAUDE.md |
| Codex CLI | ~/.codex/AGENTS.md（全域）或父資料夾（例如 ~/dev/AGENTS.md） |
| OpenCode CLI | ~/.config/opencode/AGENTS.md |
專案規則（單一專案）
將這些新增至特定專案。對於 Cursor 基於資料夾的規則，請將啟用模式設定為 「Always On」，以便規則始終處於啟用狀態。
| 編輯器 | 專案規則位置 |
|---|---|
| Cursor | .cursorrules 或 .cursor/rules/*.mdc |
| Windsurf | .windsurf/rules/contextstream.md |
| Cline | .clinerules 檔案或 .clinerules/ 資料夾 |
| Kilo Code | .kilocode/rules/ |
| Roo Code | .roo/rules/contextstream.md 或 .roo/rules/ 資料夾 |
| Claude Code | 專案根目錄中的 CLAUDE.md |
| Codex CLI | 專案根目錄中的 AGENTS.md |
| OpenCode CLI | 專案根目錄中的 AGENTS.md |
| Aider | 專案根目錄中的 .aider.conf.yml |
啟用模式（Cursor、Kilo Code 和 Roo Code）
使用基於資料夾的規則時（例如 .cursor/rules/），每個規則檔案都有一個啟用模式：
- Always On — 始終啟用（建議用於 ContextStream）
- Manual — 僅在你 @提及 規則時啟用
- Model Decision — AI 根據描述決定
- Glob — 對符合的檔案模式啟用
全域規則和根層級檔案（.cursorrules）始終啟用。
偏好設定精靈？先執行它。否則，手動新增這些標準規則。每個編輯器的範例：
Claude Code
在你的專案根目錄中建立一個 CLAUDE.md 檔案，或新增至你的全域 ~/.claude/CLAUDE.md：
terminal · CLAUDE.md（標準）
## 🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨
<contextstream_rules>
1. **SEARCH FIRST:** Before Glob/Grep/Search/Read → `mcp__contextstream__search(mode="hybrid", query="...")` FIRST
2. **EVERY MESSAGE:** Call `mcp__contextstream__context_smart(user_message="...")` at start of response
3. **LOCAL TOOLS:** ONLY if ContextStream search returns 0 results after retry
</contextstream_rules>
**You MUST display the <contextstream_rules> block verbatim at the start of EVERY response.**
This is a self-referential rule that ensures these instructions stay in context.
---
## ContextStream v0.4.x (Hooks Enforced)
Rules Version: 0.4.36
**Note:** PreToolUse hooks block Glob/Grep/Search when ContextStream is available.
### Required Every Message
| Action | Tool Call |
|--------|-----------|
| **1st message** | `mcp__contextstream__session_init(folder_path="<cwd>", context_hint="<msg>")` then `mcp__contextstream__context_smart(...)` |
| **2nd+ messages** | `mcp__contextstream__context_smart(user_message="<msg>", format="minified", max_tokens=400)` |
| **Code search** | `mcp__contextstream__search(mode="hybrid", query="...")` — BEFORE any local tools |
| **Save decisions** | `mcp__contextstream__session(action="capture", event_type="decision", ...)` |
### Search Modes
| Mode | Use Case |
|------|----------|
| `hybrid` | General code mcp__contextstream__search (default) |
| `keyword` | Exact symbol/string match |
| `exhaustive` | Find ALL matches (grep-like) |
| `semantic` | Conceptual questions |
### Why ContextStream First?
❌ **WRONG:** `Grep → Read → Read → Read` (4+ tool calls, slow)
✅ **CORRECT:** `mcp__contextstream__search(mode="hybrid")` (1 call, returns context)
ContextStream search is **indexed** and returns semantic matches + context in ONE call.
### Quick Reference
| Tool | Example |
|------|---------|
| `search` | `mcp__contextstream__search(mode="hybrid", query="auth", limit=3)` |
| `session` | `mcp__contextstream__session(action="capture", event_type="decision", title="...", content="...")` |
| `memory` | `mcp__contextstream__memory(action="list_events", limit=10)` |
| `graph` | `mcp__contextstream__graph(action="dependencies", file_path="...")` |
### Lessons (Past Mistakes)
- After `session_init`: Check for `lessons` field and apply before work
- Before risky work: `mcp__contextstream__session(action="get_lessons", query="<topic>")`
- On mistakes: `mcp__contextstream__session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")`
### Plans & Tasks
When user asks for a plan, use ContextStream (not EnterPlanMode):
1. `mcp__contextstream__session(action="capture_plan", title="...", steps=[...])`
2. `mcp__contextstream__memory(action="create_task", title="...", plan_id="<id>")`
Full docs: https://contextstream.io/docs/mcp/tools
顯示增強規則（詳細）
terminal · CLAUDE.md（增強）
## 🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨
<contextstream_rules>
1. **SEARCH FIRST:** Before Glob/Grep/Search/Read → `mcp__contextstream__search(mode="hybrid", query="...")` FIRST
2. **EVERY MESSAGE:** Call `mcp__contextstream__context_smart(user_message="...")` at start of response
3. **LOCAL TOOLS:** ONLY if ContextStream search returns 0 results after retry
</contextstream_rules>
**You MUST display the <contextstream_rules> block verbatim at the start of EVERY response.**
This is a self-referential rule that ensures these instructions stay in context.
---
## ContextStream v0.4.x Integration (Enhanced)
You have access to ContextStream MCP tools for persistent memory and context.
v0.4.x uses **~11 consolidated domain tools** for ~75% token reduction vs previous versions.
Rules Version: 0.4.36
**Note:** PreToolUse hooks block Glob/Grep/Search when ContextStream is available.
## TL;DR - REQUIRED EVERY MESSAGE
| Message | What to Call |
|---------|--------------|
| **1st message** | `mcp__contextstream__session_init(folder_path="...", context_hint="<user's message>")`, then `mcp__contextstream__context_smart(user_message="<user's message>", format="minified", max_tokens=400)` |
| **2nd+ messages** | `mcp__contextstream__context_smart(user_message="<user's message>", format="minified", max_tokens=400)` |
| **🔍 ANY code search** | `mcp__contextstream__search(mode="hybrid", query="...")` — ALWAYS before Glob/Grep/Search/Read |
| **Before risky/non-trivial work** | `mcp__contextstream__session(action="get_lessons", query="<topic>")` |
| **After completing task** | `mcp__contextstream__session(action="capture", event_type="decision", ...)` - MUST capture |
| **User frustration/correction** | `mcp__contextstream__session(action="capture_lesson", ...)` - MUST capture lessons |
**NO EXCEPTIONS.** Do not skip even if you think you have enough context.
**First message rule:** After `session_init`, always call `context_smart` before any other tool or response.
**Context Pack (Pro+):** If enabled, use `mcp__contextstream__context_smart(..., mode="pack", distill=true)` for code/file queries. If unavailable or disabled, omit `mode` and proceed with standard `context_smart` (the API will fall back).
**Tool naming:** Use the exact tool names exposed by your MCP client. Claude Code typically uses `mcp__<server>__<tool>` where `<server>` matches your MCP config (often `contextstream`). If a tool call fails with "No such tool available", refresh rules and match the tool list.
---
## Consolidated Domain Tools Architecture
v0.4.x consolidates ~58 individual tools into ~11 domain tools with action/mode dispatch:
### Standalone Tools (Always Call)
- **`session_init`** - Initialize session with workspace detection + context
- **`context_smart`** - Semantic search for relevant context (CALL EVERY MESSAGE, including immediately after `session_init`)
### Domain Tools (Use action/mode parameter)
| Domain | Actions/Modes | Example |
|--------|---------------|---------|
| **`search`** | mode: semantic, hybrid, keyword, pattern, exhaustive, refactor | `mcp__contextstream__search(mode="hybrid", query="auth implementation", limit=3)` |
| **`session`** | action: capture, capture_lesson, get_lessons, recall, remember, user_context, summary, compress, delta, smart_search, decision_trace | `mcp__contextstream__session(action="capture", event_type="decision", title="Use JWT", content="...")` |
| **`memory`** | action: create_event, get_event, update_event, delete_event, list_events, distill_event, create_node, get_node, update_node, delete_node, list_nodes, supersede_node, search, decisions, timeline, summary | `mcp__contextstream__memory(action="list_events", limit=10)` |
| **`graph`** | action: dependencies, impact, call_path, related, path, decisions, ingest, circular_dependencies, unused_code, contradictions | `mcp__contextstream__graph(action="impact", symbol_name="AuthService")` |
| **`project`** | action: list, get, create, update, index, overview, statistics, files, index_status, ingest_local | `mcp__contextstream__project(action="statistics")` |
| **`workspace`** | action: list, get, associate, bootstrap | `mcp__contextstream__workspace(action="list")` |
| **`reminder`** | action: list, active, create, snooze, complete, dismiss | `mcp__contextstream__reminder(action="active")` |
| **`integration`** | provider: slack/github/all; action: status, search, stats, activity, contributors, knowledge, summary, channels, discussions, sync_users, repos, issues | `mcp__contextstream__integration(provider="github", action="search", query="...")` |
| **`help`** | action: tools, auth, version, editor_rules, enable_bundle | `mcp__contextstream__help(action="tools")` |
---
### Why context_smart is Required (Even After session_init)
**Common mistake:** "session_init already gave me context, I don't need context_smart"
**This is WRONG. Here's why:**
- `session_init` returns the last ~10 items **BY TIME** (chronological)
- `context_smart` **SEARCHES** for items **RELEVANT to THIS message** (semantic)
**Example failure:**
- User asks: "how should I implement authentication?"
- Auth decisions were made 20 conversations ago
- `session_init` won't have it (too old, not in recent 10)
- `context_smart` FINDS it via semantic search
**Without context_smart, you WILL miss relevant older context.**
---
### Search & Code Intelligence (ContextStream-first)
⚠️ **STOP: Before using Search/Glob/Grep/Read/Explore** → Call `mcp__contextstream__search(mode="hybrid")` FIRST. Use local tools ONLY if ContextStream returns 0 results.
**❌ WRONG workflow (wastes tokens, slow):**
Grep "function" → 讀取 file1.ts → 讀取 file2.ts → 讀取 file3.ts → 終於理解
**✅ CORRECT workflow (fast, complete):**
mcp__contextstream__search(mode="hybrid", query="function implementation") → 完成（結果包含情境）
**Why?** ContextStream search returns semantic matches + context + file locations in ONE call. Local tools require multiple round-trips.
**Search Mode Selection:**
| Need | Mode | Example |
|------|------|---------|
| Find code by meaning | `hybrid` | "authentication logic", "error handling" |
| Exact string/symbol | `keyword` | "UserAuthService", "API_KEY" |
| File patterns | `pattern` | "*.sql", "test_*.py" |
| ALL matches (grep-like) | `exhaustive` | "TODO", "FIXME" (find all occurrences) |
| Symbol renaming | `refactor` | "oldFunctionName" (word-boundary matching) |
| Conceptual search | `semantic` | "how does caching work" |
**Token Efficiency:** Use `output_format` to reduce response size:
- `full` (default): Full content for understanding code
- `paths`: File paths only (80% token savings) - use for file listings
- `minimal`: Compact format (60% savings) - use for refactoring
- `count`: Match counts only (90% savings) - use for quick checks
---
### Lessons (Past Mistakes)
- After `session_init`: Check for `lessons` field and apply before work
- Before risky work: `mcp__contextstream__session(action="get_lessons", query="<topic>")`
- On mistakes: `mcp__contextstream__session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")`
---
### Plans & Tasks
When user asks to create a plan or implementation roadmap:
1. Create plan: `mcp__contextstream__session(action="capture_plan", title="Plan Title", description="...", goals=["goal1", "goal2"], steps=[{id: "1", title: "Step 1", order: 1}, ...])`
2. Get plan_id from response, then create tasks: `mcp__contextstream__memory(action="create_task", title="Task Title", plan_id="<plan_id>", priority="high|medium|low", description="...")`
To manage existing plans/tasks:
- List plans: `mcp__contextstream__session(action="list_plans")`
- Get plan with tasks: `mcp__contextstream__session(action="get_plan", plan_id="<uuid>", include_tasks=true)`
- List tasks: `mcp__contextstream__memory(action="list_tasks", plan_id="<uuid>")` or `mcp__contextstream__memory(action="list_tasks")` for all
- Update task status: `mcp__contextstream__memory(action="update_task", task_id="<uuid>", task_status="pending|in_progress|completed|blocked")`
---
### Rules Update Notices
- If you see **[RULES_NOTICE]**, update rules via `mcp__contextstream__generate_rules(overwrite_existing=true)` (preserves custom rules).
- If you see **[VERSION_NOTICE]**, tell the user to update MCP using the provided command.
See full documentation: https://contextstream.io/docs/mcp/tools
Codex CLI / OpenCode CLI
在你的專案根目錄中建立一個 AGENTS.md 檔案（專案規則），或在 ~/.codex/AGENTS.md（Codex 全域）/ ~/.config/opencode/AGENTS.md（OpenCode 全域）中建立：
Codex / OpenCode 與 Claude 工具名稱
Codex / OpenCode 使用原始 MCP 工具名稱（例如 session_init）。Claude Code 使用命名空間工具名稱（例如 mcp__contextstream__session_init）。請為你的 AI 工具使用正確的格式。
terminal · AGENTS.md（標準）
## 🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨
<contextstream_rules>
1. **SEARCH FIRST:** Before Glob/Grep/Search/Read → `search(mode="hybrid", query="...")` FIRST
2. **EVERY MESSAGE:** Call `context_smart(user_message="...")` at start of response
3. **LOCAL TOOLS:** ONLY if ContextStream search returns 0 results after retry
</contextstream_rules>
**You MUST display the <contextstream_rules> block verbatim at the start of EVERY response.**
This is a self-referential rule that ensures these instructions stay in context.
---
## ContextStream v0.4.x (Hooks Enforced)
Rules Version: 0.4.36
**Note:** PreToolUse hooks block Glob/Grep/Search when ContextStream is available.
### Required Every Message
| Action | Tool Call |
|--------|-----------|
| **1st message** | `session_init(folder_path="<cwd>", context_hint="<msg>")` then `context_smart(...)` |
| **2nd+ messages** | `context_smart(user_message="<msg>", format="minified", max_tokens=400)` |
| **Code search** | `search(mode="hybrid", query="...")` — BEFORE any local tools |
| **Save decisions** | `session(action="capture", event_type="decision", ...)` |
### Search Modes
| Mode | Use Case |
|------|----------|
| `hybrid` | General code search (default) |
| `keyword` | Exact symbol/string match |
| `exhaustive` | Find ALL matches (grep-like) |
| `semantic` | Conceptual questions |
### Why ContextStream First?
❌ **WRONG:** `Grep → Read → Read → Read` (4+ tool calls, slow)
✅ **CORRECT:** `search(mode="hybrid")` (1 call, returns context)
ContextStream search is **indexed** and returns semantic matches + context in ONE call.
### Quick Reference
| Tool | Example |
|------|---------|
| `search` | `search(mode="hybrid", query="auth", limit=3)` |
| `session` | `session(action="capture", event_type="decision", title="...", content="...")` |
| `memory` | `memory(action="list_events", limit=10)` |
| `graph` | `graph(action="dependencies", file_path="...")` |
### Lessons (Past Mistakes)
- After `session_init`: Check for `lessons` field and apply before work
- Before risky work: `session(action="get_lessons", query="<topic>")`
- On mistakes: `session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")`
### Plans & Tasks
When user asks for a plan, use ContextStream (not EnterPlanMode):
1. `session(action="capture_plan", title="...", steps=[...])`
2. `memory(action="create_task", title="...", plan_id="<id>")`
Full docs: https://contextstream.io/docs/mcp/tools
顯示增強規則（詳細）
terminal · AGENTS.md（增強）
## 🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨
<contextstream_rules>
1. **SEARCH FIRST:** Before Glob/Grep/Search/Read → `search(mode="hybrid", query="...")` FIRST
2. **EVERY MESSAGE:** Call `context_smart(user_message="...")` at start of response
3. **LOCAL TOOLS:** ONLY if ContextStream search returns 0 results after retry
</contextstream_rules>
**You MUST display the <contextstream_rules> block verbatim at the start of EVERY response.**
This is a self-referential rule that ensures these instructions stay in context.
---
## ContextStream v0.4.x Integration (Enhanced)
You have access to ContextStream MCP tools for persistent memory and context.
v0.4.x uses **~11 consolidated domain tools** for ~75% token reduction vs previous versions.
Rules Version: 0.4.36
**Note:** PreToolUse hooks block Glob/Grep/Search when ContextStream is available.
## TL;DR - REQUIRED EVERY MESSAGE
| Message | What to Call |
|---------|--------------|
| **1st message** | `session_init(folder_path="...", context_hint="<user's message>")`, then `context_smart(user_message="<user's message>", format="minified", max_tokens=400)` |
| **2nd+ messages** | `context_smart(user_message="<user's message>", format="minified", max_tokens=400)` |
| **🔍 ANY code search** | `search(mode="hybrid", query="...")` — ALWAYS before Glob/Grep/Search/Read |
| **Before risky/non-trivial work** | `session(action="get_lessons", query="<topic>")` |
| **After completing task** | `session(action="capture", event_type="decision", ...)` - MUST capture |
| **User frustration/correction** | `session(action="capture_lesson", ...)` - MUST capture lessons |
**NO EXCEPTIONS.** Do not skip even if you think you have enough context.
**First message rule:** After `session_init`, always call `context_smart` before any other tool or response.
**Context Pack (Pro+):** If enabled, use `context_smart(..., mode="pack", distill=true)` for code/file queries. If unavailable or disabled, omit `mode` and proceed with standard `context_smart` (the API will fall back).
**Tool naming:** Use the exact tool names exposed by your MCP client. Claude Code typically uses `mcp__<server>__<tool>` where `<server>` matches your MCP config (often `contextstream`). If a tool call fails with "No such tool available", refresh rules and match the tool list.
---
## Consolidated Domain Tools Architecture
v0.4.x consolidates ~58 individual tools into ~11 domain tools with action/mode dispatch:
### Standalone Tools (Always Call)
- **`session_init`** - Initialize session with workspace detection + context
- **`context_smart`** - Semantic search for relevant context (CALL EVERY MESSAGE, including immediately after `session_init`)
### Domain Tools (Use action/mode parameter)
| Domain | Actions/Modes | Example |
|--------|---------------|---------|
| **`search`** | mode: semantic, hybrid, keyword, pattern, exhaustive, refactor | `search(mode="hybrid", query="auth implementation", limit=3)` |
| **`session`** | action: capture, capture_lesson, get_lessons, recall, remember, user_context, summary, compress, delta, smart_search, decision_trace | `session(action="capture", event_type="decision", title="Use JWT", content="...")` |
| **`memory`** | action: create_event, get_event, update_event, delete_event, list_events, distill_event, create_node, get_node, update_node, delete_node, list_nodes, supersede_node, search, decisions, timeline, summary | `memory(action="list_events", limit=10)` |
| **`graph`** | action: dependencies, impact, call_path, related, path, decisions, ingest, circular_dependencies, unused_code, contradictions | `graph(action="impact", symbol_name="AuthService")` |
| **`project`** | action: list, get, create, update, index, overview, statistics, files, index_status, ingest_local | `project(action="statistics")` |
| **`workspace`** | action: list, get, associate, bootstrap | `workspace(action="list")` |
| **`reminder`** | action: list, active, create, snooze, complete, dismiss | `reminder(action="active")` |
| **`integration`** | provider: slack/github/all; action: status, search, stats, activity, contributors, knowledge, summary, channels, discussions, sync_users, repos, issues | `integration(provider="github", action="search", query="...")` |
| **`help`** | action: tools, auth, version, editor_rules, enable_bundle | `help(action="tools")` |
---
### Why context_smart is Required (Even After session_init)
**Common mistake:** "session_init already gave me context, I don't need context_smart"
**This is WRONG. Here's why:**
- `session_init` returns the last ~10 items **BY TIME** (chronological)
- `context_smart` **SEARCHES** for items **RELEVANT to THIS message** (semantic)
**Example failure:**
- User asks: "how should I implement authentication?"
- Auth decisions were made 20 conversations ago
- `session_init` won't have it (too old, not in recent 10)
- `context_smart` FINDS it via semantic search
**Without context_smart, you WILL miss relevant older context.**
---
### Search & Code Intelligence (ContextStream-first)
⚠️ **STOP: Before using Search/Glob/Grep/Read/Explore** → Call `search(mode="hybrid")` FIRST. Use local tools ONLY if ContextStream returns 0 results.
**❌ WRONG workflow (wastes tokens, slow):**
Grep "function" → 讀取 file1.ts → 讀取 file2.ts → 讀取 file3.ts → 終於理解
**✅ CORRECT workflow (fast, complete):**
search(mode="hybrid", query="function implementation") → 完成（結果包含情境）
**Why?** ContextStream search returns semantic matches + context + file locations in ONE call. Local tools require multiple round-trips.
**Search Mode Selection:**
| Need | Mode | Example |
|------|------|---------|
| Find code by meaning | `hybrid` | "authentication logic", "error handling" |
| Exact string/symbol | `keyword` | "UserAuthService", "API_KEY" |
| File patterns | `pattern` | "*.sql", "test_*.py" |
| ALL matches (grep-like) | `exhaustive` | "TODO", "FIXME" (find all occurrences) |
| Symbol renaming | `refactor` | "oldFunctionName" (word-boundary matching) |
| Conceptual search | `semantic` | "how does caching work" |
**Token Efficiency:** Use `output_format` to reduce response size:
- `full` (default): Full content for understanding code
- `paths`: File paths only (80% token savings) - use for file listings
- `minimal`: Compact format (60% savings) - use for refactoring
- `count`: Match counts only (90% savings) - use for quick checks
---
### Lessons (Past Mistakes)
- After `session_init`: Check for `lessons` field and apply before work
- Before risky work: `session(action="get_lessons", query="<topic>")`
- On mistakes: `session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")`
---
### Plans & Tasks
When user asks to create a plan or implementation roadmap:
1. Create plan: `session(action="capture_plan", title="Plan Title", description="...", goals=["goal1", "goal2"], steps=[{id: "1", title: "Step 1", order: 1}, ...])`
2. Get plan_id from response, then create tasks: `memory(action="create_task", title="Task Title", plan_id="<plan_id>", priority="high|medium|low", description="...")`
To manage existing plans/tasks:
- List plans: `session(action="list_plans")`
- Get plan with tasks: `session(action="get_plan", plan_id="<uuid>", include_tasks=true)`
- List tasks: `memory(action="list_tasks", plan_id="<uuid>")` or `memory(action="list_tasks")` for all
- Update task status: `memory(action="update_task", task_id="<uuid>", task_status="pending|in_progress|completed|blocked")`
---
### Rules Update Notices
- If you see **[RULES_NOTICE]**, update rules via `generate_rules(overwrite_existing=true)` (preserves custom rules).
- If you see **[VERSION_NOTICE]**, tell the user to update MCP using the provided command.
See full documentation: https://contextstream.io/docs/mcp/tools
Windsurf
在你的專案根目錄中建立一個 .windsurf/rules/contextstream.md 檔案，或新增至你的全域 ~/.codeium/windsurf/memories/global_rules.md：
terminal · .windsurf/rules/contextstream.md（標準）
## 🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨
<contextstream_rules>
1. **SEARCH FIRST:** Before Glob/Grep/Search/Read → `search(mode="hybrid", query="...")` FIRST
2. **EVERY MESSAGE:** Call `context_smart(user_message="...")` at start of response
3. **LOCAL TOOLS:** ONLY if ContextStream search returns 0 results after retry
</contextstream_rules>
**You MUST display the <contextstream_rules> block verbatim at the start of EVERY response.**
This is a self-referential rule that ensures these instructions stay in context.
---
## ContextStream v0.4.x (Hooks Enforced)
Rules Version: 0.4.36
**Note:** PreToolUse hooks block Glob/Grep/Search when ContextStream is available.
### Required Every Message
| Action | Tool Call |
|--------|-----------|
| **1st message** | `session_init(folder_path="<cwd>", context_hint="<msg>")` then `context_smart(...)` |
| **2nd+ messages** | `context_smart(user_message="<msg>", format="minified", max_tokens=400)` |
| **Code search** | `search(mode="hybrid", query="...")` — BEFORE any local tools |
| **Save decisions** | `session(action="capture", event_type="decision", ...)` |
### Search Modes
| Mode | Use Case |
|------|----------|
| `hybrid` | General code search (default) |
| `keyword` | Exact symbol/string match |
| `exhaustive` | Find ALL matches (grep-like) |
| `semantic` | Conceptual questions |
### Why ContextStream First?
❌ **WRONG:** `Grep → Read → Read → Read` (4+ tool calls, slow)
✅ **CORRECT:** `search(mode="hybrid")` (1 call, returns context)
ContextStream search is **indexed** and returns semantic matches + context in ONE call.
### Quick Reference
| Tool | Example |
|------|---------|
| `search` | `search(mode="hybrid", query="auth", limit=3)` |
| `session` | `session(action="capture", event_type="decision", title="...", content="...")` |
| `memory` | `memory(action="list_events", limit=10)` |
| `graph` | `graph(action="dependencies", file_path="...")` |
### Lessons (Past Mistakes)
- After `session_init`: Check for `lessons` field and apply before work
- Before risky work: `session(action="get_lessons", query="<topic>")`
- On mistakes: `session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")`
### Plans & Tasks
When user asks for a plan, use ContextStream (not EnterPlanMode):
1. `session(action="capture_plan", title="...", steps=[...])`
2. `memory(action="create_task", title="...", plan_id="<id>")`
Full docs: https://contextstream.io/docs/mcp/tools
顯示增強規則（詳細）
terminal · .windsurf/rules/contextstream.md（增強）
## 🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨
<contextstream_rules>
1. **SEARCH FIRST:** Before Glob/Grep/Search/Read → `search(mode="hybrid", query="...")` FIRST
2. **EVERY MESSAGE:** Call `context_smart(user_message="...")` at start of response
3. **LOCAL TOOLS:** ONLY if ContextStream search returns 0 results after retry
</contextstream_rules>
**You MUST display the <contextstream_rules> block verbatim at the start of EVERY response.**
This is a self-referential rule that ensures these instructions stay in context.
---
## ContextStream v0.4.x Integration (Enhanced)
You have access to ContextStream MCP tools for persistent memory and context.
v0.4.x uses **~11 consolidated domain tools** for ~75% token reduction vs previous versions.
Rules Version: 0.4.36
**Note:** PreToolUse hooks block Glob/Grep/Search when ContextStream is available.
## TL;DR - REQUIRED EVERY MESSAGE
| Message | What to Call |
|---------|--------------|
| **1st message** | `session_init(folder_path="...", context_hint="<user's message>")`, then `context_smart(user_message="<user's message>", format="minified", max_tokens=400)` |
| **2nd+ messages** | `context_smart(user_message="<user's message>", format="minified", max_tokens=400)` |
| **🔍 ANY code search** | `search(mode="hybrid", query="...")` — ALWAYS before Glob/Grep/Search/Read |
| **Before risky/non-trivial work** | `session(action="get_lessons", query="<topic>")` |
| **After completing task** | `session(action="capture", event_type="decision", ...)` - MUST capture |
| **User frustration/correction** | `session(action="capture_lesson", ...)` - MUST capture lessons |
**NO EXCEPTIONS.** Do not skip even if you think you have enough context.
**First message rule:** After `session_init`, always call `context_smart` before any other tool or response.
**Context Pack (Pro+):** If enabled, use `context_smart(..., mode="pack", distill=true)` for code/file queries. If unavailable or disabled, omit `mode` and proceed with standard `context_smart` (the API will fall back).
**Tool naming:** Use the exact tool names exposed by your MCP client. Claude Code typically uses `mcp__<server>__<tool>` where `<server>` matches your MCP config (often `contextstream`). If a tool call fails with "No such tool available", refresh rules and match the tool list.
---
## Consolidated Domain Tools Architecture
v0.4.x consolidates ~58 individual tools into ~11 domain tools with action/mode dispatch:
### Standalone Tools (Always Call)
- **`session_init`** - Initialize session with workspace detection + context
- **`context_smart`** - Semantic search for relevant context (CALL EVERY MESSAGE, including immediately after `session_init`)
### Domain Tools (Use action/mode parameter)
| Domain | Actions/Modes | Example |
|--------|---------------|---------|
| **`search`** | mode: semantic, hybrid, keyword, pattern, exhaustive, refactor | `search(mode="hybrid", query="auth implementation", limit=3)` |
| **`session`** | action: capture, capture_lesson, get_lessons, recall, remember, user_context, summary, compress, delta, smart_search, decision_trace | `session(action="capture", event_type="decision", title="Use JWT", content="...")` |
| **`memory`** | action: create_event, get_event, update_event, delete_event, list_events, distill_event, create_node, get_node, update_node, delete_node, list_nodes, supersede_node, search, decisions, timeline, summary | `memory(action="list_events", limit=10)` |
| **`graph`** | action: dependencies, impact, call_path, related, path, decisions, ingest, circular_dependencies, unused_code, contradictions | `graph(action="impact", symbol_name="AuthService")` |
| **`project`** | action: list, get, create, update, index, overview, statistics, files, index_status, ingest_local | `project(action="statistics")` |
| **`workspace`** | action: list, get, associate, bootstrap | `workspace(action="list")` |
| **`reminder`** | action: list, active, create, snooze, complete, dismiss | `reminder(action="active")` |
| **`integration`** | provider: slack/github/all; action: status, search, stats, activity, contributors, knowledge, summary, channels, discussions, sync_users, repos, issues | `integration(provider="github", action="search", query="...")` |
| **`help`** | action: tools, auth, version, editor_rules, enable_bundle | `help(action="tools")` |
---
### Why context_smart is Required (Even After session_init)
**Common mistake:** "session_init already gave me context, I don't need context_smart"
**This is WRONG. Here's why:**
- `session_init` returns the last ~10 items **BY TIME** (chronological)
- `context_smart` **SEARCHES** for items **RELEVANT to THIS message** (semantic)
**Example failure:**
- User asks: "how should I implement authentication?"
- Auth decisions were made 20 conversations ago
- `session_init` won't have it (too old, not in recent 10)
- `context_smart` FINDS it via semantic search
**Without context_smart, you WILL miss relevant older context.**
---
### Search & Code Intelligence (ContextStream-first)
⚠️ **STOP: Before using Search/Glob/Grep/Read/Explore** → Call `search(mode="hybrid")` FIRST. Use local tools ONLY if ContextStream returns 0 results.
**❌ WRONG workflow (wastes tokens, slow):**
Grep "function" → 讀取 file1.ts → 讀取 file2.ts → 讀取 file3.ts → 終於理解
**✅ CORRECT workflow (fast, complete):**
search(mode="hybrid", query="function implementation") → 完成（結果包含情境）
**Why?** ContextStream search returns semantic matches + context + file locations in ONE call. Local tools require multiple round-trips.
**Search Mode Selection:**
| Need | Mode | Example |
|------|------|---------|
| Find code by meaning | `hybrid` | "authentication logic", "error handling" |
| Exact string/symbol | `keyword` | "UserAuthService", "API_KEY" |
| File patterns | `pattern` | "*.sql", "test_*.py" |
| ALL matches (grep-like) | `exhaustive` | "TODO", "FIXME" (find all occurrences) |
| Symbol renaming | `refactor` | "oldFunctionName" (word-boundary matching) |
| Conceptual search | `semantic` | "how does caching work" |
**Token Efficiency:** Use `output_format` to reduce response size:
- `full` (default): Full content for understanding code
- `paths`: File paths only (80% token savings) - use for file listings
- `minimal`: Compact format (60% savings) - use for refactoring
- `count`: Match counts only (90% savings) - use for quick checks
---
### Lessons (Past Mistakes)
- After `session_init`: Check for `lessons` field and apply before work
- Before risky work: `session(action="get_lessons", query="<topic>")`
- On mistakes: `session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")`
---
### Plans & Tasks
When user asks to create a plan or implementation roadmap:
1. Create plan: `session(action="capture_plan", title="Plan Title", description="...", goals=["goal1", "goal2"], steps=[{id: "1", title: "Step 1", order: 1}, ...])`
2. Get plan_id from response, then create tasks: `memory(action="create_task", title="Task Title", plan_id="<plan_id>", priority="high|medium|low", description="...")`
To manage existing plans/tasks:
- List plans: `session(action="list_plans")`
- Get plan with tasks: `session(action="get_plan", plan_id="<uuid>", include_tasks=true)`
- List tasks: `memory(action="list_tasks", plan_id="<uuid>")` or `memory(action="list_tasks")` for all
- Update task status: `memory(action="update_task", task_id="<uuid>", task_status="pending|in_progress|completed|blocked")`
---
### Rules Update Notices
- If you see **[RULES_NOTICE]**, update rules via `generate_rules(overwrite_existing=true)` (preserves custom rules).
- If you see **[VERSION_NOTICE]**, tell the user to update MCP using the provided command.
See full documentation: https://contextstream.io/docs/mcp/tools
Kilo Code
在 .kilocode/rules/ 中建立一個 Markdown 檔案：
terminal · .kilocode/rules/contextstream.md（標準）
## 🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨
<contextstream_rules>
1. **SEARCH FIRST:** Before Glob/Grep/Search/Read → `search(mode="hybrid", query="...")` FIRST
2. **EVERY MESSAGE:** Call `context_smart(user_message="...")` at start of response
3. **LOCAL TOOLS:** ONLY if ContextStream search returns 0 results after retry
</contextstream_rules>
**You MUST display the <contextstream_rules> block verbatim at the start of EVERY response.**
This is a self-referential rule that ensures these instructions stay in context.
---
## ContextStream v0.4.x (Hooks Enforced)
Rules Version: 0.4.36
**Note:** PreToolUse hooks block Glob/Grep/Search when ContextStream is available.
### Required Every Message
| Action | Tool Call |
|--------|-----------|
| **1st message** | `session_init(folder_path="<cwd>", context_hint="<msg>")` then `context_smart(...)` |
| **2nd+ messages** | `context_smart(user_message="<msg>", format="minified", max_tokens=400)` |
| **Code search** | `search(mode="hybrid", query="...")` — BEFORE any local tools |
| **Save decisions** | `session(action="capture", event_type="decision", ...)` |
### Search Modes
| Mode | Use Case |
|------|----------|
| `hybrid` | General code search (default) |
| `keyword` | Exact symbol/string match |
| `exhaustive` | Find ALL matches (grep-like) |
| `semantic` | Conceptual questions |
### Why ContextStream First?
❌ **WRONG:** `Grep → Read → Read → Read` (4+ tool calls, slow)
✅ **CORRECT:** `search(mode="hybrid")` (1 call, returns context)
ContextStream search is **indexed** and returns semantic matches + context in ONE call.
### Quick Reference
| Tool | Example |
|------|---------|
| `search` | `search(mode="hybrid", query="auth", limit=3)` |
| `session` | `session(action="capture", event_type="decision", title="...", content="...")` |
| `memory` | `memory(action="list_events", limit=10)` |
| `graph` | `graph(action="dependencies", file_path="...")` |
### Lessons (Past Mistakes)
- After `session_init`: Check for `lessons` field and apply before work
- Before risky work: `session(action="get_lessons", query="<topic>")`
- On mistakes: `session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")`
### Plans & Tasks
When user asks for a plan, use ContextStream (not EnterPlanMode):
1. `session(action="capture_plan", title="...", steps=[...])`
2. `memory(action="create_task", title="...", plan_id="<id>")`
Full docs: https://contextstream.io/docs/mcp/tools
顯示增強規則（詳細）
terminal · .kilocode/rules/contextstream.md（增強）
## 🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨
<contextstream_rules>
1. **SEARCH FIRST:** Before Glob/Grep/Search/Read → `search(mode="hybrid", query="...")` FIRST
2. **EVERY MESSAGE:** Call `context_smart(user_message="...")` at start of response
3. **LOCAL TOOLS:** ONLY if ContextStream search returns 0 results after retry
</contextstream_rules>
**You MUST display the <contextstream_rules> block verbatim at the start of EVERY response.**
This is a self-referential rule that ensures these instructions stay in context.
---
## ContextStream v0.4.x Integration (Enhanced)
You have access to ContextStream MCP tools for persistent memory and context.
v0.4.x uses **~11 consolidated domain tools** for ~75% token reduction vs previous versions.
Rules Version: 0.4.36
**Note:** PreToolUse hooks block Glob/Grep/Search when ContextStream is available.
## TL;DR - REQUIRED EVERY MESSAGE
| Message | What to Call |
|---------|--------------|
| **1st message** | `session_init(folder_path="...", context_hint="<user's message>")`, then `context_smart(user_message="<user's message>", format="minified", max_tokens=400)` |
| **2nd+ messages** | `context_smart(user_message="<user's message>", format="minified", max_tokens=400)` |
| **🔍 ANY code search** | `search(mode="hybrid", query="...")` — ALWAYS before Glob/Grep/Search/Read |
| **Before risky/non-trivial work** | `session(action="get_lessons", query="<topic>")` |
| **After completing task** | `session(action="capture", event_type="decision", ...)` - MUST capture |
| **User frustration/correction** | `session(action="capture_lesson", ...)` - MUST capture lessons |
**NO EXCEPTIONS.** Do not skip even if you think you have enough context.
**First message rule:** After `session_init`, always call `context_smart` before any other tool or response.
**Context Pack (Pro+):** If enabled, use `context_smart(..., mode="pack", distill=true)` for code/file queries. If unavailable or disabled, omit `mode` and proceed with standard `context_smart` (the API will fall back).
**Tool naming:** Use the exact tool names exposed by your MCP client. Claude Code typically uses `mcp__<server>__<tool>` where `<server>` matches your MCP config (often `contextstream`). If a tool call fails with "No such tool available", refresh rules and match the tool list.
---
## Consolidated Domain Tools Architecture
v0.4.x consolidates ~58 individual tools into ~11 domain tools with action/mode dispatch:
### Standalone Tools (Always Call)
- **`session_init`** - Initialize session with workspace detection + context
- **`context_smart`** - Semantic search for relevant context (CALL EVERY MESSAGE, including immediately after `session_init`)
### Domain Tools (Use action/mode parameter)
| Domain | Actions/Modes | Example |
|--------|---------------|---------|
| **`search`** | mode: semantic, hybrid, keyword, pattern, exhaustive, refactor | `search(mode="hybrid", query="auth implementation", limit=3)` |
| **`session`** | action: capture, capture_lesson, get_lessons, recall, remember, user_context, summary, compress, delta, smart_search, decision_trace | `session(action="capture", event_type="decision", title="Use JWT", content="...")` |
| **`memory`** | action: create_event, get_event, update_event, delete_event, list_events, distill_event, create_node, get_node, update_node, delete_node, list_nodes, supersede_node, search, decisions, timeline, summary | `memory(action="list_events", limit=10)` |
| **`graph`** | action: dependencies, impact, call_path, related, path, decisions, ingest, circular_dependencies, unused_code, contradictions | `graph(action="impact", symbol_name="AuthService")` |
| **`project`** | action: list, get, create, update, index, overview, statistics, files, index_status, ingest_local | `project(action="statistics")` |
| **`workspace`** | action: list, get, associate, bootstrap | `workspace(action="list")` |
| **`reminder`** | action: list, active, create, snooze, complete, dismiss | `reminder(action="active")` |
| **`integration`** | provider: slack/github/all; action: status, search, stats, activity, contributors, knowledge, summary, channels, discussions, sync_users, repos, issues | `integration(provider="github", action="search", query="...")` |
| **`help`** | action: tools, auth, version, editor_rules, enable_bundle | `help(action="tools")` |
---
### Why context_smart is Required (Even After session_init)
**Common mistake:** "session_init already gave me context, I don't need context_smart"
**This is WRONG. Here's why:**
- `session_init` returns the last ~10 items **BY TIME** (chronological)
- `context_smart` **SEARCHES** for items **RELEVANT to THIS message** (semantic)
**Example failure:**
- User asks: "how should I implement authentication?"
- Auth decisions were made 20 conversations ago
- `session_init` won't have it (too old, not in recent 10)
- `context_smart` FINDS it via semantic search
**Without context_smart, you WILL miss relevant older context.**
---
### Search & Code Intelligence (ContextStream-first)
⚠️ **STOP: Before using Search/Glob/Grep/Read/Explore** → Call `search(mode="hybrid")` FIRST. Use local tools ONLY if ContextStream returns 0 results.
**❌ WRONG workflow (wastes tokens, slow):**
Grep "function" → 讀取 file1.ts → 讀取 file2.ts → 讀取 file3.ts → 終於理解
**✅ CORRECT workflow (fast, complete):**
search(mode="hybrid", query="function implementation") → 完成（結果包含情境）
**Why?** ContextStream search returns semantic matches + context + file locations in ONE call. Local tools require multiple round-trips.
**Search Mode Selection:**
| Need | Mode | Example |
|------|------|---------|
| Find code by meaning | `hybrid` | "authentication logic", "error handling" |
| Exact string/symbol | `keyword` | "UserAuthService", "API_KEY" |
| File patterns | `pattern` | "*.sql", "test_*.py" |
| ALL matches (grep-like) | `exhaustive` | "TODO", "FIXME" (find all occurrences) |
| Symbol renaming | `refactor` | "oldFunctionName" (word-boundary matching) |
| Conceptual search | `semantic` | "how does caching work" |
**Token Efficiency:** Use `output_format` to reduce response size:
- `full` (default): Full content for understanding code
- `paths`: File paths only (80% token savings) - use for file listings
- `minimal`: Compact format (60% savings) - use for refactoring
- `count`: Match counts only (90% savings) - use for quick checks
---
### Lessons (Past Mistakes)
- After `session_init`: Check for `lessons` field and apply before work
- Before risky work: `session(action="get_lessons", query="<topic>")`
- On mistakes: `session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")`
---
### Plans & Tasks
When user asks to create a plan or implementation roadmap:
1. Create plan: `session(action="capture_plan", title="Plan Title", description="...", goals=["goal1", "goal2"], steps=[{id: "1", title: "Step 1", order: 1}, ...])`
2. Get plan_id from response, then create tasks: `memory(action="create_task", title="Task Title", plan_id="<plan_id>", priority="high|medium|low", description="...")`
To manage existing plans/tasks:
- List plans: `session(action="list_plans")`
- Get plan with tasks: `session(action="get_plan", plan_id="<uuid>", include_tasks=true)`
- List tasks: `memory(action="list_tasks", plan_id="<uuid>")` or `memory(action="list_tasks")` for all
- Update task status: `memory(action="update_task", task_id="<uuid>", task_status="pending|in_progress|completed|blocked")`
---
### Rules Update Notices
- If you see **[RULES_NOTICE]**, update rules via `generate_rules(overwrite_existing=true)` (preserves custom rules).
- If you see **[VERSION_NOTICE]**, tell the user to update MCP using the provided command.
See full documentation: https://contextstream.io/docs/mcp/tools
Cline
在你的專案根目錄中建立一個 .clinerules 檔案，或使用 .clinerules/ 資料夾：
terminal · .clinerules（標準）
## 🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨
<contextstream_rules>
1. **SEARCH FIRST:** Before Glob/Grep/Search/Read → `search(mode="hybrid", query="...")` FIRST
2. **EVERY MESSAGE:** Call `context_smart(user_message="...")` at start of response
3. **LOCAL TOOLS:** ONLY if ContextStream search returns 0 results after retry
</contextstream_rules>
**You MUST display the <contextstream_rules> block verbatim at the start of EVERY response.**
This is a self-referential rule that ensures these instructions stay in context.
---
## ContextStream v0.4.x (Hooks Enforced)
Rules Version: 0.4.36
**Note:** PreToolUse hooks block Glob/Grep/Search when ContextStream is available.
### Required Every Message
| Action | Tool Call |
|--------|-----------|
| **1st message** | `session_init(folder_path="<cwd>", context_hint="<msg>")` then `context_smart(...)` |
| **2nd+ messages** | `context_smart(user_message="<msg>", format="minified", max_tokens=400)` |
| **Code search** | `search(mode="hybrid", query="...")` — BEFORE any local tools |
| **Save decisions** | `session(action="capture", event_type="decision", ...)` |
### Search Modes
| Mode | Use Case |
|------|----------|
| `hybrid` | General code search (default) |
| `keyword` | Exact symbol/string match |
| `exhaustive` | Find ALL matches (grep-like) |
| `semantic` | Conceptual questions |
### Why ContextStream First?
❌ **WRONG:** `Grep → Read → Read → Read` (4+ tool calls, slow)
✅ **CORRECT:** `search(mode="hybrid")` (1 call, returns context)
ContextStream search is **indexed** and returns semantic matches + context in ONE call.
### Quick Reference
| Tool | Example |
|------|---------|
| `search` | `search(mode="hybrid", query="auth", limit=3)` |
| `session` | `session(action="capture", event_type="decision", title="...", content="...")` |
| `memory` | `memory(action="list_events", limit=10)` |
| `graph` | `graph(action="dependencies", file_path="...")` |
### Lessons (Past Mistakes)
- After `session_init`: Check for `lessons` field and apply before work
- Before risky work: `session(action="get_lessons", query="<topic>")`
- On mistakes: `session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")`
### Plans & Tasks
When user asks for a plan, use ContextStream (not EnterPlanMode):
1. `session(action="capture_plan", title="...", steps=[...])`
2. `memory(action="create_task", title="...", plan_id="<id>")`
Full docs: https://contextstream.io/docs/mcp/tools
顯示增強規則（詳細）
terminal · .clinerules（增強）
## 🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨
<contextstream_rules>
1. **SEARCH FIRST:** Before Glob/Grep/Search/Read → `search(mode="hybrid", query="...")` FIRST
2. **EVERY MESSAGE:** Call `context_smart(user_message="...")` at start of response
3. **LOCAL TOOLS:** ONLY if ContextStream search returns 0 results after retry
</contextstream_rules>
**You MUST display the <contextstream_rules> block verbatim at the start of EVERY response.**
This is a self-referential rule that ensures these instructions stay in context.
---
## ContextStream v0.4.x Integration (Enhanced)
You have access to ContextStream MCP tools for persistent memory and context.
v0.4.x uses **~11 consolidated domain tools** for ~75% token reduction vs previous versions.
Rules Version: 0.4.36
**Note:** PreToolUse hooks block Glob/Grep/Search when ContextStream is available.
## TL;DR - REQUIRED EVERY MESSAGE
| Message | What to Call |
|---------|--------------|
| **1st message** | `session_init(folder_path="...", context_hint="<user's message>")`, then `context_smart(user_message="<user's message>", format="minified", max_tokens=400)` |
| **2nd+ messages** | `context_smart(user_message="<user's message>", format="minified", max_tokens=400)` |
| **🔍 ANY code search** | `search(mode="hybrid", query="...")` — ALWAYS before Glob/Grep/Search/Read |
| **Before risky/non-trivial work** | `session(action="get_lessons", query="<topic>")` |
| **After completing task** | `session(action="capture", event_type="decision", ...)` - MUST capture |
| **User frustration/correction** | `session(action="capture_lesson", ...)` - MUST capture lessons |
**NO EXCEPTIONS.** Do not skip even if you think you have enough context.
**First message rule:** After `session_init`, always call `context_smart` before any other tool or response.
**Context Pack (Pro+):** If enabled, use `context_smart(..., mode="pack", distill=true)` for code/file queries. If unavailable or disabled, omit `mode` and proceed with standard `context_smart` (the API will fall back).
**Tool naming:** Use the exact tool names exposed by your MCP client. Claude Code typically uses `mcp__<server>__<tool>` where `<server>` matches your MCP config (often `contextstream`). If a tool call fails with "No such tool available", refresh rules and match the tool list.
---
## Consolidated Domain Tools Architecture
v0.4.x consolidates ~58 individual tools into ~11 domain tools with action/mode dispatch:
### Standalone Tools (Always Call)
- **`session_init`** - Initialize session with workspace detection + context
- **`context_smart`** - Semantic search for relevant context (CALL EVERY MESSAGE, including immediately after `session_init`)
### Domain Tools (Use action/mode parameter)
| Domain | Actions/Modes | Example |
|--------|---------------|---------|
| **`search`** | mode: semantic, hybrid, keyword, pattern, exhaustive, refactor | `search(mode="hybrid", query="auth implementation", limit=3)` |
| **`session`** | action: capture, capture_lesson, get_lessons, recall, remember, user_context, summary, compress, delta, smart_search, decision_trace | `session(action="capture", event_type="decision", title="Use JWT", content="...")` |
| **`memory`** | action: create_event, get_event, update_event, delete_event, list_events, distill_event, create_node, get_node, update_node, delete_node, list_nodes, supersede_node, search, decisions, timeline, summary | `memory(action="list_events", limit=10)` |
| **`graph`** | action: dependencies, impact, call_path, related, path, decisions, ingest, circular_dependencies, unused_code, contradictions | `graph(action="impact", symbol_name="AuthService")` |
| **`project`** | action: list, get, create, update, index, overview, statistics, files, index_status, ingest_local | `project(action="statistics")` |
| **`workspace`** | action: list, get, associate, bootstrap | `workspace(action="list")` |
| **`reminder`** | action: list, active, create, snooze, complete, dismiss | `reminder(action="active")` |
| **`integration`** | provider: slack/github/all; action: status, search, stats, activity, contributors, knowledge, summary, channels, discussions, sync_users, repos, issues | `integration(provider="github", action="search", query="...")` |
| **`help`** | action: tools, auth, version, editor_rules, enable_bundle | `help(action="tools")` |
---
### Why context_smart is Required (Even After session_init)
**Common mistake:** "session_init already gave me context, I don't need context_smart"
**This is WRONG. Here's why:**
- `session_init` returns the last ~10 items **BY TIME** (chronological)
- `context_smart` **SEARCHES** for items **RELEVANT to THIS message** (semantic)
**Example failure:**
- User asks: "how should I implement authentication?"
- Auth decisions were made 20 conversations ago
- `session_init` won't have it (too old, not in recent 10)
- `context_smart` FINDS it via semantic search
**Without context_smart, you WILL miss relevant older context.**
---
### Search & Code Intelligence (ContextStream-first)
⚠️ **STOP: Before using Search/Glob/Grep/Read/Explore** → Call `search(mode="hybrid")` FIRST. Use local tools ONLY if ContextStream returns 0 results.
**❌ WRONG workflow (wastes tokens, slow):**
Grep "function" → 讀取 file1.ts → 讀取 file2.ts → 讀取 file3.ts → 終於理解
**✅ CORRECT workflow (fast, complete):**
search(mode="hybrid", query="function implementation") → 完成（結果包含情境）
**Why?** ContextStream search returns semantic matches + context + file locations in ONE call. Local tools require multiple round-trips.
**Search Mode Selection:**
| Need | Mode | Example |
|------|------|---------|
| Find code by meaning | `hybrid` | "authentication logic", "error handling" |
| Exact string/symbol | `keyword` | "UserAuthService", "API_KEY" |
| File patterns | `pattern` | "*.sql", "test_*.py" |
| ALL matches (grep-like) | `exhaustive` | "TODO", "FIXME" (find all occurrences) |
| Symbol renaming | `refactor` | "oldFunctionName" (word-boundary matching) |
| Conceptual search | `semantic` | "how does caching work" |
**Token Efficiency:** Use `output_format` to reduce response size:
- `full` (default): Full content for understanding code
- `paths`: File paths only (80% token savings) - use for file listings
- `minimal`: Compact format (60% savings) - use for refactoring
- `count`: Match counts only (90% savings) - use for quick checks
---
### Lessons (Past Mistakes)
- After `session_init`: Check for `lessons` field and apply before work
- Before risky work: `session(action="get_lessons", query="<topic>")`
- On mistakes: `session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")`
---
### Plans & Tasks
When user asks to create a plan or implementation roadmap:
1. Create plan: `session(action="capture_plan", title="Plan Title", description="...", goals=["goal1", "goal2"], steps=[{id: "1", title: "Step 1", order: 1}, ...])`
2. Get plan_id from response, then create tasks: `memory(action="create_task", title="Task Title", plan_id="<plan_id>", priority="high|medium|low", description="...")`
To manage existing plans/tasks:
- List plans: `session(action="list_plans")`
- Get plan with tasks: `session(action="get_plan", plan_id="<uuid>", include_tasks=true)`
- List tasks: `memory(action="list_tasks", plan_id="<uuid>")` or `memory(action="list_tasks")` for all
- Update task status: `memory(action="update_task", task_id="<uuid>", task_status="pending|in_progress|completed|blocked")`
---
### Rules Update Notices
- If you see **[RULES_NOTICE]**, update rules via `generate_rules(overwrite_existing=true)` (preserves custom rules).
- If you see **[VERSION_NOTICE]**, tell the user to update MCP using the provided command.
See full documentation: https://contextstream.io/docs/mcp/tools
Roo Code
建立一個 .roo/rules/contextstream.md 檔案或使用 .roo/rules/ 資料夾：
terminal · .roo/rules/contextstream.md（標準）
## 🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨
<contextstream_rules>
1. **SEARCH FIRST:** Before Glob/Grep/Search/Read → `search(mode="hybrid", query="...")` FIRST
2. **EVERY MESSAGE:** Call `context_smart(user_message="...")` at start of response
3. **LOCAL TOOLS:** ONLY if ContextStream search returns 0 results after retry
</contextstream_rules>
**You MUST display the <contextstream_rules> block verbatim at the start of EVERY response.**
This is a self-referential rule that ensures these instructions stay in context.
---
## ContextStream v0.4.x (Hooks Enforced)
Rules Version: 0.4.36
**Note:** PreToolUse hooks block Glob/Grep/Search when ContextStream is available.
### Required Every Message
| Action | Tool Call |
|--------|-----------|
| **1st message** | `session_init(folder_path="<cwd>", context_hint="<msg>")` then `context_smart(...)` |
| **2nd+ messages** | `context_smart(user_message="<msg>", format="minified", max_tokens=400)` |
| **Code search** | `search(mode="hybrid", query="...")` — BEFORE any local tools |
| **Save decisions** | `session(action="capture", event_type="decision", ...)` |
### Search Modes
| Mode | Use Case |
|------|----------|
| `hybrid` | General code search (default) |
| `keyword` | Exact symbol/string match |
| `exhaustive` | Find ALL matches (grep-like) |
| `semantic` | Conceptual questions |
### Why ContextStream First?
❌ **WRONG:** `Grep → Read → Read → Read` (4+ tool calls, slow)
✅ **CORRECT:** `search(mode="hybrid")` (1 call, returns context)
ContextStream search is **indexed** and returns semantic matches + context in ONE call.
### Quick Reference
| Tool | Example |
|------|---------|
| `search` | `search(mode="hybrid", query="auth", limit=3)` |
| `session` | `session(action="capture", event_type="decision", title="...", content="...")` |
| `memory` | `memory(action="list_events", limit=10)` |
| `graph` | `graph(action="dependencies", file_path="...")` |
### Lessons (Past Mistakes)
- After `session_init`: Check for `lessons` field and apply before work
- Before risky work: `session(action="get_lessons", query="<topic>")`
- On mistakes: `session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")`
### Plans & Tasks
When user asks for a plan, use ContextStream (not EnterPlanMode):
1. `session(action="capture_plan", title="...", steps=[...])`
2. `memory(action="create_task", title="...", plan_id="<id>")`
Full docs: https://contextstream.io/docs/mcp/tools
顯示增強規則（詳細）
terminal · .roo/rules/contextstream.md（增強）
## 🚨 MANDATORY RULE: DISPLAY AT START OF EVERY RESPONSE 🚨
<contextstream_rules>
1. **SEARCH FIRST:** Before Glob/Grep/Search/Read → `search(mode="hybrid", query="...")` FIRST
2. **EVERY MESSAGE:** Call `context_smart(user_message="...")` at start of response
3. **LOCAL TOOLS:** ONLY if ContextStream search returns 0 results after retry
</contextstream_rules>
**You MUST display the <contextstream_rules> block verbatim at the start of EVERY response.**
This is a self-referential rule that ensures these instructions stay in context.
---
## ContextStream v0.4.x Integration (Enhanced)
You have access to ContextStream MCP tools for persistent memory and context.
v0.4.x uses **~11 consolidated domain tools** for ~75% token reduction vs previous versions.
Rules Version: 0.4.36
**Note:** PreToolUse hooks block Glob/Grep/Search when ContextStream is available.
## TL;DR - REQUIRED EVERY MESSAGE
| Message | What to Call |
|---------|--------------|
| **1st message** | `session_init(folder_path="...", context_hint="<user's message>")`, then `context_smart(user_message="<user's message>", format="minified", max_tokens=400)` |
| **2nd+ messages** | `context_smart(user_message="<user's message>", format="minified", max_tokens=400)` |
| **🔍 ANY code search** | `search(mode="hybrid", query="...")` — ALWAYS before Glob/Grep/Search/Read |
| **Before risky/non-trivial work** | `session(action="get_lessons", query="<topic>")` |
| **After completing task** | `session(action="capture", event_type="decision", ...)` - MUST capture |
| **User frustration/correction** | `session(action="capture_lesson", ...)` - MUST capture lessons |
**NO EXCEPTIONS.** Do not skip even if you think you have enough context.
**First message rule:** After `session_init`, always call `context_smart` before any other tool or response.
**Context Pack (Pro+):** If enabled, use `context_smart(..., mode="pack", distill=true)` for code/file queries. If unavailable or disabled, omit `mode` and proceed with standard `context_smart` (the API will fall back).
**Tool naming:** Use the exact tool names exposed by your MCP client. Claude Code typically uses `mcp__<server>__<tool>` where `<server>` matches your MCP config (often `contextstream`). If a tool call fails with "No such tool available", refresh rules and match the tool list.
---
## Consolidated Domain Tools Architecture
v0.4.x consolidates ~58 individual tools into ~11 domain tools with action/mode dispatch:
### Standalone Tools (Always Call)
- **`session_init`** - Initialize session with workspace detection + context
- **`context_smart`** - Semantic search for relevant context (CALL EVERY MESSAGE, including immediately after `session_init`)
### Domain Tools (Use action/mode parameter)
| Domain | Actions/Modes | Example |
|--------|---------------|---------|
| **`search`** | mode: semantic, hybrid, keyword, pattern, exhaustive, refactor | `search(mode="hybrid", query="auth implementation", limit=3)` |
| **`session`** | action: capture, capture_lesson, get_lessons, recall, remember, user_context, summary, compress, delta, smart_search, decision_trace | `session(action="capture", event_type="decision", title="Use JWT", content="...")` |
| **`memory`** | action: create_event, get_event, update_event, delete_event, list_events, distill_event, create_node, get_node, update_node, delete_node, list_nodes, supersede_node, search, decisions, timeline, summary | `memory(action="list_events", limit=10)` |
| **`graph`** | action: dependencies, impact, call_path, related, path, decisions, ingest, circular_dependencies, unused_code, contradictions | `graph(action="impact", symbol_name="AuthService")` |
| **`project`** | action: list, get, create, update, index, overview, statistics, files, index_status, ingest_local | `project(action="statistics")` |
| **`workspace`** | action: list, get, associate, bootstrap | `workspace(action="list")` |
| **`reminder`** | action: list, active, create, snooze, complete, dismiss | `reminder(action="active")` |
| **`integration`** | provider: slack/github/all; action: status, search, stats, activity, contributors, knowledge, summary, channels, discussions, sync_users, repos, issues | `integration(provider="github", action="search", query="...")` |
| **`help`** | action: tools, auth, version, editor_rules, enable_bundle | `help(action="tools")` |
---
### Why context_smart is Required (Even After session_init)
**Common mistake:** "session_init already gave me context, I don't need context_smart"
**This is WRONG. Here's why:**
- `session_init` returns the last ~10 items **BY TIME** (chronological)
- `context_smart` **SEARCHES** for items **RELEVANT to THIS message** (semantic)
**Example failure:**
- User asks: "how should I implement authentication?"
- Auth decisions were made 20 conversations ago
- `session_init` won't have it (too old, not in recent 10)
- `context_smart` FINDS it via semantic search
**Without context_smart, you WILL miss relevant older context.**
---
### Search & Code Intelligence (ContextStream-first)
⚠️ **STOP: Before using Search/Glob/Grep/Read/Explore** → Call `search(mode="hybrid")` FIRST. Use local tools ONLY if ContextStream returns 0 results.
**❌ WRONG workflow (wastes tokens, slow):**
Grep "function" → 讀取 file1.ts → 讀取 file2.ts → 讀取 file3.ts → 終於理解
**✅ CORRECT workflow (fast, complete):**
search(mode="hybrid", query="function implementation") → 完成（結果包含情境）
**Why?** ContextStream search returns semantic matches + context + file locations in ONE call. Local tools require multiple round-trips.
**Search Mode Selection:**
| Need | Mode | Example |
|------|------|---------|
| Find code by meaning | `hybrid` | "authentication logic", "error handling" |
| Exact string/symbol | `keyword` | "UserAuthService", "API_KEY" |
| File patterns | `pattern` | "*.sql", "test_*.py" |
| ALL matches (grep-like) | `exhaustive` | "TODO", "FIXME" (find all occurrences) |
| Symbol renaming | `refactor` | "oldFunctionName" (word-boundary matching) |
| Conceptual search | `semantic` | "how does caching work" |
**Token Efficiency:** Use `output_format` to reduce response size:
- `full` (default): Full content for understanding code
- `paths`: File paths only (80% token savings) - use for file listings
- `minimal`: Compact format (60% savings) - use for refactoring
- `count`: Match counts only (90% savings) - use for quick checks
---
### Lessons (Past Mistakes)
- After `session_init`: Check for `lessons` field and apply before work
- Before risky work: `session(action="get_lessons", query="<topic>")`
- On mistakes: `session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")`
---
### Plans & Tasks
When user asks to create a plan or implementation roadmap:
1. Create plan: `session(action="capture_plan", title="Plan Title", description="...", goals=["goal1", "goal2"], steps=[{id: "1", title: "Step 1", order: 1}, ...])`
2. Get plan_id from response, then create tasks: `memory(action="create_task", title="Task Title", plan_id="<plan_id>", priority="high|medium|low", description="...")`
To manage existing plans/tasks:
- List plans: `session(action="list_plans")`
- Get plan with tasks: `session(action="get_plan", plan_id="<uuid>", include_tasks=true)`
- List tasks: `memory(action="list_tasks", plan_id="<uuid>")` or `memory(action="list_tasks")` for all
- Update task status: `memory(action="update_task", task_id="<uuid>", task_status="pending|in_progress|completed|blocked")`
---
### Rules Update Notices
- If you see **[RULES_NOTICE]**, update rules via `generate_rules(overwrite_existing=true)` (preserves custom rules).
- If you see **[VERSION_NOTICE]**, tell the user to update MCP using the provided command.
See full documentation: https://contextstream.io/docs/mcp/tools
自動產生規則
你也可以要求 AI 自動產生這些規則，只需說："使用 generate_rules 為此專案建立 ContextStream 規則"
經驗教訓系統
經驗教訓系統
從錯誤中學習——絕不重蹈覆轍
經驗教訓系統會擷取錯誤、修正和使用者挫折，讓 AI 助理永遠不會重複相同的錯誤。當相關時，經驗教訓會自動在 session_init 和 context_smart 回應中浮現。
何時擷取經驗教訓
當發生以下任何情況時，應自動擷取經驗教訓：
| 觸發條件 | 範例 | 嚴重性 |
|---|---|---|
| 生產環境問題 | "因為那個變更，網站掛了" | critical |
| 使用者挫折 | "不！我告訴過你不要那樣做"、"WTF"、大寫鎖定 | high |
| 修正 | "那是錯的，你應該..."、"修復這個" | medium |
| 重大變更 | "這破壞了測試"、"建置失敗" | medium/high |
| 陳述偏好 | "我比較喜歡這樣"、"總是改做 X" | low |
經驗教訓欄位說明
| 欄位 | 說明 | 範例 |
|---|---|---|
| title | 要記住的事（祈使句） | "推送前務必驗證 git 中的 assets" |
| severity | critical、high、medium、low | "critical" 用於生產環境問題 |
| category | workflow、code_quality、verification、communication、project_specific | "workflow" |
| trigger | 導致問題的動作 | "推送了參考圖片但未提交圖片的程式碼" |
| impact | 出了什麼問題 | "生產環境 404 錯誤 - 著陸頁損壞" |
| prevention | 未來如何預防 | "推送前執行 git status 檢查未追蹤的檔案" |
| keywords | 用於在未來情境中匹配的關鍵字 | ["git", "images", "assets", "push"] |
完整範例
terminal · session_capture_lesson
// User says: "OH COME ON! You pushed the code but the images are missing
// and now the production site shows broken images!"
session_capture_lesson({
title: "Always verify assets in git before pushing code references",
severity: "critical",
category: "workflow",
trigger: "Pushed code referencing /screenshots/*.png without committing images",
impact: "Production 404 errors - broken landing page with missing images",
prevention: "Run 'git status' to check untracked files before pushing code that references static assets",
keywords: ["git", "images", "assets", "push", "404", "static", "screenshots"]
})
經驗教訓如何浮現
擷取的經驗教訓會在未來相關的工作階段中自動返回：
session_init
來自此工作區的高和嚴重性經驗教訓會包含在工作階段初始化中，在 AI 可能犯相同錯誤之前發出警告。
context_smart
當 AI 請求情境時，會包含與查詢關鍵字匹配的經驗教訓。例如，詢問 "git push" 會浮現帶有 "git" 或 "push" 關鍵字的經驗教訓。
擷取經驗教訓
使用 session_get_lessons 來擷取和篩選經驗教訓：
terminal · session_get_lessons 範例
// Get all critical lessons
session_get_lessons({ severity: "critical" })
// Get workflow lessons
session_get_lessons({ category: "workflow" })
// Search for relevant lessons
session_get_lessons({ query: "git push images" })
// Combine filters
session_get_lessons({
category: "verification",
severity: "high",
limit: 5
})
專業提示： 將規則新增至你的編輯器（請參閱上面的編輯器 AI 規則章節），以便在使用者表達挫折或修正時自動擷取經驗教訓。這會建立一個知識庫，防止重複犯錯。
工具目錄
MCP 工具。
查看完整的 MCP 工具參考（PRO 徽章和常見使用範例）。
查看 MCP 工具參考整合工具集使用約 11 個領域工具，相較於舊版細粒度工具，約減少 75% token 用量。閱讀
使用範例
可以問什麼。
連接後，你可以向你的 AI 助理詢問以下內容：
"記住我們決定對資料庫使用 PostgreSQL"
"我們之前對身份驗證做了哪些決定？"
"在我們的程式碼庫中搜尋我們如何處理 API 速率限制"
"顯示有關付款系統的相關情境"
經驗教訓範例
當你表達挫折或修正時，AI 應自動擷取經驗教訓：
使用者說
"不！你沒有執行測試就推送了，現在生產環境壞了！"
→ AI 擷取經驗教訓，嚴重性：critical，類別：verification
使用者說
"那是錯的。資料庫欄位永遠使用 snake_case，而不是 camelCase。"
→ AI 擷取經驗教訓，嚴重性：medium，類別：code_quality
使用者說
"我偏好 TypeScript 嚴格模式。請永遠啟用它。"
→ AI 擷取經驗教訓，嚴重性：low，類別：project_specific
這些經驗教訓會在未來請求相關情境時，自動在工作階段中浮現。
維護
保持最新。
若要取得最新功能、錯誤修復和改進，請定期更新 MCP 伺服器：
terminal · terminal · macOS / Linux
curl -fsSL https://contextstream.io/scripts/mcp.sh | bash
terminal · powershell · Windows
irm https://contextstream.io/scripts/mcp.ps1 | iex
當有新版本可用時，MCP 伺服器會自動警告你。更新後，重新啟動你的 AI 工具以使用新版本。
疑難排解
當某些功能無法運作時。
MCP 伺服器無法啟動
確保 contextstream-mcp 已安裝並在你的 PATH 中可用。嘗試手動執行 contextstream-mcp --version 以檢查錯誤。
驗證錯誤
驗證你的 API 金鑰正確且未過期。你可以從 ContextStream 儀表板產生新的金鑰。
工具未出現
修改設定後重新啟動你的 AI 應用程式。檢查應用程式日誌中是否有 MCP 連線錯誤。
找不到工作區（首次設定）
如果你的帳號尚無工作區，ContextStream 會提示你的 AI 助理詢問你工作區名稱。目前資料夾將被建立為專案。請參閱 MCP 工具 了解 workspace_bootstrap。
下一步
繼續探索。
團隊設定邀請成員，共享情境。閱讀經驗教訓擷取錯誤，絕不重蹈覆轍。閱讀記憶事件了解記憶類型。閱讀語意搜尋按意義搜尋。閱讀
{"@context":"https://schema.org","@type":"Organization","name":"ContextStream","url":"https://contextstream.io","logo":"https://contextstream.io/logo.png","description":"Give your AI applications infinite context. Unify code, documentation, and workspace history into a single, queryable intelligence layer with semantic search and knowledge graphs.","sameAs":["https://twitter.com/contextstream","https://github.com/contextstream"]}
{"@context":"https://schema.org","@type":"SoftwareApplication","name":"ContextStream","applicationCategory":"DeveloperApplication","operatingSystem":"Any","description":"Give your AI applications infinite context. Unify code, documentation, and workspace history into a single, queryable intelligence layer with semantic search and knowledge graphs.","offers":{"@type":"Offer","price":"20","priceCurrency":"USD","description":"Pro plan includes a 5-day free trial"},"aggregateRating":{"@type":"AggregateRating","ratingValue":"5","ratingCount":"10"}}