I got tired of re-explaining my codebase to Claude every morning, so I built this

Every morning I open Claude Code and have the same conversation.

"We use the outbox pattern for Kafka writes." "The auth service is separate from the API." "We decided last week not to use MediatR for this project." "Yes, I know the test coverage is low in the storage layer, we're fixing it."

Same context. Every session. From scratch.

I got tired of it. So I built ContextOS.

What it does

ContextOS is an MCP server that gives AI coding agents persistent memory across sessions. You store decisions, todos, and notes during a session. The next time you open Claude Code in that workspace, ContextOS injects the relevant context automatically before you type a single word.

The agent already knows where you left off.

Here is what that looks like in practice. I open Claude Code in a workspace I have not touched in three weeks and ask "what was I working on?" Without calling any tool, Claude responds:

Project: contextos-test on branch master. Recent decision: using the outbox pattern for Kafka writes to ensure exactly-once delivery. Three commits in the last session. One uncommitted file.

No tool call. No "let me check your memory." It just knows. That is the feature I built everything around.

How it works

Three pieces worth explaining: the MCP tools, the retrieval pipeline, and auto-hydration.

The MCP tools

Four tools exposed over the MCP protocol:

• remember stores a memory with a type (decision, note, todo, gotcha, skill), tags, and an importance score from 0 to 1
• remember_skill stores a reusable procedure with name, steps, and outcome. Skills never decay.
• recall runs hybrid search over stored memories. Supports scope="global" to search across all your workspaces.
• context assembles a markdown summary of the current workspace state

Auto-hydration

When an MCP client connects, the MCP protocol sends an initialize request. ContextOS responds with the standard handshake and also sets serverInfo.instructions to a pre-assembled context blob.

The MCP spec says clients should treat serverInfo.instructions as background knowledge. Claude Code does exactly that. It reads the injected context and uses it naturally, without the user asking, without any tool call, before the first message.

The blob includes your current branch, recent commits, active todos, recent decisions, and top skills. The whole thing is assembled in under 20ms and kept under 2KB.

The retrieval pipeline

When you call recall:

1. Your query gets embedded using a local ONNX model (all-MiniLM-L6-v2, bundled in the binary, no API keys needed)
2. Vector search runs a cosine similarity scan over all stored memory embeddings
3. Keyword search runs FTS5 BM25 ranking over memory content and tags
4. Both result lists get merged using Reciprocal Rank Fusion (RRF, k=60)
5. Results get reranked by exp(-age_days/30) * (0.5 + importance)
6. Top-k results are returned

RRF is the interesting choice here. It combines ranked lists without needing to normalize scores across different retrieval methods. A memory that ranks 3rd in vector search and 5th in BM25 scores better than one that ranks 1st in only one of them.

The embeddings run entirely locally. No API call, no latency spike, no cost per query.

Memory decay

Memories auto-archive after 90 days of inactivity. If you recall a memory, the clock resets. Skills represent durable procedural knowledge so they never decay. Setting decay_days=0 on any memory pins it permanently.

What I built it on

.NET 10. The self-contained single-file binary story is solid. One file, no dependencies, runs anywhere. The release pipeline produces four platform binaries averaging 118MB each, including the .NET runtime, ONNX Runtime, LibGit2Sharp, and the embedding model.

126 tests. CI on Linux. Apache 2.0.

Honest limitations

• Cursor support is not manually verified for auto-hydration (tools work, hydration behavior unknown)
• No team or cloud sync, workspace-local SQLite only
• No automatic git ingestion, manual remember calls only
• Tested primarily with Claude Code

Install in one command

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

Or via .NET tool:

dotnet tool install -g ContextOS

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

Repo: https://github.com/aftabkh4n/contextos

If you try it, I want to know what breaks. Open an issue or comment here.