Related Pages

Related topics: The Four-Stage Pipeline, MCP Server, Graph Sidecar, and Custom Tools

Introduction and Quickstart

What Continuum Is and Why It Exists

Continuum is an open, local-first capture and memory layer for your computer. It addresses a specific failure mode: when you switch between apps (Claude, Slack, X, a design tool, your email), each one starts blank, and *you* become the courier re-pasting context between them. Continuum quietly remembers what you do on-device and exposes that memory to the next tool, so an agent can answer "what was I just doing in X?" without any re-explanation. Source: README.md.

The project is positioned explicitly as a primitive, not an app — a shovel others build use cases on, not a closed "brain" you hand everything to. Source: README.md. Concretely, it is:

• Event-driven, not continuous — it captures only when the screen or focused window meaningfully changes, so it is faithful without being a firehose. Source: daemon/stage1/screen.swift (perceptual-hash gating before OCR).
• Local-first — all data lives under ~/.continuum; credential managers are excluded by default and PII is redacted. Source: daemon/stage1/screen.swift (EXCLUDED set + CONTINUUM_EXCLUDE env var).
• Composable — queryable from the CLI, an importable Node SDK, or via MCP, so any agent can use the memory. Source: README.md.

The package itself is named continuum-core at version 0.1.5, ships as an ESM module with Node 18+ as the minimum engine, and has zero runtime dependencies by design. Source: package.json.

Installation

The README's install path takes roughly 30 seconds and requires only Node 18+. Source: README.md.

npm install -g continuum-core
continuum verify          # proves the whole loop works — no keys, no permissions

continuum is wired in as the bin entry continuum-core exposes; the CLI is implemented at bin/continuum.mjs. Source: package.json. The verify subcommand is also registered as a npm run verify script for local development. Source: package.json.

For contributors and source-build users, the repo provides equivalent npm scripts for every stage of the toolchain (build:capture, build:app, start, test). Source: package.json.

Running Continuum Day-to-Day

Three commands cover almost all everyday use:

continuum start          # begin on-device capture (macOS prompts for Screen Recording)
continuum dashboard      # open the searchable timeline at http://localhost:3939
continuum mcp-install    # register Continuum with Claude Desktop (preserves existing config)

Source: README.md. After mcp-install, the user must fully quit and reopen Claude Desktop (Cmd+Q) for the new MCP server to load. Source: README.md.

For non-Claude MCP clients (Cursor, custom agents), continuum mcp-config prints a JSON snippet the user merges manually. The shipped example for Claude Desktop wraps the Node server in an mcpServers block under the key continuum. Source: examples/claude-desktop.json.

A lightweight macOS menu-bar app (◌ icon) is also provided for users who prefer a GUI over the CLI: it exposes Start/Stop, an "Open data folder" action, and a Quit item, and runs as an LSUIElement (no Dock icon). Source: packaging/menubar.swift.

How It Works — The Four-Stage Pipeline

Continuum turns a torrent of raw screen events into a small set of high-signal episodes, with the LLM kept off the hot path. Source: README.md. The pipeline has four named stages, all importable as separate modules:

flowchart LR
    A[Stage 1: Capture<br/>screen.swift / capture.swift<br/>NDJSON CaptureEvents] --> B[Stage 2: Segment<br/>daemon/stage2/segmenter.mjs]
    B --> C[Stage 3: Index<br/>daemon/stage3/index.mjs<br/>local hybrid index]
    C --> D[Stage 4: Distill<br/>daemon/stage4/distill.mjs<br/>~30 LLM calls/day]
    D --> E[Retrieval<br/>daemon/retrieval.mjs]
    E --> F[MCP Server<br/>daemon/mcp-server.mjs]

• Stage 1 — Capture. Two Swift helpers share one contract: screen.swift uses ScreenCaptureKit + Apple Vision OCR, gated by a perceptual hash so a static window costs almost nothing. Source: daemon/stage1/screen.swift. capture.swift is the accessibility-based alternative that watches the focused element on a 1-second pasteboard poll plus per-pid AXObserver, emitting clean AXFocusedUIElement text keyed by focus+role. Source: daemon/stage1/capture.swift.
• Stages 2–4 (segment, index, distill) are pure Node modules that take *injected* adapters (embedder, LLM, graph store) and must run offline — this is a hard project rule, not a suggestion. Source: CONTRIBUTING.md.
• Capture-quality guardrails. The screen helper already excludes credential managers, the Continuum dashboard, and the terminal running the daemon, and it crops the top band of browser windows before OCR so episodes start with page content rather than the tab strip. Source: daemon/stage1/screen.swift. These correspond directly to the open community issues #3 and #4 tracked for the project, which explicitly link the design back to docs/architecture/capture-quality.md.

