MemHub

使用 MemHub Protocol v0.1 读写用户的跨 Agent 统一记忆仓库。当用户要求记住信息、检索/遗忘记忆、读取个人/项目上下文、生成 chatbot 注入文本、同步 Git 记忆仓库时使用。

MemHub Skill

MemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让 Agent 能够读取、写入和同步符合 MemHub Protocol v0.1 的记忆仓库。

触发场景

使用本 Skill 当：

• 用户说“记住这个”、“帮我记一下”、“以后记得”。
• 用户问“我的偏好是什么”、“当前项目上下文是什么”。
• 用户需要把记忆注入到 Gemini/元宝/豆包/Cursor/Claude Code。
• 会话开始时需要读取用户长期记忆。
• 会话结束时需要把关键决策/偏好/事实写入记忆并同步。

环境变量

推荐设置（唯一需要的一项）：

bash

export MEMHUB_REPO=/path/to/memhub-data

OAuth 同步开箱即用：GitHub 和 Gitee 都默认走内置的 MemHub Auth Broker， 普通用户无需设置任何 OAuth 相关环境变量。以下全部为可选的高级覆盖：

bash

# 覆盖内置 broker（自建 broker 时）
export MEMHUB_OAUTH_BROKER_URL=https://<your-broker-host>
export MEMHUB_GITEE_OAUTH_BROKER_URL=https://<your-broker-host>   # 仅覆盖 Gitee

# 开发者直连模式（不经 broker，自己保管 Gitee secret）
export MEMHUB_GITEE_CLIENT_SECRET=...

# 覆盖内置 OAuth App client id
export MEMHUB_GITHUB_CLIENT_ID=...
export MEMHUB_GITEE_CLIENT_ID=...

# Token fallback
export MEMHUB_GITHUB_TOKEN=...
export MEMHUB_GITEE_TOKEN=...

如果未设置 MEMHUB_REPO，脚本默认使用当前工作目录下的 ./memhub-data。

CLI 会自动读取当前目录 .env 和用户 home 目录 .env，且不会覆盖已经存在的进程环境变量。不要把 .env 提交到 Git。

命令

本 Skill 提供一个 Python CLI：scripts/memhub.py。

bash

# 初始化仓库
python scripts/memhub.py --repo ~/memhub-data init --name dateng --role "Product Manager"

# 读取上下文
python scripts/memhub.py --repo ~/memhub-data context
python scripts/memhub.py --repo ~/memhub-data context --pack brief
# 记忆：默认直写 canonical 并本地提交（不自动推送）
python scripts/memhub.py --repo ~/memhub-data remember "用户偏好结构化直接的回答" --type preference --source agent
python scripts/memhub.py --repo ~/memhub-data remember "MemHub 采用 Git-first 架构" --type decision --project memhub --source agent
# 低置信/待人工复核的内容才进 inbox 审计缓冲
python scripts/memhub.py --repo ~/memhub-data remember "也许该支持 Notion 导出" --type fact --inbox --source agent

# 检索与遗忘
python scripts/memhub.py --repo ~/memhub-data search "Git-first"
python scripts/memhub.py --repo ~/memhub-data search "决策" --type decision --project memhub
python scripts/memhub.py --repo ~/memhub-data search "旧偏好" --include-archived   # 含已归档
python scripts/memhub.py --repo ~/memhub-data forget "过时的偏好"            # 预览
python scripts/memhub.py --repo ~/memhub-data forget "过时的偏好" --apply     # 软归档（status=archived）

# 将 inbox 缓冲项归档到 canonical（仅 --inbox 写入的内容才需要）
python scripts/memhub.py --repo ~/memhub-data promote --dry-run
python scripts/memhub.py --repo ~/memhub-data promote --apply
python scripts/memhub.py --repo ~/memhub-data promote --status all --apply   # 扫全部 inbox 项

# 检查 inbox
python scripts/memhub.py --repo ~/memhub-data inbox list
python scripts/memhub.py --repo ~/memhub-data inbox list --status all
python scripts/memhub.py --repo ~/memhub-data inbox show <filename-or-id-fragment>

