Getting Started

Get up and running with ContextForge in 5 minutes. Works with Claude Code, Claude Desktop, GitHub Copilot, and Cursor.

claude -c

Continue one conversation. Memory stays in that session. Great for short-term work on a single project.

claude + ContextForge

Permanent memory across all conversations and all projects. Searchable forever.

Prerequisites

Node.js 18 or higher
Claude Code, Claude Desktop, VS Code with Copilot, or Cursor
A ContextForge account (free tier available)

Step 1: Create an Account

Create Free Account

Step 2: Get Your API Key

After signing up, navigate to Settings → API Keys and create a new key.

Your API key will look like: cf_live_xxxxxxxxxxxxxxxx

Step 3: Install ContextForge MCP

Install the ContextForge MCP server globally using npm.

npm install -g contextforge-mcp

Two required steps remain — both are needed for memory to work:

Connect ContextForge to your editor using the API key you just created — this is the only step that uses your key. Pick your editor below (Claude Code, Claude Desktop, Cursor, or Copilot).
Initialize each project with npx contextforge-mcp init (next) so your AI actually uses ContextForge instead of its built-in memory.

The order doesn't matter — but creating an API key alone connects nothing.

Step 4: Initialize your project (required)

Run this in every project directory where you want persistent memory:

cd ~/your-project
npx contextforge-mcp init

This writes editor-specific rules that tell Claude Code and Cursor to use the ContextForge MCP instead of their built-in file-based auto-memory.

Without this step, your AI will silently ignore ContextForge for memory queries — even though the MCP is connected — because the built-in auto-memory wins by default.

What gets written

By default, init auto-detects which editor your project uses:

File written	For editor	Detected when
`CLAUDE.md`	Claude Code	`CLAUDE.md` or `.claude/` exists
`.cursorrules`	Cursor	`.cursorrules` or `.cursor/` exists
Both	—	No editor detected (zero-friction default)

Force a specific editor

Skip auto-detection with the --editor flag:

npx contextforge-mcp init --editor=claude   # only CLAUDE.md
npx contextforge-mcp init --editor=cursor   # only .cursorrules
npx contextforge-mcp init --editor=all      # both, skip detection

Idempotent: re-running is safe. Existing content in CLAUDE.md or .cursorrules is preserved; our section is appended once and skipped on subsequent runs.

Tip:you can run this before or after connecting the MCP to your AI tool below — the order doesn't matter, but both are required.

Option A: Claude Code (CLI) Setup

Set up ContextForge globally for all your projects.

Quick Setup Wizard

Recommended

Run the interactive setup wizard - it will guide you through the configuration:

npx contextforge-setup

The wizard will ask for your API key and configure everything automatically.

Alternative: Manual Command

If the wizard doesn't work, you can run this command directly:

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

Tip: Replace your-api-key-here with your API key. The -s user flag makes it available in all projects.

Verify it works:

Open Claude Code in any project and run /mcp - you should see ContextForge connected.

npx contextforge-setup --verify

Option B: Claude Desktop Setup

If you use Claude Desktop, follow these steps:

1. Find your config file

# macOS

~/Library/Application Support/Claude/claude_desktop_config.json

# Windows

%APPDATA%\Claude\claude_desktop_config.json

# Linux

~/.config/Claude/claude_desktop_config.json

2. Add ContextForge configuration

Edit the file and add this JSON configuration:

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

Note: Replace your-api-key-here with your actual API key from Step 2.

3. Restart Claude Desktop

Close and reopen Claude Desktop to load the new configuration.

Option C: GitHub Copilot (VS Code)

GitHub Copilot supports MCP servers in Agent Mode. Add ContextForge to your VS Code settings.

Option 1: Project-level config

Create a .mcp.json file in your project root:

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

Option 2: User-level config

Add to your VS Code settings.json to enable for all projects:

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

3. Use in Agent Mode

Open Copilot Chat in VS Code, switch to Agent Mode, and ContextForge tools will be available automatically.

Test Your Setup

Try these commands to verify everything works:

# Store something in memory
"Remember that our API uses JWT tokens with 1-hour expiration"

# Query your memory
"What do we use for authentication?"

# List your spaces
"Show me my memory spaces"

# Get statistics
"Show me my memory usage stats"

Recommended: Link Your Project

New

Link your local directory to a ContextForge project so queries automatically filter to that project's spaces.

Why link?

Queries only search within the linked project's spaces
Keep context separate between different codebases
No need to specify project in every command

