Knowledge

A knowledge base is a name, a set of files and an index. This extension owns the first two, keeps the third current, and lets you ask the result a question and read what came back.

What you can do

• Define a base — give it an id, point it at the files it holds with globs, and the definition lands in .punica/knowledge.json where a team can review it in a diff.
• Build it — the globs resolve against the workspace and everything they name is chunked, embedded and stored.
• See what is in it — every base shows the collections it owns, how many chunks and files they hold, how much disk they take and when they were last built.
• Ask it a question — the answer names the passages, their scores and their files, and it says whether they came back from the index or from a keyword search.
• See how a file splits — the units a file would be embedded as, with their labels and their sizes, before anything is embedded.
• Compare splits — one document chunked four ways, side by side, so a choice of strategy is a measurement rather than a preference.

Getting started

1. Install Vectors, which is where the embedding and the index live. Nothing here works without it.
2. Open the Knowledge panel from the bottom strip and click Define one. That writes a first base covering the markdown in your workspace.
3. Edit .punica/knowledge.json to point it at what you actually want indexed.
4. Click Preview paths to see which files the globs resolve to, then Build.
5. Type a question in the box.

Vectors ships with a hashing embedder that works offline and is lexical rather than semantic. It is enough to prove the pipeline runs; for results worth judging, set Vectors to a real embedding model first.

The definition file

{
  "version": 1,
  "bases": [
    {
      "id": "docs",
      "title": "Docs",
      "include": ["docs/**", "README.md"],
      "exclude": ["**/*.draft.md"],
      "topK": 8,
      "strategy": "heading"
    }
  ]
}

id is the corpus name and the base's identity. include and exclude are workspace-relative globs where ** crosses directories and * does not; a bare directory name means everything under it. exclude is applied after include, never before.

strategy is how the files are split: auto (the default), paragraph, heading or file. It needs Vectors 1.4.7 or newer, and windowLines and overlapLines size the window the first three use. A base that names none behaves exactly as it did before the field existed.

Two things worth knowing

An empty resolution is refused, not built. Building hands the resolved paths to Vectors, which treats that list as the whole corpus and deletes the chunks of every file the list no longer names. A renamed folder or a typo in a pattern would therefore clear an index and report success. When the globs come back empty this refuses and names the patterns that matched nothing.

Prose gets its own collection per base. A notebook's markdown cells are routed away from its code so they do not compete for the same slots, and each base routes its own into <id>-prose rather than into a collection shared with every other base. A query asks for both, which is the reason to ask a base rather than a corpus.

Compare splits measures shape, not quality. It chunks one document four ways and shows the counts and sizes side by side, which is free because nothing is embedded and nothing is stored. Which split retrieves better is a different question and no number in that view answers it.

What it does not do yet

Retrieval quality is not scored here. That is what the RAG eval engine measures, against a set of cases that name which documents are relevant — build a base twice with two strategies, score each, and the comparison becomes a verdict instead of a shape.