Memory Schema

Manage structured note types using Basic Memory's Picoschema system. Schemas define what fields a note type should have, making notes uniform, queryable, and validatable.

When to Use

• - New note type emerging — you notice several notes share the same structure (meetings, people, decisions)
• Validation check — confirm existing notes conform to their schema
• Schema drift — detect fields that notes use but the schema doesn't define (or vice versa)
• Schema evolution — add/remove/change fields as requirements evolve
• On demand — user asks to create, check, or manage schemas

Picoschema Syntax Reference

Schemas are defined in YAML frontmatter using Picoschema — a compact notation for describing note structure.

Basic Types

CODEBLOCK0

Supported types: string, integer, number, boolean.

Optional Fields

Append ? to the field name:

CODEBLOCK1

Enums

Use (enum) with a list of allowed values:

CODEBLOCK2

Optional enum:

CODEBLOCK3

Arrays

Use (array) for list fields:

CODEBLOCK4

Relations

Reference other entity types directly:

CODEBLOCK5

Relations create edges in the knowledge graph, linking notes together.

Validation Settings

CODEBLOCK6

Complete Example

CODEBLOCK7

Discovering Unschemaed Notes

Look for clusters of notes that share structure but have no schema:

1. 1. Search by type: search_notes(query="type:Meeting") — if many notes share a type but no schema/Meeting.md exists, it's a candidate.

1. 2. Infer a schema: Use schema_infer to analyze existing notes and generate a suggested schema:

   schema_infer(noteType="Meeting")
   schema_infer(noteType="Meeting", threshold=0.5)  # fields in 50%+ of notes
   

1. 3. Review the suggestion — the inferred schema shows field names, types, and frequency. Decide which fields to keep, make optional, or drop.

Creating a Schema

Write the schema note to schema/<EntityName>:

CODEBLOCK9

Key Principles

• - Schema notes live in schema/ — one note per entity type
• note_type="schema" marks it as a schema definition
• entity: Meeting in metadata names the type it applies to
• version: 1 in metadata — increment when making breaking changes
• settings.validation: warn is recommended to start — it logs issues without blocking writes

Validating Notes

Check how well existing notes conform to their schema:

CODEBLOCK10

Important: schema_validate checks for schema fields as observation categories in the note body — e.g., a status field expects - [status] active as an observation. Fields stored only in frontmatter metadata won't satisfy validation. To pass cleanly, include schema fields as both frontmatter values (for metadata search) and observations (for schema validation).

Validation reports:

• - Missing required fields — the note lacks a field the schema requires (as an observation category)
• Unknown fields — the note has fields the schema doesn't define
• Type mismatches — a field value doesn't match the expected type
• Invalid enum values — a value isn't in the allowed set

Handling Validation Results

• - warn mode: Review warnings periodically. Fix notes that are clearly wrong; add optional fields to the schema for legitimate new patterns.
• error mode: Use for strict schemas where conformance matters (e.g., automated pipelines consuming notes).

Detecting Drift

Over time, notes evolve and schemas lag behind. Use schema_diff to find divergence:

CODEBLOCK11

Diff reports:

• - Fields in notes but not in schema — candidates for adding to the schema (as optional)
• Schema fields rarely used — consider making optional or removing
• Type inconsistencies — fields used as different types across notes

Schema Evolution

When note structure changes:

1. 1. Run diff to see current state: INLINECODE23
2. Update the schema note via edit_note:

   edit_note(
     identifier="schema/Meeting",
     operation="find_replace",
     find_text="version: 1",
     content="version: 2",
     expected_replacements=1
   )
   

1. 3. Add/remove/modify fields in the schema: block
2. Re-validate to confirm existing notes still pass: INLINECODE26
3. Fix outliers — update notes that don't conform to the new schema

Evolution Guidelines

• - Additive changes (new optional fields) are safe — no version bump needed
• Breaking changes (new required fields, removed fields, type changes) should bump INLINECODE27
• Prefer optional over required — most fields should be optional to start
• Don't over-constrain — schemas should describe common structure, not enforce rigid templates
• Schema as documentation — even if validation is set to warn, the schema serves as living documentation for what notes of that type should contain

Workflow Summary

CODEBLOCK13