用途：在每次新对话开始时调用，了解用户是谁、如何工作、学到了什么、质量标准是什么。
Purpose: Call at the start of each new conversation to understand who the user is, how they work, what they have learned, and their quality bar.

分层说明 / Tiered behaviour:
- "quick": 仅身份画像 + 工作偏好（纯 JSON 读取，无文件扫描，最低延迟）。
  Profile + preferences only — pure JSON reads, no filesystem scans. Lowest latency.
- "standard"（默认）: 加上质量标准、经验领域、相关教训/决策、项目快照。跳过昂贵的 reconcile。
  Default. Adds quality, domains, top lessons/decisions, project snapshot. Skips expensive reconciliation.
- "full": 完整上下文，含冲突检测、过期/暂存提醒、自动同步副作用。仅在用户明确要求"全量回顾"时使用。
  Full context including conflict detection, stale/staging warnings, auto-sync side effects. Use only when the user explicitly asks for a comprehensive memory review.

注意：默认 "standard" 已覆盖绝大多数冷启动需求；只有用户问"我们之前所有决定/经验"或要做记忆健康检查时才用 "full"。
Note: "standard" covers most cold-start needs. Use "full" only when the user asks for a comprehensive memory review.

Args:
    project_folder: 当前项目文件夹路径（可选）。 / Current project folder path (optional).
    level: "quick" | "standard" | "full"，默认 "standard"。 / Tier — defaults to "standard".

用途：需要把用户身份、工作方式、质量标准、经验教训分享给其它 AI 工具时调用。
Purpose: Call when another AI tool needs a self-contained summary of the user's identity, work style, quality standards, and lessons.

注意：如果本会话只需要运行时上下文，用 get_user_context 更合适。
Note: If the current session only needs runtime context, get_user_context is usually the better choice.

用途：想了解某个项目之前的技术栈、已知问题、协作次数时调用。
Purpose: Call when you need a project's previous tech stack, known issues, notes, or collaboration history.

注意：如果想获取用户级完整身份上下文，用 get_user_context；如果想写入项目快照，用 save_project_snapshot。
Note: Use get_user_context for full user-level context; use save_project_snapshot to write a project snapshot.

Args:
    project_folder: 项目文件夹路径。 / Project folder path.

用途：你知道当前项目路径但不知道该搜什么词时调用，Engram 根据项目技术栈自动筛选。
Purpose: Call when you know the current project path but not the right search terms; Engram filters by project tech stack.

注意：如果用户给了明确搜索词，用 search_knowledge 更直接。
Note: If the user provides explicit search keywords, search_knowledge is more direct.

Args:
    project_folder: 当前项目文件夹路径。 / Current project folder path.
    limit: 最多返回多少条（默认 8）。 / Maximum number of items to return (default 8).

Call when the user asks to find knowledge about a specific topic,
or recalls a procedure ('X how to' / 'X steps').

If you only have a project path and no query, use get_relevant_knowledge;
if you have an existing knowledge ID, use find_similar_knowledge.

Args:
    query: Search query keywords.
    scope: Search scope: 'all', 'lessons', 'decisions', or 'playbooks'.
    limit: Maximum number of items to return (default 10).

用途：用户明确说出一条踩坑经验或技术发现时调用。
Purpose: Call when the user explicitly states a lesson, pitfall, or technical finding.

注意：如果用户给了一段会话摘要让你自动提取，请用 extract_session_insights 而不是本工具。
Note: If the user gives a session summary for automatic extraction, use extract_session_insights instead.

Args:
    summary: 教训的一行摘要。 / One-line lesson summary.
    detail: 详细说明（可选）。 / Detailed explanation (optional).
    domain: 技术领域（可选），可填多个，逗号分隔，如 'python,testing'。 / Technical domain (optional); may contain multiple comma-separated labels such as 'python,testing'.
    source_tool: 记录来源工具，如 'claude_code', 'codex'（可选，建议填写）。 / Source tool, such as 'claude_code' or 'codex' (optional but recommended).
    source_url: 如果教训来自外部内容，填写来源 URL（可选）。 / Source URL when the lesson comes from external content (optional).

用途：用户说"我们决定用 X"或"以后都用 Y"时调用。
Purpose: Call when the user says they decided to use X or will use Y going forward.

注意：如果用户给了一段会话摘要让你自动提取，请用 extract_session_insights 而不是本工具。
Note: If the user gives a session summary for automatic extraction, use extract_session_insights instead.

