Continuum

Passive Cognitive Telemetry & Operational Reasoning Memory

Continuum is a personal cognitive observability platform built for high-context development workflows, specifically optimized for ADHD/AuDHD minds. It eliminates the "executive function tax" of manual note-taking by passively observing your work and automatically reconstructing the state of your thinking.

Origin

Continuum is a fork of Open Brain.

The core reason for the fork: active submission and manual annotation are valuable, but for neurodivergent workflows they can be hard to sustain consistently. If remembering to take notes is itself a burden, critical context gets lost.

Continuum keeps the active submission model from Open Brain and adds a passive capture system on top of it. The goal is to enhance the original model while adding additional functionality and insight through continuous background observation.

🧠 The Philosophy: Passive-First, Governed Truth

Most "Second Brain" systems fail because they assume executive function is intact. Continuum reverses the model:

1. Observation → Passive capture from terminals, files, git, and AI chats.
2. Normalization → Deterministic Source Integration Layer (Dedupe, Redaction, Project Mapping).
3. Inference → Periodic synthesis of raw telemetry into semantic work threads.
4. Governance → A formal State Machine (Active, Dormant, Resolved) and Authority weighting.
5. Reconstruction → On-demand operational state recovery ("Where was I?").

🧱 Core Information Model

Continuum organizes cognitive state using five primary object types:

• Events (Evidence Layer): Immutable records of what actually happened (terminal commands, file edits, git commits, AI prompts/responses, connector messages).
• Threads (Problem Spaces): Clusters of related events representing active work problems, including attempts, blockers, pivots, decisions, and outcomes.
• Authority Objects (Governed Truth): Explicit decisions/constraints (plus validated blockers/dead ends/actions) that shape future reasoning and support supersession/contradiction.
• Artifacts (Derived Interpretations): Replay timelines, loop labels, guardrail triggers, and summaries. Artifacts are derivative and must reference evidence.
• Graph Edges (Relationship Index): Secondary relationship projection for traversal and multi-hop reasoning; never the source of truth.

🏗️ Architecture: Distributed Sensors / Central Brain

Continuum is designed for native Linux environments (no Docker), operating as a network-wide control plane.

Edge Sensors (Laptops/Workstations)      Cloud Connectors (Slack/GitHub)
            ↘                                     ↙
               Source Integration Layer (Ingest)
                          ↓
             Event Substrate (PostgreSQL + pgvector)
                          ↓
                  Thread Formation Layer
                          ↓
               Governance Engine (State Machine)
                          ↓
               Synthesis Workers (Compression)
                          ↓
              Reconstruction Engine (4-Stage RAG)
                          ↓
                    CLI / API / Web

🔄 Information Lifecycle

Every piece of information moves through a governed lifecycle:

captured → normalized → linked → interpreted → governed → reviewed → decayed or reaffirmed

Meaning:

• Captured from passive telemetry or explicit user input.
• Normalized into canonical events.
• Linked to threads/entities/evidence sets.
• Interpreted by synthesis and retrieval processes.
• Governed through state machines and authority/supersession rules.
• Reviewed via trust metrics and operator intervention.
• Decayed or reaffirmed over time to prevent stagnation/drift.

Key Subsystems

• Substrate: A PostgreSQL-backed immutable record of "What Happened."
• Thread Formation: Clusters raw events into semantic work threads using temporal proximity, entity overlap, project identity, and conversational context. Threads represent problem spaces, not conversations.
• Governance Layer: Manages "What it Means Now" via Thread lifecycles and Authority Objects.
• Temporal Layer: Segments thread history into episodes/phases and stores temporal artifacts for change-over-time reasoning.
• Retrieval Pipeline: A governed 4-stage process:
  1. Candidate Generation: hybrid lexical + vector recall.
  2. Reranking: authority weight, thread membership, recency decay, source credibility.
  3. Reconstruction: builds operational state (goals, blockers, decisions, next actions).
  4. Assembly: produces final response with evidence references.
• Edge Agents: Lightweight sensors with local regex redaction to ensure secrets never leave your workstation.

Graph Projection Layer

Continuum maintains a lightweight graph projection derived from governed state. Typical projected edges:

• thread -> contains -> event
• thread -> has_decision -> authority_object
• authority_object -> supersedes -> authority_object
• attempt -> led_to -> outcome
• entity -> participates_in -> thread

