continuum

---

你的 Agent 会遗忘，Continuum 会记住。

将任意 MCP 客户端连接到 Continuum，并让它读取剧情。客户端会成为编排器——它会研究代码库、验证计划、持久化派遣记录，并为你准备好一段可直接粘贴的提示词，用于在隔离的 git 工作树中启动全新的 Agent。项目中的所有其他 Claude Code / Codex / Cline 聊天都能看到已预留的内容、共享已学到的经验，也无需再三解释代码库。一个本地服务：向量知识库、编排协议、Agent 注册表——在你机器上所有支持 MCP 的应用之间共享。

flowchart TD
    CC["Claude Code"]
    CX["Codex"]
    CL["Cline"]
    YOU["YOU"]

    subgraph CONTINUUM["CONTINUUM ORCHESTRATOR"]
        direction LR
        PLOT["PLOT.md<br/>protocol"]
        KNOW["KNOWLEDGE<br/>(vectorized)"]
        AGENTS["AGENTS<br/>registry"]
        PANEL["WEB PANEL<br/>(humans)"]
    end

    DB[("SQLite + sqlite-vec<br/>one file, your disk")]

    CC -- MCP --> CONTINUUM
    CX -- MCP --> CONTINUUM
    CL -- MCP --> CONTINUUM
    YOU -- HTTP --> CONTINUUM
    CONTINUUM --> DB

**没有 SaaS，没有遥测，也无需管理密钥。**数秒即可启动。重启后仍可继续运行。随你一同扩展。

---

你将获得

🧠 向量化记忆	Agent 学到的每条经验都会转换为 768 维嵌入向量，并编入 sqlite-vec 索引。检索基于语义、支持模糊匹配且即时完成——无需玩精确匹配的把戏。
🔍 原生支持 RAG 的搜索	knowledge_search({q: "how do we handle webhook retries?"}) 会返回排名后的元数据（slug + kind + agentSlug + 时间戳）；后续可用 knowledge_get({slug}) 获取正文。优先返回元数据可降低 top-K 上下文成本；只获取值得阅读的内容。
🗺️ 规范工作流	每个项目都会获得一个 PLOT.md，其中预置了包含 4 个阶段的派遣协议——接收 → 研究 → 验证 → 交接。无需再反复解释你的流程。
🤖 多 Agent 注册表	状态机 + 预留路径跟踪，可防止并行 Agent 在不同 git 工作树中互相覆盖。
📚 双层知识	fundamental 经验是每次派遣都会加载的约束规则。situational 经验会在相关时通过语义搜索呈现。
🖥️ 面向人的 Web 面板	通过 Astro + React UI 浏览项目、Agent、剧情和知识，同时由 AI 客户端通过 MCP 驱动一切。
🔌 不绑定客户端	标准 MCP / Streamable HTTP。适用于 Claude Code、Codex、Cline、Cursor，或任何支持该协议的工具。
🔒 本地优先	一个 SQLite 文件。WAL 模式。无需云服务。嵌入模型可选（Ollama、TEI，以及任何兼容 OpenAI 接口的服务）。
📦 生产环境只需一个容器	单个镜像、一个 HTTP 端口、一个挂载卷。部署到任意主机，然后将 MCP 客户端连接到它即可。

---

Continuum 的存在意义

没有 Continuum	使用 Continuum
会话结束 → 上下文消失。	经验以嵌入向量的形式持久保存。重启、更换模型或客户端后仍可召回。
每次会话都要重新解释约定。	knowledge_search 按相关性对经验排序；需要时用 knowledge_get 获取正文。
两个并行 Agent 修改同一个文件。	reserved_paths + 状态机可在派发前发现冲突。
每项新任务都要临时摸索编排方式。	每个项目都会注入 PLOT.md 协议 — 接收 → 研究 → 验证 → 交接。
“Claude 上周做了什么？”	registry_list 对派发元数据进行分页（slug、状态、分支、预留路径）。agent_get({slug}) 获取完整记录。
知识散落在聊天记录中。	一个 SQLite 数据库。一个向量索引。一个事实来源。

