/memory-notes

name: memory-notes
description: "How to write well-structured Basic Memory notes: frontmatter, observations with semantic categories, relations with wiki-links, and best practices for building a rich knowledge graph. Use when creating or improving notes."

Memory Notes

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.

Note Anatomy

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

Frontmatter

Every note starts with YAML frontmatter:

---
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. By default permalinks stay stable across file moves (unless the project enables `update_permalinks_on_move`). 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`.

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

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

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

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(entity_types=["observation"], categories=["decision"])` returns every decision observation across your knowledge base.

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