ContinuityOS

ContinuityOS — continuity engine + controlled governance runner

Calls explicitly routed through continuity run or a correctly installed host hook receive a decision — ALLOW · WARN · HOLD · DENY · REQUIRE_CONFIRMATION · DRY_RUN_ONLY — with reasons, a tamper-evident local ledger, and a local rollback plan where the controlled runner can materialize one. ContinuityOS does not intercept raw shell/MCP/tool calls by merely being installed; mandatory broker enforcement remains future work. Apache-2.0.

continuity run shell -- rm -rf /     # ⛔ BLOCKED — command was NOT executed
continuity run shell -- npm test     # ✓ ALLOW — runs

ContinuityBench v0 is a 30-case, hand-labeled regression corpus, not a security-boundary certification. The current verified run is summarized in BUILD_GATE_STATUS.md, and CI fails if the corpus regresses. The bundled MCP adapter supplies its local continuity context; third-party adapters must explicitly provide and validate their own context.

The memory + continuity layers below are the context engine that powers those decisions.

Durable memory + continuity layer for AI agents and humans. Local-first, with no required external service for the core memory path. Apache-2.0.

The tested core combines memory (hybrid recall) with continuity (canon, frontiers, loops, checkpoints, doctor, handoff). The repository also contains experimental primitives: an authority-tagged multi-agent wrapper, a retrieval/keyword-based Twin, simulation helpers, and an operator control plane. These experiments are not evidence of a validated behavioral twin, co-evolution outcome, or production multi-agent product.

Your Claude / ChatGPT / agent forgets everything between sessions. ContinuityOS is a small local memory layer that stores what matters — who you are, your projects, your rules, decisions you've made — and gives it back when it's relevant. It recalls both structurally (folder-like namespaces + keyword search) and semantically (vector similarity), so the right memory surfaces whether you match the words or just the meaning.

The core does not upload user memory content: the memory store is one local SQLite file, while governance and metering can create additional local databases. Update checks and optional model downloads can make outbound requests; there is no account requirement or product telemetry.

Why

• Agents forget. Every new session starts cold. ContinuityOS persists context across sessions and tools.
• Hybrid recall. Keyword-only memory misses paraphrases; pure-vector memory misses exact facts and structure. ContinuityOS blends both.
• Structure like folders. Memories live in namespaces — identity, projects, rules, facts, events, notes (or your own) — so recall can be scoped and a human can browse it.
• For agents and humans. Use it from your code, from the CLI, from an MCP-capable client (Claude Desktop / Claude Code), or over a tiny HTTP API.
• Local-first & private. Core is stdlib-only — no required dependencies, no services. Drop-in to anything.

Install

pip install continuityos          # core (stdlib-only)
# optional, for production-grade embeddings:
pip install "continuityos[fast]"        # recommended: FastEmbed / ONNX
pip install "continuityos[st]"          # sentence-transformers
pip install "continuityos[m2v]"         # light static model2vec
pip install "continuityos[embeddings]"  # all optional embedders

Requires Python 3.10+.

Quick start

From the CLI

cos remember "Robert prefers Apache-2.0 licenses" -n rules -t license
cos remember "ContinuityOS = hybrid memory: FTS + vectors" -n projects
cos recall  "which license should I pick?"
# 0.54 [rules] Robert prefers Apache-2.0 licenses  (semantic 0.22 + keyword)
cos namespaces

Common Operational Memory v1 (shadow-only)

ContinuityOS now includes a separate evidence-bound operational ledger. It does not replace Control Center current truth and cannot apply state changes:

continuity-memory init
continuity-memory import-broker MASTER_RETURN_REGISTRY_R64.jsonl
continuity-memory snapshot --out operational_snapshot.json
continuity-memory checkpoint --label after-import
continuity-memory verify

It stores schema-enforced append-only events, bi-temporal claims, authority-bound decisions, physical broker custody and replay checkpoints in a local SQLite WAL database outside DriveFS. Imported returns are forced to content_status=UNREVIEWED and apply_status=NOT_APPLIED. See docs/COMMON_OPERATIONAL_MEMORY_V1.md.

For evidence-bound project memory, the operator workflow is split deliberately between verified current-session READ_ONLY surfaces and separate effectful gates:

Existing project DB:
  continuity-work
    -> continuity-memory-delta             # NOT_APPLIED proposal
    -> continuity-memory-apply             # separate exact authorization; current session unbound

Fresh project DB:
  continuity-memory-bootstrap-plan         # NOT_APPLIED manifest proposal
    -> continuity-memory-bootstrap-check   # point-in-time READ_ONLY validation
    -> continuity-memory-bootstrap         # separate exact authorization; current session unbound

