MemHub

SKILL.md

---
name: memhub
version: 0.1.6
description: 使用 MemHub Protocol v0.1 读写用户的跨 Agent 统一记忆仓库。当用户要求记住信息、读取个人/项目上下文、生成 chatbot 注入文本、同步 Git 记忆仓库时使用。
tags:
  - memory
  - memhub
  - github
  - gitee
  - sync
  - agent-memory
license: MIT-0
---

# MemHub Skill

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

## 触发场景

使用本 Skill 当：

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

## 环境变量

推荐设置：

```bash
export MEMHUB_REPO=/path/to/memhub-data
```

同步 setup 可选使用：

```bash
# 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`。

```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

# 写入 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 不存在，先初始化：

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

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

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

5. 检查当前授权状态：

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

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

```bash
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 都属于敏感信息；不要在回答中复述。

### 对话开始：读取前同步

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

```bash
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：

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

类型建议：

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

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

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

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

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

#### GitHub OAuth Device Flow

```bash
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

```bash
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

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

```bash
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。需要整理长期记忆时，先预览：

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

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

```bash
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 是唯一可信源数据。