CodeOracle

Self-hosted MCP server that searches your codebase and remembers why it was built that way.

Plug it into Cursor, Claude Code, or any MCP client. Index once. Ask with citations. Stay fresh via GitHub webhooks or a local reindex.

Status: actively developed. Hybrid code search and file explain are the strongest paths today. Decision memory works end-to-end, but extract quality tracks whatever chat model you configure — we treat that as a known limit and keep improving ranking, prompts, and evals. We do not claim “perfect answers out of the box.”

Default path is private-by-design: run the stack on your machine or your VPC; use local Ollama (or any local OpenAI-compatible server) for embeddings and, if you want, for decision extract — so source and PR text need not leave your network. Cloud providers are optional, config-only, and never required for search.

Interactive overview: docs/demo/index.html · live site (GitHub Pages): https://jassu78.github.io/CodeOracle/

Contributing: CONTRIBUTING.md

Privacy & offline

CodeOracle is built for teams that want agent memory without shipping the monorepo to a vendor RAG cloud by default.

Mode	What leaves your machine
All-local (Compose + Ollama embed ± local chat)	Nothing required for search; extract stays local if chat is local
Local embed + optional cloud chat	Only texts you send to extract (PR/commit bodies), after secret scrubbing — not a full repo upload product
Your own VPC	Same binary; point `providers.yaml` at internal endpoints

That is the wedge beside “ask the IDE on demand”: a durable index you operate, with citations, that can run air-gapped or offline for the search path. Infra and model capacity are still your cost — local does not mean free of hardware.

What this is (and isn’t)

Coding agents are strong at reading today’s files in-session. They are weak at durable team memory:

why Postgres won over the alternative two years ago
which PR recorded an auth edge case
what you already rejected — and why

That context lives in PR bodies, review threads, and people’s heads. Session to session, the agent forgets.

CodeOracle is a small, cited memory layer your agent can call over MCP — not another “chat with the repo” UI, and not a replacement for Cursor’s own indexing.

Is	Is not
Hybrid search + decision archive with mandatory citations	A Cursor competitor for general coding
Self-hosted index your team owns	“Upload the monorepo to our cloud” by default
Tools any MCP client can call	Locked to one IDE
Fresh via webhooks / reindex	Magic that invents rationale missing from sources

Product test: if you remove a fancy UI and still have queryable architectural decisions + cited code search for any coding agent, you built CodeOracle.

Why not “just ask Cursor”?

Cursor (and similar tools) already do a quick lookup of the current tree — and they’re excellent at that. Use them.

CodeOracle is for the layer beside that:

Cited retrieval you own — ranked chunks with file paths, same contract every time, on hardware you control.
Decision memory — structured WHY mined from git/PR history, with a mandatory source URL (not vibes).
Team freshness — one shared index updated by webhooks, so every engineer’s agent sees the same archive.

If the only job is “find this function in the open repo,” the editor is enough. If the job is “remember why we chose this, with proof, across sessions and teammates,” that’s the gap this project targets — and we’re still sharpening how well extraction fills that gap depending on the chat model you run.

What you get

Tool	What it does	Needs
`search_codebase`	Hybrid search over indexed chunks	Embeddings
`explain_file`	File chunks + related decisions (no LLM rewrite)	Index
`find_decision`	WHY, alternatives, confidence, source URL	Extract once with a chat model; queries are retrieval only

Typical loop: register a repo → worker indexes → optional decision extract → connect MCP → optional GitHub push webhooks.

Rules we do not bend

No citation = bug — every hit has a filePath; every decision has a sourceUrl
No invent — extraction never invents tech, paths, or alternatives missing from the source
Config-only providers — new LLM hosts are a providers.yaml change, never a new SDK
Domain owns policy — ranking and filters live in @codeoracle/core-domain, not in HTTP glue

Honest limits (read this)

Search / explain improve with a good index and embeddings. Prefer symbol-ish queries when you can (authorizeForRepo beats vague prose). Soft NL can still prefer docs over code — we’re tightening that with evals.
Decision extract quality follows your chat model and how much rationale exists in PR/commit text. Small or weak local models often produce thin or noisy decisions; stronger models (local or cloud) usually do better. Empty alternatives is often honest — the source never named an option.
CodeOracle narrows the haystack; it does not replace the coding model in your editor.
Prefer all-local providers when code must not leave your environment; use cloud chat only when you accept that extract payloads go to that API.

Architecture

Layers: blue = who calls in · green = runtimes · amber = product logic · indigo = storage and models.

Path	Flow
Ask	Editor → `mcp-server` → `retrieval` (+ `core-domain`) → Postgres / Qdrant → cited answer
Index	CLI/API → Redis → `worker` → `chunker` + `gateway` → Postgres + Qdrant
Extract	`worker` → `extraction` → `gateway` (chat) → decisions in Postgres (+ vectors)
Fresh	GitHub push → `api` (HMAC) → `incremental_reindex`

Packages never import apps. Shared shapes live in @codeoracle/contracts.

