Knowledge Format

Basic Memory is a knowledge base that you and your AI share. Everything is stored as plain markdown files on your machine — files you can open in any text editor, track with git, browse in Obsidian, or back up however you like. You own your data completely.

This page explains how those files are structured and how that structure turns a folder of notes into a connected knowledge graph.

What a Note Looks Like

Here's a note that an AI might create during a conversation about a project:

---
title: Authentication Design
type: note
tags: [auth, security, backend]
permalink: authentication-design
created: 2026-08-01T14:30:00Z
modified: 2026-08-10T09:15:00Z
---

# Authentication Design

## Observations
- [decision] Using JWT tokens for stateless authentication #security
- [approach] Refresh tokens stored in HTTP-only cookies to prevent XSS
- [constraint] Tokens expire after 15 minutes to limit exposure window
- [status] Implementation complete and deployed to staging

## Relations
- implements [[API Security Requirements]]
- depends_on [[User Database Schema]]
- relates_to [[Session Management]]

That's it. Markdown with a few simple patterns. The AI handles writing notes like this for you — you just tell it what you want to remember and it produces well-structured notes. But it helps to understand what you're looking at, so let's walk through the pieces.

Frontmatter

The YAML block at the top of each file holds metadata:

---
title: Authentication Design
type: note
tags: [auth, security, backend]
permalink: authentication-design
created: 2026-08-01T14:30:00Z
modified: 2026-08-10T09:15:00Z
---

• title — The name of the note. Used for linking and display.
• type — What kind of note this is (e.g. note, meeting, decision). You can use any type you want.
• tags — For organization and filtering.
• permalink — A stable identifier for this note. Generated automatically from the file's path (and prefixed with the project name by default) if you don't set one. Stays the same even if you later move the file.
• created and modified — Optional authoritative timestamps for the note. When present, Basic Memory uses them for recency ordering instead of filesystem timestamps.

Historical created or modified values can move a note earlier in recent_activity and date-sorted search results after the note is reindexed. Use valid date or datetime values and change them only when you intend to change the note's recorded chronology.

Observations

Observations are individual facts, decisions, or details captured as list items with a category in brackets:

## Observations
- [decision] Using JWT tokens for stateless authentication #security
- [approach] Refresh tokens stored in HTTP-only cookies
- [constraint] Tokens expire after 15 minutes (based on security audit)

The pattern is: - [category] content #optional-tags (optional context)

Categories can be anything that makes sense for what you're capturing — [decision], [fact], [preference], [question], [todo], [risk], [idea], whatever fits. There's no fixed list. Use what feels natural and the AI will follow your lead.

The power of observations is that each one is indexed individually. When you search your knowledge base, Basic Memory can surface the specific fact you need rather than just pointing you at a whole document. See Semantic Search for how this works.

For category conventions, tags, and worked examples, see the deep dive: Observations and Relations.

Relations

Relations link notes together using [[wiki-link]] syntax:

## Relations
- implements [[API Security Requirements]]
- depends_on [[User Database Schema]]
- relates_to [[Session Management]]

The word before the link becomes the relationship type. Like categories, you can use any relation type — implements, inspired_by, blocks, part_of, contrasts_with, whatever describes the connection. Quoting rules and edge cases (multi-word types, bare wikilinks) are covered in Observations and Relations.

You can also reference other notes inline anywhere in the document:

This builds on the patterns established in [[Core Architecture]] and
addresses the concerns raised in [[Security Review Q4]].

Relations can link to notes that don't exist yet. When those notes are created later, the connections are already in place.

How wikilinks resolve

Basic Memory tries exact identities first: permalink, title, and file path. At the project root, a filename-stem link such as [[alpha_note]] can resolve alpha_note.md even when the note's frontmatter title is different.

If no exact identity matches, Basic Memory can try a Unicode case-insensitive file-path alias that treats underscores and hyphens as equivalent. The fallback must identify exactly one note; [[alpha-note]] remains unresolved when multiple files collapse to the same alias. This forgiving lookup applies only to link resolution—writes and updates keep their exact note identity rules and never use the alias to choose a file to overwrite or move.

Directory casing is handled separately. Since v0.23.2, each destination-folder segment on a note write or move resolves to an existing folder when there is exactly one case-insensitive match, so schemas/drafts can land in Schemas/Drafts. Unknown folders are created with the requested spelling, existing case-variant siblings remain ambiguous, and the note's basename is never case-corrected by this folder rule.

For relation-type conventions and how inline references index, see Observations and Relations.

The Knowledge Graph

Every note you write becomes a node. Every relation becomes an edge. Together, they form a knowledge graph that grows with your conversations.

This graph is what makes Basic Memory more than a folder of files. When the AI uses build_context, it can follow connections across notes to pull together relevant information from across your entire knowledge base — not just the one note you asked about, but the notes it links to, and the notes that link back to it.

Permalinks

Every note has a permalink — a stable identifier derived from its file path (project-prefixed by default). Permalinks are how Basic Memory addresses notes internally and how memory:// URLs work — and by default they stay unchanged when a file is renamed or moved:

memory://authentication-design

Permalinks stay the same even if you rename or move the file. For more on how memory URLs work, including pattern matching and graph traversal, see Memory URLs.

File Organization

Organize your files however you want — the knowledge graph is built from the content of your notes, not from where they sit on disk. See Projects and Folders for organizing with projects and folder structure.

Schemas

If you want consistency across certain types of notes — say, all meeting notes should include attendees and action items — you can define schemas that describe what a note type should contain. The AI will follow them automatically.

See Schema System for details.

Agent Skills

You can teach your AI best practices for writing notes using agent skills. The memory-notes skill gives the AI guidance on structuring knowledge effectively. See Agent Skills for how to set this up.

Next Steps