Skip to main content
Glama
bosprimigenious

continuum

by bosprimigenious
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

CONTINUUM

Your tools change. Your context stays.

A local-first history layer for humans and coding agents.

CI License: MIT Stage: pre-alpha

中文 · Architecture · Contributing · Security

Coding conversations are scattered across tools. Continuum is being built to let you find them in one place, read their original context, and make selected history available to another agent through MCP—without rewriting a vendor's conversation database.

Where the project stands

This is a developer foundation, not a ready-to-use history browser.

Available in this repository

Not implemented yet

Versioned normalized snapshot contract and synthetic example

Claude Code / Codex adapters; Cursor JSONL transcripts

Atomic SQLite imports, literal Unicode search, source references

Automatic discovery and background incremental updates

Version-bound pagination and explicit errors

Desktop installer / Tauri

CLI-backed GUI session and Vite shell (pytest only)

Browser e2e, live GUI host

CLI and four read-only stdio MCP tools sharing one core

Fine-grained client permissions and attachment reading

Cursor IDE state.vscdb read-only import through CLI/stdio/wheel (synthetic fixtures)

Live Cursor host verification

Unit, rollback, CLI and real stdio protocol tests; CI

Cross-agent execution, cloud sync, semantic search

No private conversations are included. The example is hand-written synthetic data. The earlier single-user Cursor prototype is not bundled or claimed as native support.

Related MCP server: chist

Try the foundation

Requires uv and Python 3.12+. Run from a checkout; no package has been published to PyPI and no desktop release exists.

git clone https://github.com/bosprimigenious/continuum.git
cd continuum
uv sync --locked

uv run continuum --db .continuum/demo.sqlite3 import examples/synthetic.snapshot.json
uv run continuum --db .continuum/demo.sqlite3 sources
uv run continuum --db .continuum/demo.sqlite3 search "数据库锁"
uv run continuum --db .continuum/demo.sqlite3 list

Copy a returned session_id from search (or id from list):

uv run continuum --db .continuum/demo.sqlite3 read SESSION_ID --limit 2

Pass the returned next_cursor with --cursor to continue. null means the end. Rerun the import: it reports "changed": false. The input file is never modified.

import accepts Continuum's normalized snapshot v1 by default. To import one explicitly selected Cursor IDE state.vscdb (not auto-discovered, not a live-host verification):

uv run continuum --db .continuum/demo.sqlite3 import \
  --adapter cursor-state-vscdb --source-id cursor-demo PATH/TO/state.vscdb

Do not commit real Cursor databases. The reader copies the selected file plus WAL/SHM sidecars and opens the copy with SQLite mode=ro; it does not write the source. A damaged capture (incomplete_source) leaves any existing index unchanged and does not create a new empty --db. Other Cursor stores (agent-transcripts JSONL, workspace DBs) are not this adapter.

Reusing a source_id replaces that source's entire derived snapshot atomically, including removing previously indexed events absent from the new snapshot. It is not an archive merge. Keep your source files; indexes are disposable derived data.

Connect an MCP client

Start the stdio server using the same index:

uv run continuum --db .continuum/demo.sqlite3 serve

For a host supporting the usual mcpServers JSON configuration, adapt this example. Replace both paths with absolute paths on your machine; configuration location varies by host.

{
  "mcpServers": {
    "continuum": {
      "command": "uv",
      "args": [
        "run", "--locked", "--directory", "/absolute/path/to/continuum",
        "continuum", "--db", "/absolute/path/to/continuum/.continuum/demo.sqlite3", "serve"
      ]
    }
  }
}

Tool

Purpose

history_sources

Inspect imported sources, counts, snapshot digests and index timestamps

history_list

List sessions with exact source/project filters

history_search

Search literal text, including short Chinese queries

history_read

Read complete events in order, with pagination and references

All four tools query the same local core. They cannot import files, delete source records, read arbitrary filesystem paths or launch another agent. SDK stdio interoperability is tested; real Codex / Claude Code / Cursor host integration is not yet verified.

Connecting a client gives it read access to this entire index. Project filters are not access controls. Use separate indexes for different trust boundaries. Text retrieved by an agent may be sent to that agent's model provider, even though Continuum has no upload service.

Architecture and stack

Source adapters → normalized snapshots → local history core → CLI
                                             │             → MCP (stdio)
                                         SQLite / FTS5     → GUI (CLI JSON; Vite shell)

  • Core: Python 3.12+, Pydantic v2 contracts, SQLite + FTS5, official MCP Python SDK v2.

  • Tooling: uv and a committed lockfile; pytest, Ruff, mypy; GitHub Actions.

  • GUI: React + TypeScript + Vite talks to the index through the continuum CLI JSON interface (continuum_history.gui). Run npm install && npm run dev in gui/ from a checkout. Browser end-to-end tests and Tauri are not implemented.

  • Deployment: one local modular application. No account, cloud database, vector service, model download or LLM API is needed for the current demo.

The core must remain independent of MCP, the GUI and vendor formats. Packaging the Python core with a desktop shell requires a platform-specific spike before committing to a release. See architecture, trade-offs and migration boundaries.

Development

uv sync --locked
uv run python scripts/check.py

The aggregate gate checks formatting, lint, strict source typing, tests with a coverage floor, basic publication hygiene, wheel/sdist builds, and a wheel installed in an isolated environment. It may download build/runtime dependencies. It does not read your native agent history.

CI runs the same gate on Linux, macOS and Windows. A green run validates the foundation, not native source coverage or real-host compatibility. Read the next bounded milestone before adding features. Adapter work starts with synthetic fixtures and failing behavior tests.

