one-context-mcp

One local MCP server that gives Claude, Cline, Codex, and other AI tools the same project memory.

one-context-mcp stops the repeated setup explanation every time you switch AI tools. It stores project context locally in a small SQLite database and exposes it through MCP tools that every connected assistant can read and update.

• PyPI package: one-ctx
• Main CLI command: one-context
• Alternate CLI commands: ctx, one-ctx
• GitHub repo: m4vic/one-context-mcp
• Default merge mode: local rules only, no model and no API key

Quick Install

Add this to Claude Desktop, Cline, Codex, or any MCP client:

{
  "mcpServers": {
    "one-context": {
      "command": "uvx",
      "args": ["--from", "one-ctx", "one-context", "stdio"]
    }
  }
}

Then fully restart the MCP client.

First prompt — paste this once and your assistant teaches itself the tool:

Call how_to_ctx() and follow that guide for this and every session.

Full setup instructions are in INSTALLATION_GUIDE.md.

Why It Exists

Every coding assistant has its own short-term context. When you move from Claude to Cline, from Cline to Codex, or from one IDE session to another, you usually explain the same project again:

This is a FastAPI backend, PostgreSQL is the database, src/main.py is the entry point, we just changed auth, and next we need rate limiting.

one-context-mcp makes that explanation persistent and shared.

Architecture

graph TD
    classDef rootNode fill:#0d1117,stroke:#58a6ff,stroke-width:3px,color:#c9d1d9,font-size:16px,font-weight:bold;
    classDef aiNode fill:#161b22,stroke:#3fb950,stroke-width:2px,color:#c9d1d9,font-size:14px;
    classDef bucketNode fill:#21262d,stroke:#8b949e,stroke-dasharray: 5 5,color:#c9d1d9;
    classDef localNode fill:#1f2937,stroke:#f59e0b,stroke-width:2px,color:#f9fafb;

    A([one-context MCP Server]):::rootNode
    DB[(Local SQLite DB)]:::localNode

    C1[Claude Desktop]:::aiNode
    C2[Cline / VS Code]:::aiNode
    C3[Codex]:::aiNode
    C4[Other MCP Clients]:::aiNode

    B1[(WHAT\nProject scope)]:::bucketNode
    B2[(DONE\nHistory and decisions)]:::bucketNode
    B3[(NOW\nCurrent work)]:::bucketNode
    B4[(MAP\nImportant files)]:::bucketNode
    B5[(NOTES\nUser messages)]:::bucketNode

    C1 <-->|ctx_get / ctx_update| A
    C2 <-->|ctx_get / ctx_update| A
    C3 <-->|ctx_get / ctx_update| A
    C4 <-->|MCP tools| A

    A --- DB
    DB --- B1
    DB --- B2
    DB --- B3
    DB --- B4
    DB --- B5

Everything is local by default. No account, no cloud service, no vector database, and no LLM API call is required.

First Use

Use a stable project name. For example, use asrt every time you refer to the ASRT project.

Ask your assistant:

Use one-context. Link project asrt to F:\ASRT, then load context.

At the end of a work session:

Update one-context for project asrt with what we changed, what is done, what is next, and important files.

You do not edit MCP config when switching work folders. Link each project once with ctx_link(project, repo_path).

What Gets Stored

The buckets (WHAT/DONE/NOW/MAP) are auto-merged and summarized — great for evolving state, but lossy. DOCS are stored and returned verbatim — use them for anything that must survive exactly (an implementation plan, project rules, a detailed brief). MAP entries are normalized and deduplicated. When a project is linked to a repo_path, file tracking is scoped to that repo so context from different projects does not get mixed.

MCP Tools

ctx_get accepts a view argument:

• view: "brief" — returns only the recent slice of DONE when the calling session is low on context.
• view: "detailed" — returns the buckets plus the full verbatim update history, notes, and docs in the same call. Use this when a tool needs the complete detailed context (for example an implementation plan), not just the compact buckets. Bounded by CTX_MAX_DETAIL_CHARS (default 20000).

Per-Project Instructions & Docs

Buckets are auto-summarized. When you need content kept exactly — an implementation plan, project rules, a full brief — use ctx_doc:

Save the implementation plan:   ctx_doc(project, "plan", "<full plan text>")
Set project rules:              ctx_doc(project, "instructions", "Always keep ASRT internals private. Prefer SafetyDiff work.")
Read it back verbatim:          ctx_doc(project, "plan")

The instructions doc is special: ctx_get returns it at the top of the snapshot, so every tool that loads context sees the project's rules first.

Make every AI tool self-instruct from ctx

MCP is pull-based — a server can't push rules into a model. The reliable pattern is to store the rules in ctx (one place, shared across tools) and add one bootstrap line to each tool's own rules file, so it always fetches them:

At the start of work, call ctx_resolve(<workspace path>), then ctx_get(project), and follow the returned instructions field as project rules before doing anything else.

Paste that once per tool:

• Claude Code / Claude Desktop → your CLAUDE.md
• Cursor → .cursor/rules
• Cline → Custom Instructions
• Codex → ~/.codex/config

After that, per-project rules live in ctx via ctx_doc(project, "instructions", ...) and propagate to every tool automatically — change them in one place. Clients that support the MCP server-instructions capability also receive a short "how to use ctx" pointer at connect time; any assistant can call how_to_ctx() for the full guide.

CLI Reference

ctx status [project]          # View current context or list projects
ctx init <project> --path .   # Create/link project to repo path
ctx search <query>            # Search across projects and history
ctx export <project> -o f.json   # Backup one project (--all for everything, --format md for readable)
ctx import f.json             # Restore/merge an exported backup
ctx reset <project>           # Clear a project's context
ctx delete <project>          # Permanently delete a project
ctx list                      # List all projects
ctx serve --port 7337         # Start HTTP/SSE server (localhost only by default)
ctx stdio                     # Start stdio MCP server

Backup & Portability

Your entire context lives in one SQLite file (~/.ctx/ctx.db). To back it up, commit it to a repo, or move machines:

ctx export myproject -o context-backup.json   # per-project backup
ctx export --all -o all-context.json          # everything
ctx import context-backup.json                # merge into existing (safe, idempotent)
ctx import context-backup.json --mode replace # overwrite buckets

Any MCP client can do the same via the ctx_export / ctx_import tools.

Security

• stdio mode (the default setup) has no network surface.
• ctx serve binds localhost only by default (changed in 0.4.0; previously 0.0.0.0).
• To expose HTTP mode on a network, set a token first: CTX_AUTH_TOKEN=<secret> ctx serve --host 0.0.0.0. Clients must then send Authorization: Bearer <secret>. Without the token the server warns loudly.
• With auth enabled, /health hides the tool list and CORS is restricted to localhost origins.

Documentation

• Installation Guide
• PyPI package
• GitHub Releases

License

MIT

Built to end context amnesia across AI tools.