Paparats: Local Semantic Code Search
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| EMBED_URL | No | llama-swap / llama.cpp embedding server (bge-code-v1 + Qwen3-Embedding-0.6B) | http://127.0.0.1:18434 |
| QDRANT_URL | No | Qdrant URL (local Docker or Qdrant Cloud) | http://localhost:6333 |
| QDRANT_API_KEY | No | API key for authenticated Qdrant, e.g. Qdrant Cloud | |
| PAPARATS_METRICS | No | Expose Prometheus metrics at /metrics | false |
| PAPARATS_PROJECTS | No | Comma-separated allowlist of project names this server may search | |
| PAPARATS_OTEL_ENABLED | No | Enable OpenTelemetry traces via OTLP | false |
| PAPARATS_DOCS_AUDIENCE | No | Comma-separated docs audience ceiling, e.g. client,public | |
| PAPARATS_ANALYTICS_ENABLED | No | Local SQLite search analytics | true |
| OTEL_EXPORTER_OTLP_ENDPOINT | No | OTLP HTTP endpoint for traces |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Semantic code search and knowledge base across workspace projects.
MANDATORY: You MUST call search_code BEFORE answering ANY question about the codebase. This includes questions about: "how does X work", "where is X", "find X", "what does X do", "how many X", "list X", "count X", "which files", "show me X", "is there a X", implementation details, patterns, flows, or any reference to project code.
Do NOT answer from memory or guess. Do NOT use grep or file reading as first resort — search_code is more efficient (50-90% fewer tokens vs full files).
Workflow: search_code FIRST → evaluate scores → get_chunk for details → find_usages for dependencies → answer with citations.
Score interpretation (included with each result):
60%+ = high confidence — trust these results
40-59% = partial match — supplement with grep or file reading
<40% = low confidence — fall back to grep, file reading, or ask the user
Project names: The project parameter is the directory basename (e.g. a repo cloned to /code/billing has project name "billing", NOT "org/billing"). Use "all" to search across all projects. If this server is scoped via PAPARATS_PROJECTS, searches are automatically filtered to the allowed set.
Use delete_project to remove a corrupted project's index — it will be re-indexed on the next indexer cycle. Use health_check to verify indexing status.
Documentation
search_docs searches written documentation as prose — runbooks, RFCs, onboarding notes, product and process docs. It is a separate index from code and they never mix: use search_code for implementation, search_docs when the answer is a documented procedure, rationale or policy. Hits carry the document title, heading breadcrumb, project, file and source link.
Hits are excerpts, not whole documents. When the answer depends on a complete sequence or a table you can only partly see, read the file at the returned path instead of inferring from the excerpt. Do not enumerate a document's contents from excerpts alone.
A ## Glossary block may be prepended to results when the query mentions a known term. That block is context, not an answer — a term can match a question it does not resolve.
Glossary
term_search resolves an acronym, service name or domain term to a definition plus aliases. Call it before searching when a request contains shorthand you cannot expand confidently — the definition supplies the words the index actually contains, so one lookup often replaces several rephrased searches.
Each hit is labelled exact match (the query equalled a term name or alias — identity, trust it) or similar, 0.xxx (the vector's nearest guess — verify before relying on it). Never invent an expansion the glossary lacks; say it is unrecorded and ask.
Record vocabulary you establish with term_record(term, definition, aliases[], project?). Keep definitions to 1-2 sentences: they are injected into context on every match. Re-recording an existing name overwrites in place, which is also how you correct a definition. A near-verbatim restatement of a different term is refused as duplicate and returns what it collided with. Prefer distinct canonical names — an exact query resolves to the name owner, so an alias never hides an existing term.
What a miss means — coverage differs sharply per layer
Only code is densely indexed. The knowledge layers are authored by agents as work happens, so they are incomplete by construction:
Code — dense across every indexed repository; a miss is real signal.
Docs — a wiki snapshot plus repo markdown. It can lag; a miss is inconclusive.
Glossary — partial. A miss means the term is not recorded yet.
Architectural memory — sparse, often empty for a group. A miss means nobody wrote it down, never that no such decision exists.
So on the sparse layers, do not present an empty result as evidence, and do not skip reading the code because a layer was silent. The corollary is that writing is where the value is until they fill up: when you confirm something durable, record it.
Architectural memory
Reading. Before changes affecting more than one component or before introducing a new pattern, call arch_context with the question or the list of files you are about to touch. Each returned card carries an updated-at age — treat anything older than 90 days as a hypothesis and verify against the current code before acting on it.
Writing during work — proactive, not on request. Record without being asked when any of these happen:
New component discovered or introduced (a logical unit not already in arch_context) →
arch_record_component.Architectural choice made (library, pattern, boundary) that wasn't obvious from the code →
arch_record_decision. If you are deliberately replacing a known prior decision, pass its id insupersedes.Lesson worth keeping →
arch_record_lesson. Triggers: the user corrects a non-obvious mistake of yours; OR you made an assumption that turned out wrong and the fix was not obvious from reading the code; OR the user accepts an unusual approach that would surprise a future reader. Do NOT record: typos, parser errors, facts trivially visible in code, restatements of existing CLAUDE.md rules.
Memory layers — which one to write to:
arch (this server) — rules about the code: contracts, boundaries, patterns, API shape, framework gotchas, schema/migration constraints. Anything a future engineer joining the codebase would need.
agent-side memory (auto-memory / CLAUDE.md / AGENTS.md) — rules about the user's workflow or how to collaborate with them: commit style, branch naming, when to ask vs act, formatting preferences. Not the arch layer's concern.
When in doubt, ask: "would another engineer in this repo benefit?" If yes → arch. If only this user → agent-side memory.
Responding to the similarity gate. The server checks for near-duplicates before writing decisions and lessons. When you get back:
created/updated: done.duplicate(decision): a near-identical decision already exists. Stop. Ask the user whyarch_contextdid not surface it before you wrote — that gap matters more than the write.duplicate(lesson): the server bumped updatedAt on the existing lesson; nothing more to do unless your wording was sharper, in which case refine the existing card.similar(decision): considersupersedesif you really mean to replace it; otherwise sharpen the wording so it stops looking like a duplicate.similar(lesson): decide whether to refine the existing card or write a clearly distinct one — and re-call accordingly.
Disagreement with memory. If arch_context returns a card that contradicts the code (files no longer exist, behaviour differs, anchor symbols renamed), do NOT silently overwrite. Surface the conflict to the user — "memory says X, code shows Y — which is correct?" — and update only after they clarify.
Initialisation. If the user asks to initialise or bootstrap architectural memory for the project, walk the repository via search_code, identify 8-20 components by domain boundaries, and write each via arch_record_component. Optionally capture decisions inferable from code comments or commit history via arch_record_decision. Report a short summary when done.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| search_codeA | REQUIRED — call this FIRST for ANY code question. Semantic code search across all indexed projects. Returns relevant code chunks ranked by confidence score with symbol definitions and usages. Triggers (call this when the user asks about): code location, implementation, "how X works", "how many X", "what versions of X", "count X", "list X", patterns, flows, error handling, auth, API usage, or ANY reference to project code. WHY: Returns only relevant chunks (50-90% fewer tokens vs full files). Searches by meaning, not just keywords. WORKFLOW: Search first → evaluate scores → get_chunk for details → find_usages for dependencies. Project names are directory basenames, not org/repo format. Example: "billing" not "org/billing". |
| health_checkA | Check indexing status: number of indexed chunks per group. Use to verify projects are indexed before searching or debugging empty results. |
| get_chunkA | Get a code chunk by ID with optional surrounding context. Returns code with symbol definitions and usage info. Use to expand on search results. |
| delete_projectA | Delete all indexed data for a specific project: chunks from Qdrant, metadata from SQLite, and query cache. The project will be re-indexed on the next indexer cycle if configured. Use when a project's index is corrupted or stale. |
| find_usagesA | Find symbol relationships: what calls this code, and what this code calls. Supports incoming (callers), outgoing (dependencies), or both directions. Use after search_code or get_chunk when the user asks 'where is this used?', 'what calls this?', or 'what does this depend on?'. Pass chunk_id from search results. |
| list_projectsA | List all indexed projects with metadata: chunk count and languages per project, grouped by collection. Use when the user asks 'what projects are indexed?', 'which repos are available?', or 'show me all projects'. Optionally filter by group name. |
| arch_contextA | Retrieve architectural memory relevant to a question or set of touched files. Returns three card kinds, each with an updated-at age stamp:
Each kind has its own independent top-N budget — a verbose decision bucket can't starve components. Pass |
| arch_record_componentA | Record (or update by name — idempotent) an architectural component. Use when you discover a logical unit not already in arch_context, or when an existing component's boundary changes. The |
| arch_record_decisionA | Record an architectural decision. Use when you pick a library, pattern, or boundary that wasn't obvious. The server runs a similarity gate against existing decisions in the group; possible outcomes:
|
| arch_record_lessonA | Record a lesson — a rule the agent should follow next time. Use when the user corrects a non-obvious mistake of yours, OR when you accept an unusual approach that would surprise a future reader. Skip typos, parser errors, and facts trivially visible in code. Belongs here (arch) vs. agent-side memory (auto-memory / CLAUDE.md / AGENTS.md):
Three fields, each markdown:
|
| arch_listA | Enumerate arch cards in a group — no vector search, no ranking, no similarity threshold. Use this when you need every card (audit, dedupe, migration) rather than the top-N most similar to a query. Optional filters:
Returns each card with id, kind, project (or 'global'), status, and a short label (name/title/rule). Use the ids with |
| arch_suggest_componentsA | Suggest candidate components to record. Reads the symbol-graph in-degree (how often a chunk is called from the rest of the indexed code) and surfaces the most-called files that are not yet covered by an existing component card. Ranked by in-degree. Use this when initialising the arch layer for a group (instead of guessing where the boundaries are) or after a large refactor to spot newly important modules. The tool only reads — it does not write component cards. Read each suggestion, decide whether it represents a meaningful architectural boundary (some high-degree files are utilities, not components), and call Optional |
| arch_deleteA | Hard-delete one or more arch cards by id. No undo, no audit trail — the cards are gone from Qdrant. Use for: cleaning up obsolete cards left over from a refactor, dropping cards for a removed feature, migrating away from old payload schemas. Idempotent: ids that no longer exist are reported in |
| search_docsA | Hybrid (dense semantic + BM25 keyword) search over indexed markdown documentation, fused with RRF. Returns EXCERPTS, not whole documents: each hit is the best-matching passage plus its neighbouring sections, carrying the document title, heading breadcrumb, project, file, and source link when available. When a hit covers only part of its document an |
| term_searchA | Look up a term, abbreviation, or domain concept in the company glossary (e.g. 'CLIC', 'feed-poster'). Use this FIRST when a query contains an unfamiliar acronym or product name — the definition and aliases sharpen a follow-up search_code / search_docs. Returns the term, its definition, and known aliases. |
| term_listB | List recorded glossary terms in a group (optionally scoped to a project). Use to audit coverage or review what terminology has been captured. |
| term_recordA | Record a glossary term (canonical name, definition, aliases, optional project scope). Goes through a duplicate/similar gate like arch_record_decision: if a near-identical term already exists it is returned instead of writing a duplicate — reconcile by updating that term. Authored by the agent as it learns domain vocabulary, or in bulk via the extract-terminology skill. |
| term_deleteA | Hard-delete a glossary term by id. No undo. Use to remove obsolete or wrong terms. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| find_implementation | Locate where a feature, concept, or behavior is implemented across the indexed codebase. |
| trace_callers | Map who depends on a symbol before renaming, deleting, or changing its signature. |
| onboard_to_project | Day-one overview of a project: what it does, tech stack, main subsystems, configuration, integrations. |
| init_arch_memory | First-time bootstrap of the architectural memory layer for a project — analogous to /init in Claude Code. Walks the repo, identifies components and base decisions, writes them as cards. |
| audit_architecture | Sweep the arch memory for a group: find stale cards (>90 days), broken anchors (deleted files/symbols), and components that contradict the current code. |
| record_lesson_from_correction | Convert a user correction or self-discovered mistake into a structured lesson card, then write it. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| project-overview | |
| arch-schema |
TDQS
Scored across 18 tools
The three tool families (code search, glossary, arch memory) are clearly separated, and the pairings that could collide — search_code vs search_docs, get_chunk vs find_usages, arch_context vs arch_list, term_search vs term_list — are explicitly distinguished in their descriptions (ranked retrieval vs ground-truth enumeration, chunks vs prose, symbol graph vs glossary). The only mild residual overlap is term_search vs search_docs for domain questions, but the guidance ('glossary first for acronyms') resolves it. An agent should reliably pick the right tool.
All names are snake_case, but the ordering convention flips between verb_noun (search_code, get_chunk, find_usages, list_projects, delete_project, health_check) and noun_verb (term_search, term_record, arch_context, arch_list, arch_delete, arch_record_component). The prefix-grouping is readable and even praiseworthy for discoverability, yet inconsistent with the search/code family. Readable overall, but not a single predictable pattern.
18 tools spans three genuinely distinct sub-domains (semantic code search, glossary, architectural memory), so the count is roughly proportional rather than padded. Still, it sits at the top of the comfortable range, and the seven arch_* tools plus four term_* tools make the surface heavier than a pure search server would need. Slightly over a lean ideal but each tool maps to a real operation.
Glossary (record/search/list/delete) and arch memory (record/list/context/delete/suggest) have near-full lifecycles, and code search covers discovery, expansion, and dependency tracing. The notable gap is indexing control — there is no reindex/refresh tool, only delete_project with a note that re-indexing happens on the next cycle — and term updates are only implicit through the duplicate gate. Workarounds exist, so nothing is a dead end.