Skip to main content
Glama
Paparats: Local Semantic Code Search

Paparats: Local Semantic Code Search

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
EMBED_URLNollama-swap / llama.cpp embedding server (bge-code-v1 + Qwen3-Embedding-0.6B)http://127.0.0.1:18434
QDRANT_URLNoQdrant URL (local Docker or Qdrant Cloud)http://localhost:6333
QDRANT_API_KEYNoAPI key for authenticated Qdrant, e.g. Qdrant Cloud
PAPARATS_METRICSNoExpose Prometheus metrics at /metricsfalse
PAPARATS_PROJECTSNoComma-separated allowlist of project names this server may search
PAPARATS_OTEL_ENABLEDNoEnable OpenTelemetry traces via OTLPfalse
PAPARATS_DOCS_AUDIENCENoComma-separated docs audience ceiling, e.g. client,public
PAPARATS_ANALYTICS_ENABLEDNoLocal SQLite search analyticstrue
OTEL_EXPORTER_OTLP_ENDPOINTNoOTLP 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 in supersedes.

  • 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 why arch_context did 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): consider supersedes if 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

CapabilityDetails
tools
{
  "listChanged": true
}
prompts
{
  "listChanged": true
}
resources
{
  "listChanged": true
}

Tools

Functions exposed to the LLM to take actions

NameDescription
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:

  • Components: what parts the system is made of.

  • Decisions: why they were built that way.

  • Lessons: rules that survived previous mistakes — each rule comes with why (incident context) and when (when to apply) continuation bullets. Superseded and deprecated cards are hidden by default. Cards older than 90 days are prefixed with ⚠ stale — verify them against the current code before acting. Call this BEFORE any non-trivial change. Returns an init hint when the arch layer is empty.

Each kind has its own independent top-N budget — a verbose decision bucket can't starve components. Pass limits: { component, decision, lesson } to override the per-kind cap (default 5 each, max 50; 0 suppresses the kind). When you pass project, cards whose payload matches that project also get a small additive rank boost (~one calibrated tier) so short global cards don't drown out longer project-scoped ones on raw cosine — globals stay visible but no longer dominate. When you suspect ranking issues, prefer arch_list for ground-truth enumeration.

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 summary field is structured markdown with four sections (Does / Owns / Does not / Touched when); anchors are stable exported symbol names that survive a refactor. Returns status created or updated.

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:

  • created: a new decision was written.

  • duplicate: a nearly identical decision already exists — nothing is written. Ask the user why arch_context did not surface it earlier.

  • similar: a related decision exists — nothing is written. To explicitly replace it, re-call with supersedes set to its id; otherwise sharpen the wording. Passing supersedes bypasses the gate and marks the named prior decision as superseded.

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):

  • arch (this tool) — rules about the code: contracts, boundaries, patterns, API shape, type invariants, framework gotchas, schema/migration constraints, security rules tied to the codebase. Examples: "GraphQL admin mutations require a non-null ID and a corresponding picker query", "Always preserve createdAt on re-upsert", "Run integration tests against a real database, not mocks".

  • agent-side memory (not here) — rules about the user's workflow or how to collaborate with them: preferred commit style, branch naming, when to ask vs act, formatting preferences. Those live in auto-memory or a CLAUDE.md / AGENTS.md file — not in arch.

  • Heuristic: if a new engineer joining the codebase would need it → write it here. If only this specific user needs it → it's agent-side memory.

Three fields, each markdown:

  • rule: one imperative sentence (the rule).

  • why: 1-3 sentences with the incident — quote the user verbatim when possible.

  • when: one sentence describing the situation in which the rule applies. The server runs a similarity gate; possible outcomes:

  • created: a new lesson was written.

  • updated: a near-duplicate already existed — its updatedAt was bumped (confirmation signal). Refine the existing card if your wording was better.

  • similar: a related lesson exists — nothing is written. Decide whether to refine the existing or write a clearly distinct one.

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. arch_context is for relevance-ranked retrieval; arch_list is for ground truth.

Optional filters:

  • project: components must match this project (hard filter); decisions/lessons match this project OR have no project field (soft filter — group-wide guidance still surfaces).

  • kinds: subset of ['component', 'decision', 'lesson'].

  • include_history: include superseded/deprecated cards (default false).

  • limit (default 50, max 200), offset: pagination — pass next_offset from the previous response to resume.

Returns each card with id, kind, project (or 'global'), status, and a short label (name/title/rule). Use the ids with arch_delete or as input to follow-up arch_record_* calls (e.g. supersedes on arch_record_decision).

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 arch_record_component for the ones that do.

Optional project restricts suggestions to one project in the group. Optional limit (default 10, max 50) caps how many uncovered files to return.

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 notFound but do not fail the call. Always re-fetch ids via arch_context immediately before calling — ids from earlier in the conversation may point to cards that have since been re-upserted (a re-upsert allocates a fresh UUID), so deleting by a stale id will silently miss the intended card and could wipe a now-current one if the id was reassigned. Prefer supersedes on arch_record_decision when you have a replacement decision; use arch_delete only when there is no replacement.

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 Excerpt: line says which sections you got and how many exist — read the named file directly when you need the rest, because the passage may not be the document's full answer. The top hit is usually right but not always; scan the alternatives before concluding. Use for questions answered by prose docs (runbooks, RFCs, onboarding, business docs), not code. For code use search_code. Optional audience restricts results to visibility labels (e.g. ["internal"], ["client","public"]); omit to search every audience the endpoint is allowed to see. Some deployments enforce an audience ceiling — there, audience can only narrow within it, never widen past it. Results are filtered by a semantic-similarity floor, so a question the corpus does not cover returns nothing rather than the nearest unrelated page; treat an empty result as "not documented". Two floors apply: min_score (default 0.45) for long-form prose, and min_score_code (default 0.6) for markdown that ships inside code repositories (README, CLAUDE.md, design notes) — those are written as overviews and score deceptively well against questions they do not answer, so they are held to a stricter bar. A Last updated ... ago line marks a document untouched for over a year: docs checked in beside code go stale quietly, so prefer a recent source when they disagree, and verify against the code before relying on it. Absence of that line means recent OR unknown age, not verified-current. The reported score is a fusion rank, not a similarity — use it to order hits, not to judge how good a match is.

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

NameDescription
find_implementationLocate where a feature, concept, or behavior is implemented across the indexed codebase.
trace_callersMap who depends on a symbol before renaming, deleting, or changing its signature.
onboard_to_projectDay-one overview of a project: what it does, tech stack, main subsystems, configuration, integrations.
init_arch_memoryFirst-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_architectureSweep 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_correctionConvert a user correction or self-discovered mistake into a structured lesson card, then write it.

Resources

Contextual data attached and managed by the client

NameDescription
project-overview
arch-schema

TDQS

A3.9/5.0

Scored across 18 tools

Disambiguation4/5

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.

Naming Consistency3/5

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.

Tool Count4/5

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.

Completeness4/5

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.

Maintenance

ActivityNo data
ResponsivenessOutdated data