LoginGet Started

Project Linking

New in v0.1.21

Link your local directories to ContextForge projects for automatic context filtering.

What is Project Linking?

Project linking creates a connection between your local code directory and a ContextForge project in the cloud. When linked, all memory queries and operations automatically filter to that project's spaces.

Your Local Projects              ContextForge Cloud
─────────────────────            ──────────────────
~/code/frontend-app/             Project: "Frontend"
  └── .contextforge ──────────→  ├── Space: "Components"
                                 ├── Space: "State Management"
                                 └── Space: "UI Guidelines"

~/code/backend-api/              Project: "Backend"
  └── .contextforge ──────────→  ├── Space: "API Docs"
                                 └── Space: "Database Schema"

~/code/mobile-app/               Project: "Mobile"
  └── .contextforge ──────────→  └── Space: "React Native"

Benefits

Focused Queries

Search only in relevant spaces. No mixing frontend docs with backend notes.

Automatic Context

No need to specify which project to use. Claude knows based on your directory.

Team Collaboration

Team members can link to the same project and share knowledge.

How to Link a Project

Step 1: List Available Projects

First, ask Claude to show you available projects:

# In Claude Code

"Link this project to ContextForge"

# Or more specifically:
"What ContextForge projects do I have?"

Claude will show you available projects to choose from.

Step 2: Link to a Project

# Link to an existing project

"Link this directory to project Frontend"

# Or create a new project and link

"Link this to a new project called Mobile App"

Step 3: Verify the Link

"What project is linked to this directory?"

This will show you the linked project and all its spaces.

The .contextforge File

When you link a project, ContextForge creates a .contextforge file in your directory root:

# .contextforge

{
  "project_id": "abc-123-def-456",
  "project_name": "Frontend",
  "linked_at": "2026-01-15T10:30:00.000Z"
}

Tip: Add .contextforge to your .gitignore if you don't want to share the link with your team, or commit it if you want everyone to use the same project.

MCP Tool Reference

memory_link_projectNew

Link the current directory to a ContextForge project.

Parameters

NameTypeRequiredDescription
project_namestringNoName of project to link. Shows list if not provided.
create_newbooleanNoIf true, creates a new project with the given name.

# Example response

{
  "success": true,
  "linked": true,
  "project": {
    "id": "abc-123",
    "name": "Frontend",
    "slug": "frontend"
  },
  "config_file": "/Users/you/project/.contextforge",
  "message": "Project \"Frontend\" linked to this directory",
  "hint": "Queries will now be filtered to this project's spaces"
}
memory_current_projectNew

Show the currently linked project and its spaces.

# Example response

{
  "linked": true,
  "project": {
    "id": "abc-123",
    "name": "Frontend",
    "slug": "frontend",
    "space_count": 3
  },
  "spaces": [
    { "id": "...", "name": "Components", "slug": "components" },
    { "id": "...", "name": "State", "slug": "state" },
    { "id": "...", "name": "UI Guidelines", "slug": "ui-guidelines" }
  ],
  "config_file": "/Users/you/project/.contextforge",
  "message": "This directory is linked to project \"Frontend\" with 3 space(s)"
}
memory_unlink_projectNew

Remove the project link from this directory. Deletes the .contextforge file.

# Example response

{
  "success": true,
  "config_file": "/Users/you/project/.contextforge",
  "message": "Project unlinked from this directory",
  "hint": "Queries will now search all your spaces"
}

How Filtering Works

When a project is linked, these operations automatically filter to the project's spaces:

ToolBehavior When Linked
memory_list_spacesOnly shows spaces in the linked project
memory_querySearches only within the linked project's spaces
memory_create_spaceCreates new spaces in the linked project
memory_ingestSaves to spaces within the linked project

Note: You can always override the automatic filtering by explicitly specifying a space_id or project_id parameter.

Best Practices

  • 1

    Link at the project root

    Create the .contextforge file in your project's root directory, not in subdirectories.

  • 2

    One project per codebase

    Each local code repository should link to one ContextForge project.

  • 3

    Match project names

    Use the same name for your ContextForge project as your repository name for clarity.

  • 4

    Use with monorepos

    For monorepos, you can link the root to a project with multiple spaces (one per package).