The headline performance figure: ~29k raw daily events are funneled into roughly 30 LLM calls per day, which is what makes the system tractable. Source: README.md.

Tiers and What's Free

Continuum ships in three tiers today; only the first is fully open and free. Source: README.md.

The graph tier is intentionally the paid line because reliable entity/relation extraction needs a frontier model (Claude/GPT-class) — open models cannot satisfy the strict EdgeDuplicate / NodeResolutions schemas in graphiti-core and raise pydantic ValidationError. Source: backend/graphiti/sidecar.py. The optional sidecar runs as a FastAPI service on Neo4j, with Anthropic as the default extraction LLM and gpt-4o-mini selectable as a roughly 15–20× cheaper alternative. Source: backend/graphiti/README.md.

Development Quickstart

To hack on Continuum itself, clone the repo, run the offline test suite, and (on macOS) build the Swift helpers. Source: CONTRIBUTING.md.

git clone https://github.com/nikhilkagita04/continuum && cd continuum
npm test                                                 # 36 unit + integration tests, no network
node bin/continuum.mjs verify                            # end-to-end smoke
swiftc daemon/stage1/screen.swift -o daemon/stage1/screen

Source: CONTRIBUTING.md. All contributions must be signed off with git commit -s (DCO) and the project is licensed under Apache-2.0. Source: CONTRIBUTING.md.

See Also

• Ingestion pipeline deep dive: docs/architecture/ingestion-pipeline.md — referenced from README.md.
• Capture-quality design notes: docs/architecture/capture-quality.md — referenced from the open issues #1–#4 for AX-focused input, LLM structuring, browser-chrome cropping, and self-exclusion.

Related Pages

Related topics: Capture Quality, Noise Filtering, and Self-Exclusion, MCP Server, Graph Sidecar, and Custom Tools, Introduction and Quickstart

The Four-Stage Pipeline

Overview

Continuum is described as an *open capture + memory layer*: a small, dependency-free primitive that turns on-device activity into a queryable timeline. The entire design is organized as a four-stage pipeline — capture → segment → index → distill — where each stage is a small, tested module under daemon/, and the LLM is kept entirely off the hot capture path. The README states the goal quantitatively: *"Four stages turn ~29k raw daily events into ~30 LLM calls — and the LLM never touches the capture path"* README.md.

Stages 2–4 are designed as pure modules that take injected adapters (embedder, LLM, graph) and *"must run offline"* — there is no hard-coded cloud dependency in the core CONTRIBUTING.md. This separation is what keeps the capture path light and the overall system local-first.

flowchart LR
    A[Stage 1<br/>Capture] -->|CaptureEvent NDJSON| B[Stage 2<br/>Segment]
    B -->|Episodes| C[Stage 3<br/>Index]
    C -->|Hybrid index| D[Stage 4<br/>Distill]
    D -->|Entities / facts| E[(~/.continuum store)]
    E -->|query| R[Retrieval / MCP]

The pipeline is the package's main export: "." resolves to daemon/pipeline.mjs, and each stage is independently importable via subpath exports such as continuum-core/segmenter, continuum-core/index, and continuum-core/distill package.json.

Stage 1 — Capture (event-driven, on-device)

Stage 1 emits a normalized NDJSON stream of CaptureEvents on stdout: {t, source, app, window_id, url_host?, title?, text, secure?} daemon/stage1/capture.swift:7-9. There are two interchangeable helpers:

The AX helper *retargets* on NSWorkspace.didActivateApplicationNotification, tears down and rebuilds per-pid observers, and coalesces emits at ≤1 per 400ms per window to avoid floods daemon/stage1/capture.swift. It also descends the focused subtree, skipping chrome roles (buttons, menus, toolbars, tabs) and only collecting prose ≥3 words / ≥24 chars — explicitly separating *signal from window furniture* daemon/stage1/capture.swift.

The screen helper uses ScreenCaptureKit with a perceptual-hash dedup, so a static window costs ~nothing; when a change is detected, Apple Vision runs OCR in reading order and emits a source: "ocr" event with the same contract as the AX path daemon/stage1/screen.swift. Both helpers pipe into node daemon/pipeline.mjs — the downstream stages don't care which one produced the stream.

