MemTether：为所有AI客户端赋予统一共享记忆的开源中间层

1. 项目缘起：当每一个 AI 客户端都“失忆”，我决定自己动手

先说说我为什么折腾出 MemTether 这个东西。过去半年，我手头常开的 AI 客户端至少有四五个：ChatGPT 网页版、Claude 的桌面端、本地部署的开源模型、还有手机上装的各种 AI 助手 App。每个客户端都很聪明，但问题是它们之间完全不通气——我在 ChatGPT 里交代清楚了项目的背景资料，切到 Claude 那边又得重新讲一遍；本地模型好不容易调教好了回答风格，换一个客户端又打回原形。最崩溃的是长对话场景，我经常要把前面十几轮的关键结论复制出来，当作“临时记忆”粘到新的对话里，格式乱、长度超限、还容易漏掉细节。时间一长，我意识到真正缺的不是另一个更聪明的模型，而是一个能让所有 AI 客户端共享同一份记忆的中间层。

市面上不是没有记忆方案，比如各种记忆插件、长期记忆 API、上下文压缩工具，但它们大多绑定某一个特定客户端或者某一家云端服务，换工具就失效。而且很多方案是“黑盒”，数据存在别人服务器上，我不放心。我想要的其实很简单：一份记忆文件，存放在我自己手里，格式完全开放，任何 AI 客户端通过标准接口都能读写。这就是 MemTether——一个把多个 AI 客户端的记忆统一管理起来的开源工具。它的定位不是替代任何模型或客户端，而是做那个连接所有客户端的“记忆中枢”。名字里 Tether 是系绳的意思，我用一根绳子把散落在各个客户端的记忆碎片全部串起来，让每个客户端都拥有同一个大脑。

这个项目最近在社区里陆续有人试用，反馈最集中的一句话是“终于不用重复复制粘贴了”。从实际效果看，MemTether 解决的不只是省事的问题，更重要的是让跨客户端的对话变得连续：我在 A 客户端聊了一半的需求分析，到 B 客户端可以直接接着问“根据刚才的记忆，帮我拟一份框架”，不需要任何补充说明。这篇文章我会从设计思路、核心实现、部署步骤、踩坑记录几个方面完整复盘这个项目，适合正在做 AI 工具集成、想给自己的多客户端工作流加“记忆”的朋友参考。

2. 整体设计思路：我为什么把记忆做成了“中间层”

2.1 先想清楚一个问题：AI 的“记忆”到底指什么

动手写代码之前，我花了不少时间想一个问题：所谓“共享记忆”，共享的到底是什么东西？如果只是把聊天记录堆在一起，那每个客户端本来就各自存着历史记录，根本不需要额外共享。真正有意义的是把对话中沉淀下来的“可复用信息”抽取出来，变成一份结构化的、可以被新的对话直接加载的上下文。举个例子，我在 ChatGPT 里讨论过某个项目的技术选型，最后确定了后端用 Go、数据库用 PostgreSQL，这个结论是“记忆”；而我当时问过的那些发散性问题、来回试错的讨论过程，虽然也是一段对话历史，但对新会话的参考价值不大。

所以 MemTether 的记忆模型不是简单地存聊天日志，而是把记忆项抽象成“键值化”的信息条目。每条记忆就是一个独立的记录，包含内容本身、来源客户端、写入时间、标签、失效时间等元数据。这样做的好处有两个方面：一方面，任何客户端读写记忆的时候不需要解析冗长的对话文本，直接操作结构化条目就行；另一方面，记忆的更新可以做到“精准覆盖”——比如技术选型变了，新写入的一条记忆直接替换旧的那条，而不是让新旧两条矛盾的信息同时存在。

这个设计和人脑的记忆机制有点像：短期记忆经过整理沉淀为长期记忆，长期记忆里过时的部分会被更新或遗忘。MemTether 就是把这套机制外置成了一个工具。我在设计初期也考虑过直接用向量数据库做语义记忆，让 AI 客户端按照“相似度”自动检索相关记忆，后来在实际测试中放弃了。原因很简单：语义检索虽然灵活，但结果不确定，今天检索出的内容和明天可能不一样，这对需要稳定上下文的场景反而是缺点。MemTether 更偏向“精确记忆”路线，每条记忆有明确的标识和内容，读出来就是写进去的样子。

