Schema lifecycle management for Basic Memory: discover unschemaed notes, infer schemas, create and edit schema definitions, validate notes, and detect drift. Use when working with structured note types (Task, Person, Meeting, etc.) to maintain consistency across the knowledge graph.

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. Project scope If the project is unknown, discover it with bm project(command="list") . Pass a nonempty project on every note, folder, context and schema call, even with one project or a qualified memory:// URL. Use the chosen project's name, workspace/project , or external ID; <project below is a placeholder for it. Recent activity also requires project . Search accepts project for one project, projects for selected projects, or all projects=True explicitly. Discovery and bundled manuals need no project. Keep the same scope when following returned paths, paginating, or recovering from a refusal. 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 Supported types: string , integer , number , boolean . Optional Fields Append ? to the field name: Enums Use (enum) with a list of allowed values: Optional enum: Arrays Use (array) for list fields: Relations Reference other entity types directly: Relations create edges in the knowledge graph, linking notes together. Validation Settings Use strict as the canonical enforcing mode. error is accepted only as a compatibility alias. Complete Example Discovering Unschemaed Notes Look for clusters of notes that share structure but have no schema: 1. Search by type : bm search(note types=["meeting"], project="<project ") — if many notes share a type but no schema/Meeting.md exists, it's a candidate. 2. Infer a schema : Use bm schema(command="infer", project="<project ") to analyze existing notes and generate a suggested schema: The threshold (0.0–1.0) controls how common a field must be to be included. Default is usually fine; lower it to catch rarer fields. 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 : 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: Important: bm schema(command="validate", project="<project ") 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 (as observation categories, or relations for entity reference fields) and invalid enum values . Undeclared observation categories and relations are listed as informational "unmatched" items. Scalar values are not type checked. Handling Validation Results warn mode : Review warnings periodically. Fix notes that are clearly wrong; add optional fields to the schema for legitimate new patterns. strict mode : Use where conformance matters (e.g., automated pipelines consuming notes). Detecting Drift Over time, notes evolve and schemas lag behind. Use bm schema(command="diff", project="<project ") to find divergence: 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 Cardinality changes — a field that moved between single value and array Schema Evolution When note structure changes: 1. Run diff to see current state: bm schema(command="diff", note type="Meeting", project="<project ") 2. Update the schema note via bm edit with the metadata parameter. Top level keys are replaced whole, so pass the complete updated schema map along with the new version : 3. Re validate to confirm existing notes still pass: bm schema(command="validate", note type="Meeting", project="<project ") 4. 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 version 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

memory-schema