记忆共享系统

Engram      = 专家是谁 + 知道什么 + 怎么思考
Skills/Tools = 具体能做什么操作

第一层：常驻加载（load_engram 时一次性返回）
  ├── role.md              全文  ← 角色人设（背景 + 沟通风格 + 回答原则）
  ├── workflow.md          全文  ← 工作流程（决策步骤）
  ├── rules.md             全文  ← 运作规则 + 常见错误 + Onboarding 区块
  ├── knowledge/_index.md  ← 知识索引（文件列表 + 一句话描述 + 内联摘要，若 extends 会附加父知识索引）
  ├── examples/_index.md   ← 案例索引（文件列表 + 一句话描述 + uses 关联）
  ├── memory/_index.md     ← 动态记忆热层索引（最近50条，TTL过滤）
  └── <packs-dir>/_global/memory/_index.md  ← 全局用户记忆（跨专家共享）

第二层：按需加载（LLM 根据索引摘要判断后主动调用）
  └── read_engram_file(name, path)  ← 读取任意知识、案例或记忆文件（含 memory/_index_full.md）

第三层：对话中写入（LLM 识别到重要信息时主动调用）
  └── capture_memory(name, content, category, summary, memory_type, tags, conversation_id, expires, is_global)  ← 捕获用户偏好、关键决定等

knowledge/
  _index.md
  训练基础/
    _index.md
    深蹲模式.md
  营养策略/
    _index.md
    增肌期配餐.md

# macOS / Linux
brew install uv
# 或
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

claude mcp add --scope user engram-server -- uvx --from git+https://github.com/DazhuangJammy/Engram engram-server

claude mcp remove --scope user engram-server

你有一个专家记忆系统可用。对话开始时先调用 engram-server 这个 MCP 中的 list_engrams() 查看可用专家。

# 自动执行规则（傻瓜式）
- 默认原则：能由模型直接完成的事，不让用户手动执行命令；优先直接调用 MCP 工具。
- 除非环境/权限阻塞，否则不要让用户“自己去终端跑命令”。
- 如果调用了 MCP，回复时要告诉用户调用了什么 MCP 和哪个专家。
- 首次进入新项目时，默认检查并使用 `./.claude/engram`。
- 目录策略统一为“项目级优先，`~/.engram` 为共享/回退目录”。

## 自然语言意图 -> MCP 自动映射
- 用户说“找/查/推荐某类 Engram” -> 自动调用 search_engrams(query)
- 用户说“安装某个 Engram” -> 自动调用 install_engram(source-or-name)
- 安装默认写入当前项目 `./.claude/engram`，不是默认全局目录。
- 用户说“初始化当前项目 engram” -> 优先检查 `starter-complete` / `starter-template` 是否存在。
- install_engram(name/source) 失败时，不中断用户：自动调用 search_engrams(query) 找候选后重试 install_engram。
- 用户说“看统计/导出报表” -> 自动调用 stats_engrams(format=plain/json/csv)
- 用户说“创建 Engram” -> 自动进入创建助手流程（create_engram_assistant + finalize_engram_draft）
- 当用户说"打开engram管理界面"，AI 调用 open_ui()

## 专家加载与知识读取
- 用户问题匹配某个专家时，调用 load_engram(name, query)。
- load_engram 后优先看知识索引/案例索引；索引不足再 read_engram_file(name, "knowledge/xxx.md")。
- 若 workflow 明确写了 Skill 调用节点，按节点提示主动调用对应 Skills。
- load_engram 返回“继承知识索引”区块时，可 read_engram_file(父专家名, "knowledge/xxx.md") 读取父知识。
- 在 load_engram 后优先读取案例 frontmatter 的 id/title/uses/tags/updated_at，再决定要不要读具体 knowledge 文件。

