What can you do with this server?

The threadctx-mcp server provides shared memory for AI coding agents, letting them store and retrieve project-specific learnings, decisions, and gotchas across sessions and teammates. * Store memories (memory_write): Save bugs, architectural decisions, fixes, or gotchas to a shared memory store, with optional tags (e.g. ["incident", "retry-logic"]) for organization. * Retrieve memories (memory_query): Query past knowledge with a plain-language task description to surface relevant learnings and known pitfalls before starting risky or repeated work. * Local or cloud storage: Local mode stores memories as a JSON file (free, no signup); cloud mode enables team-wide sharing with semantic search via an API key. * Passive knowledge capture: The capture CLI command distills recent Git history into memories using your own LLM provider (Anthropic/OpenAI), accumulating knowledge automatically from code changes. * Auto-injects agent instructions: On first start, automatically adds a "check team memory" instruction to agent rule files (AGENTS.md, CLAUDE.md, etc.) so agents always consult memory. * CLI management: Commands like init, join, and list help set up repos for team sharing, generate MCP config files, and browse stored memories. * Cross-client compatibility: Works identically with Claude Code, Cursor, Copilot, and any MCP-compatible client — no per-client integration needed. * Repo-scoped: Memory is scoped per repository (auto-detected via git remote), keeping learnings relevant and organized.

Which integrations are available for this server?

Injects rules into GitHub Copilot's instruction file to prompt the agent to query and write team memory, enabling memory sharing across coding sessions.

How do I use threadctx-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@threadctx-mcp find context about the authentication flow" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

threadctx-mcp

Official

by threadctx-dev

Overview Schema Related Servers Score Discussions(1)

TypeScript

Hybrid

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.

This repo runs on itself: its own AGENTS.md and CLAUDE.md were set up with npx threadctx-mcp init, the same command you'd run — check the git history if you want to see it happen.

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).

Related MCP server: local-memory-mcp

Quick start

# Local mode — nothing to configure. Also auto-adds the "check team memory"
# instruction to your agents' rule files (AGENTS.md, CLAUDE.md, and any
# detected tool-specific files) on first start.
npx threadctx-mcp

# Set a repo up for your whole team (run once, commit the results)
npx threadctx-mcp init

# Cloud mode — shared team memory via threadctx.dev
npx threadctx-mcp init --mode=cloud --api-key=tctx_xxx

# Joining a repo a teammate already set up? One command:
npx threadctx-mcp join

# See what your agents have written to this machine
npx threadctx-mcp list            # this repo
npx threadctx-mcp list --all      # every repo

init writes three committable, secret-free files: .threadctx.json (just { "mode": ... }), .mcp.json (Claude Code project config), and .cursor/mcp.json (Cursor project config). Commit all three — every teammate who then opens the repo in Claude Code or Cursor is prompted to enable threadctx automatically, with nothing to install or configure. Teammates on other MCP clients run npx threadctx-mcp join, which sets up their machine the same way and prints the config block for their client.

Your API key never appears in any committed file. It is read from the THREADCTX_API_KEY environment variable at runtime (export it in your shell profile), so secrets stay out of version control by construction.

threadctx also adds a small, clearly-marked instruction to your project rules telling the agent to call memory_query before a task and memory_write after. It writes the two universal files every time — AGENTS.md (the cross-tool standard read by Copilot, Cursor, Windsurf, Zed, Codex, Aider, and ~24 others) and CLAUDE.md (Claude Code's richer native format) — plus .cursor/rules/threadctx.mdc. It then adds a tool-specific file only when that tool's footprint is detected in the repo, so it never litters your project with rule files for tools you don't use:

Tool	File written	Written when
Cross-tool standard	`AGENTS.md`	always
Claude Code	`CLAUDE.md`	always
Cursor	`.cursor/rules/threadctx.mdc`	always
GitHub Copilot	`.github/copilot-instructions.md`	`.github/` exists
Windsurf	`.windsurf/rules/threadctx.md`	`.windsurf/` exists
Cline	`.clinerules/threadctx.md`	`.clinerules` exists
Gemini CLI	`GEMINI.md`	`.gemini/` exists

Shared files (AGENTS.md, CLAUDE.md, Copilot, Gemini) get a marker-fenced block spliced in, preserving your own content around it; dedicated files are owned in full. This happens automatically the first time the server starts in a project — you don't need to run init for it. Running init just triggers it explicitly and prints the result; either way it's idempotent (safe to re-run, never duplicates). Opt out entirely with THREADCTX_NO_AUTO_RULES=1, or per-init-call with --no-rules.

The same instruction is also sent as part of the MCP initialize handshake itself (the protocol's instructions field), so it reaches the model even before any rules file exists, and for clients that don't read project-rules files at all. The file-based rules are belt-and-suspenders on top of that, since not every MCP client is guaranteed to surface instructions prominently.

Claude Code setup

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"
      }
    }
  }
}

