{"id":"366f9af7-2179-46fd-89b3-dc6297a99603","entityType":"agent","slug":"clawhub-cutd-memhub","name":"MemHub","canonicalUrl":"https://www.xpersona.co/agent/clawhub-cutd-memhub","canonicalPath":"/agent/clawhub-cutd-memhub","generatedAt":"2026-10-10T21:41:25.899Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:56:54.369Z","emptyReason":null},"description":"使用 MemHub Protocol v0.1 管理用户明确指定的跨 Agent 记忆仓库。用于用户明确要求记住、检索、遗忘、导出上下文或配置 Git 同步时；读取可直接执行，持久写入、自动同步、OAuth、remote 修改和仓库创建必须来自当前用户的明确请求。","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.3K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s177syff6qvrxch7gg6c492w5n83q5yz:memhub","sourceUrl":"https://clawhub.ai/cutd/memhub","homepage":"https://clawhub.ai/cutd/skills/memhub","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/cutd/memhub","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/cutd/skills/memhub","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":62,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"MemHub technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:56:54.369Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:56:54.369Z","emptyReason":null},"stars":null,"forks":null,"downloads":1329,"packageName":null,"latestVersion":"0.4.10","tractionLabel":"1.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:56:54.368Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T16:56:54.369Z","lastCrawledAt":"2026-10-10T16:56:54.368Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T16:56:54.368Z","lastVerifiedAt":null,"highlights":[{"version":"0.4.10","createdAt":"2026-09-22T02:23:14.404Z","changelog":"Security hardening: credentials moved outside the memory repo (0600 file in a 0700 dir, MEMHUB_SECRETS_DIR overridable, legacy in-repo copy migrated once), Gitee direct OAuth now generates and verifies an OAuth state to prevent account substitution, doctor is offline by default and only probes a broker with --network, and permissions.json declares filesystem, shell, network and credential boundaries.","fileCount":7,"zipByteSize":43439},{"version":"0.4.9","createdAt":"2026-09-22T02:21:56.252Z","changelog":"Security hardening","fileCount":7,"zipByteSize":43413},{"version":"0.4.8","createdAt":"2026-09-22T02:17:02.130Z","changelog":"Security hardening","fileCount":3,"zipByteSize":9229},{"version":"0.4.7","createdAt":"2026-09-21T14:28:42.408Z","changelog":"Security hardening: stage only MemHub-managed paths; remove historically tracked secrets, caches, indexes, databases and env files from Git while preserving local copies; pass Git authorization through child-process environment rather than argv. Includes the 0.4.5-0.4.6 path, host, URL-token and explicit-env protections.","fileCount":6,"zipByteSize":40233},{"version":"0.4.6","createdAt":"2026-09-21T14:20:57.624Z","changelog":"Security hardening without feature loss: commit only MemHub-managed paths, remove tracked secrets/cache/index files from Git while preserving local files, confine paths to MEMHUB_REPO, bind credentials to official provider hosts, keep tokens out of URLs, and stop implicit generic .env loading.","fileCount":6,"zipByteSize":39944},{"version":"0.4.5","createdAt":"2026-09-21T14:04:18.780Z","changelog":"Security hardening without feature loss: confine all memory paths to MEMHUB_REPO, bind HTTPS credentials to official provider hosts, keep Gitee tokens out of URLs, require an explicit allowlisted env file, remove secret CLI arguments, and require confirmation or explicit configuration for third-party OAuth broker use.","fileCount":6,"zipByteSize":39587},{"version":"0.4.4","createdAt":"2026-06-25T07:06:50.139Z","changelog":"修复发布包结构：保留 scripts/ 与 templates/ 子目录前缀，使其与 SKILL.md 中 python scripts/memhub.py 的引用一致（此前被压成扁平结构，安装后脚本路径找不到）。","fileCount":6,"zipByteSize":38477},{"version":"0.4.3","createdAt":"2026-06-25T03:43:09.196Z","changelog":"新增 onboard 首次接入命令：授权后自动探测远端，已有记忆则拉取为准且不播种默认数据，远端为空则初始化并推送——避免新 agent 用默认数据污染真实记忆。","fileCount":6,"zipByteSize":38257}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s177syff6qvrxch7gg6c492w5n83q5yz:memhub","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s177syff6qvrxch7gg6c492w5n83q5yz:memhub` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/cutd/memhub before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cutd-memhub/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cutd-memhub/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cutd-memhub/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cutd-memhub/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cutd-memhub/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cutd-memhub/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T21:41:25.896Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cutd-memhub/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cutd-memhub/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cutd-memhub/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cutd-memhub/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:56:54.369Z","emptyReason":null},"readme":"Skill: MemHub\n\nOwner: cutd\n\nSummary: 使用 MemHub Protocol v0.1 管理用户明确指定的跨 Agent 记忆仓库。用于用户明确要求记住、检索、遗忘、导出上下文或配置 Git 同步时；读取可直接执行，持久写入、自动同步、OAuth、remote 修改和仓库创建必须来自当前用户的明确请求。\n\nTags: agent-memory:0.4.10, gitee:0.4.10, github:0.4.10, latest:0.4.10, memhub:0.4.10, memory:0.4.10, sync:0.4.10\n\nVersion history:\n\nv0.4.10 | 2026-09-22T02:23:14.404Z | user\n\nSecurity hardening: credentials moved outside the memory repo (0600 file in a 0700 dir, MEMHUB_SECRETS_DIR overridable, legacy in-repo copy migrated once), Gitee direct OAuth now generates and verifies an OAuth state to prevent account substitution, doctor is offline by default and only probes a broker with --network, and permissions.json declares filesystem, shell, network and credential boundaries.\n\nv0.4.9 | 2026-09-22T02:21:56.252Z | user\n\nSecurity hardening\n\nv0.4.8 | 2026-09-22T02:17:02.130Z | user\n\nSecurity hardening\n\nv0.4.7 | 2026-09-21T14:28:42.408Z | user\n\nSecurity hardening: stage only MemHub-managed paths; remove historically tracked secrets, caches, indexes, databases and env files from Git while preserving local copies; pass Git authorization through child-process environment rather than argv. Includes the 0.4.5-0.4.6 path, host, URL-token and explicit-env protections.\n\nv0.4.6 | 2026-09-21T14:20:57.624Z | user\n\nSecurity hardening without feature loss: commit only MemHub-managed paths, remove tracked secrets/cache/index files from Git while preserving local files, confine paths to MEMHUB_REPO, bind credentials to official provider hosts, keep tokens out of URLs, and stop implicit generic .env loading.\n\nv0.4.5 | 2026-09-21T14:04:18.780Z | user\n\nSecurity hardening without feature loss: confine all memory paths to MEMHUB_REPO, bind HTTPS credentials to official provider hosts, keep Gitee tokens out of URLs, require an explicit allowlisted env file, remove secret CLI arguments, and require confirmation or explicit configuration for third-party OAuth broker use.\n\nv0.4.4 | 2026-06-25T07:06:50.139Z | user\n\n修复发布包结构：保留 scripts/ 与 templates/ 子目录前缀，使其与 SKILL.md 中 python scripts/memhub.py 的引用一致（此前被压成扁平结构，安装后脚本路径找不到）。\n\nv0.4.3 | 2026-06-25T03:43:09.196Z | user\n\n新增 onboard 首次接入命令：授权后自动探测远端，已有记忆则拉取为准且不播种默认数据，远端为空则初始化并推送——避免新 agent 用默认数据污染真实记忆。\n\nv0.4.2 | 2026-06-24T12:19:09.636Z | user\n\nGitHub/Gitee OAuth 统一走内置 MemHub Auth Broker（v2 session 协议），开箱即用、无需任何环境变量；doctor 增加 broker 就绪检查；setup 自动建目录；保留 token/SSH/直连 fallback。\n\nv0.4.1 | 2026-06-24T07:56:50.898Z | user\n\n节流自动同步 + search/forget/doctor + 结构化合并\n\nv0.1.6 | 2026-05-26T10:57:54.912Z | user\n\n补充安装后首次使用的主动授权引导协议，要求 Agent 主动检测 provider、检查授权状态并引导用户登录。\n\nv0.1.5 | 2026-05-26T10:36:50.360Z | user\n\n新增 MemHub Auth Broker 多 Provider 登录；支持按部署机器地区自动选择 GitHub/Gitee；默认同步仓库名改为 mh-memories。\n\nv0.1.4 | 2026-05-21T13:01:26.314Z | user\n\nAdd Gitee OAuth broker flow so normal users can authorize by clicking confirmation while keeping Gitee client_secret off-device.\n\nv0.1.3 | 2026-05-21T12:36:45.593Z | user\n\n内置 MemHub GitHub OAuth client id 和 Gitee client id，普通用户使用 GitHub 同步时无需配置 client id；Gitee client secret 仍不进入公开包。\n\nv0.1.2 | 2026-05-21T12:26:43.673Z | user\n\nCLI 自动读取当前目录和用户 home 目录的 .env，便于 GitHub/Gitee OAuth client id 配置；不覆盖已有环境变量。\n\nv0.1.1 | 2026-05-21T09:34:07.477Z | user\n\n同步 ClawHub MIT-0 发布许可元数据；保持通用 MemHub Skill 命名和 Agent 同步协议。\n\nv0.1.0 | 2026-05-21T09:31:43.499Z | user\n\n将 Skill 名称泛化为 MemHub；完善 Agent 同步行为协议；支持 GitHub/Gitee OAuth、token/SSH fallback。\n\nArchive index:\n\nArchive v0.4.10: 7 files, 43439 bytes\n\nFiles: permissions.json (1822b), README.md (5010b), scripts/memhub.py (112731b), skill-card.md (2379b), SKILL.md (19425b), templates/context-pack.md.j2 (278b), _meta.json (126b)\n\nFile v0.4.10:SKILL.md\n\n---\nname: memhub\nversion: 0.4.8\ndescription: 使用 MemHub Protocol v0.1 管理用户明确指定的跨 Agent 记忆仓库。用于用户明确要求记住、检索、遗忘、导出上下文或配置 Git 同步时；读取可直接执行，持久写入、自动同步、OAuth、remote 修改和仓库创建必须来自当前用户的明确请求。\ntags:\n  - memory\n  - memhub\n  - github\n  - gitee\n  - sync\n  - agent-memory\nlicense: MIT-0\n---\n\n# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让 Agent 能够读取、写入和同步符合 MemHub Protocol v0.1 的记忆仓库。\n\n## 触发场景\n\n使用本 Skill 当：\n\n- 用户说“记住这个”、“帮我记一下”、“以后记得”。\n- 用户问“我的偏好是什么”、“当前项目上下文是什么”。\n- 用户需要把记忆注入到 Gemini/元宝/豆包/Cursor/Claude Code。\n- 会话开始时需要读取用户长期记忆。\n- 用户明确要求在会话结束前保存关键决策、偏好或事实，或已经明确启用了对应自动记忆策略。\n\n## 环境变量\n\n推荐设置（唯一需要的一项）：\n\n```bash\nexport MEMHUB_REPO=/path/to/memhub-data\n```\n\nGitHub 默认使用官方 Device Flow。Gitee OAuth 可使用内置 Broker，但 CLI 会先展示固定\nBroker 域名并要求用户确认；非交互环境必须显式传入可信 Broker 或自己的 OAuth 配置。\n\n可选配置项只写在进程环境或显式 `--env-file` 中，不要写进 Skill、仓库或聊天：\n\n- `MEMHUB_OAUTH_BROKER_URL`：明确选择的通用 Broker；\n- `MEMHUB_GITEE_OAUTH_BROKER_URL`：仅用于 Gitee 的可信 Broker；\n- `MEMHUB_GITHUB_CLIENT_ID`、`MEMHUB_GITEE_CLIENT_ID`：自有 OAuth App client id；\n- `MEMHUB_GITEE_CLIENT_SECRET`：Gitee 直连模式的 client secret；\n- `MEMHUB_GITHUB_TOKEN`、`MEMHUB_GITEE_TOKEN`：token fallback。\n\n必须通过 `--repo` 或 `MEMHUB_REPO` 明确指定专用记忆仓库；CLI 不会把当前目录隐式当作记忆仓库。\n\nCLI 不会自动读取当前目录或 home 目录的通用 `.env`。如确需文件配置，显式传入\n`--env-file /path/to/memhub.env`；只会加载受支持的 `MEMHUB_*` 键。\n\n## 权限与确认边界\n\n机器可读版本见同目录 `permissions.json`；下面的散文说明与它一致。\n\n- `context`、`search`、`inbox list/show`、`doctor` 是只读操作；`doctor` 默认完全离线，只有显式加 `--network` 才会探测已配置的 broker。\n- `remember`、`forget --apply`、`promote --apply`、`init` 会修改记忆仓库；只有用户当前请求明确要求对应写入时才执行。\n- `sync`、`sync setup`、`onboard` 会访问网络或修改 Git 状态；只有用户当前请求明确要求同步或配置时才执行。\n- `sync setup`/`onboard` 是用户明确发起的同步授权，完成后保留原有节流自动同步；用户可传 `--manual-sync` 关闭。\n- 所有 inbox 引用和 canonical target 都限制在指定 MemHub 仓库内；拒绝绝对路径和 `..` 越界。\n- HTTPS token 只会发送到所选 Provider 的固定官方 Git/API 主机；目标主机不匹配时拒绝执行。\n- 只有 `git` 一个外部命令会被调用，且不经过 shell；凭据只经子进程环境传递，不出现在 argv。\n- 远程写入（创建仓库、push）只在 `sync setup` / `onboard` / `sync` 被用户显式调用时发生。\n- 没有破坏性操作：`forget` 是软归档，不删文件、不改写 Git 历史。\n\n## 命令\n\n本 Skill 提供一个 Python CLI：`scripts/memhub.py`。\n\n```bash\n# 初始化仓库\npython scripts/memhub.py --repo ~/memhub-data init --name dateng --role \"Product Manager\"\n\n# 读取上下文\npython scripts/memhub.py --repo ~/memhub-data context\npython scripts/memhub.py --repo ~/memhub-data context --pack brief\n# 记忆：默认直写 canonical 并本地提交；是否自动推送取决于同步配置\npython scripts/memhub.py --repo ~/memhub-data remember \"用户偏好结构化直接的回答\" --type preference --source agent\npython scripts/memhub.py --repo ~/memhub-data remember \"MemHub 采用 Git-first 架构\" --type decision --project memhub --source agent\n# 低置信/待人工复核的内容才进 inbox 审计缓冲\npython scripts/memhub.py --repo ~/memhub-data remember \"也许该支持 Notion 导出\" --type fact --inbox --source agent\n\n# 检索与遗忘\npython scripts/memhub.py --repo ~/memhub-data search \"Git-first\"\npython scripts/memhub.py --repo ~/memhub-data search \"决策\" --type decision --project memhub\npython scripts/memhub.py --repo ~/memhub-data search \"旧偏好\" --include-archived   # 含已归档\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\"            # 预览\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\" --apply     # 软归档（status=archived）\n\n# 将 inbox 缓冲项归档到 canonical（仅 --inbox 写入的内容才需要）\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote --status all --apply   # 扫全部 inbox 项\n\n# 检查 inbox\npython scripts/memhub.py --repo ~/memhub-data inbox list\npython scripts/memhub.py --repo ~/memhub-data inbox list --status all\npython scripts/memhub.py --repo ~/memhub-data inbox show <filename-or-id-fragment>\n\n# 将 inbox 半自动归档到 canonical memory\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote <filename-or-id-fragment> --apply\n\n# 导出给 chatbot 的上下文\npython scripts/memhub.py --repo ~/memhub-data export chatbot\n\n# 首次接入（推荐）：授权 + 自动判断拉取已有记忆 / 初始化新仓库\npython scripts/memhub.py --repo ~/memhub-data onboard github --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data onboard gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n\n# 同步 GitHub/Gitee（手动分步）\npython scripts/memhub.py --repo ~/memhub-data sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\npython scripts/memhub.py --repo ~/memhub-data sync setup github --auth token --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\npython scripts/memhub.py --repo ~/memhub-data sync status\npython scripts/memhub.py --repo ~/memhub-data sync\n\n# 自检：确认本机/本仓库的自动同步是否就绪（remote/token/merge driver/MEMHUB_REPO 等）\npython scripts/memhub.py --repo ~/memhub-data doctor\n```\n\n## Agent 行为协议\n\n### 上下文 pack 分级\n\n`context --pack` 有四档,逐档累加内容:\n\n- `brief`:用户画像、最重要的偏好、当前项目及最近决策(用于注入 chatbot)。\n- `standard`(默认):brief + 约束、惯例、未完成任务。\n- `project`:聚焦默认/指定项目,决策与任务更全。\n- `full`:standard + knowledge、relations、最近 timeline。\n\n`export chatbot` 默认用 brief;若存在 `.memhub/templates/context-pack.md.j2`,则用该模板渲染(支持 `{{ name }}` 等占位符)。\n\n### 总原则\n\n- `MEMHUB_REPO` 是用户记忆仓库；不要把用户记忆写入代码仓库。\n- GitHub/Gitee remote 只是同步后端；YAML/Markdown 文件仍是可信源数据。\n- 自动写入默认进入 canonical 记忆（本地提交，不自动推送）；低置信或需人工复核的才用 `--inbox`。\n- `sync setup` 会触发授权、创建仓库、修改 remote；**只有用户明确要求配置/切换同步时才执行**。\n- OAuth/token/SSH 凭据、authorization code、client secret、access token 都属于敏感信息；不要在回答中复述。\n\n### 对话开始：读取上下文\n\n**本会话首次涉及记忆时**，先跑一次自检确认自动同步就绪（每个会话只需一次，不要每轮都跑）：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" doctor\n```\n\n- 若 doctor 报 `NOT ready`（有 ✗），说明自动同步未生效。按提示补齐：缺 remote → 提示用户\n  `sync setup`；缺 token（常见于新机器）→ 引导用户重新授权；其余 ✗ 同理。**不要静默忽略**，\n  否则用户会误以为在自动同步，实际没有。\n- 若全绿或只有 `!` 提示，继续正常流程。\n- doctor 是只读的、默认不联网（只有显式 `--network` 才探测 broker），开销很小；但仍只需每会话首次跑一次即可。\n- doctor 会打印凭据存放位置；若仓库里还有旧版 `.memhub/secrets.yaml`，会提示可以删除。\n\n确认就绪后，直接读取 context。仅当用户已通过 setup/onboard 授权自动同步时，\n`context` 才会按节流阈值从远端拉取最新记忆：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief\n```\n\n- 若距上次拉取超过 `pull_throttle_seconds`，`context` 会自动 `pull --rebase` 再输出。\n- 自动拉取失败时，CLI 会用本地记忆并在 stderr 提示“远端同步失败，当前上下文可能不是最新”，\n  无需中断；如需强制最新，可显式 `sync` 后再读。\n- 将 context 作为可审计上下文，不要当成绝对事实；遇到冲突时优先询问用户。\n\n### 对话中：写入记忆\n\n当用户明确要求记忆，或已经明确启用了对应自动记忆策略时，默认**直写 canonical**：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"内容\" --type fact --source agent\n```\n\n- 直写会按 type 路由到对应 canonical 文件、去重后追加并本地提交；是否自动推送取决于用户在 setup/onboard 时选择的同步模式。\n- 重复内容会被自动跳过。\n- 只有低置信、需人工复核或批量待整理的内容，才加 `--inbox` 进审计缓冲，之后再 `promote`。\n\n类型建议：\n\n- `decision`：明确决策\n- `preference`：稳定偏好\n- `fact`：事实\n- `knowledge`：可复用知识/结论\n- `event`：重要事件\n- `relation`：人物/组织/工具关系\n- `constraint`：约束\n- `convention`：惯例\n\n### 同步：显式配置后自动节流，可选择手动模式\n\n只有用户明确执行 setup/onboard 后才会配置 remote；此后保留原有的节流自动同步。\n若用户传入 `--manual-sync`，则关闭自动 pull/push，只保留显式 `sync`：\n\n- **写入即同步（节流）**：每次 `remember` / `forget --apply` / `promote --apply` 后，CLI 会\n  自动尝试推送。距上次推送不足 `sync.push_throttle_seconds`（默认 3600 秒）时只在本地提交，\n  超过阈值才真正 pull+push。**记忆始终立即落本地，绝不丢失。**\n- **读取即拉取（节流）**：`context` 命令会在 `sync.pull_throttle_seconds`（默认 3600 秒）阈值外\n  自动 `pull --rebase` 拉取其它设备的最新记忆；拉取失败则用本地并在 stderr 提示可能不是最新。\n\n显式 `sync` 命令**忽略节流，立即** pull+push，适合在对话收尾兜底，确保本次所有记忆都已上远端：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync\n```\n\n节流阈值与开关都在 `.memhub/config.yaml` 的 `sync` 段（`auto_push`/`auto_pull` /\n`push_throttle_seconds` / `pull_throttle_seconds`）；节流时间戳记在本机 `.memhub/cache/sync.yaml`\n（git 忽略，每台设备独立）。单次写入若想跳过自动推送，加 `--no-sync`。\n\n`init`/`sync` 会自动注册结构化 merge 驱动（local git config 不随 clone 走，故每台设备首次\n`sync` 会自愈补注册），多设备对同一记忆文件的并发追加可自动合并，不会冲突。\n\n> **换新机器/新 Agent 时**：凭据存在记忆仓库**之外**的机器本地目录（macOS 默认\n> `~/Library/Application Support/memhub/secrets/`，Linux 默认 `~/.local/state/memhub/secrets/`，\n> 可用 `MEMHUB_SECRETS_DIR` 覆盖），因此不随 clone 或同步走，新机器需要**重新授权一次**。\n> 先跑 `doctor` 自检，按提示补齐\n> remote/token 即可——全绿后自动同步即就绪。\n\n### 检索与遗忘\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" search \"关键词\" --type decision --project memhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" forget \"过时内容\"          # 预览\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" forget \"过时内容\" --apply   # 软归档\n```\n\n- `forget` 默认 dry-run；`--apply` 把命中条目 `status` 置为 `archived`，使其从 context pack\n  消失但保留在 Git 历史中，可审计、可回滚。\n- 纠正一条记忆 = `forget` 旧条目 + `remember` 新条目。\n\n### 首次接入：用 onboard（推荐）\n\n新 agent / 新机器第一次接入时，**用 `onboard` 一条命令完成全流程**，它会自动判断该\n\"拉取已有记忆\"还是\"初始化新仓库\"，避免用默认数据污染你已有的真实记忆：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" onboard gitee --repo-name mymemhub --broker-url https://<trusted-broker>\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" onboard github --repo-name mymemhub\n```\n\nonboard 的流程：\n\n1. 授权（GitHub 默认走官方 Device Flow；Gitee Broker 必须显式指定）。\n2. **探测远端**是否已有 MemHub 记忆仓库（含 `.memhub/config.yaml`）：\n   - **已有** → 以远端为准拉取到本地，**不写入任何默认数据**（你的真实记忆直接到位）；\n   - **为空** → 初始化默认记忆并推送，建立远端仓库。\n3. 注册 merge 驱动，并按用户选择启用节流 auto-sync 或 `--manual-sync`。\n4. 打印 `doctor` 自检结果。\n\n完成 setup/onboard 后，默认维持原有节流自动同步；如果用户选择 `--manual-sync`，则只在\n显式执行 `sync` 时联网。新机器换设备时优先用 `onboard`，不要先 `init` 再 `sync setup`\n（那会先播种默认数据，可能污染远端真实记忆）。\n\n### 同步 setup：手动分步配置（高级）\n\n`onboard` 内部会调用 setup。只有当你想单独配置/切换 remote、且明确知道本地数据状态时，\n才直接用 `sync setup`。当用户说“配置同步”、“连接 GitHub/Gitee”、“换成 Gitee/GitHub 同步”时，\n优先用 `onboard`。\n\nGitHub 默认走官方 Device Flow。Gitee 交互式配置会先展示内置 Broker 域名并请求确认；\n非交互环境必须通过 `--broker-url` 或 `MEMHUB_GITEE_OAUTH_BROKER_URL` 明确指定，\n也可以使用自己的 client secret 直连。\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n```\n\n显式选择 Broker 时的授权流程：\n\n1. CLI 调用 broker 创建授权 session，得到一个 `auth_url`。\n2. CLI 打开（或打印）该 URL；Agent 应把 URL 展示给用户，请用户在浏览器完成授权。\n3. CLI 轮询 broker 直到拿到 access token，自动存入记忆仓库之外的本机凭据目录（0600，可用 `MEMHUB_SECRETS_DIR` 覆盖）。\n4. 不要要求用户把 access token 发到聊天里。\n\n无浏览器环境：加 `--no-browser`，CLI 会打印 URL 由用户手动打开。\n\n#### 高级 / fallback（仅当用户明确选择时）\n\n- 自建 broker：`--broker-url https://your-broker` 或设 `MEMHUB_OAUTH_BROKER_URL` /\n  `MEMHUB_GITEE_OAUTH_BROKER_URL`。\n- 开发者直连（不经 broker）：Gitee 使用 `MEMHUB_GITEE_CLIENT_SECRET`；\n  GitHub 会回退到 Device Flow。\n- Token / SSH：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth token --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\n```\n\n### 同步失败与冲突处理\n\n- 不要删除本地 `inbox`、canonical 文件或 `.git` 历史。\n- 将错误摘要告诉用户，避免泄露 token/header。\n- 如果 `git pull --rebase` 冲突，停止自动处理，报告冲突文件，让用户/Agent 单独修复。\n- 如果 provider 授权失败，建议用户重新授权或切换 token/SSH fallback。\n- 如果远端仓库创建失败但已存在，可以继续配置 remote 并尝试 sync。\n\n### Inbox 归档（promote）\n\n`remember` 默认直写 canonical，无需 promote。只有用 `--inbox` 缓冲过的低置信/待复核内容\n才需要 promote。整理 inbox 时先预览：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox list\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --dry-run\n```\n\n确认归档目标合理后再执行（默认 dry-run，须显式 `--apply`；已启用 auto-sync 时才按节流自动推送）：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --apply\n```\n\n`promote` 默认只扫 pending 的 inbox 项，可用 `--status all` 扫全部。归档路由规则：\n\n- `decision` → `projects/<project>/decisions.yaml`\n- `preference` → `identity/preferences.yaml`\n- `constraint` → `identity/constraints.yaml`\n- `convention` → `identity/conventions.yaml`\n- `knowledge` → `knowledge/product.yaml`\n- `relation` → `relations/people.yaml`\n- `fact` / `event` → `timeline/YYYY-MM.yaml`\n\n不要写入：\n\n- 临时闲聊\n- 未确认猜测\n- 敏感信息，除非用户明确授权\n- 无新增信息的重复内容\n\n### 对话结束\n\n如果用户明确要求保存重要决策、偏好或事实，或已经明确启用了对应自动记忆策略：\n\n1. `remember` 直写记忆（低置信内容用 `--inbox`，必要时 `promote`）。\n2. 如果用户已明确启用 auto-sync，按节流策略同步；否则只有用户明确要求时才执行 `sync`。\n\n## 安全模型与机器可读边界\n\n`permissions.json` 是本 Skill 的权限边界声明（文件/网络/凭据/变更），供扫描器与人工复核直接读取：\n\n- 文件写入只落在 `MEMHUB_REPO` 内；绝对路径与 `..` 越界一律拒绝。\n- 凭据只写入 `MEMHUB_REPO` 之外的本机目录，文件 0600、目录 0700。\n- 默认无自动出网；`sync setup` / `onboard` / `sync` 被显式调用后才访问 github.com / gitee.com。\n- GitHub 走官方 Device Flow（scope `repo`）；Gitee 直连 OAuth 每次生成并校验 `state`，防止把别人的账号绑定到本仓库。\n- 第三方 broker 不会被隐式使用：必须由用户通过 `--broker-url` 或 `MEMHUB_*_OAUTH_BROKER_URL` 明确指定主机。\n- `doctor` 默认离线；需要探测 broker 时显式加 `--network`。\n\n## 发布与安全约束\n\n- 不要把真实 token、client secret、OAuth code 写进 `SKILL.md`、README、示例或提交历史。\n- 凭据文件必须留在记忆仓库之外；仓库内的旧 `.memhub/secrets.yaml` 只作为一次性读取的迁移来源。\n- 发布到 SkillHub/ClawHub 的包应包含：`SKILL.md`、`README.md`、`permissions.json`、`scripts/memhub.py`、`templates/context-pack.md.j2`。\n- 发布包不应包含 `__pycache__`、`.pyc`、`.git` 或用户个人记忆数据。\n\n## 重要原则\n\n- MemHub 只负责存取和同步，智能判断由 Agent 完成。\n- 写入必须带 source，便于追溯。\n- 默认直写 canonical 记忆；低置信或需人工复核的内容才进 inbox 审计缓冲。\n- Git 仓库中的 YAML/Markdown 是唯一可信源数据。\n\nFile v0.4.10:README.md\n\n# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让任意支持 Skill 的 Agent 能够读写、归档和同步用户的跨 Agent 统一记忆仓库。\n\n## 能力\n\n- 读取长期记忆上下文：`context --pack brief|standard|full|project`\n- 写入默认 inbox：`remember`\n- 检查与展示 inbox：`inbox list/show`\n- 半自动归档到 canonical memory：`promote --dry-run/--apply`\n- 导出给 chatbot 的上下文：`export chatbot`\n- GitHub/Gitee 同步：OAuth、token fallback、SSH fallback\n\n## 安装到任意支持 Skill 的 Agent\n\n将本目录 `skills/memhub/` 复制到对应 skills 目录，或通过 SkillHub/ClawHub 安装。\n\n## 配置仓库路径\n\n```bash\nexport MEMHUB_REPO=~/memhub-data\n```\n\n必须通过 `--repo` 或 `MEMHUB_REPO` 明确指定专用记忆仓库；CLI 不会把当前目录隐式当作记忆仓库。\n\n## 首次初始化\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" init --name dateng --role \"Product Manager\"\n```\n\n## 配置 GitHub/Gitee 同步\n\n推荐使用 OAuth setup 命令，而不是手动配置 remote。GitHub 默认走官方 Device Flow。\nGitee 交互式配置会先展示内置 Broker 域名并请求确认；非交互环境需明确提供可信 Broker，\n或使用自己的 OAuth 配置。\n\n### GitHub / Gitee 授权\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n```\n\nGitHub 使用 Device Flow。明确选择 Broker 时，流程为：\n\n1. CLI 调 broker 创建授权 session，拿到 `auth_url`；\n2. CLI 打开该 URL，用户在 GitHub/Gitee 页面点击确认授权；\n3. broker 在服务端用 `client_secret` 换取 token；\n4. CLI 轮询 broker 拿到 token，存入记忆仓库之外的本机凭据目录（0600）。\n\n无浏览器环境加 `--no-browser`，CLI 会打印 URL 供手动打开。\n\n### 高级覆盖 / Fallback\n\n可选配置项：`MEMHUB_OAUTH_BROKER_URL`、`MEMHUB_GITEE_OAUTH_BROKER_URL`、\n`MEMHUB_GITHUB_CLIENT_ID`、`MEMHUB_GITEE_CLIENT_ID`、\n`MEMHUB_GITEE_CLIENT_SECRET`。只放在进程环境或显式 `--env-file` 中，\n不要写进仓库、文档示例或聊天。\n\n### Token / SSH Fallback\n\n```bash\n# Token fallback\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth token --repo-name mymemhub\n\n# SSH fallback\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\n```\n\nOAuth/token 保存在记忆仓库**之外**的本机目录（macOS 默认 `~/Library/Application Support/memhub/secrets/`，Linux 默认 `~/.local/state/memhub/secrets/`，可用 `MEMHUB_SECRETS_DIR` 覆盖），文件权限 0600、目录 0700。仓库因此永远不含凭据，clone 与同步也不会带走它们。\n\n不要把 OAuth app 的 client secret、token 或 authorization code 提交到仓库或在聊天中复述。第三方 OAuth broker 不会被隐式使用，必须由 `--broker-url` 或 `MEMHUB_*_OAUTH_BROKER_URL` 明确指定。`doctor` 默认离线，只有 `--network` 才会探测 broker。\n\n## 常用命令\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"要记住的内容\" --type fact --source agent\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox list\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox show <filename-or-id-fragment>\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --dry-run\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --apply\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" export chatbot\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync status\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync\n```\n\n## Agent 使用原则\n\n- 读取前：如果任务依赖长期记忆，先 `sync`，再 `context --pack brief`。\n- 写入时：用户明确要求记忆，或形成稳定决策/偏好/事实时，写入 inbox。\n- 写入后：已授权 auto-sync 时由节流逻辑处理；manual-sync 模式只在用户要求时执行 `sync`。\n- 归档时：先 `promote --dry-run`，确认后再 `promote --apply`，然后 `sync`。\n- setup：只有用户明确要求配置或切换同步服务时才执行。\n- 自动同步：用户明确运行 setup/onboard 后默认启用；如只想手动同步，添加 `--manual-sync`。\n- 失败：同步失败时不要删除本地数据；报告错误并保留本地文件。\n\nCLI 不会隐式读取 cwd 或 home 的 `.env`。需要文件配置时使用\n`--env-file /path/to/memhub.env`，且只加载受支持的 `MEMHUB_*` 键。\n\n## 发布包内容\n\n发布到 SkillHub/ClawHub 时应包含：\n\n```text\nSKILL.md\nREADME.md\npermissions.json\nscripts/memhub.py\ntemplates/context-pack.md.j2\n```\n\n不应包含：\n\n```text\n__pycache__/\n*.pyc\n.git/\n本机凭据目录下的 secrets 文件\n用户个人记忆数据\n```\n\n## License\n\nMIT-0\n\nFile v0.4.10:_meta.json\n\n{\n  \"ownerId\": \"kn7aq20vx0abk37pk7pnq842t1827dq3\",\n  \"slug\": \"memhub\",\n  \"version\": \"0.4.10\",\n  \"publishedAt\": 1790043794404\n}\n\nFile v0.4.10:skill-card.md\n\n## Description:\n\nMemHub lets an agent manage a user-designated cross-agent memory repository with MemHub Protocol v0.1, including remembering, retrieving, forgetting, exporting context, and configuring Git sync with explicit user consent for persistent writes and remote changes.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cutd](https://clawhub.ai/user/cutd)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent users use MemHub when they want an agent to maintain, retrieve, archive, export, and optionally Git-sync a dedicated long-term memory repository across agent sessions.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Long-term memory may retain sensitive, stale, or unwanted personal context.\n\nMitigation: Use a dedicated MEMHUB_REPO, review what gets remembered, and use the skill's forget, inbox, and promote workflows to keep retained context intentional.\n\nRisk: After sync setup or onboard, memory reads may pull and memory writes may push repository content on a throttle.\n\nMitigation: Configure sync only when the user explicitly asks for it, and choose manual sync or no-sync options when automatic pull or push is not desired.\n\nRisk: OAuth codes, client secrets, or access tokens could be exposed if shared in chat.\n\nMitigation: Do not paste tokens or OAuth codes into chat; use the supported authorization flow and local credential storage instead.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/cutd/skills/memhub)\n- [README](artifact/README.md)\n- [Permission boundary](artifact/permissions.json)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and generated memory context text]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Outputs are intended for agent use with explicit user consent for persistent writes, remote sync setup, OAuth, repository creation, and apply-mode mutations.]\n\n## Skill Version(s):\n\n0.4.10 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.4.10:permissions.json\n\n{\n  \"schema\": \"memhub.permission-boundary/v1\",\n  \"skill\": \"memhub\",\n  \"version\": \"0.4.8\",\n  \"purpose\": \"Read, write and Git-sync a user-designated MemHub memory repository.\",\n  \"filesystem\": {\n    \"read\": [\"${MEMHUB_REPO}/**\", \"${SKILL_DIR}/**\"],\n    \"write\": [\"${MEMHUB_REPO}/**\"],\n    \"credentialWrite\": [\"${MEMHUB_SECRETS_DIR}/**\"],\n    \"denied\": [\"${MEMHUB_REPO}/../**\", \"/**\", \"**/.env\", \"**/.git/config\"],\n    \"pathEscape\": \"rejected: absolute paths and `..` sequences are refused\"\n  },\n  \"shell\": {\n    \"commands\": [\"git\"],\n    \"interpreter\": false,\n    \"secretInArguments\": \"never; git authorization is passed through the child-process environment\"\n  },\n  \"network\": {\n    \"mode\": \"opt-in\",\n    \"default\": \"no automatic egress until `sync setup` or `onboard` is run explicitly\",\n    \"hosts\": [\"github.com\", \"api.github.com\", \"gitee.com\"],\n    \"optionalHosts\": [\"${MEMHUB_OAUTH_BROKER_URL}\", \"${MEMHUB_GITEE_OAUTH_BROKER_URL}\"],\n    \"thirdPartyBroker\": \"used only when the user names the host via --broker-url or a MEMHUB_*_OAUTH_BROKER_URL variable\"\n  },\n  \"mutations\": {\n    \"localWrite\": {\n      \"commands\": [\"remember\", \"forget --apply\", \"promote --apply\", \"init\"],\n      \"requires\": \"explicit user request\"\n    },\n    \"remoteWrite\": {\n      \"commands\": [\"sync\", \"sync setup\", \"onboard\"],\n      \"requires\": \"explicit user request\"\n    },\n    \"destructive\": \"none: `forget` soft-archives (status=archived); no file deletion and no history rewrite\"\n  },\n  \"credentials\": {\n    \"storage\": \"outside ${MEMHUB_REPO}, file mode 0600 in a 0700 directory\",\n    \"inRepository\": \"never\",\n    \"inChatOutput\": \"never\",\n    \"inProcessArguments\": \"never\",\n    \"oauthState\": \"generated per authorization attempt and verified on the callback\",\n    \"scopes\": {\"github\": \"repo (device flow)\", \"gitee\": \"user_info projects\"}\n  }\n}\n\nArchive v0.4.9: 7 files, 43413 bytes\n\nFiles: permissions.json (1822b), README.md (5010b), scripts/memhub.py (112731b), skill-card.md (2276b), SKILL.md (19425b), templates/context-pack.md.j2 (278b), _meta.json (125b)\n\nFile v0.4.9:SKILL.md\n\n---\nname: memhub\nversion: 0.4.8\ndescription: 使用 MemHub Protocol v0.1 管理用户明确指定的跨 Agent 记忆仓库。用于用户明确要求记住、检索、遗忘、导出上下文或配置 Git 同步时；读取可直接执行，持久写入、自动同步、OAuth、remote 修改和仓库创建必须来自当前用户的明确请求。\ntags:\n  - memory\n  - memhub\n  - github\n  - gitee\n  - sync\n  - agent-memory\nlicense: MIT-0\n---\n\n# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让 Agent 能够读取、写入和同步符合 MemHub Protocol v0.1 的记忆仓库。\n\n## 触发场景\n\n使用本 Skill 当：\n\n- 用户说“记住这个”、“帮我记一下”、“以后记得”。\n- 用户问“我的偏好是什么”、“当前项目上下文是什么”。\n- 用户需要把记忆注入到 Gemini/元宝/豆包/Cursor/Claude Code。\n- 会话开始时需要读取用户长期记忆。\n- 用户明确要求在会话结束前保存关键决策、偏好或事实，或已经明确启用了对应自动记忆策略。\n\n## 环境变量\n\n推荐设置（唯一需要的一项）：\n\n```bash\nexport MEMHUB_REPO=/path/to/memhub-data\n```\n\nGitHub 默认使用官方 Device Flow。Gitee OAuth 可使用内置 Broker，但 CLI 会先展示固定\nBroker 域名并要求用户确认；非交互环境必须显式传入可信 Broker 或自己的 OAuth 配置。\n\n可选配置项只写在进程环境或显式 `--env-file` 中，不要写进 Skill、仓库或聊天：\n\n- `MEMHUB_OAUTH_BROKER_URL`：明确选择的通用 Broker；\n- `MEMHUB_GITEE_OAUTH_BROKER_URL`：仅用于 Gitee 的可信 Broker；\n- `MEMHUB_GITHUB_CLIENT_ID`、`MEMHUB_GITEE_CLIENT_ID`：自有 OAuth App client id；\n- `MEMHUB_GITEE_CLIENT_SECRET`：Gitee 直连模式的 client secret；\n- `MEMHUB_GITHUB_TOKEN`、`MEMHUB_GITEE_TOKEN`：token fallback。\n\n必须通过 `--repo` 或 `MEMHUB_REPO` 明确指定专用记忆仓库；CLI 不会把当前目录隐式当作记忆仓库。\n\nCLI 不会自动读取当前目录或 home 目录的通用 `.env`。如确需文件配置，显式传入\n`--env-file /path/to/memhub.env`；只会加载受支持的 `MEMHUB_*` 键。\n\n## 权限与确认边界\n\n机器可读版本见同目录 `permissions.json`；下面的散文说明与它一致。\n\n- `context`、`search`、`inbox list/show`、`doctor` 是只读操作；`doctor` 默认完全离线，只有显式加 `--network` 才会探测已配置的 broker。\n- `remember`、`forget --apply`、`promote --apply`、`init` 会修改记忆仓库；只有用户当前请求明确要求对应写入时才执行。\n- `sync`、`sync setup`、`onboard` 会访问网络或修改 Git 状态；只有用户当前请求明确要求同步或配置时才执行。\n- `sync setup`/`onboard` 是用户明确发起的同步授权，完成后保留原有节流自动同步；用户可传 `--manual-sync` 关闭。\n- 所有 inbox 引用和 canonical target 都限制在指定 MemHub 仓库内；拒绝绝对路径和 `..` 越界。\n- HTTPS token 只会发送到所选 Provider 的固定官方 Git/API 主机；目标主机不匹配时拒绝执行。\n- 只有 `git` 一个外部命令会被调用，且不经过 shell；凭据只经子进程环境传递，不出现在 argv。\n- 远程写入（创建仓库、push）只在 `sync setup` / `onboard` / `sync` 被用户显式调用时发生。\n- 没有破坏性操作：`forget` 是软归档，不删文件、不改写 Git 历史。\n\n## 命令\n\n本 Skill 提供一个 Python CLI：`scripts/memhub.py`。\n\n```bash\n# 初始化仓库\npython scripts/memhub.py --repo ~/memhub-data init --name dateng --role \"Product Manager\"\n\n# 读取上下文\npython scripts/memhub.py --repo ~/memhub-data context\npython scripts/memhub.py --repo ~/memhub-data context --pack brief\n# 记忆：默认直写 canonical 并本地提交；是否自动推送取决于同步配置\npython scripts/memhub.py --repo ~/memhub-data remember \"用户偏好结构化直接的回答\" --type preference --source agent\npython scripts/memhub.py --repo ~/memhub-data remember \"MemHub 采用 Git-first 架构\" --type decision --project memhub --source agent\n# 低置信/待人工复核的内容才进 inbox 审计缓冲\npython scripts/memhub.py --repo ~/memhub-data remember \"也许该支持 Notion 导出\" --type fact --inbox --source agent\n\n# 检索与遗忘\npython scripts/memhub.py --repo ~/memhub-data search \"Git-first\"\npython scripts/memhub.py --repo ~/memhub-data search \"决策\" --type decision --project memhub\npython scripts/memhub.py --repo ~/memhub-data search \"旧偏好\" --include-archived   # 含已归档\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\"            # 预览\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\" --apply     # 软归档（status=archived）\n\n# 将 inbox 缓冲项归档到 canonical（仅 --inbox 写入的内容才需要）\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote --status all --apply   # 扫全部 inbox 项\n\n# 检查 inbox\npython scripts/memhub.py --repo ~/memhub-data inbox list\npython scripts/memhub.py --repo ~/memhub-data inbox list --status all\npython scripts/memhub.py --repo ~/memhub-data inbox show <filename-or-id-fragment>\n\n# 将 inbox 半自动归档到 canonical memory\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote <filename-or-id-fragment> --apply\n\n# 导出给 chatbot 的上下文\npython scripts/memhub.py --repo ~/memhub-data export chatbot\n\n# 首次接入（推荐）：授权 + 自动判断拉取已有记忆 / 初始化新仓库\npython scripts/memhub.py --repo ~/memhub-data onboard github --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data onboard gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n\n# 同步 GitHub/Gitee（手动分步）\npython scripts/memhub.py --repo ~/memhub-data sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\npython scripts/memhub.py --repo ~/memhub-data sync setup github --auth token --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\npython scripts/memhub.py --repo ~/memhub-data sync status\npython scripts/memhub.py --repo ~/memhub-data sync\n\n# 自检：确认本机/本仓库的自动同步是否就绪（remote/token/merge driver/MEMHUB_REPO 等）\npython scripts/memhub.py --repo ~/memhub-data doctor\n```\n\n## Agent 行为协议\n\n### 上下文 pack 分级\n\n`context --pack` 有四档,逐档累加内容:\n\n- `brief`:用户画像、最重要的偏好、当前项目及最近决策(用于注入 chatbot)。\n- `standard`(默认):brief + 约束、惯例、未完成任务。\n- `project`:聚焦默认/指定项目,决策与任务更全。\n- `full`:standard + knowledge、relations、最近 timeline。\n\n`export chatbot` 默认用 brief;若存在 `.memhub/templates/context-pack.md.j2`,则用该模板渲染(支持 `{{ name }}` 等占位符)。\n\n### 总原则\n\n- `MEMHUB_REPO` 是用户记忆仓库；不要把用户记忆写入代码仓库。\n- GitHub/Gitee remote 只是同步后端；YAML/Markdown 文件仍是可信源数据。\n- 自动写入默认进入 canonical 记忆（本地提交，不自动推送）；低置信或需人工复核的才用 `--inbox`。\n- `sync setup` 会触发授权、创建仓库、修改 remote；**只有用户明确要求配置/切换同步时才执行**。\n- OAuth/token/SSH 凭据、authorization code、client secret、access token 都属于敏感信息；不要在回答中复述。\n\n### 对话开始：读取上下文\n\n**本会话首次涉及记忆时**，先跑一次自检确认自动同步就绪（每个会话只需一次，不要每轮都跑）：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" doctor\n```\n\n- 若 doctor 报 `NOT ready`（有 ✗），说明自动同步未生效。按提示补齐：缺 remote → 提示用户\n  `sync setup`；缺 token（常见于新机器）→ 引导用户重新授权；其余 ✗ 同理。**不要静默忽略**，\n  否则用户会误以为在自动同步，实际没有。\n- 若全绿或只有 `!` 提示，继续正常流程。\n- doctor 是只读的、默认不联网（只有显式 `--network` 才探测 broker），开销很小；但仍只需每会话首次跑一次即可。\n- doctor 会打印凭据存放位置；若仓库里还有旧版 `.memhub/secrets.yaml`，会提示可以删除。\n\n确认就绪后，直接读取 context。仅当用户已通过 setup/onboard 授权自动同步时，\n`context` 才会按节流阈值从远端拉取最新记忆：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief\n```\n\n- 若距上次拉取超过 `pull_throttle_seconds`，`context` 会自动 `pull --rebase` 再输出。\n- 自动拉取失败时，CLI 会用本地记忆并在 stderr 提示“远端同步失败，当前上下文可能不是最新”，\n  无需中断；如需强制最新，可显式 `sync` 后再读。\n- 将 context 作为可审计上下文，不要当成绝对事实；遇到冲突时优先询问用户。\n\n### 对话中：写入记忆\n\n当用户明确要求记忆，或已经明确启用了对应自动记忆策略时，默认**直写 canonical**：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"内容\" --type fact --source agent\n```\n\n- 直写会按 type 路由到对应 canonical 文件、去重后追加并本地提交；是否自动推送取决于用户在 setup/onboard 时选择的同步模式。\n- 重复内容会被自动跳过。\n- 只有低置信、需人工复核或批量待整理的内容，才加 `--inbox` 进审计缓冲，之后再 `promote`。\n\n类型建议：\n\n- `decision`：明确决策\n- `preference`：稳定偏好\n- `fact`：事实\n- `knowledge`：可复用知识/结论\n- `event`：重要事件\n- `relation`：人物/组织/工具关系\n- `constraint`：约束\n- `convention`：惯例\n\n### 同步：显式配置后自动节流，可选择手动模式\n\n只有用户明确执行 setup/onboard 后才会配置 remote；此后保留原有的节流自动同步。\n若用户传入 `--manual-sync`，则关闭自动 pull/push，只保留显式 `sync`：\n\n- **写入即同步（节流）**：每次 `remember` / `forget --apply` / `promote --apply` 后，CLI 会\n  自动尝试推送。距上次推送不足 `sync.push_throttle_seconds`（默认 3600 秒）时只在本地提交，\n  超过阈值才真正 pull+push。**记忆始终立即落本地，绝不丢失。**\n- **读取即拉取（节流）**：`context` 命令会在 `sync.pull_throttle_seconds`（默认 3600 秒）阈值外\n  自动 `pull --rebase` 拉取其它设备的最新记忆；拉取失败则用本地并在 stderr 提示可能不是最新。\n\n显式 `sync` 命令**忽略节流，立即** pull+push，适合在对话收尾兜底，确保本次所有记忆都已上远端：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync\n```\n\n节流阈值与开关都在 `.memhub/config.yaml` 的 `sync` 段（`auto_push`/`auto_pull` /\n`push_throttle_seconds` / `pull_throttle_seconds`）；节流时间戳记在本机 `.memhub/cache/sync.yaml`\n（git 忽略，每台设备独立）。单次写入若想跳过自动推送，加 `--no-sync`。\n\n`init`/`sync` 会自动注册结构化 merge 驱动（local git config 不随 clone 走，故每台设备首次\n`sync` 会自愈补注册），多设备对同一记忆文件的并发追加可自动合并，不会冲突。\n\n> **换新机器/新 Agent 时**：凭据存在记忆仓库**之外**的机器本地目录（macOS 默认\n> `~/Library/Application Support/memhub/secrets/`，Linux 默认 `~/.local/state/memhub/secrets/`，\n> 可用 `MEMHUB_SECRETS_DIR` 覆盖），因此不随 clone 或同步走，新机器需要**重新授权一次**。\n> 先跑 `doctor` 自检，按提示补齐\n> remote/token 即可——全绿后自动同步即就绪。\n\n### 检索与遗忘\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" search \"关键词\" --type decision --project memhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" forget \"过时内容\"          # 预览\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" forget \"过时内容\" --apply   # 软归档\n```\n\n- `forget` 默认 dry-run；`--apply` 把命中条目 `status` 置为 `archived`，使其从 context pack\n  消失但保留在 Git 历史中，可审计、可回滚。\n- 纠正一条记忆 = `forget` 旧条目 + `remember` 新条目。\n\n### 首次接入：用 onboard（推荐）\n\n新 agent / 新机器第一次接入时，**用 `onboard` 一条命令完成全流程**，它会自动判断该\n\"拉取已有记忆\"还是\"初始化新仓库\"，避免用默认数据污染你已有的真实记忆：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" onboard gitee --repo-name mymemhub --broker-url https://<trusted-broker>\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" onboard github --repo-name mymemhub\n```\n\nonboard 的流程：\n\n1. 授权（GitHub 默认走官方 Device Flow；Gitee Broker 必须显式指定）。\n2. **探测远端**是否已有 MemHub 记忆仓库（含 `.memhub/config.yaml`）：\n   - **已有** → 以远端为准拉取到本地，**不写入任何默认数据**（你的真实记忆直接到位）；\n   - **为空** → 初始化默认记忆并推送，建立远端仓库。\n3. 注册 merge 驱动，并按用户选择启用节流 auto-sync 或 `--manual-sync`。\n4. 打印 `doctor` 自检结果。\n\n完成 setup/onboard 后，默认维持原有节流自动同步；如果用户选择 `--manual-sync`，则只在\n显式执行 `sync` 时联网。新机器换设备时优先用 `onboard`，不要先 `init` 再 `sync setup`\n（那会先播种默认数据，可能污染远端真实记忆）。\n\n### 同步 setup：手动分步配置（高级）\n\n`onboard` 内部会调用 setup。只有当你想单独配置/切换 remote、且明确知道本地数据状态时，\n才直接用 `sync setup`。当用户说“配置同步”、“连接 GitHub/Gitee”、“换成 Gitee/GitHub 同步”时，\n优先用 `onboard`。\n\nGitHub 默认走官方 Device Flow。Gitee 交互式配置会先展示内置 Broker 域名并请求确认；\n非交互环境必须通过 `--broker-url` 或 `MEMHUB_GITEE_OAUTH_BROKER_URL` 明确指定，\n也可以使用自己的 client secret 直连。\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n```\n\n显式选择 Broker 时的授权流程：\n\n1. CLI 调用 broker 创建授权 session，得到一个 `auth_url`。\n2. CLI 打开（或打印）该 URL；Agent 应把 URL 展示给用户，请用户在浏览器完成授权。\n3. CLI 轮询 broker 直到拿到 access token，自动存入记忆仓库之外的本机凭据目录（0600，可用 `MEMHUB_SECRETS_DIR` 覆盖）。\n4. 不要要求用户把 access token 发到聊天里。\n\n无浏览器环境：加 `--no-browser`，CLI 会打印 URL 由用户手动打开。\n\n#### 高级 / fallback（仅当用户明确选择时）\n\n- 自建 broker：`--broker-url https://your-broker` 或设 `MEMHUB_OAUTH_BROKER_URL` /\n  `MEMHUB_GITEE_OAUTH_BROKER_URL`。\n- 开发者直连（不经 broker）：Gitee 使用 `MEMHUB_GITEE_CLIENT_SECRET`；\n  GitHub 会回退到 Device Flow。\n- Token / SSH：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth token --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\n```\n\n### 同步失败与冲突处理\n\n- 不要删除本地 `inbox`、canonical 文件或 `.git` 历史。\n- 将错误摘要告诉用户，避免泄露 token/header。\n- 如果 `git pull --rebase` 冲突，停止自动处理，报告冲突文件，让用户/Agent 单独修复。\n- 如果 provider 授权失败，建议用户重新授权或切换 token/SSH fallback。\n- 如果远端仓库创建失败但已存在，可以继续配置 remote 并尝试 sync。\n\n### Inbox 归档（promote）\n\n`remember` 默认直写 canonical，无需 promote。只有用 `--inbox` 缓冲过的低置信/待复核内容\n才需要 promote。整理 inbox 时先预览：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox list\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --dry-run\n```\n\n确认归档目标合理后再执行（默认 dry-run，须显式 `--apply`；已启用 auto-sync 时才按节流自动推送）：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --apply\n```\n\n`promote` 默认只扫 pending 的 inbox 项，可用 `--status all` 扫全部。归档路由规则：\n\n- `decision` → `projects/<project>/decisions.yaml`\n- `preference` → `identity/preferences.yaml`\n- `constraint` → `identity/constraints.yaml`\n- `convention` → `identity/conventions.yaml`\n- `knowledge` → `knowledge/product.yaml`\n- `relation` → `relations/people.yaml`\n- `fact` / `event` → `timeline/YYYY-MM.yaml`\n\n不要写入：\n\n- 临时闲聊\n- 未确认猜测\n- 敏感信息，除非用户明确授权\n- 无新增信息的重复内容\n\n### 对话结束\n\n如果用户明确要求保存重要决策、偏好或事实，或已经明确启用了对应自动记忆策略：\n\n1. `remember` 直写记忆（低置信内容用 `--inbox`，必要时 `promote`）。\n2. 如果用户已明确启用 auto-sync，按节流策略同步；否则只有用户明确要求时才执行 `sync`。\n\n## 安全模型与机器可读边界\n\n`permissions.json` 是本 Skill 的权限边界声明（文件/网络/凭据/变更），供扫描器与人工复核直接读取：\n\n- 文件写入只落在 `MEMHUB_REPO` 内；绝对路径与 `..` 越界一律拒绝。\n- 凭据只写入 `MEMHUB_REPO` 之外的本机目录，文件 0600、目录 0700。\n- 默认无自动出网；`sync setup` / `onboard` / `sync` 被显式调用后才访问 github.com / gitee.com。\n- GitHub 走官方 Device Flow（scope `repo`）；Gitee 直连 OAuth 每次生成并校验 `state`，防止把别人的账号绑定到本仓库。\n- 第三方 broker 不会被隐式使用：必须由用户通过 `--broker-url` 或 `MEMHUB_*_OAUTH_BROKER_URL` 明确指定主机。\n- `doctor` 默认离线；需要探测 broker 时显式加 `--network`。\n\n## 发布与安全约束\n\n- 不要把真实 token、client secret、OAuth code 写进 `SKILL.md`、README、示例或提交历史。\n- 凭据文件必须留在记忆仓库之外；仓库内的旧 `.memhub/secrets.yaml` 只作为一次性读取的迁移来源。\n- 发布到 SkillHub/ClawHub 的包应包含：`SKILL.md`、`README.md`、`permissions.json`、`scripts/memhub.py`、`templates/context-pack.md.j2`。\n- 发布包不应包含 `__pycache__`、`.pyc`、`.git` 或用户个人记忆数据。\n\n## 重要原则\n\n- MemHub 只负责存取和同步，智能判断由 Agent 完成。\n- 写入必须带 source，便于追溯。\n- 默认直写 canonical 记忆；低置信或需人工复核的内容才进 inbox 审计缓冲。\n- Git 仓库中的 YAML/Markdown 是唯一可信源数据。\n\nFile v0.4.9:README.md\n\n# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让任意支持 Skill 的 Agent 能够读写、归档和同步用户的跨 Agent 统一记忆仓库。\n\n## 能力\n\n- 读取长期记忆上下文：`context --pack brief|standard|full|project`\n- 写入默认 inbox：`remember`\n- 检查与展示 inbox：`inbox list/show`\n- 半自动归档到 canonical memory：`promote --dry-run/--apply`\n- 导出给 chatbot 的上下文：`export chatbot`\n- GitHub/Gitee 同步：OAuth、token fallback、SSH fallback\n\n## 安装到任意支持 Skill 的 Agent\n\n将本目录 `skills/memhub/` 复制到对应 skills 目录，或通过 SkillHub/ClawHub 安装。\n\n## 配置仓库路径\n\n```bash\nexport MEMHUB_REPO=~/memhub-data\n```\n\n必须通过 `--repo` 或 `MEMHUB_REPO` 明确指定专用记忆仓库；CLI 不会把当前目录隐式当作记忆仓库。\n\n## 首次初始化\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" init --name dateng --role \"Product Manager\"\n```\n\n## 配置 GitHub/Gitee 同步\n\n推荐使用 OAuth setup 命令，而不是手动配置 remote。GitHub 默认走官方 Device Flow。\nGitee 交互式配置会先展示内置 Broker 域名并请求确认；非交互环境需明确提供可信 Broker，\n或使用自己的 OAuth 配置。\n\n### GitHub / Gitee 授权\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n```\n\nGitHub 使用 Device Flow。明确选择 Broker 时，流程为：\n\n1. CLI 调 broker 创建授权 session，拿到 `auth_url`；\n2. CLI 打开该 URL，用户在 GitHub/Gitee 页面点击确认授权；\n3. broker 在服务端用 `client_secret` 换取 token；\n4. CLI 轮询 broker 拿到 token，存入记忆仓库之外的本机凭据目录（0600）。\n\n无浏览器环境加 `--no-browser`，CLI 会打印 URL 供手动打开。\n\n### 高级覆盖 / Fallback\n\n可选配置项：`MEMHUB_OAUTH_BROKER_URL`、`MEMHUB_GITEE_OAUTH_BROKER_URL`、\n`MEMHUB_GITHUB_CLIENT_ID`、`MEMHUB_GITEE_CLIENT_ID`、\n`MEMHUB_GITEE_CLIENT_SECRET`。只放在进程环境或显式 `--env-file` 中，\n不要写进仓库、文档示例或聊天。\n\n### Token / SSH Fallback\n\n```bash\n# Token fallback\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth token --repo-name mymemhub\n\n# SSH fallback\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\n```\n\nOAuth/token 保存在记忆仓库**之外**的本机目录（macOS 默认 `~/Library/Application Support/memhub/secrets/`，Linux 默认 `~/.local/state/memhub/secrets/`，可用 `MEMHUB_SECRETS_DIR` 覆盖），文件权限 0600、目录 0700。仓库因此永远不含凭据，clone 与同步也不会带走它们。\n\n不要把 OAuth app 的 client secret、token 或 authorization code 提交到仓库或在聊天中复述。第三方 OAuth broker 不会被隐式使用，必须由 `--broker-url` 或 `MEMHUB_*_OAUTH_BROKER_URL` 明确指定。`doctor` 默认离线，只有 `--network` 才会探测 broker。\n\n## 常用命令\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"要记住的内容\" --type fact --source agent\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox list\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox show <filename-or-id-fragment>\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --dry-run\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --apply\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" export chatbot\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync status\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync\n```\n\n## Agent 使用原则\n\n- 读取前：如果任务依赖长期记忆，先 `sync`，再 `context --pack brief`。\n- 写入时：用户明确要求记忆，或形成稳定决策/偏好/事实时，写入 inbox。\n- 写入后：已授权 auto-sync 时由节流逻辑处理；manual-sync 模式只在用户要求时执行 `sync`。\n- 归档时：先 `promote --dry-run`，确认后再 `promote --apply`，然后 `sync`。\n- setup：只有用户明确要求配置或切换同步服务时才执行。\n- 自动同步：用户明确运行 setup/onboard 后默认启用；如只想手动同步，添加 `--manual-sync`。\n- 失败：同步失败时不要删除本地数据；报告错误并保留本地文件。\n\nCLI 不会隐式读取 cwd 或 home 的 `.env`。需要文件配置时使用\n`--env-file /path/to/memhub.env`，且只加载受支持的 `MEMHUB_*` 键。\n\n## 发布包内容\n\n发布到 SkillHub/ClawHub 时应包含：\n\n```text\nSKILL.md\nREADME.md\npermissions.json\nscripts/memhub.py\ntemplates/context-pack.md.j2\n```\n\n不应包含：\n\n```text\n__pycache__/\n*.pyc\n.git/\n本机凭据目录下的 secrets 文件\n用户个人记忆数据\n```\n\n## License\n\nMIT-0\n\nFile v0.4.9:_meta.json\n\n{\n  \"ownerId\": \"kn7aq20vx0abk37pk7pnq842t1827dq3\",\n  \"slug\": \"memhub\",\n  \"version\": \"0.4.9\",\n  \"publishedAt\": 1790043716252\n}\n\nFile v0.4.9:skill-card.md\n\n## Description:\n\nMemHub helps agents read, write, archive, export, and Git-sync a user-designated personal memory repository using MemHub Protocol v0.1.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cutd](https://clawhub.ai/user/cutd)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent users use MemHub when an agent needs explicit long-term memory: remembering user-approved facts or preferences, retrieving context, exporting context packs, soft-archiving outdated entries, and syncing a dedicated memory repository.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Long-term memory can retain sensitive personal or project information if the user asks the agent to store it.\n\nMitigation: Review remembered content regularly and avoid storing highly sensitive secrets or credentials as memory content.\n\nRisk: Optional Git sync can expose memory data through a remote repository or broad token permissions.\n\nMitigation: Use a private remote, keep OAuth or token access limited, and configure sync only after an explicit user request.\n\nRisk: OAuth brokers and remote changes introduce trust and account-binding considerations.\n\nMitigation: Use the default GitHub Device Flow when possible, provide trusted broker URLs explicitly, and confirm setup or onboard actions before they modify remotes or credentials.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/cutd/skills/memhub)\n- [README](artifact/README.md)\n- [Permission boundary](artifact/permissions.json)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown context packs, YAML-backed memory records, CLI output, and shell commands.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Reads and writes are scoped to an explicitly configured MemHub repository; network sync is opt-in and user-directed.]\n\n## Skill Version(s):\n\n0.4.9 (source: ClawHub release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.4.9:permissions.json\n\n{\n  \"schema\": \"memhub.permission-boundary/v1\",\n  \"skill\": \"memhub\",\n  \"version\": \"0.4.8\",\n  \"purpose\": \"Read, write and Git-sync a user-designated MemHub memory repository.\",\n  \"filesystem\": {\n    \"read\": [\"${MEMHUB_REPO}/**\", \"${SKILL_DIR}/**\"],\n    \"write\": [\"${MEMHUB_REPO}/**\"],\n    \"credentialWrite\": [\"${MEMHUB_SECRETS_DIR}/**\"],\n    \"denied\": [\"${MEMHUB_REPO}/../**\", \"/**\", \"**/.env\", \"**/.git/config\"],\n    \"pathEscape\": \"rejected: absolute paths and `..` sequences are refused\"\n  },\n  \"shell\": {\n    \"commands\": [\"git\"],\n    \"interpreter\": false,\n    \"secretInArguments\": \"never; git authorization is passed through the child-process environment\"\n  },\n  \"network\": {\n    \"mode\": \"opt-in\",\n    \"default\": \"no automatic egress until `sync setup` or `onboard` is run explicitly\",\n    \"hosts\": [\"github.com\", \"api.github.com\", \"gitee.com\"],\n    \"optionalHosts\": [\"${MEMHUB_OAUTH_BROKER_URL}\", \"${MEMHUB_GITEE_OAUTH_BROKER_URL}\"],\n    \"thirdPartyBroker\": \"used only when the user names the host via --broker-url or a MEMHUB_*_OAUTH_BROKER_URL variable\"\n  },\n  \"mutations\": {\n    \"localWrite\": {\n      \"commands\": [\"remember\", \"forget --apply\", \"promote --apply\", \"init\"],\n      \"requires\": \"explicit user request\"\n    },\n    \"remoteWrite\": {\n      \"commands\": [\"sync\", \"sync setup\", \"onboard\"],\n      \"requires\": \"explicit user request\"\n    },\n    \"destructive\": \"none: `forget` soft-archives (status=archived); no file deletion and no history rewrite\"\n  },\n  \"credentials\": {\n    \"storage\": \"outside ${MEMHUB_REPO}, file mode 0600 in a 0700 directory\",\n    \"inRepository\": \"never\",\n    \"inChatOutput\": \"never\",\n    \"inProcessArguments\": \"never\",\n    \"oauthState\": \"generated per authorization attempt and verified on the callback\",\n    \"scopes\": {\"github\": \"repo (device flow)\", \"gitee\": \"user_info projects\"}\n  }\n}\n\nArchive v0.4.8: 3 files, 9229 bytes\n\nFiles: skill-card.md (2622b), SKILL.md (19425b), _meta.json (125b)\n\nFile v0.4.8:SKILL.md\n\n---\nname: memhub\nversion: 0.4.8\ndescription: 使用 MemHub Protocol v0.1 管理用户明确指定的跨 Agent 记忆仓库。用于用户明确要求记住、检索、遗忘、导出上下文或配置 Git 同步时；读取可直接执行，持久写入、自动同步、OAuth、remote 修改和仓库创建必须来自当前用户的明确请求。\ntags:\n  - memory\n  - memhub\n  - github\n  - gitee\n  - sync\n  - agent-memory\nlicense: MIT-0\n---\n\n# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让 Agent 能够读取、写入和同步符合 MemHub Protocol v0.1 的记忆仓库。\n\n## 触发场景\n\n使用本 Skill 当：\n\n- 用户说“记住这个”、“帮我记一下”、“以后记得”。\n- 用户问“我的偏好是什么”、“当前项目上下文是什么”。\n- 用户需要把记忆注入到 Gemini/元宝/豆包/Cursor/Claude Code。\n- 会话开始时需要读取用户长期记忆。\n- 用户明确要求在会话结束前保存关键决策、偏好或事实，或已经明确启用了对应自动记忆策略。\n\n## 环境变量\n\n推荐设置（唯一需要的一项）：\n\n```bash\nexport MEMHUB_REPO=/path/to/memhub-data\n```\n\nGitHub 默认使用官方 Device Flow。Gitee OAuth 可使用内置 Broker，但 CLI 会先展示固定\nBroker 域名并要求用户确认；非交互环境必须显式传入可信 Broker 或自己的 OAuth 配置。\n\n可选配置项只写在进程环境或显式 `--env-file` 中，不要写进 Skill、仓库或聊天：\n\n- `MEMHUB_OAUTH_BROKER_URL`：明确选择的通用 Broker；\n- `MEMHUB_GITEE_OAUTH_BROKER_URL`：仅用于 Gitee 的可信 Broker；\n- `MEMHUB_GITHUB_CLIENT_ID`、`MEMHUB_GITEE_CLIENT_ID`：自有 OAuth App client id；\n- `MEMHUB_GITEE_CLIENT_SECRET`：Gitee 直连模式的 client secret；\n- `MEMHUB_GITHUB_TOKEN`、`MEMHUB_GITEE_TOKEN`：token fallback。\n\n必须通过 `--repo` 或 `MEMHUB_REPO` 明确指定专用记忆仓库；CLI 不会把当前目录隐式当作记忆仓库。\n\nCLI 不会自动读取当前目录或 home 目录的通用 `.env`。如确需文件配置，显式传入\n`--env-file /path/to/memhub.env`；只会加载受支持的 `MEMHUB_*` 键。\n\n## 权限与确认边界\n\n机器可读版本见同目录 `permissions.json`；下面的散文说明与它一致。\n\n- `context`、`search`、`inbox list/show`、`doctor` 是只读操作；`doctor` 默认完全离线，只有显式加 `--network` 才会探测已配置的 broker。\n- `remember`、`forget --apply`、`promote --apply`、`init` 会修改记忆仓库；只有用户当前请求明确要求对应写入时才执行。\n- `sync`、`sync setup`、`onboard` 会访问网络或修改 Git 状态；只有用户当前请求明确要求同步或配置时才执行。\n- `sync setup`/`onboard` 是用户明确发起的同步授权，完成后保留原有节流自动同步；用户可传 `--manual-sync` 关闭。\n- 所有 inbox 引用和 canonical target 都限制在指定 MemHub 仓库内；拒绝绝对路径和 `..` 越界。\n- HTTPS token 只会发送到所选 Provider 的固定官方 Git/API 主机；目标主机不匹配时拒绝执行。\n- 只有 `git` 一个外部命令会被调用，且不经过 shell；凭据只经子进程环境传递，不出现在 argv。\n- 远程写入（创建仓库、push）只在 `sync setup` / `onboard` / `sync` 被用户显式调用时发生。\n- 没有破坏性操作：`forget` 是软归档，不删文件、不改写 Git 历史。\n\n## 命令\n\n本 Skill 提供一个 Python CLI：`scripts/memhub.py`。\n\n```bash\n# 初始化仓库\npython scripts/memhub.py --repo ~/memhub-data init --name dateng --role \"Product Manager\"\n\n# 读取上下文\npython scripts/memhub.py --repo ~/memhub-data context\npython scripts/memhub.py --repo ~/memhub-data context --pack brief\n# 记忆：默认直写 canonical 并本地提交；是否自动推送取决于同步配置\npython scripts/memhub.py --repo ~/memhub-data remember \"用户偏好结构化直接的回答\" --type preference --source agent\npython scripts/memhub.py --repo ~/memhub-data remember \"MemHub 采用 Git-first 架构\" --type decision --project memhub --source agent\n# 低置信/待人工复核的内容才进 inbox 审计缓冲\npython scripts/memhub.py --repo ~/memhub-data remember \"也许该支持 Notion 导出\" --type fact --inbox --source agent\n\n# 检索与遗忘\npython scripts/memhub.py --repo ~/memhub-data search \"Git-first\"\npython scripts/memhub.py --repo ~/memhub-data search \"决策\" --type decision --project memhub\npython scripts/memhub.py --repo ~/memhub-data search \"旧偏好\" --include-archived   # 含已归档\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\"            # 预览\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\" --apply     # 软归档（status=archived）\n\n# 将 inbox 缓冲项归档到 canonical（仅 --inbox 写入的内容才需要）\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote --status all --apply   # 扫全部 inbox 项\n\n# 检查 inbox\npython scripts/memhub.py --repo ~/memhub-data inbox list\npython scripts/memhub.py --repo ~/memhub-data inbox list --status all\npython scripts/memhub.py --repo ~/memhub-data inbox show <filename-or-id-fragment>\n\n# 将 inbox 半自动归档到 canonical memory\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote <filename-or-id-fragment> --apply\n\n# 导出给 chatbot 的上下文\npython scripts/memhub.py --repo ~/memhub-data export chatbot\n\n# 首次接入（推荐）：授权 + 自动判断拉取已有记忆 / 初始化新仓库\npython scripts/memhub.py --repo ~/memhub-data onboard github --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data onboard gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n\n# 同步 GitHub/Gitee（手动分步）\npython scripts/memhub.py --repo ~/memhub-data sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\npython scripts/memhub.py --repo ~/memhub-data sync setup github --auth token --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\npython scripts/memhub.py --repo ~/memhub-data sync status\npython scripts/memhub.py --repo ~/memhub-data sync\n\n# 自检：确认本机/本仓库的自动同步是否就绪（remote/token/merge driver/MEMHUB_REPO 等）\npython scripts/memhub.py --repo ~/memhub-data doctor\n```\n\n## Agent 行为协议\n\n### 上下文 pack 分级\n\n`context --pack` 有四档,逐档累加内容:\n\n- `brief`:用户画像、最重要的偏好、当前项目及最近决策(用于注入 chatbot)。\n- `standard`(默认):brief + 约束、惯例、未完成任务。\n- `project`:聚焦默认/指定项目,决策与任务更全。\n- `full`:standard + knowledge、relations、最近 timeline。\n\n`export chatbot` 默认用 brief;若存在 `.memhub/templates/context-pack.md.j2`,则用该模板渲染(支持 `{{ name }}` 等占位符)。\n\n### 总原则\n\n- `MEMHUB_REPO` 是用户记忆仓库；不要把用户记忆写入代码仓库。\n- GitHub/Gitee remote 只是同步后端；YAML/Markdown 文件仍是可信源数据。\n- 自动写入默认进入 canonical 记忆（本地提交，不自动推送）；低置信或需人工复核的才用 `--inbox`。\n- `sync setup` 会触发授权、创建仓库、修改 remote；**只有用户明确要求配置/切换同步时才执行**。\n- OAuth/token/SSH 凭据、authorization code、client secret、access token 都属于敏感信息；不要在回答中复述。\n\n### 对话开始：读取上下文\n\n**本会话首次涉及记忆时**，先跑一次自检确认自动同步就绪（每个会话只需一次，不要每轮都跑）：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" doctor\n```\n\n- 若 doctor 报 `NOT ready`（有 ✗），说明自动同步未生效。按提示补齐：缺 remote → 提示用户\n  `sync setup`；缺 token（常见于新机器）→ 引导用户重新授权；其余 ✗ 同理。**不要静默忽略**，\n  否则用户会误以为在自动同步，实际没有。\n- 若全绿或只有 `!` 提示，继续正常流程。\n- doctor 是只读的、默认不联网（只有显式 `--network` 才探测 broker），开销很小；但仍只需每会话首次跑一次即可。\n- doctor 会打印凭据存放位置；若仓库里还有旧版 `.memhub/secrets.yaml`，会提示可以删除。\n\n确认就绪后，直接读取 context。仅当用户已通过 setup/onboard 授权自动同步时，\n`context` 才会按节流阈值从远端拉取最新记忆：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief\n```\n\n- 若距上次拉取超过 `pull_throttle_seconds`，`context` 会自动 `pull --rebase` 再输出。\n- 自动拉取失败时，CLI 会用本地记忆并在 stderr 提示“远端同步失败，当前上下文可能不是最新”，\n  无需中断；如需强制最新，可显式 `sync` 后再读。\n- 将 context 作为可审计上下文，不要当成绝对事实；遇到冲突时优先询问用户。\n\n### 对话中：写入记忆\n\n当用户明确要求记忆，或已经明确启用了对应自动记忆策略时，默认**直写 canonical**：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"内容\" --type fact --source agent\n```\n\n- 直写会按 type 路由到对应 canonical 文件、去重后追加并本地提交；是否自动推送取决于用户在 setup/onboard 时选择的同步模式。\n- 重复内容会被自动跳过。\n- 只有低置信、需人工复核或批量待整理的内容，才加 `--inbox` 进审计缓冲，之后再 `promote`。\n\n类型建议：\n\n- `decision`：明确决策\n- `preference`：稳定偏好\n- `fact`：事实\n- `knowledge`：可复用知识/结论\n- `event`：重要事件\n- `relation`：人物/组织/工具关系\n- `constraint`：约束\n- `convention`：惯例\n\n### 同步：显式配置后自动节流，可选择手动模式\n\n只有用户明确执行 setup/onboard 后才会配置 remote；此后保留原有的节流自动同步。\n若用户传入 `--manual-sync`，则关闭自动 pull/push，只保留显式 `sync`：\n\n- **写入即同步（节流）**：每次 `remember` / `forget --apply` / `promote --apply` 后，CLI 会\n  自动尝试推送。距上次推送不足 `sync.push_throttle_seconds`（默认 3600 秒）时只在本地提交，\n  超过阈值才真正 pull+push。**记忆始终立即落本地，绝不丢失。**\n- **读取即拉取（节流）**：`context` 命令会在 `sync.pull_throttle_seconds`（默认 3600 秒）阈值外\n  自动 `pull --rebase` 拉取其它设备的最新记忆；拉取失败则用本地并在 stderr 提示可能不是最新。\n\n显式 `sync` 命令**忽略节流，立即** pull+push，适合在对话收尾兜底，确保本次所有记忆都已上远端：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync\n```\n\n节流阈值与开关都在 `.memhub/config.yaml` 的 `sync` 段（`auto_push`/`auto_pull` /\n`push_throttle_seconds` / `pull_throttle_seconds`）；节流时间戳记在本机 `.memhub/cache/sync.yaml`\n（git 忽略，每台设备独立）。单次写入若想跳过自动推送，加 `--no-sync`。\n\n`init`/`sync` 会自动注册结构化 merge 驱动（local git config 不随 clone 走，故每台设备首次\n`sync` 会自愈补注册），多设备对同一记忆文件的并发追加可自动合并，不会冲突。\n\n> **换新机器/新 Agent 时**：凭据存在记忆仓库**之外**的机器本地目录（macOS 默认\n> `~/Library/Application Support/memhub/secrets/`，Linux 默认 `~/.local/state/memhub/secrets/`，\n> 可用 `MEMHUB_SECRETS_DIR` 覆盖），因此不随 clone 或同步走，新机器需要**重新授权一次**。\n> 先跑 `doctor` 自检，按提示补齐\n> remote/token 即可——全绿后自动同步即就绪。\n\n### 检索与遗忘\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" search \"关键词\" --type decision --project memhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" forget \"过时内容\"          # 预览\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" forget \"过时内容\" --apply   # 软归档\n```\n\n- `forget` 默认 dry-run；`--apply` 把命中条目 `status` 置为 `archived`，使其从 context pack\n  消失但保留在 Git 历史中，可审计、可回滚。\n- 纠正一条记忆 = `forget` 旧条目 + `remember` 新条目。\n\n### 首次接入：用 onboard（推荐）\n\n新 agent / 新机器第一次接入时，**用 `onboard` 一条命令完成全流程**，它会自动判断该\n\"拉取已有记忆\"还是\"初始化新仓库\"，避免用默认数据污染你已有的真实记忆：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" onboard gitee --repo-name mymemhub --broker-url https://<trusted-broker>\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" onboard github --repo-name mymemhub\n```\n\nonboard 的流程：\n\n1. 授权（GitHub 默认走官方 Device Flow；Gitee Broker 必须显式指定）。\n2. **探测远端**是否已有 MemHub 记忆仓库（含 `.memhub/config.yaml`）：\n   - **已有** → 以远端为准拉取到本地，**不写入任何默认数据**（你的真实记忆直接到位）；\n   - **为空** → 初始化默认记忆并推送，建立远端仓库。\n3. 注册 merge 驱动，并按用户选择启用节流 auto-sync 或 `--manual-sync`。\n4. 打印 `doctor` 自检结果。\n\n完成 setup/onboard 后，默认维持原有节流自动同步；如果用户选择 `--manual-sync`，则只在\n显式执行 `sync` 时联网。新机器换设备时优先用 `onboard`，不要先 `init` 再 `sync setup`\n（那会先播种默认数据，可能污染远端真实记忆）。\n\n### 同步 setup：手动分步配置（高级）\n\n`onboard` 内部会调用 setup。只有当你想单独配置/切换 remote、且明确知道本地数据状态时，\n才直接用 `sync setup`。当用户说“配置同步”、“连接 GitHub/Gitee”、“换成 Gitee/GitHub 同步”时，\n优先用 `onboard`。\n\nGitHub 默认走官方 Device Flow。Gitee 交互式配置会先展示内置 Broker 域名并请求确认；\n非交互环境必须通过 `--broker-url` 或 `MEMHUB_GITEE_OAUTH_BROKER_URL` 明确指定，\n也可以使用自己的 client secret 直连。\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n```\n\n显式选择 Broker 时的授权流程：\n\n1. CLI 调用 broker 创建授权 session，得到一个 `auth_url`。\n2. CLI 打开（或打印）该 URL；Agent 应把 URL 展示给用户，请用户在浏览器完成授权。\n3. CLI 轮询 broker 直到拿到 access token，自动存入记忆仓库之外的本机凭据目录（0600，可用 `MEMHUB_SECRETS_DIR` 覆盖）。\n4. 不要要求用户把 access token 发到聊天里。\n\n无浏览器环境：加 `--no-browser`，CLI 会打印 URL 由用户手动打开。\n\n#### 高级 / fallback（仅当用户明确选择时）\n\n- 自建 broker：`--broker-url https://your-broker` 或设 `MEMHUB_OAUTH_BROKER_URL` /\n  `MEMHUB_GITEE_OAUTH_BROKER_URL`。\n- 开发者直连（不经 broker）：Gitee 使用 `MEMHUB_GITEE_CLIENT_SECRET`；\n  GitHub 会回退到 Device Flow。\n- Token / SSH：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth token --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\n```\n\n### 同步失败与冲突处理\n\n- 不要删除本地 `inbox`、canonical 文件或 `.git` 历史。\n- 将错误摘要告诉用户，避免泄露 token/header。\n- 如果 `git pull --rebase` 冲突，停止自动处理，报告冲突文件，让用户/Agent 单独修复。\n- 如果 provider 授权失败，建议用户重新授权或切换 token/SSH fallback。\n- 如果远端仓库创建失败但已存在，可以继续配置 remote 并尝试 sync。\n\n### Inbox 归档（promote）\n\n`remember` 默认直写 canonical，无需 promote。只有用 `--inbox` 缓冲过的低置信/待复核内容\n才需要 promote。整理 inbox 时先预览：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox list\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --dry-run\n```\n\n确认归档目标合理后再执行（默认 dry-run，须显式 `--apply`；已启用 auto-sync 时才按节流自动推送）：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --apply\n```\n\n`promote` 默认只扫 pending 的 inbox 项，可用 `--status all` 扫全部。归档路由规则：\n\n- `decision` → `projects/<project>/decisions.yaml`\n- `preference` → `identity/preferences.yaml`\n- `constraint` → `identity/constraints.yaml`\n- `convention` → `identity/conventions.yaml`\n- `knowledge` → `knowledge/product.yaml`\n- `relation` → `relations/people.yaml`\n- `fact` / `event` → `timeline/YYYY-MM.yaml`\n\n不要写入：\n\n- 临时闲聊\n- 未确认猜测\n- 敏感信息，除非用户明确授权\n- 无新增信息的重复内容\n\n### 对话结束\n\n如果用户明确要求保存重要决策、偏好或事实，或已经明确启用了对应自动记忆策略：\n\n1. `remember` 直写记忆（低置信内容用 `--inbox`，必要时 `promote`）。\n2. 如果用户已明确启用 auto-sync，按节流策略同步；否则只有用户明确要求时才执行 `sync`。\n\n## 安全模型与机器可读边界\n\n`permissions.json` 是本 Skill 的权限边界声明（文件/网络/凭据/变更），供扫描器与人工复核直接读取：\n\n- 文件写入只落在 `MEMHUB_REPO` 内；绝对路径与 `..` 越界一律拒绝。\n- 凭据只写入 `MEMHUB_REPO` 之外的本机目录，文件 0600、目录 0700。\n- 默认无自动出网；`sync setup` / `onboard` / `sync` 被显式调用后才访问 github.com / gitee.com。\n- GitHub 走官方 Device Flow（scope `repo`）；Gitee 直连 OAuth 每次生成并校验 `state`，防止把别人的账号绑定到本仓库。\n- 第三方 broker 不会被隐式使用：必须由用户通过 `--broker-url` 或 `MEMHUB_*_OAUTH_BROKER_URL` 明确指定主机。\n- `doctor` 默认离线；需要探测 broker 时显式加 `--network`。\n\n## 发布与安全约束\n\n- 不要把真实 token、client secret、OAuth code 写进 `SKILL.md`、README、示例或提交历史。\n- 凭据文件必须留在记忆仓库之外；仓库内的旧 `.memhub/secrets.yaml` 只作为一次性读取的迁移来源。\n- 发布到 SkillHub/ClawHub 的包应包含：`SKILL.md`、`README.md`、`permissions.json`、`scripts/memhub.py`、`templates/context-pack.md.j2`。\n- 发布包不应包含 `__pycache__`、`.pyc`、`.git` 或用户个人记忆数据。\n\n## 重要原则\n\n- MemHub 只负责存取和同步，智能判断由 Agent 完成。\n- 写入必须带 source，便于追溯。\n- 默认直写 canonical 记忆；低置信或需人工复核的内容才进 inbox 审计缓冲。\n- Git 仓库中的 YAML/Markdown 是唯一可信源数据。\n\nFile v0.4.8:_meta.json\n\n{\n  \"ownerId\": \"kn7aq20vx0abk37pk7pnq842t1827dq3\",\n  \"slug\": \"memhub\",\n  \"version\": \"0.4.8\",\n  \"publishedAt\": 1790043422130\n}\n\nFile v0.4.8:skill-card.md\n\n## Description:\n\nMemHub helps agents manage a user-selected, Git-first long-term memory repository for remembering, retrieving, forgetting, exporting context, and configuring synchronization when explicitly requested.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cutd](https://clawhub.ai/user/cutd)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent users use MemHub when an agent needs persistent personal or project memory across sessions, including reading context, saving explicit memories, archiving outdated memories, exporting chatbot context, and setting up GitHub or Gitee sync. Writes, remote changes, OAuth flows, and repository creation are intended to happen only after the current user explicitly requests them.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: A long-term memory repository can persist sensitive or incorrect personal context if the wrong repository path or sync mode is used.\n\nMitigation: Review the dedicated MemHub repository path and synchronization settings before use, and choose manual sync when automatic pull or push is not desired.\n\nRisk: OAuth codes, access tokens, client secrets, and other credentials could be exposed if shared in chat or stored with skill content.\n\nMitigation: Do not share credentials in chat; keep supported MEMHUB credential settings in process environment, explicit env files, or local credential storage outside the memory repository.\n\nRisk: Remote repository creation, push, pull, or sync configuration can change Git state or transmit memory data to GitHub or Gitee.\n\nMitigation: Run sync setup, onboard, and sync operations only when the current user explicitly requests synchronization or remote configuration.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/cutd/skills/memhub)\n- [Publisher profile](https://clawhub.ai/user/cutd)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown with inline shell commands and configuration guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Produces agent-facing instructions for operating a dedicated MemHub repository; it does not itself include user memory data.]\n\n## Skill Version(s):\n\n0.4.8 (source: frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.4.7: 6 files, 40233 bytes\n\nFiles: README.md (4530b), scripts/memhub.py (108561b), skill-card.md (2852b), SKILL.md (17660b), templates/context-pack.md.j2 (278b), _meta.json (125b)\n\nFile v0.4.7:SKILL.md\n\n---\nname: memhub\nversion: 0.4.7\ndescription: 使用 MemHub Protocol v0.1 管理用户明确指定的跨 Agent 记忆仓库。用于用户明确要求记住、检索、遗忘、导出上下文或配置 Git 同步时；读取可直接执行，持久写入、自动同步、OAuth、remote 修改和仓库创建必须来自当前用户的明确请求。\ntags:\n  - memory\n  - memhub\n  - github\n  - gitee\n  - sync\n  - agent-memory\nlicense: MIT-0\n---\n\n# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让 Agent 能够读取、写入和同步符合 MemHub Protocol v0.1 的记忆仓库。\n\n## 触发场景\n\n使用本 Skill 当：\n\n- 用户说“记住这个”、“帮我记一下”、“以后记得”。\n- 用户问“我的偏好是什么”、“当前项目上下文是什么”。\n- 用户需要把记忆注入到 Gemini/元宝/豆包/Cursor/Claude Code。\n- 会话开始时需要读取用户长期记忆。\n- 用户明确要求在会话结束前保存关键决策、偏好或事实，或已经明确启用了对应自动记忆策略。\n\n## 环境变量\n\n推荐设置（唯一需要的一项）：\n\n```bash\nexport MEMHUB_REPO=/path/to/memhub-data\n```\n\nGitHub 默认使用官方 Device Flow。Gitee OAuth 可使用内置 Broker，但 CLI 会先展示固定\nBroker 域名并要求用户确认；非交互环境必须显式传入可信 Broker 或自己的 OAuth 配置。\n\n可选配置项只写在进程环境或显式 `--env-file` 中，不要写进 Skill、仓库或聊天：\n\n- `MEMHUB_OAUTH_BROKER_URL`：明确选择的通用 Broker；\n- `MEMHUB_GITEE_OAUTH_BROKER_URL`：仅用于 Gitee 的可信 Broker；\n- `MEMHUB_GITHUB_CLIENT_ID`、`MEMHUB_GITEE_CLIENT_ID`：自有 OAuth App client id；\n- `MEMHUB_GITEE_CLIENT_SECRET`：Gitee 直连模式的 client secret；\n- `MEMHUB_GITHUB_TOKEN`、`MEMHUB_GITEE_TOKEN`：token fallback。\n\n必须通过 `--repo` 或 `MEMHUB_REPO` 明确指定专用记忆仓库；CLI 不会把当前目录隐式当作记忆仓库。\n\nCLI 不会自动读取当前目录或 home 目录的通用 `.env`。如确需文件配置，显式传入\n`--env-file /path/to/memhub.env`；只会加载受支持的 `MEMHUB_*` 键。\n\n## 权限与确认边界\n\n- `context`、`search`、`inbox list/show`、`doctor` 是只读操作。\n- `remember`、`forget --apply`、`promote --apply`、`init` 会修改记忆仓库；只有用户当前请求明确要求对应写入时才执行。\n- `sync`、`sync setup`、`onboard` 会访问网络或修改 Git 状态；只有用户当前请求明确要求同步或配置时才执行。\n- `sync setup`/`onboard` 是用户明确发起的同步授权，完成后保留原有节流自动同步；用户可传 `--manual-sync` 关闭。\n- 所有 inbox 引用和 canonical target 都限制在指定 MemHub 仓库内；拒绝绝对路径和 `..` 越界。\n- HTTPS token 只会发送到所选 Provider 的固定官方 Git/API 主机；目标主机不匹配时拒绝执行。\n\n## 命令\n\n本 Skill 提供一个 Python CLI：`scripts/memhub.py`。\n\n```bash\n# 初始化仓库\npython scripts/memhub.py --repo ~/memhub-data init --name dateng --role \"Product Manager\"\n\n# 读取上下文\npython scripts/memhub.py --repo ~/memhub-data context\npython scripts/memhub.py --repo ~/memhub-data context --pack brief\n# 记忆：默认直写 canonical 并本地提交；是否自动推送取决于同步配置\npython scripts/memhub.py --repo ~/memhub-data remember \"用户偏好结构化直接的回答\" --type preference --source agent\npython scripts/memhub.py --repo ~/memhub-data remember \"MemHub 采用 Git-first 架构\" --type decision --project memhub --source agent\n# 低置信/待人工复核的内容才进 inbox 审计缓冲\npython scripts/memhub.py --repo ~/memhub-data remember \"也许该支持 Notion 导出\" --type fact --inbox --source agent\n\n# 检索与遗忘\npython scripts/memhub.py --repo ~/memhub-data search \"Git-first\"\npython scripts/memhub.py --repo ~/memhub-data search \"决策\" --type decision --project memhub\npython scripts/memhub.py --repo ~/memhub-data search \"旧偏好\" --include-archived   # 含已归档\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\"            # 预览\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\" --apply     # 软归档（status=archived）\n\n# 将 inbox 缓冲项归档到 canonical（仅 --inbox 写入的内容才需要）\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote --status all --apply   # 扫全部 inbox 项\n\n# 检查 inbox\npython scripts/memhub.py --repo ~/memhub-data inbox list\npython scripts/memhub.py --repo ~/memhub-data inbox list --status all\npython scripts/memhub.py --repo ~/memhub-data inbox show <filename-or-id-fragment>\n\n# 将 inbox 半自动归档到 canonical memory\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote <filename-or-id-fragment> --apply\n\n# 导出给 chatbot 的上下文\npython scripts/memhub.py --repo ~/memhub-data export chatbot\n\n# 首次接入（推荐）：授权 + 自动判断拉取已有记忆 / 初始化新仓库\npython scripts/memhub.py --repo ~/memhub-data onboard github --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data onboard gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n\n# 同步 GitHub/Gitee（手动分步）\npython scripts/memhub.py --repo ~/memhub-data sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\npython scripts/memhub.py --repo ~/memhub-data sync setup github --auth token --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\npython scripts/memhub.py --repo ~/memhub-data sync status\npython scripts/memhub.py --repo ~/memhub-data sync\n\n# 自检：确认本机/本仓库的自动同步是否就绪（remote/token/merge driver/MEMHUB_REPO 等）\npython scripts/memhub.py --repo ~/memhub-data doctor\n```\n\n## Agent 行为协议\n\n### 上下文 pack 分级\n\n`context --pack` 有四档,逐档累加内容:\n\n- `brief`:用户画像、最重要的偏好、当前项目及最近决策(用于注入 chatbot)。\n- `standard`(默认):brief + 约束、惯例、未完成任务。\n- `project`:聚焦默认/指定项目,决策与任务更全。\n- `full`:standard + knowledge、relations、最近 timeline。\n\n`export chatbot` 默认用 brief;若存在 `.memhub/templates/context-pack.md.j2`,则用该模板渲染(支持 `{{ name }}` 等占位符)。\n\n### 总原则\n\n- `MEMHUB_REPO` 是用户记忆仓库；不要把用户记忆写入代码仓库。\n- GitHub/Gitee remote 只是同步后端；YAML/Markdown 文件仍是可信源数据。\n- 自动写入默认进入 canonical 记忆（本地提交，不自动推送）；低置信或需人工复核的才用 `--inbox`。\n- `sync setup` 会触发授权、创建仓库、修改 remote；**只有用户明确要求配置/切换同步时才执行**。\n- OAuth/token/SSH 凭据、authorization code、client secret、access token 都属于敏感信息；不要在回答中复述。\n\n### 对话开始：读取上下文\n\n**本会话首次涉及记忆时**，先跑一次自检确认自动同步就绪（每个会话只需一次，不要每轮都跑）：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" doctor\n```\n\n- 若 doctor 报 `NOT ready`（有 ✗），说明自动同步未生效。按提示补齐：缺 remote → 提示用户\n  `sync setup`；缺 token（常见于新机器）→ 引导用户重新授权；其余 ✗ 同理。**不要静默忽略**，\n  否则用户会误以为在自动同步，实际没有。\n- 若全绿或只有 `!` 提示，继续正常流程。\n- doctor 是只读的、不联网，开销很小；但仍只需每会话首次跑一次即可。\n\n确认就绪后，直接读取 context。仅当用户已通过 setup/onboard 授权自动同步时，\n`context` 才会按节流阈值从远端拉取最新记忆：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief\n```\n\n- 若距上次拉取超过 `pull_throttle_seconds`，`context` 会自动 `pull --rebase` 再输出。\n- 自动拉取失败时，CLI 会用本地记忆并在 stderr 提示“远端同步失败，当前上下文可能不是最新”，\n  无需中断；如需强制最新，可显式 `sync` 后再读。\n- 将 context 作为可审计上下文，不要当成绝对事实；遇到冲突时优先询问用户。\n\n### 对话中：写入记忆\n\n当用户明确要求记忆，或已经明确启用了对应自动记忆策略时，默认**直写 canonical**：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"内容\" --type fact --source agent\n```\n\n- 直写会按 type 路由到对应 canonical 文件、去重后追加并本地提交；是否自动推送取决于用户在 setup/onboard 时选择的同步模式。\n- 重复内容会被自动跳过。\n- 只有低置信、需人工复核或批量待整理的内容，才加 `--inbox` 进审计缓冲，之后再 `promote`。\n\n类型建议：\n\n- `decision`：明确决策\n- `preference`：稳定偏好\n- `fact`：事实\n- `knowledge`：可复用知识/结论\n- `event`：重要事件\n- `relation`：人物/组织/工具关系\n- `constraint`：约束\n- `convention`：惯例\n\n### 同步：显式配置后自动节流，可选择手动模式\n\n只有用户明确执行 setup/onboard 后才会配置 remote；此后保留原有的节流自动同步。\n若用户传入 `--manual-sync`，则关闭自动 pull/push，只保留显式 `sync`：\n\n- **写入即同步（节流）**：每次 `remember` / `forget --apply` / `promote --apply` 后，CLI 会\n  自动尝试推送。距上次推送不足 `sync.push_throttle_seconds`（默认 3600 秒）时只在本地提交，\n  超过阈值才真正 pull+push。**记忆始终立即落本地，绝不丢失。**\n- **读取即拉取（节流）**：`context` 命令会在 `sync.pull_throttle_seconds`（默认 3600 秒）阈值外\n  自动 `pull --rebase` 拉取其它设备的最新记忆；拉取失败则用本地并在 stderr 提示可能不是最新。\n\n显式 `sync` 命令**忽略节流，立即** pull+push，适合在对话收尾兜底，确保本次所有记忆都已上远端：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync\n```\n\n节流阈值与开关都在 `.memhub/config.yaml` 的 `sync` 段（`auto_push`/`auto_pull` /\n`push_throttle_seconds` / `pull_throttle_seconds`）；节流时间戳记在本机 `.memhub/cache/sync.yaml`\n（git 忽略，每台设备独立）。单次写入若想跳过自动推送，加 `--no-sync`。\n\n`init`/`sync` 会自动注册结构化 merge 驱动（local git config 不随 clone 走，故每台设备首次\n`sync` 会自愈补注册），多设备对同一记忆文件的并发追加可自动合并，不会冲突。\n\n> **换新机器/新 Agent 时**：凭据（token）存在本机 `.memhub/secrets.yaml` 且不随 git 同步，\n> 所以新机器即使 clone 了记忆仓库也需要**重新授权一次**。先跑 `doctor` 自检，按提示补齐\n> remote/token 即可——全绿后自动同步即就绪。\n\n### 检索与遗忘\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" search \"关键词\" --type decision --project memhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" forget \"过时内容\"          # 预览\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" forget \"过时内容\" --apply   # 软归档\n```\n\n- `forget` 默认 dry-run；`--apply` 把命中条目 `status` 置为 `archived`，使其从 context pack\n  消失但保留在 Git 历史中，可审计、可回滚。\n- 纠正一条记忆 = `forget` 旧条目 + `remember` 新条目。\n\n### 首次接入：用 onboard（推荐）\n\n新 agent / 新机器第一次接入时，**用 `onboard` 一条命令完成全流程**，它会自动判断该\n\"拉取已有记忆\"还是\"初始化新仓库\"，避免用默认数据污染你已有的真实记忆：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" onboard gitee --repo-name mymemhub --broker-url https://<trusted-broker>\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" onboard github --repo-name mymemhub\n```\n\nonboard 的流程：\n\n1. 授权（GitHub 默认走官方 Device Flow；Gitee Broker 必须显式指定）。\n2. **探测远端**是否已有 MemHub 记忆仓库（含 `.memhub/config.yaml`）：\n   - **已有** → 以远端为准拉取到本地，**不写入任何默认数据**（你的真实记忆直接到位）；\n   - **为空** → 初始化默认记忆并推送，建立远端仓库。\n3. 注册 merge 驱动，并按用户选择启用节流 auto-sync 或 `--manual-sync`。\n4. 打印 `doctor` 自检结果。\n\n完成 setup/onboard 后，默认维持原有节流自动同步；如果用户选择 `--manual-sync`，则只在\n显式执行 `sync` 时联网。新机器换设备时优先用 `onboard`，不要先 `init` 再 `sync setup`\n（那会先播种默认数据，可能污染远端真实记忆）。\n\n### 同步 setup：手动分步配置（高级）\n\n`onboard` 内部会调用 setup。只有当你想单独配置/切换 remote、且明确知道本地数据状态时，\n才直接用 `sync setup`。当用户说“配置同步”、“连接 GitHub/Gitee”、“换成 Gitee/GitHub 同步”时，\n优先用 `onboard`。\n\nGitHub 默认走官方 Device Flow。Gitee 交互式配置会先展示内置 Broker 域名并请求确认；\n非交互环境必须通过 `--broker-url` 或 `MEMHUB_GITEE_OAUTH_BROKER_URL` 明确指定，\n也可以使用自己的 client secret 直连。\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n```\n\n显式选择 Broker 时的授权流程：\n\n1. CLI 调用 broker 创建授权 session，得到一个 `auth_url`。\n2. CLI 打开（或打印）该 URL；Agent 应把 URL 展示给用户，请用户在浏览器完成授权。\n3. CLI 轮询 broker 直到拿到 access token，自动存入本机 `.memhub/secrets.yaml`（git 忽略）。\n4. 不要要求用户把 access token 发到聊天里。\n\n无浏览器环境：加 `--no-browser`，CLI 会打印 URL 由用户手动打开。\n\n#### 高级 / fallback（仅当用户明确选择时）\n\n- 自建 broker：`--broker-url https://your-broker` 或设 `MEMHUB_OAUTH_BROKER_URL` /\n  `MEMHUB_GITEE_OAUTH_BROKER_URL`。\n- 开发者直连（不经 broker）：Gitee 使用 `MEMHUB_GITEE_CLIENT_SECRET`；\n  GitHub 会回退到 Device Flow。\n- Token / SSH：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth token --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\n```\n\n### 同步失败与冲突处理\n\n- 不要删除本地 `inbox`、canonical 文件或 `.git` 历史。\n- 将错误摘要告诉用户，避免泄露 token/header。\n- 如果 `git pull --rebase` 冲突，停止自动处理，报告冲突文件，让用户/Agent 单独修复。\n- 如果 provider 授权失败，建议用户重新授权或切换 token/SSH fallback。\n- 如果远端仓库创建失败但已存在，可以继续配置 remote 并尝试 sync。\n\n### Inbox 归档（promote）\n\n`remember` 默认直写 canonical，无需 promote。只有用 `--inbox` 缓冲过的低置信/待复核内容\n才需要 promote。整理 inbox 时先预览：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox list\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --dry-run\n```\n\n确认归档目标合理后再执行（默认 dry-run，须显式 `--apply`；已启用 auto-sync 时才按节流自动推送）：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --apply\n```\n\n`promote` 默认只扫 pending 的 inbox 项，可用 `--status all` 扫全部。归档路由规则：\n\n- `decision` → `projects/<project>/decisions.yaml`\n- `preference` → `identity/preferences.yaml`\n- `constraint` → `identity/constraints.yaml`\n- `convention` → `identity/conventions.yaml`\n- `knowledge` → `knowledge/product.yaml`\n- `relation` → `relations/people.yaml`\n- `fact` / `event` → `timeline/YYYY-MM.yaml`\n\n不要写入：\n\n- 临时闲聊\n- 未确认猜测\n- 敏感信息，除非用户明确授权\n- 无新增信息的重复内容\n\n### 对话结束\n\n如果用户明确要求保存重要决策、偏好或事实，或已经明确启用了对应自动记忆策略：\n\n1. `remember` 直写记忆（低置信内容用 `--inbox`，必要时 `promote`）。\n2. 如果用户已明确启用 auto-sync，按节流策略同步；否则只有用户明确要求时才执行 `sync`。\n\n## 发布与安全约束\n\n- 不要把真实 token、client secret、OAuth code 写进 `SKILL.md`、README、示例或提交历史。\n- `.memhub/secrets.yaml` 必须保持本地忽略。\n- 发布到 SkillHub/ClawHub 的包应包含：`SKILL.md`、`README.md`、`scripts/memhub.py`、`templates/context-pack.md.j2`。\n- 发布包不应包含 `__pycache__`、`.pyc`、`.git` 或用户个人记忆数据。\n\n## 重要原则\n\n- MemHub 只负责存取和同步，智能判断由 Agent 完成。\n- 写入必须带 source，便于追溯。\n- 默认直写 canonical 记忆；低置信或需人工复核的内容才进 inbox 审计缓冲。\n- Git 仓库中的 YAML/Markdown 是唯一可信源数据。\n\nFile v0.4.7:README.md\n\n# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让任意支持 Skill 的 Agent 能够读写、归档和同步用户的跨 Agent 统一记忆仓库。\n\n## 能力\n\n- 读取长期记忆上下文：`context --pack brief|standard|full|project`\n- 写入默认 inbox：`remember`\n- 检查与展示 inbox：`inbox list/show`\n- 半自动归档到 canonical memory：`promote --dry-run/--apply`\n- 导出给 chatbot 的上下文：`export chatbot`\n- GitHub/Gitee 同步：OAuth、token fallback、SSH fallback\n\n## 安装到任意支持 Skill 的 Agent\n\n将本目录 `skills/memhub/` 复制到对应 skills 目录，或通过 SkillHub/ClawHub 安装。\n\n## 配置仓库路径\n\n```bash\nexport MEMHUB_REPO=~/memhub-data\n```\n\n必须通过 `--repo` 或 `MEMHUB_REPO` 明确指定专用记忆仓库；CLI 不会把当前目录隐式当作记忆仓库。\n\n## 首次初始化\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" init --name dateng --role \"Product Manager\"\n```\n\n## 配置 GitHub/Gitee 同步\n\n推荐使用 OAuth setup 命令，而不是手动配置 remote。GitHub 默认走官方 Device Flow。\nGitee 交互式配置会先展示内置 Broker 域名并请求确认；非交互环境需明确提供可信 Broker，\n或使用自己的 OAuth 配置。\n\n### GitHub / Gitee 授权\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n```\n\nGitHub 使用 Device Flow。明确选择 Broker 时，流程为：\n\n1. CLI 调 broker 创建授权 session，拿到 `auth_url`；\n2. CLI 打开该 URL，用户在 GitHub/Gitee 页面点击确认授权；\n3. broker 在服务端用 `client_secret` 换取 token；\n4. CLI 轮询 broker 拿到 token，存入本地 `.memhub/secrets.yaml`（git 忽略）。\n\n无浏览器环境加 `--no-browser`，CLI 会打印 URL 供手动打开。\n\n### 高级覆盖 / Fallback\n\n可选配置项：`MEMHUB_OAUTH_BROKER_URL`、`MEMHUB_GITEE_OAUTH_BROKER_URL`、\n`MEMHUB_GITHUB_CLIENT_ID`、`MEMHUB_GITEE_CLIENT_ID`、\n`MEMHUB_GITEE_CLIENT_SECRET`。只放在进程环境或显式 `--env-file` 中，\n不要写进仓库、文档示例或聊天。\n\n### Token / SSH Fallback\n\n```bash\n# Token fallback\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth token --repo-name mymemhub\n\n# SSH fallback\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\n```\n\nOAuth/token 会保存在本地 `.memhub/secrets.yaml`，并被 `.gitignore` 忽略。不要把 OAuth app 的 client secret、token 或 authorization code 提交到仓库。\n\n## 常用命令\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"要记住的内容\" --type fact --source agent\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox list\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox show <filename-or-id-fragment>\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --dry-run\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --apply\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" export chatbot\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync status\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync\n```\n\n## Agent 使用原则\n\n- 读取前：如果任务依赖长期记忆，先 `sync`，再 `context --pack brief`。\n- 写入时：用户明确要求记忆，或形成稳定决策/偏好/事实时，写入 inbox。\n- 写入后：已授权 auto-sync 时由节流逻辑处理；manual-sync 模式只在用户要求时执行 `sync`。\n- 归档时：先 `promote --dry-run`，确认后再 `promote --apply`，然后 `sync`。\n- setup：只有用户明确要求配置或切换同步服务时才执行。\n- 自动同步：用户明确运行 setup/onboard 后默认启用；如只想手动同步，添加 `--manual-sync`。\n- 失败：同步失败时不要删除本地数据；报告错误并保留本地文件。\n\nCLI 不会隐式读取 cwd 或 home 的 `.env`。需要文件配置时使用\n`--env-file /path/to/memhub.env`，且只加载受支持的 `MEMHUB_*` 键。\n\n## 发布包内容\n\n发布到 SkillHub/ClawHub 时应包含：\n\n```text\nSKILL.md\nREADME.md\nscripts/memhub.py\ntemplates/context-pack.md.j2\n```\n\n不应包含：\n\n```text\n__pycache__/\n*.pyc\n.git/\n.memhub/secrets.yaml\n用户个人记忆数据\n```\n\n## License\n\nMIT-0\n\nFile v0.4.7:_meta.json\n\n{\n  \"ownerId\": \"kn7aq20vx0abk37pk7pnq842t1827dq3\",\n  \"slug\": \"memhub\",\n  \"version\": \"0.4.7\",\n  \"publishedAt\": 1790000922408\n}\n\nFile v0.4.7:skill-card.md\n\n## Description:\n\nMemHub manages a user-designated cross-agent memory repository using MemHub Protocol v0.1, allowing agents to read, remember, search, forget, export context, and configure Git synchronization only within the user's explicit consent boundaries.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cutd](https://clawhub.ai/user/cutd)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent users use MemHub to give supported agents a shared, auditable memory store for long-term preferences, project decisions, facts, and chatbot context. The skill is intended for explicit memory operations and GitHub or Gitee synchronization of a dedicated personal memory repository.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can store GitHub or Gitee tokens locally in plaintext and can synchronize personal memory to a remote Git repository after setup.\n\nMitigation: Use private repositories, prefer GitHub device flow or a trusted OAuth broker, do not share tokens or authorization codes in chat, and use --manual-sync when every remote push should be explicit.\n\nRisk: The security evidence flags review-worthy OAuth and sync risks around token storage and Gitee account binding.\n\nMitigation: Avoid Gitee direct OAuth until state validation is fixed; use a trusted broker, a user-controlled OAuth configuration, GitHub device flow, token fallback, or SSH fallback according to the user's risk tolerance.\n\nRisk: Remote synchronization can publish personal memory to the configured Git host if the repository or remote is misconfigured.\n\nMitigation: Require explicit setup or onboard requests, confirm the selected provider and repository before synchronization, keep the memory repository private, and run sync status or doctor before relying on automatic sync.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/cutd/skills/memhub)\n- [README.md](artifact/README.md)\n- [SKILL.md](artifact/SKILL.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with CLI command examples; CLI commands can read or write YAML/Markdown memory files and export chatbot context.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Outputs may reflect user memory from the configured MemHub repository and can trigger local Git commits or remote synchronization only through explicit write or sync commands.]\n\n## Skill Version(s):\n\n0.4.7 (source: server release metadata and SKILL.md frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.4.6: 6 files, 39944 bytes\n\nFiles: README.md (4530b), scripts/memhub.py (108218b), skill-card.md (2336b), SKILL.md (17660b), templates/context-pack.md.j2 (278b), _meta.json (125b)\n\nFile v0.4.6:SKILL.md\n\n---\nname: memhub\nversion: 0.4.6\ndescription: 使用 MemHub Protocol v0.1 管理用户明确指定的跨 Agent 记忆仓库。用于用户明确要求记住、检索、遗忘、导出上下文或配置 Git 同步时；读取可直接执行，持久写入、自动同步、OAuth、remote 修改和仓库创建必须来自当前用户的明确请求。\ntags:\n  - memory\n  - memhub\n  - github\n  - gitee\n  - sync\n  - agent-memory\nlicense: MIT-0\n---\n\n# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让 Agent 能够读取、写入和同步符合 MemHub Protocol v0.1 的记忆仓库。\n\n## 触发场景\n\n使用本 Skill 当：\n\n- 用户说“记住这个”、“帮我记一下”、“以后记得”。\n- 用户问“我的偏好是什么”、“当前项目上下文是什么”。\n- 用户需要把记忆注入到 Gemini/元宝/豆包/Cursor/Claude Code。\n- 会话开始时需要读取用户长期记忆。\n- 用户明确要求在会话结束前保存关键决策、偏好或事实，或已经明确启用了对应自动记忆策略。\n\n## 环境变量\n\n推荐设置（唯一需要的一项）：\n\n```bash\nexport MEMHUB_REPO=/path/to/memhub-data\n```\n\nGitHub 默认使用官方 Device Flow。Gitee OAuth 可使用内置 Broker，但 CLI 会先展示固定\nBroker 域名并要求用户确认；非交互环境必须显式传入可信 Broker 或自己的 OAuth 配置。\n\n可选配置项只写在进程环境或显式 `--env-file` 中，不要写进 Skill、仓库或聊天：\n\n- `MEMHUB_OAUTH_BROKER_URL`：明确选择的通用 Broker；\n- `MEMHUB_GITEE_OAUTH_BROKER_URL`：仅用于 Gitee 的可信 Broker；\n- `MEMHUB_GITHUB_CLIENT_ID`、`MEMHUB_GITEE_CLIENT_ID`：自有 OAuth App client id；\n- `MEMHUB_GITEE_CLIENT_SECRET`：Gitee 直连模式的 client secret；\n- `MEMHUB_GITHUB_TOKEN`、`MEMHUB_GITEE_TOKEN`：token fallback。\n\n必须通过 `--repo` 或 `MEMHUB_REPO` 明确指定专用记忆仓库；CLI 不会把当前目录隐式当作记忆仓库。\n\nCLI 不会自动读取当前目录或 home 目录的通用 `.env`。如确需文件配置，显式传入\n`--env-file /path/to/memhub.env`；只会加载受支持的 `MEMHUB_*` 键。\n\n## 权限与确认边界\n\n- `context`、`search`、`inbox list/show`、`doctor` 是只读操作。\n- `remember`、`forget --apply`、`promote --apply`、`init` 会修改记忆仓库；只有用户当前请求明确要求对应写入时才执行。\n- `sync`、`sync setup`、`onboard` 会访问网络或修改 Git 状态；只有用户当前请求明确要求同步或配置时才执行。\n- `sync setup`/`onboard` 是用户明确发起的同步授权，完成后保留原有节流自动同步；用户可传 `--manual-sync` 关闭。\n- 所有 inbox 引用和 canonical target 都限制在指定 MemHub 仓库内；拒绝绝对路径和 `..` 越界。\n- HTTPS token 只会发送到所选 Provider 的固定官方 Git/API 主机；目标主机不匹配时拒绝执行。\n\n## 命令\n\n本 Skill 提供一个 Python CLI：`scripts/memhub.py`。\n\n```bash\n# 初始化仓库\npython scripts/memhub.py --repo ~/memhub-data init --name dateng --role \"Product Manager\"\n\n# 读取上下文\npython scripts/memhub.py --repo ~/memhub-data context\npython scripts/memhub.py --repo ~/memhub-data context --pack brief\n# 记忆：默认直写 canonical 并本地提交；是否自动推送取决于同步配置\npython scripts/memhub.py --repo ~/memhub-data remember \"用户偏好结构化直接的回答\" --type preference --source agent\npython scripts/memhub.py --repo ~/memhub-data remember \"MemHub 采用 Git-first 架构\" --type decision --project memhub --source agent\n# 低置信/待人工复核的内容才进 inbox 审计缓冲\npython scripts/memhub.py --repo ~/memhub-data remember \"也许该支持 Notion 导出\" --type fact --inbox --source agent\n\n# 检索与遗忘\npython scripts/memhub.py --repo ~/memhub-data search \"Git-first\"\npython scripts/memhub.py --repo ~/memhub-data search \"决策\" --type decision --project memhub\npython scripts/memhub.py --repo ~/memhub-data search \"旧偏好\" --include-archived   # 含已归档\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\"            # 预览\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\" --apply     # 软归档（status=archived）\n\n# 将 inbox 缓冲项归档到 canonical（仅 --inbox 写入的内容才需要）\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote --status all --apply   # 扫全部 inbox 项\n\n# 检查 inbox\npython scripts/memhub.py --repo ~/memhub-data inbox list\npython scripts/memhub.py --repo ~/memhub-data inbox list --status all\npython scripts/memhub.py --repo ~/memhub-data inbox show <filename-or-id-fragment>\n\n# 将 inbox 半自动归档到 canonical memory\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote <filename-or-id-fragment> --apply\n\n# 导出给 chatbot 的上下文\npython scripts/memhub.py --repo ~/memhub-data export chatbot\n\n# 首次接入（推荐）：授权 + 自动判断拉取已有记忆 / 初始化新仓库\npython scripts/memhub.py --repo ~/memhub-data onboard github --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data onboard gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n\n# 同步 GitHub/Gitee（手动分步）\npython scripts/memhub.py --repo ~/memhub-data sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\npython scripts/memhub.py --repo ~/memhub-data sync setup github --auth token --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\npython scripts/memhub.py --repo ~/memhub-data sync status\npython scripts/memhub.py --repo ~/memhub-data sync\n\n# 自检：确认本机/本仓库的自动同步是否就绪（remote/token/merge driver/MEMHUB_REPO 等）\npython scripts/memhub.py --repo ~/memhub-data doctor\n```\n\n## Agent 行为协议\n\n### 上下文 pack 分级\n\n`context --pack` 有四档,逐档累加内容:\n\n- `brief`:用户画像、最重要的偏好、当前项目及最近决策(用于注入 chatbot)。\n- `standard`(默认):brief + 约束、惯例、未完成任务。\n- `project`:聚焦默认/指定项目,决策与任务更全。\n- `full`:standard + knowledge、relations、最近 timeline。\n\n`export chatbot` 默认用 brief;若存在 `.memhub/templates/context-pack.md.j2`,则用该模板渲染(支持 `{{ name }}` 等占位符)。\n\n### 总原则\n\n- `MEMHUB_REPO` 是用户记忆仓库；不要把用户记忆写入代码仓库。\n- GitHub/Gitee remote 只是同步后端；YAML/Markdown 文件仍是可信源数据。\n- 自动写入默认进入 canonical 记忆（本地提交，不自动推送）；低置信或需人工复核的才用 `--inbox`。\n- `sync setup` 会触发授权、创建仓库、修改 remote；**只有用户明确要求配置/切换同步时才执行**。\n- OAuth/token/SSH 凭据、authorization code、client secret、access token 都属于敏感信息；不要在回答中复述。\n\n### 对话开始：读取上下文\n\n**本会话首次涉及记忆时**，先跑一次自检确认自动同步就绪（每个会话只需一次，不要每轮都跑）：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" doctor\n```\n\n- 若 doctor 报 `NOT ready`（有 ✗），说明自动同步未生效。按提示补齐：缺 remote → 提示用户\n  `sync setup`；缺 token（常见于新机器）→ 引导用户重新授权；其余 ✗ 同理。**不要静默忽略**，\n  否则用户会误以为在自动同步，实际没有。\n- 若全绿或只有 `!` 提示，继续正常流程。\n- doctor 是只读的、不联网，开销很小；但仍只需每会话首次跑一次即可。\n\n确认就绪后，直接读取 context。仅当用户已通过 setup/onboard 授权自动同步时，\n`context` 才会按节流阈值从远端拉取最新记忆：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief\n```\n\n- 若距上次拉取超过 `pull_throttle_seconds`，`context` 会自动 `pull --rebase` 再输出。\n- 自动拉取失败时，CLI 会用本地记忆并在 stderr 提示“远端同步失败，当前上下文可能不是最新”，\n  无需中断；如需强制最新，可显式 `sync` 后再读。\n- 将 context 作为可审计上下文，不要当成绝对事实；遇到冲突时优先询问用户。\n\n### 对话中：写入记忆\n\n当用户明确要求记忆，或已经明确启用了对应自动记忆策略时，默认**直写 canonical**：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"内容\" --type fact --source agent\n```\n\n- 直写会按 type 路由到对应 canonical 文件、去重后追加并本地提交；是否自动推送取决于用户在 setup/onboard 时选择的同步模式。\n- 重复内容会被自动跳过。\n- 只有低置信、需人工复核或批量待整理的内容，才加 `--inbox` 进审计缓冲，之后再 `promote`。\n\n类型建议：\n\n- `decision`：明确决策\n- `preference`：稳定偏好\n- `fact`：事实\n- `knowledge`：可复用知识/结论\n- `event`：重要事件\n- `relation`：人物/组织/工具关系\n- `constraint`：约束\n- `convention`：惯例\n\n### 同步：显式配置后自动节流，可选择手动模式\n\n只有用户明确执行 setup/onboard 后才会配置 remote；此后保留原有的节流自动同步。\n若用户传入 `--manual-sync`，则关闭自动 pull/push，只保留显式 `sync`：\n\n- **写入即同步（节流）**：每次 `remember` / `forget --apply` / `promote --apply` 后，CLI 会\n  自动尝试推送。距上次推送不足 `sync.push_throttle_seconds`（默认 3600 秒）时只在本地提交，\n  超过阈值才真正 pull+push。**记忆始终立即落本地，绝不丢失。**\n- **读取即拉取（节流）**：`context` 命令会在 `sync.pull_throttle_seconds`（默认 3600 秒）阈值外\n  自动 `pull --rebase` 拉取其它设备的最新记忆；拉取失败则用本地并在 stderr 提示可能不是最新。\n\n显式 `sync` 命令**忽略节流，立即** pull+push，适合在对话收尾兜底，确保本次所有记忆都已上远端：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync\n```\n\n节流阈值与开关都在 `.memhub/config.yaml` 的 `sync` 段（`auto_push`/`auto_pull` /\n`push_throttle_seconds` / `pull_throttle_seconds`）；节流时间戳记在本机 `.memhub/cache/sync.yaml`\n（git 忽略，每台设备独立）。单次写入若想跳过自动推送，加 `--no-sync`。\n\n`init`/`sync` 会自动注册结构化 merge 驱动（local git config 不随 clone 走，故每台设备首次\n`sync` 会自愈补注册），多设备对同一记忆文件的并发追加可自动合并，不会冲突。\n\n> **换新机器/新 Agent 时**：凭据（token）存在本机 `.memhub/secrets.yaml` 且不随 git 同步，\n> 所以新机器即使 clone 了记忆仓库也需要**重新授权一次**。先跑 `doctor` 自检，按提示补齐\n> remote/token 即可——全绿后自动同步即就绪。\n\n### 检索与遗忘\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" search \"关键词\" --type decision --project memhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" forget \"过时内容\"          # 预览\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" forget \"过时内容\" --apply   # 软归档\n```\n\n- `forget` 默认 dry-run；`--apply` 把命中条目 `status` 置为 `archived`，使其从 context pack\n  消失但保留在 Git 历史中，可审计、可回滚。\n- 纠正一条记忆 = `forget` 旧条目 + `remember` 新条目。\n\n### 首次接入：用 onboard（推荐）\n\n新 agent / 新机器第一次接入时，**用 `onboard` 一条命令完成全流程**，它会自动判断该\n\"拉取已有记忆\"还是\"初始化新仓库\"，避免用默认数据污染你已有的真实记忆：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" onboard gitee --repo-name mymemhub --broker-url https://<trusted-broker>\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" onboard github --repo-name mymemhub\n```\n\nonboard 的流程：\n\n1. 授权（GitHub 默认走官方 Device Flow；Gitee Broker 必须显式指定）。\n2. **探测远端**是否已有 MemHub 记忆仓库（含 `.memhub/config.yaml`）：\n   - **已有** → 以远端为准拉取到本地，**不写入任何默认数据**（你的真实记忆直接到位）；\n   - **为空** → 初始化默认记忆并推送，建立远端仓库。\n3. 注册 merge 驱动，并按用户选择启用节流 auto-sync 或 `--manual-sync`。\n4. 打印 `doctor` 自检结果。\n\n完成 setup/onboard 后，默认维持原有节流自动同步；如果用户选择 `--manual-sync`，则只在\n显式执行 `sync` 时联网。新机器换设备时优先用 `onboard`，不要先 `init` 再 `sync setup`\n（那会先播种默认数据，可能污染远端真实记忆）。\n\n### 同步 setup：手动分步配置（高级）\n\n`onboard` 内部会调用 setup。只有当你想单独配置/切换 remote、且明确知道本地数据状态时，\n才直接用 `sync setup`。当用户说“配置同步”、“连接 GitHub/Gitee”、“换成 Gitee/GitHub 同步”时，\n优先用 `onboard`。\n\nGitHub 默认走官方 Device Flow。Gitee 交互式配置会先展示内置 Broker 域名并请求确认；\n非交互环境必须通过 `--broker-url` 或 `MEMHUB_GITEE_OAUTH_BROKER_URL` 明确指定，\n也可以使用自己的 client secret 直连。\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n```\n\n显式选择 Broker 时的授权流程：\n\n1. CLI 调用 broker 创建授权 session，得到一个 `auth_url`。\n2. CLI 打开（或打印）该 URL；Agent 应把 URL 展示给用户，请用户在浏览器完成授权。\n3. CLI 轮询 broker 直到拿到 access token，自动存入本机 `.memhub/secrets.yaml`（git 忽略）。\n4. 不要要求用户把 access token 发到聊天里。\n\n无浏览器环境：加 `--no-browser`，CLI 会打印 URL 由用户手动打开。\n\n#### 高级 / fallback（仅当用户明确选择时）\n\n- 自建 broker：`--broker-url https://your-broker` 或设 `MEMHUB_OAUTH_BROKER_URL` /\n  `MEMHUB_GITEE_OAUTH_BROKER_URL`。\n- 开发者直连（不经 broker）：Gitee 使用 `MEMHUB_GITEE_CLIENT_SECRET`；\n  GitHub 会回退到 Device Flow。\n- Token / SSH：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth token --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\n```\n\n### 同步失败与冲突处理\n\n- 不要删除本地 `inbox`、canonical 文件或 `.git` 历史。\n- 将错误摘要告诉用户，避免泄露 token/header。\n- 如果 `git pull --rebase` 冲突，停止自动处理，报告冲突文件，让用户/Agent 单独修复。\n- 如果 provider 授权失败，建议用户重新授权或切换 token/SSH fallback。\n- 如果远端仓库创建失败但已存在，可以继续配置 remote 并尝试 sync。\n\n### Inbox 归档（promote）\n\n`remember` 默认直写 canonical，无需 promote。只有用 `--inbox` 缓冲过的低置信/待复核内容\n才需要 promote。整理 inbox 时先预览：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox list\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --dry-run\n```\n\n确认归档目标合理后再执行（默认 dry-run，须显式 `--apply`；已启用 auto-sync 时才按节流自动推送）：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --apply\n```\n\n`promote` 默认只扫 pending 的 inbox 项，可用 `--status all` 扫全部。归档路由规则：\n\n- `decision` → `projects/<project>/decisions.yaml`\n- `preference` → `identity/preferences.yaml`\n- `constraint` → `identity/constraints.yaml`\n- `convention` → `identity/conventions.yaml`\n- `knowledge` → `knowledge/product.yaml`\n- `relation` → `relations/people.yaml`\n- `fact` / `event` → `timeline/YYYY-MM.yaml`\n\n不要写入：\n\n- 临时闲聊\n- 未确认猜测\n- 敏感信息，除非用户明确授权\n- 无新增信息的重复内容\n\n### 对话结束\n\n如果用户明确要求保存重要决策、偏好或事实，或已经明确启用了对应自动记忆策略：\n\n1. `remember` 直写记忆（低置信内容用 `--inbox`，必要时 `promote`）。\n2. 如果用户已明确启用 auto-sync，按节流策略同步；否则只有用户明确要求时才执行 `sync`。\n\n## 发布与安全约束\n\n- 不要把真实 token、client secret、OAuth code 写进 `SKILL.md`、README、示例或提交历史。\n- `.memhub/secrets.yaml` 必须保持本地忽略。\n- 发布到 SkillHub/ClawHub 的包应包含：`SKILL.md`、`README.md`、`scripts/memhub.py`、`templates/context-pack.md.j2`。\n- 发布包不应包含 `__pycache__`、`.pyc`、`.git` 或用户个人记忆数据。\n\n## 重要原则\n\n- MemHub 只负责存取和同步，智能判断由 Agent 完成。\n- 写入必须带 source，便于追溯。\n- 默认直写 canonical 记忆；低置信或需人工复核的内容才进 inbox 审计缓冲。\n- Git 仓库中的 YAML/Markdown 是唯一可信源数据。\n\nFile v0.4.6:README.md\n\n# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让任意支持 Skill 的 Agent 能够读写、归档和同步用户的跨 Agent 统一记忆仓库。\n\n## 能力\n\n- 读取长期记忆上下文：`context --pack brief|standard|full|project`\n- 写入默认 inbox：`remember`\n- 检查与展示 inbox：`inbox list/show`\n- 半自动归档到 canonical memory：`promote --dry-run/--apply`\n- 导出给 chatbot 的上下文：`export chatbot`\n- GitHub/Gitee 同步：OAuth、token fallback、SSH fallback\n\n## 安装到任意支持 Skill 的 Agent\n\n将本目录 `skills/memhub/` 复制到对应 skills 目录，或通过 SkillHub/ClawHub 安装。\n\n## 配置仓库路径\n\n```bash\nexport MEMHUB_REPO=~/memhub-data\n```\n\n必须通过 `--repo` 或 `MEMHUB_REPO` 明确指定专用记忆仓库；CLI 不会把当前目录隐式当作记忆仓库。\n\n## 首次初始化\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" init --name dateng --role \"Product Manager\"\n```\n\n## 配置 GitHub/Gitee 同步\n\n推荐使用 OAuth setup 命令，而不是手动配置 remote。GitHub 默认走官方 Device Flow。\nGitee 交互式配置会先展示内置 Broker 域名并请求确认；非交互环境需明确提供可信 Broker，\n或使用自己的 OAuth 配置。\n\n### GitHub / Gitee 授权\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n```\n\nGitHub 使用 Device Flow。明确选择 Broker 时，流程为：\n\n1. CLI 调 broker 创建授权 session，拿到 `auth_url`；\n2. CLI 打开该 URL，用户在 GitHub/Gitee 页面点击确认授权；\n3. broker 在服务端用 `client_secret` 换取 token；\n4. CLI 轮询 broker 拿到 token，存入本地 `.memhub/secrets.yaml`（git 忽略）。\n\n无浏览器环境加 `--no-browser`，CLI 会打印 URL 供手动打开。\n\n### 高级覆盖 / Fallback\n\n可选配置项：`MEMHUB_OAUTH_BROKER_URL`、`MEMHUB_GITEE_OAUTH_BROKER_URL`、\n`MEMHUB_GITHUB_CLIENT_ID`、`MEMHUB_GITEE_CLIENT_ID`、\n`MEMHUB_GITEE_CLIENT_SECRET`。只放在进程环境或显式 `--env-file` 中，\n不要写进仓库、文档示例或聊天。\n\n### Token / SSH Fallback\n\n```bash\n# Token fallback\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth token --repo-name mymemhub\n\n# SSH fallback\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\n```\n\nOAuth/token 会保存在本地 `.memhub/secrets.yaml`，并被 `.gitignore` 忽略。不要把 OAuth app 的 client secret、token 或 authorization code 提交到仓库。\n\n## 常用命令\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"要记住的内容\" --type fact --source agent\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox list\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox show <filename-or-id-fragment>\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --dry-run\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --apply\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" export chatbot\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync status\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync\n```\n\n## Agent 使用原则\n\n- 读取前：如果任务依赖长期记忆，先 `sync`，再 `context --pack brief`。\n- 写入时：用户明确要求记忆，或形成稳定决策/偏好/事实时，写入 inbox。\n- 写入后：已授权 auto-sync 时由节流逻辑处理；manual-sync 模式只在用户要求时执行 `sync`。\n- 归档时：先 `promote --dry-run`，确认后再 `promote --apply`，然后 `sync`。\n- setup：只有用户明确要求配置或切换同步服务时才执行。\n- 自动同步：用户明确运行 setup/onboard 后默认启用；如只想手动同步，添加 `--manual-sync`。\n- 失败：同步失败时不要删除本地数据；报告错误并保留本地文件。\n\nCLI 不会隐式读取 cwd 或 home 的 `.env`。需要文件配置时使用\n`--env-file /path/to/memhub.env`，且只加载受支持的 `MEMHUB_*` 键。\n\n## 发布包内容\n\n发布到 SkillHub/ClawHub 时应包含：\n\n```text\nSKILL.md\nREADME.md\nscripts/memhub.py\ntemplates/context-pack.md.j2\n```\n\n不应包含：\n\n```text\n__pycache__/\n*.pyc\n.git/\n.memhub/secrets.yaml\n用户个人记忆数据\n```\n\n## License\n\nMIT-0\n\nFile v0.4.6:_meta.json\n\n{\n  \"ownerId\": \"kn7aq20vx0abk37pk7pnq842t1827dq3\",\n  \"slug\": \"memhub\",\n  \"version\": \"0.4.6\",\n  \"publishedAt\": 1790000457624\n}\n\nFile v0.4.6:skill-card.md\n\n## Description:\n\nMemHub manages a user-designated cross-agent memory repository using MemHub Protocol v0.1, with explicit boundaries for reading, writing, forgetting, exporting context, and configuring Git synchronization.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cutd](https://clawhub.ai/user/cutd)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent users use MemHub to read, write, search, archive, export, and synchronize long-term personal memory across agents through a dedicated local Git repository. Persistent writes, automatic sync, OAuth flows, remote changes, and repository creation are intended to run only after explicit user request.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can store durable personal memory, so sensitive facts may persist longer than the user expects.\n\nMitigation: Use a dedicated private memory repository and avoid saving sensitive facts unless the user explicitly wants them remembered.\n\nRisk: OAuth or token-based sync stores credentials locally in .memhub/secrets.yaml.\n\nMitigation: Protect the local secrets file, keep it out of Git, and reauthorize only through trusted GitHub, Gitee, or broker flows.\n\nRisk: Automatic sync can access the network after setup.\n\nMitigation: Use manual sync or a trusted broker when automatic network synchronization is not desired.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/cutd/skills/memhub)\n- [README](artifact/README.md)\n- [Skill definition](artifact/SKILL.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown and CLI text output with inline shell commands and local YAML/Markdown memory files]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Context packs may be brief, standard, project-focused, or full; sync behavior depends on user configuration and explicit authorization.]\n\n## Skill Version(s):\n\n0.4.6 (source: evidence.release.version and SKILL.md frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.4.5: 6 files, 39587 bytes\n\nFiles: README.md (4689b), scripts/memhub.py (107131b), skill-card.md (2111b), SKILL.md (17781b), templates/context-pack.md.j2 (278b), _meta.json (125b)\n\nFile v0.4.5:SKILL.md\n\n---\nname: memhub\nversion: 0.4.5\ndescription: 使用 MemHub Protocol v0.1 管理用户明确指定的跨 Agent 记忆仓库。用于用户明确要求记住、检索、遗忘、导出上下文或配置 Git 同步时；读取可直接执行，持久写入、自动同步、OAuth、remote 修改和仓库创建必须来自当前用户的明确请求。\ntags:\n  - memory\n  - memhub\n  - github\n  - gitee\n  - sync\n  - agent-memory\nlicense: MIT-0\n---\n\n# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让 Agent 能够读取、写入和同步符合 MemHub Protocol v0.1 的记忆仓库。\n\n## 触发场景\n\n使用本 Skill 当：\n\n- 用户说“记住这个”、“帮我记一下”、“以后记得”。\n- 用户问“我的偏好是什么”、“当前项目上下文是什么”。\n- 用户需要把记忆注入到 Gemini/元宝/豆包/Cursor/Claude Code。\n- 会话开始时需要读取用户长期记忆。\n- 用户明确要求在会话结束前保存关键决策、偏好或事实，或已经明确启用了对应自动记忆策略。\n\n## 环境变量\n\n推荐设置（唯一需要的一项）：\n\n```bash\nexport MEMHUB_REPO=/path/to/memhub-data\n```\n\nGitHub 默认使用官方 Device Flow。Gitee OAuth 可使用内置 Broker，但 CLI 会先展示固定\nBroker 域名并要求用户确认；非交互环境必须显式传入可信 Broker 或自己的 OAuth 配置。\n\n```bash\n# 非交互环境中明确选择并信任 OAuth broker\nexport MEMHUB_OAUTH_BROKER_URL=https://<your-broker-host>\nexport MEMHUB_GITEE_OAUTH_BROKER_URL=https://<your-broker-host>   # 仅覆盖 Gitee\n\n# 开发者直连模式（不经 broker，自己保管 Gitee secret）\nexport MEMHUB_GITEE_CLIENT_SECRET=...\n\n# 覆盖内置 OAuth App client id\nexport MEMHUB_GITHUB_CLIENT_ID=...\nexport MEMHUB_GITEE_CLIENT_ID=...\n\n# Token fallback（推荐交互输入或环境变量，不放在命令行）\nexport MEMHUB_GITHUB_TOKEN=...\nexport MEMHUB_GITEE_TOKEN=...\n```\n\n必须通过 `--repo` 或 `MEMHUB_REPO` 明确指定专用记忆仓库；CLI 不会把当前目录隐式当作记忆仓库。\n\nCLI 不会自动读取当前目录或 home 目录的通用 `.env`。如确需文件配置，显式传入\n`--env-file /path/to/memhub.env`；只会加载受支持的 `MEMHUB_*` 键。\n\n## 权限与确认边界\n\n- `context`、`search`、`inbox list/show`、`doctor` 是只读操作。\n- `remember`、`forget --apply`、`promote --apply`、`init` 会修改记忆仓库；只有用户当前请求明确要求对应写入时才执行。\n- `sync`、`sync setup`、`onboard` 会访问网络或修改 Git 状态；只有用户当前请求明确要求同步或配置时才执行。\n- `sync setup`/`onboard` 是用户明确发起的同步授权，完成后保留原有节流自动同步；用户可传 `--manual-sync` 关闭。\n- 所有 inbox 引用和 canonical target 都限制在指定 MemHub 仓库内；拒绝绝对路径和 `..` 越界。\n- HTTPS token 只会发送到所选 Provider 的固定官方 Git/API 主机；目标主机不匹配时拒绝执行。\n\n## 命令\n\n本 Skill 提供一个 Python CLI：`scripts/memhub.py`。\n\n```bash\n# 初始化仓库\npython scripts/memhub.py --repo ~/memhub-data init --name dateng --role \"Product Manager\"\n\n# 读取上下文\npython scripts/memhub.py --repo ~/memhub-data context\npython scripts/memhub.py --repo ~/memhub-data context --pack brief\n# 记忆：默认直写 canonical 并本地提交；是否自动推送取决于同步配置\npython scripts/memhub.py --repo ~/memhub-data remember \"用户偏好结构化直接的回答\" --type preference --source agent\npython scripts/memhub.py --repo ~/memhub-data remember \"MemHub 采用 Git-first 架构\" --type decision --project memhub --source agent\n# 低置信/待人工复核的内容才进 inbox 审计缓冲\npython scripts/memhub.py --repo ~/memhub-data remember \"也许该支持 Notion 导出\" --type fact --inbox --source agent\n\n# 检索与遗忘\npython scripts/memhub.py --repo ~/memhub-data search \"Git-first\"\npython scripts/memhub.py --repo ~/memhub-data search \"决策\" --type decision --project memhub\npython scripts/memhub.py --repo ~/memhub-data search \"旧偏好\" --include-archived   # 含已归档\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\"            # 预览\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\" --apply     # 软归档（status=archived）\n\n# 将 inbox 缓冲项归档到 canonical（仅 --inbox 写入的内容才需要）\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote --status all --apply   # 扫全部 inbox 项\n\n# 检查 inbox\npython scripts/memhub.py --repo ~/memhub-data inbox list\npython scripts/memhub.py --repo ~/memhub-data inbox list --status all\npython scripts/memhub.py --repo ~/memhub-data inbox show <filename-or-id-fragment>\n\n# 将 inbox 半自动归档到 canonical memory\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote <filename-or-id-fragment> --apply\n\n# 导出给 chatbot 的上下文\npython scripts/memhub.py --repo ~/memhub-data export chatbot\n\n# 首次接入（推荐）：授权 + 自动判断拉取已有记忆 / 初始化新仓库\npython scripts/memhub.py --repo ~/memhub-data onboard github --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data onboard gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n\n# 同步 GitHub/Gitee（手动分步）\npython scripts/memhub.py --repo ~/memhub-data sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\npython scripts/memhub.py --repo ~/memhub-data sync setup github --auth token --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\npython scripts/memhub.py --repo ~/memhub-data sync status\npython scripts/memhub.py --repo ~/memhub-data sync\n\n# 自检：确认本机/本仓库的自动同步是否就绪（remote/token/merge driver/MEMHUB_REPO 等）\npython scripts/memhub.py --repo ~/memhub-data doctor\n```\n\n## Agent 行为协议\n\n### 上下文 pack 分级\n\n`context --pack` 有四档,逐档累加内容:\n\n- `brief`:用户画像、最重要的偏好、当前项目及最近决策(用于注入 chatbot)。\n- `standard`(默认):brief + 约束、惯例、未完成任务。\n- `project`:聚焦默认/指定项目,决策与任务更全。\n- `full`:standard + knowledge、relations、最近 timeline。\n\n`export chatbot` 默认用 brief;若存在 `.memhub/templates/context-pack.md.j2`,则用该模板渲染(支持 `{{ name }}` 等占位符)。\n\n### 总原则\n\n- `MEMHUB_REPO` 是用户记忆仓库；不要把用户记忆写入代码仓库。\n- GitHub/Gitee remote 只是同步后端；YAML/Markdown 文件仍是可信源数据。\n- 自动写入默认进入 canonical 记忆（本地提交，不自动推送）；低置信或需人工复核的才用 `--inbox`。\n- `sync setup` 会触发授权、创建仓库、修改 remote；**只有用户明确要求配置/切换同步时才执行**。\n- OAuth/token/SSH 凭据、authorization code、client secret、access token 都属于敏感信息；不要在回答中复述。\n\n### 对话开始：读取上下文\n\n**本会话首次涉及记忆时**，先跑一次自检确认自动同步就绪（每个会话只需一次，不要每轮都跑）：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" doctor\n```\n\n- 若 doctor 报 `NOT ready`（有 ✗），说明自动同步未生效。按提示补齐：缺 remote → 提示用户\n  `sync setup`；缺 token（常见于新机器）→ 引导用户重新授权；其余 ✗ 同理。**不要静默忽略**，\n  否则用户会误以为在自动同步，实际没有。\n- 若全绿或只有 `!` 提示，继续正常流程。\n- doctor 是只读的、不联网，开销很小；但仍只需每会话首次跑一次即可。\n\n确认就绪后，直接读取 context。仅当用户已通过 setup/onboard 授权自动同步时，\n`context` 才会按节流阈值从远端拉取最新记忆：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief\n```\n\n- 若距上次拉取超过 `pull_throttle_seconds`，`context` 会自动 `pull --rebase` 再输出。\n- 自动拉取失败时，CLI 会用本地记忆并在 stderr 提示“远端同步失败，当前上下文可能不是最新”，\n  无需中断；如需强制最新，可显式 `sync` 后再读。\n- 将 context 作为可审计上下文，不要当成绝对事实；遇到冲突时优先询问用户。\n\n### 对话中：写入记忆\n\n当用户明确要求记忆，或已经明确启用了对应自动记忆策略时，默认**直写 canonical**：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"内容\" --type fact --source agent\n```\n\n- 直写会按 type 路由到对应 canonical 文件、去重后追加并本地提交；是否自动推送取决于用户在 setup/onboard 时选择的同步模式。\n- 重复内容会被自动跳过。\n- 只有低置信、需人工复核或批量待整理的内容，才加 `--inbox` 进审计缓冲，之后再 `promote`。\n\n类型建议：\n\n- `decision`：明确决策\n- `preference`：稳定偏好\n- `fact`：事实\n- `knowledge`：可复用知识/结论\n- `event`：重要事件\n- `relation`：人物/组织/工具关系\n- `constraint`：约束\n- `convention`：惯例\n\n### 同步：显式配置后自动节流，可选择手动模式\n\n只有用户明确执行 setup/onboard 后才会配置 remote；此后保留原有的节流自动同步。\n若用户传入 `--manual-sync`，则关闭自动 pull/push，只保留显式 `sync`：\n\n- **写入即同步（节流）**：每次 `remember` / `forget --apply` / `promote --apply` 后，CLI 会\n  自动尝试推送。距上次推送不足 `sync.push_throttle_seconds`（默认 3600 秒）时只在本地提交，\n  超过阈值才真正 pull+push。**记忆始终立即落本地，绝不丢失。**\n- **读取即拉取（节流）**：`context` 命令会在 `sync.pull_throttle_seconds`（默认 3600 秒）阈值外\n  自动 `pull --rebase` 拉取其它设备的最新记忆；拉取失败则用本地并在 stderr 提示可能不是最新。\n\n显式 `sync` 命令**忽略节流，立即** pull+push，适合在对话收尾兜底，确保本次所有记忆都已上远端：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync\n```\n\n节流阈值与开关都在 `.memhub/config.yaml` 的 `sync` 段（`auto_push`/`auto_pull` /\n`push_throttle_seconds` / `pull_throttle_seconds`）；节流时间戳记在本机 `.memhub/cache/sync.yaml`\n（git 忽略，每台设备独立）。单次写入若想跳过自动推送，加 `--no-sync`。\n\n`init`/`sync` 会自动注册结构化 merge 驱动（local git config 不随 clone 走，故每台设备首次\n`sync` 会自愈补注册），多设备对同一记忆文件的并发追加可自动合并，不会冲突。\n\n> **换新机器/新 Agent 时**：凭据（token）存在本机 `.memhub/secrets.yaml` 且不随 git 同步，\n> 所以新机器即使 clone 了记忆仓库也需要**重新授权一次**。先跑 `doctor` 自检，按提示补齐\n> remote/token 即可——全绿后自动同步即就绪。\n\n### 检索与遗忘\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" search \"关键词\" --type decision --project memhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" forget \"过时内容\"          # 预览\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" forget \"过时内容\" --apply   # 软归档\n```\n\n- `forget` 默认 dry-run；`--apply` 把命中条目 `status` 置为 `archived`，使其从 context pack\n  消失但保留在 Git 历史中，可审计、可回滚。\n- 纠正一条记忆 = `forget` 旧条目 + `remember` 新条目。\n\n### 首次接入：用 onboard（推荐）\n\n新 agent / 新机器第一次接入时，**用 `onboard` 一条命令完成全流程**，它会自动判断该\n\"拉取已有记忆\"还是\"初始化新仓库\"，避免用默认数据污染你已有的真实记忆：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" onboard gitee --repo-name mymemhub --broker-url https://<trusted-broker>\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" onboard github --repo-name mymemhub\n```\n\nonboard 的流程：\n\n1. 授权（GitHub 默认走官方 Device Flow；Gitee Broker 必须显式指定）。\n2. **探测远端**是否已有 MemHub 记忆仓库（含 `.memhub/config.yaml`）：\n   - **已有** → 以远端为准拉取到本地，**不写入任何默认数据**（你的真实记忆直接到位）；\n   - **为空** → 初始化默认记忆并推送，建立远端仓库。\n3. 注册 merge 驱动，并按用户选择启用节流 auto-sync 或 `--manual-sync`。\n4. 打印 `doctor` 自检结果。\n\n完成 setup/onboard 后，默认维持原有节流自动同步；如果用户选择 `--manual-sync`，则只在\n显式执行 `sync` 时联网。新机器换设备时优先用 `onboard`，不要先 `init` 再 `sync setup`\n（那会先播种默认数据，可能污染远端真实记忆）。\n\n### 同步 setup：手动分步配置（高级）\n\n`onboard` 内部会调用 setup。只有当你想单独配置/切换 remote、且明确知道本地数据状态时，\n才直接用 `sync setup`。当用户说“配置同步”、“连接 GitHub/Gitee”、“换成 Gitee/GitHub 同步”时，\n优先用 `onboard`。\n\nGitHub 默认走官方 Device Flow。Gitee 交互式配置会先展示内置 Broker 域名并请求确认；\n非交互环境必须通过 `--broker-url` 或 `MEMHUB_GITEE_OAUTH_BROKER_URL` 明确指定，\n也可以使用自己的 client secret 直连。\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n```\n\n显式选择 Broker 时的授权流程：\n\n1. CLI 调用 broker 创建授权 session，得到一个 `auth_url`。\n2. CLI 打开（或打印）该 URL；Agent 应把 URL 展示给用户，请用户在浏览器完成授权。\n3. CLI 轮询 broker 直到拿到 access token，自动存入本机 `.memhub/secrets.yaml`（git 忽略）。\n4. 不要要求用户把 access token 发到聊天里。\n\n无浏览器环境：加 `--no-browser`，CLI 会打印 URL 由用户手动打开。\n\n#### 高级 / fallback（仅当用户明确选择时）\n\n- 自建 broker：`--broker-url https://your-broker` 或设 `MEMHUB_OAUTH_BROKER_URL` /\n  `MEMHUB_GITEE_OAUTH_BROKER_URL`。\n- 开发者直连（不经 broker）：Gitee 用 `--client-secret`（或 `MEMHUB_GITEE_CLIENT_SECRET`）；\n  GitHub 会回退到 Device Flow。\n- Token / SSH：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth token --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\n```\n\n### 同步失败与冲突处理\n\n- 不要删除本地 `inbox`、canonical 文件或 `.git` 历史。\n- 将错误摘要告诉用户，避免泄露 token/header。\n- 如果 `git pull --rebase` 冲突，停止自动处理，报告冲突文件，让用户/Agent 单独修复。\n- 如果 provider 授权失败，建议用户重新授权或切换 token/SSH fallback。\n- 如果远端仓库创建失败但已存在，可以继续配置 remote 并尝试 sync。\n\n### Inbox 归档（promote）\n\n`remember` 默认直写 canonical，无需 promote。只有用 `--inbox` 缓冲过的低置信/待复核内容\n才需要 promote。整理 inbox 时先预览：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox list\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --dry-run\n```\n\n确认归档目标合理后再执行（默认 dry-run，须显式 `--apply`；已启用 auto-sync 时才按节流自动推送）：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --apply\n```\n\n`promote` 默认只扫 pending 的 inbox 项，可用 `--status all` 扫全部。归档路由规则：\n\n- `decision` → `projects/<project>/decisions.yaml`\n- `preference` → `identity/preferences.yaml`\n- `constraint` → `identity/constraints.yaml`\n- `convention` → `identity/conventions.yaml`\n- `knowledge` → `knowledge/product.yaml`\n- `relation` → `relations/people.yaml`\n- `fact` / `event` → `timeline/YYYY-MM.yaml`\n\n不要写入：\n\n- 临时闲聊\n- 未确认猜测\n- 敏感信息，除非用户明确授权\n- 无新增信息的重复内容\n\n### 对话结束\n\n如果用户明确要求保存重要决策、偏好或事实，或已经明确启用了对应自动记忆策略：\n\n1. `remember` 直写记忆（低置信内容用 `--inbox`，必要时 `promote`）。\n2. 如果用户已明确启用 auto-sync，按节流策略同步；否则只有用户明确要求时才执行 `sync`。\n\n## 发布与安全约束\n\n- 不要把真实 token、client secret、OAuth code 写进 `SKILL.md`、README、示例或提交历史。\n- `.memhub/secrets.yaml` 必须保持本地忽略。\n- 发布到 SkillHub/ClawHub 的包应包含：`SKILL.md`、`README.md`、`scripts/memhub.py`、`templates/context-pack.md.j2`。\n- 发布包不应包含 `__pycache__`、`.pyc`、`.git` 或用户个人记忆数据。\n\n## 重要原则\n\n- MemHub 只负责存取和同步，智能判断由 Agent 完成。\n- 写入必须带 source，便于追溯。\n- 默认直写 canonical 记忆；低置信或需人工复核的内容才进 inbox 审计缓冲。\n- Git 仓库中的 YAML/Markdown 是唯一可信源数据。\n\nFile v0.4.5:README.md\n\n# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让任意支持 Skill 的 Agent 能够读写、归档和同步用户的跨 Agent 统一记忆仓库。\n\n## 能力\n\n- 读取长期记忆上下文：`context --pack brief|standard|full|project`\n- 写入默认 inbox：`remember`\n- 检查与展示 inbox：`inbox list/show`\n- 半自动归档到 canonical memory：`promote --dry-run/--apply`\n- 导出给 chatbot 的上下文：`export chatbot`\n- GitHub/Gitee 同步：OAuth、token fallback、SSH fallback\n\n## 安装到任意支持 Skill 的 Agent\n\n将本目录 `skills/memhub/` 复制到对应 skills 目录，或通过 SkillHub/ClawHub 安装。\n\n## 配置仓库路径\n\n```bash\nexport MEMHUB_REPO=~/memhub-data\n```\n\n必须通过 `--repo` 或 `MEMHUB_REPO` 明确指定专用记忆仓库；CLI 不会把当前目录隐式当作记忆仓库。\n\n## 首次初始化\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" init --name dateng --role \"Product Manager\"\n```\n\n## 配置 GitHub/Gitee 同步\n\n推荐使用 OAuth setup 命令，而不是手动配置 remote。GitHub 默认走官方 Device Flow。\nGitee 交互式配置会先展示内置 Broker 域名并请求确认；非交互环境需明确提供可信 Broker，\n或使用自己的 OAuth 配置。\n\n### GitHub / Gitee 授权\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n```\n\nGitHub 使用 Device Flow。明确选择 Broker 时，流程为：\n\n1. CLI 调 broker 创建授权 session，拿到 `auth_url`；\n2. CLI 打开该 URL，用户在 GitHub/Gitee 页面点击确认授权；\n3. broker 在服务端用 `client_secret` 换取 token；\n4. CLI 轮询 broker 拿到 token，存入本地 `.memhub/secrets.yaml`（git 忽略）。\n\n无浏览器环境加 `--no-browser`，CLI 会打印 URL 供手动打开。\n\n### 高级覆盖 / Fallback\n\n```bash\n# 非交互环境中明确选择并信任 broker\nexport MEMHUB_OAUTH_BROKER_URL=https://<your-broker-host>\n# 覆盖内置 OAuth App client id\nexport MEMHUB_GITHUB_CLIENT_ID=<github-oauth-app-client-id>\nexport MEMHUB_GITEE_CLIENT_ID=<gitee-oauth-app-client-id>\n# 开发者直连（不经 broker，自己保管 Gitee secret，勿提交到仓库）\nexport MEMHUB_GITEE_CLIENT_SECRET=<gitee-oauth-app-client-secret>\n```\n\n### Token / SSH Fallback\n\n```bash\n# Token fallback\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth token --repo-name mymemhub\n\n# SSH fallback\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\n```\n\nOAuth/token 会保存在本地 `.memhub/secrets.yaml`，并被 `.gitignore` 忽略。不要把 OAuth app 的 client secret、token 或 authorization code 提交到仓库。\n\n## 常用命令\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"要记住的内容\" --type fact --source agent\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox list\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox show <filename-or-id-fragment>\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --dry-run\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --apply\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" export chatbot\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync status\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync\n```\n\n## Agent 使用原则\n\n- 读取前：如果任务依赖长期记忆，先 `sync`，再 `context --pack brief`。\n- 写入时：用户明确要求记忆，或形成稳定决策/偏好/事实时，写入 inbox。\n- 写入后：已授权 auto-sync 时由节流逻辑处理；manual-sync 模式只在用户要求时执行 `sync`。\n- 归档时：先 `promote --dry-run`，确认后再 `promote --apply`，然后 `sync`。\n- setup：只有用户明确要求配置或切换同步服务时才执行。\n- 自动同步：用户明确运行 setup/onboard 后默认启用；如只想手动同步，添加 `--manual-sync`。\n- 失败：同步失败时不要删除本地数据；报告错误并保留本地文件。\n\nCLI 不会隐式读取 cwd 或 home 的 `.env`。需要文件配置时使用\n`--env-file /path/to/memhub.env`，且只加载受支持的 `MEMHUB_*` 键。\n\n## 发布包内容\n\n发布到 SkillHub/ClawHub 时应包含：\n\n```text\nSKILL.md\nREADME.md\nscripts/memhub.py\ntemplates/context-pack.md.j2\n```\n\n不应包含：\n\n```text\n__pycache__/\n*.pyc\n.git/\n.memhub/secrets.yaml\n用户个人记忆数据\n```\n\n## License\n\nMIT-0\n\nFile v0.4.5:_meta.json\n\n{\n  \"ownerId\": \"kn7aq20vx0abk37pk7pnq842t1827dq3\",\n  \"slug\": \"memhub\",\n  \"version\": \"0.4.5\",\n  \"publishedAt\": 1789999458780\n}\n\nFile v0.4.5:skill-card.md\n\n## Description:\n\nMemHub manages an explicitly selected cross-agent memory repository using MemHub Protocol v0.1; reads are allowed directly, while persistent writes, automatic sync, OAuth, remote changes, and repository creation require the user's explicit current request.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cutd](https://clawhub.ai/user/cutd)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent users use MemHub to read, write, archive, export, and synchronize a personal cross-agent memory repository, including context packs for chatbots and GitHub/Gitee sync when explicitly authorized.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: OAuth tokens could be committed and pushed if the local MemHub secret file is already tracked by Git.\n\nMitigation: Before authorizing sync, confirm .memhub/secrets.yaml is not tracked, use a dedicated private MemHub repository, and revoke tokens if they may have been committed.\n\nRisk: GitHub/Gitee sync can expose memory data to remote collaborators or shared remotes.\n\nMitigation: Avoid shared remotes unless all collaborators are trusted, and use manual sync when tighter control over network operations is required.\n\n## Reference(s):\n\n- [MemHub ClawHub Skill Page](https://clawhub.ai/cutd/skills/memhub)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown context packs, plain-text CLI output, YAML files, and shell command guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Reads and writes an explicit MEMHUB_REPO memory repository; sync operations may use GitHub or Gitee credentials only after user authorization.]\n\n## Skill Version(s):\n\n0.4.5 (source: frontmatter and server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.4.4: 6 files, 38477 bytes\n\nFiles: README.md (4287b), scripts/memhub.py (103385b), skill-card.md (2805b), SKILL.md (16282b), templates/context-pack.md.j2 (278b), _meta.json (125b)\n\nFile v0.4.4:SKILL.md\n\n---\nname: memhub\nversion: 0.4.4\ndescription: 使用 MemHub Protocol v0.1 读写用户的跨 Agent 统一记忆仓库。当用户要求记住信息、检索/遗忘记忆、读取个人/项目上下文、生成 chatbot 注入文本、同步 Git 记忆仓库时使用。\ntags:\n  - memory\n  - memhub\n  - github\n  - gitee\n  - sync\n  - agent-memory\nlicense: MIT-0\n---\n\n# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让 Agent 能够读取、写入和同步符合 MemHub Protocol v0.1 的记忆仓库。\n\n## 触发场景\n\n使用本 Skill 当：\n\n- 用户说“记住这个”、“帮我记一下”、“以后记得”。\n- 用户问“我的偏好是什么”、“当前项目上下文是什么”。\n- 用户需要把记忆注入到 Gemini/元宝/豆包/Cursor/Claude Code。\n- 会话开始时需要读取用户长期记忆。\n- 会话结束时需要把关键决策/偏好/事实写入记忆并同步。\n\n## 环境变量\n\n推荐设置（唯一需要的一项）：\n\n```bash\nexport MEMHUB_REPO=/path/to/memhub-data\n```\n\nOAuth 同步**开箱即用**：GitHub 和 Gitee 都默认走内置的 MemHub Auth Broker，\n普通用户无需设置任何 OAuth 相关环境变量。以下全部为可选的高级覆盖：\n\n```bash\n# 覆盖内置 broker（自建 broker 时）\nexport MEMHUB_OAUTH_BROKER_URL=https://<your-broker-host>\nexport MEMHUB_GITEE_OAUTH_BROKER_URL=https://<your-broker-host>   # 仅覆盖 Gitee\n\n# 开发者直连模式（不经 broker，自己保管 Gitee secret）\nexport MEMHUB_GITEE_CLIENT_SECRET=...\n\n# 覆盖内置 OAuth App client id\nexport MEMHUB_GITHUB_CLIENT_ID=...\nexport MEMHUB_GITEE_CLIENT_ID=...\n\n# Token fallback\nexport MEMHUB_GITHUB_TOKEN=...\nexport MEMHUB_GITEE_TOKEN=...\n```\n\n如果未设置 `MEMHUB_REPO`，脚本默认使用当前工作目录下的 `./memhub-data`。\n\nCLI 会自动读取当前目录 `.env` 和用户 home 目录 `.env`，且不会覆盖已经存在的进程环境变量。不要把 `.env` 提交到 Git。\n\n## 命令\n\n本 Skill 提供一个 Python CLI：`scripts/memhub.py`。\n\n```bash\n# 初始化仓库\npython scripts/memhub.py --repo ~/memhub-data init --name dateng --role \"Product Manager\"\n\n# 读取上下文\npython scripts/memhub.py --repo ~/memhub-data context\npython scripts/memhub.py --repo ~/memhub-data context --pack brief\n# 记忆：默认直写 canonical 并本地提交（不自动推送）\npython scripts/memhub.py --repo ~/memhub-data remember \"用户偏好结构化直接的回答\" --type preference --source agent\npython scripts/memhub.py --repo ~/memhub-data remember \"MemHub 采用 Git-first 架构\" --type decision --project memhub --source agent\n# 低置信/待人工复核的内容才进 inbox 审计缓冲\npython scripts/memhub.py --repo ~/memhub-data remember \"也许该支持 Notion 导出\" --type fact --inbox --source agent\n\n# 检索与遗忘\npython scripts/memhub.py --repo ~/memhub-data search \"Git-first\"\npython scripts/memhub.py --repo ~/memhub-data search \"决策\" --type decision --project memhub\npython scripts/memhub.py --repo ~/memhub-data search \"旧偏好\" --include-archived   # 含已归档\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\"            # 预览\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\" --apply     # 软归档（status=archived）\n\n# 将 inbox 缓冲项归档到 canonical（仅 --inbox 写入的内容才需要）\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote --status all --apply   # 扫全部 inbox 项\n\n# 检查 inbox\npython scripts/memhub.py --repo ~/memhub-data inbox list\npython scripts/memhub.py --repo ~/memhub-data inbox list --status all\npython scripts/memhub.py --repo ~/memhub-data inbox show <filename-or-id-fragment>\n\n# 将 inbox 半自动归档到 canonical memory\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote <filename-or-id-fragment> --apply\n\n# 导出给 chatbot 的上下文\npython scripts/memhub.py --repo ~/memhub-data export chatbot\n\n# 首次接入（推荐）：授权 + 自动判断拉取已有记忆 / 初始化新仓库\npython scripts/memhub.py --repo ~/memhub-data onboard github --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data onboard gitee  --repo-name mymemhub\n\n# 同步 GitHub/Gitee（手动分步；默认 OAuth 走内置 broker）\npython scripts/memhub.py --repo ~/memhub-data sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup gitee --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup github --auth token --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\npython scripts/memhub.py --repo ~/memhub-data sync status\npython scripts/memhub.py --repo ~/memhub-data sync\n\n# 自检：确认本机/本仓库的自动同步是否就绪（remote/token/merge driver/MEMHUB_REPO 等）\npython scripts/memhub.py --repo ~/memhub-data doctor\n```\n\n## Agent 行为协议\n\n### 上下文 pack 分级\n\n`context --pack` 有四档,逐档累加内容:\n\n- `brief`:用户画像、最重要的偏好、当前项目及最近决策(用于注入 chatbot)。\n- `standard`(默认):brief + 约束、惯例、未完成任务。\n- `project`:聚焦默认/指定项目,决策与任务更全。\n- `full`:standard + knowledge、relations、最近 timeline。\n\n`export chatbot` 默认用 brief;若存在 `.memhub/templates/context-pack.md.j2`,则用该模板渲染(支持 `{{ name }}` 等占位符)。\n\n### 总原则\n\n- `MEMHUB_REPO` 是用户记忆仓库；不要把用户记忆写入代码仓库。\n- GitHub/Gitee remote 只是同步后端；YAML/Markdown 文件仍是可信源数据。\n- 自动写入默认进入 canonical 记忆（本地提交，不自动推送）；低置信或需人工复核的才用 `--inbox`。\n- `sync setup` 会触发授权、创建仓库、修改 remote；**只有用户明确要求配置/切换同步时才执行**。\n- OAuth/token/SSH 凭据、authorization code、client secret、access token 都属于敏感信息；不要在回答中复述。\n\n### 对话开始：读取上下文\n\n**本会话首次涉及记忆时**，先跑一次自检确认自动同步就绪（每个会话只需一次，不要每轮都跑）：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" doctor\n```\n\n- 若 doctor 报 `NOT ready`（有 ✗），说明自动同步未生效。按提示补齐：缺 remote → 提示用户\n  `sync setup`；缺 token（常见于新机器）→ 引导用户重新授权；其余 ✗ 同理。**不要静默忽略**，\n  否则用户会误以为在自动同步，实际没有。\n- 若全绿或只有 `!` 提示，继续正常流程。\n- doctor 是只读的、不联网，开销很小；但仍只需每会话首次跑一次即可。\n\n确认就绪后，直接读取 context——`context` 会按节流阈值**自动从远端拉取**最新记忆，通常无需先手动 `sync`：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief\n```\n\n- 若距上次拉取超过 `pull_throttle_seconds`，`context` 会自动 `pull --rebase` 再输出。\n- 自动拉取失败时，CLI 会用本地记忆并在 stderr 提示“远端同步失败，当前上下文可能不是最新”，\n  无需中断；如需强制最新，可显式 `sync` 后再读。\n- 将 context 作为可审计上下文，不要当成绝对事实；遇到冲突时优先询问用户。\n\n### 对话中：写入记忆\n\n当用户明确要求记忆，或对话中形成稳定偏好/决策/事实时，默认**直写 canonical**：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"内容\" --type fact --source agent\n```\n\n- 直写会按 type 路由到对应 canonical 文件、去重后追加，并**本地提交但不自动推送**。\n- 重复内容会被自动跳过。\n- 只有低置信、需人工复核或批量待整理的内容，才加 `--inbox` 进审计缓冲，之后再 `promote`。\n\n类型建议：\n\n- `decision`：明确决策\n- `preference`：稳定偏好\n- `fact`：事实\n- `knowledge`：可复用知识/结论\n- `event`：重要事件\n- `relation`：人物/组织/工具关系\n- `constraint`：约束\n- `convention`：惯例\n\n### 同步：自动节流，无需每次手动 sync\n\n配置了 remote 后，同步是**自动**的，Agent 通常无需显式调用 `sync`：\n\n- **写入即同步（节流）**：每次 `remember` / `forget --apply` / `promote --apply` 后，CLI 会\n  自动尝试推送。距上次推送不足 `sync.push_throttle_seconds`（默认 3600 秒）时只在本地提交，\n  超过阈值才真正 pull+push。**记忆始终立即落本地，绝不丢失。**\n- **读取即拉取（节流）**：`context` 命令会在 `sync.pull_throttle_seconds`（默认 3600 秒）阈值外\n  自动 `pull --rebase` 拉取其它设备的最新记忆；拉取失败则用本地并在 stderr 提示可能不是最新。\n\n显式 `sync` 命令**忽略节流，立即** pull+push，适合在对话收尾兜底，确保本次所有记忆都已上远端：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync\n```\n\n节流阈值与开关都在 `.memhub/config.yaml` 的 `sync` 段（`auto_push`/`auto_pull` /\n`push_throttle_seconds` / `pull_throttle_seconds`）；节流时间戳记在本机 `.memhub/cache/sync.yaml`\n（git 忽略，每台设备独立）。单次写入若想跳过自动推送，加 `--no-sync`。\n\n`init`/`sync` 会自动注册结构化 merge 驱动（local git config 不随 clone 走，故每台设备首次\n`sync` 会自愈补注册），多设备对同一记忆文件的并发追加可自动合并，不会冲突。\n\n> **换新机器/新 Agent 时**：凭据（token）存在本机 `.memhub/secrets.yaml` 且不随 git 同步，\n> 所以新机器即使 clone 了记忆仓库也需要**重新授权一次**。先跑 `doctor` 自检，按提示补齐\n> remote/token 即可——全绿后自动同步即就绪。\n\n### 检索与遗忘\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" search \"关键词\" --type decision --project memhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" forget \"过时内容\"          # 预览\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" forget \"过时内容\" --apply   # 软归档\n```\n\n- `forget` 默认 dry-run；`--apply` 把命中条目 `status` 置为 `archived`，使其从 context pack\n  消失但保留在 Git 历史中，可审计、可回滚。\n- 纠正一条记忆 = `forget` 旧条目 + `remember` 新条目。\n\n### 首次接入：用 onboard（推荐）\n\n新 agent / 新机器第一次接入时，**用 `onboard` 一条命令完成全流程**，它会自动判断该\n\"拉取已有记忆\"还是\"初始化新仓库\"，避免用默认数据污染你已有的真实记忆：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" onboard gitee --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" onboard github --repo-name mymemhub\n```\n\nonboard 的流程：\n\n1. 授权（默认走内置 broker，见下）。\n2. **探测远端**是否已有 MemHub 记忆仓库（含 `.memhub/config.yaml`）：\n   - **已有** → 以远端为准拉取到本地，**不写入任何默认数据**（你的真实记忆直接到位）；\n   - **为空** → 初始化默认记忆并推送，建立远端仓库。\n3. 注册 merge 驱动、确保 auto-sync 就绪。\n4. 打印 `doctor` 自检结果。\n\n之后写入即自动推送、读取即自动拉取，无需再手动 sync。新机器换设备时**总是优先用\nonboard**，不要先 `init` 再 `sync setup`（那会先播种默认数据，可能污染远端真实记忆）。\n\n### 同步 setup：手动分步配置（高级）\n\n`onboard` 内部会调用 setup。只有当你想单独配置/切换 remote、且明确知道本地数据状态时，\n才直接用 `sync setup`。当用户说“配置同步”、“连接 GitHub/Gitee”、“换成 Gitee/GitHub 同步”时，\n优先用 `onboard`。\n\n**开箱即用**：GitHub 和 Gitee 都默认走内置的 MemHub Auth Broker（`https://oauth.1024hub.cn`），\nclient_secret 保管在 broker 服务端，**用户无需设置任何环境变量或自建 OAuth 应用**。\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup gitee  --repo-name mymemhub\n```\n\n授权流程（两者一致）：\n\n1. CLI 调用 broker 创建授权 session，得到一个 `auth_url`。\n2. CLI 打开（或打印）该 URL；Agent 应把 URL 展示给用户，请用户在浏览器完成授权。\n3. CLI 轮询 broker 直到拿到 access token，自动存入本机 `.memhub/secrets.yaml`（git 忽略）。\n4. 不要要求用户把 access token 发到聊天里。\n\n无浏览器环境：加 `--no-browser`，CLI 会打印 URL 由用户手动打开。\n\n#### 高级 / fallback（仅当用户明确选择时）\n\n- 自建 broker：`--broker-url https://your-broker` 或设 `MEMHUB_OAUTH_BROKER_URL` /\n  `MEMHUB_GITEE_OAUTH_BROKER_URL`。\n- 开发者直连（不经 broker）：Gitee 用 `--client-secret`（或 `MEMHUB_GITEE_CLIENT_SECRET`）；\n  GitHub 会回退到 Device Flow。\n- Token / SSH：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth token --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\n```\n\n### 同步失败与冲突处理\n\n- 不要删除本地 `inbox`、canonical 文件或 `.git` 历史。\n- 将错误摘要告诉用户，避免泄露 token/header。\n- 如果 `git pull --rebase` 冲突，停止自动处理，报告冲突文件，让用户/Agent 单独修复。\n- 如果 provider 授权失败，建议用户重新授权或切换 token/SSH fallback。\n- 如果远端仓库创建失败但已存在，可以继续配置 remote 并尝试 sync。\n\n### Inbox 归档（promote）\n\n`remember` 默认直写 canonical，无需 promote。只有用 `--inbox` 缓冲过的低置信/待复核内容\n才需要 promote。整理 inbox 时先预览：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox list\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --dry-run\n```\n\n确认归档目标合理后再执行（默认 dry-run，须显式 `--apply`；`--apply` 后按节流自动推送）：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --apply\n```\n\n`promote` 默认只扫 pending 的 inbox 项，可用 `--status all` 扫全部。归档路由规则：\n\n- `decision` → `projects/<project>/decisions.yaml`\n- `preference` → `identity/preferences.yaml`\n- `constraint` → `identity/constraints.yaml`\n- `convention` → `identity/conventions.yaml`\n- `knowledge` → `knowledge/product.yaml`\n- `relation` → `relations/people.yaml`\n- `fact` / `event` → `timeline/YYYY-MM.yaml`\n\n不要写入：\n\n- 临时闲聊\n- 未确认猜测\n- 敏感信息，除非用户明确授权\n- 无新增信息的重复内容\n\n### 对话结束\n\n如果对话中产生重要决策、偏好或事实：\n\n1. `remember` 直写记忆（低置信内容用 `--inbox`，必要时 `promote`）。写入时已按节流自动推送。\n2. 收尾执行一次显式 `sync`：它忽略节流、立即推送，确保本次会话即使在节流窗口内产生的\n   记忆也全部上远端（兜底，防止刚写完就关闭 Agent 导致最后几条只在本地）。\n\n## 发布与安全约束\n\n- 不要把真实 token、client secret、OAuth code 写进 `SKILL.md`、README、示例或提交历史。\n- `.memhub/secrets.yaml` 必须保持本地忽略。\n- 发布到 SkillHub/ClawHub 的包应包含：`SKILL.md`、`README.md`、`scripts/memhub.py`、`templates/context-pack.md.j2`。\n- 发布包不应包含 `__pycache__`、`.pyc`、`.git` 或用户个人记忆数据。\n\n## 重要原则\n\n- MemHub 只负责存取和同步，智能判断由 Agent 完成。\n- 写入必须带 source，便于追溯。\n- 默认直写 canonical 记忆；低置信或需人工复核的内容才进 inbox 审计缓冲。\n- Git 仓库中的 YAML/Markdown 是唯一可信源数据。\n\nFile v0.4.4:README.md\n\n# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让任意支持 Skill 的 Agent 能够读写、归档和同步用户的跨 Agent 统一记忆仓库。\n\n## 能力\n\n- 读取长期记忆上下文：`context --pack brief|standard|full|project`\n- 写入默认 inbox：`remember`\n- 检查与展示 inbox：`inbox list/show`\n- 半自动归档到 canonical memory：`promote --dry-run/--apply`\n- 导出给 chatbot 的上下文：`export chatbot`\n- GitHub/Gitee 同步：OAuth、token fallback、SSH fallback\n\n## 安装到任意支持 Skill 的 Agent\n\n将本目录 `skills/memhub/` 复制到对应 skills 目录，或通过 SkillHub/ClawHub 安装。\n\n## 配置仓库路径\n\n```bash\nexport MEMHUB_REPO=~/memhub-data\n```\n\n如果未设置，脚本默认使用当前工作目录下的 `./memhub-data`。\n\n## 首次初始化\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" init --name dateng --role \"Product Manager\"\n```\n\n## 配置 GitHub/Gitee 同步\n\n推荐使用 OAuth setup 命令，而不是手动配置 remote。**GitHub 和 Gitee 都开箱即用**：\n两者默认都走内置的 MemHub Auth Broker（`https://oauth.1024hub.cn`），它在服务端保管各\nprovider 的 OAuth `client_secret`，普通用户无需配置任何环境变量或自建 OAuth 应用。\n\n### GitHub / Gitee 一键授权（默认走 broker）\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup gitee  --repo-name mymemhub\n```\n\n流程（两者一致）：\n\n1. CLI 调 broker 创建授权 session，拿到 `auth_url`；\n2. CLI 打开该 URL，用户在 GitHub/Gitee 页面点击确认授权；\n3. broker 在服务端用 `client_secret` 换取 token；\n4. CLI 轮询 broker 拿到 token，存入本地 `.memhub/secrets.yaml`（git 忽略）。\n\n无浏览器环境加 `--no-browser`，CLI 会打印 URL 供手动打开。\n\n### 高级覆盖 / Fallback\n\n```bash\n# 自建 broker\nexport MEMHUB_OAUTH_BROKER_URL=https://<your-broker-host>\n# 覆盖内置 OAuth App client id\nexport MEMHUB_GITHUB_CLIENT_ID=<github-oauth-app-client-id>\nexport MEMHUB_GITEE_CLIENT_ID=<gitee-oauth-app-client-id>\n# 开发者直连（不经 broker，自己保管 Gitee secret，勿提交到仓库）\nexport MEMHUB_GITEE_CLIENT_SECRET=<gitee-oauth-app-client-secret>\n```\n\n### Token / SSH Fallback\n\n```bash\n# Token fallback\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth token --repo-name mymemhub\n\n# SSH fallback\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\n```\n\nOAuth/token 会保存在本地 `.memhub/secrets.yaml`，并被 `.gitignore` 忽略。不要把 OAuth app 的 client secret、token 或 authorization code 提交到仓库。\n\n## 常用命令\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"要记住的内容\" --type fact --source agent\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox list\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox show <filename-or-id-fragment>\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --dry-run\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --apply\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" export chatbot\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync status\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync\n```\n\n## Agent 使用原则\n\n- 读取前：如果任务依赖长期记忆，先 `sync`，再 `context --pack brief`。\n- 写入时：用户明确要求记忆，或形成稳定决策/偏好/事实时，写入 inbox。\n- 写入后：如果配置了 remote，执行 `sync`。\n- 归档时：先 `promote --dry-run`，确认后再 `promote --apply`，然后 `sync`。\n- setup：只有用户明确要求配置或切换同步服务时才执行。\n- 失败：同步失败时不要删除本地数据；报告错误并保留本地文件。\n\n## 发布包内容\n\n发布到 SkillHub/ClawHub 时应包含：\n\n```text\nSKILL.md\nREADME.md\nscripts/memhub.py\ntemplates/context-pack.md.j2\n```\n\n不应包含：\n\n```text\n__pycache__/\n*.pyc\n.git/\n.memhub/secrets.yaml\n用户个人记忆数据\n```\n\n## License\n\nMIT-0\n\nFile v0.4.4:_meta.json\n\n{\n  \"ownerId\": \"kn7aq20vx0abk37pk7pnq842t1827dq3\",\n  \"slug\": \"memhub\",\n  \"version\": \"0.4.4\",\n  \"publishedAt\": 1782371210139\n}\n\nFile v0.4.4:skill-card.md\n\n## Description:\n\nMemHub lets an agent read, write, search, archive, export, and synchronize a user's cross-agent memory repository using MemHub Protocol v0.1.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cutd](https://clawhub.ai/user/cutd)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, operators, and end users use this skill to give agents a Git-backed long-term memory workflow for personal preferences, project context, decisions, and chatbot context export. It is also used to configure optional GitHub or Gitee synchronization for a dedicated MemHub memory repository.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill manages a dedicated memory Git repository and the server security summary says the current code can overreach local file boundaries.\n\nMitigation: Use a dedicated MEMHUB_REPO path, avoid pointing the skill at unrelated project or home directories, and review file changes before sync or deployment.\n\nRisk: The skill can configure GitHub or Gitee synchronization and handle OAuth tokens, token fallback, SSH remotes, and local secrets.\n\nMitigation: Authorize only trusted remotes, prefer SSH or tightly scoped tokens, keep tokens out of chat and source files, and review sync configuration before authorizing.\n\nRisk: The security guidance warns against running it from directories or home environments containing unrelated .env secrets until boundary and token-handling issues are fixed.\n\nMitigation: Run the CLI from a controlled working directory and keep unrelated .env secrets outside the execution boundary.\n\nRisk: Untrusted MemHub repositories or remotes may introduce misleading or unwanted memory content into an agent's context.\n\nMitigation: Use trusted repositories and remotes, treat exported memory context as auditable rather than absolute truth, and review memory entries before relying on them.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/cutd/skills/memhub)\n- [README](README.md)\n- [Skill Definition](SKILL.md)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown and terminal-oriented guidance with generated YAML or Markdown memory files]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Can create and update a dedicated local Git memory repository and local sync configuration when the user invokes the CLI.]\n\n## Skill Version(s):\n\n0.4.4 (source: frontmatter and server-resolved release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v0.4.3: 6 files, 38257 bytes\n\nFiles: context-pack.md.j2 (278b), memhub.py (103385b), README.md (4287b), skill-card.md (2364b), SKILL.md (16282b), _meta.json (125b)\n\nFile v0.4.3:SKILL.md\n\n---\nname: memhub\nversion: 0.4.3\ndescription: 使用 MemHub Protocol v0.1 读写用户的跨 Agent 统一记忆仓库。当用户要求记住信息、检索/遗忘记忆、读取个人/项目上下文、生成 chatbot 注入文本、同步 Git 记忆仓库时使用。\ntags:\n  - memory\n  - memhub\n  - github\n  - gitee\n  - sync\n  - agent-memory\nlicense: MIT-0\n---\n\n# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让 Agent 能够读取、写入和同步符合 MemHub Protocol v0.1 的记忆仓库。\n\n## 触发场景\n\n使用本 Skill 当：\n\n- 用户说“记住这个”、“帮我记一下”、“以后记得”。\n- 用户问“我的偏好是什么”、“当前项目上下文是什么”。\n- 用户需要把记忆注入到 Gemini/元宝/豆包/Cursor/Claude Code。\n- 会话开始时需要读取用户长期记忆。\n- 会话结束时需要把关键决策/偏好/事实写入记忆并同步。\n\n## 环境变量\n\n推荐设置（唯一需要的一项）：\n\n```bash\nexport MEMHUB_REPO=/path/to/memhub-data\n```\n\nOAuth 同步**开箱即用**：GitHub 和 Gitee 都默认走内置的 MemHub Auth Broker，\n普通用户无需设置任何 OAuth 相关环境变量。以下全部为可选的高级覆盖：\n\n```bash\n# 覆盖内置 broker（自建 broker 时）\nexport MEMHUB_OAUTH_BROKER_URL=https://<your-broker-host>\nexport MEMHUB_GITEE_OAUTH_BROKER_URL=https://<your-broker-host>   # 仅覆盖 Gitee\n\n# 开发者直连模式（不经 broker，自己保管 Gitee secret）\nexport MEMHUB_GITEE_CLIENT_SECRET=...\n\n# 覆盖内置 OAuth App client id\nexport MEMHUB_GITHUB_CLIENT_ID=...\nexport MEMHUB_GITEE_CLIENT_ID=...\n\n# Token fallback\nexport MEMHUB_GITHUB_TOKEN=...\nexport MEMHUB_GITEE_TOKEN=...\n```\n\n如果未设置 `MEMHUB_REPO`，脚本默认使用当前工作目录下的 `./memhub-data`。\n\nCLI 会自动读取当前目录 `.env` 和用户 home 目录 `.env`，且不会覆盖已经存在的进程环境变量。不要把 `.env` 提交到 Git。\n\n## 命令\n\n本 Skill 提供一个 Python CLI：`scripts/memhub.py`。\n\n```bash\n# 初始化仓库\npython scripts/memhub.py --repo ~/memhub-data init --name dateng --role \"Product Manager\"\n\n# 读取上下文\npython scripts/memhub.py --repo ~/memhub-data context\npython scripts/memhub.py --repo ~/memhub-data context --pack brief\n# 记忆：默认直写 canonical 并本地提交（不自动推送）\npython scripts/memhub.py --repo ~/memhub-data remember \"用户偏好结构化直接的回答\" --type preference --source agent\npython scripts/memhub.py --repo ~/memhub-data remember \"MemHub 采用 Git-first 架构\" --type decision --project memhub --source agent\n# 低置信/待人工复核的内容才进 inbox 审计缓冲\npython scripts/memhub.py --repo ~/memhub-data remember \"也许该支持 Notion 导出\" --type fact --inbox --source agent\n\n# 检索与遗忘\npython scripts/memhub.py --repo ~/memhub-data search \"Git-first\"\npython scripts/memhub.py --repo ~/memhub-data search \"决策\" --type decision --project memhub\npython scripts/memhub.py --repo ~/memhub-data search \"旧偏好\" --include-archived   # 含已归档\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\"            # 预览\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\" --apply     # 软归档（status=archived）\n\n# 将 inbox 缓冲项归档到 canonical（仅 --inbox 写入的内容才需要）\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote --status all --apply   # 扫全部 inbox 项\n\n# 检查 inbox\npython scripts/memhub.py --repo ~/memhub-data inbox list\npython scripts/memhub.py --repo ~/memhub-data inbox list --status all\npython scripts/memhub.py --repo ~/memhub-data inbox show <filename-or-id-fragment>\n\n# 将 inbox 半自动归档到 canonical memory\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote <filename-or-id-fragment> --apply\n\n# 导出给 chatbot 的上下文\npython scripts/memhub.py --repo ~/memhub-data export chatbot\n\n# 首次接入（推荐）：授权 + 自动判断拉取已有记忆 / 初始化新仓库\npython scripts/memhub.py --repo ~/memhub-data onboard github --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data onboard gitee  --repo-name mymemhub\n\n# 同步 GitHub/Gitee（手动分步；默认 OAuth 走内置 broker）\npython scripts/memhub.py --repo ~/memhub-data sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup gitee --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup github --auth token --repo-name mymemhub\npython scripts/memhub.py --repo ~/memhub-data sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\npython scripts/memhub.py --repo ~/memhub-data sync status\npython scripts/memhub.py --repo ~/memhub-data sync\n\n# 自检：确认本机/本仓库的自动同步是否就绪（remote/token/merge driver/MEMHUB_REPO 等）\npython scripts/memhub.py --repo ~/memhub-data doctor\n```\n\n## Agent 行为协议\n\n### 上下文 pack 分级\n\n`context --pack` 有四档,逐档累加内容:\n\n- `brief`:用户画像、最重要的偏好、当前项目及最近决策(用于注入 chatbot)。\n- `standard`(默认):brief + 约束、惯例、未完成任务。\n- `project`:聚焦默认/指定项目,决策与任务更全。\n- `full`:standard + knowledge、relations、最近 timeline。\n\n`export chatbot` 默认用 brief;若存在 `.memhub/templates/context-pack.md.j2`,则用该模板渲染(支持 `{{ name }}` 等占位符)。\n\n### 总原则\n\n- `MEMHUB_REPO` 是用户记忆仓库；不要把用户记忆写入代码仓库。\n- GitHub/Gitee remote 只是同步后端；YAML/Markdown 文件仍是可信源数据。\n- 自动写入默认进入 canonical 记忆（本地提交，不自动推送）；低置信或需人工复核的才用 `--inbox`。\n- `sync setup` 会触发授权、创建仓库、修改 remote；**只有用户明确要求配置/切换同步时才执行**。\n- OAuth/token/SSH 凭据、authorization code、client secret、access token 都属于敏感信息；不要在回答中复述。\n\n### 对话开始：读取上下文\n\n**本会话首次涉及记忆时**，先跑一次自检确认自动同步就绪（每个会话只需一次，不要每轮都跑）：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" doctor\n```\n\n- 若 doctor 报 `NOT ready`（有 ✗），说明自动同步未生效。按提示补齐：缺 remote → 提示用户\n  `sync setup`；缺 token（常见于新机器）→ 引导用户重新授权；其余 ✗ 同理。**不要静默忽略**，\n  否则用户会误以为在自动同步，实际没有。\n- 若全绿或只有 `!` 提示，继续正常流程。\n- doctor 是只读的、不联网，开销很小；但仍只需每会话首次跑一次即可。\n\n确认就绪后，直接读取 context——`context` 会按节流阈值**自动从远端拉取**最新记忆，通常无需先手动 `sync`：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief\n```\n\n- 若距上次拉取超过 `pull_throttle_seconds`，`context` 会自动 `pull --rebase` 再输出。\n- 自动拉取失败时，CLI 会用本地记忆并在 stderr 提示“远端同步失败，当前上下文可能不是最新”，\n  无需中断；如需强制最新，可显式 `sync` 后再读。\n- 将 context 作为可审计上下文，不要当成绝对事实；遇到冲突时优先询问用户。\n\n### 对话中：写入记忆\n\n当用户明确要求记忆，或对话中形成稳定偏好/决策/事实时，默认**直写 canonical**：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"内容\" --type fact --source agent\n```\n\n- 直写会按 type 路由到对应 canonical 文件、去重后追加，并**本地提交但不自动推送**。\n- 重复内容会被自动跳过。\n- 只有低置信、需人工复核或批量待整理的内容，才加 `--inbox` 进审计缓冲，之后再 `promote`。\n\n类型建议：\n\n- `decision`：明确决策\n- `preference`：稳定偏好\n- `fact`：事实\n- `knowledge`：可复用知识/结论\n- `event`：重要事件\n- `relation`：人物/组织/工具关系\n- `constraint`：约束\n- `convention`：惯例\n\n### 同步：自动节流，无需每次手动 sync\n\n配置了 remote 后，同步是**自动**的，Agent 通常无需显式调用 `sync`：\n\n- **写入即同步（节流）**：每次 `remember` / `forget --apply` / `promote --apply` 后，CLI 会\n  自动尝试推送。距上次推送不足 `sync.push_throttle_seconds`（默认 3600 秒）时只在本地提交，\n  超过阈值才真正 pull+push。**记忆始终立即落本地，绝不丢失。**\n- **读取即拉取（节流）**：`context` 命令会在 `sync.pull_throttle_seconds`（默认 3600 秒）阈值外\n  自动 `pull --rebase` 拉取其它设备的最新记忆；拉取失败则用本地并在 stderr 提示可能不是最新。\n\n显式 `sync` 命令**忽略节流，立即** pull+push，适合在对话收尾兜底，确保本次所有记忆都已上远端：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync\n```\n\n节流阈值与开关都在 `.memhub/config.yaml` 的 `sync` 段（`auto_push`/`auto_pull` /\n`push_throttle_seconds` / `pull_throttle_seconds`）；节流时间戳记在本机 `.memhub/cache/sync.yaml`\n（git 忽略，每台设备独立）。单次写入若想跳过自动推送，加 `--no-sync`。\n\n`init`/`sync` 会自动注册结构化 merge 驱动（local git config 不随 clone 走，故每台设备首次\n`sync` 会自愈补注册），多设备对同一记忆文件的并发追加可自动合并，不会冲突。\n\n> **换新机器/新 Agent 时**：凭据（token）存在本机 `.memhub/secrets.yaml` 且不随 git 同步，\n> 所以新机器即使 clone 了记忆仓库也需要**重新授权一次**。先跑 `doctor` 自检，按提示补齐\n> remote/token 即可——全绿后自动同步即就绪。\n\n### 检索与遗忘\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" search \"关键词\" --type decision --project memhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" forget \"过时内容\"          # 预览\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" forget \"过时内容\" --apply   # 软归档\n```\n\n- `forget` 默认 dry-run；`--apply` 把命中条目 `status` 置为 `archived`，使其从 context pack\n  消失但保留在 Git 历史中，可审计、可回滚。\n- 纠正一条记忆 = `forget` 旧条目 + `remember` 新条目。\n\n### 首次接入：用 onboard（推荐）\n\n新 agent / 新机器第一次接入时，**用 `onboard` 一条命令完成全流程**，它会自动判断该\n\"拉取已有记忆\"还是\"初始化新仓库\"，避免用默认数据污染你已有的真实记忆：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" onboard gitee --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" onboard github --repo-name mymemhub\n```\n\nonboard 的流程：\n\n1. 授权（默认走内置 broker，见下）。\n2. **探测远端**是否已有 MemHub 记忆仓库（含 `.memhub/config.yaml`）：\n   - **已有** → 以远端为准拉取到本地，**不写入任何默认数据**（你的真实记忆直接到位）；\n   - **为空** → 初始化默认记忆并推送，建立远端仓库。\n3. 注册 merge 驱动、确保 auto-sync 就绪。\n4. 打印 `doctor` 自检结果。\n\n之后写入即自动推送、读取即自动拉取，无需再手动 sync。新机器换设备时**总是优先用\nonboard**，不要先 `init` 再 `sync setup`（那会先播种默认数据，可能污染远端真实记忆）。\n\n### 同步 setup：手动分步配置（高级）\n\n`onboard` 内部会调用 setup。只有当你想单独配置/切换 remote、且明确知道本地数据状态时，\n才直接用 `sync setup`。当用户说“配置同步”、“连接 GitHub/Gitee”、“换成 Gitee/GitHub 同步”时，\n优先用 `onboard`。\n\n**开箱即用**：GitHub 和 Gitee 都默认走内置的 MemHub Auth Broker（`https://oauth.1024hub.cn`），\nclient_secret 保管在 broker 服务端，**用户无需设置任何环境变量或自建 OAuth 应用**。\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup gitee  --repo-name mymemhub\n```\n\n授权流程（两者一致）：\n\n1. CLI 调用 broker 创建授权 session，得到一个 `auth_url`。\n2. CLI 打开（或打印）该 URL；Agent 应把 URL 展示给用户，请用户在浏览器完成授权。\n3. CLI 轮询 broker 直到拿到 access token，自动存入本机 `.memhub/secrets.yaml`（git 忽略）。\n4. 不要要求用户把 access token 发到聊天里。\n\n无浏览器环境：加 `--no-browser`，CLI 会打印 URL 由用户手动打开。\n\n#### 高级 / fallback（仅当用户明确选择时）\n\n- 自建 broker：`--broker-url https://your-broker` 或设 `MEMHUB_OAUTH_BROKER_URL` /\n  `MEMHUB_GITEE_OAUTH_BROKER_URL`。\n- 开发者直连（不经 broker）：Gitee 用 `--client-secret`（或 `MEMHUB_GITEE_CLIENT_SECRET`）；\n  GitHub 会回退到 Device Flow。\n- Token / SSH：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth token --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\n```\n\n### 同步失败与冲突处理\n\n- 不要删除本地 `inbox`、canonical 文件或 `.git` 历史。\n- 将错误摘要告诉用户，避免泄露 token/header。\n- 如果 `git pull --rebase` 冲突，停止自动处理，报告冲突文件，让用户/Agent 单独修复。\n- 如果 provider 授权失败，建议用户重新授权或切换 token/SSH fallback。\n- 如果远端仓库创建失败但已存在，可以继续配置 remote 并尝试 sync。\n\n### Inbox 归档（promote）\n\n`remember` 默认直写 canonical，无需 promote。只有用 `--inbox` 缓冲过的低置信/待复核内容\n才需要 promote。整理 inbox 时先预览：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox list\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --dry-run\n```\n\n确认归档目标合理后再执行（默认 dry-run，须显式 `--apply`；`--apply` 后按节流自动推送）：\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --apply\n```\n\n`promote` 默认只扫 pending 的 inbox 项，可用 `--status all` 扫全部。归档路由规则：\n\n- `decision` → `projects/<project>/decisions.yaml`\n- `preference` → `identity/preferences.yaml`\n- `constraint` → `identity/constraints.yaml`\n- `convention` → `identity/conventions.yaml`\n- `knowledge` → `knowledge/product.yaml`\n- `relation` → `relations/people.yaml`\n- `fact` / `event` → `timeline/YYYY-MM.yaml`\n\n不要写入：\n\n- 临时闲聊\n- 未确认猜测\n- 敏感信息，除非用户明确授权\n- 无新增信息的重复内容\n\n### 对话结束\n\n如果对话中产生重要决策、偏好或事实：\n\n1. `remember` 直写记忆（低置信内容用 `--inbox`，必要时 `promote`）。写入时已按节流自动推送。\n2. 收尾执行一次显式 `sync`：它忽略节流、立即推送，确保本次会话即使在节流窗口内产生的\n   记忆也全部上远端（兜底，防止刚写完就关闭 Agent 导致最后几条只在本地）。\n\n## 发布与安全约束\n\n- 不要把真实 token、client secret、OAuth code 写进 `SKILL.md`、README、示例或提交历史。\n- `.memhub/secrets.yaml` 必须保持本地忽略。\n- 发布到 SkillHub/ClawHub 的包应包含：`SKILL.md`、`README.md`、`scripts/memhub.py`、`templates/context-pack.md.j2`。\n- 发布包不应包含 `__pycache__`、`.pyc`、`.git` 或用户个人记忆数据。\n\n## 重要原则\n\n- MemHub 只负责存取和同步，智能判断由 Agent 完成。\n- 写入必须带 source，便于追溯。\n- 默认直写 canonical 记忆；低置信或需人工复核的内容才进 inbox 审计缓冲。\n- Git 仓库中的 YAML/Markdown 是唯一可信源数据。\n\nFile v0.4.3:README.md\n\n# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让任意支持 Skill 的 Agent 能够读写、归档和同步用户的跨 Agent 统一记忆仓库。\n\n## 能力\n\n- 读取长期记忆上下文：`context --pack brief|standard|full|project`\n- 写入默认 inbox：`remember`\n- 检查与展示 inbox：`inbox list/show`\n- 半自动归档到 canonical memory：`promote --dry-run/--apply`\n- 导出给 chatbot 的上下文：`export chatbot`\n- GitHub/Gitee 同步：OAuth、token fallback、SSH fallback\n\n## 安装到任意支持 Skill 的 Agent\n\n将本目录 `skills/memhub/` 复制到对应 skills 目录，或通过 SkillHub/ClawHub 安装。\n\n## 配置仓库路径\n\n```bash\nexport MEMHUB_REPO=~/memhub-data\n```\n\n如果未设置，脚本默认使用当前工作目录下的 `./memhub-data`。\n\n## 首次初始化\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" init --name dateng --role \"Product Manager\"\n```\n\n## 配置 GitHub/Gitee 同步\n\n推荐使用 OAuth setup 命令，而不是手动配置 remote。**GitHub 和 Gitee 都开箱即用**：\n两者默认都走内置的 MemHub Auth Broker（`https://oauth.1024hub.cn`），它在服务端保管各\nprovider 的 OAuth `client_secret`，普通用户无需配置任何环境变量或自建 OAuth 应用。\n\n### GitHub / Gitee 一键授权（默认走 broker）\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup gitee  --repo-name mymemhub\n```\n\n流程（两者一致）：\n\n1. CLI 调 broker 创建授权 session，拿到 `auth_url`；\n2. CLI 打开该 URL，用户在 GitHub/Gitee 页面点击确认授权；\n3. broker 在服务端用 `client_secret` 换取 token；\n4. CLI 轮询 broker 拿到 token，存入本地 `.memhub/secrets.yaml`（git 忽略）。\n\n无浏览器环境加 `--no-browser`，CLI 会打印 URL 供手动打开。\n\n### 高级覆盖 / Fallback\n\n```bash\n# 自建 broker\nexport MEMHUB_OAUTH_BROKER_URL=https://<your-broker-host>\n# 覆盖内置 OAuth App client id\nexport MEMHUB_GITHUB_CLIENT_ID=<github-oauth-app-client-id>\nexport MEMHUB_GITEE_CLIENT_ID=<gitee-oauth-app-client-id>\n# 开发者直连（不经 broker，自己保管 Gitee secret，勿提交到仓库）\nexport MEMHUB_GITEE_CLIENT_SECRET=<gitee-oauth-app-client-secret>\n```\n\n### Token / SSH Fallback\n\n```bash\n# Token fallback\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth token --repo-name mymemhub\n\n# SSH fallback\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\n```\n\nOAuth/token 会保存在本地 `.memhub/secrets.yaml`，并被 `.gitignore` 忽略。不要把 OAuth app 的 client secret、token 或 authorization code 提交到仓库。\n\n## 常用命令\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"要记住的内容\" --type fact --source agent\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox list\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox show <filename-or-id-fragment>\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --dry-run\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --apply\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" export chatbot\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync status\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync\n```\n\n## Agent 使用原则\n\n- 读取前：如果任务依赖长期记忆，先 `sync`，再 `context --pack brief`。\n- 写入时：用户明确要求记忆，或形成稳定决策/偏好/事实时，写入 inbox。\n- 写入后：如果配置了 remote，执行 `sync`。\n- 归档时：先 `promote --dry-run`，确认后再 `promote --apply`，然后 `sync`。\n- setup：只有用户明确要求配置或切换同步服务时才执行。\n- 失败：同步失败时不要删除本地数据；报告错误并保留本地文件。\n\n## 发布包内容\n\n发布到 SkillHub/ClawHub 时应包含：\n\n```text\nSKILL.md\nREADME.md\nscripts/memhub.py\ntemplates/context-pack.md.j2\n```\n\n不应包含：\n\n```text\n__pycache__/\n*.pyc\n.git/\n.memhub/secrets.yaml\n用户个人记忆数据\n```\n\n## License\n\nMIT-0\n\nFile v0.4.3:_meta.json\n\n{\n  \"ownerId\": \"kn7aq20vx0abk37pk7pnq842t1827dq3\",\n  \"slug\": \"memhub\",\n  \"version\": \"0.4.3\",\n  \"publishedAt\": 178235\n\nArchive v0.4.2: 6 files, 36061 bytes\n\nFiles: context-pack.md.j2 (278b), memhub.py (96191b), README.md (4287b), skill-card.md (2612b), SKILL.md (14782b), _meta.json (125b)\n\nArchive v0.4.1: 6 files, 34359 bytes\n\nFiles: context-pack.md.j2 (278b), memhub.py (90722b), README.md (4403b), skill-card.md (2537b), SKILL.md (14270b), _meta.json (125b)","readmeExcerpt":"Skill: MemHub Owner: cutd Summary: 使用 MemHub Protocol v0.1 管理用户明确指定的跨 Agent 记忆仓库。用于用户明确要求记住、检索、遗忘、导出上下文或配置 Git 同步时；读取可直接执行，持久写入、自动同步、OAuth、remote 修改和仓库创建必须来自当前用户的明确请求。 Tags: agent-memory:0.4.10, gitee:0.4.10, github:0.4.10, latest:0.4.10, memhub:0.4.10, memory:0.4.10, sync:0.4.10 Version history: v0.4.10 | 2026-09-22T02:23:14.404Z | user Security hardening: credentials moved outside the memory repo (0600 file in a 07","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"export MEMHUB_REPO=/path/to/memhub-data"},{"language":"bash","snippet":"# 初始化仓库\npython scripts/memhub.py --repo ~/memhub-data init --name dateng --role \"Product Manager\"\n\n# 读取上下文\npython scripts/memhub.py --repo ~/memhub-data context\npython scripts/memhub.py --repo ~/memhub-data context --pack brief\n# 记忆：默认直写 canonical 并本地提交；是否自动推送取决于同步配置\npython scripts/memhub.py --repo ~/memhub-data remember \"用户偏好结构化直接的回答\" --type preference --source agent\npython scripts/memhub.py --repo ~/memhub-data remember \"MemHub 采用 Git-first 架构\" --type decision --project memhub --source agent\n# 低置信/待人工复核的内容才进 inbox 审计缓冲\npython scripts/memhub.py --repo ~/memhub-data remember \"也许该支持 Notion 导出\" --type fact --inbox --source agent\n\n# 检索与遗忘\npython scripts/memhub.py --repo ~/memhub-data search \"Git-first\"\npython scripts/memhub.py --repo ~/memhub-data search \"决策\" --type decision --project memhub\npython scripts/memhub.py --repo ~/memhub-data search \"旧偏好\" --include-archived   # 含已归档\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\"            # 预览\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\" --apply     # 软归档（status=archived）\n\n# 将 inbox 缓冲项归档到 canonical（仅 --inbox 写入的内容才需要）\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote --status all --apply   # 扫全部 inbox 项\n\n# 检查 inbox\npython scripts/memhub.py --repo ~/memhub-data inbox list\npython scripts/memhub.py --repo ~/memhub-data inbox list --status all\npython scripts/memhub.py --repo ~/memhub-data inbox show <filename-or-id-fragment>\n\n# 将 inbox 半自动归档到 canonical memory\npython scripts/memhub.py --repo ~/memhub-data promote --dry-run\npython scripts/memhub.py --repo ~/memhub-data promote --apply\npython scripts/memhub.py --repo ~/memhub-data promote <filename-or-id-fragment> --apply\n\n# 导出给 chatbot 的上下文\npython scripts/memhub.py --repo ~/memhub-data export chatbot\n\n# 首次接入（推荐）：授权 + 自动判断拉取已有记忆 / 初始化新仓库\npython scripts/memhub.py --repo ~/memhub-data onboard github --repo-name mymemhub\npyth"},{"language":"bash","snippet":"python scripts/memhub.py --repo \"$MEMHUB_REPO\" doctor"},{"language":"bash","snippet":"python scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief"},{"language":"bash","snippet":"python scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"内容\" --type fact --source agent"},{"language":"bash","snippet":"python scripts/memhub.py --repo \"$MEMHUB_REPO\" sync"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: memhub\nversion: 0.4.8\ndescription: 使用 MemHub Protocol v0.1 管理用户明确指定的跨 Agent 记忆仓库。用于用户明确要求记住、检索、遗忘、导出上下文或配置 Git 同步时；读取可直接执行，持久写入、自动同步、OAuth、remote 修改和仓库创建必须来自当前用户的明确请求。\ntags:\n  - memory\n  - memhub\n  - github\n  - gitee\n  - sync\n  - agent-memory\nlicense: MIT-0\n---\n\n# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让 Agent 能够读取、写入和同步符合 MemHub Protocol v0.1 的记忆仓库。\n\n## 触发场景\n\n使用本 Skill 当：\n\n- 用户说“记住这个”、“帮我记一下”、“以后记得”。\n- 用户问“我的偏好是什么”、“当前项目上下文是什么”。\n- 用户需要把记忆注入到 Gemini/元宝/豆包/Cursor/Claude Code。\n- 会话开始时需要读取用户长期记忆。\n- 用户明确要求在会话结束前保存关键决策、偏好或事实，或已经明确启用了对应自动记忆策略。\n\n## 环境变量\n\n推荐设置（唯一需要的一项）：\n\n```bash\nexport MEMHUB_REPO=/path/to/memhub-data\n```\n\nGitHub 默认使用官方 Device Flow。Gitee OAuth 可使用内置 Broker，但 CLI 会先展示固定\nBroker 域名并要求用户确认；非交互环境必须显式传入可信 Broker 或自己的 OAuth 配置。\n\n可选配置项只写在进程环境或显式 `--env-file` 中，不要写进 Skill、仓库或聊天：\n\n- `MEMHUB_OAUTH_BROKER_URL`：明确选择的通用 Broker；\n- `MEMHUB_GITEE_OAUTH_BROKER_URL`：仅用于 Gitee 的可信 Broker；\n- `MEMHUB_GITHUB_CLIENT_ID`、`MEMHUB_GITEE_CLIENT_ID`：自有 OAuth App client id；\n- `MEMHUB_GITEE_CLIENT_SECRET`：Gitee 直连模式的 client secret；\n- `MEMHUB_GITHUB_TOKEN`、`MEMHUB_GITEE_TOKEN`：token fallback。\n\n必须通过 `--repo` 或 `MEMHUB_REPO` 明确指定专用记忆仓库；CLI 不会把当前目录隐式当作记忆仓库。\n\nCLI 不会自动读取当前目录或 home 目录的通用 `.env`。如确需文件配置，显式传入\n`--env-file /path/to/memhub.env`；只会加载受支持的 `MEMHUB_*` 键。\n\n## 权限与确认边界\n\n机器可读版本见同目录 `permissions.json`；下面的散文说明与它一致。\n\n- `context`、`search`、`inbox list/show`、`doctor` 是只读操作；`doctor` 默认完全离线，只有显式加 `--network` 才会探测已配置的 broker。\n- `remember`、`forget --apply`、`promote --apply`、`init` 会修改记忆仓库；只有用户当前请求明确要求对应写入时才执行。\n- `sync`、`sync setup`、`onboard` 会访问网络或修改 Git 状态；只有用户当前请求明确要求同步或配置时才执行。\n- `sync setup`/`onboard` 是用户明确发起的同步授权，完成后保留原有节流自动同步；用户可传 `--manual-sync` 关闭。\n- 所有 inbox 引用和 canonical target 都限制在指定 MemHub 仓库内；拒绝绝对路径和 `..` 越界。\n- HTTPS token 只会发送到所选 Provider 的固定官方 Git/API 主机；目标主机不匹配时拒绝执行。\n- 只有 `git` 一个外部命令会被调用，且不经过 shell；凭据只经子进程环境传递，不出现在 argv。\n- 远程写入（创建仓库、push）只在 `sync setup` / `onboard` / `sync` 被用户显式调用时发生。\n- 没有破坏性操作：`forget` 是软归档，不删文件、不改写 Git 历史。\n\n## 命令\n\n本 Skill 提供一个 Python CLI：`scripts/memhub.py`。\n\n```bash\n# 初始化仓库\npython scripts/memhub.py --repo ~/memhub-data init --name dateng --role \"Product Manager\"\n\n# 读取上下文\npython scripts/memhub.py --repo ~/memhub-data context\npython scripts/memhub.py --repo ~/memhub-data context --pack brief\n# 记忆：默认直写 canonical 并本地提交；是否自动推送取决于同步配置\npython scripts/memhub.py --repo ~/memhub-data remember \"用户偏好结构化直接的回答\" --type preference --source agent\npython scripts/memhub.py --repo ~/memhub-data remember \"MemHub 采用 Git-first 架构\" --type decision --project memhub --source agent\n# 低置信/待人工复核的内容才进 inbox 审计缓冲\npython scripts/memhub.py --repo ~/memhub-data remember \"也许该支持 Notion 导出\" --type fact --inbox --source agent\n\n# 检索与遗忘\npython scripts/memhub.py --repo ~/memhub-data search \"Git-first\"\npython scripts/memhub.py --repo ~/memhub-data search \"决策\" --type decision --project memhub\npython scripts/memhub.py --repo ~/memhub-data search \"旧偏好\" --include-archived   # 含已归档\npython scripts/memhub.py --repo ~/memhub-data forget \"过时的偏好\"            # 预览\npyt"},{"path":"README.md","content":"# MemHub Skill\n\nMemHub 是一个无服务端、Git-first 的个人 AI 记忆协议。本 Skill 让任意支持 Skill 的 Agent 能够读写、归档和同步用户的跨 Agent 统一记忆仓库。\n\n## 能力\n\n- 读取长期记忆上下文：`context --pack brief|standard|full|project`\n- 写入默认 inbox：`remember`\n- 检查与展示 inbox：`inbox list/show`\n- 半自动归档到 canonical memory：`promote --dry-run/--apply`\n- 导出给 chatbot 的上下文：`export chatbot`\n- GitHub/Gitee 同步：OAuth、token fallback、SSH fallback\n\n## 安装到任意支持 Skill 的 Agent\n\n将本目录 `skills/memhub/` 复制到对应 skills 目录，或通过 SkillHub/ClawHub 安装。\n\n## 配置仓库路径\n\n```bash\nexport MEMHUB_REPO=~/memhub-data\n```\n\n必须通过 `--repo` 或 `MEMHUB_REPO` 明确指定专用记忆仓库；CLI 不会把当前目录隐式当作记忆仓库。\n\n## 首次初始化\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" init --name dateng --role \"Product Manager\"\n```\n\n## 配置 GitHub/Gitee 同步\n\n推荐使用 OAuth setup 命令，而不是手动配置 remote。GitHub 默认走官方 Device Flow。\nGitee 交互式配置会先展示内置 Broker 域名并请求确认；非交互环境需明确提供可信 Broker，\n或使用自己的 OAuth 配置。\n\n### GitHub / Gitee 授权\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --repo-name mymemhub\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup gitee --repo-name mymemhub --broker-url https://<trusted-broker>\n```\n\nGitHub 使用 Device Flow。明确选择 Broker 时，流程为：\n\n1. CLI 调 broker 创建授权 session，拿到 `auth_url`；\n2. CLI 打开该 URL，用户在 GitHub/Gitee 页面点击确认授权；\n3. broker 在服务端用 `client_secret` 换取 token；\n4. CLI 轮询 broker 拿到 token，存入记忆仓库之外的本机凭据目录（0600）。\n\n无浏览器环境加 `--no-browser`，CLI 会打印 URL 供手动打开。\n\n### 高级覆盖 / Fallback\n\n可选配置项：`MEMHUB_OAUTH_BROKER_URL`、`MEMHUB_GITEE_OAUTH_BROKER_URL`、\n`MEMHUB_GITHUB_CLIENT_ID`、`MEMHUB_GITEE_CLIENT_ID`、\n`MEMHUB_GITEE_CLIENT_SECRET`。只放在进程环境或显式 `--env-file` 中，\n不要写进仓库、文档示例或聊天。\n\n### Token / SSH Fallback\n\n```bash\n# Token fallback\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth token --repo-name mymemhub\n\n# SSH fallback\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync setup github --auth ssh --remote-method ssh --owner <login> --repo-name mymemhub --no-create\n```\n\nOAuth/token 保存在记忆仓库**之外**的本机目录（macOS 默认 `~/Library/Application Support/memhub/secrets/`，Linux 默认 `~/.local/state/memhub/secrets/`，可用 `MEMHUB_SECRETS_DIR` 覆盖），文件权限 0600、目录 0700。仓库因此永远不含凭据，clone 与同步也不会带走它们。\n\n不要把 OAuth app 的 client secret、token 或 authorization code 提交到仓库或在聊天中复述。第三方 OAuth broker 不会被隐式使用，必须由 `--broker-url` 或 `MEMHUB_*_OAUTH_BROKER_URL` 明确指定。`doctor` 默认离线，只有 `--network` 才会探测 broker。\n\n## 常用命令\n\n```bash\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" context --pack brief\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" remember \"要记住的内容\" --type fact --source agent\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox list\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" inbox show <filename-or-id-fragment>\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --dry-run\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" promote --apply\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" export chatbot\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync status\npython scripts/memhub.py --repo \"$MEMHUB_REPO\" sync\n```\n\n## Agent 使用原则\n\n- 读取前：如果任务依赖长期记忆，先 `sync`，再 `context --pack brief`。\n- 写入时：用户明确要求记忆，或形成稳定决"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7aq20vx0abk37pk7pnq842t1827dq3\",\n  \"slug\": \"memhub\",\n  \"version\": \"0.4.10\",\n  \"publishedAt\": 1790043794404\n}"},{"path":"skill-card.md","content":"## Description:\n\nMemHub lets an agent manage a user-designated cross-agent memory repository with MemHub Protocol v0.1, including remembering, retrieving, forgetting, exporting context, and configuring Git sync with explicit user consent for persistent writes and remote changes.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cutd](https://clawhub.ai/user/cutd)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent users use MemHub when they want an agent to maintain, retrieve, archive, export, and optionally Git-sync a dedicated long-term memory repository across agent sessions.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Long-term memory may retain sensitive, stale, or unwanted personal context.\n\nMitigation: Use a dedicated MEMHUB_REPO, review what gets remembered, and use the skill's forget, inbox, and promote workflows to keep retained context intentional.\n\nRisk: After sync setup or onboard, memory reads may pull and memory writes may push repository content on a throttle.\n\nMitigation: Configure sync only when the user explicitly asks for it, and choose manual sync or no-sync options when automatic pull or push is not desired.\n\nRisk: OAuth codes, client secrets, or access tokens could be exposed if shared in chat.\n\nMitigation: Do not paste tokens or OAuth codes into chat; use the supported authorization flow and local credential storage instead.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/cutd/skills/memhub)\n- [README](artifact/README.md)\n- [Permission boundary](artifact/permissions.json)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and generated memory context text]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Outputs are intended for agent use with explicit user consent for persistent writes, remote sync setup, OAuth, repository creation, and apply-mode mutations.]\n\n## Skill Version(s):\n\n0.4.10 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."},{"path":"permissions.json","content":"{\n  \"schema\": \"memhub.permission-boundary/v1\",\n  \"skill\": \"memhub\",\n  \"version\": \"0.4.8\",\n  \"purpose\": \"Read, write and Git-sync a user-designated MemHub memory repository.\",\n  \"filesystem\": {\n    \"read\": [\"${MEMHUB_REPO}/**\", \"${SKILL_DIR}/**\"],\n    \"write\": [\"${MEMHUB_REPO}/**\"],\n    \"credentialWrite\": [\"${MEMHUB_SECRETS_DIR}/**\"],\n    \"denied\": [\"${MEMHUB_REPO}/../**\", \"/**\", \"**/.env\", \"**/.git/config\"],\n    \"pathEscape\": \"rejected: absolute paths and `..` sequences are refused\"\n  },\n  \"shell\": {\n    \"commands\": [\"git\"],\n    \"interpreter\": false,\n    \"secretInArguments\": \"never; git authorization is passed through the child-process environment\"\n  },\n  \"network\": {\n    \"mode\": \"opt-in\",\n    \"default\": \"no automatic egress until `sync setup` or `onboard` is run explicitly\",\n    \"hosts\": [\"github.com\", \"api.github.com\", \"gitee.com\"],\n    \"optionalHosts\": [\"${MEMHUB_OAUTH_BROKER_URL}\", \"${MEMHUB_GITEE_OAUTH_BROKER_URL}\"],\n    \"thirdPartyBroker\": \"used only when the user names the host via --broker-url or a MEMHUB_*_OAUTH_BROKER_URL variable\"\n  },\n  \"mutations\": {\n    \"localWrite\": {\n      \"commands\": [\"remember\", \"forget --apply\", \"promote --apply\", \"init\"],\n      \"requires\": \"explicit user request\"\n    },\n    \"remoteWrite\": {\n      \"commands\": [\"sync\", \"sync setup\", \"onboard\"],\n      \"requires\": \"explicit user request\"\n    },\n    \"destructive\": \"none: `forget` soft-archives (status=archived); no file deletion and no history rewrite\"\n  },\n  \"credentials\": {\n    \"storage\": \"outside ${MEMHUB_REPO}, file mode 0600 in a 0700 directory\",\n    \"inRepository\": \"never\",\n    \"inChatOutput\": \"never\",\n    \"inProcessArguments\": \"never\",\n    \"oauthState\": \"generated per authorization attempt and verified on the callback\",\n    \"scopes\": {\"github\": \"repo (device flow)\", \"gitee\": \"user_info projects\"}\n  }\n}"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1415,"uniquenessScore":44,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T16:56:54.369Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T16:56:54.369Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T21:41:25.899Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}