Skip to content

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:

  1. The packaged skills that ship with BOS (bos.skills).
  2. Skills contributed by installed Python packages via the bos.skills entry-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 the LoadSkill round-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 of allow.

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.