contextos-dd 0.1.5

Local-first, IDE-agnostic agentic memory lifecycle manager

🧠 ContextOS

Stop paying for tokens your AI doesn't need.

A local-first proxy and memory layer for Claude Code, Cursor, Codex CLI, Continue, and Aider. ContextOS sits between your AI IDE and the cloud LLM (Anthropic, OpenAI) — classifying every conversation turn by heat, trimming stale context, and cutting your Anthropic / OpenAI token bill 50–70% on long coding sessions. Zero session data leaves your machine.

🌐 contextosmem.netlify.app · 📦 PyPI · 🐛 Issues

pip install contextos-dd && contextos install

---

✨ What it does

Every long Claude Code, Cursor, or Codex session resends the entire conversation history to Anthropic or OpenAI on every turn — that's where your token bill comes from. ContextOS is the local-first LLM context window manager that fixes this: it runs as a tiny FastAPI proxy on 127.0.0.1, classifies each turn HOT / WARM / COLD / DEAD by relevance, drops duplicates, and replaces stale runs with summaries — all on your machine, with no telemetry and no cloud sync.

🪶	50–70% fewer tokens on long sessions
⚡	Sub-100ms overhead — local FastAPI proxy with streaming passthrough
🔒	Zero telemetry, zero cloud sync — everything in ~/.contextos/
🧩	Works with 5 IDEs out of the box — one install command, all of them
📊	Live dashboard showing what was trimmed, what was saved, and why
💾	Append-only ledger — your history is never destroyed, just compressed for transit

---

🚀 60-second install

pip install contextos-dd
contextos install

That single command:

1. 🔍 Detects supported IDE configs (Claude Code, Cursor, Codex CLI, Continue, Aider)
2. 💾 Backs them up to ~/.contextos/backups/
3. 🔌 Patches them to route through the local proxy on 127.0.0.1:9137
4. 📥 Downloads two small models (~430 MB, one time) to ~/.contextos/models/
5. ▶️ Starts the daemon and opens the dashboard in your browser

💡 Offline / air-gapped? Use contextos install --skip-models. Models download on first compaction.

📖 See INSTALL.md for the full walkthrough.

---

🧬 How it works

┌────────────┐    raw history     ┌────────────────┐    trimmed payload   ┌──────────────┐
│ Claude Code│ ─────────────────► │   ContextOS    │ ───────────────────► │  Anthropic   │
│   Cursor   │                    │   (localhost   │                      │   OpenAI     │
│   Codex    │ ◄───────────────── │     :9137)     │ ◄─────────────────── │              │
└────────────┘    streamed reply  └────────┬───────┘     full response    └──────────────┘
                                            │
                                  ┌─────────┴──────────┐
                                  │  Local DuckDB +    │
                                  │  Qwen2.5-0.5B +    │
                                  │  bge-small-en      │
                                  └────────────────────┘

Every turn in your conversation is tagged by heat:

Heat	Meaning	What ContextOS does
🔥 HOT	last 5 turns	Always sent verbatim
☀️ WARM	within last 15	Always sent verbatim
❄️ COLD	older	Replaced by a narrative summary from local Qwen2.5
💀 DEAD	duplicate or empty	Dropped silently

Trigger phrases like "as we discussed earlier" fire a vector recall from a local LanceDB store and re-inject the missing context on the next turn — so summarized history is still semantically retrievable.

---

🎛️ Commands

Command	What it does
contextos install	Detect IDEs, back up configs, patch URLs, download models, start daemon + dashboard
contextos install --skip-models	Same as above but skip the model download (air-gapped)
contextos start	Start daemon + dashboard; auto-snapshots the ledger first
contextos start --no-dashboard	Start the daemon only (no browser)
contextos start --foreground	Run daemon in the foreground (debugging)
contextos stop	Stop daemon and dashboard
contextos status	Show daemon health and detected IDEs
contextos dashboard	Launch the Streamlit dashboard at http://127.0.0.1:9138
contextos doctor	Preflight checks: paths, deps, ports, IDE configs
contextos export <sid> --out file.json	Export full untrimmed history for a session (proves nothing was deleted)
contextos warmup	(Re-)download local models
contextos uninstall	Restore original IDE configs, stop daemon

---

📦 What gets downloaded

File	Size	Purpose
Qwen2.5-0.5B-Instruct-Q4_K_M.gguf	~400 MB	Compaction — summarizing COLD turns
bge-small-en-v1.5 ONNX	~30 MB	Embeddings for semantic recall

One time. Lives on disk forever. Re-pull anytime with contextos warmup.

---

🔐 Privacy

ContextOS is local-first by construction:

• 🚫 No telemetry. Zero. We do not phone home.
• 🚫 No cloud sync. Sessions, summaries, embeddings, logs — all in ~/.contextos/ on your machine.
• 🚫 No background uploads. Ever.
• ✅ Your code never reaches a third party. The only outbound call ContextOS makes is forwarding your IDE's request to the LLM you already chose.

The only network traffic ContextOS initiates on its own:

