memory-notes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Memory Notes

Basic Memory笔记

Write well-structured notes that Basic Memory can parse into a searchable knowledge graph. Every note is a markdown file with three key sections: frontmatter, observations, and relations.

撰写结构清晰的笔记，让Basic Memory可以将其解析为可搜索的知识图谱。每篇笔记都是一个Markdown文件，包含三个核心部分：frontmatter（前置元数据）、观察内容（Observations）和关联关系（Relations）。

Note Anatomy

笔记结构解析

markdown

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

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

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

undefined

implements [[API Specification]]
depends_on [[Authentication System]]
relates_to [[Performance Requirements]]

undefined

Frontmatter

前置元数据（Frontmatter）

Every note starts with YAML frontmatter:

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

The
```
title
```
must match the
```
# Heading
```
in the body
Tags are searchable and help with discovery
Custom
```
type
```
values (Task, Meeting, Person, etc.) work with the schema system. See the memory-schema skill for defining schemas, validating notes against them, and detecting drift.
The
```
permalink
```
is auto-generated from the
```
title
```
and
```
directory
```
. For example, title "API Design Decisions" in directory "specs" produces permalink
```
specs/api-design-decisions
```
and memory URL
```
memory://specs/api-design-decisions
```
. If no directory is specified, the permalink is just the kebab-cased title. Permalinks stay stable across file moves. You rarely need to set one manually.

Note: When using
write_note
, you don't write frontmatter yourself. The
title
,
tags
,
note_type
, and
metadata
are separate parameters — Basic Memory generates the frontmatter automatically. Your
content
parameter is just the markdown body starting with
# Heading
.

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

yaml

---
title: Note Title          # 必填 — 作为知识图谱中的实体名称
tags: [tag1, tag2]         # 可选 — 用于分类和筛选
type: note                 # 可选 — 默认值为"note"，可结合自定义类型与模式使用
permalink: custom-path     # 可选 — 若省略则自动从标题生成
---

```
title
```
必须与正文中的
```
# 标题
```
保持一致
标签可被搜索，便于内容发现
自定义
```
type
```
值（如Task、Meeting、Person等）可与模式系统配合使用。请查看memory-schema技能了解如何定义模式、验证笔记以及检测内容偏差。
```
permalink
```
由
```
title
```
和
```
directory
```
自动生成。例如，标题为"API Design Decisions"且位于目录"specs"中的笔记，其permalink为
```
specs/api-design-decisions
```
，对应的memory URL为
```
memory://specs/api-design-decisions
```
。若未指定目录，permalink仅为标题的短横线分隔形式。笔记移动后permalink保持不变，因此您几乎不需要手动设置。

注意： 使用
write_note
时无需手动编写frontmatter。
title
、
tags
、
note_type
和
metadata
为独立参数，Basic Memory会自动生成对应的frontmatter。您只需提供从
# 标题
开始的Markdown正文作为
content
参数即可。

Body / Context

正文/上下文

Free-form markdown between the heading and the Observations section. This is the heart of the note — write generously here:

Background, motivation, and history
Detailed explanation of what happened and why it matters
Analysis, reasoning, and trade-offs considered
Context that someone (or an AI) needs to understand this note later

Write complete, substantive prose. Basic Memory's search retrieves relevant chunks from note bodies, so longer, richer context makes notes more discoverable and more useful when found. Don't reduce everything to bullet points — tell the story.

位于标题与Observations部分之间的自由格式Markdown内容。这是笔记的核心，建议详细撰写：

背景信息、动机和历史
事件详情及其重要性的说明
分析过程、推理逻辑和权衡考量
未来您（或AI协作方）理解笔记所需的上下文

撰写完整、详实的内容。Basic Memory的搜索功能会从笔记正文中提取相关片段，因此内容越丰富、上下文越详细，笔记的可发现性和实用性就越高。不要将所有内容简化为项目符号——完整讲述来龙去脉。

Observations

观察内容（Observations）

Observations are categorized facts — the atomic units of knowledge. Each one becomes a searchable entity in the knowledge graph.

观察内容是带分类的事实，是知识的原子单元。每条观察内容都会成为知识图谱中可搜索的实体。

Syntax

语法格式

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

Square brackets define the semantic category
Content is the fact, decision, insight, or note
Hash tags (optional) add extra metadata for filtering

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

