内容
# 系绳
**适用于个人代理的共享内存层，跨设备。** `系绳` 是一个 [MCP](https://modelcontextprotocol.io) 服务器，支持本地 SQLite 文件。任何与 MCP 兼容的代理都可以 `记住`、`回忆`、`链接` 和 `忘记` 持久性笔记 —— 关于您、您的项目、您的偏好的事实 —— 因此上下文跟随您，而不是在每个会话中都消失。
它在**仅本地运行，无需配置**。指向托管的 [libSQL/Turso](https://turso.tech) 主数据库，同一个文件成为嵌入式副本，近乎实时地同步您的记忆跨所有设备。
## 为什么
不久的将来，个人代理将生活在许多设备上 —— 笔记本电脑、台式机、手机。为了让它感觉像 *一个* 助手，而不是几个健忘的助手，记忆必须是一个可移植的基质：可从每个设备和任何代理读取和写入，而不是孤立在单个工具中。
`系绳` 就是这种基质。它故意设计为一个 *便利层* —— 它使代理在存在时更加有用，并且在降级时从不破坏代理的工作。
## 状态
v0.1 已实现。设计和原理：[`docs/superpowers/specs/2026-07-03-tether-design.md`](docs/superpowers/specs/2026-07-03-tether-design.md)。实现计划：[`docs/superpowers/plans/2026-07-03-tether-v0.1-implementation.md`](docs/superpowers/plans/2026-07-03-tether-v0.1-implementation.md).
## 设计概览
- **四个动词**，仅此而已：`记住` · `回忆` · `链接` · `忘记`。
- **写入时更新**，因此存储不会腐化成近似重复。
- **丰富的回忆**（id、type、title、body、tags、`updated_at`），以便代理可以判断陈旧性并引用它更新的内容。
- **自动加载的启动索引** —— 一个紧凑的单行每记忆列表，在每个会话中呈现给代理，因此即使代理没有想到搜索，记忆也会有所帮助。
- **本地优先，同步可选** —— 当未配置后端时，本地路径不受影响；降级从不抛出异常。
- **关键词搜索现在，嵌入以后** —— SQLite 架构已构建，以便语义搜索和完整的实体/边缘图可以直接插入，而无需迁移数据。
## 安装
需要在 POSIX 系统（Linux/macOS）上安装 Python ≥3.10。
使用 [uv](https://docs.astral.sh/uv/) 在 Claude Code 中注册：
```sh
claude mcp add 系绳 -- uvx 系绳-记忆
```
… 或者先安装：
```sh
pip install 系绳-记忆
claude mcp add 系绳 -- 系绳-记忆
```
（该软件包在 PyPI 上命名为 `系绳-记忆` —— `系绳` 已被保留为通用品牌名称。`系绳` 在 `claude mcp add 系绳 -- ...` 中只是 Claude Code 用来引用此服务器的标签；它不需要与已安装的命令匹配。）
默认情况下，记忆存储在本地 SQLite 文件 `~/.local/share/系绳/memory.db` 中（可通过 `TETHER_DB` 重写）。无需帐户，无需网络 —— 这是适用于单台机器的整个工具。
## 跨设备同步（可选）
将 系绳 指向 [Turso](https://turso.tech) / libSQL 数据库，本地文件成为嵌入式副本 —— 本地速度读取，写入传播到其他设备。安装额外组件并设置两个环境变量：
```sh
pip install '系绳-记忆[sync]'
export TETHER_SYNC_URL='libsql://<您的数据库>.turso.io'
export TETHER_SYNC_TOKEN='<您的身份验证令牌>'
```
如果后端无法访问，系绳记录 `同步离线` 并继续针对本地文件工作；当后端恢复时，写入会收敛。
## 语义搜索（可选）
默认情况下，`回忆` 是 **混合** 的：关键词（FTS5）结果与语义（向量）结果融合，因此查询即使在确切词语不同的情况下也能找到相关的记忆（“汽车”回忆起关于您的“车辆”的笔记）。语义回忆在本地运行一个小型 **静态** 嵌入模型 —— 无需网络，无需 API 密钥，无需其他依赖。安装额外组件：
```sh
pip install '系绳-记忆[semantic]'
```
无需额外组件（或设置 `TETHER_SEMANTIC=0`），系绳仅运行关键词 FTS5 —— 语义是一个纯粹的附加功能，永远不是必需品。第一次运行时，现有记忆会被一次性嵌入；之后便是增量式。
环境：
| 变量 | 默认值 | 效果 |
|---|---|---|
| `TETHER_SEMANTIC` | 开启 | 设置 `0`/`false`/`off` 以强制仅关键词回忆 |
| `TETHER_EMBEDDING_MODEL` | `minishlab/potion-base-8M` | 重写本地静态模型 |
## 合并（可选）
系绳保留一个被取代的事实，而不是覆盖它：当一个记忆被取代时，旧的记忆被标记为不再当前（保留历史）并从 `回忆` 和启动索引中排除。回忆还倾向于更倾向于最近的事实。两个可选行为进一步：
| 变量 | 默认值 | 效果 |
|---|---|---|
| `TETHER_CONSOLIDATE` | 关闭 | 开启（`1`/`true`）在写入时合并近似重复项 —— 取代旧事实而不是使存储碎片化（需要 `[semantic]` 额外组件） |
| `TETHER_DEDUP_THRESHOLD` | `0.92` | 需要的余弦相似度才能将两个事实视为重复项 |
| `TETHER_DECAY_HALF_LIFE_DAYS` | 关闭 | 设置一个正数，以指数方式降低旧事实在回忆中的排名 |
| `TETHER_AUTHOR` | 设备 ID | 在每个记忆上记录归属 |
合并永远不会删除 —— 只有 `忘记` 才可以。所有这些在语义额外组件缺失时都会降级为简单的关键词回忆。
## 联想回忆（可选）
`回忆` 不仅仅返回关键词/语义匹配项 —— 它遵循 **使用图** 到相关记忆，因此询问一件事会显示其连接的上下文。图的边来自三个本地、确定性的来源 —— 无需 LLM，无需网络：
- **语义** —— 嵌入的最近邻（需要 `[semantic]` 额外组件），
- **显式** —— `链接()` 动词，
- **赫布学习** —— 您一起回忆的记忆会随着时间的推移而相互连接。
每个命中都带有 `via` 凭单，说明为什么它被呈现（直接匹配或通过边缘），并且两个可选的 `回忆` 参数可以调整它：
| 参数/变量 | 默认值 | 效果 |
|---|---|---|
| `budget`（每次调用） | `TETHER_RECALL_BUDGET` | 跟随关联的程度；`0` = 仅直接匹配 |
| `session`（每次调用） | 时间分桶 | 分组相关回忆，以便它们相互促进 |
| `TETHER_ASSOC` | 开启 | 设置 `0`/`false`/`off` 以进行纯关键词+语义回忆 |
| `TETHER_RECALL_BUDGET` | `8` | 默认关联广度 |
| `TETHER_PROTECT_HEAD` | `8` | 锁定多少个顶级直接命中在关联之上 |
关联回忆是 **种子主导** 的：顶级直接匹配被锁定在原位，关联只填充它们下面的槽位 —— 因此开启关联永远不会使关键词/语义搜索已经高度排名的命中项降级。
当 `TETHER_ASSOC=0`（或 `budget=0`，或图为空）时，`回忆` 的行为与以前完全相同 —— 关联回忆纯粹是附加的，永远不会破坏查找。
## 自组织存储（可选）
随着存储的增长，系绳使用相同的用法图保持其可读性：
- **中心策划的启动索引**。自动加载的记忆索引在超过 `TETHER_BOOT_INDEX_CAP`（默认 50）且存在图时会被限制在上限之上。超过上限后，它显示两个标记的切片 —— **负载承载** 记忆（最高 *行为* 程度：`显式` 链接 + 学习共回忆，绝非简单相似性）和最新的记忆 —— 因此索引保持较小并显示实际重要的内容。在上限以下，或在没有图的情況下，它与以前一样，是完整的最新优先列表。
- **通过断开连接进行遗忘**（可选，`TETHER_FORGET`）。有界扫描每 `TETHER_FORGET_INTERVAL` 次写入，并 *软归档* 既 **旧**（`TETHER_FORGET_AGE_DAYS`，默认 90 天），又 **行为孤立**（无 `显式`/`赫布学习` 边 —— 语义相似性不计）的记忆。归档的记忆会从回忆和启动索引中删除，但 **保留并可逆**（它重用与合并相同的标记无效机制；不会删除任何内容）。安全防护措施：从不在没有实时行为图的情况下运行，在低于 `2 × CAP` 记忆或超过 `TETHER_FORGET_MAX_PER_SWEEP`（默认 10）每扫描的情况下运行。
| 变量 | 默认值 | 效果 |
|---|---|---|
| `TETHER_BOOT_INDEX_CAP` | `50` | 在此大小以上策划启动索引 |
| `TETHER_FORGET` | 关闭 | 启用遗忘扫描 |
| `TETHER_FORGET_AGE_DAYS` | `90` | 符合条件的最小年龄 |
| `TETHER_FORGET_INTERVAL` | `20` | 写入之间的扫描次数 |
| `TETHER_FORGET_MAX_PER_SWEEP` | `10` | 每次扫描的最大归档数量 |
当 `TETHER_FORGET` 关闭（默认）且存储大小正常时，回忆和启动索引的行为与以前完全相同。
## 结晶（可选，默认关闭）
当 `TETHER_CRYSTALLIZE=1` 时，系绳会反映：它检测相关记忆的密集簇，并为其命名。在反射过程中读取 `系绳://crystallization`（仅拉取，非自动加载）以获取候选簇；使用 `remember(..., crystallizes=[source_ids])` 命名一个真正的原则 —— 它写入原则并将其链接到其源上 —— 或使用 `dismiss_cluster(id_a, id_b)` 丢弃候选簇。簇由显式链接 + 用例（语义相似性填充成员资格）播种，因此这会找到 *“这些属于一起”* 的结构，而不是简单的主题相似性。系绳找到结构；您的代理提供词语。
结晶的原则成为启动索引的中心，并可从回忆中的源访问。注意：这使得“命名”成为继“使用”和“链接”之后的第三个重要性信号 —— 意大利面条判断某事物具有原则性是一个强烈的信号。
## 工具
| 工具 | 它做什么 |
|---|---|
| `记住(type, title, body, tags?, links?)` | 保存记忆；在 `type`+`title` 上更新以完善事实而不是重复 |
| `回忆(query, type?, limit?, budget?, session?)` | 混合关键词 + 语义搜索，然后跟随用法图到相关记忆；返回 id/type/title/body/tags/updated_at + 一个 `via` 凭单 |
| `链接(id_a, id_b)` | 两个记忆之间的双向链接 |
| `忘记(id)` | 删除记忆 |
以及一个自动加载的资源 `系绳://memory-index` —— 一个紧凑的每记忆一行索引，在每个会话中呈现。
## 许可证
MIT