## 记忆写入规则
- 发现跨专家通用信息（年龄、城市、职业、语言偏好等） -> capture_memory(..., is_global=True)
- 状态性信息（如“用户正在备考”）要加 expires（YYYY-MM-DD），到期自动归档隐藏。
- load_engram 出现“首次引导”区块时，自然收集并 capture_memory。
- 发现用户偏好/关键事实/关键决定时，及时 capture_memory(name, content, category, summary, memory_type, tags, conversation_id, expires, is_global)。
- 只要调用了工具（Skills / MCP / Subagent / 其他外部工具），都要记录工具轨迹：capture_tool_trace(name, tool_name, intent, result_summary, args_summary, status, summary, tags, conversation_id)。
- 工具调用失败也要记录，status 设为 `error`，result_summary 写清失败原因。
- engram-server 内部多数 `name` 相关工具会自动写入 tool-trace；但外部工具不会自动写，必须显式调用 capture_tool_trace。
- 去重规则：若本轮已记录过“同一 tool_name + 同一 intent”的轨迹，不重复写入。
- 外部工具记录字段优先级：至少填写 `tool_name`、`intent`、`args_summary`、`result_summary`、`status`。
- 范围规则：只有已 `load_engram(name, ...)` 的专家，才写入该 `name` 的工具轨迹，避免串专家记忆。
- 交付前检查：若本轮发生过工具调用但未写任何轨迹，结束前补记至少一条 `capture_tool_trace`。
- 记忆条目较多出现“💡 当前共 N 条记忆”时，先 read_engram_file(name, "memory/{category}.md")，再 consolidate_memory(...)。
- 用户要求删除记忆 -> delete_memory(name, category, summary)
- 用户纠正记忆 -> correct_memory(name, category, old_summary, new_content, new_summary, memory_type, tags)
- 记忆较多查历史 -> read_engram_file(name, "memory/_index_full.md")

## 知识写入规则
- 对话中形成系统性可复用知识（方法论/对比分析/决策框架）时，先询问用户是否写入知识库，确认后 add_knowledge。
- 用户纠正知识库错误时，提议并执行 add_knowledge 更新。
- add_knowledge 支持分组路径：filename 可用 "子目录/文件名"（如 "训练基础/深蹲模式"）。

## 创建 Engram 助手（双模式）
- mode=from_conversation：把当前对话自动整理成 Engram 草稿。
- mode=guided：一步步引导用户填写；用户说“没有/你来”时自动补全。
- 统一流程：
  1) 先调用 create_engram_assistant(...) 生成草稿并回显
  2) 用户确认后调用 finalize_engram_draft(draft_json, confirm=True)
  3) finalize 后必须看 lint 结果（errors 必须先修复）
- 自动生成内容时必须提示：内容可能不完整，建议用户补充。
- 创建阶段不自动生成用户记忆条目；memory 保持空模板。

## 其他
- 用户也可以用 @专家名 直接指定专家。
- 用户询问某个 engram 详细信息时，调用 get_engram_info(name)。
- 需要直接改 role.md/workflow.md/rules.md 等非知识库文件时，调用 write_engram_file(name, path, content, mode)。
- 新增/修改案例文件时，确保 frontmatter 字段齐全（id/title/uses/tags/updated_at），id 全局唯一，updated_at 用当天日期。
- 多案例命中时，先按 tags 匹配，再参考 updated_at 选更近的案例。
- 回复中引用案例时优先带 title + id，减少歧义。
- 若发现 frontmatter 缺字段或 uses 指向不存在文件，先修复再继续回答。

uvx --from git+https://github.com/DazhuangJammy/Engram engram-server ui

# 指定端口
engram-server ui --port 8080

# 不自动打开浏览器
engram-server ui --no-open

# 指定 Engram 目录
engram-server ui --packs-dir ~/.engram

engram-server serve --packs-dir ~/.engram

engram-server --packs-dir ~/.engram

engram-server list --packs-dir ~/.engram

engram-server install <git-url|engram-name> --packs-dir ~/.engram

engram-server init my-expert --packs-dir ~/.engram

engram-server init my-expert --nested --packs-dir ~/.engram

engram-server search fitness --packs-dir ~/.engram

engram-server lint [name] --packs-dir ~/.engram

uvx --from git+https://github.com/DazhuangJammy/Engram engram-server stats

uvx --from git+https://github.com/DazhuangJammy/Engram engram-server stats --json

uvx --from git+https://github.com/DazhuangJammy/Engram engram-server stats --csv

uvx --from git+https://github.com/DazhuangJammy/Engram engram-server stats --tui

# 校验全部 Engram
engram-server lint --packs-dir ~/.engram

# 仅校验一个
engram-server lint fitness-coach --packs-dir ~/.engram

engram-server stats --json --packs-dir ~/.engram
engram-server stats --csv --packs-dir ~/.engram

# 先搜索
engram-server search fitness --packs-dir ~/.engram

# 再按名称安装
engram-server install fitness-coach --packs-dir ~/.engram

engram-server init my-expert --nested --packs-dir ~/.engram