2.2 三个核心模块：存储、同步、适配

MemTether 的整体架构划分为三个层次，每一层解决一类特定问题。

第一层是存储层，负责记忆的持久化。这一层我选用了 SQLite，原因很务实：单文件、零配置、不需要单独跑一个数据库服务，备份就是复制一个文件，部署成本几乎为零。对于个人使用或者小团队内部共享，SQLite 的性能完全够用，哪怕记忆条目积累到几万条，查询速度依然是毫秒级。如果你未来要支撑大量并发读写或者多节点部署，存储层我也留了接口，可以替换成 PostgreSQL，但那是后话，90% 的场景用 SQLite 就够了。

第二层是同步引擎，负责处理“多客户端同时读写同一份记忆”时的冲突与一致性问题。这一层是 MemTether 的核心价值所在。多个客户端不可能串行排队读记忆，现实场景一定是并发的：A 客户端正在写入一条新记忆，B 客户端同时要读取现有记忆。如果同步逻辑做得粗糙，会出现读取到不完整的数据、写入互相覆盖等问题。我采用的是“基于版本号的乐观并发控制”策略——每条记忆记录都有一个版本号字段，写入时必须携带读取时的版本号，如果版本号对不上，说明这条记录在读取之后被其他客户端改过了，写入请求会被拒绝，客户端可以选择重新读取再写入。这套机制在分布式系统里比较常见，但用在一个单文件工具里效果意外地好，实现简单而且不会出现脏写。

第三层是 API 适配层，负责让不同 AI 客户端以各自的“母语”接入 MemTether。这是整个项目里工作量最大、也最容易被低估的部分。不同 AI 客户端的“记忆能力”形态差异很大：有些客户端支持 API 调用，我可以直接通过 HTTP 请求读写记忆；有些客户端本身没有开放接口，但支持自定义指令或者插件系统，我可以通过对话指令触发记忆的写入和读取；还有些小工具只有配置文件，没有接口能力，那就提供命令行工具，让用户在终端里手动操作记忆。

三层各司其职后，整体数据流大概是这样的：某个 AI 客户端在对话中产生了一条重要结论 → 通过 API 适配层交给同步引擎 → 校验版本号、写入 SQLite → 其他客户端发起记忆查询 → 适配层收到请求、查询存储层 → 返回结构化的记忆内容 → 新对话自动加载这些上下文。整个过程对用户是透明的，没有感知。

3. 核心细节解析：记忆项设计、版本控制与指令协议

3.1 记忆项的数据结构：一张表打天下

MemTether 的存储层核心就一张表，我把字段精简到了不能再精简的程度。每个记忆项有这些字段：

• id：全局唯一标识，使用 UUID，保证多客户端写入时不会出现主键冲突。
• key：业务键，相当于这条记忆在业务逻辑中的“名字”，比如project.tech_stack。同一个 key 下的记录是互斥的，新写入会覆盖旧的。
• content：记忆的具体内容，纯文本，一般建议写成结构化描述，比如“后端使用 Go 1.22 版本，数据库选用 PostgreSQL 16”。
• source：记录来源，标识是哪台客户端写入的，方便以后排查“这条记忆是从哪来的”。
• version：整数版本号，每次更新加一，用于并发控制。
• tags：标签列表，JSON 数组格式，方便按主题检索，比如["项目A", "技术选型"]。
• created_at和updated_at：两个时间戳，分别记录创建时间和最后更新时间。
• expires_at：过期时间，可以为空，不设置则永久有效。这个字段对处理“临时记忆”场景非常有用。

你可能注意到我没有给每个客户端单独建表，而是所有客户端共享同一张表。这是有意为之——不同客户端产生的是同一份记忆的不同片段，混在一起反而自然，查询的时候靠source字段过滤来源即可。如果每个客户端一张表，那就又变成了几个孤立记忆库，违背了“共享”的初衷。

3.2 版本控制与冲突合并：最容易被忽略但最重要的一环

