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

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

• 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 title if you don't set one. Stays the same even if you move the file.

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.

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.

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.

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 title. Permalinks are how Basic Memory addresses notes internally and how memory:// URLs work:

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. Flat folders, nested hierarchies, topic-based groupings — the knowledge graph is built from the content of your notes, not from where they sit on disk.

knowledge/
  projects/
    auth-design.md
    api-roadmap.md
  meetings/
    2026-03-01-standup.md
  decisions/
    database-choice.md

The graph connects everything regardless of 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