open-context-engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AnnaSuSu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/brand/logo-lockup-dark.svg">
+    <img src="assets/brand/logo-lockup.svg" alt="OpenContextEngine" width="660">
+  </picture>
+  <p><strong>Precise code context for AI coding agents.</strong></p>
+  <p>Find related code across files. Follow its connections. Give your agent the evidence it needs.</p>
+  <p>
+    <a href="docs/BENCHMARKS.md#seven-method-comparison"><img src="https://img.shields.io/badge/dev_evidence_coverage-94.79%25-23875b?style=flat-square" alt="Development evidence coverage: 94.79%"></a>
+    <a href="docs/BENCHMARKS.md#seven-method-comparison"><img src="https://img.shields.io/badge/median_retrieval-1.73_s-23875b?style=flat-square" alt="Median retrieval: 1.73 seconds"></a>
+    <a href="docs/BENCHMARKS.md#engineering-validation"><img src="https://img.shields.io/badge/verified_tests-107-23875b?style=flat-square" alt="107 verified tests"></a>
+    <a href="docs/QUICKSTART.md"><img src="https://img.shields.io/badge/MCP-stdio-193c34?style=flat-square" alt="MCP over stdio"></a>
+  </p>
+  <p><a href="#quick-start">Quick start</a> · <a href="docs/BENCHMARKS.md">Benchmarks</a> · <a href="docs/QUICKSTART.md">MCP setup</a></p>
+</div>
+
+OpenContextEngine is a **self-hostable code context engine for AI coding agents**. Connect it to your agent through MCP to help it explore an unfamiliar codebase, locate implementations, and find the related code needed for a fix or feature.
+
+It indexes your working directory and follows saved changes. Given a natural-language task, it combines semantic and keyword search, code relationships, and reranking to return relevant source snippets with file paths and line numbers, within a fixed context budget.
+
+## Why OpenContextEngine
+
+- **Search beyond exact words.** Describe a behavior; retrieve its implementation and connected code across files.
+- **Understand code structure.** Python, TypeScript, JavaScript, and Go adapters, plus text fallback for other languages, configuration, and scripts.
+- **Stay current as you edit.** Saved changes, file deletions, and branch switches sync automatically. Unchanged embeddings are reused; incomplete updates never replace a complete index.
+- **Work across projects through MCP.** Your agent supplies the project path; indexes start on demand and are reused. `search_code` retrieves evidence; `index_status` reports synchronization.
+
+## Measured results
+
+![Required evidence coverage and observed query time](assets/benchmarks/method-comparison.svg)
+
+**94.79% required evidence coverage · 1.73 s median retrieval · 69/80 queries with complete evidence.** Seven engines, four repositories, the same 4,000-token output budget. OpenContextEngine retained the most required evidence in this internal development evaluation.
+
+Measured with the optional batch rerank API. 40 source-derived tasks, each asked in Chinese and English. Coverage measures source evidence, not coding-agent success. Timings reflect native retrieval for open tools and SDK client calls for ACE. [Full comparison, configurations, and per-query results →](docs/eval/METHOD_COMPARISON.md)
+
+## Quick start
+
+Requires **macOS or Linux**, Node.js 22.14+, Python 3.10+, Git, and configured embedding/reranking services. Go repositories also need Go 1.22+.
+
+**Preparing the first npm release; not yet published.** Get the installation archive from the maintainer, then expand your client's guide. Model settings are shared across clients on the same machine.
+
+<details>
+<summary><strong>Codex — install, connect, and search</strong></summary>
+
+**1. Install the CLI**
+
+With Codex CLI already installed, run:
+
+```sh
+npm install -g /path/to/open-context-engine-0.1.0.tgz
+```
+
+**2. Configure your models**
+
+```sh
+open-context-engine setup
+```
+
+Enter your embedding and reranking base URLs, API keys, model names, and embedding dimensions. Setup installs isolated Python dependencies and saves your settings. The default reranker uses the ordinary `/rerank` API. [Endpoint examples →](docs/QUICKSTART.md#2-shared-model-configuration)
+
+**3. Add the MCP server**
+
+```sh
+codex mcp add open-context-engine -- open-context-engine mcp
+codex mcp get open-context-engine
+```
+
+The second command checks the saved configuration. These commands assume `open-context-engine` is on the client's `PATH`. For the desktop app or source installations, use the [absolute-path configuration](docs/QUICKSTART.md#client-setup-notes). Restart an already-running Codex client after adding the server.
+
+**4. Search your project**
+
+```sh
+cd /path/to/your-project
+codex
+```
+
+Ask:
+
+> Use open-context-engine's search_code tool to explain this project's main functionality. Include the entry points and relevant file paths and line numbers.
+
+Codex supplies the project's absolute path as `directory_path`. The first request starts indexing; if it is still building, ask Codex to check `index_status` and retry when ready. Later searches reuse the index, and saved changes update automatically.
+
+[Codex MCP reference](https://developers.openai.com/codex/mcp)
+
+</details>
+
+<details>
+<summary><strong>Claude Code — install, connect, and search</strong></summary>
+
+**1. Install the CLI**
+
+With Claude Code already installed, run:
+
+```sh
+npm install -g /path/to/open-context-engine-0.1.0.tgz
+```
+
+**2. Configure your models**
+
+```sh
+open-context-engine setup
+```
+
+Enter your embedding and reranking base URLs, API keys, model names, and embedding dimensions. Setup installs isolated Python dependencies and saves your settings. If you already completed setup for Codex, reuse those settings and skip this step. [Endpoint examples →](docs/QUICKSTART.md#2-shared-model-configuration)
+
+**3. Add the MCP server**
+
+```sh
+claude mcp add --transport stdio --scope user open-context-engine -- open-context-engine mcp
+```
+
+User scope makes the server available across your projects. For a shared project configuration, run the command from that project and replace `--scope user` with `--scope project`. These commands assume `open-context-engine` is on the client's `PATH`; see [client setup notes](docs/QUICKSTART.md#client-setup-notes) for absolute paths. Restart an already-running Claude Code session after adding the server.
+
+**4. Search your project**
+
+```sh
+cd /path/to/your-project
+claude
+```
+
+Run `/mcp` to check the connection, then ask:
+
+> Use open-context-engine's search_code tool to explain this project's main functionality. Include the entry points and relevant file paths and line numbers.
+
+Claude supplies the project's absolute path as `directory_path`. The first request starts indexing; if it is still building, ask Claude to check `index_status` and retry when ready. Later searches reuse the index, and saved changes update automatically.
+
+[Claude Code MCP reference](https://code.claude.com/docs/en/mcp)
+
+</details>
+
+<details>
+<summary>Other MCP clients</summary>
+
+[Install and run setup](docs/QUICKSTART.md#1-install), then use the configuration printed by `open-context-engine mcp-config` in your client's supported format. For clients that accept `mcpServers` JSON and can find the installed command on `PATH`:
+
+```json
+{
+  "mcpServers": {
+    "open-context-engine": {
+      "command": "open-context-engine",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Your agent supplies the current project's absolute path as `directory_path`. To pin one project, add `"--root", "/absolute/path/to/your-repository"` to `args`.
+
+</details>
+
+<details>
+<summary>Run from source or build an internal package</summary>
+
+```sh
+git clone https://github.com/AnnaSuSu/OpenContextEngine.git
+cd OpenContextEngine
+npm ci
+node bin/opencontextengine.mjs setup
+# Build an installable archive for internal testers:
+npm pack
+```
+
+Use the absolute Node and CLI paths printed by setup. [Client-specific configuration →](docs/QUICKSTART.md#client-setup-notes)
+
+</details>
+
+[Model configuration, troubleshooting, and update behavior →](docs/QUICKSTART.md)
+
+Once published, install with `npm install -g open-context-engine`. Until then, use the archive above. [Release checklist](docs/RELEASING.md).
+
+## Explore
+
+[Benchmark report](docs/BENCHMARKS.md) · [Raw evaluations](docs/eval/results) · [Retrieval engine](src/retrieval) · [Logo assets](assets/brand)
+
+## License
+
+[MIT](LICENSE) © 2026 AnnaSuSu.

package/assets/brand/logo-lockup-dark.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1320" height="240" viewBox="0 0 1320 240" role="img" aria-labelledby="title desc">
+  <title id="title">OpenContextEngine</title>
+  <desc id="desc">The OpenContextEngine bracket symbol beside the project name.</desc>
+  <g transform="translate(141 0)">
+    <g transform="translate(24 24) scale(.375)">
+      <g fill="none" stroke="#D9F2E5" stroke-width="56" stroke-linecap="square" stroke-linejoin="round">
+        <path d="M208 112H176L112 176V336L176 400H208"/>
+        <path d="M304 112H336L400 176V336L336 400H304"/>
+      </g>
+      <rect x="212" y="212" width="88" height="88" rx="12" fill="#35CE8D"/>
+    </g>
+    <text x="246" y="146" fill="#D9F2E5" font-family="Helvetica Neue, Helvetica, Arial, sans-serif" font-size="82" font-weight="600" letter-spacing="-3">OpenContextEngine</text>
+  </g>
+</svg>

package/assets/brand/logo-lockup.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1320" height="240" viewBox="0 0 1320 240" role="img" aria-labelledby="title desc">
+  <title id="title">OpenContextEngine</title>
+  <desc id="desc">The OpenContextEngine bracket symbol beside the project name.</desc>
+  <g transform="translate(141 0)">
+    <g transform="translate(24 24) scale(.375)">
+      <g fill="none" stroke="#193C34" stroke-width="56" stroke-linecap="square" stroke-linejoin="round">
+        <path d="M208 112H176L112 176V336L176 400H208"/>
+        <path d="M304 112H336L400 176V336L336 400H304"/>
+      </g>
+      <rect x="212" y="212" width="88" height="88" rx="12" fill="#35CE8D"/>
+    </g>
+    <text x="246" y="146" fill="#193C34" font-family="Helvetica Neue, Helvetica, Arial, sans-serif" font-size="82" font-weight="600" letter-spacing="-3">OpenContextEngine</text>
+  </g>
+</svg>

package/assets/brand/logo.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512" role="img" aria-labelledby="title desc">
+  <title id="title">OpenContextEngine</title>
+  <desc id="desc">Two open, chamfered brackets surround a green code block.</desc>
+  <g fill="none" stroke="#193C34" stroke-width="56" stroke-linecap="square" stroke-linejoin="round">
+    <path d="M208 112H176L112 176V336L176 400H208"/>
+    <path d="M304 112H336L400 176V336L336 400H304"/>
+  </g>
+  <rect x="212" y="212" width="88" height="88" rx="12" fill="#35CE8D"/>
+</svg>

package/bin/opencontextengine.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { setup, validateModels } from '../src/setup.mjs';
+import { loadEnvironment, configDirectory } from '../src/config.mjs';
+import { verifyPython, run } from '../src/runtime.mjs';
+import { serviceConfig } from '../src/service.mjs';
+
+const help = `OpenContextEngine — repository context for AI coding agents
+
+Usage:
+  open-context-engine setup [--python /path/to/python3] [--non-interactive]
+  open-context-engine mcp [--root /project] [--state /outside/index]
+  open-context-engine mcp --connect
+  open-context-engine mcp-config
+  open-context-engine doctor
+  open-context-engine --version
+
+Setup installs isolated Python dependencies, saves shared model settings, and
+prints MCP configuration. Without --root, your agent supplies directory_path.
+Requires macOS/Linux, Node.js 22.14+, Python 3.10+, and Git.
+`;
+function mcpConfig() {
+  const env = process.env.OCE_CONFIG_HOME ? {OCE_CONFIG_HOME:configDirectory()} : undefined;
+  console.log(JSON.stringify({mcpServers:{'open-context-engine':{command:process.execPath,
+    args:[fileURLToPath(import.meta.url),'mcp'],...(env ? {env} : {})}}},null,2));
+}
+try {
+  const [command,...args] = process.argv.slice(2);
+  if (!command || command === '--help' || command === '-h' || args.includes('--help')) {
+    console.log(help);
+  } else if (command === '--version' || command === '-v') {
+    console.log(JSON.parse(readFileSync(new URL('../package.json',import.meta.url),'utf8')).version);
+  } else if (command === 'setup') {
+    const {values} = parseArgs({args,options:{python:{type:'string'},'non-interactive':{type:'boolean'}}});
+    await setup({python:values.python,nonInteractive:Boolean(values['non-interactive'])});
+    mcpConfig();
+  } else if (command === 'mcp-config' && args.length === 0) {
+    mcpConfig();
+  } else if (command === 'doctor' && args.length === 0) {
+    const env = loadEnvironment();
+    validateModels(env);
+    await run('git',['--version'],{timeout:10000});
+    const python = serviceConfig().python;
+    const version = await verifyPython(python,env);
+    console.log(`Model configuration valid. Python ${version}, NumPy, tiktoken, and Git are ready.`);
+    console.log('Endpoint authentication is checked during search. Go projects also require Go 1.22+.');
+  } else if (command === 'mcp') {
+    // Keep stdout exclusively for MCP messages. Setup remains a separate terminal command.
+    if (!args.includes('--connect')) {
+      validateModels(loadEnvironment());
+      await verifyPython(serviceConfig().python,loadEnvironment());
+    }
+    process.argv.splice(2,1);
+    await import('../scripts/mcp-opencontextengine.mjs');
+  } else {
+    throw new Error('Unknown command or arguments. Run open-context-engine --help');
+  }
+} catch (error) {
+  process.stderr.write(`OpenContextEngine: ${error.message}\n`);
+  process.stderr.write('Run open-context-engine setup to configure models and install Python dependencies.\n');
+  process.exitCode = 1;
+}

package/docs/QUICKSTART.md

@@ -0,0 +1,192 @@
+# Connect OpenContextEngine to your agent
+
+OpenContextEngine runs a local repository index and calls configured model services for embeddings and reranking. Its MCP interface uses stdio. Currently supported hosts: **macOS and Linux**.
+
+## 1. Install
+
+Requires Node.js 22.14+, Python 3.10+, and Git. Go source analysis also needs Go 1.22+ on `PATH`, or an explicit `OCE_GO_BINARY`.
+
+**First npm release in preparation; not yet published.** Install the archive supplied by the maintainer:
+
+```sh
+npm install -g /path/to/open-context-engine-0.1.0.tgz
+open-context-engine setup
+```
+
+`setup` asks for your embedding and reranking endpoints, keys, model names, and embedding dimensions. It creates a private Python virtual environment, installs NumPy and tiktoken, and preloads tokenizer data. No model weights are installed. API key input is not echoed. Use `--python /absolute/path/to/python3` to select a base interpreter.
+
+You can also run the same setup from source:
+
+```sh
+git clone https://github.com/AnnaSuSu/OpenContextEngine.git
+cd OpenContextEngine
+npm ci
+node bin/opencontextengine.mjs setup
+```
+
+After the first npm release, install with `npm install -g open-context-engine`, then run `open-context-engine setup`. Maintainers can build an archive with `npm pack`; see the [release checklist](https://github.com/AnnaSuSu/OpenContextEngine/blob/main/docs/RELEASING.md).
+
+The CLI and package are named `open-context-engine`. The previous `opencontextengine` command remains an alias. Existing configuration and cache directories keep their paths, so saved keys and indexes are reused.
+
+## 2. Shared model configuration
+
+Setup saves `~/.config/opencontextengine/config.json` with owner-only file permissions. All MCP clients running under the same user share these settings. Python environments live in the adjacent `runtimes/` directory. Use `OCE_CONFIG_HOME` to select a separate configuration directory; setup includes that override in its generated MCP configuration.
+
+Configuration precedence is **process environment → saved user settings → source checkout `.env` defaults**. The `.env` of the project being searched is never loaded. Existing source installations using `.env` and `OCE_PYTHON` continue to work.
+
+For automation, set the following environment variables and run `open-context-engine setup --non-interactive`:
+
+```dotenv
+EMBEDDING_BASE_URL=https://your-embedding-service.example/v1
+EMBEDDING_API_KEY=your-embedding-key
+EMBEDDING_MODEL=Qwen3-Embedding-4B
+OCE_EMBEDDING_DIMENSIONS=1024
+
+RERANK_BASE_URL=https://your-reranker-service.example/v1
+RERANK_API_KEY=your-reranker-key
+RERANK_MODEL=Qwen3-Reranker-4B
+OCE_RERANK_API=rerank
+```
+
+The embedding service must implement `POST /v1/embeddings`. By default, the reranker uses the ordinary `/rerank` API: requests contain `model`, `query`, `documents`, and `top_n`; responses must return every requested document in `results`, with its original `index` and a finite `relevance_score` between 0 and 1. Results may arrive in relevance order. Set the reranker base URL to the part before `/rerank`: for example, `https://provider.example/v1`, `/v2`, or `https://provider.example` for an unversioned endpoint.
+
+HTTPS is the default. For an explicitly trusted remote HTTP deployment, set `OCE_ALLOW_HTTP=1` before running `open-context-engine setup`; setup saves this choice in the shared configuration. HTTP transmits API keys and source text without encryption. Local model endpoints remain prohibited. Set `OCE_EMBEDDING_DIMENSIONS` to the service's actual output size (for example, `2560`); changing the provider or dimensions creates a new index generation and does not mix incompatible cached vectors.
+
+OpenContextEngine groups the needed pairs by query, reuses scores within each search, and makes at most two concurrent rerank requests by default. Optional `OCE_RERANK_CONCURRENCY` (1–8, default 2) and `OCE_RERANK_MAX_DOCUMENTS` (1–1,024, default 128) control concurrency and documents per request. It requests all scores and rejects missing, duplicate, or invalid result indices; errors are surfaced without silently switching endpoints.
+
+For the [optional benchmark reranker server](RERANKER_API.md), you can optionally set `OCE_RERANK_API=rerank-batch` to combine multiple queries into its custom `/rerank-batch` endpoint. The default `rerank` mode works with this server too. Qwen3-Embedding-4B / Qwen3-Reranker-4B are the evaluated models; the published seven-method benchmark used the custom batch mode. Other providers and models still need compatibility and quality validation, especially if they score documents jointly rather than independently. Changing document batch limits may then affect scores.
+
+The launcher defaults to HTTPS model endpoints, with explicit HTTP opt-in and SSH/direct-worker transport options available in [the transport configuration](../src/eval/remote-models.mjs). It does not install or load model weights on the client. Repository fragments and queries are sent to the model endpoints you configure.
+
+For internal testing, both model APIs can use an existing SSH connection. Keep the logical `EMBEDDING_BASE_URL` and `RERANK_BASE_URL` unchanged so the vector cache retains its provider identity. Start a loopback-only forward in a separate terminal (replace the example host and server ports):
+
+```sh
+ssh -N -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 \
+  -L 127.0.0.1:43079:127.0.0.1:8079 \
+  -L 127.0.0.1:43078:127.0.0.1:8078 operator@model-host.example
+```
+
+Then start the CLI with these overrides, or save them with `setup --non-interactive`:
+
+```dotenv
+EMBEDDING_SSH_TUNNEL_URL=http://127.0.0.1:43079/v1
+EMBEDDING_SSH_REMOTE=operator@model-host.example:22
+RERANK_SSH_TUNNEL_URL=http://127.0.0.1:43078
+RERANK_SSH_REMOTE=operator@model-host.example:22
+```
+
+The rerank tunnel must preserve the configured base URL's path prefix (for example, `/v1` if required). Keep the SSH process running while using MCP. The CLI does not create SSH sessions or store SSH passwords, and a disconnected tunnel surfaces an error instead of falling back to public HTTP. Models continue to run on the remote server.
+
+## 3. Add the MCP server
+
+Paste the MCP configuration printed by setup into your client, or print it again with `open-context-engine mcp-config`. It uses absolute Node and CLI paths so desktop clients do not need to find npm's global binary directory.
+
+If your client already has `open-context-engine` on `PATH`, this shorter equivalent works:
+
+```json
+{
+  "mcpServers": {
+    "open-context-engine": {
+      "command": "open-context-engine",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Use your client's equivalent configuration format. Configuration and dependency errors go to stderr; MCP stdout is reserved for protocol messages.
+
+Without `--root`, the server uses **automatic workspace mode**. Your agent supplies the absolute project directory in `directory_path` on each tool call. No indexing starts until a project is requested; first access starts a repository worker and background indexing. Later calls reuse it. One MCP session can search multiple projects, each with an independent worker and persistent index. Workers stay active until the client disconnects, when all are stopped.
+
+The server does not infer your editor's project from its own launch directory. Its tool instructions tell the agent to use the project path supplied by the host, or inspect the current project directory. Missing, relative, or invalid paths return an error. Symbolic links to the same directory share a worker. Supply the same project root consistently, rather than a different subdirectory on each call.
+
+Example tool arguments (sent by your agent):
+
+```json
+{"directory_path":"/absolute/path/to/your-repository","query":"Where are user sessions validated?"}
+```
+
+To pin the server to one project instead, append `"--root", "/absolute/path/to/your-repository"` to `args`. In this mode `directory_path` may be omitted; a different project path is rejected. Existing fixed-project configurations continue to work.
+
+| Tool | Purpose |
+| --- | --- |
+| `search_code` | Pass `directory_path` and describe the behavior in `query`. Returns source paths, line numbers, and relevant code; default budget: 4,000 tokens. |
+| `index_status` | Pass `directory_path` to inspect indexing progress, active generation, vector reuse, and the latest update error. First access also starts that project's index. |
+
+### Client setup notes
+
+Start with the expandable **Codex** or **Claude Code** guide in the [README](../README.md#quick-start). The CLI registration commands there assume the installed executable is on the client's `PATH`.
+
+For desktop clients or source installations, run `open-context-engine mcp-config` (or `node bin/opencontextengine.mjs mcp-config` from the checkout). Use the absolute `command` and `args` values it prints. Codex uses TOML rather than the printed `mcpServers` JSON; add or update this entry in `~/.codex/config.toml`, replacing the example paths:
+
+```toml
+[mcp_servers.open-context-engine]
+command = "/absolute/path/to/node"
+args = ["/absolute/path/to/bin/opencontextengine.mjs", "mcp"]
+startup_timeout_sec = 30
+tool_timeout_sec = 180
+```
+
+For Claude Code, use those same paths with its registration command:
+
+```sh
+claude mcp add --transport stdio --scope user open-context-engine -- /absolute/path/to/node /absolute/path/to/bin/opencontextengine.mjs mcp
+```
+
+Quote paths that contain spaces. If the generated configuration includes `env` (for example, a custom `OCE_CONFIG_HOME`), preserve it: use `[mcp_servers.open-context-engine.env]` in Codex or `--env OCE_CONFIG_HOME=/absolute/config/path` before `--transport stdio` in the Claude command. Keep your model keys in the shared OpenContextEngine settings saved by setup. Restart the client after changing its configuration.
+
+- **Command not found:** use the absolute paths above and confirm the Node executable still exists after a Node upgrade.
+- **Tools missing:** check `codex mcp get open-context-engine` for the saved Codex entry, or `/mcp` inside Claude Code for connection status; restart the client after configuration changes.
+- **First search is still indexing:** ask the agent to call `index_status` for the same project. Once it reports ready, retry `search_code`. Large repositories can take longer than a single tool call's timeout. If status reports an error, resolve that error before retrying.
+- **Model configuration or authentication errors:** rerun `open-context-engine setup`. `open-context-engine doctor` checks local configuration and dependencies; an actual search checks access to the model APIs. If using SSH forwarding, keep the tunnel running.
+
+Client references: [Codex MCP](https://developers.openai.com/codex/mcp) · [Claude Code MCP](https://code.claude.com/docs/en/mcp).
+
+## Updates & storage
+
+Saved files are checked every second by default, with a 300 ms debounce. New files, deletions, renames, and branch changes update the index automatically. Embeddings are reused by model identity and actual input content. Structural analysis conservatively refreshes the affected language group to update references in unchanged files.
+
+Search actively checks source hashes before retrieval and again before returning. It waits up to 30 seconds for synchronization (`freshnessWaitMs`, maximum 120 seconds). Failed updates, timeouts, or edits during retrieval produce explicit errors. Unsaved editor buffers are not indexed.
+
+State is stored in `~/.cache/opencontextengine/<repository-path-hash>/`. Override it with `--state /outside/repository/index`: automatic mode creates a separate path-hash subdirectory for each project; fixed `--root` mode uses that exact state directory. Existing installations automatically reuse their previous cache location. One worker may write to a state directory at a time. Stop that worker and remove the directory to delete stored source and embeddings.
+
+When model weights change under the same name, increment `OCE_EMBEDDING_REVISION`. A different provider, model name, or dimension count also invalidates vector reuse. Other models need separate compatibility and quality validation.
+
+## Share one worker across clients
+
+This optional source-installation workflow shares a running worker, in addition to the shared model configuration available to all CLI installations. Set an `OCE_API_KEY` of at least 24 characters in the environment, then run from the checkout:
+
+```sh
+npm run serve-retrieval -- --root /absolute/path/to/your-repository --port 23505
+```
+
+Configure each MCP client to run `open-context-engine mcp --connect` (or `node scripts/mcp-opencontextengine.mjs --connect` from source), with `OCE_BASE_URL=http://127.0.0.1:23505` and the same `OCE_API_KEY`. This mode always uses the shared worker's configured project: omit `directory_path`. Closing a client leaves the shared worker running.
+
+## Check and upgrade
+
+Run `open-context-engine doctor` to check model configuration, Python dependencies, tokenizer data, and Git. This does not send code to model providers; endpoint authentication is checked during actual search.
+
+If upgrading from the old package named `opencontextengine`, first run `npm uninstall -g opencontextengine` to avoid a command-name conflict. This leaves your saved model settings and indexes intact.
+
+For an internal upgrade, install the new archive and rerun setup:
+
+```sh
+npm install -g /path/to/new-open-context-engine.tgz
+open-context-engine setup
+```
+
+Press Enter to retain saved settings. Setup reuses a healthy managed Python runtime when its dependency requirements match; otherwise it builds a new environment before changing the saved configuration. Failed dependency installation preserves the previous settings and runtime. Old runtimes remain available for rollback. When migrating from the old package name, replace the client entry with the configuration printed by setup: its absolute installation path has changed. Restart the MCP client after an upgrade. Project indexes remain outside the package directory and continue to reuse compatible embeddings.
+
+First-time setup requires network access to npm/PyPI and tokenizer data. If Python is missing or lacks `venv`/`pip`, install Python 3.10+ with those components, then rerun setup. The CLI does not install system Node, Python, Git, or Go.
+
+## Internal testing checklist
+
+1. Install the supplied tarball on macOS or Linux and run setup with your model endpoints.
+2. Paste the generated MCP configuration into your client, restart it, and search a small project.
+3. Save an edit, add a file, and delete a file; verify search returns current source.
+4. Switch to another project and back; verify the results belong to the requested project.
+5. Restart the client and reinstall the archive; verify model settings and compatible indexes are retained.
+
+For issues, include the CLI version, operating system, client name, and the error message. Keep API keys and private source code out of reports.
+
+[Benchmark & test report](BENCHMARKS.md) · [Detailed update design](LIVE_INDEX.md) · [MCP implementation](../src/mcp.mjs)

package/docs/RERANKER_API.md

@@ -0,0 +1,32 @@
+# Optional benchmark reranker
+
+OpenContextEngine calls model services over HTTP. Normal installation does not require running a GPU model server from this repository; configure your own embedding and reranking endpoints as described in [Quick start](QUICKSTART.md).
+
+The published benchmarks used Qwen3-Reranker-4B with an optional batch API. Its [reference server](../scripts/benchmarks/reranker-server.py) is retained with the benchmark tools so the scoring implementation remains inspectable. It loads model weights and runs only on a separately configured Linux CUDA host with `OCE_REMOTE_MODEL_HOST=1`.
+
+## API modes
+
+| Mode | Endpoint | Request | Response |
+| --- | --- | --- | --- |
+| Default | `POST /v1/rerank` | `model`, `query`, `documents`, `top_n` | `results` with original document `index` and `relevance_score` |
+| Optional batch | `POST /v1/rerank-batch` | `model`, `queries`, `documents`, `pairs` of query/document indices | `results` with original pair `index`, `query_index`, `document_index`, and `relevance_score` |
+
+Both endpoints require `Authorization: Bearer <key>`. Scores are finite values between 0 and 1. The batch implementation shares inference across requested pairs; it does not generate an answer. The published seven-method comparison used `OCE_RERANK_API=rerank-batch`; ordinary services use `OCE_RERANK_API=rerank`.
+
+The reference server exposes unauthenticated readiness through `GET /healthz` and authenticated model metadata through `GET /v1/models`. It reports truncation and rejects invalid inputs. Its source defines input, batch, body-size, concurrency, and timeout limits.
+
+## Reference environment
+
+The recorded benchmark deployment used Python 3.12, PyTorch 2.7.1 with CUDA 12.8, Transformers 4.57.6, and BF16 inference. The server additionally imports FastAPI and Pydantic and needs an ASGI runner such as Uvicorn. These model-server dependencies are separate from the client requirements.
+
+The operator supplies `RERANK_MODEL_DIR` pointing to pre-provisioned Qwen3-Reranker-4B weights and `RERANK_API_KEY` with at least 24 characters. Loading is local-only with remote model code disabled. Optional batch settings are `RERANK_MAX_BATCH` and `RERANK_BATCH_TOKEN_BUDGET`.
+
+On that Linux model host, from this repository's root:
+
+```sh
+# Set the model directory and secret in the server's environment first.
+OCE_REMOTE_MODEL_HOST=1 python -m uvicorn reranker-server:app \
+  --app-dir scripts/benchmarks --host 127.0.0.1 --port 8000
+```
+
+Use an HTTPS proxy or explicitly configured secure transport for remote clients. Personal service addresses, Supervisor configuration, and deployment logs are not part of the public example. No deployment or model download is performed by installing OpenContextEngine.

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "open-context-engine",
+  "version": "0.1.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22.14"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "prepare-django": "node scripts/prepare-django.mjs",
+    "ace-django": "node scripts/ace-django.mjs",
+    "score-django": "node scripts/score-django.mjs",
+    "baseline": "node scripts/run-baseline.mjs",
+    "search": "node scripts/search-opencontextengine.mjs",
+    "serve-retrieval": "node scripts/serve-opencontextengine.mjs",
+    "benchmark-service": "node scripts/benchmark-service.mjs",
+    "mcp": "node scripts/mcp-opencontextengine.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.0",
+    "typescript": "5.9.3",
+    "zod": "4.6.5"
+  },
+  "description": "Live code context for AI coding agents, with automatic workspaces and MCP.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AnnaSuSu/OpenContextEngine.git"
+  },
+  "homepage": "https://github.com/AnnaSuSu/OpenContextEngine#readme",
+  "bin": {
+    "open-context-engine": "bin/opencontextengine.mjs",
+    "opencontextengine": "bin/opencontextengine.mjs"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "files": [
+    "bin/",
+    "src/config.mjs",
+    "src/environment.mjs",
+    "src/client.mjs",
+    "src/service.mjs",
+    "src/workspaces.mjs",
+    "src/mcp.mjs",
+    "src/runtime.mjs",
+    "src/setup.mjs",
+    "src/eval/remote-models.mjs",
+    "src/retrieval/**/*.py",
+    "src/retrieval/**/*.mjs",
+    "src/retrieval/**/*.go",
+    "scripts/mcp-opencontextengine.mjs",
+    "scripts/retrieval-server.py",
+    "requirements.txt",
+    "docs/QUICKSTART.md",
+    "assets/brand/*.svg",
+    "docs/RERANKER_API.md"
+  ],
+  "devDependencies": {
+    "@augmentcode/auggie-sdk": "0.2.0",
+    "@openai/codex-sdk": "0.160.0",
+    "js-tiktoken": "1.0.21"
+  },
+  "license": "MIT",
+  "author": "AnnaSuSu",
+  "keywords": [
+    "mcp",
+    "code-search",
+    "code-context",
+    "codex",
+    "claude-code",
+    "retrieval"
+  ],
+  "bugs": {
+    "url": "https://github.com/AnnaSuSu/OpenContextEngine/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/requirements.txt

@@ -0,0 +1,2 @@
+numpy>=2.2,<3
+tiktoken>=0.9,<1