memory-notes

记忆笔记

编写结构良好的笔记，让 Basic Memory 能够将其解析为可搜索的知识图谱。每篇笔记都是一个 Markdown 文件，包含三个关键部分：前置元数据、观察和关系。

笔记结构

---
title: API Design Decisions
tags: [api, architecture, decisions]
---

# API Design Decisions

The API team evaluated multiple approaches for the public API during Q1. After
prototyping both REST and GraphQL, the team chose REST due to broader ecosystem
support and simpler caching semantics. This note captures the key decisions and
their rationale, along with open questions still to resolve.

## Observations
- [decision] Use REST over GraphQL for simplicity #api
- [requirement] Must support versioning from day one
- [risk] Rate limiting needed for public endpoints

## Relations
- implements [[API Specification]]
- depends_on [[Authentication System]]
- relates_to [[Performance Requirements]]

前置元数据

每篇笔记都以 YAML 前置元数据开头：

---
title: Note Title          # required — becomes the entity name in the knowledge graph
tags: [tag1, tag2]         # optional — for organization and filtering
type: note                 # optional — defaults to "note", use custom types with schemas
permalink: custom-path     # optional — auto-generated from title if omitted
---

• title 必须与正文中的 # Heading 一致
• 标签可供搜索，有助于发现笔记
• 自定义 type 值（Task、Meeting、Person 等）适用于架构系统。请参阅 memory-schema 技能，了解如何定义架构、根据架构验证笔记以及检测偏差。
• permalink 根据 title 和 directory 自动生成。例如，目录为 "specs" 的标题 "API Design Decisions" 会生成永久链接 specs/api-design-decisions 和记忆 URL memory://specs/api-design-decisions。如果未指定目录，永久链接就是转换为 kebab-case 的标题。移动文件后，永久链接仍保持不变。通常无需手动设置。

注意： 使用 write_note 时，无需自行编写前置元数据。title、tags、note_type 和 metadata 是独立参数，Basic Memory 会自动生成前置元数据。content 参数只需填写以 # Heading 开头的 Markdown 正文。

正文 / 上下文

标题与“观察”部分之间的自由格式 Markdown 内容。这是笔记的核心，可在此充分展开：

• 背景、动机和历史
• 对所发生事件及其重要性的详细说明
• 分析、推理和权衡考量
• 有助于他人（或 AI）日后理解这篇笔记的上下文

请撰写完整、充实的内容。Basic Memory 会从笔记正文中检索相关片段，因此上下文越丰富、内容越充实，笔记就越容易被发现，也越能在找到时发挥作用。不要把所有内容都缩减成项目符号，要讲清来龙去脉。

观察

观察是经过分类的事实，是构成知识的基本单元。每条观察都会成为知识图谱中可搜索的实体。

语法

- [category] Content of the observation #optional-tag

• 方括号用于定义语义类别
• 内容是事实、决定、见解或笔记
• 井号标签（可选）用于添加额外元数据，以便筛选

类别不受限制

方括号中的类别为自由格式，可根据观察内容使用合适的标签。没有固定列表，唯一的规则是遵循 [category] content 语法。在项目内部保持一致有助于搜索，但也可以自由创建类别。

以下示例展示了类别的多样性：

- [decision] Use PostgreSQL for primary data store
- [risk] Third-party API has no SLA guarantee
- [technique] Exponential backoff for retry logic #resilience
- [question] Should we support multi-tenancy at the DB level?
- [preference] Use Bun over Node for new projects
- [lesson] Always validate webhook signatures server-side
- [status] active
- [flavor] Ethiopian beans work best with lighter roasts

观察提示

• 每条观察只写一个事实。 不要在一行中塞入多个想法。
• 具体明确。 [decision] Use JWT 不如 [decision] Use JWT with 15-minute expiry for API auth 有用。
• 使用标签标注跨领域关注点。 [risk] Rate limiting needed #api #security 可让这条观察同时通过两个主题找到。
• 类别可用于查询。 search_notes("[decision]") 可查找知识库中的所有决定。

