Context Portal 实现原理

[Pines-Cheng]

Context Portal MCP (ConPort) - 一个基于数据库的模型上下文协议(MCP)服务器，主要用于管理结构化的项目上下文。

主要功能

ConPort 是你项目的"记忆银行"，它帮助AI助手更好地理解你的特定软件项目，通过结构化的方式存储重要信息，如：

• 项目决策、进度和系统设计
• 自定义项目数据（如术语表或规范）
• 智能搜索项目相关信息
• RAG支持（检索增强生成）让AI能基于项目上下文给出更准确的回答

核心特性

1. 结构化存储：使用SQLite数据库（每个工作空间一个数据库）
2. 多工作空间支持：通过workspace_id管理
3. 语义搜索：支持向量数据存储和语义搜索
4. 项目知识图谱：构建项目特定的知识图谱，捕获实体间的关系
5. MCP集成：作为MCP服务器与各种IDE和AI助手集成

支持的IDE和工具

• Roo Code
• CLine
• Windsurf Cascade
• Cursor IDE

主要工具类别

• 产品上下文管理
• 活跃上下文管理
• 决策日志
• 进度跟踪
• 系统模式管理
• 自定义数据管理
• 上下文链接
• 导入/导出功能

这个工具的目标是替代基于文件的上下文管理系统，提供更可靠和可查询的数据库后端，让AI助手能够访问精确、最新的项目信息，从而提供更有上下文感知的准确回答。

Context Portal (ConPort) 确实是一个 RAG 平台。

RAG 核心功能

ConPort 专门设计为支持检索增强生成 (Retrieval Augmented Generation) 的后端系统： 1

• 项目知识图谱构建：存储决策、进度、系统模式等结构化项目上下文 2
• 向量嵌入和语义搜索：为关键文本内容生成向量嵌入，支持基于语义相似性的搜索 3
• RAG 后端服务：为 AI 助手提供精确、可查询的项目记忆 4

多层次检索能力

ConPort 实现了多种搜索策略来支持不同的 RAG 用例： 5

• 全文搜索 (FTS)：使用 SQLite FTS5 进行关键词匹配
• 语义搜索：通过 ChromaDB 向量存储进行概念相似性搜索 6
• 知识图谱遍历：通过 get_linked_items 工具探索实体关系
• 直接检索：基于主键的特定实体获取

RAG 工作流集成

系统包含专门的 RAG 检索指导，定义了动态上下文检索的步骤： 7

1. 查询分析：识别关键实体、概念和所需信息类型
2. 优先检索策略：选择最合适的 ConPort 工具进行搜索
3. 上下文扩展：使用链接项目获取相关上下文
4. 合成过滤：构建简洁、高度相关的上下文集

向量存储实现

ConPort 使用 ChromaDB 作为向量存储后端： 8

向量数据存储在每个工作空间的 context_portal/conport_vector_data/ 目录中，与 SQLite 数据库并行管理。 9

Notes

ConPort 不仅仅是一个通用的 RAG 平台，而是专门为软件开发项目设计的结构化知识管理系统。它通过 MCP (Model Context Protocol) 协议与 AI 助手集成，提供了约 30 个专门的工具来管理项目上下文、决策记录、进度跟踪等开发相关的知识实体。

Wiki pages you might want to explore:

• Context Portal Overview (GreatScottyMac/context-portal)
• IDE-Specific Strategies (GreatScottyMac/context-portal)
• Specialized Workflows (GreatScottyMac/context-portal)

Citations

File: README.md (L36-36)

ConPort provides a robust and structured way for AI assistants to store, retrieve, and manage various types of project context. It effectively builds a **project-specific knowledge graph**, capturing entities like decisions, progress, and architecture, along with their relationships. This structured knowledge base, enhanced by **vector embeddings** for semantic search, then serves as a powerful backend for **Retrieval Augmented Generation (RAG)**, enabling AI assistants to access precise, up-to-date information for more context-aware and accurate responses.

File: README.md (L47-47)

- Enables building a dynamic **project knowledge graph** with explicit relationships between context items.

File: README.md (L48-48)

- Includes **vector data storage** and **semantic search** capabilities to power advanced RAG.

File: README.md (L49-49)

- Serves as an ideal backend for **Retrieval Augmented Generation (RAG)**, providing AI with precise, queryable project memory.

File: conport_mcp_deep_dive.md (L23-24)

*   **Vector Embeddings & Semantic Search:** ConPort generates and stores vector embeddings for key text content within various entities, enabling semantic similarity search.
*   **RAG Enablement:** The system is designed to be a core component for Retrieval Augmented Generation (RAG) workflows. Its rich querying capabilities (FTS, semantic search, direct retrieval, graph traversal) allow AI agents to fetch relevant context to augment their generative tasks, leading to more accurate and grounded outputs.

File: src/context_portal_mcp/handlers/mcp_handlers.py (L644-648)

