ContextOS

繁體中文 · English

Make task lifetime independent from context-window lifetime.

ContextOS is an experimental persistent context, memory, and MCP capability runtime for long-running local coding agents. llama.cpp remains the inference and interaction plane; ContextOS externalizes volatile state and exposes policy-controlled repository, memory, and evidence capabilities over standard local MCP.

Why

Most local agents implicitly assume:

conversation history = memory

That breaks down during long coding tasks. Test logs, repeated file reads, stale tool output, and old reasoning consume the context window. FIFO context shifting cannot tell an architecture decision from disposable compiler output.

ContextOS uses a different model:

Repository       = Mutable source of truth
Artifact         = Durable tool evidence
State Transfer   = Derived continuation state
Prompt Context   = Disposable working view

The goal is simple: a conversation may be compacted or reset without killing the task.

Status

Experimental · v0.2.0-dev.7 Host Context Bridge · Windows-first

The deterministic control remains frozen at v0.1.2, M4 experiment inputs remain pinned to aa59f4d, and the D0-D6 dev.5 execution contract is unchanged. dev.6 added the standards-based stdio MCP capability boundary. dev.7 adds a loopback Host Context Bridge and a narrow llama.cpp b10295 Web UI overlay so every browser completion request is pressure-checked before inference. The browser still owns the full transcript and llama.cpp remains the inference runtime.

Tested with:

• llama.cpp b10295 OpenAI-compatible chat/tool API; native MCP host compatibility verified against the tagged source and exact protocol flow
• Qwen3.6-35B-A3B GGUF
• Windows 11, Node.js 24, NVIDIA CUDA
• 64K active context, 16K reserved/output budget, 4K reasoning budget
• v0.1.2 read_file -> artifact -> read_artifact end-to-end recovery path
• Official MCP SDK negotiation plus llama.cpp MCP 2024-11-05 protocol smoke

The standalone AgentRuntime is not tied to a specific model name, but its backend must return OpenAI-style chat messages and tool calls. The MCP server is host-independent stdio; llama.cpp b10295 is the compatibility target. Other host/model pairs are not yet part of the test matrix.

Features

• Persistent working state across conversations
• Human-editable project memory
• Structured episodic memory
• Repository file/symbol map
• Tool output externalization into durable artifacts
• Recovery-gated tool-output compression and exchange eviction
• Bounded artifact retrieval with SHA-256 integrity checking
• Tool-schema-aware, five-level context pressure policy
• Schema-validated Coding State Transfer instead of generic summaries
• OpenAI-compatible tool-calling loop
• Stable-ID Context Units with explicit authority, recoverability, protection, dependencies, and lifecycle
• Bounded observational Context Inventory kept behind the model serialization boundary
• Canonical inventory SHA-256 identity that rejects stale plan bindings
• Strict CompactionPlan parser with default KEEP and proposal-only actions
• Model-free FakePlanner and valid/invalid protocol fixtures
• Runtime-owned protection, authority, recoverability, and transitive dependency authorization
• Distinct, side-effect-free ValidatedPlan with potential upper-bound token accounting
• Bounded PlannerInventoryView with global input, unit, visibility, and output limits
• Isolated tool-free Qwen Planner with versioned prompt and one strict repair attempt
• Visible-only proposal binding, deterministic fallback, session audit, PAR/IPR metrics
• M4 freeze manifest covering planner-v1, Planner input/budgets, M2, M3, and Planner metrics
• Read-only artifact, repository, memory, and rebuildable recovery-source verification
• Strict ValidatedPlan admission gate and distinct deep-frozen ExecutablePlan
• Runtime-owned source/candidate SHA-256 binding and deterministic non-COMPRESS candidates
• Isolated tool-free transformer-v1 COMPRESS generation with one schema-only repair
• Whole-plan immutable TransformationCandidate with no execution authority
• Runtime-first post-transform gates for exact binding, digests, token estimates, operation rules, and compression targets
• Isolated tool-free transform-validator-v1 semantic preservation assessment for COMPRESS only
• Whole-plan immutable ValidatedTransformation; any mechanical or semantic failure rejects everything
• Model-free D5 pre-commit revalidation of the complete Validation/Candidate/Plan/Inventory chain
• Single-use, generation-guarded Atomic Executor with whole-plan clone/build and one reference-swap commit
• Immutable ExecutionResult; stale context, recovery drift, or any build failure aborts without partial mutation
• Post-commit D6 finalization bound to the exact committed context generation
• Existing-registry Context Inventory rebuild with stable IDs and inactive removed units
• Canonical before/after ContextManager accounting with identical tools/overhead and signed actual reduction
• Immutable ExecutionReport; finalization failure never rewrites D5 as aborted or rolls back its commit
• Real-path-aware project-root containment for file and artifact tools
• Approval prompts for writes, edits, and shell commands
• Destructive-command guardrails
• Windows start, stop, diagnostics, setup, and resumable model download scripts
• Standard MCP stdio server using the pinned official TypeScript SDK
• Default read-only tool surface and explicit trusted-local mutation mode
• Bounded MCP resources for repository map, project memory, working state, and durable artifacts
• Machine-readable MCP evidence envelopes backed by the existing ToolEvidenceManager
• Loopback-only Host Context Bridge with bounded request validation, exact-request caching, and fail-closed preparation
• Minimal official llama.cpp b10295 Web UI overlay that preserves browser history while compacting the model request copy
• One-click bridge/server/MCP/UI lifecycle with integrated UI, health, and mutation-tool checks

