Contextforge Mcp

ContextForge MCP — Persistent Memory for Claude, Cursor & Copilot

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

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

Restart Claude Desktop.

Claude Code (CLI)

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:

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

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

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; Claude Code's own system turns — prompts that start with an XML-like tag and contain a closing tag — are not logged)

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

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

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 runs in parallel with the other fetches under the same 6-second stage 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:

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:

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. Since 0.13.2 the server reminds you once per project when the recall hook is installed but the objective hook is missing or outdated.

Available Tools

ContextForge defines 69 tools across Knowledge Management, GitHub Integration, Issue Tracking, and Collaboration. No capability was ever removed — every tool below is fully callable — but as of v0.11.0, your AI client sees only 11 of them by default (CONTEXTFORGE_TOOLS=lean, the default):

• 10 core tools — the ones used on the agent's own initiative every session: memory_query, memory_ingest, memory_check_freshness, memory_confirm, memory_correct, memory_forget, tasks_list, tasks_what_next, session_list, memory_help.
• cf_tools — one gateway tool that discovers and runs the other 59. Ask your AI naturally ("sync my git commits", "restore from a snapshot", "olvida ese recuerdo viejo") and it searches (English or Spanish) and calls the right tool for you — no need to know an exact name.

Set CONTEXTFORGE_TOOLS=full to expose all 69 tools directly to your client instead, matching the behavior of versions before 0.11.0. See Environment Variables.

Why lean by default: 69 tool schemas cost ~15,000 tokens of context on every session, push past Cursor's 40-tool cap, and contribute to the accuracy degradation several clients show past ~50 tools. The lean set cuts that to ~3,500 tokens (~77% less) while keeping every tool one call away via cf_tools.

Knowledge Management

Spaces & Projects

GitHub Integration

Issue Tracking

Collaboration

Snapshots & Export

Utility

Session Presence (multi-session coordination)

Running several Claude Code sessions in parallel (worktrees, agent teams)? Each MCP process automatically registers itself as a live session and heartbeats while it runs. On a clean exit the session is removed at once (a detached helper delivers the goodbye even while the host process is being killed); if the process dies hard, the session expires ~10 minutes after its last heartbeat. Three tools let the agent coordinate — session_list is a core tool and always visible; session_update and session_end are reached through the cf_tools gateway by default (or set CONTEXTFORGE_TOOLS=full to see all three directly):

By default session_list is scoped to the current project — where work actually collides. In a multi-project organization, pass all_projects: true to see every session, or project: "<name-or-id>" to scope elsewhere.

Recommended pattern for your CLAUDE.md: call session_list when a conversation starts; call session_update when starting or switching tasks.

Natural Language Examples

You don't need to memorize commands — just talk naturally to your AI:

# Knowledge
"Save this: we use PostgreSQL for the main database"
"What database do we use?"
"List my spaces"

# GitHub
"Connect my repo github.com/myuser/myproject"
"What commits did I make today?"
"Show PRs merged this week"

# Issues
"Create an issue: Update the login page design"
"What's pending?"
"What should I work on next?"
"Mark the login issue as done"

Environment Variables

How it works

ContextForge MCP is a thin client that translates Model Context Protocol tool calls into authenticated HTTP requests against the ContextForge API. Your knowledge is stored, indexed (semantic embeddings), and retrieved on the server side — the MCP client itself is stateless.

This means:

• No infra to manage — no local databases, no embeddings to run, no vector stores to maintain
• Works everywhere your AI works — same memory across Claude Code, Cursor, Copilot, etc.
• Team collaboration — shared projects sync in real time

Dashboard

Manage your memory visually at contextforge.dev:

• View and organize your knowledge
• Search and filter memories
• Manage API keys and billing
• Track issues and collaborate
• Export and backup data

Development

# Clone and install
git clone https://github.com/alfredoizdev/contextforge-mcp.git
cd contextforge-mcp
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run dev

Contributing

Issues and pull requests are welcome at github.com/alfredoizdev/contextforge-mcp.

Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Questions: support@contextforge.app

License

MIT © Alfredo Izquierdo