Tech stack

Area	Choice
Language	TypeScript, pnpm workspaces, Turborepo
Validation	Zod (`contracts`, `config`)
API / jobs	Node HTTP API, BullMQ on Redis
Metadata	Postgres 16, Drizzle ORM
Vectors	Qdrant (`code_chunks` hybrid, `decisions` dense)
Chunking	tree-sitter (TS/Python) + sliding-window fallback
Models	OpenAI-compatible `/v1` via `gateway` (Ollama default embed)
MCP	`@modelcontextprotocol/sdk` — stdio or Streamable HTTP
GitHub	Octokit + webhook HMAC
Tests	Vitest, Compose smoke, e2e, golden eval

Data model

Postgres is the source of truth. Qdrant stores vectors only.

Table	Purpose
`repos`	Registered repo, `index_status`, clone path, embedding model lock
`chunks`	Chunk text + metadata; `qdrant_point_id` links to the vector
`decisions`	WHY memory — `source_url` is NOT NULL
`github_sources`	Raw PR/commit bodies for extraction
`job_history`	Idempotency `(repo_id, job_type, dedupe_key)` + errors
`api_tokens`	Hashed per-repo bearer tokens (`co_…`)

Qdrant: code_chunks (dense + sparse), decisions (dense).

MCP result shapes (citations required) — packages/contracts/src/mcp.ts:

// search_codebase → { results: [{ chunkId, filePath, symbolName, content, score, repoId }] }
// explain_file    → { path, chunkSummaries, relatedDecisions: [{ topic, summary, sourceUrl, … }] }
// find_decision   → { results: [{ topic, summary, alternativesConsidered, sourceUrl, confidence, superseded }] }

Schema source: packages/db/src/schema/.

Jobs on queue codeoracle: full_index → chunk_file → embed_chunks → (optional) extract_decisions; webhooks enqueue incremental_reindex.

Quick start (≤ 10 minutes)

1. Install

git clone git@github.com:Jassu78/CodeOracle.git
cd CodeOracle
corepack enable
pnpm install

2. Config + data plane

cp .env.example .env
cp providers.yaml.example providers.yaml

cd infra/compose && docker compose up -d && cd ../..
pnpm db:migrate

Defaults match Compose (DATABASE_URL, REDIS_URL, QDRANT_URL).

3. Embeddings

ollama pull nomic-embed-text

Search works with embeddings alone. Enable a chat row in providers.yaml (and its API key, if any) only when you want decision extraction. Prefer a capable chat model for extract — tiny models are fine for experiments, weaker for production-quality decisions.

4. Worker + register + index

# Terminal A
pnpm worker

# Terminal B — local mirror (no GitHub PAT)
pnpm --filter @codeoracle/cli start -- repo register --local-path /absolute/path/to/your/repo
pnpm --filter @codeoracle/cli start -- repo index <repoId>
pnpm --filter @codeoracle/cli start -- repo status <repoId>   # wait for ready

GitHub: set GITHUB_PAT, then repo register --github OWNER/REPO.

Guided setup: pnpm --filter @codeoracle/cli start -- init.

5. Connect MCP

pnpm --filter @codeoracle/cli start -- mcp-config <repoId>

Paste into Cursor MCP settings (or .cursor/mcp.json), then reload.

Or:

export CODEORACLE_REPO_ID=<repoId>
pnpm mcp          # stdio
pnpm mcp:http     # HTTP — bearer required

6. Extract decisions (optional)

pnpm --filter @codeoracle/cli start -- decisions extract <repoId>
pnpm decisions:review <repoId>

Cap spend with EXTRACT_QUEUE_LIMIT / --limit N and EXTRACT_REPO_DAILY_TOKEN_BUDGET.

Try asking

Tool	Example
`search_codebase`	`where do we validate JWT`
`explain_file`	`apps/api/src/lib/auth.ts`
`find_decision`	`why hybrid ranking`

Prefer symbol names over vague NL when searching (verifyGitHubSignature beats “where do we verify webhooks”).

Configuration

File	Role
`.env` ← `.env.example`	Runtime env (fail-loud validation)
`providers.yaml` ← `providers.yaml.example`	Chat/embed endpoints (gitignored)

Required: DATABASE_URL, REDIS_URL, QDRANT_URL.

Common optional: GITHUB_PAT, GITHUB_WEBHOOK_SECRET, CODEORACLE_REPO_ID, API_TOKEN, MCP_HTTP_*, WORKER_CONCURRENCY, EXTRACT_*, provider *_API_KEY vars for enabled YAML rows.

Adding a provider = edit providers.yaml, set the key, enabled: true. Lower priority is tried first; failover on 429/5xx/network.

All-local example

chat:
  - id: ollama-local
    kind: chat
    baseUrl: http://localhost:11434/v1
    apiKeyEnv: null
    model: qwen2.5-coder:7b   # use the strongest local chat model you can run for extract
    priority: 1
    enabled: true