# 将 inbox 半自动归档到 canonical memory
python scripts/memhub.py --repo ~/memhub-data promote --dry-run
python scripts/memhub.py --repo ~/memhub-data promote --apply
python scripts/memhub.py --repo ~/memhub-data promote <filename-or-id-fragment> --apply

# 导出给 chatbot 的上下文
python scripts/memhub.py --repo ~/memhub-data export chatbot

# 首次接入（推荐）：授权 + 自动判断拉取已有记忆 / 初始化新仓库
python scripts/memhub.py --repo ~/memhub-data onboard github --repo-name mymemhub
python scripts/memhub.py --repo ~/memhub-data onboard gitee  --repo-name mymemhub

# 同步 GitHub/Gitee（手动分步；默认 OAuth 走内置 broker）
python scripts/memhub.py --repo ~/memhub-data sync setup github --repo-name mymemhub
python scripts/memhub.py --repo ~/memhub-data sync setup gitee --repo-name mymemhub
python scripts/memhub.py --repo ~/memhub-data sync setup github --auth token --repo-name mymemhub
python scripts/memhub.py --repo ~/memhub-data sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create
python scripts/memhub.py --repo ~/memhub-data sync status
python scripts/memhub.py --repo ~/memhub-data sync

# 自检：确认本机/本仓库的自动同步是否就绪（remote/token/merge driver/MEMHUB_REPO 等）
python scripts/memhub.py --repo ~/memhub-data doctor

Agent 行为协议

上下文 pack 分级

context --pack 有四档,逐档累加内容:

• brief:用户画像、最重要的偏好、当前项目及最近决策(用于注入 chatbot)。
• standard(默认):brief + 约束、惯例、未完成任务。
• project:聚焦默认/指定项目,决策与任务更全。
• full:standard + knowledge、relations、最近 timeline。

export chatbot 默认用 brief;若存在 .memhub/templates/context-pack.md.j2,则用该模板渲染(支持 {{ name }} 等占位符)。

总原则

• MEMHUB_REPO 是用户记忆仓库；不要把用户记忆写入代码仓库。
• GitHub/Gitee remote 只是同步后端；YAML/Markdown 文件仍是可信源数据。
• 自动写入默认进入 canonical 记忆（本地提交，不自动推送）；低置信或需人工复核的才用 --inbox。
• sync setup 会触发授权、创建仓库、修改 remote；只有用户明确要求配置/切换同步时才执行。
• OAuth/token/SSH 凭据、authorization code、client secret、access token 都属于敏感信息；不要在回答中复述。

对话开始：读取上下文

本会话首次涉及记忆时，先跑一次自检确认自动同步就绪（每个会话只需一次，不要每轮都跑）：

bash

python scripts/memhub.py --repo "$MEMHUB_REPO" doctor

• 若 doctor 报 NOT ready（有 ✗），说明自动同步未生效。按提示补齐：缺 remote → 提示用户 sync setup；缺 token（常见于新机器）→ 引导用户重新授权；其余 ✗ 同理。不要静默忽略， 否则用户会误以为在自动同步，实际没有。
• 若全绿或只有 ! 提示，继续正常流程。
• doctor 是只读的、不联网，开销很小；但仍只需每会话首次跑一次即可。

确认就绪后，直接读取 context——context 会按节流阈值自动从远端拉取最新记忆，通常无需先手动 sync：

bash

python scripts/memhub.py --repo "$MEMHUB_REPO" context --pack brief

• 若距上次拉取超过 pull_throttle_seconds，context 会自动 pull --rebase 再输出。
• 自动拉取失败时，CLI 会用本地记忆并在 stderr 提示“远端同步失败，当前上下文可能不是最新”， 无需中断；如需强制最新，可显式 sync 后再读。
• 将 context 作为可审计上下文，不要当成绝对事实；遇到冲突时优先询问用户。

对话中：写入记忆

当用户明确要求记忆，或对话中形成稳定偏好/决策/事实时，默认直写 canonical：

bash

python scripts/memhub.py --repo "$MEMHUB_REPO" remember "内容" --type fact --source agent

• 直写会按 type 路由到对应 canonical 文件、去重后追加，并本地提交但不自动推送。
• 重复内容会被自动跳过。
• 只有低置信、需人工复核或批量待整理的内容，才加 --inbox 进审计缓冲，之后再 promote。