关系

关系在知识图谱中创建边，将笔记彼此关联。通过关系，可以在单篇笔记之外构建结构。

语法

- relation_type [[Target Note Title]]

• relation_type 是描述性动词或短语（通常使用 snake_case）
• 双层方括号 [[...]] 用于通过标题或永久链接标识目标笔记
• 关系具有方向性：当前笔记 → 目标笔记

关系类型

类型	用途	示例
implements	一个事物实现另一个事物	- implements [[Auth Spec]]
requires	依赖项	- requires [[Database Setup]]
relates_to	一般关联	- relates_to [[Performance Notes]]
part_of	层级关系／组成关系	- part_of [[Backend Architecture]]
extends	增强或阐述	- extends [[Base Config]]
pairs_with	协同工作的事物	- pairs_with [[Frontend Client]]
inspired_by	来源材料	- inspired_by [[CRDT Research Paper]]
replaces	取代另一条笔记	- replaces [[Old Auth Design]]
depends_on	运行时／构建依赖项	- depends_on [[MCP SDK]]
contrasts_with	替代方案	- contrasts_with [[GraphQL Approach]]

行内关系

笔记正文中的任意位置（不仅限于 Relations 部分）出现的 Wiki 链接也会创建图边：

We evaluated [[GraphQL Approach]] but decided against it because
the team has more experience with REST. See [[API Specification]]
for the full contract.

这些链接会自动创建 references 关系。使用 Relations 部分添加明确且带类型的关系；使用行内链接在自然行文中引用。

关系提示

• 尽管链接。 关系能将孤立的笔记转变为知识图谱。拿不准时，就添加链接。
• 如果目标笔记尚不存在，就创建它。 [[Future Topic]] 是有效的——创建该笔记后，BM 会解析它。
• 使用 build_context 进行遍历。 build_context(url="memory://note-title") 会沿关系遍历，收集相关知识。
• 自定义关系类型也没问题。 taught_by、blocks、tested_in——使用任何描述性关系类型即可。

Memory URL

每条笔记都可以通过 memory:// URL 访问，该 URL 根据笔记的永久链接生成。这些 URL 可用于以编程方式浏览知识图谱。

URL 模式

memory://api-design-decisions          # by permalink (title → kebab-case)
memory://docs/authentication           # by file path
memory://docs/authentication.md        # with extension (also works)
memory://auth*                         # wildcard prefix
memory://docs/*                        # wildcard suffix
memory://project/*/requirements        # path wildcards

项目范围的 URL

在多项目设置中，在前面加上项目名称：

memory://main/specs/api-design         # "main" project, "specs/api-design" path
memory://research/papers/crdt          # "research" project

第一个路径段会与已知项目名称进行匹配。如果匹配成功，该名称就会用作项目范围；否则，URL 会在默认项目中解析。

使用 Memory URL

Memory URL 可与 build_context 配合使用，通过遍历关系来汇集相关知识：

# Get a note and its connected context
build_context(url="memory://api-design-decisions")

# Wildcard — gather all docs
build_context(url="memory://docs/*")

# Direct read by permalink
read_note(identifier="memory://api-design-decisions")

创建笔记前

创建新笔记前，请务必先搜索 Basic Memory。重复笔记会使知识图谱变得支离破碎——更新现有笔记几乎总是比创建第二条更好。

使用多种变体搜索

单次搜索常常会漏掉结果。请尝试全名、缩写、首字母缩略词和关键词：

# Searching for an entity that might already exist
search_notes(query="Kubernetes Migration")
search_notes(query="k8s migration")
search_notes(query="container migration")

搜索人物时，尝试全名和姓氏。搜索组织时，尝试全名和常见缩写。

决策树

