# One Context > One local MCP server that gives Claude, Cline, Codex, and other AI tools the same project memory. - **Type:** MCP server - **Install:** `agentstack add mcp-m4vic-one-context` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [m4vic](https://agentstack.voostack.com/s/m4vic) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [m4vic](https://github.com/m4vic) - **Source:** https://github.com/m4vic/one-context ## Install ```sh agentstack add mcp-m4vic-one-context ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # one-context-mcp ----> one-context [](https://pepy.tech/projects/one-ctx) > 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: ```json { "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: ```text Call how_to_ctx() and follow that guide for this and every session. ``` Full setup instructions are in [INSTALLATION_GUIDE.md](INSTALLATION_GUIDE.md). --- ## What's New in 0.7.0 Most "AI memory" tools just *store* context. **0.7.0 makes one-context *merge* it across tools** — and gives you a way to read it without spending a single tool-call token. - **Per-tool provenance.** Every `WHAT`/`DONE`/`NOW` entry is now tagged with the tool that wrote it — `- [codex @ 2026-07-23 14:20] added rate limiting`. You can see who did what. → [Cross-tool merge & provenance](#cross-tool-merge--provenance-the-part-other-memory-tools-dont-do) - **Cross-tool `NOW`, no clobber.** When one tool records a new current task, it retires *its own* previous task to `DONE` but keeps *other* tools' active work. Claude and Codex in parallel no longer overwrite each other. - **Conflict surfacing.** If two tools have competing current tasks, `ctx_get` returns a `now_conflict` so you reconcile it instead of one silently winning. - **A file you can grep (no MCP call).** Every update mirrors the project to `/.ctx/context.md`. Read it directly, `diff` it, commit it, or point your `CLAUDE.md`/`AGENTS.md` at it. → [Two ways to read your context](#two-ways-to-read-your-context) - **`ctx sync`.** New CLI command to write/refresh that mirror on demand (`ctx sync ` or `--all`). - **Honest verbatim docs.** `ctx_doc` now tells you (`truncated`, `original_chars`) if a doc exceeded the size cap instead of trimming silently. Upgrading is drop-in — no schema migration, existing `~/.ctx/ctx.db` just works. The only visible change: `.ctx/context.md` starts appearing in linked repos (it's `.gitignore`-friendly; disable with `CTX_MIRROR=0`). --- ## 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 ```mermaid 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: ```text Use one-context. Link project asrt to F:\ASRT, then load context. ``` At the end of a work session: ```text 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. Each project links itself the first time you pass `repo_path` to `ctx_update` (or run `ctx init --path .`). --- ## What Gets Stored | Bucket | Purpose | Example | |--------|---------|---------| | `WHAT` | Project identity, stack, architecture, constraints | FastAPI backend with PostgreSQL and async SQLAlchemy | | `DONE` | Completed work, decisions, solved issues | JWT auth implemented, UUID user IDs chosen | | `NOW` | Current task and next steps | Working on rate limiting middleware | | `MAP` | Important files and what they do | `src/auth.py` - auth middleware | | `NOTES` | User-authored messages (`ctx_update` with `author=`) | Remember to keep ASRT context strict | | `DOCS` | Verbatim per-project documents (plan, instructions, context, ...) | Full implementation plan, kept word-for-word | 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. --- ## Cross-tool merge & provenance (the part other memory tools don't do) Most "AI memory" MCP servers *store* or *semantically search*. one-context **merges**: it reconciles what each tool did into one project state. - **Every entry is tagged with the tool that wrote it** — `WHAT`/`DONE`/`NOW` lines look like `- [codex @ 2026-07-23 14:20] added rate limiting`. You can see at a glance who contributed what. - **NOW is cross-tool aware.** When a tool records a new current task, it retires **its own** previous task to `DONE` but **keeps other tools' active work** — so Claude and Codex working in parallel don't clobber each other. - **Conflicts are surfaced, not silently resolved.** If two different tools both have an active `NOW`, `ctx_get` returns a `now_conflict` flag listing the tools, so you (or the next assistant) reconcile it instead of one tool silently winning. ```jsonc // ctx_get response when two tools disagree on the current task "now": "- [claude @ ...] refactor auth\n- [codex @ ...] add rate limiting", "now_conflict": { "tools": ["claude", "codex"], "note": "Multiple tools have active NOW entries; reconcile before continuing." } ``` --- ## Two ways to read your context MCP tool calls cost tokens. So one-context gives you a read path that doesn't need one: 1. **The file (no MCP call).** Every update mirrors the project's context to a plain-Markdown `/.ctx/context.md` — grep it, `diff` it, commit it, or have your tool auto-read it at session start (point your `CLAUDE.md`/`AGENTS.md` at it). Zero tool-call overhead. 2. **MCP (the write path).** `ctx_update` is where the deterministic cross-tool merge happens — that's what earns the round-trip. Reads can come from the file; writes go through MCP. The mirror is **on by default**; it only writes under repo roots that already exist, and it's one well-known path you can `.gitignore`. Disable it with `CTX_MIRROR=0`. Materialize it for existing projects any time with `ctx sync ` (or `ctx sync --all`). --- ## MCP Tools **5 focused tools** (since 0.6.0). The job is a smooth, correct context handoff between tools — not a big tool surface. | Tool | Purpose | |------|---------| | `ctx_get(project?, repo_path?, view?)` | Load a project's context (+ git). Omit `project` to auto-resolve it from `repo_path`. `view`: `full` (default), `brief` (recent DONE only), `detailed` (full verbatim history + notes + docs). A mismatched `repo_path` returns a safety warning; competing NOWs from different tools return a `now_conflict`. | | `ctx_update(project?, session_summary?, tool_name, repo_path?, author?, files?)` | Persist state (merged into WHAT/DONE/NOW/MAP). `repo_path` also links the project. `author` records a verbatim user note. `files` registers important files. Empty summary + `repo_path` just links/creates the project. | | `ctx_doc(project, kind, content?, action?)` | Read/write a **verbatim** doc (`plan`, `instructions`, `context`, `handoff`, …) — stored exactly, never summarized. | | `ctx_search(query, project?)` | Search context, history, notes, and bugs; optional `project` scope. | | `how_to_ctx()` | Return the usage guide so any assistant learns the workflow. | ### Migrating from ≤0.5.x The tool surface was slimmed from 16 to 5. Every capability is preserved — folded into a parameter or moved to the CLI: | Old tool | Now | |----------|-----| | `ctx_resolve(path)` | `ctx_get(repo_path=path)` | | `ctx_strict_get(p, path)` | `ctx_get(p, repo_path=path)` — heed the `safety` warning | | `ctx_link(p, path)` | `ctx_update(p, repo_path=path)` | | `ctx_note(p, msg, author)` | `ctx_update(p, session_summary=msg, author=author)` | | `ctx_map(p, files)` | `ctx_update(p, files=[...])` | | `ctx_history(p)` | `ctx_get(p, view="detailed")` | | `ctx_bug(...)` | a note, or `ctx_doc(p, "bugs", ...)` | | `ctx_export` / `ctx_import` / `ctx_reset` / `ctx_list` | CLI: `ctx export` / `import` / `reset` / `list` | --- ## 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`: ```text Save the implementation plan: ctx_doc(project, "plan", "") 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_get(repo_path=)` (omit the project — the folder resolves it), 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 ```bash ctx status [project] # View current context or list projects ctx init --path . # Create/link project to repo path ctx search # Search across projects and history ctx export -o f.json # Backup one project (--all for everything, --format md for readable) ctx import f.json # Restore/merge an exported backup ctx reset # Clear a project's context ctx delete # Permanently delete a project ctx list # List all projects ctx sync # Write the .ctx/context.md mirror now (--all for every project) 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: ```bash 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 ``` Backup and restore are CLI-only since 0.6.0 — the MCP tool surface stays minimal. --- ## 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= ctx serve --host 0.0.0.0`. Clients must then send `Authorization: Bearer `. 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](INSTALLATION_GUIDE.md) - [PyPI package](https://pypi.org/project/one-ctx/) - [GitHub Releases](https://github.com/m4vic/one-context-mcp/releases) --- ## License MIT --- Built to end context amnesia across AI tools. ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [m4vic](https://github.com/m4vic) - **Source:** [m4vic/one-context](https://github.com/m4vic/one-context) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-m4vic-one-context - Seller: https://agentstack.voostack.com/s/m4vic - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.