Stage 2 — Segment

Stage 2 turns the raw event stream into discrete, meaningful *episodes*. It is exported as continuum-core/segmenter and is exercised by the test suite (npm test runs daemon/stage2/segmenter.test.mjs first) package.json. The segmenter's contract is to coalesce noisy per-window events into coherent activities (e.g., "writing an email in Mail.app"), bounded by app switches, idle gaps, or text deltas. As an injected module, it depends only on the configured embedder adapter and writes structured segments to the local store.

Stage 3 — Index

Stage 3 builds the hybrid index — typically a combination of lexical (BM25/FTS) and vector recall over episodes. It is exported as continuum-core/index package.json. The README describes this as the substrate of the free tier: *"The free tier runs entirely on the local hybrid index (capture → segment → vector recall)"* backend/graphiti/README.md. Because this stage takes an injected embedder, the core can run with local embeddings ($0) or a hosted provider README.md.

Stage 4 — Distill

Stage 4 is the only stage that talks to the LLM. It is exported as continuum-core/distill and runs on the already-segmented, already-indexed data — selectively, not per-event — which is why the headline number is "~30 LLM calls / day" for ~29k raw events README.md. Distillation is also the natural place for higher-level structuring, and the community has identified it as the right insertion point for an LLM-based attribution pass that turns raw OCR text into structured fields (author, content, app) and drops chrome/noise — see issue #2.

Adapters, Config, and Retrieval

Stages 2–4 are decoupled from concrete implementations via two modules:

• daemon/adapters.mjs — the injection points (embedder, llm, graph) so the core remains cloud-free by default CONTRIBUTING.md.
• daemon/config.mjs — runtime configuration loaded by the pipeline.

Retrieval (daemon/retrieval.mjs, exported as continuum-core/retrieval) is what the MCP server and dashboard call. It reads from the on-disk store at ~/.continuum and answers natural-language queries, optionally calling out to a graph sidecar (backend/graphiti/sidecar.py) when the temporal knowledge graph tier is enabled package.json, backend/graphiti/sidecar.py.

Known Capture-Quality Failure Modes

The community has surfaced four capture-quality concerns, all of which feed *into* Stage 1 and propagate through the rest of the pipeline. The design notes for resolving them live in docs/architecture/capture-quality.md:

• Self-capture loop (issue #4) — the dashboard (localhost:3939) and the running terminal are currently captured. The intended fix is a title/window exclusion (already partially in place for screen.swift via SELF_MARKERS heuristic strings daemon/stage1/screen.swift).
• Browser chrome noise (issue #3) — every browser episode is prefixed by the tab/bookmarks bar. A conservative top-band crop is the proposed mitigation; the screen helper already recognizes a BROWSERS set, though the crop itself is the open work daemon/stage1/screen.swift.
• OCR vs. authored input (issue #1) — OCR fuses the user's typed text with the surrounding page; AXFocusedUIElement reliably yields *just the user's text* and should be emitted as a distinct source: "input" event alongside the OCR stream.
• Episode attribution (issue #2) — a Stage-4 structuring pass would convert raw OCR text into structured fields, avoiding brittle per-site parsers.

See Also

• README.md — project introduction and tier table
• CONTRIBUTING.md — ground rules and test invocation
• package.json — package exports and npm scripts
• docs/architecture/ingestion-pipeline.md — referenced deep dive on the four-stage design
• docs/architecture/capture-quality.md — design notes referenced by issues #1–#4
• backend/graphiti/README.md — optional temporal knowledge graph tier (Pro)

Related Pages

Related topics: The Four-Stage Pipeline, MCP Server, Graph Sidecar, and Custom Tools

Capture Quality, Noise Filtering, and Self-Exclusion

Purpose and Scope

Continuum is an open, local-first capture + memory layer that records what the user sees on screen and turns it into a searchable timeline. Because every app the user interacts with is a potential capture source, capture quality is the primary lever that determines whether the downstream segmenter, indexer, and distiller produce useful episodes or noisy ones. The project addresses quality at three layers:

1. Stage 1 (capture) — pre-OCR noise removal: skip UI chrome, crop browser toolbars, suppress self-capture and credential apps.
2. Stage 1 (AX helper) — accessibility-tree filtering: ignore button/menu/toolbar roles, deduplicate repeats, enforce text budgets.
3. Stage 4 (distill) — semantic structuring: an injected LLM pass that attributes who-said-what and drops residual noise (designed, in flight).

This page documents the first two layers, which are fully implemented in the current source tree, and summarizes the Stage-4 design referenced in issue #2 and docs/architecture/capture-quality.md.

Related Pages

Related topics: The Four-Stage Pipeline, Capture Quality, Noise Filtering, and Self-Exclusion, Introduction and Quickstart

MCP Server, Graph Sidecar, and Custom Tools

Overview — the extensibility layer

Continuum positions itself as a primitive, not an app. The capture/segment/index/distall stages are importable Node modules, and three explicit extension points turn that core into agent-ready infrastructure: the MCP server (daemon/mcp-server.mjs) for tool-calling agents, the graph sidecar (backend/graphiti/sidecar.py) for the optional temporal knowledge graph tier, and the public exports declared in package.json for users building custom tools against the SDK. Together they make Continuum "a shovel: build your own use cases on top." Source: README.md.

The packaging contract is small and intentional: every Stage 2–4 module takes injected adapters (embedder / LLM / graph) and must run offline, so no cloud provider becomes a hard dependency in core. Source: CONTRIBUTING.md. That contract is what makes the sidecar and the custom-tool SDK possible without forking the daemon.

flowchart LR
  A[Stage 1 capture<br/>Swift NDJSON] --> B[Stage 2 segment]
  B --> C[Stage 3 index<br/>embedder adapter]
  C --> D[Stage 4 distill<br/>LLM adapter]
  D --> E[Local hybrid index<br/>~/.continuum]
  D -. optional .-> F[Graph sidecar<br/>sidecar.py /add /search]
  E --> G[MCP server<br/>mcp-server.mjs]
  F --> G
  E --> H[Custom tools<br/>examples/standup.mjs]
  G --> I[Claude Desktop / Cursor / agent]

MCP Server — exposing memory to agents

The Model Context Protocol server is the payoff surface: agents (Claude Desktop, Cursor, custom clients) call it to recall what the user did. The CLI ships two helper commands: continuum mcp-install patches Claude Desktop's config non-destructively (existing config preserved and backed up), while continuum mcp-config prints the config so users on other clients can wire it up by hand. Source: README.md. The MCP entry point is daemon/mcp-server.mjs, referenced by the published package example.

The published example shows the exact shape of a working registration:

{
  "mcpServers": {
    "continuum": {
      "command": "<NODE>",
      "args": ["<ABSOLUTE_PATH>/daemon/mcp-server.mjs"]
    }
  }
}

Source: examples/claude-desktop.json. The README recommends fully quitting and reopening Claude Desktop (Cmd+Q) so the new server is loaded before the first query. Source: README.md.

Operationally, the MCP server depends on continuum start being kept running — there must be a daemon process for it to recall from. Source: README.md. Because the core pipeline modules are exported as ESM subpaths (see exports in package.json), MCP tool implementations can import { ... } from "continuum-core/retrieval" rather than shelling out, which keeps tool responses low-latency.

Graph Sidecar — the optional Pro tier

The graph tier is "optional and advanced": it layers entity/relation extraction with bi-temporal edges on top of Graphiti, backed by Neo4j. Source: backend/graphiti/README.md. The sidecar.py service is a FastAPI app exposing three endpoints that the Continuum pipeline calls from its distill stage.

The sidecar is intentionally separated from the daemon. When enabled in ~/.continuum/config.json ("graph": { "enabled": true, "url": "http://localhost:8000" }), the distill step writes daily rollups into the graph and retrieval fuses graph facts with vector recall. Source: backend/graphiti/README.md.

LLM selection is runtime-configurable via GRAPHITI_LLM_PROVIDER. The default openai path uses gpt-4o-mini; anthropic swaps in Claude Sonnet for extraction with Haiku as the small model. Embeddings and the cross-encoder reranker are pinned to OpenAI (text-embedding-3-small at 1536 dims, gpt-4o-mini reranker) because Anthropic has no native embeddings API. Source: backend/graphiti/sidecar.py. This is also why the README notes that graph extraction is "the natural paid line" — open/local models can't satisfy Graphiti's strict extraction schemas. Source: README.md.

Privacy isolation is preserved end-to-end: each user/workspace bucket maps to a Graphiti group_id, so memories stay separated even when self-hosted. Source: backend/graphiti/README.md.

Custom Tools — the SDK and examples

The package's exports field is the SDK surface. Each pipeline stage is importable as a subpath, so a custom tool is roughly twenty lines instead of a fork:

Source: package.json.

Two reference examples ship in examples/: a standup generator (examples/standup.mjs) that calls the retrieval module, and the Claude Desktop config (examples/claude-desktop.json) that wires the MCP server into the agent. The README frames these as templates: "the stages are importable modules — a useful tool is ~20 lines." Source: README.md.

The community roadmap reinforces where this surface is heading. Issue #2 proposes adding a Stage-4 LLM structuring pass that turns a raw OCR episode into structured fields (author, content, app) — a custom tool that drops chrome/noise at distill time rather than via per-site parsers. Source: issue #2. The macOS Stage-1 capture helpers (daemon/stage1/capture.swift, daemon/stage1/screen.swift) emit normalized CaptureEvent NDJSON with a source field (e.g. "input" for AX-focused-element text vs. "ocr" for Vision OCR), which gives the structuring pass a clean signal to attribute authorship. Sources: daemon/stage1/capture.swift and daemon/stage1/screen.swift.

Failure modes and guardrails

• Self-capture. Issue #4 reports that Continuum currently captures its own dashboard (localhost:3939) and the running terminal; the fix is a title/window exclusion in Stage 1 rather than scraping site DOMs. Source: issue #4.
• Browser chrome noise. Issue #3 notes that browser windows prefix every page with the tab/bookmarks bar; the in-progress fix crops the top band before OCR. Source: issue #3.
• Local-LLM extraction is not viable. The sidecar relies on Graphiti's strict structured outputs; open-weight models fail validation, which is why the graph tier is paid-only. Source: backend/graphiti/sidecar.py.
• MCP server requires the daemon. continuum start must be running for the MCP server to recall anything. Source: README.md.

See Also

• Ingestion Pipeline Architecture — the four-stage design (capture → segment → index → distill).
• Graph Tier README — running the sidecar with Neo4j + Graphiti.
• Claude Desktop MCP Config Example — the registration template referenced above.

Doramagic Pitfall Log

Found 13 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/nikhilkagita04/continuum

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: Capture: LLM structuring pass to attribute episodes (who said what)
• User impact: Developers may misconfigure credentials, environment, or host setup: Capture: LLM structuring pass to attribute episodes (who said what)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Capture: LLM structuring pass to attribute episodes (who said what). Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | https://github.com/nikhilkagita04/continuum/issues/2

3. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: Capture: emit AX focused-element as clean user-authored text
• User impact: Developers may misconfigure credentials, environment, or host setup: Capture: emit AX focused-element as clean user-authored text
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Capture: emit AX focused-element as clean user-authored text. Context: Observed when using macos
• Evidence: failure_mode_cluster:github_issue | https://github.com/nikhilkagita04/continuum/issues/1

4. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/nikhilkagita04/continuum

5. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/nikhilkagita04/continuum

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/nikhilkagita04/continuum

7. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/nikhilkagita04/continuum

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/nikhilkagita04/continuum/issues/2

9. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/nikhilkagita04/continuum/issues/1

10. Capability evidence risk: Capability evidence risk requires verification

• Severity: low
• Finding: Developers should check this conceptual risk before relying on the project: Capture: exclude Continuum's own windows (dashboard/terminal) from capture
• User impact: Developers may hit a documented source-backed failure mode: Capture: exclude Continuum's own windows (dashboard/terminal) from capture
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: failure_mode_cluster:github_issue | https://github.com/nikhilkagita04/continuum/issues/4

11. Capability evidence risk: Capability evidence risk requires verification

• Severity: low
• Finding: Developers should check this conceptual risk before relying on the project: Capture: reduce browser-chrome noise (crop toolbar/tab band before OCR)
• User impact: Developers may hit a documented source-backed failure mode: Capture: reduce browser-chrome noise (crop toolbar/tab band before OCR)
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: failure_mode_cluster:github_issue | https://github.com/nikhilkagita04/continuum/issues/3

12. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/nikhilkagita04/continuum

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using continuum with real data or production workflows.

• Capture: LLM structuring pass to attribute episodes (who said what) - github / github_issue
• Capture: emit AX focused-element as clean user-authored text - github / github_issue
• Capture: exclude Continuum's own windows (dashboard/terminal) from captu - github / github_issue
• Capture: reduce browser-chrome noise (crop toolbar/tab band before OCR) - github / github_issue
• Configuration risk requires verification - GitHub / issue