async def handle_semantic_search_conport(args: models.SemanticSearchConportArgs) -> List[Dict[str, Any]]:
    """
    Handles the 'semantic_search_conport' MCP tool.
    Performs a semantic search using embeddings and vector store, with optional metadata filters.
    """

File: conport-custom-instructions/roo_code_conport_strategy (L305-310)

  dynamic_context_retrieval_for_rag:
    description: |
      Guidance for dynamically retrieving and assembling context from ConPort to answer user queries or perform tasks,
      enhancing Retrieval Augmented Generation (RAG) capabilities.
    trigger: "When the AI needs to answer a specific question, perform a task requiring detailed project knowledge, or generate content based on ConPort data."
    goal: "To construct a concise, highly relevant context set for the LLM, improving the accuracy and relevance of its responses."

File: src/context_portal_mcp/db/vector_store_service.py (L52-55)

    # Path for ChromaDB persistence.
    # It will be located at: [workspace_id]/context_portal/conport_vector_data/
    # This aligns with the SQLite DB being in [workspace_id]/context_portal/context.db
    # workspace_id is assumed to be the root path of the user's project.

File: src/context_portal_mcp/db/vector_store_service.py (L62-62)

    vector_db_path = os.path.join(context_portal_base_dir, "conport_vector_data") # No leading dot, and inside context_portal

[Pines-Cheng]

工具列表

根据代码库中的定义，ConPort 提供了 31 个专门的 MCP 工具。 1

工具分类

上下文管理工具 (4个)

• get_product_context - 获取项目整体目标和架构 2
• update_product_context - 更新产品上下文 3
• get_active_context - 获取当前工作焦点 4
• update_active_context - 更新活跃上下文 5

决策记录工具 (4个)

• log_decision - 记录架构或实现决策 6
• get_decisions - 检索已记录的决策 7
• search_decisions_fts - 全文搜索决策内容 8
• delete_decision_by_id - 按ID删除决策 9

进度跟踪工具 (4个)

• log_progress - 记录任务进度 10
• get_progress - 获取进度条目 11
• update_progress - 更新现有进度条目 12
• delete_progress_by_id - 按ID删除进度条目 13

系统模式管理工具 (3个)

• log_system_pattern - 记录系统/编码模式 14
• get_system_patterns - 检索系统模式 15
• delete_system_pattern_by_id - 按ID删除系统模式 16

自定义数据管理工具 (5个)

• log_custom_data - 存储自定义键值数据 17
• get_custom_data - 检索自定义数据 18
• delete_custom_data - 删除自定义数据条目 19
• search_project_glossary_fts - 在项目词汇表中全文搜索 20
• search_custom_data_value_fts - 在所有自定义数据中全文搜索 21

知识图谱工具 (2个)

• link_conport_items - 在ConPort项目间创建关系链接 22
• get_linked_items - 检索与特定项目相关的链接项目 23

历史和元数据工具 (3个)

• get_item_history - 检索产品或活跃上下文的版本历史 24
• get_recent_activity_summary - 提供最近ConPort活动摘要 25
• get_conport_schema - 检索可用ConPort工具的模式 26

导入导出工具 (2个)

• export_conport_to_markdown - 将ConPort数据导出为markdown文件 27
• import_markdown_to_conport - 从markdown文件导入数据到ConPort 28

批量操作和语义搜索工具 (2个)

• batch_log_items - 批量记录同类型的多个项目 29
• semantic_search_conport - 基于语义相似性的搜索 30

Notes

这些工具都在 TOOL_ARG_MODELS 字典中定义，每个工具都有对应的 Pydantic 模型来验证参数。 31 所有工具都需要 workspace_id 参数来确保操作在正确的项目上下文中执行。

Wiki pages you might want to explore:

• Context Portal Overview (GreatScottyMac/context-portal)
• Knowledge Graph Structure (GreatScottyMac/context-portal)
• AI Agent Integration (GreatScottyMac/context-portal)

Citations

File: src/context_portal_mcp/db/models.py (L360-361)

# Dictionary mapping tool names to their expected argument models (for potential future use/validation)
# Note: The primary validation happens in the handler using these models.

File: src/context_portal_mcp/db/models.py (L362-392)