How to link:

# See available projects
"Link this project to ContextForge"

# Link to a specific project
"Link this directory to project MyProject"

# Create and link a new project
"Create and link a project called Backend-API"

# Check what's linked
"What project is linked here?"

Note: This creates a .contextforge file in your directory. Add it to .gitignore or commit it to share with your team.

Learn more about Project Linking →

Available MCP Tools

ContextForge provides these tools to Claude for managing your contextual memory:

Core Memory Operations

memory_ingest

Store new knowledge in memory with automatic embedding generation

memory_query

Search memory using semantic similarity (powered by Voyage AI)

memory_list_items

List all stored knowledge items with pagination

memory_delete

Remove items from memory by ID or title

Project Management

memory_list_projects

List all projects in your account

memory_create_project

Create a new project to organize spaces

memory_link_projectNew

Link current directory to a cloud project

memory_current_projectNew

Show linked project and its spaces

memory_unlink_projectNew

Remove project link from directory

memory_delete_project

Delete a project and all its spaces

Space Management

memory_list_spaces

List all available memory spaces

memory_create_space

Create a new isolated memory workspace

memory_move_space

Move a space to a different project

memory_stats

Get usage statistics and limits

Git Integration

memory_git_connect

Connect a GitHub repository for automatic syncing

memory_git_sync

Manually sync commits and PRs from connected repos

memory_git_commits

List commits stored in memory

memory_git_prs

List pull requests stored in memory

Snapshots & Backup

memory_snapshot_create

Create a snapshot backup of your memory

memory_snapshot_restore

Restore memory from a previous snapshot

memory_snapshot_list

List all available snapshots

Import & Export

memory_export

Export memory as JSON, Markdown, or CSV

memory_import

Import data from JSON, Markdown, Notion, or Obsidian

Batch Operations

memory_ingest_batch

Store multiple items at once (up to 100)

memory_delete_batch

Delete multiple items using filters

Example Workflows

Document your architecture

"Remember: Our backend uses a microservices architecture with these services: auth-service (handles JWT), api-gateway (rate limiting), user-service (CRUD), and notification-service (email/push)."

Later, Claude can answer: "What services do we have?"

Save code patterns

"Store this as our standard error handling pattern:"

try {
  await operation();
} catch (error) {
  logger.error('Operation failed', { error });
  throw new AppError('OPERATION_FAILED', error);
}

Track decisions

"Remember: We decided to use PostgreSQL instead of MongoDB because of our need for complex joins and ACID compliance. Decision made on 2024-01-15."

Next Steps

Project Linking

New

Link directories to projects for automatic filtering

Semantic Search

Learn how to query your memory effectively

Troubleshooting

"Tool not found" error

Make sure you restarted Claude after adding the configuration. For Claude Code, verify with claude mcp list.

"Invalid API key" error

Double-check your API key in the configuration. Make sure there are no extra spaces or quotes. Verify the key is valid in your dashboard settings.

"Command not found: contextforge-mcp" error

Make sure you installed the package globally with npm install -g contextforge-mcp. Verify it with which contextforge-mcp.

ContextForge shows as "disabled" in Claude Code

Use the arrow keys in the /mcp dialog to navigate to contextforge and press Enter to enable it. Or run claude mcp add contextforge -s user -e CONTEXTFORGE_API_KEY=your-api-key-here -- npx -y contextforge-mcp again.

Getting Started

Prerequisites

Step 1: Create an Account

Step 2: Get Your API Key

Step 3: Install ContextForge MCP

Step 4: Initialize your project (required)

What gets written

Force a specific editor

Option A: Claude Code (CLI) Setup

Quick Setup Wizard

Alternative: Manual Command

Verify it works:

Option B: Claude Desktop Setup

1. Find your config file

2. Add ContextForge configuration

3. Restart Claude Desktop

Option C: GitHub Copilot (VS Code)

Option 1: Project-level config

Option 2: User-level config

3. Use in Agent Mode

Test Your Setup

Recommended: Link Your Project

Why link?

How to link:

Available MCP Tools

Core Memory Operations

Project Management

Space Management

Git Integration

Snapshots & Backup

Import & Export

Batch Operations

Example Workflows

Document your architecture

Save code patterns

Track decisions

Next Steps

Project Linking

Semantic Search

Git Integration

Snapshots

Security

Troubleshooting

"Tool not found" error

"Invalid API key" error

"Command not found: contextforge-mcp" error

ContextForge shows as "disabled" in Claude Code