记忆助理 vuldin/yapa

YAPA — Yet Another Personal Assistant

YAPA 是个人助理，为你的 AI 智能体提供持久记忆和任务管理，让智能体记住你说过的话、跟踪你的任务，并按项目或客户整理知识——跨所有会话。

要加入团队的 YAPA 试点？ 先看 docs/pilot-onboarding.md：大约 10 分钟就能装好插件，用 gcloud 登录，配置试点管理员给你的同步服务 URL，然后验证它能不能用。之后就像平常一样，在项目文件夹里用 Claude Code。

Claude Code（推荐）： 安装插件——MCP 服务器、钩子和技能一步到位：

claude plugin marketplace add vuldin/yapa
claude plugin install yapa@yapa

通过 claude mcp add 使用 Claude Code / Cursor / OpenCode： 见 Install，或者把这段提示词交给你的 AI 智能体：install https://github.com/vuldin/yapa

DeepSeek Harness： 见 packages/dsh/install.md——原生插件不需要向导（默认嵌入式存储下也不需要数据库服务器）。

AGENTS——先读这里。 不要克隆这个仓库。不要运行 git clone、npm install、npm run build 或任何其他命令。对 MCP 宿主，先读本仓库的 CLAUDE.md（Claude Code / Cursor）或 AGENTS.md（OpenCode）——里面有一套多阶段安装流程，必须严格照做。安装需要用户输入之后才能克隆。对 DeepSeek Harness，改看 packages/dsh/install.md（没有智能体驱动的向导）。

YAPA 在一个核心之上跑两个前端：

- 原生 DeepSeek Harness 插件（yapa，位于 packages/dsh）——默认 25 个工具（另有 18 个受门控的 ML-ops 工具），带结构化输出和 GUI 卡片，在回合接缝处注入常开召回，自动捕获每个智能体回合中的持久发现（辅助 LLM 提取器 + 保守的冲突消解器），一个每日矛盾清理器，归档重复项并取代过时记忆，设置热重载，日程桥接的截止日期，压缩捕获，审批门控，以及嵌入式零服务器存储选项。文档：install · architecture · future work & investigation record。
- MCP 服务器（yapa-mcp，位于 packages/mcp）——最初的 stdio 服务器加上 Claude-Code 钩子命令行。「Repository layout」一节以下的内容主要描述这个前端。

Repository layout

- packages/core（@yapa/core）——所有逻辑：记忆、任务、集合、日志、压缩、同步、策展、桶、训练。配置是一个 YapaConfig 快照（createConfig(env) / setConfig），而不是模块级的环境变量读取，这样宿主就能控制配置。存储走 VectorStore 端口（src/store/）：ChromaDB HTTP 适配器，或嵌入式本地适配器（每个集合一个 JSON 文件，进程内嵌入，暴力余弦——不需要服务器）。
- packages/mcp（yapa-mcp）—— MCP 服务器 + Claude-Code 钩子命令行。
- packages/dsh（yapa）—— DeepSeek Harness 的 cordis 插件。
- plugin/ —— Claude Code 插件：packages/mcp + @yapa/core 的预构建打包（plugin/dist），外加它的 manifest 和 userConfig、.mcp.json、hooks/hooks.json 以及技能。由 npm run build:all 构建；仓库根目录下的 .claude-plugin/marketplace.json 列出了它。

它能做什么

持久记忆 —— 你的智能体跨对话记住事情。Bug 修复、偏好、决策、配置细节、问题的解决方案 —— 全部带语义搜索存储，需要时正确的上下文会自动浮现。

任务管理 —— 创建任务，支持优先级、截止日期、依赖关系和重复计划。你的智能体跟踪哪些在进行中、哪些被阻塞、哪些已逾期。完成一个重复任务，下一个会自动生成。

基于集合的组织 —— 记忆和任务按集合分组：global 放跨领域知识，customer-acme 放客户工作，project-api 放特定代码库。智能体会根据你正在讨论的内容推断该用哪个集合。