Cursor setup

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.

Passive capture — turn git history into memory

Memory shouldn't depend on an agent remembering to call memory_write. threadctx capture reads the commits landed since its last run, uses your own LLM provider key to distill the genuinely reusable decisions and gotchas (skipping trivial commits), dedups them against what's already stored, and writes the survivors. It's tool-agnostic — it doesn't matter whether the work happened in Claude Code, Cursor, Copilot, or a plain editor.

# Off by default because it calls an LLM (billed to your provider). Enable it:
export THREADCTX_CAPTURE_ENABLED=1
export ANTHROPIC_API_KEY=sk-...     # or OPENAI_API_KEY

npx threadctx-mcp capture --dry-run     # preview what it would store
npx threadctx-mcp capture               # store them (incremental since last run)
npx threadctx-mcp capture --since=v1.2.0 --diffs   # a range, with patches

# Scaffold a GitHub Action that captures every merged PR automatically:
npx threadctx-mcp capture --print-workflow > .github/workflows/threadctx-capture.yml

Capture calls your LLM provider directly — nothing is routed through threadctx's servers, so local mode keeps its "no network call beyond your own LLM provider" promise. It is off unless THREADCTX_CAPTURE_ENABLED=1 (or a one-off --force), so it can never run up token cost as a side effect.

Environment variables

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

Local development

npm install
npm run dev     # runs the server via tsx, watches for changes
npm run build   # compiles to dist/ for publishing

How the tools work

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 hits)) so the same string is recognizable whether you're reading 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.

CLI subcommands

Command	What it does
`npx threadctx-mcp`	Runs the MCP server (this is what Claude Code / Cursor launch). Auto-injects project rules on first start in a project.
`npx threadctx-mcp init [--mode=cloud --api-key=…] [--no-rules]`	Sets a repo up for the team: writes `.threadctx.json`, committable Claude Code/Cursor project MCP configs, and the project-rules files.
`npx threadctx-mcp join`	Joins a repo a teammate already set up: project MCP configs, rules, and per-client instructions.
`npx threadctx-mcp list [--all] [--full] [--json]`	Shows what's stored in the local on-disk memory.
`npx threadctx-mcp capture [--dry-run] [--since=<ref>] [--max=N] [--diffs] [--model=ID] [--print-workflow]`	Distills recent git history into memories via your own LLM key. Off unless `THREADCTX_CAPTURE_ENABLED=1` (or `--force`).

Browse, search, edit, and prune team (cloud) memory in a human dashboard at threadctx.dev/dashboard — sign in with your team API key.

Available Tools

2 tools

memory_queryA

Retrieve relevant past learnings, fixes, decisions, or gotchas from the team's shared memory before starting risky or repeated work — e.g. touching a service that has caused incidents before, or implementing something similar to past work. Call this before, not after.

ParametersJSON Schema

Name	Required	Description	Default
`max_results`	No	Max number of memories to return (default 5).
`task_description`	Yes	What you are about to do, in plain language.

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It implies read-only behavior for retrieval. However, lacks details on auth requirements, scope of accessible memories, or potential side effects, which are minor for a query tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, purpose front-loaded, efficient. Every sentence adds value with no waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, and description does not explain return format (e.g., list of strings, objects). For a query tool, this gap hinders understanding of how results are presented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. Description adds context for 'task_description' ('What you are about to do, in plain language') and mentions default for 'max_results', providing value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it retrieves past learnings, fixes, decisions, or gotchas from shared memory. Specific verb 'retrieve' and resource 'shared memory' distinguish it from sibling 'memory_write'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'before starting risky or repeated work' and 'Call this before, not after.' Provides examples of scenarios, effectively differentiating from the write tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_writeA

Store a learning, decision, fix, or gotcha for this repository so other agents and teammates can find it later. Call this whenever you resolve a non-obvious bug, make an architectural decision, or discover something that would save someone time in the future.