类型建议：

• decision：明确决策
• preference：稳定偏好
• fact：事实
• knowledge：可复用知识/结论
• event：重要事件
• relation：人物/组织/工具关系
• constraint：约束
• convention：惯例

同步：自动节流，无需每次手动 sync

配置了 remote 后，同步是自动的，Agent 通常无需显式调用 sync：

• 写入即同步（节流）：每次 remember / forget --apply / promote --apply 后，CLI 会 自动尝试推送。距上次推送不足 sync.push_throttle_seconds（默认 3600 秒）时只在本地提交， 超过阈值才真正 pull+push。记忆始终立即落本地，绝不丢失。
• 读取即拉取（节流）：context 命令会在 sync.pull_throttle_seconds（默认 3600 秒）阈值外 自动 pull --rebase 拉取其它设备的最新记忆；拉取失败则用本地并在 stderr 提示可能不是最新。

显式 sync 命令忽略节流，立即 pull+push，适合在对话收尾兜底，确保本次所有记忆都已上远端：

bash

python scripts/memhub.py --repo "$MEMHUB_REPO" sync

节流阈值与开关都在 .memhub/config.yaml 的 sync 段（auto_push/auto_pull / push_throttle_seconds / pull_throttle_seconds）；节流时间戳记在本机 .memhub/cache/sync.yaml （git 忽略，每台设备独立）。单次写入若想跳过自动推送，加 --no-sync。

init/sync 会自动注册结构化 merge 驱动（local git config 不随 clone 走，故每台设备首次 sync 会自愈补注册），多设备对同一记忆文件的并发追加可自动合并，不会冲突。

换新机器/新 Agent 时：凭据（token）存在本机 .memhub/secrets.yaml 且不随 git 同步， 所以新机器即使 clone 了记忆仓库也需要重新授权一次。先跑 doctor 自检，按提示补齐 remote/token 即可——全绿后自动同步即就绪。

检索与遗忘

bash

python scripts/memhub.py --repo "$MEMHUB_REPO" search "关键词" --type decision --project memhub
python scripts/memhub.py --repo "$MEMHUB_REPO" forget "过时内容"          # 预览
python scripts/memhub.py --repo "$MEMHUB_REPO" forget "过时内容" --apply   # 软归档

• forget 默认 dry-run；--apply 把命中条目 status 置为 archived，使其从 context pack 消失但保留在 Git 历史中，可审计、可回滚。
• 纠正一条记忆 = forget 旧条目 + remember 新条目。

首次接入：用 onboard（推荐）

新 agent / 新机器第一次接入时，用 onboard 一条命令完成全流程，它会自动判断该 "拉取已有记忆"还是"初始化新仓库"，避免用默认数据污染你已有的真实记忆：

bash

python scripts/memhub.py --repo "$MEMHUB_REPO" onboard gitee --repo-name mymemhub
python scripts/memhub.py --repo "$MEMHUB_REPO" onboard github --repo-name mymemhub

onboard 的流程：

1. 授权（默认走内置 broker，见下）。
2. 探测远端是否已有 MemHub 记忆仓库（含 .memhub/config.yaml）：
   • 已有 → 以远端为准拉取到本地，不写入任何默认数据（你的真实记忆直接到位）；
   • 为空 → 初始化默认记忆并推送，建立远端仓库。
3. 注册 merge 驱动、确保 auto-sync 就绪。
4. 打印 doctor 自检结果。

之后写入即自动推送、读取即自动拉取，无需再手动 sync。新机器换设备时总是优先用 onboard，不要先 init 再 sync setup（那会先播种默认数据，可能污染远端真实记忆）。

同步 setup：手动分步配置（高级）

onboard 内部会调用 setup。只有当你想单独配置/切换 remote、且明确知道本地数据状态时， 才直接用 sync setup。当用户说“配置同步”、“连接 GitHub/Gitee”、“换成 Gitee/GitHub 同步”时， 优先用 onboard。