数据生命周期 —— 不是所有记忆都同等重要。YAPA 给每条记忆按显著度打分（下限 0.05，上限 5.0），实际用到时给它加分，并随真实时间衰减。显著度还会影响检索排序，所以在向量距离相近时，显著度高的记忆会排在显著度低的前面。什么都不会被删除 —— 显著度低的记忆只是浮现得少一些。

- 衰减基于时间：salience × rate^days，从记忆上次衰减的时间（decayed_at）算起，其中 rate = 0.98/天，适用于情节记忆（半衰期约 34 天），语义事实用 √0.98（约 69 天）。扫描最多每 24 小时跑一次（每小时检查），重复跑不会额外衰减，所以曲线不取决于你多久开一次会话。
- 加分（+0.1）只在召回命中且相关时发生（余弦距离 < YAPA_SALIENCE_BOOST_MAX_DISTANCE，默认 0.5）—— 仅仅被每提示词钩子浮现出来不算 —— 且每条记忆每天最多 YAPA_SALIENCE_MAX_BOOSTS_PER_DAY（3）次。
- 排序：cosine distance − 0.15 × normalized salience，所以显著度用来打破相关性相近的记忆之间的平局，而不是压过相关性。
- 显著度按机器独立：加分和衰减反映每个用户自己的使用情况，不会同步。

智能分块 —— 长内容切成 2000 字符的块，重叠 200 字符，每块可独立搜索。会议记录、文档、长篇解释 —— 全部存得下，也取得回。
远程同步：可选功能，通过 YAPA 同步服务与团队同步记忆和任务（用 Google 登录；你机器上不存数据库凭据），或者自托管时，用你自己跑的 PostgreSQL+pgvector 数据库。把本地数据推到远端，把队友的数据拉下来。后台同步每 5 分钟自动跑一次。安装向导支持 Docker、Neon、Supabase、AWS RDS、GCP Cloud SQL 和 Azure Flexible Server。

去重 —— 同步过程中，YAPA 用余弦相似度比较文档嵌入（默认阈值 0.95）。近似重复的文档通过 related_ids 关联起来，而不是合并或丢弃，所以不会丢数据，你还能追溯相关知识的来源。

工作原理

在 DSH 下，插件默认原生注册 25 个 yapa_ 工具（另有 18 个由 trainingPipeline 控制开关），在 agent/pre-step 接缝处把召回结果和未完成任务注入每一轮（不用钩子，不用接线），每轮结束后用后台辅助 LLM 提取器判断有没有值得长期保留的发现（自动存储、去重、矛盾时用新记忆取代过期记忆），每天对现有存储跑一次清理扫描，数据默认存在内嵌本地存储里。完整的接缝图见 packages/dsh/architecture.md。

在 MCP 宿主下，YAPA 是一个 MCP 服务器，默认带 25 个工具（另有 18 个由 YAPA_TRAINING_PIPELINE 控制开关）。你的智能体通过编辑器的 MCP 配置连上它。连上之后：

- 每次回复之前，智能体会查询你的记忆，找相关上下文
- 学到重要东西时，自动存下来（bug 修复、偏好、决策）
- 识别到工作时，创建并跟踪任务
- 集合从对话上下文推断 —— 不用手动归档
- 如果启用了同步，后台循环每 5 分钟推一次本地改动、拉一次远端更新

数据存在 ChromaDB（MCP 的默认选项）或内嵌本地存储（DSH 插件的默认选项；YAPA_STORAGE=local 也能让 MCP 用上它）。嵌入始终在进程内计算（默认 MiniLM，也可以用 HTTP 服务商）；没有后端在服务端做嵌入。启用远程同步后，文档还会存进带 pgvector 的 PostgreSQL，用于跨机器搜索和去重。

安装

Claude Code 插件（推荐）

claude plugin marketplace add vuldin/yapa
claude plugin install yapa@yapa

插件打包了 MCP 服务器、常驻钩子和 /yapa:standup 技能，并在会话开始时注入 YAPA 的常驻规则，所以不用手动往 CLAUDE.md 或 settings.json 里加东西。安装时 Claude Code 会从 plugin/package-lock.json 装运行时依赖（@huggingface/transformers、pg）。选项（启用时提示；之后用 /plugin → Configure options 或 claude plugin configure yapa 修改）：