TOOL_ARG_MODELS = {
    "get_product_context": GetContextArgs,
    "update_product_context": UpdateContextArgs,
    "get_active_context": GetContextArgs,
    "update_active_context": UpdateContextArgs,
    "log_decision": LogDecisionArgs,
    "get_decisions": GetDecisionsArgs,
    "search_decisions_fts": SearchDecisionsArgs,
    "delete_decision_by_id": DeleteDecisionByIdArgs,
    "log_progress": LogProgressArgs,
    "get_progress": GetProgressArgs,
    "log_system_pattern": LogSystemPatternArgs,
    "get_system_patterns": GetSystemPatternsArgs,
    "delete_system_pattern_by_id": DeleteSystemPatternByIdArgs,
    "log_custom_data": LogCustomDataArgs,
    "get_custom_data": GetCustomDataArgs,
    "delete_custom_data": DeleteCustomDataArgs,
    "search_custom_data_value_fts": SearchCustomDataValueArgs,
    "search_project_glossary_fts": SearchProjectGlossaryArgs,
    "export_conport_to_markdown": ExportConportToMarkdownArgs,
    "import_markdown_to_conport": ImportMarkdownToConportArgs,
    "link_conport_items": LinkConportItemsArgs,
    "get_linked_items": GetLinkedItemsArgs,
    "batch_log_items": BatchLogItemsArgs,
    "get_item_history": GetItemHistoryArgs,
    "get_conport_schema": GetConportSchemaArgs,
    "get_recent_activity_summary": GetRecentActivitySummaryArgs,
    "semantic_search_conport": SemanticSearchConportArgs, # New tool
    "update_progress": UpdateProgressArgs, # New tool
    "delete_progress_by_id": DeleteProgressByIdArgs, # New tool
}

File: README.md (L299-300)

  - `get_product_context`: Retrieves the overall project goals, features, and architecture.
  - `update_product_context`: Updates the product context. Accepts full `content` (object) or `patch_content` (object) for partial updates (use `__DELETE__` as a value in patch to remove a key).

File: README.md (L302-302)

  - `get_active_context`: Retrieves the current working focus, recent changes, and open issues.

File: README.md (L303-303)

  - `update_active_context`: Updates the active context. Accepts full `content` (object) or `patch_content` (object) for partial updates (use `__DELETE__` as a value in patch to remove a key).

File: README.md (L305-306)

  - `log_decision`: Logs an architectural or implementation decision.
    - Args: `summary` (str, req), `rationale` (str, opt), `implementation_details` (str, opt), `tags` (list[str], opt).

File: README.md (L307-308)

  - `get_decisions`: Retrieves logged decisions.
    - Args: `limit` (int, opt), `tags_filter_include_all` (list[str], opt), `tags_filter_include_any` (list[str], opt).

File: README.md (L309-310)

  - `search_decisions_fts`: Full-text search across decision fields (summary, rationale, details, tags).
    - Args: `query_term` (str, req), `limit` (int, opt).

File: README.md (L311-312)

  - `delete_decision_by_id`: Deletes a decision by its ID.
    - Args: `decision_id` (int, req).

File: README.md (L314-315)

  - `log_progress`: Logs a progress entry or task status.
    - Args: `status` (str, req), `description` (str, req), `parent_id` (int, opt), `linked_item_type` (str, opt), `linked_item_id` (str, opt).

File: README.md (L316-317)

  - `get_progress`: Retrieves progress entries.
    - Args: `status_filter` (str, opt), `parent_id_filter` (int, opt), `limit` (int, opt).

File: README.md (L318-319)

  - `update_progress`: Updates an existing progress entry.
    - Args: `progress_id` (int, req), `status` (str, opt), `description` (str, opt), `parent_id` (int, opt).

File: README.md (L320-321)

  - `delete_progress_by_id`: Deletes a progress entry by its ID.
    - Args: `progress_id` (int, req).

File: README.md (L323-324)

  - `log_system_pattern`: Logs or updates a system/coding pattern.
    - Args: `name` (str, req), `description` (str, opt), `tags` (list[str], opt).

File: README.md (L325-326)

  - `get_system_patterns`: Retrieves system patterns.
    - Args: `tags_filter_include_all` (list[str], opt), `tags_filter_include_any` (list[str], opt).

File: README.md (L327-328)

  - `delete_system_pattern_by_id`: Deletes a system pattern by its ID.
    - Args: `pattern_id` (int, req).

File: README.md (L330-331)

  - `log_custom_data`: Stores/updates a custom key-value entry under a category. Value is JSON-serializable.
    - Args: `category` (str, req), `key` (str, req), `value` (any, req).

File: README.md (L332-333)

  - `get_custom_data`: Retrieves custom data.
    - Args: `category` (str, opt), `key` (str, opt).

File: README.md (L334-335)

  - `delete_custom_data`: Deletes a specific custom data entry.
    - Args: `category` (str, req), `key` (str, req).

File: README.md (L336-337)

  - `search_project_glossary_fts`: Full-text search within the 'ProjectGlossary' custom data category.
    - Args: `query_term` (str, req), `limit` (int, opt).

File: README.md (L338-339)

  - `search_custom_data_value_fts`: Full-text search across all custom data values, categories, and keys.
    - Args: `query_term` (str, req), `category_filter` (str, opt), `limit` (int, opt).

