obsidian-user-memory

Obsidian User Memory

让不同 Agent 继承可审计的协作状态，而不是复制账号、聊天或黑箱记忆

一个面向 Codex 与其他 Agent 的可迁移连续性 Skill。它以用户拥有的 Obsidian 账本作为跨 Agent 权威事实源，用生命周期索引控制上下文，用经过验证的产品原生记忆作为可选镜像，并提供规则接入、审计、导出、恢复和新上下文验收。

快速开始 · 架构 · 运行模式 · 迁移恢复 · 安全边界 · 升级

---

它解决什么问题

很多“AI 记忆迁移”方案只完成了其中一小部分：复制一份 Markdown、导出聊天、备份整个配置目录，或依赖某个产品不可见的账号记忆。结果往往是：

• 换账号、设备或 Agent 后，用户偏好、当前状态和重要决定无法可靠恢复；
• 规则、Skills、领域档案和环境事实没有一起盘点，所谓迁移只恢复了文字摘要；
• 两个记忆库被当成平级，产生冲突、重复和循环回写；
• 全量历史每次都塞进上下文，过期结论和候选印象继续影响任务；
• 复制整个 .codex、浏览器配置或应用数据库，顺带带走认证和缓存；
• 文件存在就被误报成“产品会自动读取”，没有真实回环证据。

obsidian-user-memory 的目标更窄也更可验证：

恢复用户明确保存的工作关系、事实、偏好、决定、经验、当前交接、规则与 Skills；不声称复制模型实例、隐藏推理、未记录聊天或账号状态。

连续性架构

架构中只有 Obsidian 主账本拥有跨 Agent 权威。Agent 原生记忆必须先证明接口存在、能读写、产品会消费并完成真实回环，才可作为镜像；否则明确降级，但不影响从 Obsidian 接班。

核心能力

能力	实际行为
选择性加载	用有源文件 SHA-256 的索引只加载当前交接、有效热层和任务相关温层
生命周期治理	区分 active、candidate、review-due、superseded、archived，并设置证据与复核日期
Obsidian 优先同步	有长期增量时先写主账本、变更日志和索引，再写可选本地镜像
冲突与去重	使用稳定 ID 和证据优先级，不采用最后写入者获胜
Agent 接入	幂等合并标记规则块，记录规则自动加载和原生记忆的真实验证状态
Skill 迁移审计	区分用户自有、托管可重装和平台系统 Skill，避免复制缓存
安全导出	白名单导出、凭据形态拦截、SHA-256 清单、恢复前校验
冲突保护恢复	默认只读预演；已有不同文件不覆盖，规则只做语义合并
新上下文验收	在没有旧聊天的任务中验证读取、路由、应写增量和无变化回合

这不是什么

• 不是聊天记录导出器；
• 不是账号记忆抓取器；
• 不是 Obsidian 同步服务；
• 不是把多个记忆库设为平级的双向复制器；
• 不是认证、浏览器或整个 Agent 配置目录备份工具；
• 不是“安装 Skill 后自动拥有旧电脑数据”的承诺。

安装本 Skill 只提供规则和工具。目标机器仍需单独恢复用户自己的 Obsidian vault。

快速开始

方式一：让 Codex 安装

请从 https://github.com/Chen0125-a/obsidian-user-memory 安装 obsidian-user-memory Skill。
安装后先只读发现我的 Obsidian vault，并运行记忆健康检查，不要创建第二份记忆包。

方式二：手动安装

Windows PowerShell：

git clone https://github.com/Chen0125-a/obsidian-user-memory.git "$env:USERPROFILE\.codex\skills\obsidian-user-memory"

macOS / Linux：

git clone https://github.com/Chen0125-a/obsidian-user-memory.git "${CODEX_HOME:-$HOME/.codex}/skills/obsidian-user-memory"

重新打开一个 Agent 任务后，再明确告诉它 vault 位置，或让 Skill 先执行只读发现。

运行环境

• Python 3.8+；
• 只使用 Python 标准库；
• Windows、macOS 或 Linux 的普通文件系统；
• 一个由用户控制、结构符合契约的 Obsidian vault；
• 如果需要 GitHub 备份，由用户单独选择并授权，Skill 不隐式创建远端。

