memory-schema

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

使用Basic Memory的Picoschema系统管理结构化笔记类型。Schema定义了某类笔记应包含的字段，使笔记保持统一、可查询且可验证。

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

新笔记类型出现——你注意到多个笔记具有相同的结构（如会议、人物、决策）
验证检查——确认现有笔记符合其Schema定义
Schema漂移——检测笔记中使用但Schema未定义的字段（反之亦然）
Schema演进——随着需求变化添加/删除/修改字段
按需使用——用户要求创建、检查或管理Schema

Picoschema Syntax Reference

Picoschema语法参考

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

Schema通过YAML前置元数据使用Picoschema定义——这是一种用于描述笔记结构的简洁标记法。

Basic Types

基础类型

yaml

schema:
  name: string, person's full name
  age: integer, age in years
  score: number, floating-point rating
  active: boolean, whether currently active

Supported types:

string

integer

number

boolean

yaml

schema:
  name: string, person's full name
  age: integer, age in years
  score: number, floating-point rating
  active: boolean, whether currently active

支持的类型：

string

、

integer

、

number

、

boolean

。

Optional Fields

可选字段

Append

to the field name:

yaml

schema:
  title: string, required field
  subtitle?: string, optional field

在字段名后追加

：

yaml

schema:
  title: string, required field
  subtitle?: string, optional field

Enums

枚举类型

Use

(enum)

with a list of allowed values:

yaml

schema:
  status(enum): [active, blocked, done, abandoned], current state

Optional enum:

yaml

schema:
  priority?(enum): [low, medium, high, critical], task priority

使用

(enum)

搭配允许的值列表：

yaml

schema:
  status(enum): [active, blocked, done, abandoned], current state

可选枚举：

yaml

schema:
  priority?(enum): [low, medium, high, critical], task priority

Arrays

数组类型

Use

(array)

for list fields:

yaml

schema:
  tags(array): string, categorization labels
  steps?(array): string, ordered steps to complete

对列表字段使用

(array)

：

yaml

schema:
  tags(array): string, categorization labels
  steps?(array): string, ordered steps to complete

Relations

关联关系

Reference other entity types directly:

yaml

schema:
  parent_task?: Task, parent task if this is a subtask
  attendees?(array): Person, people who attended

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

直接引用其他实体类型：

yaml

schema:
  parent_task?: Task, parent task if this is a subtask
  attendees?(array): Person, people who attended

关联关系会在知识图谱中创建边，将笔记相互链接。

Validation Settings

验证设置

yaml

settings:
  validation: warn    # warn (log issues) or error (strict)

yaml

settings:
  validation: warn    # warn（记录问题）或error（严格模式）

Complete Example

完整示例

yaml

---
title: Meeting
type: schema
entity: Meeting
version: 1
schema:
  topic: string, what was discussed
  date: string, when it happened (YYYY-MM-DD)
  attendees?(array): Person, who attended
  decisions?(array): string, decisions made
  action_items?(array): string, follow-up tasks
  status?(enum): [scheduled, completed, cancelled], meeting state
settings:
  validation: warn
---

yaml

---
title: Meeting
type: schema
entity: Meeting
version: 1
schema:
  topic: string, what was discussed
  date: string, when it happened (YYYY-MM-DD)
  attendees?(array): Person, who attended
  decisions?(array): string, decisions made
  action_items?(array): string, follow-up tasks
  status?(enum): [scheduled, completed, cancelled], meeting state
settings:
  validation: warn
---

Discovering Unschemaed Notes

发现无Schema的笔记

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

Search by type:
```
search_notes(query="type:Meeting")
```
— if many notes share a
```
type
```
but no
```
schema/Meeting.md
```
exists, it's a candidate.
Infer a schema: Use
```
schema_infer
```
to analyze existing notes and generate a suggested schema:
python
```
schema_infer(noteType="Meeting")
schema_infer(noteType="Meeting", threshold=0.5)  # fields in 50%+ of notes
```
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.
Review the suggestion — the inferred schema shows field names, types, and frequency. Decide which fields to keep, make optional, or drop.

寻找具有相同结构但未定义Schema的笔记集群：

按类型搜索：
```
search_notes(query="type:Meeting")
```
——如果许多笔记共享同一个
```
type
```
但不存在
```
schema/Meeting.md
```
，则可作为候选对象。
推断Schema：使用
```
schema_infer
```
分析现有笔记并生成建议的Schema：
python
```
schema_infer(noteType="Meeting")
schema_infer(noteType="Meeting", threshold=0.5)  # 包含在50%以上笔记中的字段
```
阈值（0.0–1.0）控制字段需要达到的普及度才能被纳入。默认值通常已足够；降低阈值可捕获更罕见的字段。
审核建议——推断出的Schema会显示字段名称、类型和出现频率。决定保留哪些字段、设为可选或删除。

Creating a Schema

创建Schema

Write the schema note to

schema/<EntityName>

python

