contextforge-mcp

# ContextForge MCP — Persistent Memory for Claude, Cursor & Copilot

[![npm version](https://img.shields.io/npm/v/contextforge-mcp.svg)](https://www.npmjs.com/package/contextforge-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
[![Glama MCP](https://glama.ai/mcp/servers/alfredoizdev/contextforge-mcp/badges/score.svg)](https://glama.ai/mcp/servers/alfredoizdev/contextforge-mcp)

> Give Claude Code, Cursor, and GitHub Copilot **persistent memory across sessions** via the Model Context Protocol (MCP). Stop re-explaining your project every time.

ContextForge MCP is an open-source MCP server that connects your AI coding assistants to **long-term, searchable memory**. Decisions, architecture notes, debugging context, and project knowledge stay available across every session — across every tool that supports MCP.

- 🧠 **Persistent memory** — your AI remembers everything across sessions, days, and weeks
- 🔍 **Semantic search** — find knowledge by meaning, not keywords
- 🔗 **One memory, every tool** — Claude Code, Cursor, Copilot, Claude Desktop, Windsurf
- 🐙 **Git integration** — sync commits and PRs automatically
- ✅ **Task tracking** — issues, assignments, and project status
- 👥 **Team collaboration** — share projects and memory with your team
- 🆓 **Free tier** — get started without a credit card

> [!NOTE]
> **Works automatically, no config needed (v0.5.1+).** On connect, the server sends startup instructions to your AI client. Clients that honor them (Claude Desktop, Claude Code) **load your project memory at the start of every session and save new decisions proactively — without you editing any settings**. Running `init` (Step 4) is now a reinforcement, not a requirement, and still helps on clients that don't yet honor server instructions (e.g. Cursor).

---

## Quick Start

### 1. Install

No install step needed — the setup below runs the server via `npx -y contextforge-mcp`, which fetches it on demand and keeps it up to date.

> Prefer a global install for slightly faster cold starts? `npm install -g contextforge-mcp` is optional; if you do it, you can drop the `npx -y` prefix from the commands below.

### 2. Get your API key

1. Go to **[contextforge.dev](https://contextforge.dev)**
2. Sign up (free tier available)
3. Settings → API Keys → **Generate API Key**
4. Copy your key (starts with `cf_`)

### 3. Connect to your AI tool

#### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "contextforge": {
      "command": "npx",
      "args": ["-y", "contextforge-mcp"],
      "env": {
        "CONTEXTFORGE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Restart Claude Desktop.

#### Claude Code (CLI)

```bash
claude mcp add contextforge -s user \
  -e CONTEXTFORGE_API_KEY=your-api-key-here \
  -- npx -y contextforge-mcp
```

Restart Claude Code and run `/mcp` to verify it's connected.

#### Cursor

Add to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "contextforge": {
      "command": "npx",
      "args": ["-y", "contextforge-mcp"],
      "env": {
        "CONTEXTFORGE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

#### GitHub Copilot (VS Code)

Add to your Copilot MCP config:

```json
{
  "servers": {
    "contextforge": {
      "command": "npx",
      "args": ["-y", "contextforge-mcp"],
      "env": {
        "CONTEXTFORGE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### 4. Initialize your project (recommended)

> With v0.5.1+ the server auto-loads memory on supporting clients (see the note at the top), so this step is **optional but recommended**: it reinforces the behavior, covers clients that don't honor server instructions, and fully overrides the built-in file-based memory.

Set up your project so your AI editor always prefers ContextForge memory:

```bash
npx contextforge-mcp init
```

By default, `init` auto-detects which editor your project uses and writes three rule sections and two hooks:

- **Memory rules** — route memory questions to ContextForge instead of the built-in file memory
- **Session Presence rules** — make parallel sessions check for each other at conversation start and before big changes
- **Startup Context rules** — load a short project summary (overview, open tasks, live sessions) from ContextForge at the start of every conversation
- **Post-compaction recall hook** (Claude Code only) — a `SessionStart` hook with matcher `compact` in `.claude/settings.json`. When Claude Code compacts a long conversation, the hook runs `npx -y contextforge-mcp recall` and re-injects the session objective, memories relevant to what you are working on, your project's 10 most recent memories and pending tasks, so decisions saved in ContextForge survive the summary.
- **Session objective hook** (Claude Code only, 0.13.0) — a `UserPromptSubmit` hook that runs the generated script `.claude/hooks/contextforge-objective.cjs` with plain `node` (~50 ms). It records your prompts to `~/.contextforge-mcp/sessions/<session_id>.jsonl` on your machine, so `recall` can put the session's objective back after a compaction. The log is pruned after 14 days and never uploaded; see the privacy note below for what `recall` sends.

Files written:

- `CLAUDE.md` for Claude Code (signals: existing `CLAUDE.md` or `.claude/` directory)
- `.cursorrules` for Cursor (signals: existing `.cursorrules` or `.cursor/` directory)
- `.claude/settings.json` for Claude Code — merged, never overwritten; only the two ContextForge hook groups are added
- `.claude/hooks/contextforge-objective.cjs` for Claude Code — the generated objective hook script (safe to commit; refreshed by `init` when a new version ships)

If no editor is detected, both files are generated.

On clients that honor server instructions (Claude Desktop, Claude Code), ContextForge is used automatically even without this step. On other clients — or to guarantee the built-in file-based auto-memory never wins — run `init`: it writes explicit rules that always route memory to ContextForge.

#### Override with `--editor`

| Flag | Behavior |
|---|---|
| `--editor=claude` | Generate only `CLAUDE.md` |
| `--editor=cursor` | Generate only `.cursorrules` |
| `--editor=all` | Generate both, skip detection |

Re-running `init` is idempotent **per section** — sections you already have are left untouched; missing ones are appended. Upgrading from an older version? Just re-run `npx contextforge-mcp init`: it adds the new Startup Context section without touching the rest of your file.

#### Check your version

```bash
npx contextforge-mcp --version   # also: -v, version
```

Prints the installed version (e.g. `contextforge-mcp 0.5.2`).

#### Surviving compaction (Claude Code)

Long sessions get compacted: Claude Code summarizes the conversation to free space, and the summary keeps the gist but drops details — usually the decisions, and often the task itself. `init` installs two hooks that fix both:

1. **Objective hook** (`UserPromptSubmit`) — records each prompt locally so the session's first real request is never lost to the summary.
2. **Recall hook** (`SessionStart`, matcher `compact`) — fires right after every compaction and prints back, in this order: the session objective and the latest request before the cut; up to 5 memories relevant to the current work (semantic search over the objective, git branch, recent commit subjects and changed files, whatever their age); the project's 10 most recent memories; up to 5 pending tasks; and a reminder to call `memory_query` for anything older. The whole block stays around 4 KB and is injected once, never pinned, so it does not move the compaction trigger.

The relevance search is one metered query per compaction. It only runs when there is a session objective or you are on a non-default branch (git-only context on `main` is noise), it has its own 4-second deadline so a slow search can never drop the rest of the block, and `CONTEXTFORGE_RECALL_RELEVANCE=0` in the environment turns it off entirely.

The hooks run as plain shell commands, so `recall` reads your API key from `CONTEXTFORGE_API_KEY` if set, otherwise from the `contextforge` server entry in `~/.claude.json` (where `claude mcp add` stores it), otherwise from a project `.mcp.json`. It needs a linked project (`.contextforge` in the repo root). If anything is missing it prints nothing and never blocks the session. Note that a `CONTEXTFORGE_API_KEY` exported in your shell profile wins over `~/.claude.json`: if it holds an old key, recall silently prints nothing.

Try it by hand from your project directory:

```bash
npx contextforge-mcp recall           # prints the block for the newest session in this directory
npx contextforge-mcp recall --stats   # local numbers: recalls, objective coverage, follow-up queries
```

Privacy: the prompt log and the recall stats live under `~/.contextforge-mcp/` on your machine and are never uploaded. What leaves the machine: after a compaction, `recall` sends the session objective (at most 600 characters, together with the git branch, recent commit subjects and changed file names) to ContextForge as the search query, the same way `memory_query` sends a query; it is not stored. Note that `.claude/settings.json` is usually committed, so teammates who pull the repo get the prompt hook too; they can remove the `UserPromptSubmit` group to opt out.

#### Already using ContextForge? (existing users)

Nothing to reconfigure. Update to the latest and restart your AI client:

```bash
npm update -g contextforge-mcp   # only if you installed globally; npx users get it on next launch
```

You do **not** need to re-run `init` for the auto-load behavior. To get the post-compaction recall hook and the session objective hook, run `npx contextforge-mcp init` once in each project; it only adds what is missing.