Architecture

flowchart LR
    U["User"] --> H["llama.cpp Web UI / Agent Host"]
    H --> B["ContextOS Host Bridge preflight"]
    B --> H
    H <--> L["llama.cpp inference"]
    L <--> Q["Qwen3.6"]
    H <--> C["MCP client"]
    C <--> M["ContextOS MCP server"]
    M --> T["ToolRunner / policy"]
    M --> D["Memory / evidence / artifacts"]
    T --> P["Project repository"]

Loading

The .qwen-agent directory name is retained for compatibility with the original MVP. A neutral on-disk namespace is planned before a stable release.

Quick start

Requirements

• Windows 10/11
• Node.js 20 or newer
• A recent llama-server.exe
• A tool-capable GGUF model
• Enough RAM/VRAM for your model and context size

1. Clone

git clone https://github.com/HayronHgh/context-os.git
cd context-os

2. Create local configuration

Double-click 00_setup.bat, or run:

npm run setup

This creates ignored local files:

config/agent.json
config/server.json
config/mcp.json
config/llama-mcp.json
config/bridge.json

Edit config/server.json and point executable and model to your local files. Edit config/mcp.json.projectRoot for the repository exposed to the llama.cpp Web UI. Keep MCP mode read-only unless local mutation is intentional.

Build the exact b10295 Web UI overlay once, or copy an already-built ignored host-ui/ directory. See Host Context Bridge. To expose writes without shell commands, copy the fields from config/mcp.trusted-local.example.json into local config/mcp.json.

3. Diagnose and start

START.bat

START.bat is the one-click stack entrypoint. It starts the Host Context Bridge and llama.cpp with the generated config/llama-mcp.json, waits for both health surfaces, verifies the exact integrated UI marker and ContextOS tools through /tools, and opens the Web UI. In trusted-local mode it also requires write_file and edit_file. 02_start_agent.bat remains an optional standalone CLI:

02_start_agent.bat "C:\path\to\your\repository"

Stop the managed bridge, server, and stdio MCP child with the one-click STOP.bat.

Agent commands

Command	Purpose
/health	Check server and loaded model
/map	Rebuild the repository map
/state	Show persistent working state
/memory	Show project memory
/inventory	Inspect the current Context Unit inventory
/compact	Force Coding State Transfer
/new	Reset conversation, retain persistent state
/project	Show the active project root
/exit	Exit the CLI

Tools

Read-only MCP mode advertises six Runtime-managed tools:

read_file             file_glob_search
grep_search           read_working_state
read_artifact         get_datetime

Explicit trusted-local mode additionally advertises six mutation/state tools:

write_file            edit_file
run_command           build_repo_map
update_working_state  save_episode

The standalone CLI keeps interactive approval. MCP stdio has no interactive approval channel, so read-only mode omits mutations and trusted-local is explicit non-interactive auto-approval. All calls still use existing containment, command policy, and evidence handling.

Persistent state

Each target repository receives:

