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 <mudler@localai.io>

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/<agent>/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

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/<agent>/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/\<agent\>/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