Context Portal (ConPort)

Context Portal (ConPort) is a database-backed Model Context Protocol (MCP) server that acts as a "memory bank" for AI assistants. It allows AI tools (like Cursor, Windsurf, or Cline) to store and retrieve structured project context, such as architectural decisions, tasks, and system designs, in a project-specific knowledge graph.

Key capabilities include:

• Structured Storage: Uses SQLite (one database per workspace) to manage context more reliably than plain text files.
• Semantic Search: Uses vector embeddings to enable Retrieval Augmented Generation (RAG) via semantic search.
• Knowledge Graph: Captures explicit relationships between different context entities.
• Multi-workspace Support: Uses workspace_id to isolate context between different projects.
• Prompt Caching Support: Provides structured context that compatible LLM providers can leverage for efficient prompt caching.

Context Portal (ConPort) is a Model Context Protocol (MCP) server designed to provide AI assistants with structured, persistent, and workspace-specific project context. It functions as a knowledge graph and a backend for Retrieval Augmented Generation (RAG), allowing AI agents to query precise information about a software project rather than relying solely on file-based context.

Key features include:

• Workspace Isolation: Data is tied to a workspace_id (the project directory path), ensuring context remains relevant to the specific project.
• Knowledge Graph: Uses explicit relationships between entities (decisions, patterns, progress) to build a queryable graph.
• Semantic Search: Integrates vector embeddings (via ChromaDB) to enable similarity-based retrieval.
• Dual Communication Modes: Supports STDIO for local IDE integration (e.g., Roo Code) and HTTP (via FastAPI/Uvicorn) for broader client accessibility.

ConPort manages project knowledge through several structured entities stored in a workspace-specific SQLite database. Understanding these entities is key to knowing what information an AI agent can log or retrieve:

• Product Context (product_context): High-level, relatively static project information (goals, architecture, features).
• Active Context (active_context): Dynamic, short-term information relevant to the current session (current focus, next steps, open questions).
• Decisions (decisions): Logs of architectural or implementation decisions, including rationale and implementation details. Supports FTS5 full-text search.
• Progress Entries (progress_entries): Tracks tasks and their status (e.g., TODO, IN_PROGRESS, DONE) in a hierarchy using parent_id.
• System Patterns (system_patterns): Documents recurring architectural or design patterns used in the project.
• Custom Data (custom_data): Arbitrary key-value data categorized by the user (e.g., glossaries, notes). Supports FTS5 search.
• Context Links (context_links): The edges of the knowledge graph that define relationships between entities (e.g., a decision implements a pattern).
• Vector Store (ChromaDB): Stores embeddings for semantic similarity search, linked to SQLite entities via metadata.

Database Migrations

ConPort uses Alembic for schema management.

• v0.1.9 users: Upgrades are typically seamless and automatic via Alembic.
• v0.1.8 or earlier users: Require manual data export/import due to breaking schema changes.

Workspace Management

• Package Installation is Global: The context-portal-mcp package is installed in your Python environment (e.g., a virtual environment). Updating the package once updates it for all workspaces using that environment.
• Database Migration is Per-Workspace: Each workspace has its own context.db. If a workspace is on an old version, you must perform the migration steps (Export $\rightarrow$ Delete DB $\rightarrow$ Install $\rightarrow$ Import) specifically for that workspace's directory.
• Alembic Configuration: For migrations to function, alembic.ini must reside in your project's workspace root (the directory containing context_portal/ and context.db). While new workspaces provision this automatically, existing workspaces upgraded from older versions may require you to manually copy alembic.ini from your Python site-packages to the workspace root.

The mem4sprint strategy defines specific entity shapes for logging data to ConPort. Use these schemas to ensure valid data entry. Key entities include:

• sprint_goal: Requires content, sprint_id, and status (planned, active, blocked, done).
• artifact: Requires content, artifact_kind (file, function, api, doc, dataset, run, env), and status.
• decision: Requires summary; optional rationale and tags.
• relation: Links two entities using from_id, rel (e.g., BLOCKED_BY, IMPLEMENTS, DEPENDS_ON), and to_id.
• bug: Requires content, status, and severity (low, medium, high, critical).
• risk: Requires content, severity, and likelihood.
• retrospective_item: Requires content and kind (keep_doing, stop_doing, start_doing, action).

Validation rules enforce ID uniqueness, relation tuple uniqueness, and require that edges point to existing nodes.

// Example: sprint_goal shape
{
  "type": "sprint_goal",
  "content": "<goal statement>",
  "sprint_id": "S-YYYY.MM",
  "status": "planned",
  "tags": [],
  "provenance": { "agent": "planner", "tool": "mem4sprint", "ts": "" }
}

ConPort enables AI assistants to use prompt caching (supported by providers like Google Gemini, Anthropic Claude, and OpenAI) by providing structured, stable project context. This reduces latency and cost by allowing large blocks of frequently used information to be cached by the LLM provider.

ConPort supports this through three mechanisms:

1. Structured Context: Storing Product Context, System Patterns, and Custom Data in a structured database makes them ideal candidates for the cacheable prefix of a prompt.
2. User-Defined Cache Hints: Users can flag specific content for caching by adding a cache_hint key to the metadata field of a custom_data entity.
3. Strategy Guidance: ConPort provides guidance via custom instruction files or a central context_portal/prompt_caching_strategy.yml file. This helps the AI assistant identify cacheable content, structure prompts according to the specific LLM provider's requirements (e.g., explicit breakpoints for Anthropic), and notify the user when caching is being utilized.

The recommended installation method for most IDEs is using uvx to execute the package directly from PyPI. This avoids manual virtual environment management.

Add the following configuration to your MCP client settings (e.g., mcp_settings.json).

Note on ${workspaceFolder}: Many IDEs do not expand the ${workspaceFolder} variable when launching MCP servers. If your IDE fails to resolve this, either provide an absolute path for --workspace_id or omit the flag entirely to rely on the workspace_id provided by the client during tool calls.

{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": [
        "--from",
        "context-portal-mcp",
        "conport-mcp",
        "--mode",
        "stdio",
        "--workspace_id",
        "${workspaceFolder}",
        "--log-file",
        "./logs/conport.log",
        "--log-level",
        "INFO"
      ]
    }
  }
}