{
  "markdown": "# ContextForge MCP — Persistent Memory for Claude, Cursor & Copilot\n\n[![npm version](https://img.shields.io/npm/v/contextforge-mcp.svg)](https://www.npmjs.com/package/contextforge-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)\n[![Glama MCP](https://glama.ai/mcp/servers/alfredoizdev/contextforge-mcp/badges/score.svg)](https://glama.ai/mcp/servers/alfredoizdev/contextforge-mcp)\n\n> Give Claude Code, Cursor, and GitHub Copilot **persistent memory across sessions** via the Model Context Protocol (MCP). Stop re-explaining your project every time.\n\nContextForge 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.\n\n- 🧠 **Persistent memory** — your AI remembers everything across sessions, days, and weeks\n- 🔍 **Semantic search** — find knowledge by meaning, not keywords\n- 🔗 **One memory, every tool** — Claude Code, Cursor, Copilot, Claude Desktop, Windsurf\n- 🐙 **Git integration** — sync commits and PRs automatically\n- ✅ **Task tracking** — issues, assignments, and project status\n- 👥 **Team collaboration** — share projects and memory with your team\n- 🆓 **Free tier** — get started without a credit card\n\n> [!NOTE]\n> **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).\n\n---\n\n## Quick Start\n\n### 1. Install\n\nNo 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.\n\n> 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.\n\n### 2. Get your API key\n\n1. Go to **[contextforge.dev](https://contextforge.dev)**\n2. Sign up (free tier available)\n3. Settings → API Keys → **Generate API Key**\n4. Copy your key (starts with `cf_`)\n\n### 3. Connect to your AI tool\n\n#### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"contextforge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"contextforge-mcp\"],\n      \"env\": {\n        \"CONTEXTFORGE_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop.\n\n#### Claude Code (CLI)\n\n```bash\nclaude mcp add contextforge -s user \\\n  -e CONTEXTFORGE_API_KEY=your-api-key-here \\\n  -- npx -y contextforge-mcp\n```\n\nRestart Claude Code and run `/mcp` to verify it's connected.\n\n#### Cursor\n\nAdd to your Cursor MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"contextforge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"contextforge-mcp\"],\n      \"env\": {\n        \"CONTEXTFORGE_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n#### GitHub Copilot (VS Code)\n\nAdd to your Copilot MCP config:\n\n```json\n{\n  \"servers\": {\n    \"contextforge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"contextforge-mcp\"],\n      \"env\": {\n        \"CONTEXTFORGE_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n### 4. Initialize your project (recommended)\n\n> 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.\n\nSet up your project so your AI editor always prefers ContextForge memory:\n\n```bash\nnpx contextforge-mcp init\n```\n\nBy default, `init` auto-detects which editor your project uses and writes three rule sections:\n\n- **Memory rules** — route memory questions to ContextForge instead of the built-in file memory\n- **Session Presence rules** — make parallel sessions check for each other at conversation start and before big changes\n- **Startup Context rules** — load a short project summary (overview, open tasks, live sessions) from ContextForge at the start of every conversation\n\nFiles written:\n\n- `CLAUDE.md` for Claude Code (signals: existing `CLAUDE.md` or `.claude/` directory)\n- `.cursorrules` for Cursor (signals: existing `.cursorrules` or `.cursor/` directory)\n\nIf no editor is detected, both files are generated.\n\nOn 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.\n\n#### Override with `--editor`\n\n| Flag | Behavior |\n|---|---|\n| `--editor=claude` | Generate only `CLAUDE.md` |\n| `--editor=cursor` | Generate only `.cursorrules` |\n| `--editor=all` | Generate both, skip detection |\n\nRe-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.\n\n#### Check your version\n\n```bash\nnpx contextforge-mcp --version   # also: -v, version\n```\n\nPrints the installed version (e.g. `contextforge-mcp 0.5.2`).\n\n#### Already using ContextForge? (existing users)\n\nNothing to reconfigure. Update to the latest and restart your AI client:\n\n```bash\nnpm update -g contextforge-mcp   # only if you installed globally; npx users get it on next launch\n```\n\nYou do **not** need to re-run `init` — the auto-load behavior ships with the server and applies on your next connection.\n\n---\n\n## Available Tools\n\nContextForge 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):\n\n- **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`.\n- **`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.\n\nSet `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](#environment-variables).\n\nWhy 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`.\n\n### Knowledge Management\n\n| Tool | Description |\n|------|-------------|\n| `memory_ingest` | Save knowledge to memory |\n| `memory_query` | Search your knowledge semantically |\n| `memory_list_items` | List all stored items |\n| `memory_delete` | Remove specific items |\n| `memory_ingest_batch` | Save multiple items at once |\n| `memory_delete_batch` | Delete items by filter |\n\n### Spaces & Projects\n\n| Tool | Description |\n|------|-------------|\n| `memory_list_spaces` | List your spaces |\n| `memory_create_space` | Create a new space |\n| `memory_delete_space` | Delete a space |\n| `memory_move_space` | Move space to project |\n| `memory_list_projects` | List your projects |\n| `memory_create_project` | Create a new project |\n| `memory_delete_project` | Delete a project |\n| `memory_link_project` | Link directory to project |\n| `memory_unlink_project` | Unlink directory |\n| `memory_current_project` | Show linked project |\n\n### GitHub Integration\n\n| Tool | Description |\n|------|-------------|\n| `memory_git_connect` | Connect a GitHub repo |\n| `memory_git_list` | List connected repos |\n| `memory_git_activate` | Activate/deactivate webhook |\n| `memory_git_sync` | Import existing history |\n| `memory_git_commits` | List synced commits |\n| `memory_git_prs` | List synced PRs |\n| `memory_git_disconnect` | Disconnect a repo |\n\n### Issue Tracking\n\n| Tool | Description |\n|------|-------------|\n| `issues_list` | List your issues |\n| `issues_create` | Create a new issue |\n| `issues_start` | Mark as in progress |\n| `issues_resolve` | Mark as resolved |\n| `issues_resolve_by_name` | Resolve by title |\n| `issues_assign` | Assign to collaborator |\n| `issues_what_next` | Get recommendation |\n\n### Collaboration\n\n| Tool | Description |\n|------|-------------|\n| `project_share` | Share project by email |\n| `collaborators_list` | List collaborators |\n\n### Snapshots & Export\n\n| Tool | Description |\n|------|-------------|\n| `memory_snapshot_create` | Create a backup |\n| `memory_snapshot_list` | List all snapshots |\n| `memory_snapshot_restore` | Restore from backup |\n| `memory_snapshot_delete` | Delete a snapshot |\n| `memory_export` | Export to JSON/MD/CSV |\n| `memory_import` | Import from file |\n\n### Utility\n\n| Tool | Description |\n|------|-------------|\n| `memory_stats` | View usage statistics |\n| `memory_relate` | Link two items |\n| `memory_help` | Show help |\n\n---\n\n## Session Presence (multi-session coordination)\n\nRunning several Claude Code sessions in parallel (worktrees, agent teams)?\nEach MCP process automatically registers itself as a live session and\nheartbeats while it runs. On a clean exit the session is removed at once\n(a detached helper delivers the goodbye even while the host process is\nbeing killed); if the process dies hard, the session expires ~10 minutes\nafter its last heartbeat. Three tools let the agent coordinate — `session_list`\nis a core tool and always visible; `session_update` and `session_end` are\nreached through the `cf_tools` gateway by default (or set\n`CONTEXTFORGE_TOOLS=full` to see all three directly):\n\n| Tool | What it does |\n|------|--------------|\n| `session_update` | Declare what this session is working on (\"working on the auth module\") |\n| `session_list` | See other live sessions in the same project and their focus before touching shared areas (pass `all_projects: true` for the whole org) |\n| `session_end` | Explicitly end this session's presence (also automatic on exit) |\n\nBy default `session_list` is scoped to the current project — where work\nactually collides. In a multi-project organization, pass `all_projects: true`\nto see every session, or `project: \"<name-or-id>\"` to scope elsewhere.\n\nRecommended pattern for your CLAUDE.md: call `session_list` when a\nconversation starts; call `session_update` when starting or switching tasks.\n\n---\n\n## Natural Language Examples\n\nYou don't need to memorize commands — just talk naturally to your AI:\n\n```\n# Knowledge\n\"Save this: we use PostgreSQL for the main database\"\n\"What database do we use?\"\n\"List my spaces\"\n\n# GitHub\n\"Connect my repo github.com/myuser/myproject\"\n\"What commits did I make today?\"\n\"Show PRs merged this week\"\n\n# Issues\n\"Create an issue: Update the login page design\"\n\"What's pending?\"\n\"What should I work on next?\"\n\"Mark the login issue as done\"\n```\n\n---\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `CONTEXTFORGE_API_KEY` | Yes | Your API key from the dashboard |\n| `CONTEXTFORGE_API_URL` | No | API endpoint (defaults to production) |\n| `CONTEXTFORGE_DEFAULT_SPACE` | No | Default space for operations |\n| `CONTEXTFORGE_TOOLS` | No | `lean` (default) exposes 11 tools — the 10 most-used plus the `cf_tools` gateway to the other 59. `full` exposes all 69, as versions before 0.11.0 did. Lean keeps ContextForge under Cursor's 40-tool cap and Claude Code's 50-tool degradation threshold. |\n\n---\n\n## How it works\n\nContextForge 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.\n\nThis means:\n- **No infra to manage** — no local databases, no embeddings to run, no vector stores to maintain\n- **Works everywhere your AI works** — same memory across Claude Code, Cursor, Copilot, etc.\n- **Team collaboration** — shared projects sync in real time\n\n---\n\n## Dashboard\n\nManage your memory visually at **[contextforge.dev](https://contextforge.dev)**:\n\n- View and organize your knowledge\n- Search and filter memories\n- Manage API keys and billing\n- Track issues and collaborate\n- Export and backup data\n\n---\n\n## Development\n\n```bash\n# Clone and install\ngit clone https://github.com/alfredoizdev/contextforge-mcp.git\ncd contextforge-mcp\nnpm install\n\n# Build\nnpm run build\n\n# Run tests\nnpm test\n\n# Watch mode\nnpm run dev\n```\n\n---\n\n## Contributing\n\nIssues and pull requests are welcome at **[github.com/alfredoizdev/contextforge-mcp](https://github.com/alfredoizdev/contextforge-mcp)**.\n\n---\n\n## Support\n\n- 📖 [Documentation](https://contextforge.dev/docs)\n- 🐛 [Report Issues](https://github.com/alfredoizdev/contextforge-mcp/issues)\n- 💬 Questions: support@contextforge.app\n\n---\n\n## License\n\nMIT © [Alfredo Izquierdo](https://github.com/alfredoizdev)\n",
  "bytes": 13752,
  "sha": "3e7a8e27868979d3fdff219d85e54d7460be76be33d915abd67adb1e62ae85ff",
  "repo_slug": "alfredoizdev/contextforge-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_alfredoizdev_contextforge_mcp_8f397707/readme"
}