#When You Need Your Notes to Be Consistent

One of the best things about Basic Memory is that you don’t have to plan anything. You just start writing. Notes add up, ideas connect, patterns emerge on their own. That loose, organic quality is part of what makes it work. Your knowledge base grows the way thinking actually grows.

But not everything benefits from that looseness.

Some things need to be consistent every single time. A recipe should always list its ingredients. A task should always have a status. A meeting note should always capture who was there and what was decided.

That’s what schemas are for.

What a Schema Is

A schema is a template for a type of note. You define it once so your AI can use it every time a note of that type gets created or updated.

Say you want every recipe note to include the cuisine, the number of servings, a list of ingredients, and the cooking steps. You tell your AI that once. It saves a schema. Now when your AI creates a recipe note, it has the structure available to work from.

Like all things in Basic Memory, the schema itself is just a note. It lives in your knowledge base like everything else. You can open it, read it, edit it by hand. Your AI can read it too, whenever it’s working on that type of note.

Here’s what a recipe schema actually looks like as a file:

---
title: Recipe
type: schema
entity: recipe
schema:
  cuisine?: string, type of cuisine
  servings?: integer, how many it feeds
  prep_time?: string, how long to prepare
  ingredients(array): string, what you need
  steps(array): string, how to make it
  notes?(array): string, personal tweaks
  inspired_by?: Recipe, adapted from another recipe
---

# Recipe

Schema for recipes in the knowledge base. Every recipe
should list its ingredients and steps. Cuisine, servings,
and prep time are nice to have. Link to other recipes
with `inspired_by` when one recipe builds on another.

A markdown file with some YAML and a description. The body text matters — it gives your AI the context to understand why a field exists, not just that it exists. The ? means optional. The (array) means there can be more than one. Recipe with a capital letter means a link to another note. Simple declarations, no configuration files, no setup wizards.

How to Create One

Establishing a schema is as simple as telling your AI what you want.

“I want all my notes about my daily reading to include book title, author, page count, date of publication, my thoughts on the book, and a 1 to 10 rating of the book.”

That’s it. Your AI creates the schema note for you. Now it has a reference to work from whenever it’s creating or updating a book note.

If you’ve already been saving book notes for a while and want to bring consistency to what you’ve already written, your AI can figure out the pattern from what exists:

“Look at all my book notes and figure out what they have in common.”

It analyzes your existing notes, finds the patterns, and proposes a schema based on what you’ve already been doing naturally. You review it, adjust anything that doesn’t look right, and confirm. Then it can check your existing notes against the new template and offer to fix any that don’t match.

The result is that you end up with a consistent, reliable structure without having to design anything upfront.

Keeping It Honest Over Time

Notes evolve. Sometimes you start tracking things you didn’t think to include at first. Maybe you start noting where you bought a book, who recommended it, or whether you’re reading it alone or as part of a book club.

You can ask your AI: “Have any new patterns arisen from my reading notes?”

It compares what you’ve actually been writing to what the schema says. Maybe you’ve been adding a source field that isn’t in the template yet. Maybe there’s a field nobody uses anymore. It shows you the gaps and you decide what to update.

Your schema stays honest to how you actually work, not how you planned to work six months ago.

It Works for More Than Just Books

Schemas are useful anywhere you want a repeatable shape. A few examples people actually use:

Task tracking. Every task has a status, a priority, maybe a due date and a link to a project. You ask your AI to create a task, it fills in the right fields. You ask “what’s still in progress?” and every task has a status field to answer from.

Meeting notes. Who was there, what was decided, what happens next. Three months later you can ask “what did we decide about the API redesign?” and your AI finds the decision in exactly the place it expects it.

Research notes. Source, key findings, open questions, connections to other research. Each note links to what it supports or contradicts. Over time you build a web of evidence that your AI can actually navigate.

The point isn’t that schemas make your AI smarter. They make your information more legible. When every meeting note has a decisions field, finding decisions is trivial. When some meeting notes bury decisions in paragraph three and others use a bullet list and others don’t record them at all, your AI is guessing.

