Hologres:Code Context Hologres user guide

Environment requirements

DashScope and Bailian configuration

You need a DashScope API Key to use the embedding models.

1. Sign up for an Alibaba Cloud account.

2. Activate the Model Studio (Bailian) service.

3. Create an API Key in the Model Studio (Bailian) console. The key starts with sk-.

Available DashScope embedding models:

Hologres instance configuration

Prepare the following Hologres connection details:

AI coding assistant installation

Install the AI coding assistant you plan to use:

• Qwen Code: Install from the official Qwen Code documentation.

• Claude Code: Install from the Claude Code documentation.

Claude Code configuration

claude mcp add code-context-hologres \
    -e EMBEDDING_PROVIDER=DashScope \
    -e DASHSCOPE_API_KEY=sk-your-dashscope-api-key \
    -e EMBEDDING_MODEL=text-embedding-v4 \
    -e EMBEDDING_BATCH_SIZE=10 \
    -e HOLOGRES_HOST=your-hologres-instance.hologres.aliyuncs.com \
    -e HOLOGRES_PORT=80 \
    -e HOLOGRES_DATABASE=your-database-name \
    -e HOLOGRES_USER=your-access-id \
    -e HOLOGRES_PASSWORD=your-access-secret \
  -- npx code-context-mcp-hologres@latest

{
  "mcpServers": {
    "code-context-hologres": {
      "command": "npx",
      "args": ["-y", "code-context-mcp-hologres@latest"],
      "env": {
        "EMBEDDING_PROVIDER": "DashScope",
        "DASHSCOPE_API_KEY": "sk-your-dashscope-api-key",
        "EMBEDDING_MODEL": "text-embedding-v4",
        "EMBEDDING_BATCH_SIZE": "10",
        "HOLOGRES_HOST": "your-hologres-instance.hologres.aliyuncs.com",
        "HOLOGRES_PORT": "80",
        "HOLOGRES_DATABASE": "your-database-name",
        "HOLOGRES_USER": "your-access-id",
        "HOLOGRES_PASSWORD": "your-access-secret"
      }
    }
  }
}

claude mcp list

Qwen Code configuration

qwen mcp add \
    -t stdio \
    -e EMBEDDING_PROVIDER=DashScope \
    -e DASHSCOPE_API_KEY=sk-your-dashscope-api-key \
    -e EMBEDDING_MODEL=text-embedding-v4 \
    -e EMBEDDING_BATCH_SIZE=10 \
    -e HOLOGRES_HOST=your-hologres-instance.hologres.aliyuncs.com \
    -e HOLOGRES_PORT=80 \
    -e HOLOGRES_DATABASE=your-database-name \
    -e HOLOGRES_USER=your-access-id \
    -e HOLOGRES_PASSWORD=your-access-secret \
    code-context-hologres \
    npx -y code-context-mcp-hologres@latest

{
  "mcpServers": {
    "code-context-hologres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "code-context-mcp-hologres@latest"],
      "env": {
        "EMBEDDING_PROVIDER": "DashScope",
        "DASHSCOPE_API_KEY": "sk-your-dashscope-api-key",
        "EMBEDDING_MODEL": "text-embedding-v4",
        "EMBEDDING_BATCH_SIZE": "10",
        "HOLOGRES_HOST": "your-hologres-instance.hologres.aliyuncs.com",
        "HOLOGRES_PORT": "80",
        "HOLOGRES_DATABASE": "your-database-name",
        "HOLOGRES_USER": "your-access-id",
        "HOLOGRES_PASSWORD": "your-access-secret"
      }
    }
  }
}

Global configuration file

To share credentials across multiple MCP clients, store them in a single global configuration file instead of setting environment variables per client.

Create a ~/.context/.env file with the following content:

# DashScope embedding model configuration
EMBEDDING_PROVIDER=DashScope
DASHSCOPE_API_KEY=sk-your-dashscope-api-key
EMBEDDING_MODEL=text-embedding-v4
EMBEDDING_BATCH_SIZE=10

# Hologres database configuration
HOLOGRES_HOST=your-hologres-instance.hologres.aliyuncs.com
HOLOGRES_PORT=80
HOLOGRES_DATABASE=your-database-name
HOLOGRES_USER=your-access-id
HOLOGRES_PASSWORD=your-access-secret