| 选项 | 默认值 | 含义 |
| username | 操作系统登录名 | 用于任务 ID 和所有同步内容（使用同步服务时来自你的 Google 账号，此时仅作参考） |
| storage | local | local 内嵌存储（无需服务器）或 chroma |
| chroma_url | http://localhost:8000 | storage 为 chroma 时使用的 ChromaDB 服务器 |
| project_roots | _（空）_ | 逗号分隔的文件夹，其子文件夹映射到 project-{name} / customer-{name} 集合 |
| customers | _（空）_ | 根目录下属于客户的文件夹名 |
| sync_enabled、sync_service_url | 关闭 | 通过 YAPA 同步服务进行团队同步，用你的 Google 账号登录（gcloud auth login） |
| sync_database_url、sync_ca_cert | _（空）_ | 高级/自托管：直连 PostgreSQL+pgvector 的 URL（设置了服务 URL 时忽略；存放在系统凭据存储中） |
| response_capture | 关闭 | 每轮对话后自动捕获持久发现（见下方钩子） |

整个团队使用时，添加 marketplace 并在托管设置或仓库设置中启用插件（extraKnownMarketplaces + enabledPlugins: {"yapa@yapa": true}）。

claude mcp add（仅 MCP 服务器，可选钩子）

git clone https://github.com/vuldin/yapa && cd yapa/plugin && npm install --omit=dev
claude mcp add -s user -t stdio -e YAPA_USERNAME=you -e YAPA_STORAGE=local yapa -- node "$PWD/dist/yapa-mcp.mjs"
node dist/yapa.mjs hooks install # adds the always-on hooks to ~/.claude/settings.json

钩子命令行会从 ~/.claude.json 中的 yapa 条目读取同样的 -e 设置，所以钩子和服务器始终一致。yapa hooks uninstall 只删除 YAPA 的条目；yapa hooks print 只显示不写入。重新运行 hooks install 会替换旧版本安装的 YAPA 钩子，而不是重复添加。

智能体驱动的向导（Cursor / OpenCode / 自定义环境）

给你的 AI 智能体这条提示词：install https://github.com/vuldin/yapa —— 它会遵循 CLAUDE.md / AGENTS.md。

以后要卸载，在任意会话中说 uninstall yapa（插件则用 claude plugin uninstall yapa@yapa）。

团队试点

加入团队同步试点：

- docs/pilot-onboarding.md：安装、配置、验证、隐私规则、故障排查、回滚。
- docs/second-user-test.md：双人操作手册，端到端验证跨用户同步。
- docs/pilot-feedback-template.md：如何反馈问题（Slack + YAPA 任务）。
- 管理员：scripts/yapa-user.sh 可列出、禁用、启用或映射用户（文件头部说明了 IAP 隧道）。

工具

下表列出 MCP 工具名。DSH 插件以 yapa_ 前缀暴露同样的能力（memory_recall → yapa_memory_recall），外加 yapa_status 和 yapa_storage_import。setup_instructions 和 uninstall 仅限 MCP（插件没有需要写入配置文件的內容）。

工具面保持精简： 下面 25 个工具默认可见。
ML-ops 子系统（策展分类器、分桶路由、系统提示词配套、训练、评估、适配器晋升——还有 18 个）属于运维工作流，不是智能体的日常界面：只有设置了 trainingPipeline: true（DSH 插件配置 / settings）或 YAPA_TRAINING_PIPELINE=true（MCP）时才会出现。完整流水线走查及其工具见 docs/training-pipeline.md。

