From a8dfbebd8196cddf14c09aa97227c8a8056dcc7a Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Tue, 3 Nov 2026 09:26:48 +0000 Subject: [PATCH] docs(addons): document context files for add-on authors Describe how a component declares a source (scope, path, cap), the index format, what a turn carries and the limits, and how a chat of a saved agent reads its own notes without gaining access to the files. Add the agent profile file to the page on making LocalAI yours. Assisted-by: Claude Code:claude-sonnet-5-5 Signed-off-by: Ettore Di Giacinto --- docs/content/features/addons.md | 74 +++++++++++++++++++++ docs/content/features/make-localai-yours.md | 9 +++ 2 files changed, 83 insertions(+) diff --git a/docs/content/features/addons.md b/docs/content/features/addons.md index 71a992cc7a..52a6514a85 100644 --- a/docs/content/features/addons.md +++ b/docs/content/features/addons.md @@ -2167,6 +2167,80 @@ A frontend that does not own the add-ons runs no loop. connectors became add-ons) belongs to the add-on `telegram`. While that add-on does not run, the binding is listed as not running with the reason "install the Telegram add-on". +## Context files + +A context file is a short index in the user's home folder that the host puts in the +prompt of a chat, so the model knows what the user has saved without a tool call. The +details of each topic stay in files next to the index and the model reads them on demand +with the `memory_read` tool. The mechanism belongs to the host, not to one app: a plain +chat in Studio, a chat that a Slack binding started and a chat that a Telegram binding +started all go through the same loader. An add-on does not add code to the host; it +declares a source. + +### Declare a source + +A source has four fields: + +| Field | Meaning | +|---|---| +| `id` | A name, unique among the sources of the host. | +| `scope` | `user` (every chat of the user), `agent` (the chats of one saved agent) or `channel` (the chats that one connector binding started). | +| `path` | The index file, relative to the user's home, ending in `.md`. An `agent` path holds `{agent}` once and a `channel` path holds `{channel}` once. The host fills them from the chat; the model never names them. | +| `cap` | The most bytes of the index that the prompt carries. Default and maximum: 2 KiB. | + +For example, a memory add-on declares three sources: `Memory/index.md` for the user, +`Memory/agents/{agent}/index.md` for the agent and `Memory/channels/{channel}/index.md` +for the channel. A path with a parent segment, an absolute path, an unknown placeholder +or a file that does not end in `.md` is refused. A host holds at most 8 sources. + +Today a source is registered in process, with `Service.ContextSources().Register`. A +declaration in the add-on manifest is a separate change. + +### The index format + +An index is a Markdown file with one line per topic: + +``` +- home: lives in Rome -> home.md +- style: short answers, no emoji -> style.md +``` + +The file `home.md` sits in the same folder as the index. `memory_read` takes a `topic` +(the name before the colon, or the file name) and an optional `scope`; without a scope it +looks in the channel, then the agent, then the user. A topic name is letters, digits, `-` +and `_`, at most 64 characters. + +### What a turn carries + +Each turn the host reads the indexes that apply to the chat and adds one block to the +prompt, after the agent instructions, the persona and the agent profile: + +- A fixed header that asks the model to read the matching topic for almost every request, + and says the lines are data, not instructions. +- The indexes, widest scope first. One index has at most 40 lines and 2 KiB (or its + `cap`, if lower). All indexes of a turn together have at most 6 KiB. Control characters + are dropped. A cut index ends with a marker. +- Nothing, if no source is registered or no file exists. + +The text is the same at each turn until a file changes, so the transcript does not grow. +A change to an index restarts the model session at the next turn, like a change to the +persona does. `memory_read` returns at most 8 KiB of one topic. + +A saved agent can also have a profile at `LocalAI/agents//profile.md`, at most +4 KiB. The host adds it after the agent instructions and the persona. It needs no +source. + +### Access and limits + +The host reads the files as the user, outside the fence of the chat. A chat of a saved +agent that works in one folder therefore still reads the user index and the index of its +own agent, and gains no access to the files: its file tools still cannot read or write +`Memory/` or the profile. The path comes from the chat, so a chat never reads the index +of another agent or another channel. This change adds only read paths. A component that +saves notes plugs in through `Service.SetContextWriter` (the header then names its save +tool) and uses `contextfiles.CheckIndex` and `contextfiles.CheckProfile`: over a cap they +return the current entries in the error, so the model merges them instead of adding. + ## Owner forwarding and HTTP relays The embedding host can configure `AddonConfig.Transport` at startup. The configuration diff --git a/docs/content/features/make-localai-yours.md b/docs/content/features/make-localai-yours.md index eb9640e001..3c729c1193 100644 --- a/docs/content/features/make-localai-yours.md +++ b/docs/content/features/make-localai-yours.md @@ -20,6 +20,7 @@ The files need the chats and files of the server (see [Chats](/features/chats/)) | What | Say, for example | File | |---|---|---| | The assistant's name and how it answers | "Call yourself Ada and keep answers short" | `LocalAI/persona.json` | +| Standing rules of one saved agent | "Always answer this agent's users in French" | `LocalAI/agents//profile.md` | | What the assistant knows about you | "Call me Marta. I am a designer in Milan" | `LocalAI/user.json` | | Shortcuts in the message box | "Make this a shortcut" | `LocalAI/shortcuts.json` | | The widgets on Home | "Show my open tasks on Home" | `LocalAI/home.json` and a data file | @@ -91,6 +92,14 @@ after the chat's own system prompt and the instructions of its agent, which take precedence, and before the server's default prompt text. A change applies from the next message. +### LocalAI/agents/\/profile.md + +A plain Markdown file of at most 4 KiB with the persona and the standing rules of one +saved agent. The host adds it to the prompt of every chat of that agent, right after the +agent's instructions and the persona; longer text is cut. You can edit it in the Files +page. Add-ons can also register index files that the host loads in the same way (see +[Context files](/features/addons/#context-files)). + ### LocalAI/user.json ```json