continuity-work, continuity-memory-delta, continuity-memory-bootstrap-plan, and continuity-memory-bootstrap-check require a verified current session and never grant execution. READY and proposal terminals are not write permission. continuity-memory-apply and continuity-memory-bootstrap are separate effectful gates; they revalidate their exact inputs and remain shadow-only. None of these commands applies accepted Control Center truth, mutates canonical state, deploys, dispatches an agent, trades, accesses a wallet, or grants capital permission.

Import your AI history (6 vendors)

Bring your existing history into ContinuityOS from ChatGPT, Claude, Gemini, Grok, Mistral, and Perplexity — bi-temporally, so cos recall --as-of <date> reconstructs what you knew then instead of a flat dump:

cos import ~/Downloads/chatgpt-export/conversations.json   # ChatGPT (DAG backward-traversal)
cos import ~/Downloads/claude-export/                      # Claude (+ memories.json / projects.json)
cos import ~/Downloads/Takeout/                            # Google Gemini (MyActivity.json)
cos import grok-export.json                                # xAI Grok (BSON dates)
cos import perplexity_thread.json                          # Perplexity (dual-schema)
cos import export.json --extract                           # distill typed facts, not raw turns

Auto-detects all six formats; cross-vendor dedup via the PAM content_hash standard (the same question asked to different models collapses to one memory). Deterministic and offline (no API keys); every imported memory's valid_from is the original message time.

From Python

from continuityos import Memory

m = Memory("memory.db")
m.remember("The grid lab K=0.04 cohort led at +$1405 / 3 days", namespace="facts", tags=["trading"])

for hit in m.recall("best grid setup", k=3):
    print(hit.score, hit.namespace, hit.text)

# inject straight into an agent prompt:
print(m.context("what do I know about grid trading?"))

As an MCP server (Claude Desktop / Claude Code)

ContinuityOS ships an MCP stdio server so an agent can remember and recall on its own. Add to your MCP client config:

{
  "mcpServers": {
    "continuityos": {
      "command": "cos",
      "args": ["--db", "~/.continuityos/memory.db", "serve"]
    }
  }
}

Tools are reported by the MCP tools/list response; use that response as the version-correct inventory. Now the agent pulls relevant memory automatically before answering — and writes new facts back as it learns it.

Recommended: use the cross-platform bridge instead of cos serve:

{
  "mcpServers": {
    "continuityos": {
      "command": "python",
      "args": ["/path/to/mcp_bridge.py"]
    }
  }
}

See docs/MCP_INTEGRATION.md for Hermes, Claude Desktop, and Cursor setup.

Over HTTP (optional)

cos api --port 8077                       # local-only: 127.0.0.1
curl -s "localhost:8077/recall?q=license&k=3"
curl -s -XPOST localhost:8077/remember -d '{"text":"hello","namespace":"notes"}'

Remote bind is intentionally opt-in:

export CONTINUITYOS_ALLOW_REMOTE=1        # required for --host 0.0.0.0
export CONTINUITYOS_TOKEN='change-me'     # optional bearer auth for HTTP API
cos api --host 0.0.0.0 --port 8077
curl -H "Authorization: Bearer $CONTINUITYOS_TOKEN" "localhost:8077/health"

Real semantic recall (recommended)

The default embedder is offline & dependency-free. For real semantic quality (synonyms, paraphrases), switch in one line:

from continuityos import Memory
from continuityos.embedders import FastEmbedEmbedder   # pip install "continuityos[fast]"
m = Memory("memory.db", embedder=FastEmbedEmbedder())  # bge-small, ONNX, no torch

The optional embedder path is available, but no current comparative result artifact is shipped. See BENCHMARKS.md for the reproducible zero-dependency floor and its limitations.

With Docker

docker compose up -d        # HTTP API on :8077, memory persisted in ./cos-data

More than memory — the continuity layer

A chat is a terminal, not memory. ContinuityOS persists the operating state that keeps work coherent across sessions:

