# https://github.com/nikhilkagita04/continuum 项目说明书

生成时间：2026-06-24 06:29:29 UTC

## 目录

- [概览、安装与版本分层](#page-1)
- [系统架构与四阶段数据流](#page-2)
- [捕获质量与 Stage 1（社区重点议题）](#page-3)
- [图谱后端、MCP 集成与可扩展性](#page-4)

<a id='page-1'></a>

## 概览、安装与版本分层

### 相关页面

相关主题：[系统架构与四阶段数据流](#page-2), [图谱后端、MCP 集成与可扩展性](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/nikhilkagita04/continuum/blob/main/README.md)
- [package.json](https://github.com/nikhilkagita04/continuum/blob/main/package.json)
- [CONTRIBUTING.md](https://github.com/nikhilkagita04/continuum/blob/main/CONTRIBUTING.md)
- [backend/graphiti/README.md](https://github.com/nikhilkagita04/continuum/blob/main/backend/graphiti/README.md)
- [backend/graphiti/sidecar.py](https://github.com/nikhilkagita04/continuum/blob/main/backend/graphiti/sidecar.py)
- [examples/claude-desktop.json](https://github.com/nikhilkagita04/continuum/blob/main/examples/claude-desktop.json)
- [daemon/stage1/capture.swift](https://github.com/nikhilkagita04/continuum/blob/main/daemon/stage1/capture.swift)
- [daemon/stage1/screen.swift](https://github.com/nikhilkagita04/continuum/blob/main/daemon/stage1/screen.swift)
</details>

# 概览、安装与版本分层

## 项目定位与核心理念

Continuum 是一个开源、本地优先的"**上下文捕获 + 记忆层**"(capture + memory layer),在仓库中被明确自我定位为"a primitive, not an app"——一个供他人构建用例的底层铲子,而不是又一个封闭的"大脑"应用。资料来源:[README.md:23-31]()

它要解决的核心痛点是:用户在 Claude、Slack、X、Gemini、设计工具等十几个应用间切换时,每个应用都是"从零开始",前一处的上下文对新工具不可见,**用户被迫成为搬运工**,反复粘贴、解释、重新建立语境。Continuum 的策略是:在用户机器上静默记住每个应用里发生的事,然后让任何代理(Claude、Cursor、自建 Agent)通过查询接口复用这些记忆。资料来源:[README.md:9-15]()

所有数据落在 `~/.continuum`,凭据管理器被默认排除、PII 会被脱敏,信息不出本机,这构成了项目的核心隐私承诺。资料来源:[README.md:31-35]()

## 安装、构建与快速验证

### 运行时依赖

- **Node.js ≥ 18**,由 `package.json` 的 `engines` 字段强制要求。资料来源:[package.json:64-66]()
- **macOS 权限**:`daemon/stage1/screen.swift`(OCR 全屏抓取)需要 Screen Recording;`daemon/stage1/capture.swift`(AX 结构化抓取)需要 Accessibility。两者是互补的抓取器,任选其一即可让 pipeline 工作。资料来源:[daemon/stage1/screen.swift:39-46](), [daemon/stage1/capture.swift:6-9]()

### 三种安装路径

| 方式 | 命令 | 适用场景 |
|---|---|---|
| 全局安装 | `npm install -g continuum-core` | 一般终端用户 |
| 源码软链 | `git clone … && cd continuum && npm link` | 本地开发与贡献 |
| 构建 Swift helper | `swiftc daemon/stage1/screen.swift -o daemon/stage1/screen` | 启用 macOS OCR 抓取 |

资料来源:[README.md:20-30](), [package.json:11-16]()

### 一键验证

安装后立即执行 `continuum verify`——它会在**无密钥、无权限弹窗、无外部配置**的情况下跑通 capture → segment → index → distill → recall 的全链路,是项目最常用的 smoke test。资料来源:[README.md:25-27](), [package.json:14-15]()

### 日常命令与脚本

`package.json` 暴露的核心脚本:`test`(36 个单测与集成测试,纯本地、零网络)、`verify`、`build:capture`、`build:app`、`start`。其中 `start` 等价于 `node bin/continuum.mjs start`。资料来源:[package.json:13-18]()

运行时常用 CLI:`continuum start` 开启抓取、`continuum dashboard` 在 `localhost:3939` 打开可搜索时间线、`continuum mcp-install` 一键接入 Claude Desktop、`continuum mcp-config` 打印配置供其他 MCP 客户端(Cursor、自建 Agent)手动接入。资料来源:[README.md:35-52]()

## 版本分层 (Tiers)

项目刻意把能力切成三层,**确保免费档完全离线、核心代码不依赖任何云厂商**。`Stages 2–4` 接收注入式适配器(embedder / LLM / graph),所以"上不上云"是部署侧的配置选择,而不是代码改动。资料来源:[CONTRIBUTING.md:7-12]()

| 能力 | Free | Pro(后续) | Enterprise(后续) |
|---|---|---|---|
| Capture · Recall · MCP | ✅ | ✅ | ✅ |
| Embeddings / LLM | 本地,$0 | OpenAI / Anthropic | 托管 |
| 时序知识图谱 | — | ✅ | ✅(团队图谱) |

资料来源:[README.md:60-66]()

图谱层之所以成为付费线,是因为实体/关系抽取需要 frontier 模型:开源或本地模型无法稳定满足 Graphiti 的严格 schema(`EdgeDuplicate`、`NodeResolutions`),会在 pydantic 校验阶段报错。可选的侧车 `backend/graphiti/sidecar.py` 自托管 Neo4j + Graphiti + OpenAI/Anthropic,通过 FastAPI 暴露 `/add`、`/search`、`/health`,并在 `~/.continuum/config.json` 中通过 `graph.url` 启用。资料来源:[backend/graphiti/README.md:5-11](), [backend/graphiti/sidecar.py:42-58](), [backend/graphiti/README.md:35-44]()

## MCP 集成与社区关注点

`continuum mcp-install` 会把 Continuum 注册为 Claude Desktop 的 MCP 服务,**保留并备份用户已有配置**,仅合并 `continuum` 块。配置示例见 `examples/claude-desktop.json`,需要把 `<NODE>` 与 `<ABSOLUTE_PATH>` 替换为本机路径,然后**完全退出并重启**(Cmd+Q)Claude Desktop。资料来源:[README.md:46-52](), [examples/claude-desktop.json:1-7]()

社区当前最活跃的四个议题全部聚焦在 **Stage 1 抓取质量**——也正是安装后立刻会被开发者遇到的"第一公里"问题:

- **#1**:把 macOS AX 的 `AXFocusedUIElement` 单独作为 `source: "input"` 事件输出,因为它就是用户**亲手键入**的内容,跟 OCR 抓到的页面背景天然分离。资料来源:[issue #1]()
- **#2**:在 Stage 4 增加一次 LLM 结构化 pass,把 OCR 原始文本归一为 `(author, content, app)` 字段,语义化、跨 UI 改版可复用,比按站点写解析器更鲁棒。资料来源:[issue #2]()
- **#3**:对浏览器窗口做"顶部工具栏带"启发式裁剪,先去掉 tab 与书签栏再 OCR。资料来源:[issue #3]()
- **#4**:按窗口标题排除 Continuum 自己的 dashboard 与终端;`screen.swift` 已用 `SELF_MARKERS` 做了简易字符串守卫(`"What your machine captured"`、`"continuum: tier="`、`"capture=screen embed="`),但仍待硬化。资料来源:[issue #4](), [daemon/stage1/screen.swift:23-26]()

## 另见 (See Also)

- 抓取 → 蒸馏全链路深读:[docs/architecture/ingestion-pipeline.md]()
- 图谱侧车自托管与配置:[backend/graphiti/README.md]()
- 贡献流程与 DCO 签名:[CONTRIBUTING.md]()
- Stage 1 抓取源码:`daemon/stage1/capture.swift`、`daemon/stage1/screen.swift`
- Stage 2–4 可导入模块(SDK 入口):`package.json` 的 `exports` 字段 — `daemon/pipeline.mjs`、`daemon/stage2/segmenter.mjs`、`daemon/stage3/index.mjs`、`daemon/stage4/distill.mjs`、`daemon/retrieval.mjs`、`daemon/adapters.mjs`、`daemon/config.mjs`。资料来源:[package.json:5-13]()

---

<a id='page-2'></a>

## 系统架构与四阶段数据流

### 相关页面

相关主题：[概览、安装与版本分层](#page-1), [捕获质量与 Stage 1（社区重点议题）](#page-3), [图谱后端、MCP 集成与可扩展性](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/nikhilkagita04/continuum/blob/main/README.md)
- [package.json](https://github.com/nikhilkagita04/continuum/blob/main/package.json)
- [CONTRIBUTING.md](https://github.com/nikhilkagita04/continuum/blob/main/CONTRIBUTING.md)
- [daemon/pipeline.mjs](https://github.com/nikhilkagita04/continuum/blob/main/daemon/pipeline.mjs)
- [daemon/retrieval.mjs](https://github.com/nikhilkagita04/continuum/blob/main/daemon/retrieval.mjs)
- [daemon/adapters.mjs](https://github.com/nikhilkagita04/continuum/blob/main/daemon/adapters.mjs)
- [daemon/stage1/capture.swift](https://github.com/nikhilkagita04/continuum/blob/main/daemon/stage1/capture.swift)
- [daemon/stage1/screen.swift](https://github.com/nikhilkagita04/continuum/blob/main/daemon/stage1/screen.swift)
- [daemon/stage2/segmenter.mjs](https://github.com/nikhilkagita04/continuum/blob/main/daemon/stage2/segmenter.mjs)
- [daemon/stage3/index.mjs](https://github.com/nikhilkagita04/continuum/blob/main/daemon/stage3/index.mjs)
- [daemon/stage4/distill.mjs](https://github.com/nikhilkagita04/continuum/blob/main/daemon/stage4/distill.mjs)
- [backend/graphiti/README.md](https://github.com/nikhilkagita04/continuum/blob/main/backend/graphiti/README.md)
- [backend/graphiti/sidecar.py](https://github.com/nikhilkagita04/continuum/blob/main/backend/graphiti/sidecar.py)
- [packaging/menubar.swift](https://github.com/nikhilkagita04/continuum/blob/main/packaging/menubar.swift)
- [examples/claude-desktop.json](https://github.com/nikhilkagita04/continuum/blob/main/examples/claude-desktop.json)

</details>

# 系统架构与四阶段数据流

## 1. 设计原则与总体定位

Continuum 是一个本地优先（local-first）的捕获与记忆层，定位为"可被组合的基元（primitive）"而非独立 App。其核心架构原则是：**捕获路径不接触 LLM**——只有后端"蒸馏"阶段才调用大模型，从而把高频采集与模型调用解耦，保持轻量。资料来源：[README.md:13-15]()。

整体流程遵循 `capture → segment → index → distill` 四个阶段。README 给出量化目标：每天约 29,000 条原始事件经分层处理后只产生约 30 次 LLM 调用。资料来源：[README.md:35-38]()。该四阶段模型由 `daemon/pipeline.mjs` 串联，每个阶段都是一个可独立测试、可注入适配器（embedder / LLM / graph）的小模块。资料来源：[CONTRIBUTING.md:15-18]()。

## 2. Stage 1：事件驱动捕获（macOS 原生）

Stage 1 在 macOS 上提供两条互斥的捕获路径，都向 stdout 写入统一的 NDJSON `CaptureEvent`，其结构为 `{t, source, app, window_id, url_host?, title?, text, secure?}`，由 `daemon/pipeline.mjs` 消费。资料来源：[daemon/stage1/capture.swift:5-13]()。

**AX 路径**（`daemon/stage1/capture.swift`）基于 `NSWorkspace`、每 PID 一个 `AXObserver`、以及 1 秒剪贴板轮询，事件驱动而非轮询。资料来源：[daemon/stage1/capture.swift:1-5]()。`CHROME_ROLES` 集合过滤按钮、菜单、工具栏等 UI 噪声，仅保留 ≥3 词或 ≥24 字符的实质文本。资料来源：[daemon/stage1/capture.swift:25-40]()。`isSecure()` 通过 `AXSecureTextField` 识别安全输入字段，避免泄露密码。资料来源：[daemon/stage1/capture.swift:18-22]()。

**OCR 路径**（`daemon/stage1/screen.swift`）使用 `ScreenCaptureKit` 截取聚焦窗口并调用 Apple Vision OCR。资料来源：[daemon/stage1/screen.swift:1-5]()。通过感知哈希（perceptual hash）确保**仅在屏幕有意义变化时才执行 OCR**，静态窗口成本几乎为零。资料来源：[daemon/stage1/screen.swift:21-23]()。`EXCLUDED` 集合与 `CONTINUUM_EXCLUDE` 环境变量共同排除 1Password、Keychain 等凭据管理器。资料来源：[daemon/stage1/screen.swift:11-17]()。

两条路径通过 shell 管道接入 Node 流水线：`./daemon/stage1/capture | node daemon/pipeline.mjs`。资料来源：[daemon/stage1/capture.swift:2-4]()。`packaging/menubar.swift` 中的菜单栏应用以相同方式捆绑并启动该管道。资料来源：[packaging/menubar.swift:25-30]()。

## 3. Stage 2–4：分段、索引、蒸馏

`package.json` 的 `exports` 字段把每个阶段作为独立 ES Module 暴露，便于第三方组合与测试：

- `.` → `daemon/pipeline.mjs`（主入口）
- `./segmenter` → `daemon/stage2/segmenter.mjs`
- `./index` → `daemon/stage3/index.mjs`
- `./distill` → `daemon/stage4/distill.mjs`
- `./retrieval` / `./adapters` / `./config`

资料来源：[package.json:8-17]()。测试脚本也按此顺序执行：`segmenter → index → distill → pipeline → store`。资料来源：[package.json:19-21]()。

- **Stage 2 — 分段（Segment）**：将高频原始事件按应用、窗口、空白停顿等启发式聚合成有意义的"片段（episode）"。
- **Stage 3 — 索引（Index）**：构建本地混合索引，结合向量召回与结构化字段，提供零云端成本的检索能力。资料来源：[README.md:11-15]()。
- **Stage 4 — 蒸馏（Distill）**：可选 LLM 介入层，把原始片段压缩为更高级语义结构。`daemon/adapters.mjs` 通过依赖注入接受任意 LLM 适配器，保证核心可离线运行。资料来源：[CONTRIBUTING.md:9-12]()。

```mermaid
flowchart LR
  subgraph S1["Stage 1 — 捕获 (macOS)"]
    AX["daemon/stage1/capture.swift<br/>AXObserver 事件驱动"]
    OCR["daemon/stage1/screen.swift<br/>Vision OCR"]
  end
  P["daemon/pipeline.mjs"]
  S2["daemon/stage2/segmenter.mjs"]
  S3["daemon/stage3/index.mjs"]
  S4["daemon/stage4/distill.mjs"]
  R["daemon/retrieval.mjs"]
  M["daemon/mcp-server.mjs"]
  G["backend/graphiti/sidecar.py<br/>Neo4j + Graphiti"]
  AX --> P
  OCR --> P
  P --> S2 --> S3 --> S4
  S4 --> R --> M
  S4 -. 可选 .-> G
```

## 4. 检索、MCP 与可选时间图谱

查询路径从 `daemon/retrieval.mjs` 进入，被 Claude Desktop 等 MCP 客户端通过 `daemon/mcp-server.mjs` 调用。资料来源：[examples/claude-desktop.json:1-7]()。免费层完全使用本地混合索引，零云端依赖。资料来源：[README.md:11-15]()。

**可选的时间知识图谱**通过 `backend/graphiti/sidecar.py` 实现，基于 Graphiti（Apache-2.0）并以 Neo4j 为底层存储。资料来源：[backend/graphiti/README.md:1-8]()。该层强制使用前沿 LLM（Claude 或 GPT）以满足 graphiti 严格的结构化抽取 schema，本地模型不可靠。资料来源：[backend/graphiti/sidecar.py:18-26]()。这正是 README "Tiers" 表中"graph 层级需前沿模型"的原因。资料来源：[README.md:43-46]()。

## 5. 社区关注的捕获质量改进

当前社区议题集中于 Stage 1 与 Stage 4 的捕获质量：

- **Issue #1（AX focused element）**：OCR 会把用户键入文本与页面其余内容混杂；建议在 AX 路径上把 `AXFocusedUIElement` 作为独立 `source: "input"` 事件发出，键控于 focus+role，在 Chrome 中仍稳定。资料来源：[daemon/stage1/capture.swift:5-13]()`。
- **Issue #2（LLM 结构化 pass）**：提议在 Stage 4 增加一次 LLM 整理 pass，从原始 OCR 抽取 `(author, content, app)` 等结构化字段，运行于 distill 时刻。资料来源：[daemon/stage4/distill.mjs:1-3]()`。
- **Issue #3（浏览器噪声）**：在 OCR 路径中按启发式裁掉标签栏/书签栏后再识别。资料来源：[daemon/stage1/screen.swift:24-26]()`。
- **Issue #4（自指排除）**：通过 `SELF_MARKERS` 排除 Continuum 自己的 dashboard 与终端窗口，避免回声捕获。资料来源：[daemon/stage1/screen.swift:19-21]()`。

## See Also

- 安装与运行：[README.md](https://github.com/nikhilkagita04/continuum/blob/main/README.md)
- 贡献与核心原则：[CONTRIBUTING.md](https://github.com/nikhilkagita04/continuum/blob/main/CONTRIBUTING.md)
- 模块入口与脚本：[package.json](https://github.com/nikhilkagita04/continuum/blob/main/package.json)
- 可选图谱后端：[backend/graphiti/README.md](https://github.com/nikhilkagita04/continuum/blob/main/backend/graphiti/README.md)
- 菜单栏 GUI 封装：[packaging/menubar.swift](https://github.com/nikhilkagita04/continuum/blob/main/packaging/menubar.swift)

---

<a id='page-3'></a>

## 捕获质量与 Stage 1（社区重点议题）

### 相关页面

相关主题：[系统架构与四阶段数据流](#page-2), [图谱后端、MCP 集成与可扩展性](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [daemon/stage1/capture.swift](https://github.com/nikhilkagita04/continuum/blob/main/daemon/stage1/capture.swift)
- [daemon/stage1/screen.swift](https://github.com/nikhilkagita04/continuum/blob/main/daemon/stage1/screen.swift)
- [daemon/stage1/files.mjs](https://github.com/nikhilkagita04/continuum/blob/main/daemon/stage1/files.mjs)
- [docs/architecture/capture-quality.md](https://github.com/nikhilkagita04/continuum/blob/main/docs/architecture/capture-quality.md)
- [daemon/stage4/distill.mjs](https://github.com/nikhilkagita04/continuum/blob/main/daemon/stage4/distill.mjs)
- [README.md](https://github.com/nikhilkagita04/continuum/blob/main/README.md)
- [package.json](https://github.com/nikhilkagita04/continuum/blob/main/package.json)
- [CONTRIBUTING.md](https://github.com/nikhilkagita04/continuum/blob/main/CONTRIBUTING.md)
</details>

# 捕获质量与 Stage 1（社区重点议题）

## 概述

Continuum 的"上下文记忆"能力完全取决于 Stage 1 抓取事件的质量——任何错误的内容、重复的 UI 噪声或缺失的用户输入都会污染下游的 segment、index、distill 流程。社区当前最关注的 4 个与捕获质量直接相关的议题是：

- **#1**：把 macOS 的 `AXFocusedUIElement` 作为"用户实际键入"的内容单独发出；
- **#2**：在 Stage 4 中加入 LLM 结构化阶段，把 OCR 原始文本归并为 `(author, content, app)`；
- **#3**：在 OCR 之前裁掉浏览器的标签/书签栏；
- **#4**：排除 Continuum 自身的 dashboard 与终端窗口。

这些议题的共同目标是——"让每条 `CaptureEvent` 都更接近『你做的事』，而不是『你看到的画面』"。Continuum 在 README 中强调"~29k 原始事件 / 天 → ~30 次 LLM 调用"，因为 LLM 不参与 capture 路径，正是为了把捕获层保持轻量与本地。资料来源：[README.md:1-30]()。

## Stage 1 的双轨架构

Stage 1 同时提供两条互斥的捕获路径，由 `package.json` 中的 `build:capture` 脚本独立编译：

| 路径 | 可执行文件 | 触发机制 | 主要职责 |
|---|---|---|---|
| 事件驱动（AX） | `daemon/stage1/capture` | `NSWorkspace` + `AXObserver` + 1s 剪贴板轮询 | 抓取"焦点 + 值变化"的结构化文本，主动跳过 UI chrome |
| 视觉兜底（OCR） | `daemon/stage1/screen` | `ScreenCaptureKit` + Apple Vision | 抓取任意"焦点窗口"的整图 OCR，仅在屏幕显著变化时触发 |

资料来源：[package.json:1-50](), [daemon/stage1/capture.swift:1-15](), [daemon/stage1/screen.swift:1-25]()。

```mermaid
flowchart LR
  A[前台 App] -->|NSWorkspace didActivate| B(capture.swift)
  A -->|ScreenCaptureKit| C(screen.swift)
  B -->|NDJSON: source=ax| D[pipeline.mjs]
  C -->|NDJSON: source=ocr| D
  D --> E[Stage 2 segmenter]
  E --> F[Stage 3 index]
  F --> G[Stage 4 distill]
  G -->|LLM structuring · #2| H[结构化 episode]
```

## 排除 Continuum 自身窗口（Issue #4）

两条路径都实现了显式的"自我排除"。

OCR 路径内置三段硬编码字符串作为自识别锚点：dashboard 标题 `"What your machine captured"`、终端 banner `"continuum: tier="`、以及启动信息 `"capture=screen embed="`，命中任一即丢弃。资料来源：[daemon/stage1/screen.swift:20-35]()。

社区方案进一步要求按窗口标题做白/黑名单（而非抓取站点 DOM），设计文档 `docs/architecture/capture-quality.md` 明确指出"不要抓取 site DOM"——那会把捕获层锁死在每个站点的版式上，违背"语义通用"的目标。AX 路径则天然不会同时持有 Continuum 自身进程的焦点，但仍依赖 `extractText` 的 chrome 角色过滤把残留文本压到 0。资料来源：[issue #4](https://github.com/nikhilkagita04/continuum/issues/4), [daemon/stage1/capture.swift:40-70]()。

## 浏览器标签/书签栏裁剪（Issue #3）

浏览器抓取时，OCR 第一行常常是"标签栏 + 书签栏 + 地址栏"，整段都属 chrome。`screen.swift` 维护了 7 个常见浏览器集合（`Google Chrome`、`Safari`、`Arc`、`Firefox`、`Microsoft Edge`、`Brave Browser`、`Opera`），命中时调用 `cropTopBand(_:fraction:)` 在 OCR 之前把图像顶部按比例裁掉。

由于工具栏高度因扩展、书签可见性、窗口尺寸变化，裁剪比例保持保守，并通过 `CGImage.cropping(to:)` 在 CoreGraphics 层面完成；失败时安全回退到原图，不会让 Stage 1 崩溃。资料来源：[daemon/stage1/screen.swift:35-50](), [issue #3](https://github.com/nikhilkagita04/continuum/issues/3)。

## AX 焦点元素独立为"用户输入"事件（Issue #1）

`capture.swift` 的 `Capture.captureFocused()` 读取 `kAXFocusedUIElementAttribute`，对焦点元素的 value 做 `extractText`（`budget=6000` 字符），并用 `lastEmit` 字典按窗口 id 做 ≤1 emit / 400ms 的合并，防止键入爆发导致事件洪水。

社区建议把这段 value 作为独立的 `CaptureEvent`（例如 `source: "input"`）发出——它正是用户在邮件/聊天框里实际键入的文字，键路径 `focus+role` 在 Chrome 中也比整棵 AX 树更稳定，因为 Chrome 经常让非焦点元素也参与整树重构。资料来源：[daemon/stage1/capture.swift:80-110](), [issue #1](https://github.com/nikhilkagita04/continuum/issues/1)。

与此同时，代码内置了双重安全护栏：`isSecure(_:)` 在焦点元素是 `AXSecureTextField` 时直接 `return`，永不读取密码字段内容；`EXCLUDED` 集合默认屏蔽 `1Password`、`Keychain Access`、`Bitwarden`、`Dashlane`、`LastPass`，并支持 `CONTINUUM_EXCLUDE` 环境变量追加。资料来源：[daemon/stage1/capture.swift:20-40](), [daemon/stage1/screen.swift:10-20]()。

## Stage 4 的 LLM 结构化（Issue #2）

原始 OCR 文本把作者、内容、应用上下文混在一行。社区提出在 Stage 4（distill）注入 LLM，把 `(author, content, app)` 拆开并丢弃 chrome 噪声——这是"语义通用"的关键：与"按站点写 parser"相比，LLM 抽象了 UI 重设计带来的脆弱性。

设计文档 `docs/architecture/capture-quality.md` 与 `daemon/stage4/distill.mjs` 共同定义该 pass 的契约：可注入的 LLM 适配器、运行于 distill 时（不是 capture 时）、不污染 capture 路径。`CONTRIBUTING.md` 中的"Keep the core pure"也明确要求 Stage 2–4 通过注入适配器运行离线，不能硬编码云依赖。资料来源：[issue #2](https://github.com/nikhilkagita04/continuum/issues/2), [daemon/stage4/distill.mjs:1-30](), [CONTRIBUTING.md:1-20]()。

## 常见失效模式与防御

| 现象 | 触发场景 | 现有防御 |
|---|---|---|
| 抓到自己 | 终端/CI 中运行 `continuum start` | `SELF_MARKERS` 字符串匹配 |
| 抓到密码 | 焦点落在 `AXSecureTextField` | `isSecure` 早 return |
| 重复键入风暴 | 快速键入期间 | 400ms / 窗口 合并 |
| OCR 全是 chrome | 浏览器前台 | `cropTopBand` 顶部裁剪 |
| 多余应用前台 | 凭据管理器 | `EXCLUDED` + `CONTINUUM_EXCLUDE` |
| Stage 1 把站点版式耦合进来 | 改用 DOM 抓取 | 设计文档明确禁止 |

资料来源：[daemon/stage1/screen.swift:20-50](), [daemon/stage1/capture.swift:20-110](), [docs/architecture/capture-quality.md]()。

## See Also

- 架构总览：[README.md](https://github.com/nikhilkagita04/continuum/blob/main/README.md)
- 四阶段流水线：[docs/architecture/ingestion-pipeline.md](https://github.com/nikhilkagita04/continuum/blob/main/docs/architecture/ingestion-pipeline.md)
- 捕获质量设计文档：[docs/architecture/capture-quality.md](https://github.com/nikhilkagita04/continuum/blob/main/docs/architecture/capture-quality.md)
- 社区议题：#1 / #2 / #3 / #4
- 图谱侧车（可选付费层）：[backend/graphiti/README.md](https://github.com/nikhilkagita04/continuum/blob/main/backend/graphiti/README.md)
- Claude Desktop MCP 配置示例：[examples/claude-desktop.json](https://github.com/nikhilkagita04/continuum/blob/main/examples/claude-desktop.json)

---

<a id='page-4'></a>

## 图谱后端、MCP 集成与可扩展性

### 相关页面

相关主题：[概览、安装与版本分层](#page-1), [系统架构与四阶段数据流](#page-2), [捕获质量与 Stage 1（社区重点议题）](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [backend/graphiti/sidecar.py](https://github.com/nikhilkagita04/continuum/blob/main/backend/graphiti/sidecar.py)
- [backend/graphiti/README.md](https://github.com/nikhilkagita04/continuum/blob/main/backend/graphiti/README.md)
- [daemon/mcp-server.mjs](https://github.com/nikhilkagita04/continuum/blob/main/daemon/mcp-server.mjs)
- [daemon/dashboard.mjs](https://github.com/nikhilkagita04/continuum/blob/main/daemon/dashboard.mjs)
- [examples/claude-desktop.json](https://github.com/nikhilkagita04/continuum/blob/main/examples/claude-desktop.json)
- [examples/standup.mjs](https://github.com/nikhilkagita04/continuum/blob/main/examples/standup.mjs)
- [README.md](https://github.com/nikhilkagita04/continuum/blob/main/README.md)
- [package.json](https://github.com/nikhilkagita04/continuum/blob/main/package.json)
- [CONTRIBUTING.md](https://github.com/nikhilkagita04/continuum/blob/main/CONTRIBUTING.md)
- [daemon/stage1/capture.swift](https://github.com/nikhilkagita04/continuum/stage1/capture.swift)
- [daemon/stage1/screen.swift](https://github.com/nikhilkagita04/continuum/stage1/screen.swift)
</details>

# 图谱后端、MCP 集成与可扩展性

## 概述

Continuum 是一个"开箱即用"的本地优先捕获与记忆层（capture + memory layer），定位为**可被二次构建的基元（primitive）**，而非端到端应用 [README.md](README.md)。其核心由四阶段流水线组成（capture → segment → index → distill），各阶段皆为可独立导入的模块 [README.md](README.md)。在此基础上，项目通过**可选的图谱后端**（基于 [Graphiti](https://github.com/getzep/graphiti) 的时序知识图谱）扩展高级能力，并通过 **MCP（Model Context Protocol）** 将本地记忆暴露给 Claude Desktop、Cursor 等外部代理。本页聚焦这三层：图谱后端的部署契约、MCP 接入流程，以及整体架构的可扩展性边界。

## 图谱后端（Graph Tier Sidecar）

### 角色与边界

图谱后端是**可选的高级组件**，并未进入默认 `verify` 流程。它的存在是为"实体—关系"抽取与双时态（bi-temporal）边建模提供能力——即"X 变为 Y"会作为新事实被记录，而不是覆盖旧事实 [backend/graphiti/README.md](backend/graphiti/README.md)。

```mermaid
flowchart LR
  P[Continuum Pipeline<br/>stage1-4] -- "POST /add" --> S[Graphiti Sidecar<br/>sidecar.py: FastAPI]
  S -- "graphiti.add_episode" --> N[(Neo4j<br/>bolt://7687)]
  S -- "embeddings / rerank" --> OAI[OpenAI Embeddings<br/>+ Reranker]
  S -- "extraction LLM" --> LLM{Anthropic<br/>or OpenAI}
  A[Agent / MCP Client] -- "POST /search" --> S
```

### 部署契约

后端以 FastAPI 应用形式运行（`sidecar.py`），生命周期由 `lifespan` 钩子管理，在启动时尝试 `graphiti.build_indices_and_constraints()`，关闭时调用 `graphiti.close()` [backend/graphiti/sidecar.py:48-58](backend/graphiti/sidecar.py)。环境变量驱动整套配置：

| 变量 | 作用 | 默认值 |
|---|---|---|
| `OPENAI_API_KEY` | 必填，用于 embeddings 与 reranker | — |
| `GRAPHITI_LLM_PROVIDER` | 抽取 LLM 提供方 | `openai` |
| `GRAPHITI_LLM_MODEL` | 抽取主模型 | `gpt-4o-mini` / `claude-sonnet-4-6` |
| `GRAPHITI_LLM_SMALL` | 抽取小模型 | `claude-haiku-4-5-20251001` |
| `GRAPHITI_EMB_MODEL` | 嵌入模型 | `text-embedding-3-small` |
| `NEO4J_URI` / `NEO4J_USER` / `NEO4J_PASSWORD` | 图数据库连接 | `bolt://localhost:7687` / `neo4j` / `password` |

资料来源：[backend/graphiti/sidecar.py:1-47](backend/graphiti/sidecar.py) | [backend/graphiti/README.md](backend/graphiti/README.md)

### 端点

FastAPI 暴露三个端点：`POST /add`（接收文本并落库为 `EpisodeType.text`，附加 `source_description="continuum capture"`）[backend/graphiti/sidecar.py:67-77](backend/graphiti/sidecar.py)、`POST /search`（调用 `graphiti.search`，返回 `uuid`/`fact`/`name` 字段）[backend/graphiti/sidecar.py:80-86](backend/graphiti/sidecar.py)、`GET /health` [backend/graphiti/sidecar.py:89-90](backend/graphiti/sidecar.py)。注意：抽取必须使用**前沿模型（frontier model）**，本地开源模型因无法满足 graphiti 的严格结构化输出（`EdgeDuplicate`/`NodeResolutions`）而会在 pydantic 校验阶段失败 [backend/graphiti/sidecar.py:25-33](backend/graphiti/sidecar.py)，这也是 README 中将"图谱层"定位为付费/Pro 能力的根本原因 [README.md](README.md)。

## MCP 集成

### 安装路径

Continuum 提供了两种将 MCP 服务器注册到 Claude Desktop 的方式：

- `continuum mcp-install`——自动合并到现有配置，保留并备份原文件 [README.md](README.md)。
- `continuum mcp-config`——打印完整配置，由用户自行合并 [README.md](README.md)。

合并后必须**完全退出并重启** Claude Desktop（Cmd+Q）使 MCP 加载 [README.md](README.md)。

### 服务器契约

`examples/claude-desktop.json` 描述了标准配置：MCP 客户端以 `node` 进程启动 `daemon/mcp-server.mjs` [examples/claude-desktop.json:1-9](examples/claude-desktop.json)。注释中提示：`<NODE>` 应替换为 `which node` 的输出，`<ABSOLUTE_PATH>` 应替换为 continuum 仓库根目录 [examples/claude-desktop.json:1-2](examples/claude-desktop.json)。这意味着 MCP 服务器是一个独立的 Node 进程，通过 stdin/stdout 与 Claude Desktop 通信；只要 `continuum start` 在后台运行，代理侧即可对本地记忆执行 recall 查询。

### 用法

启用后，用户可在 Claude Desktop 中直接询问 `"what was I working on this morning?"` 等问题 [README.md](README.md)。MCP 是该项目的"主要兑现"路径——把已经捕获并索引好的上下文，反向喂回给代理。

## 可扩展性

### 模块化边界

`package.json` 的 `exports` 字段明确公开了流水线各子模块：`./segmenter`、`./index`、`./distill`、`./retrieval`、`./adapters`、`./config`，以及根入口 `./daemon/pipeline.mjs` [package.json:13-21](package.json)。README 中亦强调"一阶段就是一个小型、可测试的模块"，并指出典型用例约 20 行代码 [README.md](README.md)。

### 适配器注入

`CONTRIBUTING.md` 明确写出"Stages 2–4 接受注入的适配器（embedder / LLM / graph），且必须可离线运行"——核心不能对云服务形成硬依赖 [CONTRIBUTING.md](CONTRIBUTING.md)。这是 LLM 结构化、嵌入、图后端都被列为 Pro/Enterprise 层级而非核心路径的根本原因 [README.md](README.md)。同时，CONTRIBUTING 还规定**不引入新的运行时依赖**，项目刻意保持零依赖 [CONTRIBUTING.md](CONTRIBUTING.md)。

### 测试与冒烟

`npm test` 跑 36 个单元与集成测试且无网络依赖；`node bin/continuum.mjs verify` 提供端到端冒烟 [CONTRIBUTING.md](CONTRIBUTING.md) | [package.json:23-28](package.json)。`stage1` 侧的 Swift 辅助则需用 `swiftc` 单独构建 [daemon/stage1/screen.swift:1-12](daemon/stage1/screen.swift) | [daemon/stage1/capture.swift:1-12](daemon/stage1/capture.swift)。社区讨论（如 #2、#3、#4）所提出的"LLM 结构化提取、聚焦元素输入事件、浏览器工具栏裁剪、自身窗口排除"等改进，正是借助阶段模块的注入点与 `CONTINUUM_EXCLUDE` / `SELF_MARKERS` 等已有钩子逐步落地，从而保证不破坏"纯核心 + 可选增强"的边界。

## See Also

- [README.md](README.md)——项目总览与安装指南
- [docs/architecture/ingestion-pipeline.md](docs/architecture/ingestion-pipeline.md)——四阶段流水线设计
- [CONTRIBUTING.md](CONTRIBUTING.md)——贡献与架构约束
- [backend/graphiti/README.md](backend/graphiti/README.md)——图谱后端运行说明
- `examples/` 目录——MCP 配置与 standup 生成器示例

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：nikhilkagita04/continuum

摘要：发现 13 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/nikhilkagita04/continuum | host_targets=mcp_host, claude, cursor, chatgpt

## 2. 配置坑 · 失败模式：configuration: Capture: LLM structuring pass to attribute episodes (who said what)

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Capture: LLM structuring pass to attribute episodes (who said what)
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Capture: LLM structuring pass to attribute episodes (who said what)
- 证据：failure_mode_cluster:github_issue | https://github.com/nikhilkagita04/continuum/issues/2 | Capture: LLM structuring pass to attribute episodes (who said what)

## 3. 配置坑 · 失败模式：configuration: Capture: emit AX focused-element as clean user-authored text

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Capture: emit AX focused-element as clean user-authored text
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Capture: emit AX focused-element as clean user-authored text
- 证据：failure_mode_cluster:github_issue | https://github.com/nikhilkagita04/continuum/issues/1 | Capture: emit AX focused-element as clean user-authored text

## 4. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/nikhilkagita04/continuum | README/documentation is current enough for a first validation pass.

## 5. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/nikhilkagita04/continuum | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/nikhilkagita04/continuum | no_demo; severity=medium

## 7. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/nikhilkagita04/continuum | no_demo; severity=medium

## 8. 安全/权限坑 · 来源证据：Capture: LLM structuring pass to attribute episodes (who said what)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Capture: LLM structuring pass to attribute episodes (who said what)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/nikhilkagita04/continuum/issues/2 | 来源类型 github_issue 暴露的待验证使用条件。

## 9. 安全/权限坑 · 来源证据：Capture: emit AX focused-element as clean user-authored text

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Capture: emit AX focused-element as clean user-authored text
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/nikhilkagita04/continuum/issues/1 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 10. 能力坑 · 失败模式：conceptual: Capture: exclude Continuum's own windows (dashboard/terminal) from capture

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: Capture: exclude Continuum's own windows (dashboard/terminal) from capture
- 对用户的影响：Developers may hit a documented source-backed failure mode: Capture: exclude Continuum's own windows (dashboard/terminal) from capture
- 证据：failure_mode_cluster:github_issue | https://github.com/nikhilkagita04/continuum/issues/4 | Capture: exclude Continuum's own windows (dashboard/terminal) from capture

## 11. 能力坑 · 失败模式：conceptual: Capture: reduce browser-chrome noise (crop toolbar/tab band before OCR)

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: Capture: reduce browser-chrome noise (crop toolbar/tab band before OCR)
- 对用户的影响：Developers may hit a documented source-backed failure mode: Capture: reduce browser-chrome noise (crop toolbar/tab band before OCR)
- 证据：failure_mode_cluster:github_issue | https://github.com/nikhilkagita04/continuum/issues/3 | Capture: reduce browser-chrome noise (crop toolbar/tab band before OCR)

## 12. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/nikhilkagita04/continuum | issue_or_pr_quality=unknown

## 13. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/nikhilkagita04/continuum | release_recency=unknown

<!-- canonical_name: nikhilkagita04/continuum; human_manual_source: deepwiki_human_wiki -->