ParametersJSON Schema

Name	Required	Description	Default
`tags`	No	Optional short tags, e.g. ["incident", "retry-logic"].
`content`	Yes	The learning to remember, written so a future reader has full context.

TDQS

A3.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavioral traits. It states that the tool stores a learning but does not mention important aspects like persistence, deduplication, size limits, or whether the storage is immediate. The description lacks depth about side effects or guarantees, leaving the agent uninformed about the behavior beyond the simple act of storage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences that immediately convey purpose and usage. Every word serves a purpose, and the most important information is front-loaded. There is no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (2 params, no output schema, no annotations), the description is somewhat complete but leaves gaps. It clearly states what to store and when, but does not mention what happens after storage, error conditions, or any constraints. For a write operation, knowing if it is idempotent or if there are limits would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for its two parameters, so the baseline is 3. The description adds some context by explaining what kind of content should be stored (e.g., bug fixes, architectural decisions), but it does not significantly enhance the semantics beyond what the schema already provides. The tags parameter is already well-described in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Store a learning, decision, fix, or gotcha for this repository so other agents and teammates can find it later.' It uses a specific verb ('Store') and resource ('learning'), and distinguishes itself from its sibling 'memory_query' by being the write operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to call the tool: 'Call this whenever you resolve a non-obvious bug, make an architectural decision, or discover something that would save someone time in the future.' This gives clear usage scenarios and implies that it is intended for valuable insights rather than routine updates.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0

Disambiguation5/5

The two tools have clearly distinct purposes: one for querying past learnings, the other for storing new ones. No overlap or ambiguity.

Naming Consistency5/5

Both tools follow a consistent memory_verb pattern (memory_query, memory_write), making it predictable and easy to navigate.

Tool Count3/5

Only two tools for a memory/storage server; while minimal, they cover basic read and write operations. The set feels thin but could be sufficient for a focused use case.

Completeness2/5

The tool surface lacks essential operations like listing all memories, deleting outdated entries, or updating existing ones, leaving significant gaps for typical memory management workflows.

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

MemoryRouter A
ai.memoryrouter
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Knowledge & Memory Search
101
memory
com.lodekeep
Portable memory for AI agents: capture once, recall across Claude, Cursor, and any MCP client.
Knowledge & Memory File Systems
1
Living Memory
to.viibe
An MCP memory server. One memory your agents share — across models, devices and apps.
Knowledge & Memory Autonomous Agents AI & Machine Learning
32
mifactory-agent-memory C
io.github.mifactory-bot
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Knowledge & Memory Autonomous Agents Agent Orchestration
22

Related MCP Servers

junto-memory
Knowledge & Memory Agent Orchestration
tlemmons
A
license
Not graded
quality
B
maintenance
A shared memory and coordination server for multiple AI coding agents, built on the Model Context Protocol (MCP).
Updated 7 days ago (2026-08-26 13:29 UTC)
5
MIT
local-memory-mcp
Knowledge & Memory AI & Machine Learning
basst85
F
license
Not graded
quality
D
maintenance
A local MCP server that provides semantic memory storage and retrieval for coding and AI agents, enabling durable context across chat sessions.
Updated 7 months ago (2026-02-15 20:39 UTC)
52
4
memory-mcp
Knowledge & Memory Vector Databases AI & Machine Learning
vinnyho
F
license
Not graded
quality
D
maintenance
A persistent, conflict-aware memory MCP server for AI coding assistants (Cursor, Claude Code).
Updated 3 months ago (2026-06-14 04:56 UTC)
SyncContext
Knowledge & Memory Developer Tools AI & Machine Learning
infinitylabs-io
A
license
A
quality
D
maintenance
MCP server that provides a shared semantic memory layer for AI coding agents, enabling teams to store, search, and sync context, decisions, and knowledge across projects with project-based isolation and multi-backend support.
Updated 4 months ago (2026-05-09 14:04 UTC)
14
1
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/threadctx-dev/threadctx-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

threadctx-mcp

Modes

Quick start

Claude Code setup

Cursor setup

Passive capture — turn git history into memory

Environment variables

Local development

How the tools work

CLI subcommands

Available Tools

TDQS

TDQS

TDQS

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

junto-memory

local-memory-mcp

memory-mcp

SyncContext

Latest Blog Posts

MCP directory API