# Counterparts

Counterparts — an MCP server for Claude Code that builds a persistent local memory across sessions. Runs at the start of each new development task.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 15 repo stars
- Author: mlapeter
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/mlapeter/counterparts
- Updated: 2026-11-14
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/counterparts

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `COUNTERPARTS_DATA_DIR`, `COUNTERPARTS_CONFIG`, `COUNTERPARTS_UPDATE_CHECK` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
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 counterparts
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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 counterparts
```
Replace <…> with your own values

## When to use it
- maintain context across agent sessions
- forget irrelevant details over time
- open the memory dashboard in a browser
- exclude specific directories from memory

## Example prompts
- 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

## Similar
- [mem](https://affpapa.org/en/nevibecode/skills/mem.md) — skill · 2400 installs
- [context-sync](https://affpapa.org/en/nevibecode/mcp/context-sync.md) — MCP server · ★ 190 repo stars
- [Renor](https://affpapa.org/en/nevibecode/mcp/renor.md) — MCP server · ★ 55 repo stars
- [Palinode](https://affpapa.org/en/nevibecode/mcp/palinode.md) — MCP server · ★ 46 repo stars
- [State Memory MCP](https://affpapa.org/en/nevibecode/mcp/state-memory-mcp.md) — MCP server · ★ 44 repo stars
- [callimachus](https://affpapa.org/en/nevibecode/mcp/callimachus.md) — MCP server · ★ 50 repo stars

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