Scope

The first product milestone is reliable read-only history: discover supported local records, show coverage and errors, search and read through a GUI or MCP. Start with one Cursor path, prove it, then extend to Claude Code and Codex.

Execution orchestration, automatic migration/cleanup, shared cloud memory and model routing are out of scope for this milestone. Existing projects are welcome references; novelty is not the acceptance criterion. Correctness, understandable boundaries and a complete user path are.

Privacy and license

Local indexes contain plaintext. There is no automatic secret redaction or secure-erasure guarantee. Only import material you intend to expose to the connected client. See SECURITY.md.

MIT. Continuum is an independent project, not affiliated with any agent vendor. The working name does not imply exclusive naming or trademark rights.

Available Tools

4 tools
history_listA
Read-onlyIdempotent

List sessions; filters are exact matches, not authorization boundaries.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
cursorNo
projectNo
source_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds a non-obvious behavioral nuance: filters are exact matches, not authorization boundaries, which clarifies that results are not permission-scoped. This goes beyond the annotation hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with two clauses, front-loading the action and adding a critical caveat. It contains no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema, so return format is covered elsewhere. It has four optional parameters, and the description provides a key nuance about filters but does not explain limit/cursor pagination or the meaning of project/source_id beyond their names. Given the low complexity and the presence of an output schema, the description is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries full responsibility for explaining parameters. It only states that filters are exact matches, which applies to project and source_id but not to limit and cursor. The parameter names are somewhat self-explanatory, but pagination semantics and data types are not clarified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'List sessions', a clear verb and resource, and adds a clarifying note about filter semantics. It doesn't explicitly differentiate from sibling tools like history_search or history_read, but the core purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: use this to list sessions with exact-match filters. The warning that filters are not authorization boundaries hints at when not to rely on it for security scoping, but no alternatives are named and no explicit when-to-use/when-not-to-use guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

history_readA
Read-onlyIdempotent

Read complete events by opaque session ID, in snapshot order, with pagination.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
cursorNo
session_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavior beyond annotations: events are returned complete, in snapshot order, and with pagination. It does not discuss errors or rate limits, but the added context is sufficient for this simple read operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One compact sentence with no filler. It front-loads the verb and resource, then efficiently packs completeness, ordering, and pagination. Every phrase earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only paginated fetch with an output schema and comprehensive annotations, nothing critical is missing: session ID, record completeness, ordering, and pagination are all explicitly present. The tool's complexity is low, and the definition covers the full call contract.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It covers session_id ('opaque session ID') and pagination (limit/cursor), giving high-level semantics for the parameters. However, it leaves details unstated, such as whether the cursor itself is opaque or how limit interacts with pagination. The schema's defaults and titles fill in some meaning, so the description is adequate but not exhaustive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Read'), a clear resource ('complete events'), and the key differentiator ('by opaque session ID'), plus ordering and pagination. This distinguishes it from siblings like history_list and history_search, which imply broader listing or searching rather than a direct session-based read.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use the tool: when you have a session ID and need the full event sequence in snapshot order. It does not explicitly name alternatives or exclusions, but the intended use case is evident from the wording and sibling names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

history_sourcesA
Read-onlyIdempotent

List imported source coverage, revision and timestamps; not live discovery.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds that it lists coverage, revision, and timestamps, and clarifies it is not live discovery, which provides additional behavioral context beyond the annotations. This is useful and consistent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, compact sentence that front-loads the core action and resource. Every word earns its place, and the clarifying 'not live discovery' adds meaningful distinction without waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with a clear output schema (not shown but noted), the description is complete. It states what the tool does, what it covers, and explicitly rules out live discovery. The distinction from siblings is clear, and an agent can correctly invoke it without additional information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so schema description coverage is trivially 100%. With no parameters, the description carries no burden to explain them, and the baseline of 4 applies. No additional param info is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List') and resource ('imported source coverage, revision and timestamps'), and explicitly adds 'not live discovery' to distinguish it from live discovery tools. This differentiates it from siblings like history_list, history_search, and history_read, which are about different operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'not live discovery' clarifies that this tool is for imported/historical data, not real-time discovery. While it doesn't explicitly name alternatives, the context of the siblings (list, search, read) implies when this tool is appropriate. It gives clear context but no explicit exclusions beyond the live discovery caveat.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedhistory_list
    • First observedhistory_read
    • First observedhistory_search
    • First observedhistory_sources
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: listing sources, listing sessions, searching text, and reading full events. The overlap between search and read is well-defined, with search for discovery and read for retrieval.

Naming Consistency5/5

All tools follow a consistent history_ verb_noun pattern (sources, list, search, read). The naming is predictable and immediately conveys the action and resource.

Tool Count5/5

With only 4 tools, the server is well-scoped for a read-only history/event domain. Each tool earns its place, covering the essential operations without unnecessary bloat.

Completeness4/5

The surface covers listing, searching, and reading, which are the core operations for a history server. Minor gaps exist, such as no rich filtering for sessions, but agents can work around these limitations.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • chist

    hiropon164
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server for unified full-text search across chat histories from Claude Code, Codex, Cursor CLI, and Antigravity CLI, using SQLite FTS5. Provides read-only tools to search sessions, list conversations, and retrieve session details.
    MIT

  • retrace-mcp

    calvingunther66
    A
    license
    A
    quality
    C
    maintenance
    Read-only MCP server for searching your local Retrace screen-history database, with tools for full-text search, segment listing, frame details, app usage, and tags.
    6
    MIT