PowerShell 脚本只提供 Windows 兼容入口，核心逻辑位于 scripts/continuity.py。

第一次使用

只读取日常上下文：

用 $obsidian-user-memory 定位我的 vault，检查 MEMORY_INDEX.json 健康状态，
只加载 CURRENT.md、有效热层和与当前任务相关的温层。

新设备恢复前预演：

用 $obsidian-user-memory 校验这个迁移包，然后只做恢复预演。
列出会创建、保持、冲突或拒绝的文件，不要覆盖现有内容。

接入另一个 Agent：

用 $obsidian-user-memory 审计这个 Agent 的自动规则入口和真实本地记忆能力。
先 dry-run，无法证明的本地记忆接口必须登记为降级。

四层模型

层	权威与作用	失败时怎样处理
Obsidian canonical	用户可审阅的事实、偏好、决定、经验、当前交接和领域包	停止选择性加载，恢复主账本后再继续
Agent-local mirror	经文档和回环验证的产品原生记忆镜像	保留 Obsidian 工作，报告准确降级状态
Behavior rules	在新任务中自动加载的可迁移行为协议	语义合并并做新任务自动加载验收
Capability Skills	用户自有 Skill 源及托管 Skill 来源清单	用户自有完整恢复；托管项按来源重装

日常模式与完整模式

日常模式

适用于普通任务，只做健康检查和有界加载：

python scripts/continuity.py memory-health --vault <vault>
python scripts/continuity.py runtime-context --vault <vault> --query "<当前任务>" --max-chars 12000

运行结果会排除候选、到期、已替代和归档条目。源文件指纹漂移时失败关闭，不会继续信任旧索引。

完整模式

以下情况必须完整读取主账本和协议：

• 迁移、恢复或首次接入；
• 任何长期记忆写入或纠正；
• 冲突、隐私、生命周期或来源审计；
• 索引缺失、失效、过期、超预算或源指纹漂移。

完整模式不是“每次把全部历史塞进上下文”，而是维护和恢复路径。

记忆写入事务

有真实长期增量时，固定顺序是：

1. 完整读取并应用长期性、可行动性、证据、范围、安全和去重门槛；
2. 更新最窄的 Obsidian 权威文件；
3. 追加 MEMORY_CHANGELOG.md；
4. 原子重建 MEMORY_INDEX.json；
5. 运行健康检查并回读；
6. 仅当注册表证明本地记忆接口有效时，写入同 ID 的紧凑镜像；
7. 验证镜像，或报告准确降级状态；
8. 停止，不把日常记忆维护自动绑定到 Git。

没有长期变化时，两边都不制造记录。

导出与恢复

审计

python scripts/continuity.py verify --vault <vault> --skill-root <user-skill-root>

导出

导出只在用户明确要求迁移或备份、目标为空目录时执行：

