Understanding how Basic Memory structures knowledge will help you create richer, more connected notes. Here’s how the semantic patterns work.

​
File-First Architecture

All knowledge in Basic Memory is stored in plain text Markdown files:

  • Files are the source of truth for all knowledge in Basic Memory
  • Changes to files automatically update the knowledge graph in the db
  • You maintain complete ownership and control
  • Files work with git and other version control systems
  • Knowledge persists independently of any AI conversation

​
Core Document Structure

Every document uses this basic structure:

---
title: Document Title
type: note
tags: [tag1, tag2]
permalink: custom-path
---

# Document Title

Regular markdown content...

## Observations
- [category] Content with #tags (optional context)

## Relations
- relation_type [[Other Document]] (optional context)

​
Frontmatter

The YAML frontmatter at the top of each file defines essential metadata:

---
title: Document Title    # Used for linking and references
type: note               # Document type
tags: [tag1, tag2]       # For organization and searching
permalink: custom-link   # Optional custom URL path
---

The title is particularly important as it’s used to create links between documents.

​
Observations

Observations are facts or statements about a topic:

- [tech] Uses SQLite for storage #database
- [design] Follows local-first architecture #architecture
- [decision] Selected bcrypt for passwords #security (Based on audit)

Observations are markdown list items beginning a [category] value. Basic Memory knows to not make Markdown lists: [ ] or [x] into observations.

Each observation contains:

  • Category in [brackets] - classifies the information type
  • Content text - the main information
  • Optional #tags - additional categorization
  • Optional (context) - supporting details

Common Categories

  • [tech]: Technical details
  • [design]: Architecture decisions
  • [feature]: User capabilities
  • [decision]: Choices that were made

Additional Categories

  • [principle]: Fundamental concepts
  • [method]: Approaches or techniques
  • [preference]: Personal opinions

​
Relations

Relations connect documents to form the knowledge graph:

- implements [[Search Design]]
- depends_on [[Database Schema]]
- relates_to [[User Interface]]

Relations are markdown list items beginning a descriptive word, followed by a [[wiki link]] value. The description will by used as the relationship type.

You can also create inline references:

This builds on [[Core Design]] and uses [[Utility Functions]].

Common relation types include:

  • implements: Implementation of a specification
  • depends_on: Required dependency
  • relates_to: General connection
  • inspired_by: Source of ideas
  • extends: Enhancement
  • part_of: Component relationship
  • contains: Hierarchical relationship
  • pairs_with: Complementary relationship

​
Knowledge Graph

Basic Memory automatically builds a knowledge graph from your document connections:

  • Each document becomes a node in the graph
  • Relations create edges between nodes
  • Relation types add semantic meaning to connections
  • Forward references can link to documents that don’t exist yet

This graph enables rich context building and navigation across your knowledge base.

Every document in Basic Memory has a unique permalink that serves as its stable identifier:

  • Automatically assigned: The system generates a permalink for each document
  • Based on title: By default, derived from the document title
  • Always unique: If conflicts exist, the system adds a suffix to ensure uniqueness
  • Stable reference: Remains the same even if the file moves in the directory structure
  • Used in memory:// URLs: Forms the basis of the memory:// addressing scheme

You can specify a custom permalink in the frontmatter:

---
title: Authentication Approaches
permalink: auth-approaches-2024
---

If not specified, one will be generated automatically from the title, if the note has has a frontmatter section.

By default a notes’ permalink value will not change if the file is moved. It’s a stable identifier. But if you’d rather permalinks are always updated when a file moves, you can set the config setting in the global config.

The config file for Basic Memory is in the home directory under .basic-memory/config.json.

To change the behavior, set the following value:

~/.basic-memory/config.json 
{
  "update_permalinks_on_move": true
}

​
Using memory:// URLs

The memory:// URL scheme provides a reliable way to reference knowledge:

memory://auth-approaches-2024        # Direct access by permalink
memory://Authentication Approaches   # Access by title (automatically resolves)
memory://project/auth-approaches     # Access by path

Memory URLs support pattern matching for more powerful queries:

memory://auth*                      # All documents with permalinks starting with "auth"
memory://*/approaches               # All documents with permalinks ending with "approaches"
memory://project/*/requirements     # All requirements documents in the project folder
memory://docs/search/implements/*   # Follow all implements relations from search docs

This addressing scheme ensures content remains accessible even as your knowledge base evolves and files are reorganized.

​
File Organization

Organize files in any structure that suits your needs:

docs/
  architecture/
    design.md
    patterns.md
  features/
    search.md
    auth.md

You can:

  • Group by topic in folders
  • Use a flat structure with descriptive filenames
  • Tag files for easier discovery
  • Add custom metadata in frontmatter

The system will build the semantic knowledge graph regardless of how you organize your files.