---

快速开始

🐳 简单方式 — 一条 Docker 命令

docker compose -f docker-compose.dev.yml up

就是这样。整个技术栈都会启动，并提供热重载、SQLite 浏览器和一个共享卷 — 无需在主机上安装 Node、pnpm，也不用折腾原生构建。

你将获得：

服务	URL	说明
api	http://localhost:6685	NestJS + MCP 服务。Swagger 位于 /docs。文件变更时自动热重载。
web	http://localhost:6680	Astro + React 面板。自动热重载。
sqlite-web	http://localhost:6667	实时 SQLite 数据库的浏览器界面 — 可检查项目、Agent、知识和向量。自动加载 sqlite-vec。
embedder（可选）	http://localhost:8080	Hugging Face TEI，运行 HTTP 嵌入器。默认关闭。

API 默认在进程内执行嵌入（通过 Transformers.js 使用 Snowflake/snowflake-arctic-embed-m-v1.5，768 维，ONNX q8）。语义搜索无需外部服务。设置 EMBEDDER_URL，即可指向任意基于 HTTP 的嵌入器（Ollama、TEI、兼容 OpenAI 的服务）。使用 embedder 配置文件启用随附的 TEI 容器：

HF_TOKEN=hf_xxx docker compose -f docker-compose.dev.yml --profile embedder up

绑定挂载会将源代码树保留在主机上 — 编辑会立即生效。命名卷用于存放 node_modules，因此重启后仍会保留安装内容。数据库位于主机上的 ./.local-data/dev-orchestrator.db，已加入 gitignore，可放心删除。

停止所有服务：

docker compose -f docker-compose.dev.yml down            # keep data
docker compose -f docker-compose.dev.yml down -v         # nuke volumes too

🛠️ 或在裸机上运行

pnpm install
pnpm dev

API + MCP	http://localhost:7776（Swagger 位于 /docs）
Web 面板	http://localhost:7777

开发用 SQLite 位于 ./.local-data/orchestrator.db。已加入 gitignore。删除即可重置 — 下次启动时会重新创建并完成迁移。

需要 Node >=22.12.0 和 pnpm 10.33+。使用 compose 方式无需这两项。

---

记忆与向量

这是核心亮点。Continuum 的知识层能让你的 Agent 不再健忘。

经验如何变成记忆

agent finishes a dispatch
        │
        ▼
knowledge_create({
  project, agentSlug, slug,
  content: "When wiring rate-limit guards in Nest,
            register them in app.module.ts AFTER
            the auth guard, not before. Order matters.",
  kind: 'situational'
})
        │
        ▼
content → embedder (in-process by default, or Ollama / TEI / OpenAI-compatible)
        │       Snowflake Arctic Embed v1.5 → 768-dim vector
        ▼
SQLite row + sqlite-vec index entry
        │       freshness profile = (URL, model, dim)
        ▼
forever queryable by ANY future agent on this project

如何召回

每次派发的第 1 阶段（由编排器自动执行）：

knowledge_list({ project, kind: 'fundamental' })
  └─ returns metadata for every binding lesson — slug + agentSlug + timestamps.
knowledge_get({ project, slug })  // for each fundamental slug
  └─ full body — base branch, worktree convention, no-AI-attribution, etc.

knowledge_search({ project, q: "rate limit middleware nest interceptor order" })
  └─ vector similarity over your prose
  └─ returns top-K ranked metadata (no content)
  └─ does NOT need exact wording — natural language works
knowledge_get({ project, slug })  // for each relevant hit
  └─ pulls the full lesson body

搜索和列表仅返回元数据 — slug + kind + agentSlug + 时间戳。对于值得阅读的经验，调用 knowledge_get 获取正文。这样可以降低 top-K 上下文的成本；编排器会先筛选，再获取。

结果是：即将规划你任务的 Agent，已经知道之前五个 Agent 历经教训得出的经验。无需提示词工程，也不用复制粘贴“这是我们的约定”。