embeddings:
  - id: ollama-embed-local
    kind: embeddings
    baseUrl: http://localhost:11434/v1
    apiKeyEnv: null
    model: nomic-embed-text
    priority: 1
    enabled: true

MCP transports

Mode	Command	Auth
stdio	`pnpm mcp`	Editor spawns the process
Streamable HTTP	`pnpm mcp:http`	Bearer required (`API_TOKEN`, `MCP_HTTP_BEARER_TOKEN`, or scoped `co_…`)

HTTP listens on 127.0.0.1:3100/mcp by default. Open-dev is not allowed on HTTP.

{
  "mcpServers": {
    "codeoracle": {
      "command": "pnpm",
      "args": ["--dir", "/absolute/path/to/CodeOracle", "mcp"],
      "env": { "CODEORACLE_REPO_ID": "<repo-uuid>" }
    }
  }
}

CLI

pnpm --filter @codeoracle/cli start -- init
pnpm --filter @codeoracle/cli start -- doctor
pnpm --filter @codeoracle/cli start -- repo register --github OWNER/REPO
pnpm --filter @codeoracle/cli start -- repo register --local-path /abs/path
pnpm --filter @codeoracle/cli start -- repo index <repoId>
pnpm --filter @codeoracle/cli start -- repo status <repoId>
pnpm --filter @codeoracle/cli start -- repo recover <repoId>
pnpm --filter @codeoracle/cli start -- decisions extract <repoId> [--clear] [--limit N]
pnpm --filter @codeoracle/cli start -- decisions review <repoId>
pnpm --filter @codeoracle/cli start -- decisions failures <repoId>
pnpm --filter @codeoracle/cli start -- mcp-config <repoId>

Shortcuts: pnpm worker · pnpm api · pnpm mcp · pnpm mcp:http · pnpm db:migrate · pnpm decisions:review.

Webhooks

Set GITHUB_WEBHOOK_SECRET in .env and on GitHub.
Run pnpm api behind HTTPS in production.
Webhook URL: https://<host>/webhooks/github · JSON · Push (+ Ping).

Push → HMAC verify → incremental_reindex. See apps/api/README.md.

Auth

Principal	Use
Open-dev	No `API_TOKEN` and no `api_tokens` — local API only
`API_TOKEN`	Admin (any repo; mint tokens)
Per-repo `co_…`	Scoped to one `repoId`

MCP HTTP always needs a bearer.

Repo layout

apps/        api · worker · mcp-server · cli
packages/    contracts · config · db · core-domain · chunker
             gateway · retrieval · extraction · queue · observability
infra/       compose · docker images · ops helpers · ci notes
test/        sample-repo · golden eval · e2e
docs/        intro · specs · demo page

Production notes

Keep api + worker + mcp running; Compose for Postgres / Redis / Qdrant.
One worker only per Redis queue — duplicates keep stale code in memory after rebuilds. See infra/dogfood/README.md.
Terminate TLS in front of API (and MCP HTTP if remote).
Do not expose Postgres, Redis, Qdrant, or Ollama to the public internet.
Set API_TOKEN and webhook secret before exposing the API.
Images: infra/docker/README.md.
Full reindex recreates Qdrant code_chunks — fine for a single-repo deployment; plan multi-repo carefully.

Quality & CI

PRs need lint, typecheck, unit tests, Compose smoke, integration e2e, and golden eval. See infra/ci/README.md and CONTRIBUTING.md.

Live index replay (any ready repo): suite JSON + codeoracle replay <repoId> --suite test/replay/suites/….json — see test/replay/README.md. Complements fixture pnpm test:eval; does not replace it. CI runs golden eval + replay unit/schema tests; live product-index replay is an ops gate (needs a ready index + real embeddings).

Name		Name	Last commit message	Last commit date
.github		.github
apps		apps
docs		docs
infra		infra
packages		packages
scripts		scripts
test		test
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
providers.yaml.example		providers.yaml.example
tsconfig.base.json		tsconfig.base.json
turbo.json		turbo.json

Navigation Menu

Repository navigation

About

Repository files navigation

CodeOracle

Privacy & offline

What this is (and isn’t)

Why not “just ask Cursor”?

What you get

Honest limits (read this)

Architecture

Tech stack

Data model

Quick start (≤ 10 minutes)

1. Install

2. Config + data plane

3. Embeddings

4. Worker + register + index

5. Connect MCP

6. Extract decisions (optional)

Try asking

Configuration

MCP transports

CLI

Webhooks

Auth

Repo layout

Production notes

Quality & CI

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

CodeOracle

Privacy & offline

What this is (and isn’t)

Why not “just ask Cursor”?

What you get

Honest limits (read this)

Architecture

Tech stack

Data model

Quick start (≤ 10 minutes)

1. Install

2. Config + data plane

3. Embeddings

4. Worker + register + index

5. Connect MCP

6. Extract decisions (optional)

Try asking

Configuration

MCP transports

CLI

Webhooks

Auth

Repo layout

Production notes

Quality & CI

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages