ContextOS

Persistent engineering context for AI coding agents. ContextOS is an MCP server that gives Claude Code memory across sessions. Store decisions, notes, and gotchas once; the agent already knows them next time you open a project.

Apache 2.0. Single binary. No cloud, no auth, no Postgres.

How it works

When Claude Code opens a workspace, ContextOS injects a context summary into the MCP initialize handshake. The agent receives your recent commits, open todos, and top decisions before any user message. No tool call required.

Three MCP tools are always available:

• remember -- store a memory (decision, note, gotcha, or todo).

• recall -- search memories by hybrid semantic and keyword search.

• context -- assemble a full workspace summary on demand.

Storage is local SQLite, one file per workspace under ~/.contextos/.

Related MCP server: Cortex

Install (Claude Code)

/plugin marketplace add aftabkh4n/contextos
/plugin install contextos@contextos

Restart Claude Code. The first start downloads the binary for your platform. If contextos shows as failed in /mcp, choose Reconnect. This happens once per install or update.

Then open any git repo and ask: "What was I working on?"

Other install options

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/aftabkh4n/contextos/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/aftabkh4n/contextos/main/install.ps1 | iex

The script downloads the right binary for your platform, extracts it, adds it to PATH, registers with Claude Code, and runs a selftest.

Or via .NET tool (requires .NET 10 SDK):

dotnet tool install -g ContextOS

The .NET tool path does not include the ONNX model. Run contextos --selftest after install. If it reports a missing model, see TROUBLESHOOTING.md for the three options to fix it.

After installing, register with Claude Code:

claude mcp add --scope user contextos -- contextos

Docker (amd64 and arm64):

docker build -t contextos https://github.com/aftabkh4n/contextos.git
docker run -i --rm -v contextos-data:/data -v "$PWD":/workspace contextos

The image runs the server over stdio, so give it -i. Memories are stored in /data; keep the contextos-data volume to keep them between runs. Mount the project you want memories for at /workspace. The model is built into the image, so the server needs no network at runtime. A container cannot see which project Claude Code has open, so register it once per project, from that project's folder:

claude mcp add --scope project contextos -- docker run -i --rm -v contextos-data:/data -v "$PWD":/workspace contextos

If downloading from "latest" returns a 404, the release has not been published yet. Check the Releases tab.

macOS (Apple Silicon)

These commands are safe to run repeatedly. If you've installed ContextOS before, this will cleanly upgrade you to the latest version.

# Stop any running instance and remove existing registration (no-ops on a fresh machine)
pkill -f contextos || true
claude mcp remove contextos 2>/dev/null || true

# Extract to a permanent location (no sudo required)
mkdir -p "$HOME/.local/share/contextos/osx-arm64"
curl -fsSL https://github.com/aftabkh4n/contextos/releases/latest/download/contextos-osx-arm64.tar.gz \
  | tar xz -C "$HOME/.local/share/contextos"

# Verify
"$HOME/.local/share/contextos/osx-arm64/contextos" --version

# Register with Claude Code (full path, works without any PATH changes)
claude mcp add --scope user contextos -- "$HOME/.local/share/contextos/osx-arm64/contextos"

macOS (Intel)

pkill -f contextos || true
claude mcp remove contextos 2>/dev/null || true

mkdir -p "$HOME/.local/share/contextos/osx-x64"
curl -fsSL https://github.com/aftabkh4n/contextos/releases/latest/download/contextos-osx-x64.tar.gz \
  | tar xz -C "$HOME/.local/share/contextos"
"$HOME/.local/share/contextos/osx-x64/contextos" --version
claude mcp add --scope user contextos -- "$HOME/.local/share/contextos/osx-x64/contextos"

Linux x64

pkill -f contextos || true
claude mcp remove contextos 2>/dev/null || true

mkdir -p "$HOME/.local/share/contextos/linux-x64"
curl -fsSL https://github.com/aftabkh4n/contextos/releases/latest/download/contextos-linux-x64.tar.gz \
  | tar xz -C "$HOME/.local/share/contextos"
"$HOME/.local/share/contextos/linux-x64/contextos" --version
claude mcp add --scope user contextos -- "$HOME/.local/share/contextos/linux-x64/contextos"

Windows (PowerShell)

# Stop any running ContextOS (released by Claude Code MCP sessions)
Get-Process -Name contextos -ErrorAction SilentlyContinue | Stop-Process -Force
& claude mcp remove contextos

# Download and extract to a permanent location (no admin required)
$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest -Uri "https://github.com/aftabkh4n/contextos/releases/latest/download/contextos-win-x64.zip" `
  -OutFile "$env:TEMP\contextos-install.zip"
Expand-Archive "$env:TEMP\contextos-install.zip" -DestinationPath "$env:LOCALAPPDATA\Programs\contextos" -Force
$ProgressPreference = 'Continue'

# Verify it runs
& "$env:LOCALAPPDATA\Programs\contextos\win-x64\contextos.exe" --version

# Register with Claude Code (full path, works without any PATH changes)
claude mcp add --scope user contextos -- "$env:LOCALAPPDATA\Programs\contextos\win-x64\contextos.exe"

Optional: add to PATH so you can type contextos at the command line:

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:LOCALAPPDATA\Programs\contextos\win-x64", "User")
# Restart your PowerShell session for the change to take effect.

.NET tool (requires .NET 10 SDK)

dotnet tool install -g ContextOS

The .NET tool path does not include the ONNX model. Run contextos --selftest after install. If it reports a missing model, see TROUBLESHOOTING.md for the three options to fix it.

After installing, register with Claude Code:

claude mcp add --scope user contextos -- contextos

Verify the registration

Run claude mcp list — contextos should appear without a "failed" status. Open a Claude Code session and run /mcp to confirm all three tools appear: remember, recall, context.

First five minutes

After registering, open Claude Code in any git repo with a few commits. Ask:

"What was I working on?"

The agent will describe the recent commit history and any stored memories without calling any tool. That is auto-hydration working.

Then try storing a memory:

"Use contextos remember to store: We chose SQLite over Postgres to keep the install zero-dependency. Type: decision, importance: 0.8."

Close Claude Code, reopen it in the same directory, and ask again. The decision comes back automatically.

Technical summary

ContextOS listens on stdio and speaks the MCP protocol. On the initialize handshake it assembles a context blob (recent commits, top memories by importance and recency, open todos) and returns it in serverInfo.instructions. The client passes this to the model as a system instruction before any user message lands.

Search uses a hybrid pipeline: vector cosine similarity over 384-dim embeddings (all-MiniLM-L6-v2, runs locally via ONNX Runtime) merged with SQLite FTS5 full-text search. The two ranked lists are merged via Reciprocal Rank Fusion and reranked by recency and stored importance. All of this runs in-process with no network calls for the default ONNX provider.

State lives in ~/.contextos/{workspace_id}.db, one SQLite file per workspace. The workspace ID is derived from the absolute path of the nearest .git directory. No data leaves the machine unless you configure the OpenAI embeddings provider.

Scope

v1 is a local, single-user tool. Out of scope: web UI, auth, Postgres, team sync, cloud features, PR ingestion, architecture graphs, memory decay policies. See PROJECT.md for the full spec.

Contributing

See CONTRIBUTING.md.

License

Apache 2.0. See LICENSE.