filename = "训练基础/深蹲模式"

# 复制模板并填写 baseline/engram 回答
cp evaluation/case_study_template.json evaluation/my_case_study.json

# 执行多维评测
python3 evaluation/score_case_study.py --input evaluation/my_case_study.json

# 可选导出 CSV
python3 evaluation/score_case_study.py --input evaluation/my_case_study.json --csv evaluation/my_case_study_report.csv

# 已加载 Engram: fitness-coach

## 用户关注方向
{query}

## 角色
{role.md 全文}

## 工作流程
{workflow.md 全文}

## 规则
{rules.md 全文}

## 知识索引
{knowledge/_index.md 内容，含内联摘要}

## 案例索引
{examples/_index.md 内容，含 uses 关联}

## 动态记忆
{memory/_index.md 内容，含自动捕获的用户偏好和关键信息，用 <memory> 标签包裹}

## 全局用户记忆（可选）
{<packs-dir>/_global/memory/_index.md 的活跃条目，用 <global_memory> 标签包裹}

## 首次引导（可选）
{rules.md 中的 ## Onboarding 区块提取内容}

用户第一次提到自己的基本信息时：
  → AI 调用 capture_memory(
        name="fitness-coach",   ← 当前专家名（用于节流key，不影响写入位置）
        content="用户名叫 Jammy，28岁，居住在深圳，职业是独立开发者",
        category="user-profile",
        summary="Jammy，28岁，深圳，独立开发者",
        memory_type="fact",
        is_global=True           ← 写入全局，而非当前 Engram
    )
  → 下次加载任意 Engram 时，load_engram 返回内容末尾自动附加：
    ## 全局用户记忆
    <global_memory>
    - `memory/user-profile.md` [2026-02-25] [fact] Jammy，28岁，深圳，独立开发者
    </global_memory>

<packs-dir>/_global/
└── memory/
    ├── _index.md          ← 热层索引（最近50条）
    ├── _index_full.md     ← 冷层索引（全量）
    └── user-profile.md    ← 用户基础信息

原始条目不断追加（append-only）
         ↓
某个 category 超过 30 条时
         ↓
AI 调用 read_engram_file 读取原始内容
         ↓
AI 写出去重压缩的密集摘要
         ↓
调用 consolidate_memory → 原始条目归档，摘要替换

用户："我已经不住北京了，帮我删掉那条记录"
  → AI 调用 read_engram_file("name", "memory/_index.md") 找到对应条目
  → 确认摘要文本 → 调用 delete_memory("name", "user-profile", "居住在北京")
  → 条目从索引和分类文件中同时移除

用户："我体重不是80kg了，现在75kg"
  → AI 读取 memory/_index.md，找到摘要"体重80kg"
  → 调用 correct_memory("name", "user-profile", "体重80kg",
      "用户体重75kg（已减重）", "体重75kg", memory_type="fact")
  → 原条目内容和索引同步更新，时间戳保留

用户："帮我把刚才讨论的跑步技术要点记录到知识库里"
  → AI 整理内容
  → 调用 add_knowledge("name", "跑步技术", "# 跑步技术\n\n落地方式...", "落地方式与步频优化要点")
  → 新文件写入 knowledge/跑步技术.md，knowledge/_index.md 自动追加一行

用户："我膝盖疼，还能做深蹲吗？"
  → agent 调用 list_engrams() 看到 fitness-coach
  → 判断匹配 → 调用 load_engram("fitness-coach", "膝盖疼深蹲")
  → 看到知识索引中的摘要，判断需要深入
  → 调用 read_engram_file("fitness-coach", "knowledge/膝关节损伤训练.md")
  → 拿到完整知识 → 以专家身份回答

用户："@fitness-coach 帮我制定一个增肌计划"
  → agent 识别 @ 指令 → 直接调用 load_engram("fitness-coach", "增肌计划")

<engram-name>/
  meta.json           # 支持 extends 字段实现继承
  role.md
  workflow.md
  rules.md            # 支持 ## Onboarding 区块
  knowledge/
    _index.md
    <topic>.md
  examples/           # 可选
    _index.md
    <case>.md
  memory/             # 动态记忆（自动生成，对话中捕获）
    _index.md         # 热层：最近50条
    _index_full.md    # 冷层：完整记录（按需加载）
    <category>.md

{
  "name": "sports-nutritionist",
  "extends": "fitness-coach",
  "description": "运动营养师，在健身教练基础上增加营养学知识"
}

{
  "name": "fitness-coach",
  "author": "test",
  "version": "1.0.0",
  "description": "前康复机构训练主管，10年教练经验，擅长增肌减脂、膝肩不适训练调整与可执行计划落地",
  "tags": ["健身", "营养", "训练计划"],
  "knowledge_count": 5,
  "examples_count": 3
}

Engram  = 身份 + 知识 + 决策流程
MCP 工具 = 可调用的外部能力（数据库、监控、API 等）
Skills  = 可触发的操作流程（部署、回滚、代码生成等）

## 可调用的外部工具

| 动作 | 工具类型 | 调用方式 |
|------|----------|----------|
| 查看最近提交 | MCP 工具 | 调用 git MCP server 的 git_log |
| 查看服务日志 | MCP 工具 | 调用 grafana MCP server 的 query_logs |
| 部署到测试环境 | Skill | 触发 /deploy-staging skill |
| 回滚线上版本 | Skill | 触发 /rollback skill |

my-engram/
  meta.json
  role.md

## 记忆规则
- 用户提到身体状况、伤病或疼痛时 → capture_memory(category="health", memory_type="fact", tags=["injury"])
  示例：膝盖旧伤、肩袖问题、腰椎间盘突出
- 用户说出具体训练目标时 → capture_memory(category="goals", memory_type="fact")
  示例：3个月减10斤、备战马拉松、增肌5kg
- 用户对训练计划给出反馈时 → capture_memory(category="feedback", memory_type="preference")
  示例：上次的计划太累、喜欢居家训练、不喜欢跑步
- 用户做出关键训练决定时 → capture_memory(category="decisions", memory_type="decision")
  示例：决定从全身训练开始、选择了3天分化方案

---
id: example_fitness_coach_膝盖疼的上班族
title: 膝盖疼的上班族
uses:
  - knowledge/膝关节损伤训练.md
  - knowledge/新手训练计划.md
tags:
  - fitness-coach
  - example
  - 膝关节损伤训练
  - 新手训练计划
updated_at: 2026-02-26
---

问题描述：32岁上班族，久坐导致膝盖不适...

{
  "mcpServers": {
    "engram-server": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/engram-mcp-server",
        "engram-server",
        "--packs-dir", "~/.engram"
      ]
    }
  }
}