| 工具 | 说明 |
| setup_instructions | 为 CLAUDE.md / AGENTS.md 生成行为指令 |
| memory_store | 存储记忆，可带 content、tags、salience、sector、collection |
| memory_recall | 语义搜索，按 distance + salience 排序，可选 collection/tag/score 过滤 |
| memory_forget | 按 ID 删除记忆 |
| memory_list | 列出记忆，支持元数据过滤（tag、sector、classifier scores） |
| compaction_suggest | 把相似的非归档记忆分组，用于滚动摘要合并 |
| compaction_apply | 用一条摘要记忆替换一组记忆，并归档原始记忆 |
| journal_append | 向当前会话的 journal 追加一行草稿 |
| journal_consolidate | 会话结束时把会话草稿汇总成一条带 journal 标签的记忆 |
| janitor_now | 运行矛盾清理：处理近似重复对（归档重复项、取代过期记忆、保留不同事实） |
| task_create | 创建任务，可带 title、priority、due date、tags、collection |
| task_list | 列出任务，支持过滤；传 id 可查看单个任务的全部详情（notes、dependencies） |
| task_update | 更新任务字段（包括通过 title 重命名） |
| task_complete | 标记完成 + 处理重复任务重新生成 |
| task_delete | 删除任务 |
| task_search | 跨任务语义搜索 |
| task_add_dependency | 添加 depends-on/blocks 关系 |
| task_remove_dependency | 移除 depends-on/blocks 关系（两侧都移除，悬空边也一并处理） |
| collection_list | 列出所有 collection 及其文档数 |
| collection_create | 创建新 collection |
| collection_merge | 把一个 collection 的所有文档移入另一个（保留 id 和元数据，按移动同步），然后删除空的源 collection |
| collection_delete | 删除 collection（非空的共享 collection 需要 confirm: "<name>"；这不是合并） |
| decay_sweep | 手动触发 salience 衰减 |
| sync | 通过 action 控制同步：status（健康状态、上次拉取、待处理）、now（推送+拉取循环）、collections（远程列表 + 订阅）、subscribe / unsubscribe（保留本地数据） |
| uninstall | 从你的系统中移除 YAPA |

常驻钩子（仅 Claude Code / MCP 前端）

在 DSH 插件下这一节不适用：召回和任务浮现已内置于回合接缝（agent/pre-step），无需注册任何东西——见 packages/dsh/architecture.md。

yapa 命令行（plugin/dist/yapa.mjs，或 packages/mcp/dist/cli/index.js）实现 YAPA 的 Claude Code 钩子。插件会自动注册这些钩子；yapa hooks install 为 claude mcp add 安装方式注册同一组钩子。

| 钩子 | 作用 |
| SessionStart | 从 cwd 和 YAPA_PROJECT_ROOTS 判断作用范围，拉取该集合中队友的最新写入，注入未完成任务 + 高优先级记忆 + 压缩候选（外加插件下的常驻规则）。上下文压缩后重新注入（source: compact）。汇总崩溃会话留下的日志草稿。 |
| UserPromptSubmit | 从共享 DB 拉取当前活跃集合（受 YAPA_HOOK_PULL_TIMEOUT_MS 限制，失败即放行），然后注入与提示词最匹配的前 3 条召回结果。队友的条目标记为 by <user>；来自其他集合的命中标记为 from <collection>。 |
| Stop（异步） | 当 YAPA_RESPONSE_CAPTURE=true 时：用辅助模型评判已结束的一轮对话（缓冲的提示词 + Claude Code 的 last_assistant_message），把值得长期保留的发现存为 auto-capture 记忆（显著度 ≤ 2.0，去重；事实有变化时新记忆取代过时记忆）。未配置整理 API key 时使用 claude -p --model haiku，所以订阅用户无需 key。结果会在下一条提示词中以一行提示显示。 |
| PostCompact（异步） | 把 Claude Code 的压缩摘要存为情节式 compaction 记忆，让它比上下文窗口活得更久。 |
| SessionEnd | 清理会话的钩子状态。日志整合和最后的同步推送在 MCP 服务器自身关闭时进行（日志会话由它负责）。 |

每个钩子都失败即放行：出错时输出 {}，会话继续。

矛盾检测

memory_store 在每次写入前对目标集合做相似度检查。距离在 YAPA_CONTRADICTION_DISTANCE_THRESHOLD（默认 0.25，归一化余弦）以内的记忆会作为 potential_conflicts 返回。由智能体决定：

- 取代 —— 用 supersedes: "<conflicting ID>" 重新存储：旧记忆会被归档（archived: true + 一条 superseded_by 链接），而不是硬删除 —— 默认从 memory_recall/memory_list 中过滤掉，随时可用 include_archived: true 恢复。
- 共存 —— 保留旧记忆；新记忆已经存好。

