Memory Notes 是 Basic Memory 技能中的笔记写作指南，目标是帮助用户写出结构良好、可被 Basic Memory 解析为可搜索知识图谱的笔记。每篇笔记都是一个 Markdown 文件，包含三个关键部分：frontmatter、observations 和 relations。
笔记结构
一篇笔记由三部分组成：YAML frontmatter、正文（Body / Context）以及 Observations 和 Relations 两个结构化区块。
Frontmatter
每篇笔记以 YAML frontmatter 开头，字段包括：
- title：必填，成为知识图谱中的实体名称，必须与正文中的 # 标题一致。
- tags：可选，用于组织和过滤，可被搜索。
- type：可选，默认为 "note"，可使用自定义类型配合 schema 系统（如 Task、Meeting、Person 等）。
- permalink：可选，省略时根据标题自动生成。
permalink 由标题和目录自动生成。例如标题 "API Design Decisions" 位于目录 "specs" 下，生成 permalink specs/api-design-decisions 和 memory URL memory://specs/api-design-decisions。未指定目录时，permalink 就是标题的 kebab-case 形式。permalink 在文件移动后保持稳定，通常无需手动设置。
注意：使用 write_note 时无需自己编写 frontmatter，title、tags、note_type 和 metadata 是独立参数，Basic Memory 会自动生成 frontmatter，content 参数只需以 # 标题开头的 Markdown 正文。
正文（Body / Context）
标题与 Observations 区块之间的自由 Markdown 内容，是笔记的核心。应在此充分书写：背景、动机与历史；发生了什么及其重要性的详细说明；分析、推理与权衡；供他人或 AI 日后理解本笔记所需的上下文。Basic Memory 的搜索会从笔记正文中检索相关片段，因此更长、更丰富的上下文会让笔记更易被发现和更有用。不要把所有内容都压缩成要点，要讲清来龙去脉。
Observations
Observations 是带分类的事实，是知识的原子单元，每条都会成为知识图谱中的可搜索实体。语法为：
- [category] Content of the observation #optional-tag
方括号定义语义分类，内容为事实、决策、洞察或备注，井号标签（可选）添加额外元数据用于过滤。分类是自由形式的，没有固定列表，唯一规则是 [category] content 语法。项目内保持一致有助于搜索，但可自由创造分类。示例包括 [decision]、[risk]、[technique]、[question]、[preference]、[lesson]、[status]、[flavor] 等。
Observation 使用建议：每条观察只放一个事实；要具体，例如 [decision] Use JWT with 15-minute expiry for API auth 比 [decision] Use JWT 更有用；用标签处理跨领域关注点；分类可被查询，search_notes("[decision]") 可找到知识库中所有决策。
Relations
Relations 在知识图谱中创建边，把笔记相互连接。语法为：
- relation_type [[Target Note Title]]
relation_type 是描述性动词或短语（约定用 snake_case），双方括号 [[...]] 通过标题或 permalink 标识目标笔记。关系是有方向的：本笔记 → 目标笔记。
文档中列出的关系类型包括：implements（实现）、requires（依赖）、relates_to（一般关联）、part_of（层级/组成）、extends（增强或细化）、pairs_with（协同工作）、inspired_by（来源材料）、replaces（取代）、depends_on（运行时/构建依赖）、contrasts_with（替代方案）。
内联关系：笔记正文中任意位置的 wiki-link 也会自动创建图谱边，并生成 references 关系。Relations 区块用于显式、带类型的关系，内联链接用于自然行文中的引用。
Relation 使用建议：大胆链接，关系是把孤立笔记变成知识图谱的关键；目标笔记不存在也可先写 [[Future Topic]]，BM 会在该笔记创建时解析；用 build_context 遍历关系；自定义关系类型也可以，如 taught_by、blocks、tested_in。
Memory URL
每篇笔记都可通过 memory:// URL 寻址，URL 由 permalink 构建，用于以编程方式导航知识图谱。URL 模式包括：按 permalink（memory://api-design-decisions）、按文件路径（memory://docs/authentication）、带扩展名（memory://docs/authentication.md）、通配符前缀（memory://auth*）、通配符后缀（memory://docs/）、路径通配符（memory://project//requirements）。多项目环境下可加项目名前缀，如 memory://main/specs/api-design。第一个路径段会与已知项目名匹配，匹配则作为项目范围，否则在默认项目中解析。
Memory URL 可与 build_context 配合，通过遍历关系汇集相关知识，例如 build_context(url="memory://api-design-decisions")、build_context(url="memory://docs/*")，也可用 read_note(identifier="memory://api-design-decisions") 直接读取。
创建笔记前的准备
创建新笔记前务必先搜索 Basic Memory。重复笔记会割裂知识图谱，更新已有笔记几乎总是优于新建第二篇。
搜索时应尝试多种变体：全名、缩写、首字母缩略词和关键词。例如搜索可能已存在的实体时，可分别用 "Kubernetes Migration"、"k8s migration"、"container migration"。对人名尝试全名和姓氏，对组织尝试全名和常见缩写。
决策树：实体已存在 → 用 edit_note 更新（追加观察、添加关系、查找替换过时信息）；实体不存在 → 用 write_note 创建；不确定是否同一实体 → 先读取已有笔记再决定。
使用工具写笔记
创建笔记
使用 write_note，传入 title、directory、tags 和 content 参数。Basic Memory 会根据参数自动生成 frontmatter（包括 permalink 和 memory URL）。
编辑已有笔记
使用 edit_note 在笔记内追加、前置或查找替换。支持 operation="append"、operation="find_replace" 等，可指定 section（如 Observations、Relations）。这样能保留已有内容，保持编辑历史干净。
移动笔记
使用 move_note 将笔记重组到不同目录，例如 move_note(identifier="API Design Decisions", destination_path="archive/api-design-decisions.md")。移动后 permalink 保持不变，所有 [[wiki-links]] 和 memory:// URL 继续可解析。
最佳实践
- 从上下文开始：列出观察之前，先解释这篇笔记为何存在。
- 追求完整：写丰富、有实质内容的笔记。搜索会从正文中提取相关片段，上下文更多的长笔记更易被发现。正文用散文讲完整故事，再把关键事实提炼为 [category] content 观察，两者都重要。
- 增量构建：向已有笔记添加内容而非创建重复笔记，用 edit_note 追加新的观察或关系。
- 审查 AI 生成内容：AI 写笔记时审查其准确性，AI 结构捕捉得好但可能遗漏细微之处。
- 标题保持一致：笔记标题是知识图谱中的标识符，API Design Decisions 和 Api Design decisions 是不同实体，选定约定并坚持。
- 链接相关概念：知识图谱的价值随连接而增长，零关系的笔记是孤岛。
- 让图谱自然生长：不要预先设计完美分类法，边工作边写笔记，连接出现时添加关系，定期用 /reflect 或 /defrag 整合。