Schema System

In Basic Memory, your notes are Markdown files with structured information — facts (called observations) and links to other notes (called relations). A schema describes what a particular type of note should contain — like making sure every person note has a name.

Schemas are optional. You can use Basic Memory without ever defining one. But as your knowledge base grows, schemas help you keep notes consistent and give your AI a guide for creating well-structured notes.

Why schemas?

After writing hundreds of notes over several months, you might notice inconsistency: some person notes have a name, some don't. Some link to an employer with "works_at", others say "employed_by." The information is all there, but the lack of consistency makes it harder to search and build on.

Schemas let you define what "consistent" means for a note type, and then check your notes against that definition. The key insight is that schemas describe your existing patterns — they don't force a rigid template upfront. You write notes however feels natural, then add schemas later to bring order to what you've already created.

How it works

The most natural way to use schemas is through conversation with your AI assistant.

Discovering patterns:

You: "I've been writing a lot of person notes. Can you figure out
      what structure they have in common?"

AI: [Analyzes your person notes]

Looking at your 45 person notes, here's what I found:
- "name" appears in 95% of notes
- "role" appears in 80%
- "works_at" link appears in 60%
- "expertise" appears in 40%

Want me to create a schema based on these patterns?

Creating a schema:

You: "Yes, make name required and the rest optional."

AI: [Creates a schema note]

Done! I've created a Person schema. Notes with type "person"
will be checked against it.

Validating notes:

You: "How do my existing person notes look against that schema?"

AI: [Validates all person notes]

42 of 45 notes pass. Three are missing a name:
- people/mystery-contact.md
- people/quick-note-jane.md
- people/old-import-2024.md

Want me to fix those?

Checking for drift later:

You: "It's been a few months — are my person notes still consistent?"

AI: [Compares schema against actual usage]

Most notes still follow the schema. I notice "linkedin"
is showing up in 35% of newer notes but isn't in the schema.
Want me to add it as an optional field?

Writing with schema guidance:

When a schema exists for a note type, your AI uses it as a creation guide automatically. It includes all required fields and relevant optional ones without you having to ask.

Your schemas do double duty: they help you maintain consistency and they guide AI assistants toward producing notes that match your preferred format.

What schemas check

Schemas check that your notes include the information you care about:

• Facts — A schema can require specific facts. If your person schema says "name" is required, Basic Memory expects to find a name in the note.
• Links — A schema can define expected links to other notes. If "works_at" is defined, Basic Memory expects a link to an organization.
• Metadata — Schemas can check for specific properties in the metadata block at the top of a note (title, tags, type).

Schemas are just regular notes themselves. There's nothing special about them — they live in your knowledge base alongside everything else.

Validation

By default, schemas give gentle warnings when something's missing — they don't block anything. You can make them stricter once your patterns stabilize.

Start with warn mode. Move to strict only after your note patterns have settled down and you're confident in the schema.

Schema ideas to try

You don't need to write schemas by hand. Tell your AI what you want to track, and it creates the schema for you. Here are some starting points.

Task tracking

Keep a simple task list without a separate project management tool.

Prompt your AI:

"Create a schema for tasks. Each task should have a status (todo, in-progress, done), a priority (low, medium, high), and optionally link to a project."

What the AI creates:

schema:
  title: string, what needs to be done
  status(enum): [todo, in-progress, done], current state
  priority?(enum): [low, medium, high], how urgent
  due_date?: string, target completion date
  belongs_to?: Project, related project
  blocked_by?(array): Task, dependencies

Then use it naturally:

"Create a task to update the API docs, medium priority, for the v2 project." "What tasks are in progress right now?" "Mark the API docs task as done."

Meeting notes

Capture decisions and action items so they don't get lost in a wall of text.

Prompt your AI:

"I want a schema for meeting notes. Track who attended, what we decided, and what needs to happen next."

What the AI creates:

schema:
  date: string, when the meeting happened
  attendees(array): string, who was there
  summary?: string, brief overview
  decisions?(array): string, what was agreed on
  action_items?(array): string, follow-up tasks
  relates_to?(array): Project, projects discussed

Then use it naturally:

"Write up today's meeting with Sarah and Tom. We decided to delay the launch by a week. Sarah will update the timeline, Tom will notify partners." "What action items came out of meetings this week?"

Research notes

Organize what you're learning about a topic — articles, key takeaways, open questions.

Prompt your AI:

"Create a schema for research notes. I want to track the source, key findings, and how it connects to other research."

What the AI creates:

schema:
  topic: string, what this research is about
  source?: string, where the information came from
  findings?(array): string, key takeaways
  questions?(array): string, open questions or things to explore
  relates_to?(array): Research, connected research notes
  supports?: Hypothesis, hypothesis this evidence supports

Then use it naturally:

"I just read this article about sleep and memory consolidation. The key finding is that deep sleep within 4 hours of learning improves retention by 40%. This relates to my learning-techniques research." "What open questions do I have across my research notes?"

Recipes

Track what you cook, what worked, and what to tweak next time.

Prompt your AI:

"Make a schema for recipes. I want to track ingredients, steps, and my own notes about what I'd change."