memory_forget（硬删除）只留给本就不该存在的记忆。

在 DSH 下，矛盾处理同样是自动的：响应捕获流水线会把每个带近似邻居的自动捕获候选交给一个保守的 LLM 裁决器（跳过 / 新增 / 取代），并且每天有一次 janitor sweep 处理库中已有的重复对（yapa_janitor_now / janitor_now 可按需运行）。裁决器只在事实明确变化时才取代；拿不准时两条都保留。

可调项：

| 环境变量 | 默认值 | 含义 |
| YAPA_CONTRADICTION_DISTANCE_THRESHOLD | 0.25 | 低于此距离的两条记忆视为冲突 |
| YAPA_CONTRADICTION_MAX_RESULTS | 3 | 每次写入最多暴露多少条冲突 |

会话结束日志

有两个工具会记录会话期间发生的事，让下一个会话能接上：

- journal_append({ entry, collection? }) —— 追加一条单行笔记。草稿通过每个进程独立的 SESSION_ID 限定在当前 MCP 服务器进程内。
- journal_consolidate({ collection?, summary? }) —— 把本会话的草稿汇总成一条记忆，打上 journal 标签，salience 为 1.5，然后删除草稿。如果不提供 summary，草稿就按时间顺序拼接。

汇总也会自动发生：MCP 服务器关闭时会把自己会话的草稿汇总起来（每个 Claude Code 会话对应一个服务器进程）；SessionStart 钩子则会把崩溃会话遗留的、超过一天的草稿汇总起来。

定期压缩

当某个集合的非归档记忆数量超过 YAPA_COMPACTION_THRESHOLD（默认 50），SessionStart 钩子会把它标记为压缩候选。接下来智能体：

1. 调用 compaction_suggest({ collection }) —— 返回若干组相似记忆，每组至少 YAPA_COMPACTION_MIN_GROUP_SIZE 条（相似度由 YAPA_COMPACTION_SIMILARITY_DISTANCE 控制，默认 0.30）。
2. 为每组起草一段滚动摘要。
3. 调用 compaction_apply({ collection, member_ids, summary }) —— 以 salience 2.0 写入摘要，打上 compacted 标签，然后给每个成员标上 archived: true 和 compacted_into: 。

memory_recall 和 memory_list 默认会过滤掉 archived: true 的记忆。传 include_archived: true 可以查看它们。

可调参数：

| 环境变量 | 默认值 | 含义 |
| YAPA_COMPACTION_THRESHOLD | 50 | 集合达到多大时建议压缩 |
| YAPA_COMPACTION_MIN_GROUP_SIZE | 3 | 一个压缩组至少要有多少成员 |
| YAPA_COMPACTION_SIMILARITY_DISTANCE | 0.30 | 两条记忆距离小于多少时归为同一组 |

嵌入服务商

嵌入始终在进程内运行 —— 没有任何存储后端会在服务端做嵌入，默认配置既不需要服务器也不需要 API key。（默认服务商叫 chromadb 是历史原因：它是 @huggingface/transformers 运行的量化 all-MiniLM-L6-v2 ONNX 模型 —— 和早先 chromadb-default-embed 包用的是同一个模型，所以已有的向量依然有效 —— 跟运行 ChromaDB 服务器* 毫无关系。）设置 YAPA_MODEL_CACHE_DIR 可以把下载的权重放到持久位置（插件默认用自己的数据目录）。

在 YAPA 固定余弦空间之前创建的 ChromaDB 集合，用的是服务器默认空间（平方 L2）。YAPA 会读取每个集合的空间，把这些距离换算成余弦，所以阈值在新旧集合上表现一致。

| 服务商 | 模型 | 维度 | 配置 |
| 进程内 MiniLM（默认） | all-MiniLM-L6-v2 | 384 | 零配置 |
| Fireworks | nomic-embed-text-v1 | 768 | YAPA_EMBEDDING_PROVIDER=fireworks |
| OpenAI | text-embedding-3-small | 768 | YAPA_EMBEDDING_PROVIDER=openai |
| Voyage AI | voyage-3-lite | 512 | YAPA_EMBEDDING_PROVIDER=voyage |
| Ollama | nomic-embed-text | 768 | YAPA_EMBEDDING_PROVIDER=ollama |