方括号用于定义语义分类
内容为事实、决策、见解或备注
井号标签（可选）用于添加额外元数据以辅助筛选

Categories Are Arbitrary

分类可自定义

The category in brackets is free-form — use whatever label makes sense for the observation. There is no fixed list. The only rule is the

[category] content

syntax. Consistency within a project helps searchability, but invent categories freely.

A few examples to illustrate the range:

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

方括号中的分类为自由格式——使用任何符合观察内容含义的标签即可，没有固定列表。唯一的规则是遵循

[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

Observation Tips

观察内容撰写技巧

One fact per observation. Don't pack multiple ideas into one line.

Be specific.

[decision] Use JWT

is less useful than

[decision] Use JWT with 15-minute expiry for API auth

Use tags for cross-cutting concerns.
```
[risk] Rate limiting needed #api #security
```
makes this findable under both topics.
Categories are queryable.
```
search_notes("[decision]")
```
finds all decisions across your knowledge base.

每条观察对应一个事实。不要在一行中包含多个想法。

内容要具体。

[decision] Use JWT

的实用性远不如

[decision] Use JWT with 15-minute expiry for API auth

。

使用标签标记跨领域关注点。
```
[risk] Rate limiting needed #api #security
```
可让该内容在两个主题下都被检索到。
分类可被查询。
```
search_notes("[decision]")
```
可在知识库中找到所有决策类内容。

Relations

关联关系（Relations）

Relations create edges in the knowledge graph, linking notes to each other. They're how you build structure beyond individual notes.

关联关系在知识图谱中创建边，将不同笔记相互链接。这是将单个笔记构建为结构化知识网络的关键。

Syntax

语法格式

- relation_type [[Target Note Title]]

relation_type is a descriptive verb or phrase (snake_case by convention)
Double brackets
```
[[...]]
```
identify the target note by title or permalink
Relations are directional: this note → target note

- relation_type [[Target Note Title]]

relation_type为描述性动词或短语（通常采用蛇形命名法snake_case）
双括号
```
[[...]]
```
通过标题或permalink标识目标笔记
关联关系具有方向性：当前笔记 → 目标笔记

Relation Types

关联关系类型

Type	Purpose	Example
`implements`	One thing implements another	`- implements [[Auth Spec]]`
`requires`	Dependencies	`- requires [[Database Setup]]`
`relates_to`	General connection	`- relates_to [[Performance Notes]]`
`part_of`	Hierarchy/composition	`- part_of [[Backend Architecture]]`
`extends`	Enhancement or elaboration	`- extends [[Base Config]]`
`pairs_with`	Things that work together	`- pairs_with [[Frontend Client]]`
`inspired_by`	Source material	`- inspired_by [[CRDT Research Paper]]`
`replaces`	Supersedes another note	`- replaces [[Old Auth Design]]`
`depends_on`	Runtime/build dependency	`- depends_on [[MCP SDK]]`
`contrasts_with`	Alternative approaches	`- contrasts_with [[GraphQL Approach]]`

类型	用途	示例
`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]]`

Inline Relations

内联关联

Wiki-links anywhere in the note body — not just the Relations section — also create graph edges:

markdown

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

These create

references

relations automatically. Use the Relations section for explicit, typed relationships; use inline links for natural prose references.

笔记正文中的任何位置的维基链接——不仅限于Relations部分——也会自动创建图谱边：

markdown

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部分用于显式的带类型关联，而内联链接适用于自然叙述中的引用。

Relation Tips

关联关系撰写技巧

Link liberally. Relations are what turn isolated notes into a knowledge graph. When in doubt, add the link.
Create target notes if they don't exist yet.
```
[[Future Topic]]
```
is valid — BM will resolve it when that note is created.
Use
build_context
to traverse.
```
build_context(url="memory://note-title")
```
follows relations to gather connected knowledge.
Custom relation types are fine.
```
taught_by
```
,
```
blocks
```
,
```
tested_in
```
— use whatever is descriptive.

大量添加链接。关联关系是将孤立笔记转化为知识图谱的核心。如有疑问，就添加链接。
若目标笔记不存在则创建它。
```
[[Future Topic]]
```
是合法的写法——当该笔记创建后，Basic Memory会自动解析链接。
使用
build_context
遍历图谱。
```
build_context(url="memory://note-title")
```
会遍历关联关系以收集相关知识。
自定义关联关系类型完全可行。
```
taught_by
```
、
```
blocks
```
、
```
tested_in
```
等任何具有描述性的类型都可以使用。

Memory URLs

Memory URL

Every note is addressable via a

memory://

URL, built from its permalink. These URLs are how you navigate the knowledge graph programmatically.

每篇笔记都可通过

memory://

URL访问，该URL基于其permalink构建。这些URL是您以编程方式浏览知识图谱的方式。

URL Patterns

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

memory://api-design-decisions          # 通过permalink访问（标题转为短横线分隔形式）
memory://docs/authentication           # 通过文件路径访问
memory://docs/authentication.md        # 带扩展名的路径（同样有效）
memory://auth*                         # 前缀通配符
memory://docs/*                        # 后缀通配符
memory://project/*/requirements        # 路径通配符

Project-Scoped URLs

项目范围URL

In multi-project setups, prefix with the project name:

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

The first path segment is matched against known project names. If it matches, it's used as the project scope. Otherwise the URL resolves in the default project.

在多项目环境中，可在URL前添加项目名称前缀：

memory://main/specs/api-design         # "main"项目，路径为"specs/api-design"
memory://research/papers/crdt          # "research"项目

路径的第一个片段会与已知项目名称匹配。若匹配成功，则将其作为项目范围；否则URL将在默认项目中解析。

Using Memory URLs

Memory URL的使用

Memory URLs work with

build_context

to assemble related knowledge by traversing relations:

python

undefined

Memory URL可与

build_context

配合使用，通过遍历关联关系来整合相关知识：

python

undefined

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

通过permalink直接读取笔记

read_note(identifier="memory://api-design-decisions")

undefined

read_note(identifier="memory://api-design-decisions")

undefined

Before Creating a Note

创建笔记前的准备

Always search Basic Memory before creating a new note. Duplicates fragment your knowledge graph — updating an existing note is almost always better than creating a second one.

创建新笔记前，请务必先在Basic Memory中搜索。重复笔记会分散您的知识图谱——更新现有笔记几乎总是比创建新笔记更好。

Search with Multiple Variations

使用多种变体搜索

A single search often misses. Try the full name, abbreviations, acronyms, and keywords:

python

undefined

单次搜索可能会遗漏内容。请尝试使用完整名称、缩写、首字母缩写和关键词：

python

undefined

Searching for an entity that might already exist

搜索可能已存在的实体

search_notes(query="Kubernetes Migration") search_notes(query="k8s migration") search_notes(query="container migration")


For people, try full name and last name. For organizations, try the full name and common abbreviations.

search_notes(query="Kubernetes Migration") search_notes(query="k8s migration") search_notes(query="container migration")


对于人物，尝试使用全名和姓氏；对于组织，尝试使用全名和常用缩写。

Decision Tree

决策流程

Entity exists → Update it with
```
edit_note
```
(append observations, add relations, find-and-replace outdated info)
Entity doesn't exist → Create it with
```
write_note
```
Unsure if it's the same entity → Read the existing note first, then decide

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

Granular Updates with

edit_note

使用

edit_note

进行精细化更新

When a note already exists, make targeted edits instead of rewriting the whole file:

python

undefined

当笔记已存在时，请进行针对性编辑，而非重写整个文件：

python

undefined

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


This preserves existing content and keeps the edit history clean.

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


这样可以保留现有内容，并保持编辑记录的整洁。

Writing Notes with Tools

使用工具撰写笔记

Creating a Note

创建笔记

python

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.

python

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

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

Relations

implements [[API Specification]]
relates_to [[Backend Architecture]]""" )


Basic Memory auto-generates frontmatter (including the permalink and memory URL) from the parameters. This note would get permalink `architecture/api-design-decisions` and be addressable at `memory://architecture/api-design-decisions`.

implements [[API Specification]]
relates_to [[Backend Architecture]]""" )


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