多客户端共享记忆，最怕的一件事就是“覆盖”。我举个例子，你在 ChatGPT 里更新了项目的部署地址，然后切到本地模型那边，它读到的还是旧地址，如果你又基于旧地址改了一版新配置写回记忆，ChatGPT 那边刚更新的内容就被无声无息地覆盖了。这种类似“两个人同时编辑同一份文档”的问题，如果不做处理，用不了几天记忆就乱了。

MemTether 的做法是给每条记忆加版本号，所有写操作都必须携带版本号条件。SQL 层面就是标准条件更新：UPDATE memories SET content = ?, version = version + 1 WHERE id = ? AND version = ?，这个 SQL 执行后如果影响行数为 0，说明版本不匹配，写入失败，返回冲突错误。客户端收到冲突提示后可以主动重新读取最新的记忆内容，再决定是覆盖还是合并。当然，实际使用中会有一些客户端不太会处理冲突，对这种情况 MemTether 也提供了一个配置项conflict_policy，可选三种策略：reject（默认，只拒绝不合并）、force（强制执行覆盖，适用于确定来源的更新）、merge（自动把新旧内容拼接，适用于补丁式更新）。

这里我要多说一句，实际开发过程中我在冲突策略上走了不少弯路。最初的版本我设计了很复杂的自动合并算法，试图理解新旧内容的结构差异然后智能拼接，结果测试下来错误率很高，有时候合并出来的内容完全是两段话的机械拼装。后来想明白了，自动合并是“过度设计”——大部分冲突场景下，用户很快就知道哪个版本是新的，做法是重新写入一次。与其自作聪明地合并，不如把判断权交还给客户端，所以默认策略定为reject。真实世界的经验就是这样，能做减法的时候不要做加法。

3.3 指令协议设计：让自然语言也能读写记忆

有接口能力的客户端可以走 REST API，但现实里不少客户端只能对话，没有开放编程接口。为了让这些客户端也能用上 MemTether，我设计了一套对话指令协议：用户直接在输入框里用特定格式的指令操作记忆。指令集维持在最小可用范围：

• /tie key <名称> <内容>：把一条信息写入记忆，指定业务键名称。
• /untie key <名称>：删除一条记忆。
• /tie ls：列出当前所有记忆，带标签过滤。
• /tie get key <名称>：读取指定 key 的记忆内容。
• /tie forget [tags]：批量清理过期记忆或按标签清理。
• /tie sync：手动触发一次全量同步，让当前客户端的上下文加载所有记忆。

指令通过适配层解析，实际执行仍然是调用底层的同步引擎接口。引导语（system prompt）部分是适配层的核心之一，每个客户端接入时都需要配置一段提示词，告诉模型它具备操作记忆的能力以及指令格式是什么。这一步做得好不好，直接决定了客户端能不能正确响应指令。以 ChatGPT 接入为例，我在 system prompt 里写了类似“你可以通过调用记忆工具接口读写共享记忆，用户使用斜杠指令时请识别并触发对应操作，不要自作主张改写指令内容”这样的描述。实测下来，模型对于严格格式指令的理解和执行正确率相当高，出错概率不到 5%。

4. 实操部署与核心实现：从零到一跑通 MemTether

4.1 环境准备与依赖选择

部署 MemTether 需要准备的东西非常少，这点也是我立项时给自己定的硬性要求：“轻量”是第一诉求。跑通一个最小实例只需要三样东西：Python 3.10 以上版本、一个终端、一个 HTTP 客户端（用来测试接口，比如 curl 或者直接用浏览器）。数据库用 SQLite，不需要额外安装进程。如果你打算用 Docker 方式部署，官方仓库里也提供了现成的镜像和 docker-compose 配置，往下看。

我本人在开发环境里是用uv管理的 Python 虚拟环境，这比传统的 pip+venv 方案快不少，依赖解析也干净。如果你不想引入 uv，直接用 pip 也没问题，核心依赖只有 FastAPI、uvicorn 和 pydantic，加在一起也就三个包。FastAPI 负责提供 REST API，底层的接口定义我用 pydantic 做请求参数校验，这样客户端发来不合法请求时能快速返回 400 错误，接口层更健壮。

