vuldin/yapa

YAPA — 又一个个人助理

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

Claude Code / Cursor / OpenCode： 将以下提示词交给你的 AI 代理：install https://github.com/vuldin/yapa

各位代理——请先阅读此内容。 不要克隆此仓库。不要运行 git clone、npm install、npm run build 或任何其他命令。对于 MCP 宿主，请先阅读本仓库中的 CLAUDE.md（Claude Code / Cursor）或 AGENTS.md（OpenCode）——其中包含必须严格遵循的多阶段安装流程。安装过程在克隆之前需要用户输入。对于 DeepSeek Harness，请改为遵循 packages/dsh/install.md（无需代理驱动的向导）。

YAPA 是一个个人助理，为你的 AI 代理提供持久记忆和任务管理，让你的代理能够记住你告诉它的内容、跟踪你的任务，并按项目或客户组织知识——跨越每一个会话。

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

- 原生 DeepSeek Harness 插件（yapa，位于 packages/dsh）——默认提供 23 个工具（另有 18 个受门控的 ML-ops 工具），具备结构化输出和 GUI 卡片、在对话接缝处注入的常开回忆、自动捕获每个代理回合中的持久性发现（辅助 LLM 提取器 + 保守冲突解决器）、每日矛盾清理器（归档重复项并取代过时记忆）、热重载设置、日程桥接的截止日期、压缩捕获、审批门控，以及嵌入式零服务器存储选项。文档：安装 · 架构 · 未来工作与调查记录。
- MCP 服务器（yapa-mcp，位于 packages/mcp）——最初的 stdio 服务器加上 Claude-Code 钩子 CLI。“仓库布局”一节以下的所有内容主要描述此前端。

仓库布局

- packages/core（@yapa/core）——所有逻辑：记忆、任务、集合、日志、压缩、同步、策展、桶、训练。配置是一个 YapaConfig 快照（createConfig(env) / setConfig），而非模块级的环境变量读取，因此宿主可以控制配置。存储通过 VectorStore 端口（src/store/）进行：ChromaDB HTTP 适配器，或嵌入式本地适配器（每个集合一个 JSON 文件、进程内嵌入、暴力余弦相似度——无需服务器）。
- packages/mcp（yapa-mcp）——MCP 服务器 + Claude-Code 钩子 CLI。
- packages/dsh（yapa）——DeepSeek Harness cordis 插件。

它能做什么

持久记忆——你的代理能够跨对话记住事情。错误修复、偏好、决策、配置细节、问题的解决方案——以语义搜索的方式存储，因此在你需要时，正确的上下文会浮现出来。
任务管理 — 创建具有优先级、截止日期、依赖关系和重复计划的任务。你的智能体会跟踪哪些任务正在进行中、哪些被阻塞、哪些已逾期。完成一个重复任务后，下一个任务会自动生成。

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

数据生命周期 — 并非所有记忆都同等重要。YAPA 按显著性（1.0 到 5.0）为每条记忆评分，在访问时提升其评分，并随时间衰减。语义事实（偏好、配置）比情节事件（周二发生了什么）衰减得更慢。显著性还会影响检索排名，因此在向量距离相近的情况下，显著性更高的记忆会排在显著性更低的记忆之前。任何内容都不会被删除——低显著性的记忆只是浮现的频率更低。

智能分块 — 长内容被拆分为 2000 字符的块，并带有 200 字符的重叠，每一块都可独立搜索。会议记录、文档、冗长的解释——全都被存储并可检索。

远程同步 — 可选择将记忆和任务同步到共享的 PostgreSQL+pgvector 数据库。将本地数据推送到远程，将队友的数据拉取到本地。后台同步每 5 分钟自动运行一次。安装向导支持 Docker、Neon、Supabase、AWS RDS、GCP Cloud SQL 和 Azure Flexible Server。

去重 — 在同步期间，YAPA 使用余弦相似度（默认阈值 0.95）比较文档嵌入。近似重复项通过 related_ids 关联，而不是合并或丢弃，因此不会丢失任何数据，并且你可以追踪相关知识的来源。

工作原理

在 DSH 下，该插件默认原生注册 23 个 yapa_ 工具（另有 18 个受 trainingPipeline 门控），在 agent/pre-step 接缝处将召回内容 + 未完成任务注入每一轮（无需钩子，无需接线），通过后台辅助 LLM 提取器判断每一轮已完成的内容是否有持久发现（自动存储、去重，通过取代过时记忆来解决矛盾），对现有存储运行每日清理扫描，并默认将数据存储在嵌入式本地存储中。完整的接缝映射请参见 packages/dsh/architecture.md。