{
  "mcpServers": {
    "engram-server": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/engram-mcp-server",
        "engram-server",
        "--packs-dir", "~/.engram"
      ]
    }
  }
}

{
  "mcpServers": {
    "engram-server": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/engram-mcp-server",
        "engram-server",
        "--packs-dir", "~/.engram"
      ]
    }
  }
}

你有一个专家记忆系统可用。对话开始时先调用 engram-server 这个 MCP 中的 list_engrams() 查看可用专家。

# 自动执行规则（傻瓜式）
- 默认原则：能由模型直接完成的事，不让用户手动执行命令；优先直接调用 MCP 工具。
- 除非环境/权限阻塞，否则不要让用户“自己去终端跑命令”。
- 如果调用了 MCP，回复时要告诉用户调用了什么 MCP 和哪个专家。
- 首次进入新项目时，默认检查并使用 `./.claude/engram`。
- 目录策略统一为“项目级优先，`~/.engram` 为共享/回退目录”。

## 自然语言意图 -> MCP 自动映射
- 用户说“找/查/推荐某类 Engram” -> 自动调用 search_engrams(query)
- 用户说“安装某个 Engram” -> 自动调用 install_engram(source-or-name)
- 安装默认写入当前项目 `./.claude/engram`，不是默认全局目录。
- 用户说“初始化当前项目 engram” -> 优先检查 `starter-complete` / `starter-template` 是否存在。
- install_engram(name/source) 失败时，不中断用户：自动调用 search_engrams(query) 找候选后重试 install_engram。
- 用户说“看统计/导出报表” -> 自动调用 stats_engrams(format=plain/json/csv)
- 用户说“创建 Engram” -> 自动进入创建助手流程（create_engram_assistant + finalize_engram_draft）
- 当用户说"打开engram管理界面"，AI 调用 open_ui()

