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 的标题。默认情况下，移动文件不会改变固定链接（除非项目启用了 update_permalinks_on_move）。通常无需手动设置。

注意： bm_write 可接受准确的文件路径作为 identifier，也可接受 title + directory。content 可包含 YAML 前置元数据；也可以分别提供 title、tags、note_type 和 metadata，让 Basic Memory 自动生成。覆盖现有内容时，请使用 bm_read 返回的 file_path 作为 identifier，并将其 checksum 作为 expected_checksum 传入。

正文／上下文

标题与“观察记录”部分之间可自由编写 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 可让内容在两个主题下都能被找到。
• 类别可用于查询。 bm_search(items=["observation"], categories=["decision"]) 会返回知识库中的所有决策类观察记录。

声明何时成立

观察可以说明其成立时间。在类别后添加限定符：

- [decision] @effective:2026-06-10 The cache layer uses Redis
- [event] @occurred:2026-10-14 Launch sync moved the date to Thursday
- [deadline] @due:2026-10-20 Draft ready for review
- [stage] @valid:2026-10 Series B, about 200 employees
- [decision] @effective[2026-06-10,2026-10-14) Launch on Friday

• 类型：effective（决策或规则生效）、occurred（事件发生）、due（承诺到期）、mentioned（提及的时间）以及默认类型 valid（@2026-06-10 表示 @valid:2026-06-10）。
• 时间点覆盖其精度所指的时段：@2026 指该年，@2026-06 指该月，@2026-06-10 指从该日期起。
• 范围使用 [start,end)，任一端都可以留空：@effective[2026-06-10,)。
• 日期需写完整。未加引号的日期是一个 token（@occurred:2026-06-10）。更长的内容需加引号：@occurred:"June 10, 2026"。像 yesterday 这样的相对日期不会被视为限定符；它会保留在文本中。
• 事实发生变化时，关闭旧事实的范围并开始新事实的范围，而不是删除旧事实。两者都可以按日期搜索。

按笔记所述的事实成立时间搜索，而不是按笔记的编辑时间搜索：

bm_search(valid_at="2026-07-01")                              # true on that date
bm_search(time_kind="due", valid_overlaps="[2026-10-14,2026-10-21)")  # due this week

有效时间筛选器只返回带日期的观察；移除它即可搜索所有内容。日期时间点表示“从该日期起”，因此到期日期范围也会返回已经逾期的项目。

关系

关系会在知识图谱中创建边，将笔记彼此连接。它们能帮助你在单个笔记之外构建结构。

语法

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

行内关系

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

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 会解析它。
• 使用 bm_context 遍历。 bm_context(identifier="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

第一个路径段会与已知项目名称匹配。若匹配，则将其用作项目范围。若不匹配，且有多个项目可供访问，则需显式传入 project；否则会拒绝未限定项目的调用。

使用 Memory URL

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

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

# Wildcard — gather all docs
bm_context(identifier="memory://docs/*")

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

创建笔记前

创建新笔记前，务必先搜索 Basic Memory。重复内容会使知识图谱碎片化——更新现有笔记几乎总比创建第二篇更好。

使用多种变体进行搜索

单次搜索往往会遗漏结果。尝试完整名称、缩写、首字母缩略词和关键词：

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

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

决策树

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

使用 bm_edit 进行细粒度更新

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

# Add a new observation under the existing Observations heading
bm_edit(
  identifier="API Design Decisions",
  command="insert_after_section",
  section="Observations",
  content="- [decision] Switched to OpenAPI 3.1 for spec generation #api"
)

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

# Add a new relation
bm_edit(
  identifier="API Design Decisions",
  command="insert_after_section",
  section="Relations",
  content="- depends_on [[Rate Limiter]]"
)

这样可以保留现有内容，并保持清晰的编辑历史。

使用工具撰写笔记

创建笔记

bm_write(
  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 访问。

编辑现有笔记

使用 bm_edit 原地更新笔记——支持七种命令：append、prepend、 find_replace、replace_section、insert_before_section、insert_after_section， 以及 set_metadata（合并 frontmatter，不更改正文）。

# insert_after_section / insert_before_section — add lines at an existing heading
bm_edit(
  identifier="API Design Decisions",
  command="insert_after_section",
  section="Observations",
  content="- [decision] Use OpenAPI 3.1 for spec generation #api"
)

# append / prepend — add to the end of the note or the start of the body
# (use for time-ordered logs; neither one targets a section)
bm_edit(
  identifier="API Design Decisions",
  command="prepend",
  content="> Updated 2026-05-28: auth approach finalized.\n"
)

# replace_section — rewrite a named section (use for living content that stays current)
bm_edit(
  identifier="API Design Decisions",
  command="replace_section",
  section="Summary",
  content="Concise, current summary of the decision and its rationale."
)

# find_replace — swap specific text
bm_edit(
  identifier="API Design Decisions",
  command="find_replace",
  find_text="OpenAPI 3.0",
  content="OpenAPI 3.1"
)

如果编辑具有破坏性（replace_section、find_replace），请先读取笔记并传入其校验和，这样编辑只会应用于你读取的版本：

note = bm_read(identifier="API Design Decisions", output_format="json")
bm_edit(
  identifier="API Design Decisions",
  command="replace_section",
  section="Summary",
  content="Concise, current summary of the decision and its rationale.",
  expected_checksum=note["checksum"]
)

校验和冲突意味着你读取笔记后，有人修改了它。请重新读取笔记，并基于新文本重新进行编辑。bm_write(overwrite=True) 也以同样方式接受 expected_checksum。

移动笔记

使用 bm_move 将笔记整理到其他目录：

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

默认情况下，移动后永久链接保持不变，因此链接仍可正常解析。启用了 update_permalinks_on_move 的项目会根据新路径重写永久链接。

最佳实践

1. 从背景信息入手。 列出观察内容前，先解释这篇笔记为何存在。未来的你（或你的 AI 协作者）会感谢你。

2. 尽量完整。 撰写内容充实、信息丰富的笔记。Basic Memory 会从笔记正文中提取相关片段进行搜索，因此，包含更多上下文的长笔记更容易被发现，而不是更难找到。用正文讲述完整故事——背景、理由和细节。然后将关键事实提炼为 [category] content 格式的观察，以便进行结构化查询。两者都很重要：正文赋予内容意义，观察则提供精确性。

3. 循序渐进地构建。 在现有笔记中补充内容，而不是创建重复笔记。随着了解增多，使用 bm_edit 追加新的观察或关系。

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

5. 关联相关概念。 知识图谱的价值会随着连接的增加而不断累积。没有任何关系的笔记就像一座孤岛——有用，但不如有连接的笔记强大。

6. 让图谱自然生长。 不要试图一开始就设计完美的分类体系。工作时撰写笔记，随着关联浮现再添加关系，并定期使用 memory-reflect 或 memory-defrag 技能进行整合。