在 MCP 宿主下，YAPA 是一个 MCP 服务器，默认提供 23 个工具（另有 18 个受 YAPA_TRAINING_PIPELINE 门控）。你的智能体通过编辑器的 MCP 配置连接到它。连接后：

- 在每次响应之前，智能体会查询你的记忆以获取相关上下文
- 当它学到重要内容时，会自动存储（错误修复、偏好、决策）
- 当识别出工作时，它会创建并跟踪任务
- 集合根据对话上下文推断——无需手动归档
- 如果启用了同步，后台循环每 5 分钟推送本地更改并拉取远程更新
数据存储在 ChromaDB（MCP 的默认存储）或嵌入式本地存储中（DSH 插件的默认存储；设置 YAPA_STORAGE=local 后 MCP 也可使用）。嵌入始终在进程内计算（默认使用 MiniLM，或使用 HTTP 提供程序）；没有后端在服务端进行嵌入。启用远程同步后，文档还会存储在带有 pgvector 的 PostgreSQL 中，以便进行跨机器搜索和去重。

安装

要安装，请向你的 AI 代理提供以下提示：install https://github.com/vuldin/yapa

之后要卸载，请在任意会话中说 uninstall yapa。

工具

下表列出了 MCP 工具名称。DSH 插件以 yapa_ 前缀暴露相同的能力（memory_recall → yapa_memory_recall），另外还有 yapa_status 和 yapa_storage_import。setup_instructions 和 uninstall 仅适用于 MCP（该插件没有任何内容需要写入配置文件）。

工具界面，保持精简： 下面这 23 个工具默认可见。ML-ops 子系统（策展分类器、桶路由、系统提示词伴随工具、训练、评估、适配器提升——另外 18 个）属于操作员工作流，而非日常代理界面：仅当设置了 trainingPipeline: true（DSH 插件配置 / 设置）或 YAPA_TRAINING_PIPELINE=true（MCP）时才会出现。有关完整流水线演练及其工具，请参阅 docs/training-pipeline.md。

| 工具 | 描述 |
|------|-------------|
| setup_instructions | 为 CLAUDE.md / AGENTS.md 生成行为指令 |
| memory_store | 存储带有内容、标签、显著性、扇区、集合的记忆 |
| memory_recall | 按距离 + 显著性排序的语义搜索，支持可选的集合/标签/分数过滤 |
| memory_forget | 按 ID 删除记忆 |
| memory_list | 使用元数据过滤器（标签、扇区、分类器分数）列出记忆 |
| compaction_suggest | 将相似的未归档记忆分组，以便进行滚动摘要整合 |
| compaction_apply | 用摘要记忆替换一组记忆，并归档原始记忆 |
| journal_append | 向当前会话的日志追加一行草稿条目 |
| journal_consolidate | 在会话结束时将会话草稿汇总为一条带有 journal 标签的记忆 |
| janitor_now | 运行矛盾清理器：解决近似重复对（归档重复项、取代过时记忆、保留不同事实） |
| task_create | 创建带有标题、优先级、截止日期、标签、集合的任务 |
| task_list | 使用过滤器列出任务；传入 id 可获取单个任务的完整详情（备注、依赖项） |
| task_update | 更新任务字段 |
| task_complete | 标记为完成 + 处理重复任务的重新生成 |
| task_delete | 删除任务 |
| task_search | 跨任务进行语义搜索 |
| task_add_dependency | 添加依赖/阻塞关系 |
| collection_list | 列出所有集合及其文档数量 |
| collection_create | 创建新集合 |
| collection_delete | 删除集合 |
| decay_sweep | 手动触发显著性衰减 |
| sync | 通过 action 进行同步控制：status（健康状态、上次拉取、待处理项）、now（推送+拉取循环）、collections（远程列表 + 订阅）、subscribe / unsubscribe（本地数据保留） |
| uninstall | 从你的系统中移除 YAPA |

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

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

除 MCP 服务器外，YAPA 还附带一个小型 yapa CLI。它暴露了四个钩子入口点，设计为从 ~/.claude/settings.json 调用：

| 钩子 | 作用 |
|------|--------------|
| session-start | 从 cwd 检测作用域，将未完成任务 + 顶部记忆 + 压缩候选作为 additionalContext 浮现 |
| user-prompt-submit | 以提示词为查询，针对检测到的作用域运行 memory_recall，并注入前 3 个匹配项 |
| stop | 提醒 agent 为刚结束的回合中的发现调用 memory_store / task_create / journal_append |
| session-end | 记录会话结束；在下次会话开始时浮现待处理的日志草稿 |