想用非默认服务商，就把相关环境变量加到 MCP 宿主配置的 env 块里（DSH 下则加到插件的 cordis config:）。所有选项见 .env.example。

注意：嵌入服务商和存储后端是两件独立的事——进程内嵌入器既能配嵌入式本地存储（DSH 插件下的默认值），也能配 ChromaDB 服务器（MCP 下的默认值）。

配置

所有选项都用 YAPA_ 前缀，在 MCP 宿主配置里以环境变量形式设置。DSH 插件下，同样的值放在 cordis 行 config: 里，或放在 ~/.dsh/settings.yaml 的 yapa: 段（支持热重载，驼峰命名：chromaUrl、syncEnabled……）。完整列表见 .env.example。

| 变量 | 说明 | 默认值 |
| YAPA_STORAGE | chroma \| local（嵌入式存储，无需服务器） | MCP 下为 chroma；DSH 插件默认为 local |
| YAPA_LOCAL_STORE_PATH | 嵌入式存储的根目录 | ~/.local/share/yapa/store |
| YAPA_CHROMA_URL | ChromaDB 服务器 URL（当 YAPA_STORAGE=chroma 时） | http://localhost:8000 |
| YAPA_USERNAME | 用于任务 ID 前缀和同步归属的用户名 | 操作系统登录名 |
| YAPA_PROJECT_ROOTS | 逗号或冒号分隔的文件夹，其一级子文件夹会成为 project-{name}（或 customer-{name}）作用域 | _（无：全部为 global）_ |
| YAPA_CUSTOMERS | 项目根目录下映射到 customer-{name} 的文件夹名 | _（无）_ |
| YAPA_EMBEDDING_PROVIDER | 嵌入服务商——chromadb 是进程内 MiniLM（零配置，不调用服务器）；fireworks/openai/voyage/ollama 走 HTTP API | chromadb |
| YAPA_SALIENCE_DECAY_RATE | 情景记忆的每日衰减乘数（语义记忆取其平方根） | 0.98 |
| YAPA_SALIENCE_RANKING_WEIGHT | 显著度对检索排序的影响程度（0.0 = 纯距离，越大越以显著度为主） | 0.15 |
| YAPA_SALIENCE_BOOST_MAX_DISTANCE | 余弦距离小于此值的召回命中算作一次使用，会提升显著度 | 0.5 |
| YAPA_SALIENCE_MAX_BOOSTS_PER_DAY | 每条记忆每个 UTC 日最多提升次数 | 3 |
| YAPA_TRAINING_PIPELINE | 暴露 18 个 ML-ops 工具（curation/buckets/training/eval/adapter） | false |
| YAPA_SYNC_ENABLED | 启用远程同步 | false |
| YAPA_SYNC_SERVICE_URL | YAPA 同步服务 URL（优先于数据库 URL） | _（无）_ |
| YAPA_SYNC_ID_TOKEN_CMD | 打印服务用 Google ID token 的命令 | gcloud auth print-identity-token |
| YAPA_SYNC_HTTP_TIMEOUT_MS | 同步服务的单请求超时 | 15000 |
| YAPA_SYNC_DATABASE_URL | 进阶／自托管：直接连 PostgreSQL 的连接串（设置了服务 URL 时忽略） | _（无）_ |
| YAPA_SYNC_INTERVAL_MS | 后台同步间隔，单位 ms | 300000（5 分钟） |
| YAPA_SYNC_SIMILARITY_THRESHOLD | 去重用的余弦相似度阈值 | 0.95 |
| YAPA_SYNC_PUSH_DEBOUNCE_MS | 写入触发推送前的延迟（0 = 只按间隔推送） | 2000 |
| YAPA_SYNC_PULL_OVERLAP_SECONDS | 每次拉取时重读的时间窗口，避免拉取中途的推送被漏掉 | 120 |
| YAPA_DEVICE_ID | 本机的固定 id（否则在 YAPA_DEVICE_ID_PATH 生成一次） | _（自动生成）_ |
| YAPA_HOOK_PULL_TIMEOUT_MS | 钩子在召回前拉取的超时上限 | 4000 |
| YAPA_RESPONSE_CAPTURE | 每轮对话后自动捕获可长期保留的发现（Stop 钩子） | false |
| YAPA_CURATION_LLM_PROVIDER | 用于捕获／整理的辅助模型：anthropic \| openai \| fireworks \| ollama \| claude-cli | anthropic（没有 key 时钩子回退到 claude-cli） |
| YAPA_MODEL_CACHE_DIR | 进程内嵌入模型缓存权重的位置 | 库默认值 |