4.2 完整部署流程（以本地模式为例）

第一步，先把仓库克隆到本地：

git clone https://github.com/yourname/MemTether.git cd MemTether

第二步，创建虚拟环境并安装依赖：

python3 -m venv .venv source .venv/bin/activate pip install -e .

第三步，初始化配置文件。首次启动时会自动生成memtether.yaml，内容结构如下：

storage: database_path: ./data/memtether.db conflict_policy: reject server: host: 127.0.0.1 port: 8420 api_key: your_secret_key_here memory: default_ttl_days: 365 max_memory_items: 10000

配置文件里的几个关键参数我逐个解释一下。database_path控制 SQLite 文件的存放位置；conflict_policy对应前面说的三种并发冲突处理策略；server.host和port决定服务的监听地址，如果打算给局域网内的其他设备共享记忆，可以改为0.0.0.0；api_key是接口的访问凭证，客户端调用 API 时必须携带，否则拒绝服务；memory.default_ttl_days定义了无显式过期时间的新记忆默认有效天数，设成 365 意味着一年后没有更新的记忆会被标记过期，避免长期积累导致记忆库膨胀；max_memory_items是一个防御性参数，防止记忆条目无限增长。

第四步，启动服务：

memtether start

看到日志输出MemTether server started on http://127.0.0.1:8420就说明启动成功了。

第五步，验证基本读写功能。我用 curl 做了写入和读取两条测试：

curl -X POST http://127.0.0.1:8420/v1/memories \ -H "Authorization: Bearer your_secret_key_here" \ -H "Content-Type: application/json" \ -d '{"key": "project.tech_stack", "content": "后端使用 Go 1.22，数据库选用 PostgreSQL 16"}' curl http://127.0.0.1:8420/v1/memories/project.tech_stack \ -H "Authorization: Bearer your_secret_key_here"

写入接口返回 201 状态码和一条带id、version=1的记录体，读取接口返回这条记忆的完整信息。到这一步，一个最小可用的 MemTether 实例就部署完毕了。

提示：实际测试中发现 FastAPI 默认的127.0.0.1绑定只能在本地访问，如果你在 WSL2 里跑服务、宿主机那边访问不通，多半是 host 配置成了localhost，改成0.0.0.0并检查防火墙即可。

4.3 接入第一个 AI 客户端：以 OpenAI 兼容接口为例

MemTether 的 API 适配层对外提供了标准的 OpenAI 兼容封装，这意味着任何支持自定义 Base URL 的 AI 客户端都可以直接接入，不需要额外写代码。这算是我在设计时的一个“偷懒”决策：OpenAI 的 API 格式是目前最普及的接口标准，几乎所有主流客户端都支持改成第三方 Base URL，与其为每个客户端各写一套接入方案，不如直接把 MemTether 做成一个兼容的“伪后端”。

具体操作是，在客户端的设置里找到 API Base URL 配置项，把它指向http://127.0.0.1:8420/v1，然后在 API Key 处填配置文件里设置的api_key。这样客户端的每次对话请求都会经过 MemTether，MemTether 在转发到真正的大模型后端之前，会自动把匹配的记忆注入到请求的 system prompt 中,并在响应结束后把新产生的关键信息以记忆项的形式写回存储。

这里有一个关键的工程细节：如何在对话流中识别出“哪部分信息值得记忆”？我在适配层里放了一个小型的规则抽取器，它监听所有经过的对话消息，一旦捕获到key: value格式的内容（比如“技术栈: Go 1.22”），或者检测到用户显式触发了/tie指令，就提取并写入记忆库。这个规则处理策略比让模型自动判断要可靠得多——模型判断有时会漏，有时会乱写，规则匹配的结果则稳定可预测。

4.4 给本地模型调试用：通过命令行工具操作记忆

不是所有客户端都有接口能力，所以我额外写了一个命令行工具memtether-cli，方便用户在终端里直接操作记忆。常用命令：