开箱即用：GitHub 和 Gitee 都默认走内置的 MemHub Auth Broker（https://oauth.1024hub.cn）， client_secret 保管在 broker 服务端，用户无需设置任何环境变量或自建 OAuth 应用。

bash

python scripts/memhub.py --repo "$MEMHUB_REPO" sync setup github --repo-name mymemhub
python scripts/memhub.py --repo "$MEMHUB_REPO" sync setup gitee  --repo-name mymemhub

授权流程（两者一致）：

1. CLI 调用 broker 创建授权 session，得到一个 auth_url。
2. CLI 打开（或打印）该 URL；Agent 应把 URL 展示给用户，请用户在浏览器完成授权。
3. CLI 轮询 broker 直到拿到 access token，自动存入本机 .memhub/secrets.yaml（git 忽略）。
4. 不要要求用户把 access token 发到聊天里。

无浏览器环境：加 --no-browser，CLI 会打印 URL 由用户手动打开。

高级 / fallback（仅当用户明确选择时）

• 自建 broker：--broker-url https://your-broker 或设 MEMHUB_OAUTH_BROKER_URL / MEMHUB_GITEE_OAUTH_BROKER_URL。
• 开发者直连（不经 broker）：Gitee 用 --client-secret（或 MEMHUB_GITEE_CLIENT_SECRET）； GitHub 会回退到 Device Flow。
• Token / SSH：

bash

python scripts/memhub.py --repo "$MEMHUB_REPO" sync setup github --auth token --repo-name mymemhub
python scripts/memhub.py --repo "$MEMHUB_REPO" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create

同步失败与冲突处理

• 不要删除本地 inbox、canonical 文件或 .git 历史。
• 将错误摘要告诉用户，避免泄露 token/header。
• 如果 git pull --rebase 冲突，停止自动处理，报告冲突文件，让用户/Agent 单独修复。
• 如果 provider 授权失败，建议用户重新授权或切换 token/SSH fallback。
• 如果远端仓库创建失败但已存在，可以继续配置 remote 并尝试 sync。

Inbox 归档（promote）

remember 默认直写 canonical，无需 promote。只有用 --inbox 缓冲过的低置信/待复核内容 才需要 promote。整理 inbox 时先预览：

bash

python scripts/memhub.py --repo "$MEMHUB_REPO" inbox list
python scripts/memhub.py --repo "$MEMHUB_REPO" promote --dry-run

确认归档目标合理后再执行（默认 dry-run，须显式 --apply；--apply 后按节流自动推送）：

bash

python scripts/memhub.py --repo "$MEMHUB_REPO" promote --apply

promote 默认只扫 pending 的 inbox 项，可用 --status all 扫全部。归档路由规则：

• decision → projects/<project>/decisions.yaml
• preference → identity/preferences.yaml
• constraint → identity/constraints.yaml
• convention → identity/conventions.yaml
• knowledge → knowledge/product.yaml
• relation → relations/people.yaml
• fact / event → timeline/YYYY-MM.yaml

不要写入：

• 临时闲聊
• 未确认猜测
• 敏感信息，除非用户明确授权
• 无新增信息的重复内容

对话结束

如果对话中产生重要决策、偏好或事实：

1. remember 直写记忆（低置信内容用 --inbox，必要时 promote）。写入时已按节流自动推送。
2. 收尾执行一次显式 sync：它忽略节流、立即推送，确保本次会话即使在节流窗口内产生的 记忆也全部上远端（兜底，防止刚写完就关闭 Agent 导致最后几条只在本地）。

发布与安全约束

• 不要把真实 token、client secret、OAuth code 写进 SKILL.md、README、示例或提交历史。
• .memhub/secrets.yaml 必须保持本地忽略。
• 发布到 SkillHub/ClawHub 的包应包含：SKILL.md、README.md、scripts/memhub.py、templates/context-pack.md.j2。
• 发布包不应包含 __pycache__、.pyc、.git 或用户个人记忆数据。

重要原则

• MemHub 只负责存取和同步，智能判断由 Agent 完成。
• 写入必须带 source，便于追溯。
• 默认直写 canonical 记忆；低置信或需人工复核的内容才进 inbox 审计缓冲。
• Git 仓库中的 YAML/Markdown 是唯一可信源数据。