Memory & skills¶
BOS gives agents two mechanisms for working knowledge that persists beyond a single turn: memory (facts about the world and the user, maintained automatically across sessions) and skills (Markdown playbooks the agent loads on demand when it needs detailed guidance for a task). This page explains what each mechanism is, how it works, and the key configuration knobs.
For authoring custom skills see Extending BOS. For exact configuration keys see Configuration. For the hands-on tutorial see Tutorials.
Memory¶
What it is¶
Memory is platform-managed, persistent knowledge scoped to an actor. It is not a conversation transcript — it is a curated set of maxims (short, declarative facts) that the agent recalls across sessions.
The agent does not curate memory during a turn. Instead, memory consolidation runs
off-turn, from boscli memory consolidate: it reads the conversation turns a
chat has accumulated since its last run, extracts or updates maxims, and stores
them. This keeps the critical response path fast.
The consolidation loop¶
Consolidation runs off the conversational turn, on demand — nothing in the agent loop triggers it. You invoke it, or point a scheduler (cron, systemd timer, launchd) at the CLI:
boscli memory consolidate --all # or --chat <id>
│
▼
reads each chat's turns past its watermark
│
▼
consolidation agent proposes ADD / UPDATE / INVALIDATE operations
│
▼
operation service applies them and advances the watermark
│
▼
Next agent turn sees updated maxims in system prompt
Note that this is not the [harness] consolidator extension point — that one
summarises chat history for context compaction. Memory consolidation is the
MemoryPlugin's own, and runs a disposable agent with a structured-output schema.
MemoryPlugin¶
MemoryPlugin is the built-in plugin that exposes memory to agents. It is enabled
by default in the built-in agent spec. Configure it per agent (or project-wide via
[agent.defaults.plugin-bindings.MemoryPlugin]):
[agents.main.plugin-bindings.MemoryPlugin]
maxims = ["user", "self", "rules"] # which maxim categories the agent maintains (default)
[agents.main.plugin-bindings.MemoryPlugin.consolidation]
model = "" # consolidation model; defaults to BOS_CONSOLIDATOR_MODEL
maxims is the set of maxim categories the agent tracks and surfaces in its
prompt — the default is ["user", "self", "rules"] (facts about the user, the agent
itself, and standing rules). It is not a list of pre-written memory strings.
consolidation.model overrides the model the consolidation agent runs on;
otherwise it falls back to BOS_CONSOLIDATOR_MODEL, then the provider default.
Memory isolation is automatic — there is no scope option
Each agent's memory is isolated by its agent identity (the actor name), so two
actors keep separate memories with no configuration. scope is not a valid
MemoryPlugin setting — including it raises a validation error.
Memory admin¶
boscli memory provides admin subcommands to inspect, edit, and clear the memory
store for any actor without modifying config or restarting the gateway. Use it when
debugging unexpected agent behaviour or bootstrapping a new deployment.
Skills¶
What they are¶
A skill is a Markdown playbook stored as a file the agent can load on demand.
Skills implement progressive disclosure: the system prompt lists only the skill's
name and a one-line description; the agent calls the LoadSkill tool when it
decides it needs the full instructions. This keeps the context window lean while
making deep guidance available.
system prompt (every turn):
Available skills:
• coding-discipline — Behavioral guidelines to reduce LLM coding mistakes.
• python — Python-specific conventions for this project.
agent decides it needs detail → calls LoadSkill("coding-discipline")
│
▼
full skill body injected into the conversation
The SKILL.md format¶
Each skill is a directory containing a SKILL.md file. The directory name is the
skill's name. The file has a short YAML-ish frontmatter block followed by the full
instruction body:
---
name: coding-discipline
description: Behavioral guidelines to reduce common LLM coding mistakes. Load before writing code.
---
## 1. Think Before Coding
...
The description is what appears in the system prompt listing. The body (everything
after the frontmatter) is returned by LoadSkill.
skill_dirs and the __builtin__ sentinel¶
SkillsPlugin discovers skills by scanning a list of parent directories. The list
is configured under [exts.pep_skills_loader.FileSystemSkillsLoader]:
[exts.pep_skills_loader.FileSystemSkillsLoader]
skill_dirs = ["__builtin__", "skills"] # default value
The __builtin__ sentinel expands, in place, to:
- The packaged skills that ship with BOS (
bos.skills). - Skills contributed by installed Python packages via the
bos.skillsentry-point group.
Any explicit directory after __builtin__ is resolved relative to bos_dir.
Later entries win on name collision, so workspace skills override packaged
skills, and package-contributed skills override the BOS built-ins. This means you
can shadow any built-in skill by creating a directory of the same name in your
skills/ folder.
Ordering examples:
skill_dirs value |
Effective search order (last wins) |
|---|---|
["__builtin__", "skills"] |
built-ins → package contributions → bos_dir/skills/ |
["skills", "__builtin__"] |
bos_dir/skills/ → built-ins → package contributions |
["skills"] |
only bos_dir/skills/; no built-ins |
Visibility controls¶
Configure which skills are visible and loadable via SkillsPlugin bindings:
[agents.main.plugin-bindings.SkillsPlugin]
preload = ["coding-discipline"] # load these fully into the prompt at startup
allow = [] # if non-empty, only these skills are listed
exclude = [] # skill names never listed or loadable
preload: skill names to inject fully into the system prompt at startup — skips theLoadSkillround-trip. Use for skills the agent should always apply without being prompted.allow: an explicit allow-list. When non-empty, only listed skills appear in the prompt and are loadable.exclude: an explicit block-list. Named skills are removed from the listing regardless ofallow.
Built-in skills¶
BOS ships three skills in the __builtin__ set:
| Skill | Description |
|---|---|
coding-discipline |
Behavioral guidelines to reduce common LLM coding mistakes. Load before writing code. |
python |
Python-specific conventions (type hints, error handling, testing patterns). |
skill-creator |
Instructions for writing and structuring new SKILL.md files. |
Contributing skills from a package¶
Install a Python package that declares the bos.skills entry point, and its skill
directories will slot in at the __builtin__ position automatically — no config
change needed in the consuming project:
# In the package's pyproject.toml:
[project.entry-points."bos.skills"]
my-package = "my_package.skills" # package whose directory holds skill subdirs
For a full walkthrough of authoring and packaging skills see the Extending section.