## 专家加载与知识读取
- 用户问题匹配某个专家时，调用 load_engram(name, query)。
- load_engram 后优先看知识索引/案例索引；索引不足再 read_engram_file(name, "knowledge/xxx.md")。
- 若 workflow 明确写了 Skill 调用节点，按节点提示主动调用对应 Skills。
- load_engram 返回“继承知识索引”区块时，可 read_engram_file(父专家名, "knowledge/xxx.md") 读取父知识。
- 在 load_engram 后优先读取案例 frontmatter 的 id/title/uses/tags/updated_at，再决定要不要读具体 knowledge 文件。

## 记忆写入规则
- 发现跨专家通用信息（年龄、城市、职业、语言偏好等） -> capture_memory(..., is_global=True)
- 状态性信息（如“用户正在备考”）要加 expires（YYYY-MM-DD），到期自动归档隐藏。
- load_engram 出现“首次引导”区块时，自然收集并 capture_memory。
- 发现用户偏好/关键事实/关键决定时，及时 capture_memory(name, content, category, summary, memory_type, tags, conversation_id, expires, is_global)。
- 只要调用了工具（Skills / MCP / Subagent / 其他外部工具），都要记录工具轨迹：capture_tool_trace(name, tool_name, intent, result_summary, args_summary, status, summary, tags, conversation_id)。
- 工具调用失败也要记录，status 设为 `error`，result_summary 写清失败原因。
- engram-server 内部多数 `name` 相关工具会自动写入 tool-trace；但外部工具不会自动写，必须显式调用 capture_tool_trace。
- 去重规则：若本轮已记录过“同一 tool_name + 同一 intent”的轨迹，不重复写入。
- 外部工具记录字段优先级：至少填写 `tool_name`、`intent`、`args_summary`、`result_summary`、`status`。
- 范围规则：只有已 `load_engram(name, ...)` 的专家，才写入该 `name` 的工具轨迹，避免串专家记忆。
- 交付前检查：若本轮发生过工具调用但未写任何轨迹，结束前补记至少一条 `capture_tool_trace`。
- 记忆条目较多出现“💡 当前共 N 条记忆”时，先 read_engram_file(name, "memory/{category}.md")，再 consolidate_memory(...)。
- 用户要求删除记忆 -> delete_memory(name, category, summary)
- 用户纠正记忆 -> correct_memory(name, category, old_summary, new_content, new_summary, memory_type, tags)
- 记忆较多查历史 -> read_engram_file(name, "memory/_index_full.md")

## 知识写入规则
- 对话中形成系统性可复用知识（方法论/对比分析/决策框架）时，先询问用户是否写入知识库，确认后 add_knowledge。
- 用户纠正知识库错误时，提议并执行 add_knowledge 更新。
- add_knowledge 支持分组路径：filename 可用 "子目录/文件名"（如 "训练基础/深蹲模式"）。

## 创建 Engram 助手（双模式）
- mode=from_conversation：把当前对话自动整理成 Engram 草稿。
- mode=guided：一步步引导用户填写；用户说“没有/你来”时自动补全。
- 统一流程：
  1) 先调用 create_engram_assistant(...) 生成草稿并回显
  2) 用户确认后调用 finalize_engram_draft(draft_json, confirm=True)
  3) finalize 后必须看 lint 结果（errors 必须先修复）
- 自动生成内容时必须提示：内容可能不完整，建议用户补充。
- 创建阶段不自动生成用户记忆条目；memory 保持空模板。

## 其他
- 用户也可以用 @专家名 直接指定专家。
- 用户询问某个 engram 详细信息时，调用 get_engram_info(name)。
- 需要直接改 role.md/workflow.md/rules.md 等非知识库文件时，调用 write_engram_file(name, path, content, mode)。
- 新增/修改案例文件时，确保 frontmatter 字段齐全（id/title/uses/tags/updated_at），id 全局唯一，updated_at 用当天日期。
- 多案例命中时，先按 tags 匹配，再参考 updated_at 选更近的案例。
- 回复中引用案例时优先带 title + id，减少歧义。
- 若发现 frontmatter 缺字段或 uses 指向不存在文件，先修复再继续回答。

_CONSOLIDATE_HINT_THRESHOLD = 30

uv cache clean

claude mcp add --scope user engram-server -- \
  uvx --from git+https://github.com/DazhuangJammy/Engram engram-server \
  --packs-dir "$HOME/Library/Mobile Documents/com~apple~CloudDocs/EngramPacks"

cd ~/.engram
git init
git remote add origin <your-private-repo-url>
git add .
git commit -m "init engram packs"
git push -u origin main

pytest -q