Introduction
Here is how we implemented the AI search algorithm behind Awesome Repositories. The site helps visitors find open-source GitHub repositories with plain-language queries like "self-hosted feature flags" or "terminal UI for git". It returns ranked results, and each match includes a written reason. Results arrive in under four seconds and cost about a tenth of a cent in AI fees.
The hard problem is relevance. A search query describes what someone needs. A repository page often describes implementation details, project history, installation steps, and API behavior. Matching words directly breaks down. For "kubernetes gitops", a keyword engine ranks a 430k-star link collection first because that page mentions both words more often than any real tool.
We solved this by moving the hard thinking before search time. We track 5,000+ promising open-source repositories. An AI agent studies every repository once, in advance, and records what the project is as tags in one organized catalog with evidence attached. When a search arrives, a model translates the query into tags to look for. Plain database math turns those tags into a ranked list of repositories.
Reading a repository
When a repository enters our index, an analysis run reads its documentation the way a careful engineer would. One part of the agent plans which pages are worth reading. Worker agents read those pages and take notes. A final step turns the notes into structured records.
Documentation varies wildly. A command-line tool might have one README, while a platform might have hundreds of pages. We use a $1 cap per run, so a project with a 600-page documentation site cannot blow the budget. It just gets read less thoroughly.
The output is a set of tags, and each tag carries two fields: a 0-100 score for how strongly this repository belongs under the tag, plus a written reason in plain language explaining why the repository earned the tag.
The written reason is part of the product, and it is also how we debug it. When a search result looks wrong, we inspect the evidence behind every tag instead of staring at an opaque similarity score. Every judgment the AI makes is one we can audit later.
The agent also records what kind of repository it just read. A curated list of links is different from a tool, a tutorial, or a project template. Marking the format as its own tag lets the search engine exclude whole groups later, so a search for tools returns tools rather than link lists about tools.
About a thousand repositories have been through this deep analysis so far. It is the expensive part by design. We spend dollars once per repository, instead of pennies on every search.
The catalog
All repository judgments land in one tree: 32,419 approved tags under 22 top-level categories. The tree gives the system shared language. Without it, two analyses might describe the same idea in slightly different words, or worse, use the same word for different ideas.
We maintain the catalog with an AI agent that works like a librarian. It surveys a section, decides what to merge, move, or dissolve, executes through small single-purpose operations, and stamps the section as reviewed. Nothing in the catalog changes outside that review loop.
The catalog has two rules that keep it useful. First, a category gets about fifteen children at most. Anything more detailed goes a level deeper instead of making one level wider. A category with dozens of entries is harder to scan and harder to maintain than a narrower, deeper tree. The rule helps the models as much as it helps us, because choosing among fifteen related concepts is more reliable than choosing from a long flat list.
Second, every tag gets a description grounded in the repositories actually filed under it, never guessed from its name. Every cleanup decision checks that evidence first. This rule paid for itself when we tried merging tags that shared the same name. A verifier that read the underlying repositories rejected roughly 60% of those merges. Same name, different concept, more often than we expected.
The catalog also gives search its meaning layer. Every tag gets an embedding: a list of numbers that places its meaning on a map, where similar ideas sit close together. "Container orchestration" and "Kubernetes" land near each other on that map even though they share no words. We have about 43,000 embeddings on file.
Processing a search
Each search uses the model to understand the query and name the requirements. The database does the retrieval and ranking.
- A model reads the query before retrieval starts. Product names often imply categories. "posthog alternative" is really a product-analytics question, even if the query does not say analytics. Ambiguous queries keep every plausible reading instead of betting on one too early.
- The model produces two lists of tags: tags a result must match, and tags that disqualify it. The negative list matters. "Lightweight kubernetes dashboard" should push heavyweight platforms down the ranking. A must-have list alone cannot express that. Exclusions let the system say what a result should avoid, not only what it should contain.
- Each required concept is matched against the catalog two ways at once. Classic keyword search finds exact words. Embedding search finds nearby meanings on the map. The two ranked lists are merged, and entries that score well on either path rise to the top. A third signal compares the query to each repository's overall center of gravity: the average position of all its tags on the meaning map. This catches projects whose whole shape fits even when no single tag is a direct hit.
- After candidate tags are found, format tags remove repositories the query did not ask for. This is where link collections leave a tool search. A search for "best git TUI" should return terminal interfaces for git, not lists of git tools.
- The final ordering counts how well each repository's tags overlap the requirements, adjusted for how many tags the repository has. No AI runs in this step. The judgment was already spent when the tags were written.
End to end, a search takes about 3.7 seconds and costs $0.001. Repeated searches are nearly free. When a new query lands close enough on the meaning map to one we have answered before, such as "best git TUI" vs "good terminal UI for git", the stored interpretation is reused without calling a model.
The idea we kept
Do the expensive thinking once, when writing things down, and keep reading cheap. We spend dollars analyzing each repository a single time, then fractions of a cent per search after that. We kept retrieval in the database we already run. We attach a score and a written reason to every AI judgment because the first wrong-looking ranking needed evidence, not vibes.