File: README.md (L341-342)

  - `link_conport_items`: Creates a relationship link between two ConPort items, explicitly building out the **project knowledge graph**.
    - Args: `source_item_type` (str, req), `source_item_id` (str, req), `target_item_type` (str, req), `target_item_id` (str, req), `relationship_type` (str, req), `description` (str, opt).

File: README.md (L343-344)

  - `get_linked_items`: Retrieves items linked to a specific item.
    - Args: `item_type` (str, req), `item_id` (str, req), `relationship_type_filter` (str, opt), `linked_item_type_filter` (str, opt), `limit` (int, opt).

File: README.md (L346-347)

  - `get_item_history`: Retrieves version history for Product or Active Context.
    - Args: `item_type` ("product_context" | "active_context", req), `version` (int, opt), `before_timestamp` (datetime, opt), `after_timestamp` (datetime, opt), `limit` (int, opt).

File: README.md (L348-349)

  - `get_recent_activity_summary`: Provides a summary of recent ConPort activity.
    - Args: `hours_ago` (int, opt), `since_timestamp` (datetime, opt), `limit_per_type` (int, opt, default: 5).

File: README.md (L350-350)

  - `get_conport_schema`: Retrieves the schema of available ConPort tools and their arguments.

File: README.md (L352-353)

  - `export_conport_to_markdown`: Exports ConPort data to markdown files.
    - Args: `output_path` (str, opt, default: "./conport_export/").

File: README.md (L354-355)

  - `import_markdown_to_conport`: Imports data from markdown files into ConPort.
    - Args: `input_path` (str, opt, default: "./conport_export/").

File: README.md (L357-358)

  - `batch_log_items`: Logs multiple items of the same type (e.g., decisions, progress entries) in a single call.
    - Args: `item_type` (str, req - e.g., "decision", "progress_entry"), `items` (list[dict], req - list of Pydantic model dicts for the item type).

[Pines-Cheng]

在动态上下文检索中，ConPort 提供了一个结构化的工具选择策略，基于查询分析来选择最合适的搜索工具。

优先检索策略

ConPort 的动态上下文检索遵循一个明确的工具选择层次结构： 1

1. 目标导向的全文搜索 (FTS)

当查询中包含明确的关键词时，优先使用：

• search_decisions_fts - 搜索决策内容
• search_custom_data_value_fts - 搜索自定义数据值
• search_project_glossary_fts - 搜索项目词汇表 2

2. 特定项目检索

当查询指向特定的项目类型或ID时，使用：

• get_custom_data - 已知类别/键的情况下
• get_decisions - 按ID或获取最近项目
• get_system_patterns - 获取系统模式
• get_progress - 获取进度条目 3

3. 语义搜索 (概念查询)

对于需要概念理解的复杂查询，使用 semantic_search_conport： 4

该工具支持多种过滤选项：

• filter_item_types - 按项目类型过滤
• filter_tags_include_any/all - 按标签过滤
• filter_custom_data_categories - 按自定义数据类别过滤 5

4. 广泛上下文 (回退策略)

当目标检索结果不足时，使用：

• get_product_context - 获取产品整体上下文
• get_active_context - 获取当前活跃上下文

但需要注意这些工具返回的数据量较大。 6

上下文扩展策略

检索到初始结果后，可以使用 get_linked_items 进行1跳扩展，获取相关联的项目以提供更完整的上下文。 7

一般原则

ConPort 的检索策略遵循以下原则：

• 优先使用目标检索而非广泛的上下文转储
• 如果初始检索不足，尝试不同的关键词或工具
• 平衡上下文丰富性与提示令牌限制 8

Notes

这个工具选择策略在所有 ConPort 策略文件中都是一致的，包括 cascade_conport_strategy、cline_conport_strategy 和 roo_code_conport_strategy，确保了跨不同 IDE 环境的统一行为。策略的核心目标是构建简洁、高度相关的上下文集，以提高 LLM 响应的准确性和相关性。

Wiki pages you might want to explore:

• AI Agent Integration (GreatScottyMac/context-portal)
• IDE-Specific Strategies (GreatScottyMac/context-portal)

Citations

File: conport-custom-instructions/generic_conport_strategy (L312-322)

        action: "Prioritized Retrieval Strategy"
        details: |
          Based on the analysis, select the most appropriate ConPort tools:
          - **Targeted FTS:** Use `search_decisions_fts`, `search_custom_data_value_fts`, `search_project_glossary_fts` for keyword-based searches if specific terms are evident.
          - **Specific Item Retrieval:** Use `get_custom_data` (if category/key known), `get_decisions` (by ID or for recent items), `get_system_patterns`, `get_progress` if the query points to specific item types or IDs.
          - **(Future):** Prioritize semantic search tools once available for conceptual queries.
          - **Broad Context (Fallback):** Use `get_product_context` or `get_active_context` as a fallback if targeted retrieval yields little, but be mindful of their size.
      - step: 3
        action: "Retrieve Initial Set"
        details: "Execute the chosen tool(s) to retrieve an initial, small set (e.g., top 3-5) of the most relevant items or data snippets."
      - step: 4

