Knowledge

Knowledge is everything the agent may say. Answers are built from it and from nothing else: when the material does not support an answer, the agent says so and offers a next step instead of inventing one. There is no training step and no waiting: add a document, edit a claim, and the very next conversation reflects it.

​

The three kinds of source

They mix freely inside one agent. Use documents for volume, URLs for material that already lives on your site, and claims for the handful of facts that must always be exact: a price, a guarantee, an opening hour.

​

Documents

The console’s uploader takes PDF, Markdown, plain text and Word (.docx). The API additionally accepts HTML (text/html). A file the pipeline cannot read is refused with an unsupported-format error rather than half-indexed, and the cap is 10 MB per file either way. Uploading the same file twice updates the existing source instead of creating a second one: the bytes are the identity of an upload, so dragging the same PDF in again does not double your knowledge base.

​

URLs

You give a page address; wondeya fetches it and reads it. Only http and https are allowed, and addresses that resolve to private, loopback or link-local ranges are refused. The check runs when you add the URL and again at fetch time, because DNS can change in between. A URL source can keep itself current. Give it a re-sync window (syncTtlMinutes; the console offers Once, Daily and Weekly) and wondeya re-fetches the page on that schedule. Choosing Once means no re-fetch at all. The re-crawl is deterministic: it compares the fetched bytes against what it already indexed and only re-reads a page that actually changed, so a page that never moves costs nothing and never re-runs the enrichment step. You can still Retry a URL by hand at any time; with the same content it is just as cheap.

​

Claims

A claim is a title plus the approved copy in both Spanish and English. Claims are stored verbatim: never cut into fragments, never machine-translated at answer time. A claim is copy someone approved, and re-cutting it would be editing it. At answer time the visitor’s language wins, and the other language of the same claim is set aside so one fact never arrives twice.

​

Automatic enrichment

When you add a document or a URL, wondeya reads it once with a model before it is indexed. That single pass does three things you would otherwise do by hand:

• Names it. The source gets a title and a one-line summary of what it covers, so the agent knows the document exists even before it reads inside it.
• Translates it to English. The chunks are indexed and retrieved in English, which costs fewer tokens on every future answer. This is invisible to your visitors: they still read and are answered in their own language. A source shows the language it arrived in and a “translated” mark so nothing is hidden.
• Divides it into topics. The document is split into focused topics (several when the material calls for it, one when it is short), and each topic is given a short English description. A one-paragraph note becomes one topic; a long policy becomes several.

Enrichment never touches a claim: a claim is copy you approved word for word, so it is indexed exactly as written, in both languages, and never translated or renamed.

​

Topics

Topics are how retrieval routes a question to the right material. They are the deterministic half of retrieval (no model, no index, no network), and they are the cheapest quality win available. A source with no topics is universal: the topic map matches it against every question, so it is always retrievable. Tagging it is what focuses it. Every source carries up to 12 topic tags: lowercase words like pricing, warranty, shipping. You can set them by hand, and enrichment proposes them for you.

​

The topic taxonomy

Each agent keeps a managed taxonomy: the set of topics its knowledge is organized under, each with a slug (the stable key that tags the material), a title, and a description. The description is not decoration: it is what steers the agent toward the right topic when it answers, so a clear description is a direct quality lever. Enrichment writes the taxonomy for you and marks each topic auto; the moment you rename it or rewrite its description it becomes manual, and enrichment never overwrites your wording again. From there you curate what the model proposed:

• Rename a topic or rewrite its description.
• Merge two topics the model split too finely (for example prices into pricing); the material is re-tagged, never lost.
• Delete a topic; the row goes and the tag is pulled from every source, but the material stays: a passage left with no topics simply becomes universal, matched by every question. Deleting a topic never makes the agent forget a document.

There is no “create a topic” operation on purpose: a topic with no material routes to nothing. Topics are born from the knowledge you add.

​

What happens after you add a source

Indexing never runs inside your upload request. The request stores the bytes and queues the work; the queue does the reading. Every source counts against your plan’s document allowance, whether it is a document, a URL or a claim. At the cap, the API answers 402 carrying the limit and the current count. Editing a claim or retrying a failed ingest never spends a document. A source moves through four states: A failure is a state with a machine-readable reason, never a crash: unsupported_document, ingest_failed, or a fetch_… reason for a URL (timeout, DNS failure, response too large, blocked address). Retry re-runs the ingest with the file, URL or claim wondeya already holds, so recovering costs one click and no re-upload.

​

How documents are cut up

Documents are split along their own structure first (headings for Markdown and HTML, pages for PDF) and only then by size, targeting about 512 tokens with a small overlap. Very short fragments are merged rather than indexed on their own, because an orphan fragment is noise in every future search. Each chunk carries the document title and the heading trail it came from, which is what lets a passage make sense out of context.

​

How retrieval works at answer time

Two searches run in parallel over the agent’s chunks (plus the workspace pool it reads) and their rankings are fused:

• the topic map, deterministic and instant;
• vector search, filtered to your workspace and agent before it looks at a single vector.

The eight best passages go to the agent. There is no re-ranking step, on purpose: with an agent-sized corpus the bottleneck is finding the right passage at all, not ordering the ones you found, and a re-ranker would cost the visitor time in the middle of a live answer. If the vector half is unavailable (still building, or the embedding provider is down), the topic map answers alone and the page keeps working.

​

Test retrieval

Today this runs over MCP only, with probe_retrieval: it runs exactly the search the agent runs and shows you what came back, each passage, which source it belongs to, its heading trail, and how many candidates each half of the search contributed. The console does not have a retrieval-testing screen yet. It answers the question that matters when an answer is disappointing: is the agent choosing badly, or is the material simply not there?

​

Agent scope and workspace scope

A source belongs to one agent, named by agentId. A source created without agentId goes to a workspace pool that every agent of the workspace reads by default, and several pages sharing one agent share its knowledge. An agent can be cut off from the pool with its useWorkspaceKnowledge setting, so a workspace running two unrelated products can keep them from answering in each other’s name. That setting is editable through the API and MCP today; the console does not expose it yet.

​

Isolation and deletion

Knowledge never leaves your workspace. There is one index for everyone and your workspace id is part of the filter on every single search, so a search cannot be written that reaches another customer’s material: it is a pre-filter, not a post-filter. Deleting a source is real and immediate: the source row, its chunks, their vectors and the stored file go together in one cascade. Because each chunk holds its own vector, there is no window in which the database has forgotten something a search engine still remembers. Deleting a page deletes no knowledge: the material belongs to the agent, which may still answer on other pages. Deleting an agent is what removes a whole corpus in that same cascade, and that deletion is refused while a page still points at the agent.