Editing an Existing Note

编辑现有笔记

Use

edit_note

to append, prepend, or find-and-replace within a note:

python

undefined

使用

edit_note

进行追加、前置或查找替换操作：

python

undefined

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

undefined

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

undefined

Moving a Note

移动笔记

Use

move_note

to reorganize notes into different directories:

python

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

The permalink stays the same after a move, so all

[[wiki-links]]

and

memory://

URLs continue to resolve.

使用

move_note

将笔记重新组织到不同目录：

python

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

笔记移动后permalink保持不变，因此所有

[[wiki-links]]

和

memory://

URL仍可正常解析。

Best Practices

最佳实践

Start with context. Before listing observations, explain why this note exists. Future-you (or your AI collaborator) will thank you.
Favor completeness. Write rich, substantive notes. Basic Memory's search pulls relevant chunks from note bodies, so longer notes with more context are more discoverable, not less. Use prose in the body to tell the full story — the background, the reasoning, the nuance. Then distill key facts into
```
[category] content
```
observations for structured queries. Both matter: prose gives meaning, observations give precision.
Build incrementally. Add to existing notes rather than creating duplicates. Use
```
edit_note
```
to append new observations or relations as you learn more.
Review AI-generated content. When an AI writes notes for you, review them for accuracy. The AI captures structure well but may miss nuance.
Use consistent titles. Note titles are identifiers in the knowledge graph.
```
API Design Decisions
```
and
```
Api Design decisions
```
are different entities. Pick a convention and stick with it.
Link related concepts. The value of a knowledge graph compounds with connections. A note with zero relations is an island — useful, but not as powerful as a connected one.
Let the graph grow naturally. Don't try to design a perfect taxonomy upfront. Write notes as you work, add relations as connections emerge, and periodically use
```
/reflect
```
or
```
/defrag
```
to consolidate.

