Work / Infrastructure / The Infinite Catalog
PHAROS
What if code search had to prove which version of the code every answer came from?
Source auditedPublic repository ↗



The machine I built, one step per station
Follow one question through PHAROS.
This room is PHAROS’s pipeline: a repository goes in at the hopper, and cited, verified code comes out for an assistant. Pick a recorded repository, then open any machine and try the experiment at the top. Four run PHAROS’s own code in your browser; the rest replay real runs. What I built and decided is under the room.
RECORDED · PHAROS · 975a38d · 807 files → 7,272 chunks. Replay motion is explanatory, not a captured event log.
What runs here, and what is recorded Enter anywhere. Escape returns to the room.Enter anywhere. Close the book to return to the room.
Repository metrics are recordings. Parsing shows recorded symbols. Search and hashing execute here on the existing fixture; selecting a repository does not turn the fixture into a search of that repository. No external PHAROS service is contacted.
Contents
What’s in this book?
Three passes: a minute, how it works, then the deep dive. Stop after any one. Pick a page to open it in the book, or walk Valerie to a machine in the room.
- Pass 1 Overview 1 minute
- Pass 2 How it works 3 minutes
- What’s the idea, in one picture?
- Which repositories has PHAROS really indexed?Exhibit 1 RECORDED
- What will PHAROS refuse to index?Exhibit 2 RUNS HERE
- What does it read from a repository?Exhibit 3 RECORDED
- How does it cut code into pieces?Exhibit 4 RECORDED
- What does it turn into vectors, and what does indexing cost?Exhibit 5 RUNS HERE
- How does it know who calls whom?Exhibit 6 RECORDED
- Which retriever answered, and why that one?Exhibit 7 RUNS HERE
- What if the code changed after it was indexed?Exhibit 8 RUNS HERE
- What does an assistant get back?Exhibit 9 RECORDED
- How do the parts connect?
- Pass 3 Deep dive As long as you like
Pass 1 of 3
Overview
What PHAROS solves and why it matters, followed by one real question traced all the way through it. 1 minute
Pass 1 · Overview
What problem does PHAROS solve?
PHAROS gives an AI coding assistant real code it can cite, and proves which version of the code that is before handing it over.
Why it matters. An assistant reading a codebase gets whatever retrieval hands it. A stale chunk looks exactly like a current one, and a confident answer hides which is which. Most code search asks “what looks relevant?”. I built PHAROS around a stricter question: “what can be shown to be true at this commit?”.
- Measured: held-out nDCG@10 rose from 0.394 to 0.697 and from 0.463 to 0.726 on two locked sets of 101 questions, with a single annotator.
- Failed: repository memory missed its primary gate. It is shown below at the same size as the win.
Pass 1 · Overview
What did Ram build, and what changed?
My contribution
- What I built
- PHAROS itself, in Python and FastAPI: a Tree-sitter indexer for symbols, imports and calls; keyword and dense retrieval fused by rank, with mode routing (the audited auto mode chooses dense, hybrid or keyword; the SPLADE sparse retriever from its earlier search module is implemented, but auto does not route to the sparse retriever); verification of every cited source against its commit; and the REST and native MCP interfaces assistants call. Indexing and embedding run in asynchronous workers, apart from the API.
- The tradeoff I chose
- Provable over plentiful. When PHAROS can’t verify something, it returns less: a retrieval mode it can’t run fails out loud instead of quietly substituting another, a citation is checked against its Git blob before it is returned, and an ambiguous call stays unlinked rather than guessed. On its own code that leaves about three quarters of calls unlinked. I accepted that cost.
- What changed
- Held-out nDCG@10 rose from 0.394 to 0.697 and from 0.463 to 0.726 on two locked sets of 101 questionsreported · one annotator. Assistants get code they can cite to a commit, path and line span. And when repository memory missed the gates I set for it before writing it, the miss went on this page, not into a footnote.
Pass 1 · Overview
What happens to one question?
A real question from an AI assistant, followed from start to finish, with the measured time of each stage.
One question, end to end
RECORDED Replayed from a real run on November 2, 2026 at commit 975a38d (MCP trace pharos-verified-context). Nothing is running now.
A real question an assistant sent PHAROS over MCP, followed through every part it touched. Values and timings are from the recording at 975a38d.
AssistantAsks a question over MCP
“how is retrieved source checked against the git blob recorded at index time”
Tool retrieve_context, scoped to ram-tewari/pharos, at most 5 chunks.
PHAROSChecks who is asking
The bearer token is parsed and matched to a principal before the tool runs (parse_bearer, principal_for_token, allowed_for).
PHAROSPicks a mode: auto → dense
Asked for auto. An embedder was available (granite-embedding-english-r2-int8), so auto ran dense retrieval, and the response says so.
PHAROSTurns the question into a vector
One ONNX call: 4.36 ms.
PHAROSSearches the index by meaning
Nearest neighbours over pgvector: 12.2 ms, 50 candidates back.
PHAROSKeeps the best 5
Fused, filtered and hydrated with their spans in 1.84 ms.
Rank Symbol Where 1read_blobbackend/app/codeintel/git_source.py:383–4062git_sourcebackend/app/codeintel/git_source.py:1–4653file_evidencebackend/app/learning/memory.py:52–574read_file_at_commitbackend/app/codeintel/git_source.py:446–4615git_blob_shabackend/app/codeintel/source.py:85–86PHAROSFetches each file at its commit
5 HTTPS reads from GitHub at 975a38d. With the check, this is the slowest stage: 82.09 ms of 104.43 ms.
PHAROSHashes the bytes the way Git does
Each file's blob SHA is compared with the one recorded at index time. 5 of 5 matched, so all 5 are returned as verified.
read_blobverifiedgit_sourceverifiedfile_evidenceverifiedread_file_at_commitverifiedgit_blob_shaverifiedPHAROSAssembles cited context
Each chunk carries its path, line span and commit: about 1,349 tokens, inside the budget.
AssistantGets code it can cite, in 104.43 ms
Where the time went:
Stage Time Embed the question4.36 msSearch the index12.2 msFuse and hydrate1.84 msFetch and verify source82.09 msRelated symbols2.52 msTotal104.43 ms
Pass 1 · Overview
Has it really run?
Four recorded runs, each one told in a few short steps.
Run one question through it
RECORDED
Four real runs, recorded on 2026-11-02 at commit 975a38d (local mac, loopback only; not the deployed service). This page calls no PHAROS service: each step replays what came back.
Ask it a question
“how is retrieved source checked against the git blob recorded at index time”
AssistantAsks over MCP
retrieve_context, scoped to ram-tewari/pharos, mode auto.
PHAROSSearches by meaning (dense)
Auto mode could run dense retrieval, so it did, and said so. Top 3 of 5:
Rank Symbol Where 1read_blobbackend/app/codeintel/git_source.py:383–4062git_sourcebackend/app/codeintel/git_source.py:1–4653file_evidencebackend/app/learning/memory.py:52–57PHAROSChecks every file at its commit
Each file is re-read at 975a38d and hashed the way Git does. 5 of 5 matched the fingerprint recorded at index time.
read_blobverifiedgit_sourceverifiedfile_evidenceverifiedAssistantGets cited code
5 chunks with their path, lines and commit, about 1,349 tokens, inside the budget.
Every piece of code the assistant receives points at a commit, a path and a line span, and was checked against Git first.
Give it a hint
The same question, with hints: “git_blob_sha” and “content_mismatch”.
PHAROSHints switch auto to hybrid
It runs two searches: by name (50 candidates) and by meaning (50).
PHAROSFuses the two rankings
Reciprocal rank fusion: 1/(60+rank) per list, exact-name boost 1/61, path penalty ×0.7.
Symbol By name By meaning Fused git_blob_sha#1#5#1git_source#3#2#2read_blob#6#1#3Resultgit_blob_sha moves to the top
Meaning alone ranked the function that does the comparison #5. Its name ranked it #1, and fused it is #1.
Meaning and names fail differently. Fusing them recovered the exact function, and the response still reports the mode that ran.
Tamper with the record
Fetch backend/app/codeintel/source.py:141–162 three ways: honestly, with its fingerprint altered, and with none on record.
PHAROSThe SHA recorded at index time
The bytes match. The code is returned, verified.
resolvedPHAROSThe recorded SHA with its first hex digit changed
The bytes don’t match. The code is withheld, and the reason is returned instead.
unavailable:content_mismatchPHAROSNo SHA on record
Nothing to compare against. The code is returned, marked unverified.
resolved
A mismatch withholds the code instead of returning something that only looks right. Integrity is not correctness: a match proves the bytes, not the logic.
Take away the embedder
The same question, on a server with no embedding model, asked four ways.
PHAROSmode: auto
Auto falls back to keyword and warns: “dense retrieval unavailable (no embedding backend configured (EMBEDDING_BACKEND=none)); used keyword retrieval only”.
degradedPHAROSmode: dense
Refused with ModeUnavailable: no embedding backend configured (EMBEDDING_BACKEND=none).
refusedPHAROSmode: hybrid
Refused with ModeUnavailable: no embedding backend configured (EMBEDDING_BACKEND=none).
refusedPHAROSmode: graph
Refused with ModeUnavailable: no embedding backend configured (EMBEDDING_BACKEND=none).
refused
Auto may degrade, but it says so. A mode you ask for by name is never silently swapped for a weaker one.
Pass 2 of 3
How it works
The idea behind PHAROS, and then the room’s ten exhibits, in the order a repository flows through them. 3 minutes
Pass 2 · How it works
What’s the idea, in one picture?
Picture a librarian who files every page by the edition it came from, finds pages by meaning or by name, and checks the edition stamp before handing one over. If the stamp doesn’t match, you get nothing, not the wrong page.
- 01File it
Code is cut along its own structure, into functions and classes, and filed under the commit it came from.
- 02Keep pointers
The database keeps where code is, its vectors and who calls whom. The code itself stays in Git.
- 03Find, then check
A question is answered by meaning, by name or both. Then each file is re-read at its commit and its fingerprint compared.
- 04Hand it over
An assistant gets cited code through the same tool calls it uses for anything else.
Pass 2 · How it works · Exhibit 1 of 10 · The intake hopper RECORDED
Which repositories has PHAROS really indexed?
Pick a repository PHAROS really indexed.
Try Pick a repository from the shelf. Which part of indexing it took longest?
ram-tewari/PHAROS at 975a38d
- Files indexed
- 807 of 1,576 tracked
- Chunks
- 7,272
- Lines
- 222,275
- Graph edges
- 14,712
- Wall time
- 402.9 s
Languages indexed: Python 441, TypeScript 354, JavaScript 6, C 2, Java 1, C++ 1, Rust 1, Go 1. Skipped: 712 not source, 57 excluded path.
| Checkout | Parse | Embed | Database write | Graph |
|---|---|---|---|---|
| 2.323 s | 1.501 s | 368.889 s | 28.836 s | 1.229 s |
Indexed in this site's audit on 2026-11-02: PHAROS at 975a38d, macOS arm64, CPU only, granite-embedding-english-r2-int8, PostgreSQL 17.11 with pgvector 0.8.7.
pallets/click at 2247b35
- Files indexed
- 91 of 178 tracked
- Chunks
- 1,517
- Lines
- 30,383
- Graph edges
- 3,465
- Wall time
- 278.7 s
Languages indexed: Python 91. Skipped: 87 not source.
| Checkout | Parse | Embed | Database write | Graph |
|---|---|---|---|---|
| 0.016 s | 0.333 s | 271.053 s | 7.183 s | 0.114 s |
Reported by PHAROS in its retrieval benchmark, run 2026-10-30 by its code at 0b01729 on arm 18 CPUs, 36 GiB, none (CPU only), granite-embedding-english-r2-int8. Not rerun here.
sindresorhus/ky at 3541888
- Files indexed
- 98 of 115 tracked
- Chunks
- 997
- Lines
- 36,231
- Graph edges
- 1,672
- Wall time
- 118.9 s
Languages indexed: TypeScript 98. Skipped: 17 not source.
| Checkout | Parse | Embed | Database write | Graph |
|---|---|---|---|---|
| 0.023 s | 0.3 s | 113.707 s | 4.803 s | 0.054 s |
Reported by PHAROS in its retrieval benchmark, run 2026-10-30 by its code at 0b01729 on arm 18 CPUs, 36 GiB, none (CPU only), granite-embedding-english-r2-int8. Not rerun here.
dtolnay/anyhow at bb1b0f9
- Files indexed
- 37 of 54 tracked
- Chunks
- 438
- Lines
- 5,857
- Graph edges
- 622
- Wall time
- 60.4 s
Languages indexed: Rust 37. Skipped: 17 not source.
| Checkout | Parse | Embed | Database write | Graph |
|---|---|---|---|---|
| 0.024 s | 0.087 s | 58.075 s | 2.162 s | 0.05 s |
Reported by PHAROS in its retrieval benchmark, run 2026-10-30 by its code at 0b01729 on arm 18 CPUs, 36 GiB, none (CPU only), granite-embedding-english-r2-int8. Not rerun here.
curl/curl at 87c4c6d
- Files indexed
- 1,117 of 4,545 tracked
- Chunks
- 9,424
- Lines
- 316,221
- Graph edges
- 32,130
- Wall time
- 703.6 s
Languages indexed: C 1,060, Python 55, C++ 2. Skipped: 3,428 not source.
| Checkout | Parse | Embed | Database write | Graph |
|---|---|---|---|---|
| 0.024 s | 1.836 s | 659.763 s | 40.736 s | 1.137 s |
Reported by PHAROS in its retrieval benchmark, run 2026-10-30 by its code at 0b01729 on arm 18 CPUs, 36 GiB, none (CPU only), granite-embedding-english-r2-int8. Not rerun here.
go-chi/chi at 9f8adb1
- Files indexed
- 89 of 110 tracked
- Chunks
- 578
- Lines
- 13,152
- Graph edges
- 1,577
- Wall time
- 106.2 s
Languages indexed: Go 89. Skipped: 21 not source.
| Checkout | Parse | Embed | Database write | Graph |
|---|---|---|---|---|
| 0.012 s | 0.167 s | 103.27 s | 2.652 s | 0.057 s |
Reported by PHAROS in its retrieval benchmark, run 2026-10-30 by its code at 0b01729 on arm 18 CPUs, 36 GiB, none (CPU only), granite-embedding-english-r2-int8. Not rerun here.
google/gson at 5773104
- Files indexed
- 264 of 313 tracked
- Chunks
- 4,345
- Lines
- 57,131
- Graph edges
- 8,681
- Wall time
- 754.2 s
Languages indexed: Java 264. Skipped: 49 not source.
| Checkout | Parse | Embed | Database write | Graph |
|---|---|---|---|---|
| 0.023 s | 0.7 s | 730.578 s | 22.422 s | 0.39 s |
Reported by PHAROS in its retrieval benchmark, run 2026-10-30 by its code at 0b01729 on arm 18 CPUs, 36 GiB, none (CPU only), granite-embedding-english-r2-int8. Not rerun here.
immerjs/immer at 75a290e
- Files indexed
- 57 of 169 tracked
- Chunks
- 474
- Lines
- 17,865
- Graph edges
- 1,010
- Wall time
- 77.7 s
Languages indexed: TypeScript 29, JavaScript 28. Skipped: 112 not source.
| Checkout | Parse | Embed | Database write | Graph |
|---|---|---|---|---|
| 0.032 s | 0.203 s | 74.996 s | 2.416 s | 0.033 s |
Reported by PHAROS in its retrieval benchmark, run 2026-10-30 by its code at 0b01729 on arm 18 CPUs, 36 GiB, none (CPU only), granite-embedding-english-r2-int8. Not rerun here.
Eight indexing runs: PHAROS itself, and seven open-source repositories from its retrieval benchmark. Every number on a spine was recorded when PHAROS indexed that commit.
Pass 2 · How it works · Exhibit 2 of 10 · The intake hopper RUNS HERE
What will PHAROS refuse to index?
Admit the repository, or refuse it with a reason.
Try Type a repository URL. Try one that starts with http:// and see why it is refused before anything is cloned.
| Reference | Verdict | Raised at |
|---|---|---|
https://github.com/pallets/click | admitted as https://github.com/pallets/click | — |
pallets/click | admitted as https://github.com/pallets/click | — |
javascript:alert(1) | refused: “malformed repository URL” | :157 |
http://github.com/pallets/click | refused: “only https:// repository URLs are accepted” | :159 |
https://token@github.com/pallets/click | refused: “credentials in repository URLs are not accepted; configure GIT_CLONE_TOKEN instead” | :161 |
https://github.com:8443/pallets/click | refused: “custom ports are not accepted in repository URLs” | :165 |
https://github.com/pallets/click?tab=readme | refused: “repository URLs must not contain a query or fragment” | :167 |
https://127.0.0.1/pallets/click | refused: “IP-address hosts are not accepted” | :170 |
https://example.com/pallets/click | refused: “host 'example.com' is not in CODEINTEL_ALLOWED_GIT_HOSTS” | :173 |
https://github.com/pallets/click/tree/main | refused: “expected a URL of the form https://host/owner/repo” | :179 |
/home/me/repo | refused: “local repositories can only be indexed from the CLI” | :144 |
Before anything is cloned, PHAROS checks the reference. Type any repository URL: this is PHAROS's own check, ported line for line and running in your browser.
Pass 2 · How it works · Exhibit 3 of 10 · The intake hopper RECORDED
What does it read from a repository?
Read only what Git tracks at that commit.
Try Drag the time dial to replay the clone, and watch the hopper and the counters follow it.
Replay: PHAROS
RECORDED
- Tracked
- 1,576
- Indexed
- 807
- Not source
- 712
- Excluded
- 57
.github/workflows/ci.ymlnot source.kiro/hooks/external-discovery-cache-invalidation.jsonnot source.kiro/specs/README.mdnot source.kiro/specs/backend/ml-model-training/tasks.mdnot source.kiro/specs/backend/phase11-5-ml-benchmarking/design.mdnot source.kiro/specs/backend/phase12-fowler-refactoring/tasks.mdnot source.kiro/specs/backend/phase16-7-missing-features-implementation/requirements.mdnot source.kiro/specs/backend/phase19-hybrid-edge-cloud-orchestration/SECURITY_UPDATES.mdnot source
The names are a sample, about one in every 14 tracked files at the pinned commit; each verdict is PHAROS's ported skip rule. Counts and times are the recorded run's. Times are compressed.
Change PHAROS's fixture and re-index
RUNS HERE
Sixteen files of PHAROS's test repository, each hashed as a Git blob in your browser. Change one and only it is re-indexed; the rest only move their commit pointer (indexer.py:245).
android/src/com/tinyshop/CartActivity.javaunchangednative/c/checksum.cunchangednative/c/checksum.hunchangednative/cpp/geometry.cppunchangednative/src/lib.rsunchangedshop/__init__.pyunchangedshop/api.pyunchangedshop/auth.pyunchangedshop/cart.pyunchangedshop/db.pyunchangedtests/test_cart.pyunchangedtools/ratelimit/limiter.gounchangedweb/client.jsunchangedweb/format.jsunchangedweb/session.tsunchangedweb/types.tsunchanged
PHAROS lists the files Git tracks at the exact revision, skips what is not source code, and on a re-index touches only files whose blob SHA changed. Replay the repository you chose, then change PHAROS's own fixture and watch the diff.
For engineersOpen detail
- A bare shallow clone is read with
git cat-fileat a pinned commit, so symlinks and submodules cannot escape the repository, and repository code is parsed, never run. - Remote repositories must be https on an allowlisted host. Local paths can only be registered through the CLI, so API callers cannot reach the worker's filesystem.
- Jobs live in PostgreSQL with atomic claims and retries. Read the claim.
- Files are compared by Git blob SHA. Unchanged files only move their commit pointer. Read the diff.
- The last commit is written after everything else, so a failed run leaves the previous index searchable. Read the run.
Pass 2 · How it works · Exhibit 4 of 10 · The branching manuscript RECORDED
How does it cut code into pieces?
Split each file into symbols.
Try Pick a symbol and see the exact lines PHAROS cut for it.
shop/auth.py
RECORDED
1"""Password hashing and session tokens.""" 2 3import hashlib 4import hmac 5import secrets 6import time 7 8from .db import fetch_user 9 10TOKEN_TTL_SECONDS = 3600 11 12 13def hash_password(password: str, salt: bytes | None = None) -> str: 14 """Derive a salted PBKDF2 hash for storing a user's password.""" 15 salt = salt or secrets.token_bytes(16) 16 digest = hashlib.pbkdf2_hmac("sha256", password.encode(), salt, 200_000) 17 return salt.hex() + ":" + digest.hex() 18 19 20def verify_password(password: str, stored: str) -> bool: 21 """Check a plaintext password against a stored PBKDF2 hash in constant time.""" 22 salt_hex, digest_hex = stored.split(":", 1) 23 candidate = hash_password(password, bytes.fromhex(salt_hex)) 24 return hmac.compare_digest(candidate.split(":", 1)[1], digest_hex) 25 26 27def authenticate(username: str, password: str) -> dict | None: 28 """Log a user in: look them up and verify the password.""" 29 user = fetch_user(username) 30 if user is None or not verify_password(password, user["password_hash"]): 31 return None 32 return user 33 34 35class TokenSigner: 36 """Issues and validates HMAC-signed session tokens.""" 37 38 def __init__(self, secret: bytes): 39 self.secret = secret 40 41 def issue(self, user_id: int, now: float | None = None) -> str: 42 """Create a signed token that expires after TOKEN_TTL_SECONDS.""" 43 expires = int((now or time.time()) + TOKEN_TTL_SECONDS) 44 payload = f"{user_id}.{expires}" 45 return payload + "." + self._sign(payload) 46 47 def verify(self, token: str, now: float | None = None) -> int | None: 48 """Return the user id for a valid, unexpired token, else None.""" 49 try: 50 user_id, expires, signature = token.rsplit(".", 2) 51 except ValueError: 52 return None 53 if not hmac.compare_digest(signature, self._sign(f"{user_id}.{expires}")): 54 return None 55 if int(expires) < (now or time.time()): 56 return None 57 return int(user_id) 58 59 def _sign(self, payload: str) -> str: 60 return hmac.new(self.secret, payload.encode(), hashlib.sha256).hexdigest()
9 chunks: one per function, class and method, plus the module. Parser: Python ast.
web/session.ts
RECORDED
1import { Session } from "./types"; 2 3/** Decode the expiry embedded in a session token ("<user>.<expires>.<sig>"). */ 4export function tokenExpiry(token: string): number { 5 const [, expires] = token.split("."); 6 return Number(expires) * 1000; 7} 8 9/** Keeps the current session and refreshes it shortly before it expires. */ 10export class SessionManager { 11 private session: Session | null = null; 12 13 /** True when there is a session whose token has not expired yet. */ 14 isLoggedIn(now: number = Date.now()): boolean { 15 return this.session !== null && tokenExpiry(this.session.token) > now; 16 } 17 18 start(session: Session): void { 19 this.session = session; 20 } 21}
5 chunks: one per function, class and method, plus the module. Parser: tree-sitter.
native/src/lib.rs
RECORDED
1//! Native helpers for tinyshop. 2 3use std::fmt; 4 5/// CRC-32 (IEEE) checksum used to verify uploaded product images. 6pub fn crc32(data: &[u8]) -> u32 { 7 let mut crc: u32 = 0xFFFF_FFFF; 8 for &byte in data { 9 crc ^= byte as u32; 10 for _ in 0..8 { 11 let mask = (!(crc & 1)).wrapping_add(1); 12 crc = (crc >> 1) ^ (0xEDB8_8320 & mask); 13 } 14 } 15 !crc 16} 17 18/// A money amount in integer cents. 19pub struct Cents(pub i64); 20 21impl fmt::Display for Cents { 22 /// Format cents as dollars, e.g. `1250` -> `$12.50`. 23 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 24 write!(f, "${}.{:02}", self.0 / 100, self.0 % 100) 25 } 26}
5 chunks: one per function, class and method, plus the module. Parser: tree-sitter.
tools/ratelimit/limiter.go
RECORDED
1// Package ratelimit throttles API clients with a token bucket. 2package ratelimit 3 4import ( 5 "sync" 6 "time" 7) 8 9// Bucket is a token-bucket rate limiter. 10type Bucket struct { 11 mu sync.Mutex 12 capacity float64 13 tokens float64 14 rate float64 15 last time.Time 16} 17 18// NewBucket creates a bucket that refills `rate` tokens per second. 19func NewBucket(capacity, rate float64) *Bucket { 20 return &Bucket{capacity: capacity, tokens: capacity, rate: rate, last: time.Now()} 21} 22 23// Allow reports whether one request may proceed, consuming a token if so. 24func (b *Bucket) Allow() bool { 25 b.mu.Lock() 26 defer b.mu.Unlock() 27 b.refill(time.Now()) 28 if b.tokens < 1 { 29 return false 30 } 31 b.tokens-- 32 return true 33} 34 35// refill adds tokens for the time elapsed since the last call. 36func (b *Bucket) refill(now time.Time) { 37 elapsed := now.Sub(b.last).Seconds() 38 b.tokens = min(b.capacity, b.tokens+elapsed*b.rate) 39 b.last = now 40}
5 chunks: one per function, class and method, plus the module. Parser: tree-sitter.
android/src/com/tinyshop/CartActivity.java
RECORDED
1package com.tinyshop; 2 3import java.util.ArrayList; 4import java.util.List; 5 6/** Android screen listing the items in the cart. */ 7public class CartActivity { 8 private final List<String> skus = new ArrayList<>(); 9 10 /** Called when the user taps "remove" next to an item. */ 11 public void onRemoveClicked(String sku) { 12 skus.remove(sku); 13 refreshList(); 14 } 15 16 private void refreshList() { 17 System.out.println("cart now has " + skus.size() + " items"); 18 } 19}
4 chunks: one per function, class and method, plus the module. Parser: tree-sitter.
app/models/order.rb Ruby has no grammar in PHAROS
RUNS HERE
order.rb:1-60first line:puts 'line 1'order.rb:51-110first line:puts 'line 51'order.rb:101-130first line:puts 'line 101'
Windows of 60 lines overlapping by 10, recorded as line-fallback with the reason unsupported_language.
In the run you chose, PHAROS:
Each function, class and method becomes its own chunk with exact line numbers. Pick a file from PHAROS's fixture to see what its parser returned; a language with no grammar is cut into overlapping line windows, live, and the fallback is recorded rather than hidden.
For engineersOpen detail
- Python uses the standard library's
ast. JavaScript, TypeScript, Go, Rust, C, C++ and Java use tree-sitter. Read the dispatch. - Ruby, PHP, Swift, Kotlin, Scala and C# have no grammar wired up, and their files use line windows recorded as fallback.
Pass 2 · How it works · Exhibit 5 of 10 · The sorted shelves RUNS HERE
What does it turn into vectors, and what does indexing cost?
Embed a summary of the code, not the code.
Try Pick another symbol and watch which dimensions of its vector are set.
What gets embedded is a short text built from the symbol: its file and name, signature, docstring, up to 25 lines of body and the calls it makes. Pick a symbol: the text, the full-text tokens and an offline hash vector are built in your browser by PHAROS's own code.
For engineersOpen detail
- A chunk is embedded from its signature, docstring, calls and first body lines, not raw source. Read the summary.
- HNSW serves vectors and GIN serves full text. Read the indexes.
- The tradeoff is real: the project measures pointer storage as saving about 5% of the database, because vectors and their index dominate.
What indexing does to a repository
RECORDED Replayed from a real run on November 2, 2026 at commit 975a38d (self-index run, macOS arm64, CPU only). Nothing is running now.
PHAROS indexing its own repository at 975a38d: which files it keeps, what it cuts them into, and where the 402.9 s went.
PHAROSChecks out the commit
1,576 tracked files at 975a38d, in 2.3 s.
PHAROSKeeps only source
712 are not source (docs, specs, configs) and 57 sit on excluded paths. 807 files remain.
PHAROSParses each file into its syntax tree
222,275 lines in 1.5 s. No file fell back to plain line splitting.
PHAROSCuts at function and class boundaries
7,272 chunks, each a whole symbol with its path and line span, never a window cut mid-function.
PHAROSEmbeds every chunk
368.9 s of the 402.9 s, on a CPU with no GPU. By far the slowest step.
PHAROSWrites the index
Chunks, vectors and blob SHAs into Postgres with pgvector in 28.8 s.
PHAROSLinks calls it can prove
6,977 calls resolved, 17,764 left unresolved and 2,888 ambiguous: a call is linked only when PHAROS can tell which function it means. 1.2 s.
Stage Time Checkout2.3 sParse1.5 sEmbed368.9 sWrite28.8 sCall graph1.2 sTotal402.9 s
Pass 2 · How it works · Exhibit 6 of 10 · The relationship engine RECORDED
How does it know who calls whom?
Link calls, and leave the doubtful ones unlinked.
Try Compare the linked calls with the unlinked ones. PHAROS draws a line only where it could tell which function was meant.
Calls in PHAROS
RECORDED
6,977 of 27,629 calls linked (25%). 14,712 edges in all, counting contains and imports.
Calls in click
RECORDED
1,863 of 5,087 calls linked (37%). 3,465 edges in all, counting contains and imports.
Calls in ky
RECORDED
609 of 3,041 calls linked (20%). 1,672 edges in all, counting contains and imports.
Calls in anyhow
RECORDED
206 of 613 calls linked (34%). 622 edges in all, counting contains and imports.
Calls in curl
RECORDED
20,684 of 33,059 calls linked (63%). 32,130 edges in all, counting contains and imports.
Calls in chi
RECORDED
980 of 2,450 calls linked (40%). 1,577 edges in all, counting contains and imports.
Calls in gson
RECORDED
3,613 of 15,270 calls linked (24%). 8,681 edges in all, counting contains and imports.
Calls in immer
RECORDED
541 of 1,390 calls linked (39%). 1,010 edges in all, counting contains and imports.
| Run | Same file | Through an import | Unique name | Unresolved | Ambiguous |
|---|---|---|---|---|---|
| PHAROS | 2,073 | 2,818 | 2,086 | 17,764 | 2,888 |
| click | 406 | 308 | 1,149 | 2,078 | 1,146 |
| ky | 227 | 147 | 235 | 2,350 | 82 |
| anyhow | 98 | 27 | 81 | 310 | 97 |
| curl | 5,072 | 2,311 | 13,301 | 8,792 | 3,583 |
| chi | 211 | 16 | 753 | 1,028 | 442 |
| gson | 1,382 | 1,734 | 497 | 6,039 | 5,618 |
| immer | 244 | 18 | 279 | 717 | 132 |
SOURCE-DERIVED
The relationship engine
What calls _resolve_one, and what it calls.
| Relation | Symbol | Resolution |
|---|---|---|
| called by | codeintel.source.resolve_sources | same_file |
| calls | codeintel.source._load | same_file |
| calls | codeintel.source._slice | same_file |
| calls | codeintel.source.git_blob_sha | same_file |
| calls | codeintel.source.SourceResult | same_file |
Drawn from the real neighbourhood of one symbol. Unresolved calls stay absent.
A call is linked only when PHAROS can tell which function it means: in the same file, through an import, or by a name defined once. Everything else stays unlinked and is counted.
For engineersOpen detail
- PHAROS's own graph resolved 6,977 calls and left 17,764 unresolved and 2,888 ambiguous; most unresolved calls reach the standard library or dependencies. Walk it.
- Graph mode adds callers and callees of the top five hits, ranked below the hit that pulled them in.
Pass 2 · How it works · Exhibit 7 of 10 · The lit stacks RUNS HERE
Which retriever answered, and why that one?
Ask, and see which retriever answered.
Try In Auto, switch the embedder off, then force Dense. One falls back with a warning; the other refuses.
Keyword BM25
Dense cosine
What PHAROS returns
Fusion adds 1/(60 + rank) from each list (retrieval.py:431), plus 1/61 when the question names the symbol (:446); tests, docs and examples are then multiplied by 0.7 unless asked for (:511).
Recorded from PHAROS: “verify a user's password”, hybrid
RECORDED
| # | Symbol | Keyword rank | Dense rank | Score |
|---|---|---|---|---|
| 1 | shop.auth.authenticate | 2 | 1 | 0.0325 |
| 2 | shop.auth.verify_password | 1 | 3 | 0.0323 |
| 3 | shop.db.save_user | 5 | 2 | 0.0315 |
| 4 | shop.auth.TokenSigner.verify | 3 | 5 | 0.0313 |
| 5 | shop.auth.hash_password | 4 | 7 | 0.0306 |
PHAROS's Retriever at 975a38d on its tinyshop fixture, SQLite, hash-v1 embedder. The page reproduces this ranking exactly.
RECORDED
The lit stacks
The same question, ranked two ways.
How is retrieved source checked against the Git blob? One recorded question, chosen for this page. It is not a quality measurement.
| Rank | Dense, no hints | Hybrid, with hints |
|---|---|---|
| 1 | git_source.Checkout.read_blob | source.git_blob_sha |
| 2 | git_source | git_source |
| 3 | learning.memory.file_evidence | git_source.Checkout.read_blob |
| 4 | git_source.read_file_at_commit | source |
| 5 | source.git_blob_sha | git_source.Checkout._git |
RECORDED Captured from a real run on November 2, 2026. Nothing is running now.
Lights respond to the recorded answer. This is not a new search.
auto prefers the dense retriever, switches to hybrid when the caller passes identifier hints, and falls back to keyword with a warning when dense cannot run. Search PHAROS's fixture with its own retrieval code, switch the embedder off, and watch two rankings fuse.
For engineersOpen detail
- Keyword is PostgreSQL full-text. Dense is pgvector cosine through HNSW. Hybrid is reciprocal rank fusion with k=60, plus an exact-name boost of 1/61. Read the fusion.
- Tests, docs and examples are multiplied by 0.7 after fusion, unless the question asks for them. Read the penalty.
- With no embedder, auto degrades to keyword with a warning, and asking for dense is refused. See it happen.
- Scope is a filter the caller chooses. A call naming no repository searches the whole index.
- The page searches with SQLite's path (Python BM25 and exact cosine), which PHAROS uses without PostgreSQL. The service ranks keywords with
ts_rank_cdinstead.
How auto picks a retrieval mode
RUNS HERE PHAROS’s mode routing, ported to the browser at 975a38d (packages/pharos-web) runs in this page. No service, model or device is involved.
Choose what the caller asks for and what the server has. PHAROS’s own routing, ported to this page, decides; the diagram shows the route it took and what it returned. The SPLADE sparse retriever is implemented in PHAROS, but auto never routes to it, so it is not on this map.
CallerAsks for a mode
auto, or a mode by name, with or without hints. The router first asks whether dense retrieval can run: is there an embedder, and was the index embedded with the same model?
Routerauto, embedder ready, no hints: dense
Search by meaning, and the response says dense was used.
Routerauto with hints: hybrid
Two searches, by name and by meaning, fused by reciprocal rank, plus a boost for an exact symbol name.
Routerauto without a usable embedder: keyword, with a warning
It degrades, and says so in the response: “dense retrieval unavailable (…); used keyword retrieval only”.
Routerkeyword by name: keyword
Asked for by name, it needs no embedder, so it runs as asked.
RouterA named mode that can’t run: refused
Dense or hybrid asked for by name, with no usable embedder, fails with ModeUnavailable. It is never quietly swapped for a weaker mode.
Ask PHAROS about its own code The same retrieval, in your browser, over the index PHAROS built of itself.
Pass 2 · How it works · Exhibit 8 of 10 · The magnifying lectern RUNS HERE
What if the code changed after it was indexed?
Check the source before handing it over.
Try Change one character of the source, and watch PHAROS refuse to hand it over. Then put it back.
backend/app/codeintel/source.py at 975a38d MIT licence. Lines 141–162 are _resolve_one.
- Expected, from Git's tree
c9f05cf7bf871b09919d64e9fdaf8380ecc3df2c- Hashed now, in your browser
…
| Expected SHA | Status | Code returned | Verified |
|---|---|---|---|
| The SHA recorded at index time | resolved | yes | yes |
| The recorded SHA with its first hex digit changed | unavailable:content_mismatch | no | no |
| No SHA on record | resolved | yes | no |
RECORDED Captured from a real run on November 2, 2026. Nothing is running now.
Check the expected SHA yourself: git rev-parse 975a38d:backend/app/codeintel/source.py
PHAROS fetches the file at the indexed commit and hashes it the way Git does. Change one character below and it refuses to return the code.
The recorded integrity cases Source verification in the explorer
Tamper with the record
RECORDED Replayed from a real run on November 2, 2026 at commit 975a38d (integrity cases pharos-integrity-cases). Nothing is running now.
The same 22 lines, backend/app/codeintel/source.py:141–162, fetched three times: with the fingerprint recorded at index time, with that fingerprint altered by one digit, and with none on record.
PHAROSFetches the file at the indexed commit
backend/app/codeintel/source.py:141–162 at 975a38d.
PHAROSHashes the bytes the way Git does
The actual blob SHA is c9f05cf7bf871b09919d64e9fdaf8380ecc3df2c.
Case 1The SHA recorded at index time
The two fingerprints match. The code is returned, marked verified.
resolvedCase 2The recorded SHA with its first hex digit changed
Recorded 09f05cf7bf87…, actual c9f05cf7bf87…. The code is withheld and the reason returned instead.
unavailable:content_mismatchCase 3No SHA on record
Nothing to compare against. The code is returned, but marked unverified, never as verified.
resolvedverified: false
Pass 2 · How it works · Exhibit 9 of 10 · The trace journal RECORDED
What does an assistant get back?
Hand an agent cited, budgeted context.
Try Open the recorded answer an assistant received, and follow one citation to its commit.
The assistant asks
RECORDED
retrieve_context( query="how is retrieved source checked against the git blob recorded at index time", repository="ram-tewari/pharos", max_chunks=5, include_memory=false )
PHAROS answers
RECORDED
# Code context for: how is retrieved source checked against the git blob recorded at index time ## [1] backend.app.codeintel.git_source.Checkout.read_blob (method) — ram-tewari/pharos:backend/app/codeintel/git_source.py:383-406 ✓ source verified at the commit; code returned ## [2] backend.app.codeintel.git_source (module) — ram-tewari/pharos:backend/app/codeintel/git_source.py:1-465 ✓ source verified at the commit; code returned ## [3] backend.app.learning.memory.file_evidence (function) — ram-tewari/pharos:backend/app/learning/memory.py:52-57 ✓ source verified at the commit; code returned ## [4] backend.app.codeintel.git_source.read_file_at_commit (function) — ram-tewari/pharos:backend/app/codeintel/git_source.py:446-461 ✓ source verified at the commit; code returned ## [5] backend.app.codeintel.source.git_blob_sha (function) — ram-tewari/pharos:backend/app/codeintel/source.py:85-86 ✓ source verified at the commit; code returned ## Related code (call graph) - imported_by: backend.app.cli — backend/app/cli.py:1-463 - imported_by: backend.app.codeintel.context — backend/app/codeintel/context.py:1-360 - imported_by: backend.app.codeintel.indexer — backend/app/codeintel/indexer.py:1-563 - imported_by: backend.app.codeintel.jobs — backend/app/codeintel/jobs.py:1-302 … and 8 more
- Characters
- 5,396
- About tokens
- 1,349
- Truncated
- no
- Retrieval
- 18.41 ms
- Verifying source
- 82.09 ms
Headings rebuilt in PHAROS's own format (context.py:321) from the recorded fields. The code bodies were verified and returned but not stored here; the full text's SHA-256 is c4b4be41c1a6887e…. Mode used: dense.
RECORDED Captured from a real run on November 2, 2026. Nothing is running now.
The eight tools an assistant can call
SOURCE-DERIVED
retrieve_context- Ranked functions and classes with verified source, their callers and callees, and what PHAROS learned about the repository.
search_code- Chunk pointers (path, lines, symbol) with retrieval evidence, no code. auto, keyword, dense, hybrid or graph.
find_symbol- Where a symbol is defined, with its callers and callees.
get_repo_brief- What the repository is, its layout, main modules and strongest conventions, in at most 2,200 characters.
search_memory- Conventions, files that change together, and history, learned from the repository.
list_skills- How recurring changes are made in the repository, one line each.
get_skill- One playbook: its steps and example commits.
list_repositories- Indexed repositories with their commit, language coverage and status.
All read-only, over streamable HTTP (native_server.py:79).
An assistant calls PHAROS over MCP and gets back ranked code it can cite: each chunk with its repository, path and lines, the code itself when it verified, and related functions from the graph, cut to a character budget.
Pass 2 · How it works
How do the parts connect?
All twelve parts of the system on a single map. Pick any part to see what it hands on to the next one.
PHAROS, in twelve partsOpen diagram
01 File it Index
02 Keep pointers Store
03 Find, then check Serve
04 Hand it over Interface
Source verification Recorded run
Re-reads the file at its commit and checks its Git fingerprint before anything is returned.
Hands to Context assembly.
Its deep diveEvery connection, as a table
| From | Hands over | To |
|---|---|---|
| Ingestion jobs | runs | Indexer |
| Indexer | parses with | Parsers |
| Indexer | embeds with | Embeddings |
| Indexer | rebuilds | Call graph |
| Parsers | chunks | PostgreSQL store |
| Embeddings | vectors | PostgreSQL store |
| Call graph | edges | PostgreSQL store |
| PostgreSQL store | searched by | Retriever |
| Retriever | ranked hits | Context assembly |
| Source verification | verified code | Context assembly |
| Repository memory | memory block | Context assembly |
| Context assembly | retrieve_context | MCP server |
| Context assembly | /context/retrieve | REST API |
| Retriever | search_code | MCP server |
| Retriever | /search/code | REST API |
Integrity checking proves the bytes match the indexed commit. It says nothing about whether the code is correct or secure.
Pass 3 of 3
Deep dive
Whether it worked and what failed, every part with its source code, and how the project got to where it is. As long as you like
Pass 3 · Deep dive · Exhibit 10 of 10 · The curtained shelf REPORTED
Did it work?
What it achieved, and what failed.
Try Put the retrieval gain beside the memory gate that failed.
Retrieval improved on questions it had never seen
REPORTED
| Held-out set | Before | After |
|---|---|---|
| Held-out set 1 | 0.394 | 0.697 |
| Held-out set 2 | 0.463 | 0.726 |
Reported From PHAROS's benchmark report, not rerun here. One annotator, who also built the system; CPU. nDCG@10 scores how close the right code sits to the top, from 0 to 1.
Repository memory v1 failed its primary gates
REPORTED
| Gate | Target | Result | Verdict |
|---|---|---|---|
| Precision of what memory claims (audited) | 90% | 55% | ✕ failed |
| Primary: source-file recall | must improve | 0.827 → 0.823 | ✕ failed |
| Repository questions answered (secondary) | reported | 5 → 14 of 30 | secondary measure |
| File-selection precision, 80 tasks (secondary) | reported | 63.4% → 77.5% | secondary measure |
Reported The precision and recall gates failed, so memory v1 is not a success, whatever the secondary measures say. The file-precision figure is owner-confirmed and stays beside the gates that failed.
15 milestones, each linked to its commit
SOURCE-LINKED
- Similarity moves into pgvector
- The knowledge-management product is removed
- Module boundaries become a CI gate
- A real MCP server
- Today's core: chunk-level indexing and hybrid retrieval
- Migrations squashed, code index schema added
- Two tokens, and working MCP on the new core
- Retrieval gets a benchmark
- Free deployment with CPU embeddings
- Granite embeddings and dense by default
- Query embedding can run off the host
- The memory evaluation is locked first
- Memory fails its locked evaluation
- Memory claims must prove themselves
- The second evaluation stops with no verdict
Retrieval improved on held-out questions. Repository memory did not pass its own gates, and it stays here at the same size as the success.
I locked two held-out sets of code questions across seven repositories before the final measurement, and ran each once.
| Held-out set | Baseline | Improved |
|---|---|---|
| Held-out set 1 | 0.394 | 0.697 |
| Held-out set 2 | 0.463 | 0.726 |
Reported One annotator, CPU. From the project’s own evaluation; not rerun for this site.
nDCG@10 scores how close the right code sits to the top of the results, from 0 to 1.
What it cost. Questions that name the API scored slightly lower without hints, 0.987 → 0.907 and 0.982 → 0.931, because dense retrieval ranks most named symbols first but not all. Passing hints brought the first set back to 0.991. Reported
How it works7 claims, each with how it is known
PHAROS indexes committed code using AST-aware chunks and incremental blob-SHA checks.
PHAROS supports keyword, dense, hybrid and graph retrieval; auto prefers dense, hybrid with hints, keyword fallback with warnings.
Explicit unavailable semantic modes fail; auto can degrade with a warning. Repository scope is a filter the caller chooses; a call naming no repository searches the whole index.
Implemented dense, SPLADE sparse and lexical retrieval with reciprocal-rank fusion.
In the commit audited for this site, auto mode does not route to the sparse retriever.
Source context is checked against the indexed Git blob SHA.
Integrity checking is not semantic code correctness or security certification.
Call/import graph resolution is conservative; ambiguous calls remain unresolved.
Native MCP exposes search, context, symbol, repository and repository-memory tools.
PHAROS runs indexing and embedding in asynchronous workers separate from its cloud API, with GitHub-referenced source storage to limit duplicated repository data.
The deployed service was not inspected for this site.
A line marked owner confirmed is stated on my November 2026 résumé. It is my own account, and it was not re-measured for this site.
Measured and recorded6 claims, each with how it is known
Reported nDCG@10 improved 0.394 to 0.697 and 0.463 to 0.726 on two locked held-out sets totaling 101 questions.
Seven repositories and languages, single annotator, CPU. Read from project documentation; not reproduced for this site.
After retrieval phase 1, questions that name the API scored slightly lower without hints (nDCG@10 0.987 → 0.907 and 0.982 → 0.931); hints brought the first set back to 0.991.
From the retrieval phase 1 report at 975a38d. Shown beside the result as its recorded cost.
In a recorded run at commit 975a38d, a question sent through native MCP returned five chunks, each fetched from GitHub and matched against its indexed Git blob.
One local run with a question chosen by the author. Not a benchmark and not the deployed service.
In a recorded run, changing the expected blob SHA made PHAROS withhold the source and report a content mismatch.
With no SHA on record, source is returned marked unverified.
In a recorded run with no embedder, auto used keyword retrieval with a warning, and explicit dense, hybrid and graph modes were refused.
Indexing PHAROS at commit 975a38d resolved 6,977 calls and left 17,764 unresolved and 2,888 ambiguous.
Most unresolved calls reach the standard library or dependencies. PHAROS leaves them unlinked by design.
Pass 3 · Deep dive
What didn’t work?
Repository memory v1 failed its primary gates.
- Audited precision
- 55%
- Primary source-file recall
- 0.827 to 0.823
- Repo Q&A, secondary only
- 5 to 14 of 30
- File precision, secondary only
- 0.634 to 0.775
I wrote the gates before any memory code existed. Repo Q&A and file precision improved, but neither was the primary metric. A secondary win does not rescue a failed primary gate, so the numbers stay together, at the same size as the success. That is the point of setting the bar first.
The two claims, with how each is known2 claims, each with how it is known
Repository memory v1 failed its primary source-file recall and precision gates; audited precision was 55%.
Primary source-file recall went from 0.827 to 0.823. Repo Q&A, a secondary measure, improved from 5 to 14 of 30.
In an 80-task evaluation of Git-history memory, file-selection precision rose from 63.4% to 77.5%, while unsupported memory claims were audited.
Memory v1 still failed its primary gates: audited precision was 55%, and primary source-file recall did not improve.
A line marked owner confirmed is stated on my November 2026 résumé. It is my own account, and it was not re-measured for this site.
Smaller findings from these recordings
- Dense retrieval ranked the function that does the comparison fifth for a question about exactly that. Hints moved it to first, and the project reports that hints help less on code a model has not seen.
- On PHAROS's own code, the graph resolved about a quarter of attempted calls. Most of the rest reach libraries, and that is the cost of never guessing.
- Concurrent source fetches can read the same file more than once, because the cache has no single-flight.
Pass 3 · Deep dive
How does each part work, exactly?
Every part of the system, where its responsibility ends, and how each of those facts is known.
Each part below opens to what it does, where it stops, and how that is known: its pinned source at 975a38d, the recorded runs that passed through it, and its page in the explorer.
Index File it
Ingestion jobsA durable queue in the database. Workers claim jobs atomically.Source audited
Queue state lives in PostgreSQL, so a job survives a restart. Redis is optional and only wakes workers, which also poll.
Stalled workers are recovered, and retries back off. On the free deployment the API cannot index, so jobs wait for a separate worker.
Limits
- Job recovery was covered by the project's tests, not exercised in a recorded run here.
Proof
- backend/app/codeintel/jobs.py, lines 118–141 pinned source at the indexed commit
- Ingestion jobs in the explorer highlighted source and every span
IndexerBrings the index in line with one commit, by blob SHA.Source audited
Tracked files are compared with the index by Git blob SHA. New and changed files are parsed and embedded; unchanged files only move their commit pointer.
The repository's last commit is written after everything else succeeds. A failed run leaves the previous index searchable.
Limits
- Source is not stored. Reading it later depends on the Git host being reachable.
Proof
- backend/app/codeintel/indexer.py, lines 185–241 pinned source at the indexed commit
- Indexer in the explorer highlighted source and every span
ParsersPython's ast module, tree-sitter for seven more languages, line windows for the rest.Source audited
Each function, method, class and module becomes a chunk. Repository code is parsed and never executed.
Files that fall back to line windows are recorded as fallback, per chunk and per language, so they cannot pass as AST output.
Limits
- Ruby, PHP, Swift, Kotlin, Scala and C# have no grammar wired up and use line windows.
Proof
- backend/app/codeintel/parsers/__init__.py, lines 65–89 pinned source at the indexed commit
- Parsers in the explorer highlighted source and every span
EmbeddingsPluggable backends. Vectors from different models are never compared.Source audited
A chunk is embedded from its signature, docstring, calls and first body lines. The recorded runs here use granite-embedding-english-r2 as an int8 ONNX model on the CPU.
The hash backend exists for offline tests. It is lexical, not semantic, and these recordings do not use it.
Limits
- Document embedding needs far more memory than a 512 MB host has, so production query serving and indexing run apart.
Proof
- backend/app/codeintel/embeddings.py, lines 475–516 pinned source at the indexed commit
- Embeddings in the explorer highlighted source and every span
Call graphResolves a call only when one target is defensible.Recorded run
A name resolves within its own file first, then through imports, then if it is unique in the repository. A wrong edge misleads an assistant; a missing one only loses recall.
Indexing this commit resolved 6,977 calls and left 17,764 unresolved and 2,888 ambiguous.
Limits
- Dynamic dispatch is not followed. Most unresolved calls reach the standard library or dependencies, and the graph is deliberately incomplete.
Proof
- backend/app/codeintel/graph.py, lines 144–244 pinned source at the indexed commit
- Who calls this, and what does it call? recorded run
- Call graph in the explorer highlighted source and every span
Store Keep pointers
PostgreSQL storeChunk pointers, pgvector embeddings, edges and jobs. Source stays in Git.Source audited
An HNSW index serves dense search and a GIN index serves full-text search.
SQLite is used in tests, with Python fallbacks over the same columns. Quality numbers are only reported for PostgreSQL.
Limits
- The project reports that pointing at code saves about 5% of the database, because vectors and their index dominate.
Proof
- backend/alembic/versions/0002_codeintel.py, lines 110–121 pinned source at the indexed commit
- PostgreSQL store in the explorer highlighted source and every span
Serve Find, then check
RetrieverKeyword, dense, hybrid and graph modes, with the mode used always reported.Recorded run
Auto is dense when dense can run, and hybrid when the caller passes hints. If embeddings are unavailable it falls back to keyword and says so. An explicit mode that cannot run is refused.
Hybrid is reciprocal rank fusion of keyword and dense, with a boost for an exact symbol name. Tests, docs and examples are down-ranked unless the question asks for them.
Limits
- Repository scope is a filter the caller chooses. A call that names no repository searches every repository in the index.
- The retrieval metrics are read from project documentation. They were not reproduced for this site.
Proof
- backend/app/codeintel/retrieval.py, lines 204–277 pinned source at the indexed commit
- Hints turn auto into hybrid recorded run
- A missing embedder: degrade with a warning, or refuse recorded run
- Retriever in the explorer highlighted source and every span
Source verificationCode is read at the indexed commit and compared with its Git blob SHA before it is returned.Recorded run
PHAROS stores pointers instead of source. To answer, it fetches the file at the pinned commit, hashes the whole file the way Git does and compares that with the SHA recorded at index time.
A mismatch withholds the code and reports why. Cached bytes pass through the same comparison.
Limits
- This proves the bytes match the indexed commit. It says nothing about whether the code is correct or secure.
- With no SHA on record, source is still returned, marked unverified. Files PHAROS indexes get a SHA; the check depends on that row.
Proof
- backend/app/codeintel/source.py, lines 85–86 pinned source at the indexed commit
- A question reaches verified source recorded run
- What the blob check does with a mismatch recorded run
- Source verification in the explorer highlighted source and every span
Context assemblyRanked code, neighbours and rules, rendered with citations inside a budget.Recorded run
The same call serves REST, MCP and the CLI. It returns structured chunks and a Markdown rendering with path and line citations.
The response records whether the budget truncated it.
Limits
- Character budgets are approximate token budgets.
Proof
- backend/app/codeintel/context.py, lines 154–261 pinned source at the indexed commit
- A question reaches verified source recorded run
- Context assembly in the explorer highlighted source and every span
Repository memoryLearned conventions and history. It failed its primary evaluation.Failed its gate
Memory is mined from the index and Git history and added to the context after ranking, so it cannot change what retrieval returns.
The locked evaluation failed its primary recall gate and its precision gate. Repository Q&A improved, but that was a secondary measure.
Limits
- Memory was not learned for the index behind these recordings, so it does not appear in them.
Proof
- backend/app/learning/recall.py, lines 126–174 pinned source at the indexed commit
- The failed gate, with its numbers below
- Repository memory in the explorer highlighted source and every span
Interface Hand it over
MCP serverEight read-only tools over streamable HTTP.Recorded run
Assistants connect directly. Every tool is read-only and returns what the REST API returns.
The recorded handshake listed retrieve_context, search_code, find_symbol, list_repositories, get_repo_brief, search_memory, list_skills and get_skill.
Limits
- Authentication is static bearer tokens. There are no user accounts.
Proof
- backend/app/modules/mcp/native_server.py, lines 88–126 pinned source at the indexed commit
- A question reaches verified source recorded run
- Who calls this, and what does it call? recorded run
- MCP server in the explorer highlighted source and every span
REST APIThe same operations under /api/v1, with admin and read scopes.Recorded run
The read token can search and fetch context. It cannot index, delete or reach admin endpoints.
Older routers for papers, planning and a resource graph are still mounted and maintained to a lower bar. This explorer covers the code-intelligence path only.
Limits
- No public endpoint is called from this site.
Proof
- backend/app/modules/code/router.py, lines 220–238 pinned source at the indexed commit
- Hints turn auto into hybrid recorded run
- REST API in the explorer highlighted source and every span
The check itselfbackend/app/codeintel/source.pyOpen source
The function every cited span passes through, exactly as it reads at the indexed commit. It loads the file, hashes it the way Git does, and withholds the code when the hash differs from the one recorded at index time.
def _resolve_one(req: SourceRequest, token: str | None) -> SourceResult: try: data, origin = _load(req, token) except PermissionError: return SourceResult(req.key, "unavailable:host_not_allowed") except FileNotFoundError: return SourceResult(req.key, "unavailable:not_found") except OverflowError: return SourceResult(req.key, "unavailable:too_large") except LookupError: return SourceResult(req.key, "unavailable:no_raw_endpoint") except GitError: return SourceResult(req.key, "unavailable:git_error") except Exception as exc: # network errors, timeouts logger.info("source fetch failed for %s: %s", req.path, type(exc).__name__) return SourceResult(req.key, "unavailable:fetch_failed") verified = False if req.blob_sha: if git_blob_sha(data) != req.blob_sha: return SourceResult(req.key, "unavailable:content_mismatch") verified = True return SourceResult(req.key, "resolved", _slice(data, req.start_line, req.end_line), verified, origin)Pass 3 · Deep dive
How did it get here?
PHAROS didn’t start as a code-search service. It started as a much bigger idea, and most of what it is now came from finding out which parts were real.
Sep–Dec 2025
It began as Neo Alexandria
A research library: papers, citations, annotations, recommendations, and three-way search fused by rank, planned phase by phase as requirements, design and task documents. The SPLADE retriever comes from here.
What it taught me A plan for every phase is not proof for every phase. Its own test-fix specification recorded 74.8% of tests passing.
Jan 2026
Tests an assistant can’t rewrite
Expected values moved into read-only golden-data files, and a failing test says not to edit the test.
What it taught me Write the answer down before the code can see it.
Feb–Apr 2026
Renamed PHAROS, and pointed at code
A cloud API with a separate GPU worker, AST parsing and code search, aimed at coding assistants.
What it taught me A narrower question is easier to answer well.
Apr–May 2026
Audit the claims, including mine
An April audit, run by an AI reviewer told to trust no documentation, found 3 of 9 components missing, stubbed or invented. A May review found search returning results with no file paths and no code.
What it taught me Documentation is a claim, and claims need evidence.
Jul 2026
Cut back to the core
The knowledge-management product was removed, module boundaries became a CI gate, and PHAROS began speaking real MCP.
What it taught me Removing a feature can be the most useful change.
Oct–Nov 2026
Rebuilt around proof
A chunk-level code index with verification at commit. Labels were hashed before any run, each locked test set was run once, and the memory protocol was fixed before memory code existed. Retrieval passed; memory failed, and the failure stays on this page.
What it taught me Set the bar first, then publish whichever side of it you land on.
Every milestone from April 2026 on, with its commit
How the history is known3 claims, each with how it is known
PHAROS began in September 2025 as Neo Alexandria, a research-library backend for papers, citations, annotations and recommendations, specified phase by phase as Kiro requirements, design and task documents, and was renamed PHAROS in February 2026.
From PHAROS's commit history and specifications at 975a38d. Owner to confirm the framing of the project's origin.
In late 2025 the project's own test-fix specification recorded a 74.8% test pass rate, and in January 2026 a new suite moved expected values into read-only golden-data files whose failures tell the reader not to edit the test.
From PHAROS's own specifications and commit history. Owner to confirm that the early test record may be shown.
An April 2026 audit, run by an AI reviewer told to trust no documentation, found 3 of 9 audited components missing, stubbed or invented, and a May 2026 review found search returning results with no file paths and no code.
From two project documents at 975a38d. Owner to confirm that these earlier findings may be shown.
Pass 3 · Deep dive
What are its limits?
- Retrieval quality is reported, single-annotator and not reproduced for this portfolio.
- Blob integrity is not semantic correctness or a security certification.
- Conservative graph resolution means the call graph is deliberately incomplete.
- This page does not query PHAROS. It is a static case study, and the explorer's runs are recordings.
- Repository scope is a filter the caller chooses. A call that names no repository searches the whole index.
- The recordings ran on one local machine, not the deployed service.
Pass 3 · Deep dive
What would Ram test next?
A live version of this room needs a small server of its own: it holds the read token, fixes which repository can be searched, bounds every request, and falls back to these recordings when the service is cold. The credential work it was waiting on is closed. The server is not built yet, so everything here stays labelled as recorded.

