Agent Card Format

The agent card format is the standard for knowledge units that agents consume via the memory bus. It replaces relational lookup tables with flat files that embed into pgvector through the existing seed pipeline. No new DB schema is required — the growdirect_memory vector store is the only persistence layer.

Design Principles

One concept per card. A card holds exactly one idea — a signal, an agent, a hierarchy axis, a lifecycle gate. If a card needs subsections for multiple concepts, split it.

Every section embeds independently. The memory bus seeder chunks by heading. Each section must make sense when retrieved without the rest of the card. Write sections as if they will be read cold.

Frontmatter is machine data. All relational facts (what feeds what, which agent owns this, which module consumes it) live in frontmatter arrays. The body is prose that embeds well. Agents can filter on frontmatter fields before running semantic search.

No volatile data. Row counts, live metrics, and current-state summaries do not belong in cards. Cards capture structure, relationships, constraints, and context.

Frontmatter Schema

Required fields

Optional fields

Body Conventions

Section headings (use these in order, omit any that don't apply)

## What this is
One-sentence definition. This is the identity chunk — retrieved first by semantic search.

## Purpose
Agent-facing "why this exists." What problem does it solve, what decision does it inform.

## Structure
For hierarchies, role models, org layers: the data shape, constraints, enumerations.

## Signal
For signal feeds: what the signal contains, frequency, format, quality characteristics.

## Consumers
Which agents or modules use this. What they do with it. Be specific about the action, not just the name.

## Sources
Where the data comes from. External systems, feeds, human inputs.

## Routing
How it flows through the agent network. Show the chain explicitly.

## When to run
**Runbook cards only.** The trigger condition — what state means this procedure is needed. Be specific: "Docker stack is down and dispatch work is about to begin" not "whenever you need to restart Docker."

## Preconditions
**Runbook cards only.** What must be true before starting. Ordered list. If a precondition is not met, the procedure must not proceed.

## Canonical steps
**Runbook cards only.** Exact commands in order, with expected output noted inline. No paraphrasing — copy-paste fidelity is the standard.

## Verification
**Runbook cards only.** How to confirm the procedure succeeded. A query, a health check, a curl — something observable that produces a pass/fail signal.

## Failure modes
**Runbook cards only.** Known failure patterns with recovery steps. Each mode: symptom → cause → fix. No speculation — only confirmed failures.

## Invariants
Hard constraints. What must always be true. What must never happen. Agents enforce these.

## Related
Links to related cards using card-id syntax. One line per related card with a brief note.

How Cards Enter the Memory Bus

Cards in Brain/wiki/ (including subdirectories) are picked up by the seed pipeline:

python3 services/memory-bus/scripts/seed_standalone.py

The seeder chunks each card at heading boundaries and embeds each chunk with qwen3-embedding:8b (1024-dim). Chunks are stored in growdirect_memory with the file path and heading as metadata.

Agent recall:

memory_recall("social threat detection signal local market")
memory_recall("merchant org hierarchy head office role")
memory_recall("geography hierarchy LP district")

Filtered recall (frontmatter fields): The seeder stores frontmatter as chunk metadata. Future memory bus versions will support pre-filter by card-type, domain, or layer before vector search.

Versioning

Increment card-version on any substantive change. The seed pipeline is incremental by mtime — a version bump forces re-embedding even if the file timestamp doesn't change (when using --force). Do not reset card-version to 1 on edits; that signals a rewrite, not an update.

Card Directory

All agent cards live in Brain/wiki/cards/. Subdirectories are permitted for large domains but the flat directory is preferred until there are more than ~50 cards.