python scripts/continuity.py export `
  --vault <vault> `
  --output <new-empty-destination> `
  --skill-root codex-user=<user-skill-root>

输出包含机器清单、交接说明和 SHA-256 校验文件。校验和用于发现损坏或创建后变化，不证明发布者身份。

恢复

python scripts/continuity.py verify-bundle --bundle <bundle>
python scripts/continuity.py restore --bundle <bundle> --target-vault <target-vault> --skill-target codex-user=<target-skill-root>

第二条命令默认只预演。确认无冲突后，才使用相同参数加 --apply。不同的现有文件永不自动覆盖。

状态为什么必须诚实

状态	含义
verified	规则自动加载，且原生记忆接口完成真实创建、读取、更新回环
degraded-no-native-memory-file	规则有效，但未发现可验证的产品原生记忆；仍从 Obsidian 正常接班
degraded-unverified-native-memory-path	找到候选文件，但尚未证明产品会消费或回环失败
degraded-unverified-native-memory-adapter	有文档化 API/适配器，但真实回环未完成
degraded-unverified-rules-autoload	本地记忆可用，但规则尚未在新任务中证明自动加载

acceptance_status 另行记录整套新上下文演练。文件可写、规则已合并或单项测试通过，都不能冒充完整接班成功。

隐私与安全边界

永不记录、导出或恢复：

• 密码、Token、Cookie、API Key、私钥和认证文件；
• 浏览器配置、账号数据库、会话数据库和应用缓存；
• 完整聊天、隐藏推理或模型内部状态；
• 无关隐私和敏感终端完整输出；
• 仅凭一次互动推断的人格、动机、健康、财务、关系或能力标签；
• Codex 系统 Skill、插件缓存、虚拟环境和依赖缓存。

恢复默认 dry-run，规则只合并标记块，冲突不覆盖。GitHub 发布和 vault 备份始终是独立、显式授权的动作。

验证

v1.0.1 在 Windows / Python 3.8 上完成：

验证项	结果
Python 单元与 CLI 行为测试	30 / 30 通过
Agent Skill 结构校验	通过
11 个发布源文件与已安装源 SHA-256	一致
README 相对链接与 SVG XML	通过
生成物、个人账本和高置信凭据扫描	通过

测试覆盖发现、索引、选择性加载、健康检查、接入、导出、校验、恢复预演、冲突保护、凭据拦截和篡改检测。测试通过证明实现满足这些可观察契约，不证明某个第三方 Agent 一定提供原生记忆接口。

运行测试：

python -m unittest discover -s tests -p "test_*.py" -v

项目结构

obsidian-user-memory/
├── SKILL.md
├── agents/openai.yaml
├── references/
│   ├── agent-compatibility.md
│   ├── continuity-architecture.md
│   ├── dual-memory-protocol.md
│   ├── manifest-schema.md
│   └── memory-lifecycle.md
├── scripts/
│   ├── continuity.py
│   ├── find_memory_root.ps1
│   └── verify_memory_package.ps1
├── tests/test_continuity.py
├── assets/continuity-architecture.svg
├── CHANGELOG.md
├── LICENSE
└── README.md

升级与版本

仓库版本使用 SemVer；主账本 schema、内存索引 schema 和协议代数拥有各自版本。v1.0.0 是独立仓库首个发布版本，v1.0.1 收窄了凭据文件名识别的误报，不代表内部协议版本变化。

升级时：

1. 阅读 CHANGELOG.md 和 Release notes；
2. 备份当前 Skill 源，但不要复制整个 Agent 配置目录；
3. 更新仓库文件；
4. 运行 30 项测试与 Skill 结构校验；
5. 对真实 vault 先执行 memory-health 和 verify；
6. schema 变化时先 dry-run，不手改指纹掩盖漂移；
7. 在无旧聊天的新任务中复测规则、读取、写入和无变化回合。

已知限制

• 本 Skill 不能访问或导出不透明的产品账号记忆；
• 安装 Skill 不会自动恢复缺失的 Obsidian vault；
• SHA-256 提供完整性检测，不提供发布者身份认证；
• 不支持冲突内容的自动语义裁决，重要冲突需要当前证据或用户确认；
• 不自动提供加密、云存储或 Git 远端；
• Agent 没有可验证原生记忆时，会保持降级状态而不是伪造双记忆成功。

参与贡献

欢迎改进跨 Agent 兼容、隐私扫描、迁移契约和失败关闭行为。提交前请：

• 为行为变更先增加可失败的测试；
• 保持 Python 3.8+ 与标准库运行边界；
• 更新对应 reference、测试和 changelog；
• 不在 fixture、issue 或日志中放入真实用户账本、绝对个人路径、凭据或聊天；
• 运行完整测试、结构校验、链接检查和凭据扫描。

English summary

obsidian-user-memory is an Agent Skill for portable, auditable collaboration continuity. It treats a user-owned Obsidian ledger as the cross-agent authority, uses a fingerprinted lifecycle index for selective context loading, mirrors validated deltas only into documented agent-native memory mechanisms, and provides dry-run-first onboarding, export, restore, conflict protection, credential blocking, and fresh-context acceptance tests. It does not export chats, authentication, hidden model state, or opaque account memory.

License

This project is available under the MIT License.

---

可迁移的不是“同一个模型”，而是一套由用户拥有、能够验证和修正的协作连续性。