• Canon — slow, non-negotiable truths (who you are, rules you don't break).
• Frontiers — 1 trunk + 1 cash + 1 lab focus discipline; classify every idea.
• Open loops — what's still unfinished, bounded so it can't sprawl.
• Checkpoints — every session ends with delta + next irreversible action + proof.
• Doctor — an anti-drift check: is a cash frontier set? loops bounded? checkpoint fresh? proof attached?
• Handoff pack — one block (canon + frontiers + loops + last checkpoint) to resume in a new session or hand to another agent.

cos frontier trunk continuityos
cos frontier cash  inner-circle
cos loop "ship v0.2 to GitHub"
cos checkpoint --summary "built continuity layer" --next "update sites" --proof continuity.py
cos doctor       # ✅ healthy 5/5  (or flags drift)
cos handoff      # paste this into the next session

from continuityos import Continuity
c = Continuity(db="memory.db")
c.add_canon("Proof beats explanation. Closure beats branching.")
c.set_frontier("cash", "inner-circle")
c.checkpoint(summary="...", next_action="...", proof="path/to/artifact")
print(c.doctor())     # anti-drift report
print(c.handoff())    # resume-context block

Over MCP the agent gets checkpoint, handoff, doctor, set_frontier tools too — so it maintains its own continuity, not just its recall.

Governance — devil's advocate, audit, gate

ContinuityOS isn't just recall — it's the governance & audit layer for agent memory, built for the EU-AI-Act era (Article-12 queryable decision records), not the LoCoMo leaderboard.

• cos advocate "<claim>" — a running devil's advocate that challenges a claim or action against your own memory (contradictions, stale facts, missing evidence, canon conflicts, overconfidence, dishonest omissions, irreversible actions) → verdict STOP / RECONSIDER / PROCEED. Auto-gated at checkpoint/close/boot. Rubric in ADVOCATE.md.
• cos audit [--devil] — memory inventory + invariants (append-only integrity, bi-temporal ordering, canon, dangling pointers); emits an Article-12-style record.
• Governance preflight — for actions explicitly routed through the runner or an installed hook, a decision (ALLOW / WARN / HOLD / DENY / REQUIRE_CONFIRMATION / DRY_RUN_ONLY) with reasons, rollback plan, and an append-only ledger.

cos advocate "All 150 bots are profitable and guaranteed to win"   # flags overconfidence + honesty
cos audit --devil                                                   # invariants + adversarial pass

How it works

            remember(text, namespace, tags)
                        │
                        ▼
        ┌───────────────────────────────┐
        │            Store               │   one local SQLite file
        │  items  +  FTS5  +  vectors    │
        └───────────────────────────────┘
                        ▲
          recall(query) │  HYBRID rank
            ┌───────────┴───────────┐
   structural / keyword       semantic / vector
   (FTS5 + namespace)         (cosine over embeddings)
            └───────────┬───────────┘
                  blended score → top-k

• Structural layer — namespace (folder-like) + tags + FTS5 full-text index.

• Semantic layer — each memory is embedded to an L2-normalized vector; recall ranks by cosine similarity.

• Hybrid score — semantic_weight · semantic + (1 − semantic_weight) · keyword (tunable; default 0.6).

• Embeddings are pluggable — the default HashingEmbedder is deterministic and fully offline (great for privacy and tests). For best semantic quality, pass any str → list[float] callable (e.g. a sentence-transformers model):

  from sentence_transformers import SentenceTransformer
  enc = SentenceTransformer("all-MiniLM-L6-v2")
  m = Memory("memory.db", embedder=lambda t: enc.encode(t, normalize_embeddings=True).tolist())
  

Privacy

ContinuityOS core does not upload memory content. Memory is a local SQLite file; governance and metering can create additional local databases. .gitignore excludes common SQLite artifacts and downloaded benchmark data, but operators remain responsible for excluding their own import/export directories and secrets.

Governance boundary status

ContinuityOS currently provides a deterministic decision engine, an argv-only controlled CLI runner, and opt-in host hooks. These are useful enforcement points inside the paths that are actually wired to them. The MCP preflight_action tool is advisory: exposing it does not force an agent's other tools through it. Raw shell access, a direct SDK call, or an unconfigured host can bypass the gate entirely.

The ledger is append-only and hash-chained, with transactional concurrent appends, but it is not cryptographically signed or externally anchored. Local rollback is materialized by the controlled CLI immediately before approved execution for supported explicit file targets; advisory preflight responses do not claim that a snapshot already exists. These artifacts can support an audit, but they are not by themselves evidence of regulatory compliance. See THREAT_MODEL.md and BUILD_GATE_STATUS.md.

Two-tier memory & cost-aware routing

The strongest 2026 agents don't win on a bigger context window — they win on how they handle the finiteness of context. ContinuityOS implements the two-tier pattern Anthropic and OpenAI both converge on:

• Session memory — the auto-compactible state of the current run (goal, live hypotheses, found IDs, tool outcomes, unresolved blockers). Carried forward instead of re-derived each turn.
• Long-term memory — durable lessons, stable user preferences, recurring patterns, anti-patterns, domain facts. One lesson per file; update the existing note, don't spawn duplicates — the same discipline this repo's memory files follow.

context(query, k, max_tokens=…, compact=…) packs the most relevant long-term memories until a token budget is hit, so recall stays cheap, and its output order is deterministic — which matters for prompt-cache stability.

Cache-friendly memory rules (preserve the prompt-cache hash; cache miss = paying full price every turn):

1. Never put volatile values (datetime.now(), random IDs, per-turn counters) in the system prompt or any cached prefix — they reset the cache every call. Put them in the body of the last user message.
2. Keep tool definitions and the memory block in a stable, sorted order so the cached prefix is byte-identical across turns (compact=True + deterministic packing does this).
3. Cache thresholds and provider behavior change; verify the current provider documentation before relying on a minimum prefix size.
4. To change instructions mid-run without busting the cache, inject a role:"system" message into the history rather than editing the cached system prompt.

Cost-aware routing. estimate_cost(text, model_id, output_tokens) can compare a context block against the package's static MODEL_REGISTRY. Those entries are estimates, not a live price feed; verify provider pricing before a financial or routing decision.

Why continuity, not just memory

ContinuityOS stores continuity state outside a model: canon, rules, bi-temporal facts, and decision checkpoints can be reloaded after a model or vendor change. cos boot reconstructs a context pack; it does not prove that the new model is the same agent or will reproduce prior behavior.

Sim-OS — closed-loop simulation on top of the memory core

Beyond memory, ContinuityOS ships an experimental layer: continuityos/sim/ is a durable OODA-style loop with a mock simulation engine, risk scoring, loop detection, and local rollback hooks. It is designed to keep unverified results out of canon, but is not a sandbox or a guarantee against canon contamination.

cos sim --objective edge --iters 6      # run the closed loop (mock engine)

See continuityos/sim/README.md for the architecture.

Extension seams

ContinuityOS is a memory + governance library, not a closed product. The Memory API, advisory governance preflight, and sim/ package are available extension seams. The in-repository Sim-OS/Pandora code is an experimental integration; no independent-user, retention, or production-dependency claim is made here without a linked receipt.

Honest limits (threat model)

We'd rather tell you the edges than oversell. Full detail in THREAT_MODEL.md.

• Installation is not interception. Only the controlled runner and correctly installed hooks enforce a result. The MCP preflight tool is advisory, and direct/raw tools remain outside this boundary.
• The classifier is not an oracle. It covers known shell/file/git patterns and validates typed paths where supplied. It does not understand arbitrary application logic or close the symlink/path TOCTOU gap between decision and execution.
• Rollback is narrow and local-only. The v1 executor snapshots explicit regular-file, SQLite, and not-yet-existing file targets. Directories, symlinks, remote APIs, GitHub operations, messages, and transactions are not reversible through this module.
• The ledger is tamper-evident, not tamper-proof. Concurrent appends are serialized, but there is no signature, separate writer identity, or external anchor.
• Default embedder is weak on purpose. The zero-dependency HashingEmbedder is fast but semantically shallow. For real synonym/paraphrase recall install continuityos[fast] (ONNX, ~bge-small) or [m2v] (30MB static). We publish honest LoCoMo retrieval numbers in BENCHMARKS.md — not answer-graded marketing figures.
• Memory can go stale. A fact true last week can be wrong today. Use bi-temporal supersede() / recall(current_only=True) so corrections hide stale facts instead of contradicting them. Don't hand an agent raw memory without the current-only filter for state-sensitive decisions.
• It asks for discipline. Continuity relies on session-close rituals (cos checkpoint) and periodic cos doctor. Skip them and the store drifts toward a log dump. This is a feature (auditable thread), but it is real operator work.
• Prompt-cache hygiene. If you inject memory into a system prompt, keep it deterministic — a dynamic value (e.g. datetime.now()) busts the cache and you pay full context cost every call. context(..., compact=True) returns cache-stable output; don't wrap it in per-call timestamps.

Best fit today: operators and teams that need auditable, governed continuity (regulated internal ops, on-call/shift handoff, coding agents with rollback). Overkill if you just want Git-style backups and paste context by hand.

Status

Package version: v0.9.0. Current test and governance-corpus results are recorded in BUILD_GATE_STATUS.md; the CI workflow is the authoritative moving signal.

GitHub Transition Gate v1

Verify a strict host-closure/GitHub-transport return without applying it:

continuity github-transition verify \
  --zip RETURN.zip \
  --sidecar RETURN.zip.sha256 \
  --ready RETURN.zip.READY_FOR_SYNC.json \
  --task-body-sha256 <controller-pinned-sha256>

The gate preserves exact producer terminals (including REVISE), verifies all nine CODEX/WORK slots, repository visibility and remote HEAD/tree readbacks, and rejects force-push, existing-default merge, secret/raw-evidence leakage and any state/deployment/trading effect.

After GPT records semantic verdicts, evaluate a proposal-only memory candidate:

continuity memory-promotion evaluate \
  --closure-receipt GITHUB_TRANSITION_RECEIPT.json \
  --semantic-decisions SEMANTIC_DECISIONS.json

Even a successful result is only PROMOTION_CANDIDATE_ELIGIBLE; R63 and live state are not changed. See docs/GITHUB_TRANSITION_GATE_V1.md.

GitHub Work Admission Gate v1

Before persistent code work, bind exact task bytes, session capsule, Git baseline, candidate branch, workspace, path scope, validation commands and effect ceiling:

continuity work-admission verify \
  --request WORK_ADMISSION_REQUEST.json \
  --work-order WORK_ORDER.md \
  --session-capsule SESSION_CAPSULE.json \
  --repo /path/to/disposable/clone \
  --check-remote

After the candidate commit, ContinuityOS can execute the exact admitted test vectors itself and bind the actual stdout/stderr bytes:

continuity work-admission run-validation \
  --admission-receipt WORK_ADMISSION_RECEIPT.json \
  --admission-receipt-sha256 <SHA256> \
  --repo /path/to/candidate \
  --output-dir /outside/repo/validation-evidence

continuity work-admission verify-validation \
  --admission-receipt WORK_ADMISSION_RECEIPT.json \
  --admission-receipt-sha256 <SHA256> \
  --repo /path/to/candidate \
  --evidence-dir /outside/repo/validation-evidence

Then verify linear Git ancestry, changed paths, file/byte/commit budgets, the validation receipt and independently rehashed raw evidence:

continuity work-admission verify-delta \
  --admission-receipt WORK_ADMISSION_RECEIPT.json \
  --admission-receipt-sha256 <SHA256> \
  --validation-receipt /outside/repo/validation-evidence/WORK_VALIDATION_RECEIPT.json \
  --validation-evidence-dir /outside/repo/validation-evidence \
  --repo /path/to/candidate \
  --check-remote

A pass authorizes only later candidate transport. The gates do not create a branch, push, merge, deploy, apply R63/current state, trade or use capital. See docs/GITHUB_WORK_ADMISSION_GATE_V1.md and docs/GITHUB_WORK_VALIDATION_EVIDENCE_V1.md.

GitHub Work Ledger v1

Persist one admitted GitHub work run as an immutable receipt chain:

continuity work-ledger init --admission-receipt ADMISSION.json --out work-00.jsonl
continuity work-ledger append-delta --ledger work-00.jsonl --delta-receipt DELTA.json --out work-01.jsonl
continuity work-ledger append-transport --ledger work-01.jsonl --transport-receipt TRANSPORT.json --out work-02.jsonl
continuity work-ledger append-semantic --ledger work-02.jsonl --semantic-decision GPT_DECISION.json --out work-03.jsonl
continuity work-ledger finalize --ledger work-03.jsonl --out work-04.jsonl
continuity work-ledger verify --ledger work-04.jsonl
continuity work-ledger verify-extension --before work-03.jsonl --after work-04.jsonl

Each command creates a new successor ledger instead of mutating the input. Receipt hashes, candidate/remote HEAD and tree, GitHub Actions, GPT-only semantic review, R63 and all DENY effect ceilings are hash-chained. A closed ledger is only an integration candidate; it does not merge, deploy or apply state. See docs/GITHUB_WORK_LEDGER_V1.md.

Common Operational Context v1

Create a bounded, evidence-bound context pack from a quiescent local Common Operational Memory database:

continuity-context prepare --db memory.db --capsule SESSION_CAPSULE.json \
  --spec OPERATIONAL_CONTEXT_SPEC.json --out OPERATIONAL_CONTEXT.json
continuity-context verify --db memory.db --capsule SESSION_CAPSULE.json \
  --spec OPERATIONAL_CONTEXT_SPEC.json --context OPERATIONAL_CONTEXT.json

The bridge is shadow-only, reads SQLite immutably, rejects a non-empty WAL, fails closed on budget overflow, and never applies state. See docs/COMMON_OPERATIONAL_CONTEXT_V1.md.