在 ~/.claude/settings.json 中注册一次这些钩子（将 command 字段指向 packages/mcp/dist/cli/index.js 的绝对路径）。此后，召回和任务浮现会在每次提示时发生，无需 agent 记得调用这些工具。这正是 YAPA 能够“常驻”而非尽力而为的原因。

配置：每个钩子都采用失败开放策略——如果调用出错，钩子会输出 {}，会话正常继续。

矛盾检测

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

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

memory_forget（硬删除）保留给那些本就不应存在的记忆。

在 DSH 下，矛盾处理也是自动的：响应捕获流水线会将每个带有近邻的自动捕获候选，交给一个保守的 LLM 解析器处理（跳过 / 添加 / 取代），并且每日的 janitor 清扫会解析存储中已有的重复对（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、显著度为 1.5 的记忆，然后删除这些草稿。如果未提供 summary，草稿会按时间顺序拼接。

Stop 钩子会提示智能体在每一轮写入日志；SessionEnd 钩子会提示进行汇总。

定期压缩

当某个集合中未归档的记忆数量超过 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 }) — 以显著度 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 密钥。（默认提供程序因历史原因命名为
chromadb：它是 chromadb-default-embed 包 — 基于 onnxruntime-web（WASM）的 MiniLM-L6-v2 — 与运行 ChromaDB 服务器*毫无关系。）

| 提供程序 | 模型 | 维度 | 配置 |
|----------|-------|------------|--------|
| 进程内 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: 部分（camelCase：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 前缀的用户名 | user |
| 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.3 |
| YAPA_TRAINING_PIPELINE | 暴露 18 个 ML-ops 工具（curation/buckets/training/eval/adapter） | false |
| YAPA_SYNC_ENABLED | 启用远程同步 | false |
| YAPA_SYNC_DATABASE_URL | PostgreSQL 连接字符串 | _（无）_ |
| YAPA_SYNC_INTERVAL_MS | 后台同步间隔，单位为毫秒 | 300000（5 分钟） |
| YAPA_SYNC_SIMILARITY_THRESHOLD | 用于去重的余弦相似度阈值 | 0.95 |

ML-ops 配置（curation 模型、bucket 阈值、训练后端、
eval holdout……）位于
docs/training-pipeline.md。

远程同步

远程同步让多台机器或团队成员通过 PostgreSQL+pgvector 数据库共享记忆和任务。它是可选的——YAPA 仅凭 ChromaDB 即可完全离线工作。

工作原理

启用同步后，YAPA 每 5 分钟运行一次后台推送/拉取循环（可通过 YAPA_SYNC_INTERVAL_MS 配置）：

1. 推送 — 标记为未同步的本地文档被上传到远程数据库。你推送到的集合会自动订阅以进行拉取。
2. 拉取 — 来自已订阅远程集合的文档会被下载，跳过任何源自当前用户的文档。仅获取在上次拉取时间戳之后同步的文档。

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

去重

推送和拉取都会使用余弦相似度将文档嵌入与现有数据进行比较：
- 推送时：每个本地文档的嵌入向量会与远程数据库进行比对。如果匹配项的相似度超过阈值（默认 0.95），则通过本地和远程元数据中的 related_ids 将文档关联起来。文档仍会被推送——不会丢弃任何内容。
- 拉取时：每个远程文档会与本地 ChromaDB 数据进行比对。超过阈值的匹配项会以相同方式关联。远程文档仍会被插入到本地。

这意味着近似重复项会共存，但会相互交叉引用，因此你可以追溯相关知识的来源，而不会丢失数据。使用 YAPA_SYNC_SIMILARITY_THRESHOLD 调整阈值——较低的值会更积极地建立关联，较高的值则要求近乎完全匹配。

删除传播

当本地删除某个记忆或任务时，该删除操作会被加入队列，并在下一个同步周期传播到远程数据库。待处理的删除操作会在推送任何新文档之前处理。

私有集合

以 private- 或 local- 为前缀的集合永远不会被同步。可将这些集合用于个人笔记、凭据或任何应保留在单台机器上的内容。

数据库提供商

安装向导会处理 PostgreSQL 的设置。支持的提供商：

- Docker（本地）—— pgvector/pgvector:pg17 容器
- Neon —— 免费的 Serverless PostgreSQL，内置 pgvector
- Supabase —— 免费的托管 PostgreSQL，内置 pgvector
- AWS RDS —— 托管的 PostgreSQL，带 pgvector 扩展
- GCP Cloud SQL —— 托管的 PostgreSQL，带 pgvector 扩展
- Azure Flexible Server —— 托管的 PostgreSQL，带 pgvector 扩展