File: conport-custom-instructions/generic_conport_strategy (L324-324)

        details: "For the most promising items from Step 3, consider using `get_linked_items` to fetch directly related items (1-hop). This can provide crucial context or disambiguation. Use judiciously to avoid excessive data."

File: conport-custom-instructions/generic_conport_strategy (L339-341)

      - "Prefer targeted retrieval over broad context dumps."
      - "Iterate if initial retrieval is insufficient: try different keywords or tools."
      - "Balance context richness with prompt token limits."

File: src/context_portal_mcp/handlers/mcp_handlers.py (L644-647)

async def handle_semantic_search_conport(args: models.SemanticSearchConportArgs) -> List[Dict[str, Any]]:
    """
    Handles the 'semantic_search_conport' MCP tool.
    Performs a semantic search using embeddings and vector store, with optional metadata filters.

File: src/context_portal_mcp/db/models.py (L339-342)

    filter_item_types: Optional[List[str]] = Field(default=None, description="Optional list of item types to filter by (e.g., ['decision', 'custom_data']). Valid types: 'decision', 'system_pattern', 'custom_data', 'progress_entry'.")
    filter_tags_include_any: Optional[List[str]] = Field(default=None, description="Optional list of tags; results will include items matching any of these tags.")
    filter_tags_include_all: Optional[List[str]] = Field(default=None, description="Optional list of tags; results will include only items matching all of these tags.")
    filter_custom_data_categories: Optional[List[str]] = Field(default=None, description="Optional list of categories to filter by if 'custom_data' is in filter_item_types.")

[Pines-Cheng]

你询问的是如何在 ConPort 中构建知识库。

知识库构建方式

ConPort 提供了多种方式来构建项目知识库：

1. 初始化项目上下文

首先通过 projectBrief.md 文件自动导入项目基础信息： 1

AI 助手会自动检测并提示导入该文件到产品上下文中。 2

2. 结构化数据录入

ConPort 支持多种类型的结构化数据录入：

决策记录

使用 log_decision 工具记录架构和实现决策： 3

进度跟踪

通过 log_progress 记录任务状态和进度： 4

系统模式

使用 log_system_pattern 记录设计模式和架构模式： 5

自定义数据

通过 log_custom_data 存储项目词汇表、规范文档等： 6

3. 批量数据导入

对于大量同类型数据，可以使用 batch_log_items 进行批量录入： 7

也可以通过 import_markdown_to_conport 从 markdown 文件批量导入： 8

4. 知识图谱构建

使用 link_conport_items 在不同知识实体间建立关系链接： 9

AI 助手会主动识别对话中的潜在关系并建议创建链接： 10

5. 自动向量化

ConPort 会自动为关键内容生成向量嵌入，支持语义搜索： 11

向量数据存储在 ChromaDB 中，与 SQLite 数据库并行管理。 12

数据存储结构

知识库数据存储在工作空间的 context_portal/context.db SQLite 数据库中： 13

包含以下核心数据实体： 14

Notes

ConPort 的知识库构建是一个渐进式过程，通过 AI 助手的主动建议和用户的持续录入，逐步建立起完整的项目知识图谱。系统会自动处理向量化、索引和关系管理，用户只需专注于内容的录入和组织。

Wiki pages you might want to explore:

• Context Portal Overview (GreatScottyMac/context-portal)
• AI Agent Integration (GreatScottyMac/context-portal)

Citations

File: README.md (L271-283)

### Using a `projectBrief.md` File (Recommended)

1.  **Create `projectBrief.md`:** In the root directory of your project workspace, create a file named `projectBrief.md`.
2.  **Add Content:** Populate this file with a high-level overview of your project. This could include:
    - The main goal or purpose of the project.
    - Key features or components.
    - Target audience or users.
    - Overall architectural style or key technologies (if known).
    - Any other foundational information that defines the project.
3.  **Automatic Prompt for Import:** When an LLM agent using one of the provided ConPort custom instruction sets (e.g., `roo_code_conport_strategy`) initializes in the workspace, it is designed to:
    - Check for the existence of `projectBrief.md`.
    - If found, it will read the file and ask you if you'd like to import its content into the ConPort **Product Context**.
    - If you agree, the content will be added to ConPort, providing an immediate baseline for the project's Product Context.

File: README.md (L304-306)

- **Decision Logging:**
  - `log_decision`: Logs an architectural or implementation decision.
    - Args: `summary` (str, req), `rationale` (str, opt), `implementation_details` (str, opt), `tags` (list[str], opt).

File: README.md (L313-315)

- **Progress Tracking:**
  - `log_progress`: Logs a progress entry or task status.
    - Args: `status` (str, req), `description` (str, req), `parent_id` (int, opt), `linked_item_type` (str, opt), `linked_item_id` (str, opt).

File: README.md (L322-324)

- **System Pattern Management:**
  - `log_system_pattern`: Logs or updates a system/coding pattern.
    - Args: `name` (str, req), `description` (str, opt), `tags` (list[str], opt).

File: README.md (L329-331)

- **Custom Data Management:**
  - `log_custom_data`: Stores/updates a custom key-value entry under a category. Value is JSON-serializable.
    - Args: `category` (str, req), `key` (str, req), `value` (any, req).

File: README.md (L340-342)

- **Context Linking:**
  - `link_conport_items`: Creates a relationship link between two ConPort items, explicitly building out the **project knowledge graph**.
    - Args: `source_item_type` (str, req), `source_item_id` (str, req), `target_item_type` (str, req), `target_item_id` (str, req), `relationship_type` (str, req), `description` (str, opt).

File: README.md (L353-355)

    - Args: `output_path` (str, opt, default: "./conport_export/").
  - `import_markdown_to_conport`: Imports data from markdown files into ConPort.
    - Args: `input_path` (str, opt, default: "./conport_export/").

File: README.md (L356-358)

- **Batch Operations:**
  - `batch_log_items`: Logs multiple items of the same type (e.g., decisions, progress entries) in a single call.
    - Args: `item_type` (str, req - e.g., "decision", "progress_entry"), `items` (list[dict], req - list of Pydantic model dicts for the item type).

File: conport-custom-instructions/generic_conport_strategy (L343-348)

  proactive_knowledge_graph_linking:
    description: |
      Guidance for the AI to proactively identify and suggest the creation of links between ConPort items,
      enriching the project's knowledge graph based on conversational context.
    trigger: "During ongoing conversation, when the AI observes potential relationships (e.g., causal, implementational, clarifying) between two or more discussed ConPort items or concepts that are likely represented as ConPort items."
    goal: "To actively build and maintain a rich, interconnected knowledge graph within ConPort by capturing relationships that might otherwise be missed."

File: RELEASE_NOTES.md (L353-356)

*   **Automatic Embedding Generation**:
    *   Key ConPort items (Decisions, Progress Entries, System Patterns, and text-based Custom Data) now automatically have embeddings generated and stored when they are logged.
    *   This powers the semantic search and enables future AI-driven insights.
    *   Utilizes the `all-MiniLM-L6-v2` model for generating embeddings, ensuring consistency.

File: RELEASE_NOTES.md (L358-360)

*   **Integrated Vector Store (ChromaDB)**:
    *   Embeddings are stored in a local ChromaDB vector database, managed per workspace within the `.conport_vector_data` directory.
    *   The system now explicitly configures ChromaDB to use the project's defined embedding model, enhancing consistency and reliability.

File: conport_mcp_deep_dive.md (L29-117)

1.  **Product Context (`product_context`)**
    *   **Purpose:** Stores high-level, relatively static information about the project (e.g., overall goals, architecture, key features).
    *   **Schema:** Single row table.
        *   `id` (INTEGER, PK, fixed at 1)
        *   `content` (TEXT): Stores a JSON string representing a dictionary of product context information.
    *   **History:** Changes are versioned in `product_context_history`.

2.  **Active Context (`active_context`)**
    *   **Purpose:** Stores dynamic, short-term context relevant to the current task or session (e.g., current focus, recent changes, open questions, next steps).
    *   **Schema:** Single row table.
        *   `id` (INTEGER, PK, fixed at 1)
        *   `content` (TEXT): Stores a JSON string representing a dictionary of active context information.
    *   **History:** Changes are versioned in `active_context_history`.

3.  **Decisions (`decisions`)**
    *   **Purpose:** Logs significant architectural or implementation decisions made during the project.
    *   **Schema:**
        *   `id` (INTEGER, PK, AUTOINCREMENT)
        *   `timestamp` (TIMESTAMP): When the decision was logged.
        *   `summary` (TEXT, NOT NULL): Concise summary of the decision.
        *   `rationale` (TEXT): Reasoning behind the decision.
        *   `implementation_details` (TEXT): How the decision will be/was implemented.
        *   `tags` (TEXT): JSON stringified list of tags for categorization.
    *   **Search:** Supported by an FTS5 virtual table `decisions_fts` (searches summary, rationale, implementation_details, tags).

4.  **Progress Entries (`progress_entries`)**
    *   **Purpose:** Tracks tasks, their status, and hierarchy.
    *   **Schema:**
        *   `id` (INTEGER, PK, AUTOINCREMENT)
        *   `timestamp` (TIMESTAMP): When the progress entry was logged/updated.
        *   `status` (TEXT, NOT NULL): e.g., "TODO", "IN_PROGRESS", "DONE".
        *   `description` (TEXT, NOT NULL): Description of the task or progress.
        *   `parent_id` (INTEGER, FK to `progress_entries.id`): For subtasks.

5.  **System Patterns (`system_patterns`)**
    *   **Purpose:** Documents recurring architectural or design patterns observed or used in the project.
    *   **Schema:**
        *   `id` (INTEGER, PK, AUTOINCREMENT)
        *   `name` (TEXT, UNIQUE, NOT NULL): Unique name for the pattern.
        *   `description` (TEXT): Description of the pattern.
        *   `tags` (TEXT): JSON stringified list of tags.

6.  **Custom Data (`custom_data`)**
    *   **Purpose:** Stores arbitrary key-value data, categorized by the user. Useful for project glossaries, configuration snippets, notes, etc.
    *   **Schema:**
        *   `id` (INTEGER, PK, AUTOINCREMENT)
        *   `category` (TEXT, NOT NULL)
        *   `key` (TEXT, NOT NULL): Unique within its category.
        *   `value` (TEXT): Stores a JSON string representing the arbitrary data.
    *   **Search:** Supported by an FTS5 virtual table `custom_data_fts` (searches category, key, and the text content of the value).

7.  **Context Links (`context_links`)**
    *   **Purpose:** Establishes explicit, queryable relationships between different ConPort data entities (e.g., a decision is implemented by a system pattern, a progress item tracks a decision), forming the edges of the **project knowledge graph**.
    *   **Schema:**
        *   `id` (INTEGER, PK, AUTOINCREMENT)
        *   `timestamp` (TIMESTAMP): When the link was created.
        *   `workspace_id` (TEXT, NOT NULL): The workspace this link belongs to.
        *   `source_item_type` (TEXT, NOT NULL): Type of the source item (e.g., "decision").
        *   `source_item_id` (TEXT, NOT NULL): ID/key of the source item.
        *   `target_item_type` (TEXT, NOT NULL): Type of the target item.
        *   `target_item_id` (TEXT, NOT NULL): ID/key of the target item.
        *   `relationship_type` (TEXT, NOT NULL): Nature of the link (e.g., "implements", "related_to").
        *   `description` (TEXT): Optional description for the link itself.

8.  **Context History (`product_context_history`, `active_context_history`)**
    *   **Purpose:** Tracks changes over time to Product Context and Active Context.
    *   **Schema (for each history table):**
        *   `id` (INTEGER, PK, AUTOINCREMENT)
        *   `timestamp` (TIMESTAMP): When this historical version was saved.
        *   `version` (INTEGER, NOT NULL): Version number for the context.
        *   `content` (TEXT, NOT NULL): The JSON string content of the context at this version.
        *   `change_source` (TEXT): Brief description of what triggered the change (e.g., tool name).

9. **Vector Store (ChromaDB)**
    *   **Purpose:** Stores vector embeddings generated from text content of various ConPort entities (Decisions, Progress, Custom Data, etc.) to enable semantic similarity search.
    *   **Location:** Stored on disk within the workspace's ConPort data directory, separate from the SQLite file but managed alongside it.
    *   **Integration:** Linked to SQLite data via item type and ID metadata stored alongside the vectors.

9. **Vector Store (ChromaDB)**
    *   **Purpose:** Stores vector embeddings generated from text content of various ConPort entities (Decisions, Progress, Custom Data, etc.) to enable semantic similarity search.
    *   **Location:** Stored on disk within the workspace's ConPort data directory, separate from the SQLite file but managed alongside it.
    *   **Integration:** Linked to SQLite data via item type and ID metadata stored alongside the vectors.

9. **Vector Store (ChromaDB)**
    *   **Purpose:** Stores vector embeddings generated from text content of various ConPort entities (Decisions, Progress, Custom Data, etc.) to enable semantic similarity search.
    *   **Location:** Stored on disk within the workspace's ConPort data directory, separate from the SQLite file but managed alongside it.
    *   **Integration:** Linked to SQLite data via item type and ID metadata stored alongside the vectors.

Pydantic models defined in `src/context_portal_mcp/db/models.py` mirror these table structures and are used for data validation and serialization/deserialization within the server.

File: conport_mcp_deep_dive.md (L426-429)

### 4.4 Database Location
The SQLite database file for each workspace is typically created at:
`<workspace_id>/context_portal/context.db`
This path is determined by the `get_database_path` function in `core/config.py`.

[Pines-Cheng]

这是一个很好的问题！ConPort通过几种机制帮助Agent合理调用这28个工具：

1. 自定义指令策略

ConPort提供了针对不同AI平台的策略文件：

• cascade_conport_strategy - 针对Windsurf Cascade
• cline_conport_strategy - 针对CLine
• generic_conport_strategy - 通用策略

这些策略文件教会Agent：

• 何时使用哪些工具
• 为什么要记录特定类型的信息
• 如何构建项目知识图谱

2. 工具发现机制

# Agent可以动态获取工具schema
get_conport_schema()  # 返回所有可用工具及其参数

Agent不需要硬编码工具名称，而是动态发现可用功能。

3. 语义化的工具分组

工具按功能逻辑分组，Agent可以根据上下文选择：

• 讨论架构 → log_decision
• 跟踪任务 → log_progress
• 存储术语 → log_custom_data
• 建立关联 → link_conport_items

4. 渐进式使用模式

Agent通常遵循这样的调用模式：

# 1. 初始化时加载上下文
get_product_context()
get_active_context()

# 2. 对话中增量更新
log_decision()  # 记录重要决策
update_active_context()  # 更新当前状态

# 3. 需要时搜索历史
search_decisions_fts("database")
get_recent_activity_summary()

5. 智能过滤和搜索

Agent不需要记住所有历史，而是通过搜索工具按需获取：

• 全文搜索找相关决策
• 标签过滤找特定类型信息
• 链接查询找关联项目

这种设计让Agent能够智能地而不是机械地使用这些工具，就像人类开发者管理项目知识一样。

[Pines-Cheng]

基于你查看的cascade_conport_strategy_compact文件，ConPort的知识图谱构建采用了主动链接和关系推理的方式：

知识图谱构建机制

1. 核心链接表结构

context_links表：
- source_item_type (源项目类型)
- source_item_id (源项目ID)  
- target_item_type (目标项目类型)
- target_item_id (目标项目ID)
- relationship_type (关系类型)
- description (关系描述)

2. 主动关系检测

从策略文件可以看到Agent会：

proactive_knowledge_graph_linking:
  trigger: "对话中暗示ConPort项目间存在关系时"
  steps:
    - "监控项目提及(按ID/名称)和隐含关系"
    - "检测强候选关系(如：决策→进度实现；模式解决决策问题)"

3. 智能关系推理

Agent能识别这些关系类型：

• implements - 实现关系
• related_to - 相关关系
• tracks - 跟踪关系
• blocks - 阻塞关系
• clarifies - 澄清关系
• depends_on - 依赖关系
• resolves - 解决关系
• derived_from - 派生关系

4. 构建流程

1. 对话监听：Agent在对话中识别项目间的关系暗示
2. 候选检测：发现强关系候选（如决策导致进度任务）
3. 用户确认：提议链接并请求确认关系类型
4. 创建链接：调用link_conport_items建立正式关系

5. 图谱查询

• get_linked_items - 获取与特定项目相关的所有链接
• 支持关系类型过滤和链接项目类型过滤
• 可以进行"1-hop扩展"发现间接关系

6. 实际应用场景

• 决策追踪：决策→实现进度→相关代码模式
• 问题解决链：问题→解决方案→实现细节
• 架构演进：旧模式→新决策→新模式

这种设计让ConPort不仅仅是信息存储，而是真正构建了项目知识的语义网络，Agent可以通过关系链发现相关信息，提供更智能的上下文感知。

[Pines-Cheng]

ConPort的知识图谱构建有以下重要作用和应用场景：

主要作用

1. 上下文关联发现

• 问题：开发过程中信息孤立，难以找到相关决策和实现
• 解决：通过关系链自动发现相关信息
• 示例：查看某个决策时，自动显示相关的进度任务、系统模式和问题解决方案

2. 项目知识传承

• 问题：项目历史和决策背景容易丢失
• 解决：构建决策→实现→结果的完整链路
• 示例：新团队成员可以通过关系链了解某个架构选择的完整演进过程

3. 智能推荐和提醒

• 问题：容易遗忘相关的历史决策和模式
• 解决：基于关系图提供智能建议
• 示例：讨论数据库设计时，自动提醒相关的性能决策和已有模式

核心应用场景

1. 架构决策追踪

架构决策 → 实现进度 → 代码模式 → 遇到问题 → 解决方案

帮助理解每个决策的完整生命周期

2. 问题解决链

问题记录 → 分析决策 → 实现方案 → 验证结果 → 经验总结

构建问题解决的知识库

3. 技术债务管理

临时方案 → 后续改进计划 → 重构决策 → 新架构模式

跟踪技术债务的演进和解决

4. 团队协作增强

• 代码审查：快速了解相关决策背景
• 需求分析：查看类似功能的历史实现
• 风险评估：基于历史关联预测潜在影响

解决的核心问题

1. 信息孤岛

传统文档系统中，决策、代码、问题各自独立，ConPort通过关系链将它们连接

2. 上下文丢失

开发过程中的"为什么这样做"经常丢失，知识图谱保持决策的完整上下文

3. 重复决策

避免重复讨论已解决的问题，通过关系链快速找到历史方案

4. 影响分析困难

修改某个组件时，难以评估对其他部分的影响，关系图提供依赖视图

这种知识图谱让AI助手能够提供更智能的建议，就像一个经验丰富的架构师一样，能够关联项目的各个方面。