• 实体已存在 → 使用 edit_note 更新它（追加观察、添加关系、查找并替换过时信息）
• 实体不存在 → 使用 write_note 创建它
• 不确定是否为同一实体 → 先阅读现有笔记，再做决定

使用 edit_note 进行细粒度更新

如果笔记已存在，请进行有针对性的编辑，而不是重写整个文件：

# Append a new observation to an existing note
edit_note(
  identifier="API Design Decisions",
  operation="append",
  section="Observations",
  content="- [decision] Switched to OpenAPI 3.1 for spec generation #api"
)

# Fix outdated information
edit_note(
  identifier="API Design Decisions",
  operation="find_replace",
  find_text="- [status] draft",
  content="- [status] approved"
)

# Add a new relation
edit_note(
  identifier="API Design Decisions",
  operation="append",
  section="Relations",
  content="- depends_on [[Rate Limiter]]"
)

这样可以保留现有内容，并保持编辑历史整洁。

使用工具撰写笔记

创建笔记

write_note(
  title="API Design Decisions",
  directory="architecture",
  tags=["api", "architecture"],
  content="""# API Design Decisions

The API team evaluated REST and GraphQL during Q1 planning. After prototyping
both approaches, we chose REST for the public API — broader ecosystem support,
simpler caching with HTTP semantics, and a lower learning curve for external
consumers. GraphQL remains an option for internal services where query
flexibility matters more.

## Observations
- [decision] Use REST for public API #api
- [requirement] Support API versioning from v1

## Relations
- implements [[API Specification]]
- relates_to [[Backend Architecture]]"""
)

Basic Memory 会根据参数自动生成 frontmatter（包括永久链接和 memory URL）。此笔记的永久链接将为 architecture/api-design-decisions，可通过 memory://architecture/api-design-decisions 访问。

编辑现有笔记

使用 edit_note 在笔记中追加、前置内容，或查找并替换：

# Append new observations
edit_note(
  identifier="API Design Decisions",
  operation="append",
  section="Observations",
  content="- [decision] Use OpenAPI 3.1 for spec generation #api"
)

# Add a new relation
edit_note(
  identifier="API Design Decisions",
  operation="append",
  section="Relations",
  content="- depends_on [[Rate Limiter]]"
)

移动笔记

使用 move_note 将笔记整理到不同目录中：

move_note(
  identifier="API Design Decisions",
  destination_path="archive/api-design-decisions.md"
)

移动后永久链接保持不变，因此所有 [[wiki-links]] 和 memory:// URL 仍可正常解析。

最佳实践

1. 从背景说起。 列出观察结果之前，先说明写下这条笔记的原因。未来的你（或你的 AI 合作者）会感谢你。

2. 尽量完整。 撰写丰富、翔实的笔记。Basic Memory 的搜索会从笔记正文中提取相关片段，因此，内容更长、背景更充分的笔记更容易被发现，而不是更难。用正文讲清楚完整的来龙去脉——背景、推理过程和细微之处。然后将关键信息提炼为 [category] content 观察项，以便进行结构化查询。两者都很重要：正文赋予信息意义，观察项则带来精确性。

3. 逐步完善。 在现有笔记中补充内容，而不是创建重复笔记。随着了解不断加深，使用 edit_note 添加新的观察项或关系。

4. 审查 AI 生成的内容。 AI 为你撰写笔记时，要检查其准确性。AI 很擅长捕捉结构，但可能会忽略细微之处。

5. 统一标题格式。 笔记标题是知识图谱中的标识符。API Design Decisions 和 Api Design decisions 是不同的实体。选择一种格式并始终遵循。

6. 关联相关概念。 知识图谱的价值会随着关联的增加而不断提升。没有任何关系的笔记就像一座孤岛——有用，但远不如建立了关联的笔记强大。

7. 让图谱自然生长。 不要一开始就试图设计出完美的分类体系。工作时撰写笔记，在关联逐渐显现时添加关系，并定期使用 /reflect 或 /defrag 进行整合。