write_note(
  title="Meeting",
  directory="schema",
  note_type="schema",
  metadata={
    "entity": "Meeting",
    "version": 1,
    "schema": {
      "topic": "string, what was discussed",
      "date": "string, when it happened",
      "attendees?(array)": "Person, who attended",
      "decisions?(array)": "string, decisions made"
    },
    "settings": {"validation": "warn"}
  },
  content="""# Meeting

Schema for meeting notes.

将Schema笔记写入

schema/<EntityName>

：

python

write_note(
  title="Meeting",
  directory="schema",
  note_type="schema",
  metadata={
    "entity": "Meeting",
    "version": 1,
    "schema": {
      "topic": "string, what was discussed",
      "date": "string, when it happened",
      "attendees?(array)": "Person, who attended",
      "decisions?(array)": "string, decisions made"
    },
    "settings": {"validation": "warn"}
  },
  content="""# Meeting

Schema for meeting notes.

Observations

[convention] Meeting notes live in memory/meetings/ or as daily entries
[convention] Always include date and topic
[convention] Action items should become tasks when complex""" )

undefined

[convention] Meeting notes live in memory/meetings/ or as daily entries
[convention] Always include date and topic
[convention] Action items should become tasks when complex""" )

undefined

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

Schema笔记存储在
schema/
目录下——每种实体类型对应一个笔记
**
```
note_type="schema"
```
**标记其为Schema定义
**元数据中的
```
entity: Meeting
```
**指定其适用的实体类型
元数据中的
version: 1
——进行破坏性变更时递增版本号
推荐初始设置
settings.validation: warn
——仅记录问题而不阻止写入

Validating Notes

验证笔记

Check how well existing notes conform to their schema:

python

undefined

检查现有笔记是否符合其Schema定义：

python

undefined

Validate all notes of a type

验证某一类型的所有笔记

schema_validate(noteType="Meeting")

Validate a single note

验证单条笔记

schema_validate(identifier="meetings/2026-02-10-standup")


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

schema_validate(identifier="meetings/2026-02-10-standup")


**重要提示**：`schema_validate`会检查笔记正文中的**观察类别**是否符合Schema字段——例如，`status`字段要求笔记中包含`- [status] active`这样的观察项。仅存储在前置元数据中的字段无法通过验证。要完全通过验证，需同时在前置元数据（用于元数据搜索）和观察项（用于Schema验证）中包含Schema字段。

验证报告包含：
- **缺失必填字段**——笔记缺少Schema要求的字段（作为观察类别）
- **未知字段**——笔记包含Schema未定义的字段
- **类型不匹配**——字段值与预期类型不符
- **无效枚举值**——值不在允许的集合中

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

warn
模式：定期查看警告。修复明显错误的笔记；为合理的新模式向Schema添加可选字段。
error
模式：用于严格要求一致性的Schema（例如，供自动化流水线使用的笔记）。

Detecting Drift

检测漂移

Over time, notes evolve and schemas lag behind. Use

schema_diff

to find divergence:

python

schema_diff(noteType="Meeting")

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可能滞后。使用

schema_diff

发现差异：

python

schema_diff(noteType="Meeting")

差异报告包含：

笔记中存在但Schema未定义的字段——可作为候选添加到Schema（设为可选）
极少使用的Schema字段——考虑设为可选或删除
类型不一致——不同笔记中同一字段的类型不同

Schema Evolution

Schema演进

When note structure changes:

Run diff to see current state:
```
schema_diff(noteType="Meeting")
```

Update the schema note via

edit_note

python

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

Add/remove/modify fields in the
```
schema:
```
block
Re-validate to confirm existing notes still pass:
```
schema_validate(noteType="Meeting")
```
Fix outliers — update notes that don't conform to the new schema

当笔记结构发生变化时：

运行差异检测查看当前状态：
```
schema_diff(noteType="Meeting")
```

更新Schema笔记通过

edit_note

：

python

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

在
schema:
块中添加/删除/修改字段
重新验证确认现有笔记仍符合要求：
```
schema_validate(noteType="Meeting")
```
修复异常项——更新不符合新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

增量变更（新增可选字段）是安全的——无需升级版本
破坏性变更（新增必填字段、删除字段、类型变更）应升级
```
version
```
优先设为可选而非必填——大多数字段初始应设为可选
不要过度约束——Schema应描述通用结构，而非强制执行严格模板
Schema即文档——即使验证设置为
```
warn
```
，Schema也可作为该类型笔记应包含内容的活文档

Workflow Summary

工作流总结

1. Notice repeated note structure → infer schema (schema_infer)
2. Review + create schema note   → write to schema/ (write_note)
3. Validate existing notes       → check conformance (schema_validate)
4. Fix outliers                  → edit non-conforming notes (edit_note)
5. Periodically check drift      → detect divergence (schema_diff)
6. Evolve schema as needed       → update schema note (edit_note)

1. 发现重复的笔记结构 → 推断Schema（schema_infer）
2. 审核并创建Schema笔记 → 写入schema/目录（write_note）
3. 验证现有笔记 → 检查一致性（schema_validate）
4. 修复异常项 → 编辑不符合要求的笔记（edit_note）
5. 定期检查漂移 → 检测差异（schema_diff）
6. 根据需要演进Schema → 更新Schema笔记（edit_note）