从上下文开始。在列出观察内容之前，先说明这篇笔记的存在原因。未来的您（或您的AI协作方）会为此感谢您。
优先保证完整性。撰写丰富、详实的笔记。Basic Memory的搜索功能会从笔记正文中提取相关片段，因此内容越长、上下文越详细，笔记的可发现性就越高。使用正文叙述完整的故事——包括背景、推理和细节。然后将关键事实提炼为
```
[category] content
```
格式的观察内容，以便进行结构化查询。两者都很重要：叙述赋予意义，观察内容保证精准。
逐步构建内容。向现有笔记中添加内容，而非创建重复笔记。随着您了解更多信息，使用
```
edit_note
```
追加新的观察内容或关联关系。
审核AI生成的内容。当AI为您撰写笔记时，请审核内容的准确性。AI擅长构建结构，但可能会遗漏细节。
使用一致的标题。笔记标题是知识图谱中的标识符。
```
API Design Decisions
```
和
```
Api Design decisions
```
被视为不同的实体。请选择一种命名规范并坚持使用。
关联相关概念。知识图谱的价值会随着连接的增加而倍增。零关联的笔记就像一座孤岛——有用，但远不如相互连接的笔记强大。
让图谱自然生长。不要试图一开始就设计完美的分类体系。在工作过程中撰写笔记，随着关联关系的浮现添加链接，并定期使用
```
/reflect
```
或
```
/defrag
```
进行内容整合。

memory-notes

Original

Translation

Memory Notes

Basic Memory笔记

Note Anatomy

笔记结构解析

API Design Decisions

API Design Decisions

Observations

Observations

Relations

Relations

Frontmatter

前置元数据（Frontmatter）

Body / Context

正文/上下文

Observations

观察内容（Observations）

Syntax

语法格式

Categories Are Arbitrary

分类可自定义

Observation Tips

观察内容撰写技巧

Relations

关联关系（Relations）

Syntax

语法格式

Relation Types

关联关系类型

Inline Relations

内联关联

Relation Tips

关联关系撰写技巧

Memory URLs

Memory URL

URL Patterns

URL模式

Project-Scoped URLs

项目范围URL

Using Memory URLs

Memory URL的使用

Get a note and its connected context

获取笔记及其关联的上下文内容

Wildcard — gather all docs

通配符 — 收集所有文档

Direct read by permalink

通过permalink直接读取笔记

Before Creating a Note

创建笔记前的准备

Search with Multiple Variations

使用多种变体搜索

Searching for an entity that might already exist

搜索可能已存在的实体

Decision Tree

决策流程

Granular Updates with edit_note

使用edit_note进行精细化更新

Append a new observation to an existing note

向现有笔记追加新的观察内容

Fix outdated information

修正过时信息

Add a new relation

添加新的关联关系

Writing Notes with Tools

使用工具撰写笔记

Creating a Note

创建笔记

Observations

Observations

Relations

Relations

Editing an Existing Note

编辑现有笔记

Append new observations

追加新的观察内容

Add a new relation

添加新的关联关系

Moving a Note

Granular Updates with
`edit_note`

使用
`edit_note`
进行精细化更新