{"id":6480,"plugin_id":"plugin_asdk_app_6a49590bf6348191a16c0b87ca6b01b4","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T22:48:24.840Z","digest":"eb09b9e2c4d01c7aed8a946bd9f63d811f00e1e54372c6af9208b09515c25479","against":null,"payload":{"name":"memory-schema","description":"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.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":393}],"skill_md_contents":"---\nname: memory-schema\ndescription: \"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.\"\n---\n\n# Memory Schema\n\nManage structured note types using Basic Memory's Picoschema system. Schemas define what fields a note type should have, making notes uniform, queryable, and validatable.\n\n## When to Use\n\n- **New note type emerging** — you notice several notes share the same structure (meetings, people, decisions)\n- **Validation check** — confirm existing notes conform to their schema\n- **Schema drift** — detect fields that notes use but the schema doesn't define (or vice versa)\n- **Schema evolution** — add/remove/change fields as requirements evolve\n- **On demand** — user asks to create, check, or manage schemas\n\n## Picoschema Syntax Reference\n\nSchemas are defined in YAML frontmatter using Picoschema — a compact notation for describing note structure.\n\n### Basic Types\n\n```yaml\nschema:\n  name: string, person's full name\n  age: integer, age in years\n  score: number, floating-point rating\n  active: boolean, whether currently active\n```\n\nSupported types: `string`, `integer`, `number`, `boolean`.\n\n### Optional Fields\n\nAppend `?` to the field name:\n\n```yaml\nschema:\n  title: string, required field\n  subtitle?: string, optional field\n```\n\n### Enums\n\nUse `(enum)` with a list of allowed values:\n\n```yaml\nschema:\n  status(enum, current state): [active, blocked, done, abandoned]\n```\n\nOptional enum:\n\n```yaml\nschema:\n  priority?(enum, task priority): [low, medium, high, critical]\n```\n\n### Arrays\n\nUse `(array)` for list fields:\n\n```yaml\nschema:\n  tags(array): string, categorization labels\n  steps?(array): string, ordered steps to complete\n```\n\n### Relations\n\nReference other entity types directly:\n\n```yaml\nschema:\n  parent_task?: Task, parent task if this is a subtask\n  attendees?(array): Person, people who attended\n```\n\nRelations create edges in the knowledge graph, linking notes together.\n\n### Validation Settings\n\n```yaml\nsettings:\n  validation: warn    # warn (log issues) or error (strict)\n```\n\n### Complete Example\n\n```yaml\n---\ntitle: Meeting\ntype: schema\nentity: Meeting\nversion: 1\nschema:\n  topic: string, what was discussed\n  date: string, when it happened (YYYY-MM-DD)\n  attendees?(array): Person, who attended\n  decisions?(array): string, decisions made\n  action_items?(array): string, follow-up tasks\n  status?(enum, meeting state): [scheduled, completed, cancelled]\nsettings:\n  validation: warn\n---\n```\n\n## Discovering Unschemaed Notes\n\nLook for clusters of notes that share structure but have no schema:\n\n1. **Search by type**: `search_notes(query=\"type:Meeting\")` — if many notes share a `type` but no `schema/Meeting.md` exists, it's a candidate.\n\n2. **Infer a schema**: Use `schema_infer` to analyze existing notes and generate a suggested schema:\n   ```python\n   schema_infer(noteType=\"Meeting\")\n   schema_infer(noteType=\"Meeting\", threshold=0.5)  # fields in 50%+ of notes\n   ```\n   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.\n\n3. **Review the suggestion** — the inferred schema shows field names, types, and frequency. Decide which fields to keep, make optional, or drop.\n\n## Creating a Schema\n\nWrite the schema note to `schema/<EntityName>`:\n\n```python\nwrite_note(\n  title=\"Meeting\",\n  directory=\"schema\",\n  note_type=\"schema\",\n  metadata={\n    \"entity\": \"Meeting\",\n    \"version\": 1,\n    \"schema\": {\n      \"topic\": \"string, what was discussed\",\n      \"date\": \"string, when it happened\",\n      \"attendees?(array)\": \"Person, who attended\",\n      \"decisions?(array)\": \"string, decisions made\"\n    },\n    \"settings\": {\"validation\": \"warn\"}\n  },\n  content=\"\"\"# Meeting\n\nSchema for meeting notes.\n\n## Observations\n- [convention] Meeting notes live in memory/meetings/ or as daily entries\n- [convention] Always include date and topic\n- [convention] Action items should become tasks when complex\"\"\"\n)\n```\n\n### Key Principles\n\n- **Schema notes live in `schema/`** — one note per entity type\n- **`note_type=\"schema\"`** marks it as a schema definition\n- **`entity: Meeting`** in metadata names the type it applies to\n- **`version: 1`** in metadata — increment when making breaking changes\n- **`settings.validation: warn`** is recommended to start — it logs issues without blocking writes\n\n## Validating Notes\n\nCheck how well existing notes conform to their schema:\n\n```python\n# Validate all notes of a type\nschema_validate(noteType=\"Meeting\")\n\n# Validate a single note\nschema_validate(identifier=\"meetings/2026-02-10-standup\")\n```\n\n**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).\n\nValidation reports:\n- **Missing required fields** — the note lacks a field the schema requires (as an observation category)\n- **Unknown fields** — the note has fields the schema doesn't define\n- **Type mismatches** — a field value doesn't match the expected type\n- **Invalid enum values** — a value isn't in the allowed set\n\n### Handling Validation Results\n\n- **`warn` mode**: Review warnings periodically. Fix notes that are clearly wrong; add optional fields to the schema for legitimate new patterns.\n- **`error` mode**: Use for strict schemas where conformance matters (e.g., automated pipelines consuming notes).\n\n## Detecting Drift\n\nOver time, notes evolve and schemas lag behind. Use `schema_diff` to find divergence:\n\n```python\nschema_diff(noteType=\"Meeting\")\n```\n\nDiff reports:\n- **Fields in notes but not in schema** — candidates for adding to the schema (as optional)\n- **Schema fields rarely used** — consider making optional or removing\n- **Type inconsistencies** — fields used as different types across notes\n\n## Schema Evolution\n\nWhen note structure changes:\n\n1. **Run diff** to see current state: `schema_diff(noteType=\"Meeting\")`\n2. **Update the schema note** via `edit_note`:\n   ```python\n   edit_note(\n     identifier=\"schema/Meeting\",\n     operation=\"find_replace\",\n     find_text=\"version: 1\",\n     content=\"version: 2\",\n     expected_replacements=1\n   )\n   ```\n3. **Add/remove/modify fields** in the `schema:` block\n4. **Re-validate** to confirm existing notes still pass: `schema_validate(noteType=\"Meeting\")`\n5. **Fix outliers** — update notes that don't conform to the new schema\n\n### Evolution Guidelines\n\n- **Additive changes** (new optional fields) are safe — no version bump needed\n- **Breaking changes** (new required fields, removed fields, type changes) should bump `version`\n- **Prefer optional over required** — most fields should be optional to start\n- **Don't over-constrain** — schemas should describe common structure, not enforce rigid templates\n- **Schema as documentation** — even if validation is set to `warn`, the schema serves as living documentation for what notes of that type should contain\n\n## Workflow Summary\n\n```\n1. Notice repeated note structure → infer schema (schema_infer)\n2. Review + create schema note   → write to schema/ (write_note)\n3. Validate existing notes       → check conformance (schema_validate)\n4. Fix outliers                  → edit non-conforming notes (edit_note)\n5. Periodically check drift      → detect divergence (schema_diff)\n6. Evolve schema as needed       → update schema note (edit_note)\n```\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}