A Bourdon memory is a directory of YAML files. Each agent gets one file, the L5 manifest, and every field in it is defined by a published JSON Schema you can validate against offline. This page is that schema in prose, with a complete example at the end.
On disk#
~/agent-library/
agents/
claude-code.l5.yaml one manifest per agent (the L5)
codex.l5.yaml
cursor.l5.yaml
versions/ archived prior states, one per commit (undo history)
staging/ quarantined writes awaiting operator review
Only agents/*.l5.yaml is read by the federation. versions/ is the rollback history and staging/ is invisible to every read until promoted. Manifests are written atomically (temp file, then rename).
The schema#
Canonical, versioned, and served from this domain:
https://bourdon.ai/schema/L5_manifest_v0.1.json
The published copy is byte-checked against the repository on every site build (SHA-256 96892aef…f846d57), so the URL above and spec/L5_schema.json never disagree. Spec version is currently 0.1. Each manifest declares the version it conforms to, and the L6 store warns when it reads an incompatible one.
Top level#
| Field | Required | Meaning |
|---|---|---|
spec_version | yes | Spec version this manifest conforms to ("0.1"). |
agent | yes | Who wrote this. See below. |
last_updated | yes | ISO 8601 UTC timestamp of the last regeneration. |
capabilities | no | Free-text slugs the agent offers, so a query can ask "which agent can analyse images?" |
recent_sessions | no | Rolling window of dated sessions. Up to 500. |
known_entities | no | The glossary: things this agent knows about. Up to 1000. |
known_workstreams | no | Multi-session initiatives with a lifecycle status. Up to 200. |
notes | no | Freestanding journal entries. Up to 1000. |
visibility_policy | no | Default visibility and tag-to-visibility rules. |
agent#
| Field | Required | Meaning |
|---|---|---|
id | yes | Slug, also the filename and the cross-agent reference key. Pattern ^[a-z0-9][a-z0-9_-]*$. |
type | yes | One of code-assistant, note-capture, local-swarm, customer-support, research-assistant, creative-collaborator, project-manager, tutor, other. |
instance | no | Machine or deployment identifier, for the same agent on several machines. |
role_narrative | no | Free text distinguishing agents that share a type (Claude Code as reviewer, Codex as lead author, and so on). |
spec_version_compat | no | npm-style semver range of spec versions this manifest is compatible with. |
Entity#
| Field | Required | Meaning |
|---|---|---|
name | yes | Human-readable name. This is what recognition matches on. |
type | no | Free-text category. Common: project, product, person, customer, ticket, concept, decision. |
aliases | no | Alternative names that should also trigger recognition. |
summary | no | One to three sentences, under 500 characters. This is the glossary entry other agents see. |
last_touched | no | ISO 8601 date. |
valid_from, valid_to | no | Temporal validity window, so a query can ask what was active in a given quarter. |
tags | no | Free text. Feeds visibility_policy matching and query filters. |
visibility | no | Overrides the policy default for this row. |
Session#
| Field | Required | Meaning |
|---|---|---|
date | yes | ISO 8601 date, date-only. An empty string means the native store carried no recognisable timestamp; participants never substitute the current date. |
cwd | no | Working directory. Optional but the main join key for developer tools. |
project_focus | no | Entity names the session concerned. |
key_actions | no | One to five short strings saying what happened. |
files_touched | no | Paths or patterns modified. |
visibility | no | Row override. |
Workstream#
| Field | Required | Meaning |
|---|---|---|
name | yes | Human-readable name. |
status | yes | active, paused, done, or archived. |
summary, started, last_touched, related_entities, tags, visibility | no | As for entities. |
Note#
| Field | Required | Meaning |
|---|---|---|
date | yes | ISO 8601 date. |
text | yes | Freeform. A journal entry, not an action log. |
related_entities, tags, visibility | no | As above. |
Visibility#
Three levels, applied per row and re-applied at query time:
| Level | Reaches |
|---|---|
public | every L6 store, including peers |
team | the team's L6 stores |
private | this machine only, never federated outward |
visibility_policy sets the default for rows that do not declare their own and maps tags to levels. A typical policy:
visibility_policy:
default: team
private_tags: [personal, financial, credential, secret, health, family, legal]
team_tags: [project, active]
Two enforcement points, and both are tested: the participant applies visibility before a row is ever written, and the L6 store filters again on every read according to the caller's access_level. Shipped manifests are additionally scanned for credential shapes and leaked private rows by bourdon audit-leaks, which runs as a CI gate.
A complete example#
Everything below validates against the schema. It is the shape a small participant emits after one session.
spec_version: "0.1"
agent:
id: sample
type: code-assistant
role_narrative: >-
Reference assistant working on public sample data.
spec_version_compat: "0.1"
last_updated: "2026-06-26T00:00:00Z"
capabilities:
- state_db
- memories_dir
known_entities:
- name: Bourdon
type: project
summary: Cross-agent memory federation; recognition-first runtime.
visibility: team
tags: [project, active]
- name: Concise answers
type: preference
summary: Prefers terse, high-signal responses.
visibility: team
recent_sessions:
- date: "2026-06-24"
project_focus: [bourdon]
cwd: /projects/bourdon
files_touched:
- core/leak_audit.py
- tests/test_leak_audit.py
key_actions:
- Hardened the federation leak auditor to scan every federated string.
visibility: team
visibility_policy:
default: team
private_tags: [personal, financial, credential, secret, health, family, legal]
team_tags: [project, active]
Validate it yourself with any JSON Schema validator:
pip install check-jsonschema pyyaml
check-jsonschema --schemafile https://bourdon.ai/schema/L5_manifest_v0.1.json sample.l5.yaml
Why YAML, why this small#
Because you can read it, diff it, and leave with it. The manifest is a projection of an agent's memory, not the memory itself: the agent keeps its own store and Bourdon keeps a glossary of what is in it. That keeps the format stable while agents change, keeps private rows out by construction, and means a memory layer you can inspect with cat is the whole product, not a debugging view of it.