| get_user_contextA | 获取用户的个性化上下文（冷启动，分层延迟可控）。 / Get tiered cold-start user context with latency control. **Lifecycle: startup** — 对话开始时调用，为 AI 注入用户身份和上下文。
Lifecycle: startup — call at conversation start to inject user identity and context.
用途：在每次新对话开始时调用，了解用户是谁、如何工作、学到了什么、质量标准是什么。
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".
token_budget: 上下文 token 预算（可选）。设定后按优先级裁剪 section，低优先级 section 先丢弃。不设则返回全量。
Optional token budget. When set, sections are included by priority until budget is exhausted.
user_prompt: 用户当前提问（可选）。传入后会追加到上下文末尾，并与已存 Playbook 的
triggers 关键词匹配，命中时浮现「相关 Playbook」小节（标题 + ID；用 get_playbooks(mode="get") 查看完整步骤）。
Optional current user prompt. Appended to the context and matched against stored
playbook trigger keywords; hits surface a "Matched Playbooks" section (title + id;
call get_playbooks(mode="get") for the full steps).
|
| get_identity_cardA | 导出用户的可携带 AI 身份卡（Markdown 格式）。 / Export the user's portable AI identity card as Markdown. Owner/export surface: writes exports/identity_card.md and is refused for non-owner callers when governance is enabled.
用途：需要把用户身份、工作方式、质量标准、经验教训分享给其它 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.
|
| get_project_contextA | 读取特定项目的知识快照（项目级，只含该项目的历史）。 / Read the knowledge snapshot for a specific project, containing only that project's history. 用途：想了解某个项目之前的技术栈、已知问题、协作次数时调用。
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.
|
| get_relevant_knowledgeA | 按项目路径自动推荐最相关的经验教训（无需搜索词）。 / Automatically recommend the most relevant lessons for a project path, without search keywords. **Lifecycle: retrieval** — 在对话中需要项目相关的历史知识时调用。
Lifecycle: retrieval — call mid-conversation when project-relevant past knowledge is needed.
用途：你知道当前项目路径但不知道该搜什么词时调用，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).
include_freshness: 为每条结果附加 freshness/新鲜度提示（默认 False，保持旧输出不变）。 / Attach a per-item freshness hint (default False; output is unchanged when omitted).
|
| search_knowledgeA | 搜索知识库（lessons/decisions/playbooks）。 / Search lessons, decisions, and playbooks by keyword. **Lifecycle: retrieval** — 在对话中需要检索历史知识时调用。
Lifecycle: retrieval — call during conversation when past knowledge is needed.
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 explore_knowledge(mode="similar").
Args:
query: Search query keywords.
scope: Search scope: 'all', 'lessons', 'decisions', or 'playbooks'.
limit: Maximum number of items to return (default 10).
filters_json: Optional JSON string with filter criteria. Supported keys:
- "domain": str — only items whose domain contains this value
- "tier": str — only items matching this tier ('staging' or 'verified')
- "date_after": str — ISO date string, only items created after this date
Example: '{"tier": "verified", "domain": "python"}'
include_freshness: Attach a per-item freshness hint (fresh/aging/stale)
to each returned item. Default False keeps the response unchanged.
max_field_chars: Per-field size cap. Every string field in each returned
item (detail/reasoning/description/steps/...) longer than this is
clipped with a "[+N chars truncated]" marker so a few large bodies
cannot blow up the client. Item shape, ids, and headlines are kept.
Set 0 for full untruncated bodies (default 400).
|
| memory_storeA | 统一知识写入入口 — 根据 kind 自动路由到 add_lesson / add_decision / add_playbook。
Unified knowledge write endpoint — routes to add_lesson / add_decision / add_playbook based on kind. **Lifecycle: writeback** — 对话中产生值得长期保留的知识时调用。
Lifecycle: writeback — call when the conversation produces knowledge worth persisting.
这是 Provider 兼容的统一写入接口。如果你已经明确知道要写 lesson/decision/playbook，
也可以直接调用对应的专用工具。本工具的优势在于：调用方不需要知道 Engram 内部的分类体系。
This is a provider-compatible unified write interface. You may also call the specialized
tools directly. The advantage here: callers don't need to know Engram's internal taxonomy.
Args:
kind: 知识类型 — 'lesson' | 'decision' | 'playbook'。批量模式下作为各条目的类型（playbook 不支持批量）。 / Knowledge type; in batch mode, the item type for every item (playbook not supported in batch).
content_json: 知识内容 JSON 字符串（单条模式必填）。格式因 kind 而异：
- lesson: {"summary": "...", "detail": "...", "domain": "..."}
- decision: {"question": "...", "choice": "...", "reasoning": "..."}
- playbook: {"title": "...", "triggers": "...", "steps_json": "[...]"}
Content JSON string (required in single mode). Schema varies by kind (see above).
source_tool: 调用来源工具（可选），如 'claude_code', 'cursor'。 / Source tool (optional).
items_json: 条目 JSON 数组；给了就走批量写入（一次导入多条 lesson/decision）。 / JSON array of items; when provided, batch-writes multiple lessons/decisions in one call.
|
| add_lessonA | 记录单条经验教训（你已经知道要记什么）。 / Record one lesson learned when you already know what to save. **Lifecycle: writeback** — 对话中学到可复用的经验时调用。
Lifecycle: writeback — call when reusable experience is learned during conversation.
用途：用户明确说出一条踩坑经验或技术发现时调用。
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).
source_agent: 产生/校验此条目的 agent 身份（可选，如 'claude_code'，比 source_tool 更细）。 / Agent identity that produced or validated this entry (optional; finer-grained than source_tool).
run_id: 产生此条目的工作流/会话运行 ID（可选）。 / Workflow/session run id that produced this entry (optional).
last_validated_at: 人/agent 最近确认此条目仍然成立的 ISO-8601 时间（可选）。 / ISO-8601 time this entry was last confirmed to still hold (optional).
|
| add_decisionA | 记录单条关键决策（用户明确选了某个方案）。 / Record one key decision when the user explicitly chose an option. **Lifecycle: writeback** — 对话中做出明确决策时调用。
Lifecycle: writeback — call when an explicit decision is made during conversation.
用途：用户说"我们决定用 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.
决策链（Decision Thread）：同一问题改选方案时，会自动在决策链中标记旧决策为 superseded。
也可显式传 supersedes 参数指定被取代的旧决策 ID。
Decision thread: when the same question gets a different choice, the old decision is
automatically marked superseded. You may also explicitly pass supersedes with the old ID.
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'.
supersedes: 被本决策取代的旧决策 ID（可选）。填写后自动在决策链中建立 supersedes 关系。 / ID of the old decision this one replaces (optional). Creates a supersedes edge in the decision thread.
source_agent: 产生/校验此决策的 agent 身份（可选）。 / Agent identity that produced or validated this decision (optional).
run_id: 产生此决策的工作流/会话运行 ID（可选）。 / Workflow/session run id that produced this decision (optional).
last_validated_at: 最近确认此决策仍然成立的 ISO-8601 时间（可选）。 / ISO-8601 time this decision was last confirmed to still hold (optional).
|
| add_playbookA | 记录操作手册（Playbook）— 结构化的多步骤流程。 / Record an operational playbook — a structured multi-step procedure. 用途：完成一个多步骤操作流程后（如发布到 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.
required_tools_json: 工具依赖 JSON 数组（可选），只声明工具名/用途，不写本机路径。 / Tool dependencies JSON array (optional); declares names/purposes, not local paths.
tool_refs: 简写工具名，逗号分隔（可选）。 / Shorthand tool names, comma-separated (optional).
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).
|
| update_identityA | 更新一个身份字段。 / Update one identity field. 用途：需要修改 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.
source_tool: 调用来源工具（如 'claude_code', 'codex', 'cursor'），用于字段级溯源。 / Source tool for field-level provenance tracking.
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（列表）。
|
| save_project_snapshotA | 写入或更新项目的知识快照（写操作，不是读取）。 / Write or update a project's knowledge snapshot; this is a write operation, not a read. 用途：保存或更新当前项目的技术栈、已知问题、注释等信息。
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.
|
| wrap_up_sessionA | 会话结束一键收尾：自动提取知识、操作流程并保存项目快照。 / Wrap up a session in one step: extract knowledge, detect playbooks, and save a project snapshot. **Lifecycle: session-end** — 对话结束时调用，完成知识提取和上下文保存。
Lifecycle: session-end — call at conversation end to extract knowledge and persist session context.
用途：一次对话结束时调用，把会话摘要交给 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).
|
| doctorA | 记忆系统自诊断。 / Memory system self-diagnosis. 用途：检查 Engram 记忆系统健康状态，发现潜在问题（数据碎片、过期知识、冲突决策、
身份层异常等）。这是 MCP doctor；CLI 冲突视图请用 ``engram conflicts list``。
Purpose: Run a comprehensive health check on the Engram memory system —
detects data fragmentation, stale knowledge, conflicting decisions, identity
issues, and more.
Args:
output_format: "markdown" 或 "json"。 / "markdown" or "json".
|
| get_recent_contextA | 找回最近的 AI 对话上下文。 / Retrieve the most recent AI conversation context. 用途：上下文丢失时（工具重启、会话断开）调用，找回之前的工作状态。
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).
|
| get_resume_briefA | 跨会话/跨工具接续简报（v3.30 新增）。 / Cross-session, cross-tool resume brief. **用途：v3.30 行业首家"一次调用拿到完整接续简报"的高层 API。**
用户切换工具（Claude Code → Codex/Cursor）或开新对话时，AI 调用本工具
一次即可拿到：用户身份 + 当前项目状态 + 今日日志 + 最近会话上下文 +
最近经验/决策 + 建议阅读的项目文档清单。结果用
``<engram-resume priority="high">`` XML 标签包裹，提示客户端 AI 优先遵守。
Purpose (v3.30): the "what does the next AI need to know in 30 seconds"
high-level endpoint. When users switch tools or open a new chat,
calling this once returns identity + project state + today's daily log
+ recent context + top lessons/decisions + suggested project docs to
read. Result is wrapped in ``<engram-resume priority="high">`` so client
AIs (Claude Code additionalContext, Codex system prompt, etc.) treat
it as high-priority reference context.
Lifecycle: **session start** — call before the first user message in a
new session when continuing prior work, or whenever the user says
things like "接着上次", "继续之前", "what were we doing".
Args:
project_folder: 项目文件夹路径（可选）。留空只返回身份卡。 /
Project folder (optional). Empty returns identity-only.
token_budget: 输出 token 软上限（默认 2000，约 8000 字符）。 /
Soft cap for output tokens (default 2000 ≈ 8000 chars).
include_resume_pack: Include structured ``project_resume_pack.v1`` in
the JSON response. Defaults to false to preserve existing output.
include_agent_context_pack: Include structured
``agent_context_pack.v1`` for delegated sub-agent briefing.
Defaults to false to preserve existing output.
agent_role: Role used to shape the optional agent context pack.
task_summary: Current delegated task summary for agent-pack selection.
|
| get_recallA | 获取结构化 Recall Surface v1 载荷。 / Get a structured Recall Surface v1 payload. 用途：在新任务、跨工具接续或需要"一次拿到可执行记忆包"时调用。
返回身份摘要、最近活动、项目/查询相关知识和治理元数据。
Purpose: Call when a new task or cross-tool handoff needs one structured,
actionable memory bundle: identity slice, recent activity, relevant
knowledge, and governance metadata.
注意：该聚合视图可能组合多类知识和最近上下文，因此治理开启时仅 owner
(private-self) 可读；非 owner 会在读取前被拒绝，不触发搜索或遥测写入。
Note: Because this aggregate view can combine multiple knowledge classes and
recent context, it is owner-only when governance is enabled. Non-owners are
refused before any search or telemetry side effect runs.
Args:
project_folder: 项目文件夹路径（可选）。 / Project folder path (optional).
query: 可选搜索焦点。 / Optional search focus.
limit: 最多返回多少条知识（默认 8，上限 20）。 / Max knowledge items (default 8, max 20).
token_budget: 知识片段的粗略 token 预算（默认 2000）。 / Rough token budget for knowledge items.
include_freshness: 是否附加 freshness 提示。 / Attach freshness hints.
collapse_versions: 是否折叠版本链到当前 HEAD。 / Collapse version chains to current heads.
|
| get_daily_logA | 读取项目的每日日志（人类可读的会话时间线）。 / Read a project's daily log (human-readable session timeline). 用途：v3.30 新增——每次 wrap_up_session 会在 ``~/.engram/daily/<pid>/<YYYY-MM-DD>.md``
追加一条带时间戳的条目（含 lesson/decision/playbook 计数 + 摘要前 600 字符）。
新会话需要"上次到底干了什么"的快速概览时调本工具，比 search_knowledge 更直观。
Purpose (v3.30): every wrap_up_session appends a timestamped entry to
``~/.engram/daily/<pid>/<YYYY-MM-DD>.md`` with a lesson/decision tally
and the first ~600 chars of the summary. Call this when a new session
needs a glance-able "what happened today" timeline — faster than
search_knowledge for recall.
Args:
project_folder: 项目文件夹路径。 / Project folder path.
date: ISO 日期 ``YYYY-MM-DD``（可选，默认今天）。 / ISO date (optional, defaults to today).
|
