ContextStream MCP Server
官方跨会话的AI编程助手的持久化记忆与语义搜索
文档
文档 · 浏览章节
01 · 设置向导
一条命令，完成全部配置。
运行一条命令即可完成身份验证（浏览器/设备登录）、创建 API 密钥、生成规则，并为你的工具写入正确的 MCP 配置（包括 VS Code 的 servers 架构）。
终端 · 终端 · macOS / Linux
curl -fsSL https://contextstream.io/scripts/mcp.sh | bash
终端 · PowerShell · Windows
irm https://contextstream.io/scripts/mcp.ps1 | iex
已安装？重新运行设置向导
终端 · 终端 · 重新运行
contextstream-mcp setup
功能说明： 写入 MCP 配置（VS Code servers、Cursor/Cline 等 mcpServers），生成规则（标准/增强版），并可将项目关联到工作区。
整合工具集： 向导默认配置约 11 个整合领域工具（令牌减少约 75%）。可选：router 模式（约 2 个元工具，最精简）。参见完整工具目录。
预览更改而不写入文件：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 钩子。 |
| 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 | 非交互式设置转录捕获默认值。 |
终端 · 账户模式 · 团队 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%）。如需更少工具，在 env 块中添加 "CONTEXTSTREAM_PROGRESSIVE_MODE": "true" 以获得约 2 个路由元工具。参见完整工具目录。
跳转到你的工具
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 配置架构。Cursor 仍使用本地 MCP 进程，但 VS Code/Copilot 现在可以直接通过 HTTP 使用托管的 ContextStream MCP。
终端 · .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。无需在 .vscode/mcp.json 中存放本地二进制文件或 API 密钥。
终端 · .vscode/mcp.json（VS Code 原生 MCP，远程）
{
"servers": {
"contextstream": {
"type": "http",
"url": "https://mcp.contextstream.io/mcp?default_context_mode=fast"
}
}
}
更喜欢命令行？使用 code --add-mcp 添加远程服务器
终端 · 终端
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
要在 OpenCode CLI 中使用 ContextStream，请将 MCP 服务器配置添加到你的 ~/.config/opencode/opencode.json 文件（或项目根目录下的 opencode.json）：
终端 · ~/.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
要在 Codex CLI 中使用 ContextStream，请将 MCP 服务器配置添加到你的 ~/.codex/config.toml 文件：
终端 · ~/.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：
终端 · 终端
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）
终端 · 终端 · 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 文件：
终端 · .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（GUI 应用）
将 ContextStream 添加到 Claude Desktop 应用程序：
macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
Windows： %APPDATA%\Claude\claude_desktop_config.json
终端 · 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
终端 · ~/.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 支持钩子以自动强制执行 ContextStream 规则。编辑配置后，重启 Windsurf 以使更改生效。
客户端 · Cline
Cline
将 ContextStream 添加到你的 Cline MCP 配置。点击 Cline 中的 MCP 服务器图标，选择“配置”选项卡，然后点击“配置 MCP 服务器”进行编辑：
终端 · 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 服务器：
全局： 点击设置 → MCP 服务器 → 已安装 → 编辑全局 MCP 以打开 mcp_settings.json
项目： 项目根目录下的 .kilocode/mcp.json
终端 · .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 服务器：
全局： 点击设置图标 → 编辑全局 MCP 以打开 mcp_settings.json
项目： 项目根目录下的 .roo/mcp.json
终端 · .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 相同：
终端 · .mcp.json（项目根目录）
{
"mcpServers": {
"contextstream": {
"command": "contextstream-mcp",
"env": {
"CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
"CONTEXTSTREAM_API_KEY": "your_api_key"
}
}
}
}
Windows 用户：使用 cmd 包装器
终端 · .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 服务器” → “查看原始配置”访问以验证你的配置。编辑后重启 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 | 设置 → 通用 → 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 文件夹的规则，将激活模式设置为 “始终开启”，以便规则始终处于活动状态。
| 编辑器 | 项目规则位置 |
|---|---|
| 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/），每个规则文件都有一个激活模式：
- 始终开启 — 始终处于活动状态（推荐用于 ContextStream）
- 手动 — 仅当你 @提及 规则时
- 模型决定 — AI 根据描述决定
- Glob — 对匹配的文件模式处于活动状态
全局规则和根级文件（.cursorrules）始终处于活动状态。
更喜欢使用设置向导？先运行它。否则，手动添加这些标准规则。每个编辑器的示例：
Claude Code
在项目根目录创建一个 CLAUDE.md 文件，或添加到你的全局 ~/.claude/CLAUDE.md：
终端 · 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
显示增强规则（详细）
终端 · 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
在项目根目录（项目规则）或 ~/.codex/AGENTS.md（Codex 全局）/ ~/.config/opencode/AGENTS.md（OpenCode 全局）中创建一个 AGENTS.md 文件：
Codex / OpenCode 与 Claude 工具名称
Codex / OpenCode 使用原始 MCP 工具名称（例如 session_init）。Claude Code 使用命名空间工具名称（例如 mcp__contextstream__session_init）。为你的 AI 工具使用正确的格式。
终端 · 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
显示增强规则（详细）
终端 · 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：
终端 · .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
显示增强规则（详细）
终端 · .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 文件：
终端 · .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
显示增强规则（详细）
终端 · .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/ 文件夹：
终端 · .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
显示增强规则（详细）
终端 · .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/ 文件夹：
终端 · .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
显示增强规则（详细）
终端 · .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
自动生成规则
你也可以通过说：“使用 generate_rules 为此项目创建 ContextStream 规则” 来让 AI 自动生成这些规则。
经验教训系统
经验教训系统
从错误中学习 — 永不重复
经验教训系统捕获错误、更正和用户挫败感，以便 AI 助手永远不会重复相同的错误。当相关时，经验教训会自动出现在 session_init 和 context_smart 的响应中。
何时捕获经验教训
当出现以下任何情况时，应自动捕获经验教训：
| 触发器 | 示例 | 严重性 |
|---|---|---|
| 生产问题 | “由于那个更改，网站宕机了” | 严重 |
| 用户挫败感 | “不！我告诉过你不要那样做”，“WTF”，大写锁定 | 高 |
| 更正 | “那是错的，你应该……”，“修复这个” | 中 |
| 破坏性更改 | “这破坏了测试”，“构建失败” | 中/高 |
| 陈述偏好 | “我更喜欢这种方式”，“总是做 X 而不是” | 低 |
经验教训字段说明
| 字段 | 描述 | 示例 |
|---|---|---|
| title | 要记住的内容（祈使句） | “推送前始终验证 git 中的资源” |
| severity | 严重、高、中、低 | 生产问题为“严重” |
| category | 工作流、代码质量、验证、沟通、项目特定 | “工作流” |
| trigger | 导致问题的操作 | “推送了引用图片的代码，但没有提交它们” |
| impact | 出了什么问题 | “生产环境 404 错误 - 着陆页损坏” |
| prevention | 将来如何预防 | “推送前运行 git status 检查未跟踪的文件” |
| keywords | 用于将来上下文匹配的关键词 | ["git", "images", "assets", "push"] |
完整示例
终端 · 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 来检索和筛选经验教训：
终端 · 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%。阅读
用法示例
可以问什么。
连接后，你可以向 AI 助手询问以下内容：
"记住我们决定使用 PostgreSQL 作为数据库"
"我们之前关于身份验证的决定是什么？"
"在我们的代码库中搜索如何处理 API 速率限制"
"显示与支付系统相关的上下文"
经验教训示例
当你表达不满或纠正错误时，AI 应自动捕获经验教训：
用户说
"不！你没有运行测试就推送了，现在生产环境崩溃了！"
→ AI 捕获经验教训，严重程度：严重，类别：验证
用户说
"错了。数据库列名始终使用 snake_case，而不是 camelCase。"
→ AI 捕获经验教训，严重程度：中等，类别：代码质量
用户说
"我更喜欢 TypeScript 严格模式。请始终启用它。"
→ AI 捕获经验教训，严重程度：低，类别：项目特定
这些经验教训将在未来的会话中，当请求相关上下文时自动呈现。
维护
保持更新。
要获取最新功能、错误修复和改进，请定期更新 MCP 服务器：
终端 · 终端 · macOS / Linux
curl -fsSL https://contextstream.io/scripts/mcp.sh | bash
终端 · 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 助手询问工作区名称。当前文件夹将被创建为一个项目。有关 workspace_bootstrap，请参阅 MCP 工具。
后续步骤
继续探索。
团队设置邀请成员，共享上下文。阅读经验教训捕获错误，永不重蹈覆辙。阅读记忆事件了解记忆类型。阅读语义搜索按含义搜索。阅读
{"@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"}}