io.github.alfredoizdev/contextforge-mcp
Persistent memory MCP server for Claude Code, Cursor, and GitHub Copilot.
Open source Open in the app JSON README (API)
About
Persistent memory MCP server for Claude Code, Cursor, and GitHub Copilot.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- alfredoizdev
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.11.0
- Stars
- 2
- Last push
- 2026-09-04T15:58:19Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:24
- Updated
- 2026-09-04 19:00:53
- Origin id
io.github.alfredoizdev/contextforge-mcp
README
# ContextForge MCP — Persistent Memory for Claude, Cursor & Copilot
[](https://www.npmjs.com/package/contextforge-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[](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:
- **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
Files written:
- `CLAUDE.md` for Claude Code (signals: existing `CLAUDE.md` or `.claude/` directory)
- `.cursorrules` for Cursor (signals: existing `.cursorrules` or `.cursor/` directory)
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`).
#### 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` — the auto-load behavior ships with the server and applies on your next connection.
---
## 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](#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
| Tool | Description |
|------|-------------|
| `memory_ingest` | Save knowledge to memory |
| `memory_query` | Search your knowledge semantically |
| `memory_list_items` | List all stored items |
| `memory_delete` | Remove specific items |
| `memory_ingest_batch` | Save multiple items at once |
| `memory_delete_batch` | Delete items by filter |
### Spaces & Projects
| Tool | Description |
|------|-------------|
| `memory_list_spaces` | List your spaces |
| `memory_create_space` | Create a new space |
| `memory_delete_space` | Delete a space |
| `memory_move_space` | Move space to project |
| `memory_list_projects` | List your projects |
| `memory_create_project` | Create a new project |
| `memory_delete_project` | Delete a project |
| `memory_link_project` | Link directory to project |
| `memory_unlink_project` | Unlink directory |
| `memory_current_project` | Show linked project |
### GitHub Integration
| Tool | Description |
|------|-------------|
| `memory_git_connect` | Connect a GitHub repo |
| `memory_git_list` | List connected repos |
| `memory_git_activate` | Activate/deactivate webhook |
| `memory_git_sync` | Import existing history |
| `memory_git_commits` | List synced commits |
| `memory_git_prs` | List synced PRs |
| `memory_git_disconnect` | Disconnect a repo |
### Issue Tracking
| Tool | Description |
|------|-------------|
| `issues_list` | List your issues |
| `issues_create` | Create a new issue |
| `issues_start` | Mark as in progress |
| `issues_resolve` | Mark as resolved |
| `issues_resolve_by_name` | Resolve by title |
| `issues_assign` | Assign to collaborator |
| `issues_what_next` | Get recommendation |
### Collaboration
| Tool | Description |
|------|-------------|
| `project_share` | Share project by email |
| `collaborators_list` | List collaborators |
### Snapshots & Export
| Tool | Description |
|------|-------------|
| `memory_snapshot_create` | Create a backup |
| `memory_snapshot_list` | List all snapshots |
| `memory_snapshot_restore` | Restore from backup |
| `memory_snapshot_delete` | Delete a snapshot |
| `memory_export` | Export to JSON/MD/CSV |
| `memory_import` | Import from file |
### Utility
| Tool | Description |
|------|-------------|
| `memory_stats` | View usage statistics |
| `memory_relate` | Link two items |
| `memory_help` | Show help |
---
## 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):
| Tool | What it does |
|------|--------------|
| `session_update` | Declare what this session is working on ("working on the auth module") |
| `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) |
| `session_end` | Explicitly end this session's presence (also automatic on exit) |
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
| Variable | Required | Description |
|----------|----------|-------------|
| `CONTEXTFORGE_API_KEY` | Yes | Your API key from the dashboard |
| `CONTEXTFORGE_API_URL` | No | API endpoint (defaults to production) |
| `CONTEXTFORGE_DEFAULT_SPACE` | No | Default space for operations |
| `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. |
---
## 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](https://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
```bash
# 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](https://github.com/alfredoizdev/contextforge-mcp)**.
---
## Support
- 📖 [Documentation](https://contextforge.dev/docs)
- 🐛 [Report Issues](https://github.com/alfredoizdev/contextforge-mcp/issues)
- 💬 Questions: support@contextforge.app
---
## License
MIT © [Alfredo Izquierdo](https://github.com/alfredoizdev)