OpenACE

AI-native Contextual Code Engine. Rust core with Python bindings, exposing a CLI, Python SDK, and MCP server for Claude Code / Codex CLI.

OpenACE combines multi-signal retrieval (BM25 full-text + vector kNN + exact match + graph expansion + AST chunk search) with Reciprocal Rank Fusion to deliver high-quality code search across Python, TypeScript, JavaScript, Rust, Go, and Java.

Quick Start

pip install "openace[mcp,openai]"

# Index a project
openace index /path/to/project --embedding siliconflow

# Search
openace search "user authentication" -p /path/to/project --embedding siliconflow

# Start MCP server
openace serve /path/to/project --embedding siliconflow

Use with Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "openace": {
      "command": "openace",
      "args": ["serve", ".", "--embedding", "siliconflow"],
      "env": {
        "OPENACE_EMBEDDING_API_KEY": "your-api-key"
      }
    }
  }
}

Or use uvx for zero-install (once published to PyPI):

{
  "mcpServers": {
    "openace": {
      "command": "uvx",
      "args": ["openace", "serve", ".", "--embedding", "siliconflow"],
      "env": {
        "OPENACE_EMBEDDING_API_KEY": "your-api-key"
      }
    }
  }
}

Use with Codex CLI

codex mcp add openace -- uvx openace serve . --embedding siliconflow

Custom API Providers

OpenACE supports any OpenAI-compatible embedding/reranking API. Configure via CLI flags or environment variables:

{
  "mcpServers": {
    "openace": {
      "command": "openace",
      "args": [
        "serve", ".",
        "--embedding", "openai",
        "--reranker", "siliconflow"
      ],
      "env": {
        "OPENACE_EMBEDDING_API_KEY": "your-embedding-key",
        "OPENACE_EMBEDDING_BASE_URL": "https://api.your-provider.com/v1",
        "OPENACE_RERANKER_API_KEY": "your-reranker-key",
        "OPENACE_RERANKER_BASE_URL": "https://api.your-reranker.com/v1"
      }
    }
  }
}

Environment Variables

Variable	Description
OPENACE_EMBEDDING_API_KEY	API key for embedding provider
OPENACE_EMBEDDING_BASE_URL	Custom base URL for embedding API
OPENACE_EMBEDDING_DIM	Override embedding vector dimension
OPENACE_RERANKER_API_KEY	API key for reranker provider
OPENACE_RERANKER_BASE_URL	Custom base URL for reranker API
OPENACE_EMBEDDING	Default embedding provider for serve
OPENACE_RERANKER	Default reranker for serve

Embedding Providers

Name	Model	Requires
siliconflow	Qwen/Qwen3-Embedding-8B (1024-dim)	openace[openai] + API key
openai	text-embedding-3-small	openace[openai] + API key
local	all-MiniLM-L6-v2 (384-dim)	openace[onnx]
none	BM25 only, no vector search	(default)

Reranker Providers

Name	Backend	Requires
auto	Matches embedding provider	(default)
siliconflow	Qwen/Qwen3-Reranker-8B	openace[openai] + API key
cohere	Cohere Rerank	openace[rerank-cohere] + API key
cross_encoder	Local cross-encoder model	openace[rerank-local]
rule_based	Heuristic (no API needed)	(built-in)

MCP Tools

semantic_search

Search for code by natural language query. Returns file-level results with code snippets, match signals, and file outlines.

find_symbol

Look up symbols by exact name. Returns definitions with file path, line range, and signature.

get_file_outline

Get all symbols defined in a file. Returns a structural overview with symbol kinds, names, and line ranges.

Python SDK

from openace import Engine

engine = Engine("/path/to/project")
engine.index()

# Semantic search
results = engine.search("parse XML", limit=10)
for r in results:
    print(f"{r.file_path}:{r.line_range[0]} {r.name} ({r.kind})")

# Exact lookup
symbols = engine.find_symbol("MyClass")

# File outline
outline = engine.get_file_outline("src/main.py")

Installation

# Default install (includes MCP server, OpenAI/SiliconFlow embedding & reranking)
pip install openace

# With local ONNX embedding (no API key needed)
pip install "openace[onnx]"

# With Cohere reranker
pip install "openace[rerank-cohere]"

# Development
pip install -e ".[dev]"

Architecture

Source files --> Scanner --> Parser (tree-sitter) --> Indexer --> Storage
                                                                   |
                                                     SQLite (graph/relations)
                                                     Tantivy (BM25 full-text)
                                                     usearch (vector kNN)
                                                                   |
Query --> CLI/SDK/MCP --> Retrieval (BM25 + vector + exact + graph + chunk)
                              |
                          RRF Fusion --> Reranker --> Results

• Rust core handles all performance-critical operations (parsing, indexing, storage, retrieval)
• Python layer provides the SDK, CLI, MCP server, and pluggable embedding/reranking providers
• tree-sitter for multi-language AST parsing
• Triple-backend storage: SQLite for graph/relations, Tantivy for BM25, usearch for HNSW vector search
• CJK bigram tokenization in BM25 for Chinese/Japanese/Korean query support

Supported Languages

Python, TypeScript, JavaScript, Rust, Go, Java.

Building from Source

Requires Rust >= 1.85.0 and Python >= 3.10.

git clone https://github.com/Kosthi/OpenACE.git
cd OpenACE
pip install maturin
maturin develop --release
pip install -e ".[dev]"

License

MIT