两类知识

类型	加载时机	用途
fundamental	每次派发时，无条件加载	项目级规则：基础分支、工作树命名、提交约定、只追加文件
situational	仅在与任务语义相关时加载	具体注意事项：“身份验证守卫顺序”、“重新生成产物的合并策略”、“Stripe webhook 幂等键”

新鲜度配置

向量绑定到 (EMBEDDER_URL, EMBEDDER_MODEL, EMBEDDER_DIM) 三元组。更改其中任一项后，Continuum 会将过期向量标记为待重建，并在下次启动时重建。你可以自主决定由哪个嵌入器管理记忆 — 本地 Ollama、可自托管的 TEI，或任何兼容 OpenAI 格式的服务。

可插拔嵌入器

嵌入器是必需的，默认在进程内运行（Snowflake/snowflake-arctic-embed-m-v1.5，768 维，ONNX q8）。模型权重已打包在 API 镜像中——无需额外容器，也无需额外配置，语义搜索开箱即用。

通过 EMBEDDER_URL 覆盖设置，将嵌入任务委托给 HTTP 服务：

# Option A — Ollama (simplest, fully local)
ollama pull <embedding-model>
# EMBEDDER_URL=http://127.0.0.1:11434/api/embed
# EMBEDDER_MODEL=<embedding-model>   EMBEDDER_DIM=768

# Option B — Hugging Face TEI (production-grade, batched)
HF_TOKEN=hf_xxx docker compose -f docker-compose.dev.yml --profile embedder up embedder
# EMBEDDER_URL=http://127.0.0.1:8080/v1/embeddings
# EMBEDDER_MODEL=<repo-id>   EMBEDDER_DIM=768

# Option C — anything OpenAI-compatible /v1/embeddings
# Works out of the box. Match the dim.

基于 sqlite-vec 构建

向量索引与项目、Agent 和 plot 位于同一个 SQLite 文件中。一个文件。一份备份。一次还原。无需配置单独的向量数据库，无需支付 Pinecone 费用，也无需操心 Chroma 守护进程。WAL 模式支持读写并发；外键确保注册表一致；busy_timeout = 5000 可在发生争用时保持稳定。

---

将其接入你的 AI 客户端

Claude Code

// ~/.claude.json  →  mcpServers
{
  "mcpServers": {
    "continuum": {
      "transport": "streamable-http",
      "url": "http://127.0.0.1:7776/mcp"
    }
  }
}

重启 Claude Code。工具会显示为 mcp__continuum__*。

Codex

# ~/.codex/config.toml
[mcp_servers.continuum]
transport = "streamable-http"
url = "http://127.0.0.1:7776/mcp"

其他客户端（Cline、Cursor、自定义客户端）

让任何兼容 MCP 的客户端连接到 http://127.0.0.1:7776/mcp。支持可流式传输的 HTTP 和有状态会话（以 UUID 为键）。服务名称为 continuum。

---

创建你的第一个项目

在任何已接入的客户端中：

Create a Continuum project for /absolute/path/to/my/repo,
then read the PLOT.md and act as orchestrator
for the following task: <describe what you want done>.

执行过程：

1. 客户端调用 project_create({project: "/absolute/path/..."})
2. 服务创建 PLOT.md（编排协议）和一个空知识库
3. 客户端调用 plot({project})，读取协议并进入编排器模式
4. 客户端遵循 4 阶段工作流——开展研究、验证、保存调度记录，并为你准备一条可直接粘贴的提示词，以便在新的 git worktree 中启动全新的 Agent

你将提示词粘贴到新的 Claude Code / Codex 会话中。该 Agent 会在隔离的 worktree 中，仅针对其预留路径编写代码。其他并行 Agent 可通过协调简报看到该 Agent 的新预留路径。

工作合并后，编排器会通过 knowledge_create 记录所学内容——该项目今后的每次调度都将永久受益。

---

工作流

1. 接收任务