空值等同于未设置（你没配过的插件选项，Claude Code 会替换成 ""）。

ML-ops 相关配置（整理模型、分桶阈值、训练后端、评估留出集……）见 docs/training-pipeline.md。

远程同步

远程同步让多台机器或团队成员共享记忆和任务。它是可选的：YAPA 完全能离线工作，远程连不上时本地功能照常可用。

设置（同步服务）

1. 安装插件（见上文），启用 sync_enabled。
2. 把 sync_service_url 设为你团队的 YAPA 同步服务 URL（问你的 YAPA 管理员）。
3. 登录一次：用公司 Google 账号执行 gcloud auth login。YAPA 会调用 gcloud auth print-identity-token 拿一个短期 ID token，只存在内存里，过期前刷新。其他 token 来源：把 YAPA_SYNC_ID_TOKEN_CMD 设成一条命令，由它打印 ID token。
4. 用 sync 工具检查，action: 'status'：它会显示后端、服务 URL、你当前登录的身份、最后一次错误，以及服务拒绝接收的文档。

接入服务后，你的用户名来自 Google 账号（在 sync status 里显示）；任务 id 会用它，username 选项只是说明性的。服务会强制归属（只有所有者能删除共享行），拒绝看起来像密钥的内容（文档留在本地不同步，列在 sync status 里，只有你改过之后才会重试），把 id 已属于其他任务的任务改名，并把删除同步到队友的机器（干净副本会被删掉；有未推送改动的副本会保留并上报）。

进阶：直连数据库（自托管）

sync_database_url（YAPA_SYNC_DATABASE_URL）不走服务，而是直接连你自己运行的 PostgreSQL+pgvector 数据库；设置了服务 URL 时它会被忽略。这个模式没有服务端访问控制：拿到 URL 的人都能读写每个共享 collection，删除不会同步到其他机器，也没有密钥校验。

工作原理

启用 sync 后，YAPA 每 5 分钟跑一轮后台 push/pull 循环（可用 YAPA_SYNC_INTERVAL_MS 配置），另外两条更快的路径让队友在几秒内就能看到更新：

- 写入即推送 —— 每个写工具（memory_store、task_update 等）都会安排一次防抖推送（YAPA_SYNC_PUSH_DEBOUNCE_MS），MCP 服务器在关闭时会冲刷掉待推送的内容。
- 召回前拉取 —— Claude Code 钩子会在注入上下文之前拉取当前活跃的 collection，所以队友几秒前写入的记忆，在你下一次提示词里就能看到。

循环本身：

1. 推送 —— 标记为未同步的本地文档会被上传，并打上本机的 origin_device。你推送到的 collection 会自动订阅拉取。Journal 草稿留在本地；只有合并后的 journal 才会同步。
2. 拉取 —— 订阅的 collection 中的文档会被下载，只跳过由本设备最后写入的行（这样你的其他机器仍能收到你的成果）。新订阅的 collection 会回填完整历史。存储的拉取点是本轮循环的起点减去一个重叠窗口，所以拉取运行期间推送的文档永远不会被跳过。
3. 更新 —— 当远端文档比本地副本新，且本地副本没有未推送的编辑时，远端版本会替换它（队友完成了任务、修正了记忆）。本地副本若有未推送的编辑则优先保留，并在下一轮循环推送。

多用户语义