Args:
    question: 决策的问题，如"数据库选型"。 / Decision question, such as 'database choice'.
    choice: 做出的选择，如"PostgreSQL"。 / Chosen option, such as 'PostgreSQL'.
    reasoning: 选择的理由（可选）。 / Reasoning for the choice (optional).
    source_tool: 记录来源工具，如 'claude_code', 'codex'（可选，建议填写）。 / Source tool, such as 'claude_code' or 'codex' (optional but recommended).
    project: 关联项目（可选）。 / Related project (optional).
    domain: 技术领域（可选），可填多个，逗号分隔，如 'architecture,database'。 / Technical domain (optional); may contain multiple comma-separated labels such as 'architecture,database'.

用途：完成一个多步骤操作流程后（如发布到 Registry、上架应用等），将步骤和经验记录为 Playbook，
方便日后调取复用，避免重复摸索。
Purpose: After completing a multi-step operational process (publishing to a registry, app deployment, etc.),
record the steps as a Playbook for future retrieval.

每条 Playbook 独立存储为单个文件，通过 triggers（记忆点关键词）快速调取。
Each Playbook is stored as an individual file, quickly retrievable via trigger keywords.

Args:
    title: 流程名称，如 'MCP Registry 发布流程'。 / Playbook name, e.g., 'MCP Registry publish workflow'.
    triggers: 记忆点关键词，逗号分隔，如 '发布,registry,上架'。 / Trigger keywords (comma-separated) for quick retrieval.
    steps_json: 步骤 JSON 数组，每个元素含 order/action/detail。 / Steps as a JSON array, each with order/action/detail.
    description: 流程概述（可选）。 / Brief description (optional).
    domain: 技术领域，逗号分隔（可选）。 / Domain labels, comma-separated (optional).
    preconditions: 前提条件，逗号分隔（可选）。 / Preconditions, comma-separated (optional).
    pitfalls: 常见陷阱，逗号分隔（可选）。 / Common pitfalls, comma-separated (optional).
    outcome: 预期结果（可选）。 / Expected outcome (optional).
    source_tool: 来源工具（可选）。 / Source tool (optional).

用途：安装、发现或确认某个工具/程序/运行时的位置和版本后调用，让所有 AI 工具都能快速查到。
Purpose: Call after installing, discovering, or confirming a tool's location and version, so all AI tools can find it.

写入时机 / When to call:
- 安装新工具后（pip install, npm install -g, 手动下载等）
- 发现系统上已有工具的准确路径后
- 工具版本升级后
- 发现某些路径不能用时（如 Windows Store stub）更新 notes 警告

Args:
    name: 工具名称（如 'Python', 'gh', 'wrangler'）。 / Tool name, e.g., 'Python', 'gh', 'wrangler'.
    path: 可执行文件或配置文件的完整路径。 / Full path to executable or config file.
    category: 分类：runtime, cli, library, credential, config, service, other。 / Category.
    version: 版本号。 / Version string.
    purpose: 用途简述。 / Brief description of what this tool is for.
    install_method: 安装方式（pip, npm, manual, system 等）。 / How it was installed.
    notes: 备注（注意事项、陷阱、替代方案等）。 / Notes, caveats, alternatives.
    source_tool: 哪个 AI 工具登记的（如 'claude_code', 'codex'）。 / Which AI tool registered this.

用途：需要查找某个工具的路径、版本或安装方式时调用。避免重复搜索或重新安装已有工具。
Purpose: Call when you need a tool's path, version, or install method. Prevents re-searching or re-installing.

Args:
    query: 搜索关键词（名称、分类、用途均可匹配）。 / Search keywords matching name, category, purpose, or path.

用途：查看当前环境中所有已知的工具、运行时和程序。
Purpose: View all known tools, runtimes, and programs in the current environment.

Args:
    category: 按分类筛选（runtime, cli, library, credential, config, service, other），留空列出全部。 / Filter by category; empty lists all.

用途：需要修改 profile、preferences、trust_boundaries、work_style 或 quality_standards 时调用。
Purpose: Call when changing profile, preferences, trust_boundaries, work_style, or quality_standards.

注意：updates_json 必须只包含该字段允许的键；敏感字段边界应通过 trust_boundaries 管理。
Note: updates_json should contain only keys valid for that field; manage sensitive-field boundaries through trust_boundaries.

Args:
    field: 字段名：profile、preferences、trust_boundaries、work_style 或 quality_standards。 / Field name: profile, preferences, trust_boundaries, work_style, or quality_standards.
    updates_json: 包含要更新字段的 JSON 字符串。 / JSON string containing the fields to update.

