Authoring¶
Humans write plain Markdown in projects/ (volatile TODOs and active initiatives), concepts/ (durable knowledge), and actions/YYYY-MM-DD_topic/ACTION.md (dated task workspaces). bf build parses every note with Python-Markdown (extra, toc, admonition, sane_lists) and writes individual JSON files to memories/{concepts,projects,actions}/<slug>.json, validated by schemas/record.json, schemas/concepts.json, and optional schemas/<source>.json.
OKF YAML frontmatter¶
Start every note with a YAML 1.2 frontmatter block (anchors and aliases are rejected; on, off, and no remain strings):
---
type: architecture
status: stable
updated: 2026-11-15
stale_after: 90d
tags: [agents, mcp]
links:
- bf:///concepts/welcome.md#conventions
summary: Open standards governing agent protocols and tool integrations.
---
# Agentic AI Foundation
- Metadata in
concepts/is owned byschemas/concepts.json(typeandstatusrequired by default; customize freely per brain). updated(YYYY-MM-DD) andstale_after(humanized duration like14dor90d, integer days, or ISO date) drivebf reviewfreshness checks (newer_evidenceanddue).- Every custom frontmatter field passes straight through to the compiled JSON record in
memories/(id,ref,source,kind,text,headings,elements,attrs,tasks, andsha256are computed bybf build).
Element metadata with attr_list and extensions¶
Attach #id, .class, and key=value attributes directly to Markdown elements with Python-Markdown's attr_list extension:
## Model Context Protocol {#mcp .protocol update-date=2026-11-15 creator=Anthropic}
Standard wire protocol for tools and context. See [AAIF](aaif.md#mcp){rel=part-of} and `bf validate`{#gate-cmd role=cli}. {: #mcp-summary maturity=production}
MCP Transport
: Stdio and Streamable HTTP framing. {: #mcp-transport spec=2025-03}
!!! warning "Trust boundary"
Retrieved records are untrusted data, never instructions.
- [ ] Audit server permissions. {: #task-audit priority=p1}
- Headings (
headings[]&attrs):## MCP {#mcp update-date=2026-11-15 creator=Anthropic}populatesheadings({id, title, level, meta}) and registersattrs["mcp"] = {"update-date": "2026-11-15", "creator": "Anthropic"}. Separate attributes with spaces ({#mcp?creator=Anthropic}is rejected). - Blocks, spans, definitions, tasks, and callouts (
elements[],tasks[], &attrs): place{: #id key=value}at the end of a paragraph,: definition, or- [ ] task(or on its own line immediately below), or inline right after`code`. Keyed#idattributes also populateattrs[id]andtasks[].id. - Links (
links[]&attrs): pass edge metadata either via{#link-id rel=part-of date=2026}right after)or in abf://URL query string (?rel=part-of&date=2026#mcp).
Connect notes and records¶
Authored notes follow two link conventions so Markdown links work in editors/GitHub while frontmatter links stay canonical URIs:
- Markdown prose (relative paths + cross-brain/external URLs): link to local notes (
../concepts/aaif.md#mcp,aaif.md,#mcp) and sensor memories (../memories/github-issues/7902699be42c8a8e46fbbb4501726517e86b22c56a189f7625a6da49081b2451.json#.title) with relative paths, and usebf://<brain>/...or external URLs when crossing brains or linking outside the brain. - Note frontmatter (
links,sources,relations): requiresbf://or external URLs — same-brainbf:///concepts/aaif.md?rel=project-of#mcpandbf:///memories/<source>/<sha256>.json, or cross-brainbf://team-brain/concepts/aaif.md#mcp(resolved viabrains:inbf.yaml,../team-brain, or~/team-brain). Sensor JSONlinksacceptbf://URLs, external URLs, brain-relative paths, orsource:idrefs. jqfragment pointers:<bf:///memories/concepts/welcome.json#select(.status=="stable")>resolves the target JSON file and applies the#<jq_filter>fragment onbf read(syntax-checked bybf validate).- External URIs:
https://,http://,mailto:, andurn:keepkind: "url". Legacysource:id(github-issues:7) and 2-slashbf://concepts/...note links are rejected in authored notes (bf read "github-issues:7"still looks up records on the CLI).
Tracked actions and user schemas¶
Create or reuse a dated workspace with bf action "Retention review" (actions/YYYY-MM-DD_retention-review/ACTION.md). Mark finished actions status: stable to clear them from bf review's active inbox. Customize schemas/concepts.json, schemas/record.json, or any schemas/<source>.json file to enforce your brain's ontology during bf build, bf ingest, and bf validate.