How the knowledge base works

The knowledge base holds what the AI should know about your business and cannot learn from the mail itself: prices, policies, opening hours, product facts and the way your team answers. You add notes, files and web pages, and the AI reads the parts that matter whenever it writes for you.

It is one store per workspace, with three levels, so an answer that only holds for one brand or one team stays with it. It is read and changed in the app under Workspace → Knowledge base, over the REST API, from the SDKs and the CLI, and by the assistant and MCP clients.

Every item sits at one level, its scope. The AI writing for an address reads that address, then its domain, then the whole workspace, and when two items disagree the more specific one wins.

• —A plus address reads its base address too, so [email protected] uses what is kept for [email protected].
• —GET /knowledge/levels lists every level you can see, how many items each holds and whether you may change items there.
• —Moving a domain to another workspace moves the items kept for it and its addresses along with it.

• —A note is text you write in place, up to 20,000 characters, in Markdown if you like. It is usually ready for the AI within a second or two.
• —A file is read into text in the background: PDFs, Word documents, spreadsheets (Excel, OpenDocument, Numbers and CSV), OpenDocument text, HTML, XML, Markdown, plain text, JSON and images (JPEG, PNG, WebP and SVG). A document can be up to 20 MB and an image up to 10 MB.
• —A web page is fetched from a public http or https address and read in the background, up to 5 MB of it. A level holds a page once, and refreshing it fetches it again after it changes.
• —Up to 1,000,000 characters of text are kept from one item, and the text is split into passages under its headings for search.

An item is queued and then processing while it is read, ready once the AI can use it, and failed with a failure that says why when it could not be read. A changed item goes back to queued, and the AI keeps using its previous text until the new one is ready. Refreshing an item reads it again and clears a failure.

• —Reply suggestions under the latest message of a thread read the levels of the address the message arrived at.
• —A draft written from a description, in the composer or with POST /emails/compose, reads the levels of the address it goes out from. The answer lists the items it drew on in sources.
• —The assistant reads the levels of the thread you have open, or every level you can see when none is open, and can search the knowledge base itself with its searchKnowledge tool.
• —The answer to GET /threads/{id}/reply-suggestions lists the items the suggestions drew on in sources.

Pinned notes go into every prompt at their level, up to 2,000 characters from each level, whether or not they match what is being written. The rest of the room, about 6,000 characters in all, goes to the passages that best match the request, found by meaning and by words. When the index does not answer within a moment, the AI writes without it rather than keep you waiting.

Add items in the app under Workspace → Knowledge base, or from code with the API, the SDKs and the CLI. The assistant and MCP clients can save a note or add a link when you ask them to remember something, and they can change, refresh and delete items too. In the app’s chat, adding, changing and refreshing an item ask first unless you asked for it, and deleting one always asks first.

Every item records where it came from in origin: app, api, assistant or mcp, with who added it in createdBy.

It also grows on its own. The AI suggests notes from the replies your team sends and notes the questions nothing answers yet, connectors keep whole sites, sitemaps, feeds and help centers in step, and links can be read again on a schedule. The sections below explain each.

When someone in the workspace replies in a conversation, the AI reads the reply and the message it answers, and suggests up to three facts from it that would hold for other people too, such as a price, a policy or a delivery time. Each suggestion is a note waiting for review, at the level of the domain the reply was sent from, or the whole workspace when that domain is not one of its own. Facts the knowledge base already holds are left out, and up to 100 replies a day are read.

Review them in the app or with GET /knowledge/suggestions. Accept one to save it as a note, changing its title, text, level or pin on the way in, or dismiss it. The same fact suggested again counts up occurrences instead of adding a second suggestion, and a dismissed one is not suggested again.

When the AI suggests replies to an incoming message, it also notes up to three things the sender asked about the business that neither the conversation nor the knowledge base answers, such as whether you ship to their country. Each becomes a question at the level of the domain the message arrived at, or the whole workspace when that domain is not one of its own, and the same question asked again counts up occurrences, so you can see which ones come up most.

Answer a question and it becomes a note: accept it with the answer as its text, and its title stays the question unless you change it. From then on the AI uses the answer whenever the question comes up. Dismiss a question that needs no answer, and it is not noted again.

Each item is compared with the closest items at every level when it is indexed, and again whenever it changes. Two items that say nearly the same thing are flagged as a duplicate. Two closely related items that disagree on a fact, such as a price or a deadline, are flagged as a conflict, with one sentence on what disagrees. The AI checks for conflicts up to 200 times a day.