registry_list({project, status:'active'})     // paginated metadata: slug + reservedPaths + timestamps
agent_get({project, slug})                    // bodies (request/plan/implPrompt/coordinationBrief) per active agent
knowledge_list({project, kind:'fundamental'}) // binding-rule metadata
knowledge_get({project, slug})                // body per fundamental slug — read every one
knowledge_search({project, q: "<task intent>"}) // RAG → ranked metadata
knowledge_get({project, slug})                // body for each relevant hit

2. 研究

启动一个 Explore / Plan 子 Agent。它会结合已加载的知识阅读代码库，并按文件生成计划：创建 / 修改 / 删除。只制定计划，不编写代码。

3. 验证

启动一个评审 Agent。它会审查每个涉及的文件，查找孤立代码和损坏的调用点，并与活跃 Agent 的预留路径进行交叉核对。返回带注释的差异。

4. 交接

agent_create({
  project, slug, branch, worktree,
  reservedPaths,        // paths this agent owns
  request,              // verbatim human task
  plan,                 // final agreed plan
  implPrompt,           // self-contained prompt for the dispatched agent
  coordinationBrief,    // short block for every other active agent
})

Agent 创建时状态为 draft。调度时通过 agent_update({status:'active'}) 将其设为活跃状态。合并后，记录 SHA 并保存经验：

agent_update({ project, slug, status:'merged', mergedCommit, postMergeNotes })
knowledge_create({ project, agentSlug, slug, content, kind:'situational' })

编排器绝不会编辑源代码、运行 regen、合并分支或推送提交。它负责研究、验证、协调和保存信息。代码由全新的 Agent 在隔离的 worktree 中编写。

---

MCP 工具

每个工具都将 project（规范的绝对路径）作为第一个参数。

项目

工具	用途
project_list	列出已注册项目
project_get	获取一个项目
project_create	注册项目，创建 PLOT.md 并初始化知识库
project_rename	重命名项目
project_delete	级联删除（项目 + Agent + 经验）

Plot — 编排协议

工具	用途
plot	读取 PLOT.md
plot_update	应用统一 git 格式的差异（零模糊匹配，精确匹配上下文）

plot_update 会严格验证 --- a/PLOT.md / +++ b/PLOT.md / @@ 标头。上下文不匹配时会抛出 hunk_mismatch，并附上失败的 hunk 标头。使用 plot 重新读取，重新生成差异，再试一次。绝不会静默覆盖。

知识——向量记忆

工具	用途
knowledge_list	课程元数据（slug、kind、agentSlug、时间戳）。可选的 kind 筛选条件。不含内容。
knowledge_search	语义查询 → 排序后的元数据。q 为自由文本意图，可选 kind，可选 limit。不含内容。
knowledge_get	按 slug 读取一条课程——完整正文
knowledge_create	记录一条新课程——kind: 'fundamental' | 'situational'。自动生成嵌入。
knowledge_update	替换课程内容。保存时重新生成嵌入。
knowledge_delete	归档一条课程

knowledge_search 会在 sqlite-vec 索引中执行向量查找。传入自然语言文本即可——问题、任务描述和说明都适用。不支持 SQL 通配符语法。响应为排序后的元数据；对于值得阅读的结果，调用 knowledge_get({project, slug}) 获取正文。knowledge_list 也使用相同模式（使用 kind: 'fundamental' 列出所有约束性条目，然后逐条获取）。

Agents

工具	用途
registry_list	分页返回 Agent 元数据——{data, page, limit, hasNextPage}。每个 data 行包含：slug、status、branch、worktree、reservedPaths、时间戳、mergedCommit、abandonedReason。可选的 status 筛选条件；默认 limit 为 10，最大为 50。不含制品正文。
agent_get	按 slug 获取完整记录——包括 request、plan、implPrompt、coordinationBrief、postMergeNotes
agent_create	持久化一条草稿调度记录
agent_update	转换状态、编辑字段

允许的状态转换：draft → active → merged | abandoned。merged 需要 7–40 个字符的 commit SHA。abandoned 需要提供原因。只有 active 状态的 Agent 会预留路径。