.qwen-agent/
├── state.json
├── project.md
├── repo-map.json
├── episodes/
├── artifacts/
└── sessions/

State	Purpose	Commit?
project.md	Shared architecture and conventions	Optional
state.json	Current task state	No
repo-map.json	Generated repository index	No
episodes/	Solved-problem memory	No
artifacts/	Full tool output	No
sessions/	Conversation/tool event log	No

Context pressure policy

Input budget is contextWindow - reservedOutputTokens. Utilization includes messages, the complete tool-definition payload, tool_choice, and a configurable fixed chat-template safety margin.

Utilization	Action
55%	Compress stale, oversized tool output
65%	Evict complete stale tool-call/result exchanges
72%	Compact older turns into structured Coding State Transfer
80%	Force transfer and retain only the latest user work window
90%	Stop instead of silently losing state

ContextOS never destructively compresses tool evidence at 55%, or evicts a complete tool exchange at 65%, unless every affected result has a durable artifact recovery path. Non-durable evidence stays in context and the runtime records the blocked eviction. Semantic and hard State Transfer retain their v0.1.1 deterministic behavior.

Tool results above artifactPersistenceChars are persisted independently of prompt rendering. Large prompt representations are bounded by maxToolOutputChars; exact content remains available through read_artifact.

Security

Warning

ContextOS is an experimental coding-agent runtime. Shell execution is not sandboxed.

• Do not use --yes on untrusted repositories.
• run_command executes with your current user permissions after approval.
• Deny lists cannot cover every destructive shell expression.
• .qwen-agent may contain source code, command output, paths, or secrets.
• Use a VM, container, or disposable account for untrusted code.
• The default server binds to localhost; do not expose it to a LAN without authentication, TLS, firewall rules, and a stricter threat model.
• MCP defaults to read-only. Do not enable trusted-local, llama.cpp --agent, built-in tools, or the MCP CORS proxy for untrusted content.

Read docs/SECURITY.md before using the runtime on important repositories.

What makes this different?

ContextOS is not trying to be a complete IDE or another general-purpose coding assistant. Its research question is narrower:

Can a local coding agent survive context resets and continue a long-running task using externalized state?

The project treats context lifecycle as a first-class system problem: tool artifacts are externalized, task state is durable, and working context can be rematerialized after compaction or reset.

Current limitations

• Approximate token counting, not tokenizer-exact accounting
• Regex-based symbol extraction, not AST/LSP intelligence
• Recent-only episode retrieval
• Non-streaming chat completions
• stdio-only MCP transport; no remote/LAN MCP service or authentication
• File-based persistence, no transactional database
• No strong OS sandbox
• Single coordinator, no multi-agent think tank
• Windows-first management scripts

Roadmap

• v0.1.2: deterministic durability and Phase 1/2 core freeze
• v0.2.0: Adaptive Semantic Context Planning research and threshold/semantic/hybrid benchmark
• v0.2.0-dev.6: standards-based MCP capability server without host transcript ownership
• v0.2.0-dev.7: bounded Host Context Bridge and exact llama.cpp b10295 Web UI request preflight
• v0.3.0: tree-sitter, LSP, Git, and repository graph intelligence
• v0.4.0: SQLite FTS5/BM25, graph retrieval, and optional semantic fallback
• v0.5.0: clean-context investigator/architect/reviewer think tank

After v0.1.2, the 0.1.x line accepts only critical bugs, security fixes, regressions, and documentation corrections. New memory architecture, context policy, repository intelligence, agents, and retrieval engines belong to 0.2+.

Documentation

English	繁體中文
Architecture	系統架構
Context compression	Context 壓縮
Memory model	記憶模型
Security	安全說明
Tutorial	完整教程
Technical report	技術報告
CompactionPlan protocol	CompactionPlan protocol
Compaction authorization	Compaction authorization
Bounded semantic planning	Bounded semantic planning
Execution contract	Execution contract
MCP capability server	MCP capability server
Host Context Bridge	Host Context Bridge
Windows MCP timeout fix	Windows MCP timeout fix
RFC-001: Adaptive Context Planning	RFC-001：自適應 Context Planning

Development

npm ci
npm test
node src/index.js --help
node src/mcp-server.js --help

License

MIT