- 归属 —— 文档保留原始作者（origin_user）；注入的上下文会把队友的条目标为 by <user>。
- global 仅限本地 —— 和 private-/local- collection 一样，它永远不会离开你的机器（连你自己的其他设备也不会收到）。团队级知识请放进共享 collection，比如 project-cs-team。
- 同一用户，多台机器：在所有机器上用同一个 Google 账号登录（直连数据库：用同一个 YAPA_USERNAME）；每个安装有自己的设备 id。
- 访问控制：用 sync 服务时，服务器会用你的 Google 身份校验每个请求；直连数据库时，拿到 URL 的人都能读取每个共享 collection。无论哪种方式，凡是不能离开你机器的内容，都用 private-/local- collection。

你也可以手动触发同步：sync（action: 'now'），查看状态：action: 'status'，管理订阅：action: 'subscribe' / 'unsubscribe'。

去重

推送和拉取都会用余弦相似度，把文档 embedding 和已有数据做比较：
- 推送时：把每个本地文档的 embedding 与远程数据库比对。如果匹配度超过相似度阈值（默认 0.95），就在本地和远程的元数据里通过 related_ids 把文档关联起来。文档仍会推送——不会丢弃任何内容。
- 拉取时：把每个远程文档与本地 ChromaDB 数据比对。超过阈值的匹配以同样方式关联。远程文档仍会插入本地。

也就是说，近似重复的文档会共存，但会互相交叉引用，这样你就能追溯相关知识来自哪里，而不会丢失数据。用 YAPA_SYNC_SIMILARITY_THRESHOLD 调整阈值——值越低关联越激进，值越高要求越接近完全匹配。

删除传播

Deleting your own memory or task queues the deletion for the remote database; it's processed on the next push, before new documents. Deleting a teammate's document only removes it from your machine: it's tombstoned locally so pull won't re-insert it, and the shared row stays for everyone else (the remote delete is also guarded by owner).

Private collections

Collections prefixed with private- or local-, and global, are never synced. Use these for personal notes, credentials, or anything that should stay on one machine.

A doc in a private collection never keeps a shared copy: if one of your docs ends up there (moved, restored, or synced by an older YAPA version), the next sync deletes its shared row. Only the same doc is removed (matched by id and creation time), never a different shared task that happens to reuse the id. A private copy of a teammate's doc is just a personal copy; their shared row stays. Each private doc is checked once per version, so steady-state syncs make no extra remote lookups.

Testing sync

From a fresh clone: npm ci && npm test (npm test builds first, since the
yapa-mcp and DSH tests import the built @yapa/core). The first run
downloads the embedding model, so give it a minute.

npm test mocks the remote (Postgres seam, and a mock HTTP server for the service client).

Backend contract suite: the same scenarios against the direct-database backend and the service backend (in-process service, test auth, RLS schema from infra/cloudsql/sql), on a throwaway pgvector container:

docker run -d --rm --name yapa-ct -e POSTGRES_PASSWORD=ct -p 127.0.0.1:55433:5432 pgvector/pgvector:pg17
YAPA_CONTRACT_DB_URL=postgres://postgres:ct@127.0.0.1:55433/postgres npx vitest run src/sync/contract.test.ts # in packages/core
docker rm -f yapa-ct

Live check against a deployed service (after gcloud auth login; writes only to a per-run project-yapa-it-<run> collection and deletes its rows afterwards):

YAPA_LIVE_SERVICE_URL=https://<your-service> npx vitest run src/sync/live.test.ts # in packages/core

Direct-database end-to-end suite (multi-user model,
collection moves, task-id collisions) against a real PostgreSQL+pgvector
database:

YAPA_IT_DATABASE_URL=postgres://user:pass@host:5432/yapa npm run test:integration -w packages/core

Each run uses unique throwaway usernames and collections and deletes every row
it wrote afterwards; other users' rows are never touched.

Database providers

The install wizard handles PostgreSQL setup. Supported providers:

- Docker (local) — pgvector/pgvector:pg17 container
- Neon — free serverless PostgreSQL with pgvector included
- Supabase — free hosted PostgreSQL with pgvector included
- AWS RDS — managed PostgreSQL with pgvector extension
- GCP Cloud SQL — managed PostgreSQL with pgvector extension
- Azure Flexible Server — managed PostgreSQL with pgvector extension