# Memory Notes

How to write well-structured Basic Memory notes: frontmatter, categorized observations...

- Repository: https://github.com/basicmachines-co/basic-memory (4440 stars)
- Category: Writing
- License: AGPL-3.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add basicmachines-co/basic-memory --skill memory-notes -g -a claude-code -y`
Codex: `npx skills add basicmachines-co/basic-memory --skill memory-notes -g -a codex -y`
Cursor: `npx skills add basicmachines-co/basic-memory --skill memory-notes -g -a cursor -y`
Gemini CLI: `npx skills add basicmachines-co/basic-memory --skill memory-notes -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add basicmachines-co/basic-memory`

## Description

How to write well-structured Basic Memory notes: frontmatter, categorized observations, wiki-link relations, and knowledge-graph best practices. Use when creating or improving notes.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

## Project scope

If the project is unknown, discover it with `bm_project(command="list")`.
Pass a nonempty `project` on every note, folder, context and schema call, even
with one project or a qualified `memory://` URL. Use the chosen project's name,
`workspace/project`, or external ID; `<project>` below is a placeholder for it.
Recent activity also requires `project`. Search accepts `project` for one
project, `projects` for selected projects, or `all_projects=True` explicitly.
Discovery and bundled manuals need no project. Keep the same scope when following
returned paths, paginating, or recovering from a refusal.

## Note Anatomy

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

### 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 rest: https://github.com/basicmachines-co/basic-memory/blob/HEAD/skills/memory-notes/SKILL.md