registry_list 会在一个分页响应中返回冲突矩阵元数据。若要查看某条调度记录的计划或 implPrompt，请接着调用 agent_get({project, slug})。逐页读取，直到 hasNextPage 为 false。

---

示例会话

human: orchestrate adding rate-limit middleware to /api routes

claude: → registry_list({project, status:'active'})  // 0 active
        → knowledge_list({project, kind:'fundamental'})
                                              // metadata for binding rules
        → knowledge_get({project, slug:'base-branch'})       // → main
        → knowledge_get({project, slug:'worktree-convention'}) // → ../<slug>/
        → knowledge_search({project, q:'rate limit middleware nest interceptor'})
                                              // ✨ 2 ranked hits on guard ordering (metadata)
        → knowledge_get({project, slug:'rate-limit-guard-ordering'}) // bodies fetched
        → spawn Plan subagent → plan returned
        → spawn critique subagent → 1 issue: missed `app.module.ts` registration → fixed
        → agent_create({
            slug: 'rate-limit-middleware',
            branch: 'feature/rate-limit',
            worktree: '/abs/path/../rate-limit-middleware',
            reservedPaths: ['apps/api/src/common/rate-limit/**', 'apps/api/src/app.module.ts'],
            request: 'orchestrate adding rate-limit middleware to /api routes',
            plan: '...',
            implPrompt: '...',
            coordinationBrief: 'reserves common/rate-limit/**, edits app.module.ts (additive)'
          })
        → here's the impl prompt to paste into a fresh session: ...

[ task ships ]

claude: → agent_update({slug:'rate-limit-middleware', status:'merged', mergedCommit:'a1b2c3d'})
        → knowledge_create({
            agentSlug: 'rate-limit-middleware',
            slug: 'rate-limit-guard-ordering',
            kind: 'situational',
            content: 'Rate-limit guards must register AFTER auth guard in app.module.ts.
                      Order in providers array decides execution order. Reverse → 401s
                      bypass rate limiting.'
          })
        // ✅ lesson embedded → vector indexed → permanent memory

下次任何人——无论是你、Claude 还是 Codex——在这个项目中处理任何与速率限制相关的内容时，都会自动显示这条课程。

---

Web 面板

Astro 6 + React 19 islands。Tailwind v4。shadcn/ui。

页面	内容
/	主页
/projects	项目列表——TanStack Table，支持排序和筛选
/agents	跨项目的注册表／状态看板
/knowledge	Markdown 查看器——支持 GFM、语法高亮、锚定章节和搜索
/plot	图表查看器 + 编辑器，带差异预览
/settings	Embedder URL + 模型 + 维度、tokenizer 密钥、REST 网关、日志级别

设置存储在 app_settings（SQLite）中，并会覆盖环境变量。无头部署仍可仅通过环境变量运行。

---

配置

同时支持环境变量和面板设置。面板设置优先。

