Counterparts — Claude Code MCP server: what it does, how to install
Counterparts — an MCP server for Claude Code that builds a persistent local memory across sessions. Runs at the start of each new development task.
no license ★ 15 updated 2026-11-14
claude mcp add --env COUNTERPARTS_DATA_DIR=<COUNTERPARTS_DATA_DIR> --env COUNTERPARTS_CONFIG=<COUNTERPARTS_CONFIG> --env COUNTERPARTS_UPDATE_CHECK=<COUNTERPARTS_UPDATE_CHECK> --transport stdio counterparts -- npx -y counterpartsWhat Counterparts does
Counterparts records session notes, decisions, and workflow details locally in an SQLite database. It forgets outdated items automatically and strips sensitive credentials before saving entries. Node 22.15 or newer, or bun 1.3 or newer is required to run the service.
The collected memories stay on your machine and remain accessible via a web dashboard or CLI commands. It checks for updates daily via npm without sending any personal data off your computer.
What it helps with
- maintain context across agent sessions
- forget irrelevant details over time
- open the memory dashboard in a browser
- exclude specific directories from memory
Example prompts for the agent
- open the memory dashboard in your browser with counterparts dashboard
- query the saved memory using counterparts ask "..."
- disable memory for the current directory with counterparts scope . --off
How to install Counterparts
Platform CLI
claude mcp add --env COUNTERPARTS_DATA_DIR=<COUNTERPARTS_DATA_DIR> --env COUNTERPARTS_CONFIG=<COUNTERPARTS_CONFIG> --env COUNTERPARTS_UPDATE_CHECK=<COUNTERPARTS_UPDATE_CHECK> --transport stdio counterparts -- npx -y counterpartsReplace <…> with your own values
Platform CLI
codex mcp add counterparts --env COUNTERPARTS_DATA_DIR=<COUNTERPARTS_DATA_DIR> --env COUNTERPARTS_CONFIG=<COUNTERPARTS_CONFIG> --env COUNTERPARTS_UPDATE_CHECK=<COUNTERPARTS_UPDATE_CHECK> -- npx -y counterpartsReplace <…> with your own values
Config file
{
"mcpServers": {
"counterparts": {
"command": "npx",
"args": [
"-y",
"counterparts"
],
"env": {
"COUNTERPARTS_DATA_DIR": "<COUNTERPARTS_DATA_DIR>",
"COUNTERPARTS_CONFIG": "<COUNTERPARTS_CONFIG>",
"COUNTERPARTS_UPDATE_CHECK": "<COUNTERPARTS_UPDATE_CHECK>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"counterparts": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"counterparts"
],
"env": {
"COUNTERPARTS_DATA_DIR": "<COUNTERPARTS_DATA_DIR>",
"COUNTERPARTS_CONFIG": "<COUNTERPARTS_CONFIG>",
"COUNTERPARTS_UPDATE_CHECK": "<COUNTERPARTS_UPDATE_CHECK>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e COUNTERPARTS_DATA_DIR=<COUNTERPARTS_DATA_DIR> -e COUNTERPARTS_CONFIG=<COUNTERPARTS_CONFIG> -e COUNTERPARTS_UPDATE_CHECK=<COUNTERPARTS_UPDATE_CHECK> counterparts npx -y counterpartsReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Counterparts
How to install Counterparts in Claude Code?
Run claude mcp add memory -- npx -y counterparts or configure it with `claude mcp add --env COUNTERPARTS_DATA_DIR=<COUNTERPARTS_DATA_DIR> --env COUNTERPARTS_CONFIG=<COUNTERPARTS_CONFIG> --env COUNTERPARTS_UPDATE_CHECK=<COUNTERPARTS_UPDATE_CHECK> --transport stdio counterparts -- npx -y counterparts`.
What does Counterparts do?
It stores long-term memory for AI agents, writing down workflow summaries and loading them in future sessions.
What is needed to run Counterparts?
Node 22.15 or newer, or bun 1.3 or newer is required.