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

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

Git Integration

Connect your repositories

Snapshots

Version control for your memory

Security

Manage API keys and permissions

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 -- contextforge-mcp again.