如果你同时使用 Hermes、Codex、opencode 等 AI 工具，很容易遇到一个具体而烦人的问题：白天在公司电脑上和 AI 讨论了几个小时，晚上回到家，换一台电脑后，AI 又像第一次见面一样。
这不是模型突然变笨了，而是上下文通常被保存在当前设备、当前目录或当前工具的本地环境里。设备一换，之前积累的对话、项目约定和工作状态也就跟着丢了。
agentctxsync（Agent Context Sync）的出发点很直接：让 Agent 的上下文能够在不同设备之间同步。这个项目由道荣和露发起并开源，源于他们长期使用多种 AI 工具时对“记忆绑设备”问题的切身体验。
真正丢失的不是聊天记录
“记忆”这个说法容易让人想到完整的聊天历史，但对于开发工作来说，更重要的往往是几类持续状态：
- 项目背景：这个仓库解决什么问题，主要模块如何组织。
- 工作约定：代码风格、测试命令、提交规范和不能触碰的目录。
- 已完成事项：哪些方案已经尝试过，哪些问题已经定位。
- 当前上下文：正在修改哪个模块，下一步准备验证什么。
- 用户偏好：希望 AI 输出多详细，是否需要先给计划，哪些操作必须确认。
这些内容如果只存在于某台电脑上的工具目录里，换设备后就需要重新解释。重复沟通不仅浪费时间，还可能让 AI 重复执行已经失败过的方案。
因此，跨设备同步的核心并不是简单地把所有聊天记录复制一遍，而是把适合长期复用的 Agent 上下文整理成可迁移、可版本管理的文件或数据，再在不同工作环境中恢复它们。
一个可落地的同步模型
如果要自己实现一个最小版本，可以先把上下文拆成三层：
- 全局上下文：适用于所有项目，例如个人偏好和通用工作方式。
- 项目上下文：只适用于某个仓库，例如架构说明、测试命令和约束。
- 会话上下文：当前任务的短期状态，例如已尝试的方案和待办事项。
可以采用目录加 Markdown 文件的方式保存。它足够透明，也便于 Git、云盘或其他同步工具处理。下面是一个示例目录：
.agent-context/
├── global.md
├── project.md
└── sessions/
└── 2025-01-15-auth-refactor.md
一个项目上下文文件可以这样写：
# Project Context
## Repository
- Backend service written in Python.
- Main application code is under `src/`.
## Commands
- Install: `python -m pip install -r requirements.txt`
- Test: `python -m pytest`
- Lint: `python -m ruff check .`
## Constraints
- Do not change database migrations without explicit confirmation.
- Add a regression test for every bug fix.
## Current Work
- Refactoring token refresh handling.
- The next step is to run the authentication test suite.
这些内容不是模型的“永久记忆”，而是明确、可检查的工作材料。Agent 启动时读取它们，任务结束时更新它们，就能在另一台电脑上恢复相近的工作状态。
用一个小脚本验证同步流程
下面的 Python 示例演示一个最小同步流程：把上下文目录打包到指定位置，并在另一台设备上解包。示例假设同步目标是一个本地目录；实际使用时可以替换成 Git 仓库、共享目录或对象存储。
运行前，将脚本保存为 sync_context.py，并准备一个 .agent-context 目录：
from __future__ import annotations
import argparse
import shutil
from pathlib import Path
def sync_context(source: Path, destination: Path) -> None:
if not source.is_dir():
raise SystemExit(f"Context directory does not exist: {source}")
destination.parent.mkdir(parents=True, exist_ok=True)
archive = shutil.make_archive(
str(destination.with_suffix("")),
"zip",
root_dir=source.parent,
base_dir=source.name,
)
print(f"Created: {archive}")
def restore_context(archive: Path, destination: Path) -> None:
if not archive.is_file():
raise SystemExit(f"Archive does not exist: {archive}")
destination.mkdir(parents=True, exist_ok=True)
shutil.unpack_archive(archive, destination)
print(f"Restored to: {destination}")
parser = argparse.ArgumentParser(description="Sync Agent context")
subparsers = parser.add_subparsers(dest="command", required=True)
push = subparsers.add_parser("push")
push.add_argument("source", type=Path)
push.add_argument("archive", type=Path)
pull = subparsers.add_parser("pull")
pull.add_argument("archive", type=Path)
pull.add_argument("destination", type=Path)
args = parser.parse_args()
if args.command == "push":
sync_context(args.source, args.archive)
else:
restore_context(args.archive, args.destination)
在第一台电脑上执行：
python sync_context.py push .agent-context /tmp/agent-context
把生成的 /tmp/agent-context.zip 放到第二台电脑后执行：
python sync_context.py pull /tmp/agent-context.zip .
这个示例只演示数据搬运。真正接入 Agent 工具时，还需要确定两个触发点：启动时从哪里加载上下文，以及任务结束时由谁负责更新上下文。可以把这两个动作放进项目脚本、Shell hook 或工具支持的初始化流程中。
同步之前，先处理安全边界
上下文文件很容易包含敏感信息，因此不能把整个工具目录无差别同步。实践中至少要注意以下边界：
- 不要同步 API Key、访问令牌、Cookie 和 SSH 私钥。
- 将
.env、凭据目录和缓存目录加入忽略规则。 - 对会话上下文做筛选，避免把客户数据、内部代码片段或个人信息写入共享仓库。
- 如果通过 Git 同步，提交前检查 diff，而不是默认相信自动化脚本。
- 对全局上下文和项目上下文设置清晰的优先级，避免旧内容覆盖当前项目约定。
一个简单的忽略文件可以这样开始：
.agent-context/secrets/
.agent-context/.env
.agent-context/sessions/private/
*.token
*.key
同步也会带来冲突问题。两台设备都修改了同一个上下文文件时，最稳妥的做法通常不是静默覆盖，而是保留版本、报告冲突，并要求用户明确合并。上下文是工作状态的一部分，错误覆盖的代价可能比丢一条普通聊天消息更高。
开源项目的价值不只是“能同步”
agentctxsync 解决的是 AI 工具使用中一个很现实的摩擦点：用户的工作方式已经跨越多台设备、多个 Agent，但上下文仍然被锁在单个本地环境里。
这类工具的价值还在于把隐性的使用习惯变成可以观察和改进的工程资产。上下文一旦文件化，就可以查看历史变化、复用成熟约定，也可以在更换模型或工具时继续使用，而不必从零开始描述项目。
当然，文件化同步并不能自动解决所有记忆问题。上下文需要定期整理，过时的规则需要删除，短期对话也不应无限累积。一个更可持续的工作流通常包括：
- 用全局文件记录稳定偏好。
- 用项目文件记录仓库事实和执行命令。
- 用会话文件记录当前任务和决策过程。
- 在任务结束时压缩、归档或删除无效内容。
- 同步前检查敏感数据和冲突。
采用前的检查清单
如果你也经常在公司电脑、家用电脑和远程开发环境之间切换，可以先从一个小范围开始：
- 只同步一个低风险项目。
- 先建立
global.md和project.md，不要一开始搬运全部聊天记录。 - 明确 Agent 的加载和更新时机。
- 为敏感文件配置忽略规则。
- 保留历史版本，避免自动覆盖。
- 观察一周后删除不会被复用的内容。
AI Agent 的能力不只体现在模型回答得多好，也体现在它能否持续理解你的项目和工作方式。agentctxsync 的开源尝试提醒我们：在多设备、多工具协作成为常态之后，Agent 上下文也需要像代码一样被保存、同步和维护。