Your next reader
is not human.

For twenty years, notes had one audience: people. You wrote for a future reader with eyes, patience, and context. That has changed. Increasingly, the most frequent reader of your knowledge base is an AI assistant answering questions from it, drafting from it, or acting on it. And AI readers have different strengths and different failure modes than human ones.

This lesson explains, in plain language, what makes a knowledge base AI-readable: what tokens and context windows are, why format matters far more than people expect, what APIs and MCP actually do, how to give AI access without giving it the keys to everything, and a checklist you can apply this week. No engineering background required.

Tokens and context windows, simply

AI language models do not read words; they read tokens, small chunks of text averaging roughly three-quarters of an English word. "Meeting notes from Tuesday" is about five tokens. This matters for one reason: every model has a context window, a hard limit on how many tokens it can consider at once. Think of it as the model's desk: everything it uses to answer you (your question, the documents you give it, its own reply) must fit on the desk at the same time.

Context windows have grown large, but they are never infinite, and two practical facts follow. First, if your document collection is bloated, less of it fits, and the model answers from a partial view. Second, most AI services charge by the token, so bloat is not just a quality problem, it is a bill. The economical question is always: how much meaning per token does this format deliver?

Why format matters: structured text versus PDF

Consider the same one-page project update in two forms. As Markdown or a structured note, it is a few kilobytes of clean text: headings marked as headings, lists as lists, a table as a table. The model sees exactly the structure the author intended.

As a PDF, that page is a print format doing its actual job, which is to place ink on paper: positioned text runs, font data, layout coordinates. Extracting text back out of it is a recovery operation, and things break in the process. Multi-column layouts interleave, tables collapse into word soup, headers and footers repeat into the text on every page, and headings lose their heading-ness. The model gets more tokens carrying less meaning, and it has to guess at structure the PDF destroyed.

The lesson generalizes: structure that software can see beats structure that only eyes can see. This is why block-based notes (lesson one) age so well in the AI era. A block editor stores a heading as a heading and a table as a table, so exports are clean and machine-readable by construction. If your knowledge lives in PDFs and screenshots, the first step toward AI-readiness is converting the living documents back into text. You can feel the difference yourself with the AI context calculator.

APIs and MCP, explained for non-engineers

Copy-pasting notes into a chat window works, but it does not scale past a handful of documents. The scalable path is letting the AI fetch what it needs, which is what two pieces of plumbing are for.

An API (application programming interface) is a door for software. Where you click through an app's interface, a program knocks on the API: "give me the page titled Launch Plan Q3", "list pages changed this week", "create a page with this content". Every serious integration between two tools goes through one. NoteX's public API follows Notion's conventions deliberately: if a tool or a developer already speaks Notion's API, they already mostly speak NoteX's.

MCP (Model Context Protocol) is a newer, open standard that answers a more specific question: how does an AI assistant discover and use tools? An MCP server presents a menu of actions ("search the workspace", "read a page", "append blocks") that any MCP-capable assistant, such as Claude or an AI code editor, can see and invoke. The practical meaning: instead of you feeding documents to the AI, the AI looks things up itself, mid-conversation, fetching only what the task needs. Ask "what did we decide about search ranking?" and the assistant searches your workspace, reads the relevant page, and answers with the current truth, not with whatever you remembered to paste.

NoteX ships both: the REST API and an MCP server with ten tools covering search, reading, creating, updating, appending, and trash. Details live on API & MCP. On NoteX Desktop the relationship also runs the other direction: AI add-ons like Claude Code work inside the app, reading and editing notes as local files. One phrase captures the design: your AI works inside NoteX, and NoteX works inside your AI.

Scoped access: give agents keys, not master keys

The moment software can read your knowledge base, security stops being abstract. The principle to internalize is least privilege: every integration gets exactly the access its job requires, and no more. In practice that means API keys with scopes, and the scopes worth understanding apply to any tool, not just NoteX:

• Read-only versus read/write. An assistant that answers questions needs to read, period. Granting write access to a reader is free risk. Reserve read/write keys for integrations whose job is creating or editing content.
• Scope by area. A key limited to specific pages or sections cannot wander. The meeting-summarizer agent needs meeting notes, not the personnel folder.
• Expiry. Keys for experiments should die on their own. A key created for a demo in March should not still open doors in November.
• Logging. You should be able to see what each key did and when. Usage logs turn "I wonder what that integration does" into a list you can read.
• One key per integration. Never share a key across tools; when one is compromised or retired, you revoke it without breaking everything else.

NoteX API keys (prefixed nx_) implement this set: read-only or read/write, optional page scoping, optional expiry, with every request logged. But the checklist is the point; hold any tool you evaluate to it.

The AI-readiness checklist

A practical pass you can run on your own knowledge base in an afternoon:

• Living documents are text, not print formats. The wiki, runbooks, and specs exist as structured notes or Markdown. PDFs remain for what they are for: signed, final, archival artifacts.
• Structure is explicit. Real headings, real lists, real tables (lesson one). One topic per page, so retrieval fetches focused pages rather than 40-page omnibus documents.
• Titles say what pages contain. AI retrieval, like human search, starts from titles. "Runbook: Deploys" retrieves; "Misc notes (new)" does not.
• The knowledge is current. An AI answering from a stale wiki is confidently wrong at scale. The ownership and review rituals from lesson three are now also an AI-quality practice.
• Access is programmatic. An API or MCP server exists, so assistants fetch live content instead of you pasting snapshots.
• Access is scoped. Each integration has its own least-privilege key, with expiry and logs.
• Sensitive material is segregated. What agents must never read lives in spaces the keys do not reach. In NoteX terms: private notes, a non-synced Local workspace, or simply pages outside every key's scope.

Teams building seriously on this pattern will find a deeper treatment in NoteX for AI teams. The final lesson of this course turns to the moment all this preparation gets tested: moving your knowledge from one tool to another.