Threadctx
About
Shared memory MCP server for AI coding agents (Claude Code, Cursor). Free & local by default.
Details
- License
- MIT
Explore
- Local (default, free, no signup): memory stored as a plain JSON file
- Cloud (paid Team tier+): memory shared across everyone on the repo
- memory_write(content, tags?) — the agent calls this after resolving a
- memory_query(task_description, max_results?) — the agent calls this
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
ThreadctxCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Add to your Claude Code MCP config (claude mcp add or edit
~/.claude/mcp.json directly):
{
"mcpServers": {
"threadctx": {
"command": "npx",
"args": ["-y", "threadctx-mcp"],
"env": {
"THREADCTX_MODE": "cloud",
"THREADCTX_API_KEY": "tctx_xxx"
}
}
}
}
Add the same block to .cursor/mcp.json in your project root (or via
Cursor Settings → Tools & MCP):
{
"mcpServers": {
"threadctx": {
"command": "npx",
"args": ["-y", "threadctx-mcp"],
"env": {
"THREADCTX_MODE": "cloud",
"THREADCTX_API_KEY": "tctx_xxx"
}
}
}
}
``
That's it — the same package and config work in both clients because
MCP is a portable, open protocol.
| Variable | Required | Description |
|---|---|---|
|
THREADCTX_MODE | no | local (default) or cloud |
| THREADCTX_API_KEY | only in cloud mode | issued via cloud/scripts/create-tenant.ts |
| THREADCTX_API_URL | no | defaults to https://threadctx.dev/api/v1; override for self-hosting |
| THREADCTX_REPO | no | overrides repo auto-detection from git remote |
| THREADCTX_DB_PATH | no | local-mode store path; defaults to ~/.threadctx/local.json |
| THREADCTX_NO_AUTO_RULES | no | set to 1 to disable auto-injecting agent rule files on server start |
| THREADCTX_CAPTURE_ENABLED | for capture | set to 1 to enable the LLM-backed capture command (off by default) |
| THREADCTX_CAPTURE_PROVIDER | no | force anthropic or openai when both keys are present |
| THREADCTX_CAPTURE_MODEL | no | override the extraction model (defaults: Haiku / gpt-4o-mini) |
| ANTHROPIC_API_KEY / OPENAI_API_KEY | for capture` | your own provider key; capture calls it directly |- memory_write(content, tags?) — the agent calls this after resolving a
non-obvious bug, making an architectural decision, or learning
something worth remembering.
- memory_query(task_description, max_results?) — the agent calls this
before starting risky or repeated work. Results are returned with a
consistent attribution footer (· via threadctx — shared team memory (N) so the same string is recognizable whether you're reading
hits)
Claude Code's terminal output or Cursor's agent panel.
Tool descriptions are written to bias the model toward calling
memory_query proactively, and — as of 0.3.0 — the server reinforces this
two more ways with zero setup required: the MCP initialize response
carries the same instruction to every connecting client, and CLAUDE.md /
.cursor/rules/threadctx.mdc get it auto-injected on first start. MCP tools
are still fundamentally pull-based (no mechanism can force a tool call), but
these three layers together are the strongest guarantee we can build.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"threadctx": {
"threadctx-mcp": {
"command": "npx",
"args": [
"threadctx-mcp"
]
}
}
}
}McpServers
{
"threadctx-mcp": {
"command": "npx",
"args": [
"threadctx-mcp"
]
}
}Shared memory MCP server for AI coding agents. Works identically with
Claude Code, Cursor, and any MCP client — same package, same config
shape, no per-client integration work. On first start it also drops a
"check team memory" instruction into whichever agents' rule files your repo
uses (AGENTS.md, CLAUDE.md, Copilot, Windsurf, Cline, Gemini) so the
memory actually gets read, not just exposed.
Modes
- Local (default, free, no signup): memory stored as a plain JSON file
at ~/.threadctx/local.json — zero native dependencies, so
npx threadctx-mcp installs instantly on any machine with Node 18+ (no
compiler, no node-gyp step). No network calls except to whichever LLM
provider your agent already uses. Matching is keyword-based, scoped to
the current repo (detected via git remote). Run npx threadctx-mcp list
any time to see exactly what your agents have stored.
- Cloud (paid Team tier+): memory shared across everyone on the repo,
with real semantic search. Requires an API key from
threadctx.dev (or your own self-hosted
deployment — see ../cloud/README.md).
Quick start
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
