memory-schema

Memory Schema

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

适用场景

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

Picoschema 语法参考

Schema 使用 Picoschema 在 YAML frontmatter 中定义，这是一种描述笔记结构的精简表示法。

基本类型

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。

可选字段

在字段名称后追加 ?：

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

枚举

使用 (enum) 并附上允许值列表：

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

可选枚举：

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

数组

使用 (array) 表示列表字段：

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

关系

直接引用其他实体类型：

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

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

验证设置

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

使用 strict 作为规范的强制模式。error 仅作为兼容性别名接受。

完整示例

---
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, meeting state): [scheduled, completed, cancelled]
settings:
  validation: warn
---

发现未定义 Schema 的笔记

查找结构相同但没有 schema 的笔记群组：

1. 按类型搜索：bm_search(note_types=["meeting"]) — 如果许多笔记具有相同的 type，但不存在 schema/Meeting.md，那么它们可能适合创建 schema。

2. 推断 schema：使用 bm_schema(command="infer") 分析现有笔记并生成建议的 schema：

   bm_schema(command="infer", note_type="Meeting")
   bm_schema(command="infer", note_type="Meeting", threshold=0.5)  # fields in 50%+ of notes
   

   阈值（0.0–1.0）控制字段必须有多常见才会被纳入。通常使用默认值即可；调低阈值可纳入较少见的字段。

3. 审阅建议 — 推断出的 schema 会显示字段名称、类型和频率。决定保留哪些字段、将哪些字段设为可选，或删除哪些字段。

创建 Schema

将 schema 笔记写入 schema/<EntityName>：

bm_write(
  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"""
)

关键原则

• Schema 笔记存放在 schema/ 中 — 每种实体类型对应一条笔记
• note_type="schema" 将其标记为 schema 定义
• 元数据中的 entity: Meeting 指定适用的类型
• 元数据中的 version: 1 — 进行破坏性变更时递增版本号
• 建议从 settings.validation: warn 开始 — 它会记录问题，但不会阻止写入

验证笔记

检查现有笔记符合其 schema 的程度：

# Validate all notes of a type
bm_schema(command="validate", note_type="Meeting")

# Validate a single note
bm_schema(command="validate", identifier="meetings/2026-02-10-standup")

重要提示： bm_schema(command="validate") 会将 schema 字段作为笔记正文中的观察类别进行检查 — 例如，status 字段要求存在 - [status] active 这样的观察内容。仅存储在 frontmatter 元数据中的字段无法满足验证要求。若要顺利通过验证，请将 schema 字段同时作为 frontmatter 值（用于元数据搜索）和观察内容（用于 schema 验证）。

验证报告会列出缺失的必填字段（作为观察类别，或针对实体引用字段列出关系）和无效的枚举值。未声明的观察类别和关系会作为信息性的“未匹配”项列出。标量值不会进行类型检查。

处理验证结果

• warn 模式：定期检查警告。修正明显有误的笔记；对于合理的新模式，可在 schema 中添加可选字段。
• strict 模式：在需要符合规范的场景中使用（例如，使用笔记的自动化流水线）。

检测漂移

随着时间推移，笔记会不断演变，而 schema 可能滞后。使用 bm_schema(command="diff") 查找差异：

bm_schema(command="diff", note_type="Meeting")

Diff 报告会列出：

• 笔记中存在但 schema 未定义的字段 — 可考虑将其添加到 schema 中（设为可选）
• 很少使用的 schema 字段 — 可考虑将其设为可选或移除
• 基数变化 — 某个字段从单值变为数组，或从数组变为单值

架构演进

当笔记结构发生变化时：

1. 运行差异检查以查看当前状态：bm_schema(command="diff", note_type="Meeting")
2. 使用 metadata 参数通过 bm_edit 更新架构笔记。顶层键会被整体替换，因此请传入完整更新后的 schema 映射以及新的 version：

   bm_edit(
     identifier="schema/Meeting",
     command="set_metadata",
     metadata={
       "version": 2,
       "schema": {
         "topic": "string, what was discussed",
         "date": "string, when it happened",
         "attendees?(array)": "Person, who attended",
         "decisions?(array)": "string, decisions made",
         "location?": "string, where it happened"
       }
     }
   )
   

3. 重新验证以确认现有笔记仍然通过验证：bm_schema(command="validate", note_type="Meeting")
4. 修正不符合项——更新不符合新架构的笔记

演进指南

• 增量式更改（新增可选字段）是安全的——无需提升版本号
• 破坏性更改（新增必填字段、移除字段、更改类型）应提升 version
• 优先选择可选字段而非必填字段——大多数字段一开始都应设为可选
• 不要过度约束——架构应描述常见结构，而不是强制使用僵化模板
• 将架构作为文档——即使验证设置为 warn，架构仍可作为持续更新的文档，说明此类笔记应包含哪些内容

工作流摘要

1. Notice repeated note structure → infer schema (bm_schema(command="infer"))
2. Review + create schema note   → write to schema/ (bm_write)
3. Validate existing notes       → check conformance (bm_schema(command="validate"))
4. Fix outliers                  → edit non-conforming notes (bm_edit)
5. Periodically check drift      → detect divergence (bm_schema(command="diff"))
6. Evolve schema as needed       → update schema note (bm_edit)