# 列出所有记忆 memtether-cli list # 按标签过滤 memtether-cli list --tags "项目A" # 写入记忆 memtether-cli set project.name "MemTether" # 获取指定记忆 memtether-cli get project.name # 删除记忆 memtether-cli delete project.name

命令行工具和 API 走的是同一套底层逻辑，只是在入口处换成了 CLI 参数解析。这个工具在调试阶段帮了我大忙——我经常在写完代码后直接敲几条命令验证记忆读写是否符合预期，比通过客户端反复对话测试快多了。建议所有接入 MemTether 的用户先把这个 CLI 工具跑熟，再配置客户端，排查问题时心里有底。

5. 进阶用法与场景扩展：共享记忆还能这样玩

5.1 多用户隔离与项目级记忆空间

个人用 MemTether 读写自己的记忆，功能已经够用，但一旦让一个小团队共享同一个服务，就必须考虑多用户和数据隔离问题了。MemTether 从设计之初就预留了命名空间字段——每条记忆都属于一个命名空间，API 路径中带namespace参数，默认值为default。团队使用时可以为每个项目或每位成员分配独立的命名空间，比如namespace=project-alpha，不同命名空间之间的记忆完全物理隔离，互不可见。

隔离粒度的选择我对比过按项目隔离和按用户隔离两种方案，最后取了折中：默认按项目命名空间隔离，同时允许在每个命名空间内配置多个用户，用户之间可以共享该项目的记忆。这样做的理由是，团队协作场景下“按项目分组”更符合人的直觉——同一项目的成员天然需要共享上下文，而不同项目之间才需要隔离。如果你有更细粒度的需求（比如同项目内不同角色的成员记忆不同），可以在应用层加一层过滤逻辑，MemTether 不会限制你。

5.2 触达外部系统：Webhook 与定时任务

记忆的本质是上下文信息，而上下文不应该只在 AI 会话中流转。我在 MemTether 里增加了 Webhook 触发机制，当某条记忆更新时，可以主动推送到外部系统，比如发消息到团队群、调用自动化工作流或同步到另一个知识库。Webhook 配置也是写在memtether.yaml里的：

webhooks: - name: team_chat url: https://yourteamchat.example.com/hooks/memtether events: [memory.created, memory.updated] namespaces: [default, project-alpha]

这个功能的典型场景是，当 AI 客户端在一次会话中确认了某个重要决策（比如确定发版日期），改写记忆的同时，通过 Webhook 把消息推送到团队群，让没在对话里的人也能实时感知信息变更。我实际试下来，这个机制比手工转发消息好用得多，信息从对话到群里的延迟在毫秒级。

另一个扩展是定时任务，MemTether 内置了一个轻量调度器，可以按 cron 规则定期整理记忆库，比如每天清理过期标记超过 30 天的记忆、每周导出记忆摘要发送到指定接口。定时任务模块的代码量控制在很小的范围，没有引入 celery 那类重量级任务框架，因为 MemTether 的任务形态很简单，就是“到点执行一个本地函数”。

5.3 跨客户端保持一致风格：调教模板共享

说一个我自己实际使用中摸索出来的玩法。用本地大模型的朋友应该知道，不同模型的性格差异巨大，同一个 prompt 在 GPT 里好用的语气，在本地模型那边可能完全不对味。共享记忆这个特性，天然也可以用来共享“调教经验”。我给自己定义了一条特殊命名规则：凡是 key 以style.开头的记忆，都是风格调教内容，比如style.tone存“回答要简洁、直接、不卖弄”，style.detail_level存“技术细节要深入，但先给结论”。

接入的时候，系统 prompt 里固定加上一句“加载所有style.*前缀的记忆作为发言风格参考”。这样本地模型在接入的一瞬间就“继承了”我在云端客户端积累的调教成果。之前换一个模型就要重新磨半天的情况，现在完全不存在了。这个玩法没有写进任何文档，算是隐藏菜单，但实用性真的很高。

6. 常见问题与排查实录：踩过的坑和解决办法

6.1 问题速查表

用表格把这段时间集中遇到的高频问题记录如下，方便后来者对照排查。

6.2 印象最深的一个坑：并发冲突导致“记忆分裂”