What the AI creates:

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 and observations
  inspired_by?: Recipe, adapted from another recipe

Then use it naturally:

"Save this pasta recipe I tried tonight. It's a carbonara, serves 2. I used guanciale instead of pancetta and it was way better. Next time use less pepper." "What recipes have I noted tweaks for?"

Roll your own

These are just starting points. The real power is that you can describe any structure and the AI builds it:

"Create a schema for book notes with author, genre, my rating out of 10, key quotes, and what I'd tell a friend about it."

"I want to track my workouts. Sets, reps, weight, and how I felt."

"Make a schema for project decisions — the context, what we chose, what we rejected, and why."

The AI reads your schemas automatically when creating notes of that type, so once a schema exists, your notes just come out consistent.

Best practices

• Use specific note types — Choose clear type values like person, meeting, decision rather than leaving everything as note.
• Let the AI infer first — Let Basic Memory analyze your existing patterns before writing schemas by hand.
• Keep schema notes together — Use a schemas/ folder for easy discovery.
• Check for drift periodically — Run a schema check every few weeks to keep schemas aligned with how you actually write notes.
• Adopt gradually — Start with warn mode. Move to strict only after patterns stabilize.
• Version your schemas — Track schema evolution over time as your needs change.

Technical Reference

The sections below cover schema syntax, configuration, and tool parameters. You don't need to read this section to use schemas — your AI handles the details for you.

Picoschema syntax

Schemas use Picoschema — a compact YAML-based syntax for defining fields. Each line declares a field name, its type, and an optional description.

Types

When a type name is capitalized (like Organization), it signals an entity reference — Basic Memory expects a wiki-link relation rather than a plain observation.

Modifiers

Descriptions

Add a description after a comma to document what the field means:

name: string, full legal name
role?: string, current job title or position
works_at?: Organization, primary employer

Complete annotated example

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

This schema says: every note of this type must have a name observation. It should have a role, email, works_at relation, and so on — but those are optional. The expertise field expects multiple observations (an array). The status field constrains values to one of three choices.

Defining schemas

There are three ways to create a schema.

1. Dedicated schema note (recommended)

Create a markdown file with type: schema in its frontmatter. This is the best approach for note types you use repeatedly — person, meeting, decision, project, and so on.

---
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. Every person note should have a name
and optionally include their role, contact info, and employer.

Use `type: person` in your note frontmatter to match this schema.

The note body is regular markdown — use it to describe the schema's purpose, provide examples, or document conventions. Basic Memory reads the schema definition from the frontmatter; the body is for humans.

Frontmatter fields for schema notes:

Place schema notes in a schemas/ folder by convention (e.g., schemas/person.md), though any location works.

2. Inline schema in a single note

Useful for one-off structure or prototyping before committing to a reusable schema:

---
title: Team Standup 2026-02-10
type: meeting
schema:
  attendees(array): string, participants
  decisions?(array): string, outcomes
  blockers?(array): string, unresolved issues
  action_items?(array): string, follow-up tasks
---

The schema applies only to this specific note. If you find yourself copying the same inline schema into multiple notes, promote it to a dedicated schema note.

3. Explicit schema reference

Point a note to a schema by name or path:

---
title: Ada Lovelace
type: person
schema: Person
---

Or by path:

---
title: Ada Lovelace
type: person
schema: schemas/person
---

This is useful when the note's type doesn't match the schema's entity field, or when you want to be explicit about which schema to use.

Schema resolution order

When validating a note, Basic Memory finds the right schema by checking in this order:

1. Inline schema — If the note has a schema dict in its frontmatter, use that directly.
2. Explicit reference — If the note has a schema string in its frontmatter (like schema: Person), look up that schema note by title or path.
3. Implicit by type — Look for a schema note whose entity field matches the note's type. For example, a note with type: person automatically matches a schema note with entity: person.
4. No schema — If none of the above match, no validation is performed. This is fine — not every note needs a schema.

How fields map to notes

Each field in a schema corresponds to something Basic Memory expects to find in the note:

CLI reference

# Analyze your existing notes to discover patterns
bm schema infer person

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

# Validate a single note
bm schema validate people/ada-lovelace.md

# Validate all notes of a type
bm schema validate person

# Check for drift over time
bm schema diff person

See the CLI Reference for full flag documentation.

MCP tool parameters

See the MCP Tools Reference for full schema_validate, schema_infer, and schema_diff parameter tables.

Complete example

Here's a full workflow for adding schemas to an existing knowledge base.

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
---

A conforming person 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:

$ bm schema validate people/ada-lovelace.md
✓ ada-lovelace: valid (0 warnings)

If [name] were missing:

$ bm schema validate people/ada-lovelace.md
⚠ ada-lovelace: missing required field: name

Common issues

No schema found — Create a schema note with type: schema for that note type, add an inline schema, or use an explicit schema: reference in frontmatter.

Missing required field — Add the observation or relation expected by the schema. For example, if name: string is required, add - [name] Ada Lovelace to the note.

Too many warnings — Either relax the schema by making more fields optional (?), or lower the inference threshold and regenerate with bm schema infer person --threshold 0.1.

Next steps