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

You need a Hologres instance to store vector data. Note the following connection details:

AI coding assistant installation

Follow the installation instructions for the AI coding assistant you are using:

• Qwen Code: Refer to the official Qwen Code documentation to complete the installation.

• Claude Code: Refer to the Claude Code documentation to complete the installation.

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

If you use Code Context Hologres with multiple MCP clients, you can manage your credentials in a single global configuration file instead of setting environment variables for each 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

After creating the global configuration file, you can simplify the MCP registration command:

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 a codebase involves splitting project files into chunks, generating vector embeddings, and storing them in Hologres. The process runs asynchronously, returning a response immediately after it starts.

Simply ask the AI in natural language:

> Index this codebase

The AI automatically calls the index_codebase tool, which supports 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

You can check the indexing progress at any time while it runs in the background. The AI calls the get_indexing_status tool.

> Check indexing status

Possible statuses:

Code search

Search the indexed codebase using a natural language query. The AI calls the search_code tool.

> Find the function that handles user authentication

The search_code tool supports the following 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

If you need to clear the index data for a codebase (for example, after switching embedding models), you can ask:

> Clear the index for the current codebase

The AI calls the clear_index tool 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

You can switch DashScope embedding models by modifying 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, Code Context Hologres supports common programming language files. If you need to index additional file types (such as .vue, .svelte, or .astro), you have two options:

Method 1: Configure globally with the CUSTOM_EXTENSIONS environment variable.

CUSTOM_EXTENSIONS=.vue,.svelte,.astro

Method 2: Specify during indexing using natural language.

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

Custom ignore patterns

Code Context Hologres automatically reads the .gitignore and .contextignore files in your project, as well as the global ~/.context/.contextignore file. You can also add extra ignore rules in the following ways:

Method 1: Use the CUSTOM_IGNORE_PATTERNS environment variable.

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

Method 2: Specify during indexing using natural language.

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

Code splitters

Code Context Hologres supports two code splitters:

You typically do not need to specify this manually. The system uses the ast splitter by default and automatically falls back if needed.

Hybrid search configuration

Code Context Hologres enables hybrid search by default (BM25 sparse vector + dense vector) for higher search accuracy. If you need to disable it and use only dense vectors, set the following:

HYBRID_MODE=false