The graph is a traversal index for reasoning assistance, not primary truth. Edges are projected from governed state rather than minted from weak embedding similarity.

🔁 State Machines

Continuum operates with three interacting lifecycle machines:

1. Thread lifecycle: active -> dormant -> resolved -> archived
2. Authority lifecycle: active -> superseded -> contradicted -> withdrawn
3. Artifact lifecycle: active -> stale -> superseded -> expired

Governance applies these transitions deterministically so retrieval never treats stale or superseded artifacts as current truth.

🧭 Anti-Corruption Rule

Continuum enforces a strict epistemic boundary:

Derived artifacts may accelerate reasoning, but they may never become primary truth.

All higher-order outputs (summaries, replay timelines, loop detections, guardrails) must reference underlying evidence and may not justify state transitions on their own.

Truth flows upward:

events → threads → authority_objects → derived_artifacts

It must never flow sideways or downward.

📁 Repository Structure

continuum/
├── apps/             # Entrypoints: API (Control Plane), CLI (Operator), Edge (Sensor)
├── services/         # Workers: Ingest (Resolution), Synthesis, Governance, Connectors
├── packages/         # Domain Logic: Substrate (Models/DB), Retrieval, Health, Core
├── db/migrations/    # Ordered Schema: 001_Initial_Schema -> 091_evidence_governance_substrate
├── infra/systemd/    # Native Linux service units
├── scripts/          # Operations: Bootstrap, Deploy, Migrate, Refactor
└── tests/redteam/    # Adversarial validation suite (Drift, Fossilization, Spam)

🚀 Deployment & Operations

Continuum treats your host like a Proper Linux Service Box.

1. Host (The Brain) Setup

./scripts/bootstrap_host.sh  # Initializes /opt/continuum and 'continuum' user
./scripts/db_init.sh         # Creates DB (if needed) + applies ordered SQL migrations
./scripts/deploy.sh          # Sychronizes code and restarts systemd units

Database Helpers

# Load stable local DB env vars (host/port/user/url) for dev shells
source ./scripts/dev-env.sh

# Initialize database and run migrations
./scripts/db_init.sh

# Bootstrap local role/password/db and run migrations
# (useful when you hit password auth failures)
CONTINUUM_DB_USER=continuum CONTINUUM_DB_NAME=continuum ./scripts/db_setup_local.sh

# Reset local/dev DB (destructive)
./scripts/db_reset.sh --yes

Postgres Auth Troubleshooting

If you see errors like:

asyncpg.exceptions.InvalidPasswordError: password authentication failed for user "...",

your role exists but credentials do not match your local Postgres config. Re-bootstrap the app role:

CONTINUUM_DB_USER=continuum \
CONTINUUM_DB_PASSWORD='change-me' \
CONTINUUM_DB_NAME=continuum \
./scripts/db_setup_local.sh

If your local Postgres requires admin password auth, provide:

CONTINUUM_PGADMIN_USER=postgres \
CONTINUUM_PGADMIN_PASSWORD='your-admin-password' \
./scripts/db_setup_local.sh

If you switch terminals often, run this once per shell session first:

source ./scripts/dev-env.sh

2. Edge (The Sensor) Setup

./scripts/bootstrap_edge.sh "$USER"
# Review ~/.config/continuum/edge.toml for machine_id, server_url, and watch_paths
bash ./scripts/install_shell_hooks.sh
sudo systemctl enable --now "continuum-edge@$USER"

Shell hook defaults after install:

• agent wrappers (codex, claude, gemini, kimi) still emit session start/end events
• per-command shell capture is off by default; enable it with export CONTINUUM_CAPTURE_COMMANDS=1
• transcript capture is off by default to reduce launch lag; enable it with export CONTINUUM_CAPTURE_TRANSCRIPTS=1
• reload with source ~/.config/continuum/shell_hook.sh or open a new terminal after reinstalling
• bypass the wrapper for troubleshooting with command gemini / command codex

🧪 Developer Commands

Use one command per task:

source ./scripts/dev-env.sh  # once per shell session
make dev         # start local API/ingest/governance/synthesis workers
make test        # run full test suite
make bench       # run medium benchmark profile with strict thresholds
make bench-large # run large benchmark profile
make logs        # tail local dev logs (or systemd fallback)
continuum status # local runtime status: config, shell hooks, spool, ollama
continuum doctor # diagnose missing shell hooks, clipboard tools, native host setup
make reset-db    # destructive local DB reset + re-init
make deploy      # deployment script