• Model downloads during install / warmup (from HuggingFace)
• Forwarding your IDE's chat requests upstream — the same request your IDE was going to send anyway, just smaller.

---

📁 Where stuff lives

~/.contextos/                       (Windows: %LOCALAPPDATA%\DataDojo\contextos\)
├── ledger.duckdb                   # append-only session + turn ledger
├── daemon.pid                      # daemon process id
├── dashboard.pid                   # dashboard process id
├── backups/                        # snapshots: ledger backups + IDE config backups
│   ├── ledger-20260517-091944.duckdb
│   └── settings.json.<ts>.bak
├── archive/                        # LanceDB vector store of compacted turns
├── models/                         # Qwen2.5 GGUF + bge-small ONNX
└── logs/
    ├── contextos.log               # rolling app log (10MB × 5)
    ├── daemon.stdout.log
    └── daemon.stderr.log

contextos uninstall restores IDE configs and stops the daemon. It does not delete the ledger or models — they stay in case you reinstall. Nuke everything by deleting the directory above.

---

🩹 Troubleshooting

The daemon won't start / "Daemon didn't become healthy in 30s"

contextos start --foreground

Runs the daemon in your terminal so you can see the real error live. Common culprits:

• Port 9137 already in use — another tool grabbed it. contextos doctor will flag this.
• AVX-512 crash on Intel 12th/13th-gen — already pinned to llama-cpp-python==0.2.90, but if you upgraded manually, downgrade back.
• Long Paths not enabled (Windows) — see INSTALL.md.
• Look at the logs: ~/.contextos/logs/daemon.stderr.log is the smoking gun.

Claude Code / IDE feels frozen or returns errors after install

Emergency kill-switch — disables trimming without uninstalling:

# Windows
set CONTEXTOS_PASSTHROUGH=1
contextos stop && contextos start

# macOS / Linux
export CONTEXTOS_PASSTHROUGH=1
contextos stop && contextos start

This makes the proxy a transparent pipe — your IDE works exactly like before, but you keep the dashboard and ledger. If this fixes the issue, please open a GitHub issue with the contents of ~/.contextos/logs/daemon.stderr.log.

Full rollback:

contextos uninstall    # restores original IDE configs

Then restart your IDE.

Dashboard shows empty charts or "no data"

The dashboard needs a few turns of activity before charts populate:

• Most panels need 1+ active session — use your IDE for a couple of minutes.
• Some charts (by-IDE / by-model breakdowns) only render meaningfully when you have multiple sessions across multiple tools.
• The "RUNNING" spinner at top-right is Streamlit's autorefresh — that's normal.

Worried about losing chat history

You can't lose it. The ledger is append-only — classification and rebuild only affect what gets sent upstream, never what's stored on disk.

Prove it to yourself:

contextos status                        # find your session id
contextos export <session_id> --out my_history.json

You'll get a JSON file with every turn ever recorded for that session, in order. Plus, contextos start snapshots the ledger to backups/ automatically every time it runs (keeps the last 7).

"Dashboard skipped: streamlit not installed"

pip install 'contextos-dd[dashboard]'

Uninstall didn't fully clean up

contextos uninstall is intentionally conservative — it restores IDE configs and stops the daemon, but leaves your ledger and models. Wipe everything by deleting the data directory:

• Windows: rmdir /s %LOCALAPPDATA%\DataDojo\contextos
• macOS/Linux: rm -rf ~/.contextos

---

🛣️ Roadmap

Version	Status	Highlights
v0.1.0	✅ shipped	Initial MVP: proxy, ledger, classifier, compactor, dashboard
v0.1.1	✅ shipped	Windows daemon stability + LanceDB API drift fix
v0.1.2	✅ shipped	Dashboard reads daemon over HTTP (fixes DuckDB lock on Windows)
v0.1.3	✅ shipped	Protocol-aware pipeline (tool_use linkage, cache_control, fail-closed validator) + seamless one-command launch + auto-backup
v0.1.4	🚧 planned	Dashboard UX overhaul with narrative insights
v0.2.0	🔭 planned	Per-conversation session IDs, OpenAI tool-calling pinning, local semantic search
Pro	🔭 future	MCP server, team/shared memory, React+WebSocket dashboard, cloud rollups (optional, encrypted)

---

🛠️ Develop

git clone https://github.com/skappal7/context-os
cd context-os
pip install -e ".[dev,dashboard]"
ruff check .
pytest -q

55 tests across the proxy, classifier, compactor, ledger, dashboard, and safety layer. Includes a realistic Claude Code fixture (tool_use + tool_result + cache_control) that locks in the v0.1.3 regression fix.

---

📜 License & credits

Apache-2.0. Built by DataDojo.

Vendored under the hood: FastAPI · DuckDB · LanceDB · llama.cpp (via llama-cpp-python) · fastembed · Qwen2.5 · BAAI/bge-small-en · Streamlit.

---

🌐 contextosmem.netlify.app

If ContextOS saves you tokens, give it a ⭐ on GitHub.