Memhub

MemHub Skill

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

触发场景

使用本 Skill 当：

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

环境变量

推荐设置：

export MEMHUB_REPO=/path/to/memhub-data

同步 setup 可选使用：

# MemHub Auth Broker：后端只协助获取 token，后续操作由 CLI 直接完成
export MEMHUB_AUTH_BROKER_URL=https://oauth.1024hub.cn
export MEMHUB_AUTH_PROVIDER=auto  # 可选：auto/github/gitee；auto 会按机器地区自动选择
export MEMHUB_API_BASE_URL=https://<your-memhub-api-host>

# GitHub Device Flow 已内置 MemHub OAuth App client id；普通用户通常无需设置
# Gitee 要做到用户只点确认授权，需要 MemHub OAuth Broker 保管 client_secret
export MEMHUB_GITEE_OAUTH_BROKER_URL=https://<your-broker-host>

# 开发者直连模式才需要 Gitee client secret；公开 skill 包不会内置 secret
export MEMHUB_GITEE_CLIENT_SECRET=...

# 如需覆盖内置 OAuth App，开发者可设置：
export MEMHUB_GITHUB_CLIENT_ID=...
export MEMHUB_GITEE_CLIENT_ID=...

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

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

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

命令

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

# 初始化仓库
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

# 写入 inbox
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 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

# MemHub Auth Broker 登录：只领取 token；业务操作由 CLI 直接完成；支持 github/gitee/auto
python scripts/memhub.py --repo ~/memhub-data auth providers --broker-url https://oauth.1024hub.cn
python scripts/memhub.py --repo ~/memhub-data auth detect
python scripts/memhub.py --repo ~/memhub-data auth login --broker-url https://oauth.1024hub.cn
python scripts/memhub.py --repo ~/memhub-data auth login --provider github --broker-url https://oauth.1024hub.cn
python scripts/memhub.py --repo ~/memhub-data auth login --provider gitee --broker-url https://oauth.1024hub.cn
python scripts/memhub.py --repo ~/memhub-data auth status
python scripts/memhub.py --repo ~/memhub-data auth refresh --provider github
python scripts/memhub.py --repo ~/memhub-data auth logout --provider github

# 同步 GitHub/Gitee（默认 OAuth；发布版应内置 GitHub/Gitee OAuth app 配置）
python scripts/memhub.py --repo ~/memhub-data sync setup github --repo-name mh-memories
python scripts/memhub.py --repo ~/memhub-data sync setup gitee --repo-name mh-memories
python scripts/memhub.py --repo ~/memhub-data sync setup github --auth token --repo-name mh-memories
python scripts/memhub.py --repo ~/memhub-data sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mh-memories --no-create
python scripts/memhub.py --repo ~/memhub-data sync status
python scripts/memhub.py --repo ~/memhub-data sync

Agent 行为协议

安装后首次使用：主动引导授权

当用户刚安装/启用本 Skill，或用户第一次要求跨设备同步、远端备份、登录、同步 GitHub/Gitee 记忆仓库时，Agent 必须主动执行/引导以下流程，而不是等用户自己发现命令：

1. 确认 MemHub repo 路径。若用户未提供，默认使用 ~/memhub-data 或环境变量 MEMHUB_REPO。
2. 如果 repo 不存在，先初始化：

python scripts/memhub.py --repo "$MEMHUB_REPO" init --name <user-name> --role ""

3. 告知用户将通过 Auth Broker 获取 token，后端只协助授权，后续同步/记忆操作由本地 CLI 完成。
4. 先检测推荐 Provider：

python scripts/memhub.py --repo "$MEMHUB_REPO" auth detect

5. 检查当前授权状态：

python scripts/memhub.py --repo "$MEMHUB_REPO" auth status

6. 如果 credential 缺失，主动给出并执行登录命令（默认 auto，国内机器会选 Gitee，其他地区会选 GitHub）：

python scripts/memhub.py --repo "$MEMHUB_REPO" auth login --broker-url https://oauth.1024hub.cn

7. 登录完成后再次运行 auth status。只有 credential 可用时，才继续执行远端同步配置或同步。
8. 登录过程中如果 CLI 打印授权 URL，应把 URL 发给用户并提示“打开后完成授权，再回复已授权”。不要复述 token、authorization code 或 client secret。

总原则

• MEMHUB_REPO 是用户记忆仓库；不要把用户记忆写入代码仓库。
• GitHub/Gitee remote 只是同步后端；YAML/Markdown 文件仍是可信源数据。
• 自动写入默认进入 inbox，不要直接写 canonical memory。
• sync setup 会触发授权、创建仓库、修改 remote；只有用户明确要求配置/切换同步，或首次使用时用户同意开启远端同步后才执行。
• auth login --provider auto|github|gitee 只用于通过 MemHub Auth Broker 领取对应 provider 的 token；auto 按机器地区自动选择：国内 locale/timezone/env 默认 gitee，其他地区默认 github。领取后后端不参与 memory/workspace/sync/import/export 等业务操作。授权 session 有效期约 5 分钟，token 只返回一次，重复读取应视为 consumed。
• OAuth/token/SSH 凭据、authorization code、client secret、access token 都属于敏感信息；不要在回答中复述。

对话开始：读取前同步

如果当前任务需要用户长期偏好、项目上下文或跨设备最新记忆，执行：

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

• 如果 sync 成功，再使用 context 输出。
• 如果 sync 失败，不要丢弃本地数据；可以继续读取本地 context，但必须告知用户“远端同步失败，当前上下文可能不是最新”。
• 将 context 作为可审计上下文，不要当成绝对事实；遇到冲突时优先询问用户。

对话中：写入 inbox

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

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

类型建议：

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

写入后，如果仓库配置了 remote，执行：

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

同步 setup：只有用户明确要求时执行

当用户说“配置同步”、“连接 GitHub/Gitee”、“换成 Gitee/GitHub 同步”时，才执行 setup。

GitHub OAuth Device Flow

python scripts/memhub.py --repo "$MEMHUB_REPO" sync setup github --repo-name mh-memories

• 需要 MEMHUB_GITHUB_CLIENT_ID 或 --client-id。
• CLI 会输出授权 URL 和 user code；Agent 应把 URL/code 展示给用户，并等待用户完成授权。
• 不要要求用户把 access token 发到聊天里。

Gitee OAuth Authorization Code

python scripts/memhub.py --repo "$MEMHUB_REPO" sync setup gitee --repo-name mh-memories

• 需要 MEMHUB_GITEE_CLIENT_ID 和 MEMHUB_GITEE_CLIENT_SECRET，或对应参数。
• 默认监听 127.0.0.1:8765/callback。
• 如果运行环境无法打开浏览器或接收本地回调，可使用 --no-browser 或 --manual-code。

Token/SSH fallback

仅当用户明确选择高级方式时使用：

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

同步失败与冲突处理

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

Canonical 归档

默认不要直接写 canonical memory。需要整理长期记忆时，先预览：

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

确认归档目标合理后再执行：

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

当前最小归档规则：

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

不要写入：

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

对话结束

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

1. 写入 inbox。
2. 必要时 promote --dry-run 给出归档建议。
3. 只有用户同意或规则非常明确时才 promote --apply。
4. 执行 sync。

发布与安全约束

• 不要把真实 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，便于追溯。
• 自动提取默认进入 inbox，而不是直接污染 canonical memory。
• Git 仓库中的 YAML/Markdown 是唯一可信源数据。