Why This Makes Your AI More Useful

When your notes have a consistent shape, your AI can answer questions with real precision.

“Show me all my pasta recipes that serve fewer than four.” “What tasks are still held up because John won’t make a decision?” “Who did we decide to follow up with after last Tuesday’s meeting?”

Queries like this are reliable when every note of that type is structured the same way. Without that consistency, your AI does its best, but it misses things. Not because it’s not smart enough, but because the information isn’t where it expects it to be. Without a schema, maybe that information isn’t there at all. Your AI wouldn’t know to ask for page count, serving size, or any of the particulars you care about.

You define the shape once, and the reliability follows.

Make It Even More Reliable with Agent Skills

Schemas work best when your AI knows to look for them. The memory-schema agent skill is a pre-built instruction set that teaches your AI to actively check for and follow schemas when creating or updating notes — making consistent structure much more likely in practice.

You can install it alongside the rest of the Basic Memory skills:

npx skills add basicmachines-co/basic-memory-skills

Learn more about agent skills

For the Nerds

Everything above works through conversation — you talk to your AI, it handles the details. But if you want to understand what’s actually happening under the hood, or you prefer working with the tools directly, here’s how the schema system is put together.

Picoschema Syntax

Schemas use a compact YAML syntax for declaring fields. Each line is a field name, a type, and an optional description:

schema:
  name: string, full legal name
  role?: string, current job title
  works_at?: Organization, primary employer
  expertise?(array): string, areas of knowledge
  status?(enum): [active, inactive, alumni]
  contact_info?(object):
    phone?: string
    location?: string

The modifiers:

Types are what you’d expect: string, integer, number, boolean, any. A capitalized name like Organization or Project means the field is a relation — a [[wiki-link]] to another note.

How Fields Map to Notes

Schema fields correspond directly to the observation and relation format Basic Memory already uses:

Nothing new to learn. If you already know how Basic Memory notes work, schemas are just a way to say “this type of note should always have these fields.”

Schema Resolution

When Basic Memory validates a note, it looks for a matching schema in this order:

1. Inline — a schema: dict defined directly in the note’s frontmatter
2. Explicit reference — a schema: Person string pointing to a named schema note
3. Implicit by type — a schema note whose entity field matches the note’s type
4. No schema — nothing found, validation skipped, and that’s fine

This means you can start with inline schemas while you’re experimenting, then promote them to dedicated schema notes when the pattern stabilizes.

Validation Modes

Schemas support three validation modes, set in the schema’s settings:

Start with warn. Move to strict once you trust the schema and want to enforce it.

CLI Tools

Three commands give you direct control:

# Analyze existing notes and propose a schema from patterns
bm schema infer person

# Save the inferred schema as a permanent note
bm schema infer person --save

# Validate notes against their schema
bm schema validate person

# Check for drift between schema and actual usage
bm schema diff person

schema infer is the interesting one. It reads all your notes of a given type, counts how often each field appears, and proposes a schema based on frequency. Fields that show up in 90% of notes become required. Fields that show up in 40% become optional. You review and adjust.

A Complete Example

The schema note (schemas/person.md):

---
title: Person
type: schema
entity: person
version: 1
schema:
  name: string, full name
  role?: string, job title
  email?: string, contact email
  works_at?: Organization, employer
  expertise?(array): string, areas of knowledge
settings:
  validation: warn
---

# Person

Schema for people in the knowledge base.
Use `type: person` in your note frontmatter to match.

A conforming note (people/ada-lovelace.md):

---
title: Ada Lovelace
type: person
---

# Ada Lovelace

## Observations
- [name] Ada Lovelace
- [role] Mathematician and Writer
- [expertise] Mathematics
- [expertise] Computing theory

## Relations
- works_at [[Analytical Engine Project]]

Validation says ✓ ada-lovelace: valid (0 warnings). Remove the [name] line, and you get ⚠ ada-lovelace: missing required field: name.

That’s the whole system. Schemas describe your patterns, validation catches drift, and everything is just markdown files you can read, edit, and version control like anything else.

Full schema system reference