With the global configuration in place, the MCP registration command simplifies to:

Claude Code:

claude mcp add code-context-hologres -- npx code-context-mcp-hologres@latest

Qwen Code:

qwen mcp add \
    -t stdio \
    code-context-hologres \
    npx -y code-context-mcp-hologres@latest

DashScope embedding model configuration

Hologres database configuration

Advanced configuration

Basic workflow

1. Open your AI coding assistant (Qwen Code or Claude Code) in your project's directory.

2. Ask the AI to index your codebase.

3. Check the indexing status and wait for it to complete.

4. Search your code using natural language.

Codebase indexing

Indexing splits project files into chunks, generates vector embeddings, and stores them in Hologres. The process runs asynchronously in the background.

Ask the AI in natural language:

> Index this codebase

The AI calls the index_codebase tool with the following parameters:

Example: Include additional file types during indexing.

> Index this codebase, and include .vue and .svelte files

Example: Force re-indexing.

> Force re-indexing of the current codebase

Indexing status

Check indexing progress at any time. The AI calls the get_indexing_status tool.

> Check indexing status

Possible statuses:

Code search

Search your indexed codebase with natural language. The AI calls the search_code tool.

> Find the function that handles user authentication

search_code parameters:

More search examples:

> Find all code related to database connections

> Search for error handling logic, but only in .py files

> Find code snippets related to the payment process

> Search for the implementation code of Hologres vector retrieval

Clear the index

To clear the index data for a codebase (for example, after switching embedding models):

> Clear the index for the current codebase

The AI calls clear_index to delete the index data from Hologres.

Example (Claude Code)

$ cd /path/to/your-project
$ claude

> Index this codebase
code-context-hologres: Started background indexing for codebase '/path/to/your-project'
using AST splitter. Indexing is running in the background.

> Check indexing status
code-context-hologres: Codebase '/path/to/your-project' is currently being indexed.
Progress: 45.2% (Processing files and generating embeddings...)

> Check indexing status
code-context-hologres: Codebase '/path/to/your-project' is fully indexed and ready
for search. Statistics: 128 files, 1,536 chunks.

> Find the function that handles user login authentication
code-context-hologres: Found 5 results for query "user login authentication":
1. Code snippet (TypeScript) [your-project]
   Location: src/auth/login.ts:15-42
   ...

Example (Qwen Code)

$ cd /path/to/your-project
$ qwen

> Index this codebase
code-context-hologres: Started background indexing for codebase '/path/to/your-project'
using AST splitter. Indexing is running in the background.

> Check indexing status
code-context-hologres: Codebase '/path/to/your-project' is fully indexed and ready
for search. Statistics: 128 files, 1,536 chunks.

> Find the function that handles user login authentication
code-context-hologres: Found 5 results for query "user login authentication":
1. Code snippet (TypeScript) [your-project]
   Location: src/auth/login.ts:15-42
   ...

Switching models

Switch embedding models by changing the EMBEDDING_MODEL environment variable.

For example, to use the text-embedding-v3 model:

# Modify in the MCP registration command
-e EMBEDDING_MODEL=text-embedding-v3

Or modify it in ~/.context/.env:

EMBEDDING_MODEL=text-embedding-v3

Custom file extensions

By default, common programming language files are indexed. To include additional file types (.vue, .svelte, .astro):

Method 1: Set the CUSTOM_EXTENSIONS environment variable.

CUSTOM_EXTENSIONS=.vue,.svelte,.astro

Method 2: Specify during indexing in natural language.

> Index this codebase and include .vue and .svelte files

Custom ignore patterns

Code Context Hologres reads .gitignore, .contextignore (project-level), and ~/.context/.contextignore (global). Add extra ignore rules as follows:

Method 1: Use the CUSTOM_IGNORE_PATTERNS environment variable.

CUSTOM_IGNORE_PATTERNS=*.test.ts,__mocks__,*.generated.ts

Method 2: Specify during indexing in natural language.

> Index this codebase, ignoring the .test.ts and __mocks__ directories

Code splitters

Two code splitters are available:

The system uses ast by default and falls back automatically if needed. Manual selection is rarely necessary.

Hybrid search configuration

Hybrid search (BM25 + dense vector) is enabled by default. To disable it and use only dense vectors:

HYBRID_MODE=false