Field-specific keys / 字段专用键:
    profile: role, language, technical_level, description / role、language、technical_level、description。
    preferences: work_patterns (dict), communication (str), tool_preferences (dict), playbook_auto_extract (bool, default true) / work_patterns（字典）、communication（字符串）、tool_preferences（字典）、playbook_auto_extract（布尔，默认 true）。
    trust_boundaries: default_sharing, tool_access, private_fields, restricted_fields / default_sharing、tool_access、private_fields、restricted_fields。
    work_style: preferences (dict), communication (str) / preferences（字典）、communication（字符串）。
    quality_standards: acceptance_threshold (1-5), rules (list) / acceptance_threshold（1-5）、rules（列表）。

用途：保存或更新当前项目的技术栈、已知问题、注释等信息。
Purpose: Call to save or update a project's tech stack, known issues, notes, and related metadata.

注意：读取项目快照用 get_project_context，不是本工具。
Note: Use get_project_context to read a project snapshot; this tool writes one.

Args:
    project_folder: 项目文件夹路径。 / Project folder path.
    data_json: JSON 字符串，支持字段 title、tech_stack、known_issues、notes。 / JSON string supporting fields: title, tech_stack, known_issues, and notes.

用途：一次对话结束时调用，把会话摘要交给 Engram 自动提取 lessons、decisions 和 Playbook 草稿，并可选更新项目快照。
Purpose: Call at the end of a conversation to let Engram extract lessons, decisions, and playbook drafts from the summary and optionally update the project snapshot.

Playbook 自动提取：如果摘要描述了一个多步骤操作流程（3+ 步骤，含顺序标记和操作动词），会自动生成 Playbook 草稿存入 staging。返回值中会包含 playbook_draft 字段（含 confidence: high/medium），AI 工具应根据 confidence 决定是否提示用户。可通过 update_preferences(playbook_auto_extract=false) 关闭此功能。
Playbook auto-extraction: If the summary describes a multi-step operational workflow (3+ steps with sequential markers and action verbs), a Playbook draft is auto-generated into staging. The return value includes a playbook_draft field (with confidence: high/medium); AI tools should decide whether to notify the user based on confidence. Disable via update_preferences(playbook_auto_extract=false).

注意：如果只想提取知识不用保存项目，用 extract_session_insights；如果只想保存项目快照，用 save_project_snapshot。
Note: Use extract_session_insights when you only want extraction, and save_project_snapshot when you only want to save a project snapshot.

Args:
    summary: 会话摘要（自由文本，段落或要点列表均可）。 / Session summary in free text; paragraphs or bullet lists both work.
    project_folder: 项目文件夹路径（可选，不填则只提取知识不保存快照）。 / Project folder path (optional; omit it to extract knowledge without saving a snapshot).
    source_tool: 调用来源工具，如 'claude_code', 'codex'。 / Calling source tool, such as 'claude_code' or 'codex'.
    project_title: 项目名称（可选，仅在首次保存快照时需要）。 / Project title (optional; mainly needed when first saving a snapshot).
    tech_stack: 技术栈（可选，逗号分隔）。 / Tech stack (optional, comma-separated).
    known_issues: 已知问题（可选，逗号分隔）。 / Known issues (optional, comma-separated).

用途：在关键节点（任务启动、阶段完成、方向变更）自动调用，静默记录工作状态。
Purpose: Call at key moments (task start, milestone, direction change) to silently record work state.

设计理念：像 Office 自动保存 — 平时无感，崩溃/重启时可找回。
Design: Like Office autosave — invisible during work, recoverable after crash/restart.

Args:
    tool: 调用来源工具名，如 'claude_code', 'codex', 'cursor'。 / Source tool name.
    content: 上下文内容（当前任务、进度、下一步，自由文本）。 / Context content (current tasks, progress, next steps, free text).
    session_id: 会话 ID（可选）。留空则新建会话，填入已有 ID 则追加到同一会话文件。 / Session ID (optional). Empty creates new session; existing ID appends to same file.
    project_folder: 项目路径（可选，写入文件头）。 / Project folder path (optional, written to file header).

用途：上下文丢失时（工具重启、会话断开）调用，找回之前的工作状态。
Purpose: Call after context loss (tool restart, session disconnect) to recover previous work state.

不会自动加载到新会话 — 只在你需要时才读取。
Does NOT auto-load into new sessions — only reads when you ask.

Args:
    tool: 工具名（可选）。留空则搜索所有工具的上下文。 / Tool name (optional). Empty searches all tools.
    limit: 最多返回几个会话（默认 1 = 最近一次）。 / Max sessions to return (default 1 = most recent).

用途：查看有哪些历史会话记录可以找回。
Purpose: See which historical session records are available for recovery.

Args:
    tool: 工具名（可选）。留空则列出所有工具。 / Tool name (optional). Empty lists all tools.
    limit: 最多返回多少条（默认 20）。 / Max entries to return (default 20).