变量	默认值	用途
PORT	7776	HTTP 端口
CORS_ORIGIN	未设置	* 或以逗号分隔的来源
ORCHESTRATOR_DB_PATH	/data/orchestrator.db	SQLite 路径。开发脚本会覆盖为 ./.local-data/orchestrator.db
PANEL_REST_ENABLED	false	挂载 /api/orchestrator/* REST 接口（面板使用）
NODE_ENV	未设置	生产环境会阻止破坏性迁移
ORCHESTRATOR_ALLOW_DESTRUCTIVE_MIGRATE	未设置	在生产环境中设为 1 以覆盖限制
ANTHROPIC_API_KEY	未设置	Token 计数端点（仅服务端）
ANTHROPIC_TOKENIZER_MODEL	claude-opus-4-7	count_tokens 使用的模型名称
EMBEDDER_URL	未设置	HTTP 嵌入端点（Ollama / TEI / OpenAI-compatible）。未设置 → 进程内嵌入器
EMBEDDER_MODEL	Snowflake/snowflake-arctic-embed-m-v1.5	模型 ID（进程内默认值；配置 HTTP 嵌入器时会传递给它）
EMBEDDER_DIM	768	预期的嵌入维度

---

技术栈

层	技术
记忆	sqlite-vec 向量索引 • 通过 Transformers.js 在进程内运行的 Snowflake Arctic Embed v1.5（默认）• 通过 EMBEDDER_URL 指定的 Ollama / TEI / OpenAI 兼容嵌入器 • 固定新鲜度的向量
API	NestJS 11 • @rekog/mcp-nest • @modelcontextprotocol/sdk 1.10 • Zod 4 • Swagger
持久化	better-sqlite3（WAL、FK、busy_timeout 5s）
差异引擎	diff 9（零容错统一差异应用器）
Web	Astro 6 • React 19 • Tailwind 4 • shadcn/ui • TanStack Table • rehype/remark • highlight.js
工具链	Turborepo 2 • pnpm 10.33 • TypeScript 5.9 • Prettier 3 • Jest

---

脚本

pnpm dev          # turbo run dev — api + web in watch
pnpm build        # turbo run build
pnpm lint         # turbo run lint
pnpm check-types  # turbo run check-types
pnpm format       # prettier across ts/tsx/js/astro/md/json

pnpm -F @continuum/api dev          # api only — nest start --watch
pnpm -F @continuum/api mcp:dev      # api with local SQLite at .local-data/
pnpm -F @continuum/api test         # jest unit tests
pnpm -F @continuum/api test:e2e     # jest e2e

pnpm -F @continuum/web dev          # web only — astro dev
pnpm -F @continuum/web build        # astro build → dist/

---

约定

• project 始终是规范的绝对路径。 传入项目根目录，切勿传入工作树子目录。工作树路径会触发 project_not_found。
• Plot 的修改通过统一差异完成。 不写入全文。上下文不匹配时，服务会通过失败的 @@ 标头拒绝请求。
• 知识更新会整体替换内容。 传入完整的新 content。保存时会重新嵌入。
• 保留路径是 JSON glob 数组。 只有处于 active 状态的 Agent 会保留路径。
• 启动时只执行向前迁移。 除非明确选择启用，否则生产环境会阻止破坏性迁移。

---

故障排除

症状	可能原因
project_not_found	传入了工作树路径。请使用通过 project_create 注册的规范项目根目录。
plot_update 返回 hunk_mismatch	差异已过时。使用 plot 重新读取，基于当前内容重新生成差异，然后重试。
knowledge_search / knowledge_list 返回空结果 / 异常结果	嵌入器无法访问、模型不匹配，或维度不匹配（仅搜索时）。检查 /settings。回填过时的向量。请记住：两者都只返回元数据——调用 knowledge_get({project, slug}) 获取正文。
切换嵌入器后向量未重新生成	新鲜度配置（URL + 模型 + 维度）必须发生变化。重启服务以触发回填。
agent_update 返回 invalid_transition	允许的状态转换：draft → active → merged | abandoned。其他转换都会报错。
missing_merged_commit / invalid_merged_commit	merged 状态要求 SHA 长度为 7–40 个字符。
生产环境拒绝执行架构迁移	如果确实需要，请设置 ORCHESTRATOR_ALLOW_DESTRUCTIVE_MIGRATE=1。

---

路线图

• 跨项目知识共享（kind: 'global'）
• 使用小型重排序模型对嵌入结果进行重排序
• 一次性导入现有的 CLAUDE.md / AGENTS.md / Cursor 规则 → 基础知识
• 只读公共知识镜像（将项目经验发布为静态网站）
• 为 SessionStart / SessionEnd 事件内置观察钩子

---

贡献

欢迎贡献。请 Fork、创建分支、测试并提交 PR。遵循 Prettier 默认设置（100 列、双引号、分号、ES5 尾随逗号）。MCP 工具变更必须使用 Zod 类型。

---

支持

问题	GitHub Issues
文档	此 README + /docs 中的 Swagger UI + 每个项目中预置的 PLOT.md
MCP 规范	https://modelcontextprotocol.io

---