LoginGet Started

项目关联

v0.1.21 新增

将本地目录关联到 ContextForge Projects，实现上下文自动过滤。

什么是项目关联？

项目关联在您的本地代码目录与云端 ContextForge Project 之间建立连接。关联后，所有记忆查询和操作将自动过滤到该 Project 的 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"

优势

精准查询

仅在相关 Spaces 中搜索，前端文档不会与后端笔记混淆。

自动上下文

无需手动指定项目，Claude 根据您所在的目录自动识别。

团队协作

团队成员可关联到同一个项目，共享知识库。

如何关联项目

第一步：列出可用 Projects

首先让 Claude 展示可用的 Projects：

# 在 Claude Code 中

"Link this project to ContextForge"

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

Claude 会展示可供选择的 Projects 列表。

第二步：关联到 Project

# 关联到已有项目

"Link this directory to project Frontend"

# 或创建新项目并关联

"Link this to a new project called Mobile App"

第三步：验证关联

"What project is linked to this directory?"

这将显示已关联的 Project 及其所有 Spaces。

.contextforge 文件

关联项目时，ContextForge 会在您的目录根路径创建 .contextforge 文件：

# .contextforge

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

提示：将 .contextforge 添加到 .gitignore 可避免与团队共享关联配置，或将其提交以让所有人使用同一个项目。

MCP 工具参考

memory_link_project新功能

将当前目录关联到 ContextForge Project。

参数

名称类型必填描述
project_namestring否要关联的 Project 名称。若不填则显示列表供选择。
create_newboolean否若为 true，则以指定名称创建新 Project。

# 示例响应

{
  "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_project新功能

显示当前已关联的 Project 及其 Spaces。

# 示例响应

{
  "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_project新功能

从当前目录移除项目关联，删除 .contextforge 文件。

# 示例响应

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

过滤机制

关联 Project 后，以下操作将自动过滤到该 Project 的 Spaces：

工具关联后的行为
memory_list_spaces仅显示已关联 Project 中的 Spaces
memory_query仅在已关联 Project 的 Spaces 中搜索
memory_create_space在已关联 Project 中创建新 Space
memory_ingest保存到已关联 Project 的 Spaces 中

注意：您可以通过显式指定 space_id 或 project_id 参数来覆盖自动过滤行为。

最佳实践

  • 1

    在项目根目录创建关联

    在项目根目录创建 .contextforge 文件，而非子目录中。

  • 2

    每个代码库对应一个 Project

    每个本地代码仓库应关联到一个 ContextForge Project。

  • 3

    保持名称一致

    ContextForge Project 与代码仓库使用相同名称，便于识别。

  • 4

    适用于 Monorepo

    对于 Monorepo，可将根目录关联到一个 Project，为每个包创建独立的 Space。