Equivalent script entrypoints are available in scripts/:

• ./scripts/dev.sh
• ./scripts/test.sh
• ./scripts/bench.sh [small|medium|large|all]
• ./scripts/logs.sh
• ./scripts/reset-db.sh
• ./scripts/deploy.sh

Benchmark Drift Gating

Use baseline comparison to catch slow regressions:

continuum benchmark --profile medium \
  --strict-threshold 0.85 \
  --compare-baseline /path/to/previous_benchmark.json \
  --max-score-regression 0.03 \
  --max-metric-regression 0.05

Exit behavior:

• 0: pass
• 1: threshold failure or baseline regression failure
• 2: critical auto-fail condition

🛠️ CLI Reference

Cognitive Context

• continuum where: Reconstructs your current working context across all machines.
• continuum replay: Shows operational replay (goal → attempts → failures/pivots → current state).
• continuum timeline [thread_id] --days N: Shows temporal evolution (episode-like day buckets + turning points).
• continuum thread <id>: Inspects thread state, decisions, blockers, and lineage.
• continuum ask "Question": Queries your history using the 4-stage retrieval pipeline.

Governance & Authority

• continuum decision "Text": Records a high-authority design choice.
• continuum supersede <old_id> "New Text": Updates a decision while preserving lineage.
• continuum resolve <id>: Marks a thread as completed.
• continuum reopen <id>: Reactivates a thread with an explicit audit trail.

Health

• continuum health: Monitors system trust metrics and operational component status.
• continuum import-recallrelay --inbox-dir ~/.recallrelay/exports: One-shot import of RecallRelay JSON exports.

🔌 RecallRelay Integration

Continuum can ingest RecallRelay conversation exports directly.

1. Export Conversations with RecallRelay

From /home/bamn/RecallRelay (or wherever RecallRelay is installed):

mkdir -p ~/.recallrelay/exports
recallrelay extract "https://chatgpt.com/share/..." --format json > ~/.recallrelay/exports/chatgpt_001.json
recallrelay extract "https://claude.ai/share/..." --format json > ~/.recallrelay/exports/claude_001.json

2. Import into Continuum

One-shot:

continuum import-recallrelay --inbox-dir ~/.recallrelay/exports

Continuous connector worker:

python -m services.connectors.recallrelay.worker --inbox-dir ~/.recallrelay/exports

The connector creates a recallrelay project (if missing), maps each conversation to a stable thread, and ingests messages as events (chat_prompt / chat_response) with dedupe keys.

Bootstrap Semantics (Important)

RecallRelay import is treated as a bootstrap bridge, not live passive telemetry.

Imported events are tagged with:

• capture_mode: imported_historical
• truth_profile.requires_corroboration: true
• truth_profile.authority_bias: below_live_telemetry

The connector emits both raw imported messages and structured recovered units:

• historical_conversation_imported
• decision_candidate_recovered
• active_thread_candidate_recovered
• blocker_candidate_recovered
• artifact_reference_recovered
• project_mapping_suspected (notably from GitHub owner/repo identity)

GitHub historical exports are supported as bootstrap input when RecallRelay provides platform: "github" plus either metadata.repo (for example owner/repo) or a GitHub source_url.

3. Optional Systemd Service

Use continuum-connector-recallrelay.service as the deployment unit template.

🛡️ Reliability Invariants (The "Month 6" Guards)

• Substrate Integrity: Summaries assist retrieval but never replace raw evidence.
• Policy Gating: Retrieval is constrained by governed state; superseded objects are filtered before scoring.
• Drift Protection: Tracks the summary_dependency_ratio to ensure the system thinks with evidence, not abstractions.
• Local Redaction: Secrets are filtered at the edge before transmission to the central brain.

📈 Trust Metrics

Continuum continuously measures its own reconstruction reliability.

Key indicators include:

• reconstruction_success_rate
• correction_rate
• stale_resurfacing_rate
• summary_dependency_ratio

If trust metrics degrade, the system should reduce automation and increase transparency. If trust metrics degrade, Continuum automatically:

• reduces inference aggressiveness
• surfaces more raw evidence in responses
• suppresses weak artifacts
• lowers confidence levels

---

Continuum is not a note-taking app. It is an operational memory system that observes your work and reconstructs the state of your thinking.