Spec: memory-sync Skill — agent-mediated Memory Sync over a Human-configured remote #187

Problem Statement

拥有 PersonaBot 的用户换设备（或多台设备并用）时，Memory 只活在单台 Host 的本地 Git 仓库里，没有跨设备连续性。手动拷目录丢 history 且易错。需要一条个人 Dropbox 式的同步路径，但产品不做账号体系、不碰用户凭据（ADR-0059 已定）。

Solution

BotHarness 提供一个第一方 Skill（memory-sync），注册在 Orchestrator 的 agent scope，对模型和用户双可见。用户用自然语言（"把我的 memory 同步到 X"）或 /memory-sync … 触发；Orchestrator 按 Skill 流程用普通 git 能力完成 push / pull / 新设备接入 / 冲突处理，全程与用户对话、不做产品审批、不碰凭据。

User Stories

1. As a Human owner, I want to push my bot's memory to a private repo I own, so that the memory survives device loss.
2. As a Human owner, I want to pull the latest memory onto a second device, so that both devices share continuity.
3. As a Human owner, I want to onboard a new device by creating a new bot and resetting its memory to the remote, so that I don't re-teach the bot from scratch.
4. As a Human owner, I want to trigger sync by typing /memory-sync, so that I have a stable, memorable entry point.
5. As a Human owner, I want to trigger sync in natural language, so that I don't need to remember any command.
6. As a Human owner, I want to be asked which remote to use when none is configured, so that I stay in control of where my memory goes.
7. As a Human owner, I want to see what the bot is about to do (remote plus branch plus direction) before it runs, so that I can stop mistakes early.
8. As a Human owner, I want a plain-language explanation plus next steps when auth fails, so that I can recover with minimal git experience.
9. As a Human owner, I want to use a non-GitHub remote, so that I am not locked to one hosting provider.
10. As a Human owner, I want conflicts in persona/pinned files reported to me rather than silently merged, so that the bot's behavior never changes behind my back.
11. As a Human owner, I want to know that identity, Sessions, Bindings, and credentials are NOT synced, so that I understand device B is the same memory under a different identity.
12. As a Human owner, I want pushed commits attributed to the bot rather than my personal git identity, so that the remote history stays legible.
13. As a Human owner, I want the bot to never force-push or delete remote branches, so that a mistake can't destroy the remote.
14. As a Human owner, I want secrets and tokens to never enter memory files or commits, so that the synced repo stays safe.
15. As a Human owner, I want an explicit confirmation before any destructive reset on a new device, so that seed content is never lost silently.
16. As a Human owner, I want a short user guide with provider examples, so that I can set up a remote and credentials by following steps.

Implementation Decisions

• Carrier: a runtime-embedded DSH Skill named memory-sync via the skills service, registered at Orchestrator agent scope (the same agent-scoped pattern the plugin already uses for tools and prompt sections); invocation policy visible to both model and user.
• No commands registration in v1: the slash-shaped UX comes from user-token injection of the skill; a same-named command would risk / parse collision and need duplicate Agent-scheduling machinery (command results don't enter model history).
• Human entries: a natural-language request, or a /memory-sync token with an optional remote URL in the same message.
• Skill content sections: background (memory is a git-versioned repo, the Orchestrator cwd is that repo); preflight (git present, bot-local identity ensured, dirty-tree handling, fail-fast no-prompt env); push flow; pull/fast-forward flow; device-B onboarding (new bot plus confirmed reset, unrelated histories); conflict handling (persona/pinned report-first, never silent overwrite); provider examples docs-only (GitHub/Gitee/GitLab/SSH); troubleshooting (auth, network, divergence); red lines; attribution rule.
• Destructive steps require explicit Human confirmation; structured confirmation preferred where the platform offers it, dialogue confirmation acceptable.
• Scope: one Human's private remote; whole memory-repo content; identity, Sessions, Bindings, credentials, and Channel history never sync.
• Plugin composition: extend the inject list with the skills capability; no new model-visible tools; no bridge/RPC/Client changes.
• Spike first on the running Host against the pinned DSH: skills-service injectability, agent-scope registration, /memory-sync token-injection behavior, skill-tool availability to the Orchestrator, confirmation-tool availability. Documented fallback is a prompt section if the service isn't plugin-reachable.
• All mechanism claims verified against the pinned DSH plus the running Host; community docs are leads, not authority.

Testing Decisions

• A good test exercises external behavior only, never Skill prose or implementation details.
• End-to-end validation on the running Host with local bare remotes over the file protocol: push-then-pull equivalence (content plus history), device-B onboarding, the conflict report path, and the auth-failure guidance path. No GitHub account or network needed.
• Automated regression at plugin composition: inject-list snapshot plus absence of model-visible memory/sync tools (prior art: plugin composition tests and the memory-tool removal).
• No unit tests for Skill prose; the Skill is validated through exercised scenarios, Human-verified in-harness (validate against the running shell, not the test suite).

Out of Scope

• OAuth/login, UI binding, Host-owned sync or credential handling (ADR-0059).
• Multi-writer shared memory; automatic or scheduled sync.
• Identity/Session/Binding/credential sync; GitHub-exclusive features.
• Vector/RAG; Soul registry integration; commands registration.
• Any Host/Client/bridge changes.

Further Notes

• Only accepted (non-dirty) state is pushed; sync never bypasses the accepted-commit boundary (ADR-0047, ADR-0059).
• Device-B reset is destructive to the seed commit by design; confirmation required.
• Skills/commands community docs describe an older DSH than the pinned one; the spike confirms the delta.
• Sequencing: mechanism spike, then Skill content plus user guide, then end-to-end validation.