• —Every item counts the open flags that name it in flags, and GET /knowledge/flags lists them, newest first.
• —Change or delete one of the two items to settle a flag. A changed item is compared again once it is indexed.
• —Dismiss a flag when the two items are fine as they are, and the same pair is not flagged for the same reason again.
• —A flag shows only to someone who can see both items.

A connector keeps many pages from one source in the knowledge base, each page as a link item at the connector’s level, and keeps them in step as the source changes.

• —The first sync starts within a minute. After that it syncs again every 7 days, or every 1 or 30 days, or only when you ask for a sync, which starts within a minute too.
• —It keeps up to 25 pages, or as many as you set up to 200, and its items count toward the plan allowance. A sync stops adding pages once the allowance is reached.
• —Each sync adds new pages, reads changed ones again and removes the items of pages that are gone from the source.
• —A page you added yourself as a link at the same level stays with that item, and deleting a connector removes only the items it added.
• —Moving a connector to another level moves its items with it.

A link can be read again on its own every 1, 7 or 30 days: set refreshDays when you add it, or later. When the page has changed, its new text replaces the old once it is read, and the AI keeps using the old text until then. nextRefreshAt says when it is read next, and a page that cannot be fetched is tried again the next day.

The AI can read a conversation and draft one note of the facts in it that the team will need again, leaving out personal details and what matters only to that conversation. Nothing is saved until you keep it: read the draft, change it as you like and save it as a note, which records the conversation it came from in threadId.

The draft suggests a level: the domain the conversation arrived at when you may add items there, otherwise the whole workspace or the address. Each draft is one AI action. From code, draft with POST /knowledge/drafts, which needs threads:read as well as knowledge:write, and save with POST /knowledge/notes and the same threadId.

A search finds passages by meaning and by words. Send rerank: true with POST /knowledge/search and the AI also reads the best 25 passages and puts them in the order that best answers the question, leaving out the ones that do not help. It adds a second or two and is one AI action, so it runs only when you ask for it. reranked in the answer says whether it happened, and when it does not finish in time the passages keep their usual order.

GET /knowledge/stats shows how the AI used the knowledge base over the last 30 days, or up to 90 when you ask.

• —How often a reply suggestion, a draft, the assistant or a search found something, how often it looked and found nothing, and the share that found something, day by day.
• —Where those uses happened: compose, reply, chat, tool and search.
• —The items used most, and how many ready items were never used. Every item carries its own count in uses, with lastUsedAt the latest.
• —How many suggestions and questions wait for review, and how many flags are open.

The workspace setting knowledgeLearning is on by default. Turn it off with PATCH /settings and { "knowledgeLearning": false } and the AI stops reading sent replies for facts to suggest, stops noting questions from incoming mail and stops checking items for conflicts. Duplicates are still flagged, and what was already suggested stays for you to accept or dismiss.

• —Reading needs knowledge:read and changing needs knowledge:write, which includes reading. The built-in Admin, Member and Developer roles can change items, Viewer can read them, and Billing cannot reach them.
• —Changing an item needs reach over every address its level covers: the whole workspace needs every address, a domain needs the whole domain, and an address needs that address. A key or an app limited to particular addresses can change items only at those addresses, or at domains it holds whole.
• —Somebody limited to particular addresses reads the whole-workspace items and the items at their addresses and those addresses’ domains. The assistant and MCP tools acting for them add and change items only at the addresses they can send from.

• —The text of every item is encrypted at rest: the body of a note, the text read from a file or a page, and every passage. The words that search by words matches are stored as keyed hashes, not as words.
• —Files are turned into text and web pages are read by OpenEmail. The privacy policy lists every service that processes your data.
• —To search by meaning, each passage and each question is turned into a vector: a list of numbers that describes what it is about. The vectors are stored unencrypted beside the encrypted text, as they are for search by meaning in mail.
• —The passages a prompt uses go to the AI model that writes the reply, the draft or the answer, as the rest of the prompt does.
• —Deleting an item removes its file, its text and its passages at once. The knowledge base is part of a workspace export, and deleting the workspace deletes it.
• —While learning is on, the AI model reads each reply sent in a conversation, with the message it answers, to suggest notes, and reads two closely related items to check them for a conflict. The setting knowledgeLearning turns both off.

Everything above is in the REST API under /knowledge, in the SDKs as openemail.knowledge (TypeScript) and client.knowledge (Python, Ruby and PHP), in the CLI as openemail knowledge, and in the MCP tools. A key needs knowledge:read to read and knowledge:write to change items.