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): [active, blocked, done, abandoned], current state

可选枚举：

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

数组

使用 (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 error (strict)

完整示例

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

发现没有 Schema 的笔记

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

1. 按类型搜索：search_notes(query="type:Meeting") — 如果许多笔记共用同一个 type，但不存在 schema/Meeting.md，那么这类笔记就值得考虑创建 schema。

2. 推断 Schema：使用 schema_infer 分析现有笔记并生成建议的 schema：

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

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

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

创建 Schema

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

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

主要原则

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

验证笔记

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

# Validate all notes of a type
schema_validate(noteType="Meeting")

# Validate a single note
schema_validate(identifier="meetings/2026-02-10-standup")

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

验证报告：

• 缺少必填字段 — 笔记缺少 schema 要求的字段（作为观察类别）
• 未知字段 — 笔记包含 schema 未定义的字段
• 类型不匹配 — 字段值与预期类型不匹配
• 无效枚举值 — 值不在允许的集合中

处理验证结果

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

检测漂移

随着时间推移，笔记会不断演变，而 schema 可能会跟不上。使用 schema_diff 查找差异：

schema_diff(noteType="Meeting")

差异报告：

• 笔记中存在但 schema 中没有的字段 — 可考虑将其添加到 schema 中（设为可选）
• 很少使用的 schema 字段 — 可考虑将其设为可选或删除
• 类型不一致 — 同一字段在不同笔记中使用了不同类型

Schema 演进

当笔记结构发生变化时：

1. 运行 diff 查看当前状态：schema_diff(noteType="Meeting")
2. 通过 edit_note 更新 schema 笔记：

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

3. 在 schema: 块中添加/删除/修改字段
4. 重新验证以确认现有笔记仍然通过：schema_validate(noteType="Meeting")
5. 修复异常项 — 更新不符合新 schema 的笔记

演进准则

• 增量变更（新增可选字段）是安全的 — 无需提升版本号
• 破坏性变更（新增必填字段、删除字段、类型变更）应提升 version
• 优先选择可选而非必填 — 大多数字段在初始阶段都应为可选
• 不要过度约束 — schema 应描述常见结构，而非强制套用僵化的模板
• 将 schema 作为文档 — 即使验证设置为 warn，schema 也可作为该类型笔记应包含内容的动态文档

工作流摘要

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)