在我自己动手用了一阵子之后，出现了一个很隐蔽的问题：同一个 key 下出现了多条内容不同的记录，读取的时候随机返回其中一条。这个问题排查了很久才定位到根因——写入接口和读取接口在代码里走了两条路径，写入路径遵守了版本号校验，读取路径却没过滤版本号，只拿了创建时间最近的一条。当两个客户端并发写入同一条 key 时，后写入的那条虽然在业务上覆盖了旧值，但 SQLite 里的旧记录并没有被真正删除，只是版本号变了。而读取接口按时间排序后总觉得“最新写的”应该就是最新版本，忽略了并发场景下时间戳未必可靠。

最终修正方案是彻底放弃按时间戳取最新值的逻辑，强制读取时也按version字段排序，同时每次写入都物理删除同 key 下的其他版本记录，确保同一时间一个 key 只存在一条有效记忆。这个教训也让我认识到，哪怕是一个单机工具，只要涉及多写入方，并发语义就不能图省事，“乐观锁 + 条件更新 + 按版本读取”这套组合拳必须完整落地，缺一个环节都会出隐藏问题。

6.3 本地大模型与云端模型接入差异：记忆格式的兼容问题

本地开源模型和云端模型在记忆格式上的兼容性，我最初完全没预料到会出问题。云端模型对结构化 prompt 的理解能力强，你给它一段“key-value 配标签”的记忆格式，它能很顺畅地吸收并运用；但本地小参数模型在指令遵循方面明显弱一些，遇到复杂的记忆格式时经常“理解不到位”，导致内容被错误地截断或者忽略。

解决方案是让适配层在注入记忆到 system prompt 时做差异化处理：云端模型走完整结构格式，本地模型则精简为纯文本摘要，去掉复杂的标签体系，只保留核心内容。实现上就是在 API 适配层的注入函数里加了一个配置参数memory_format，可选structured和plain两种模式。如果你同时接入了云端和本地客户端，建议分别给它们配置对应的格式，不要一刀切。

6.4 一个容易忽视的体验问题：记忆过载

共享记忆的价值在于“精准”，而不是“量大”。我在测试中发现，如果往记忆库塞了很多边缘信息，模型在每轮对话前都被迫加载巨量上下文，效果反而会下降。具体表现为：回答变啰嗦、抓不住重点、甚至编造出和记忆无关的内容。这是因为模型对 long context 的处理能力有限，大量低质量记忆相当于增加了大量噪声。

面对这个问题，我明确了两条纪律。第一，default_ttl_days不要设太长，个人使用建议 90 天左右；第二，写入记忆前先判断信息价值——只有“未来还会用到的事实性结论”才值得记，临时的、一次性的信息不要进记忆库。我也在文档里把这些使用建议写清楚了，避免使用者无脑堆量后觉得工具不好用。毕竟工具再好，使用方式不对也会出反效果。

7. 我在实际使用中的几条体会

最后分享几条我在 MemTether 落地使用之后的实际体会，可能比上面那些技术细节更能帮你少走弯路。

第一，共享记忆最大的价值不是省复制粘贴，而是让你在多个模型之间切换时，可以真正做到“观点连续”。同一个问题，白天用 GPT 讨论了一半，晚上切到本地模型继续深挖，它知道白天所有结论，这种连续性是单客户端时代完全无法体验的。我现在的日常使用已经离不开这种方式了。

第二，记忆数量控制在合理的范围内。我现在个人的记忆库长期维持在三四百条左右，以项目级粒度分 key 存储。超过五百条我就明显感到模型上下文质量的下降，这时候做一次大扫除，把过时和低价值的记忆清掉，效果立刻回升。与其写“永生记忆”，不如写“及时记忆”。

第三，如果你在考虑是否采用类似 MemTether 的方案，劝你注意一点：不要期待所有客户端都能无缝接入，接口适配的工作量取决于客户端的开放程度。MemTether 尽量降低了这个工作量，但遇到不开放接口、不支持自定义指令的客户端，还是只能退而求其次地手动操作。选工具的时候预留一个支持命令行操作的方案，总比被某个客户端卡住要好。