Knowledge Format

Understanding how Basic Memory structures knowledge helps 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:

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

Observations

Observations are facts or statements about a topic:

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

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

Primary 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
• [fact] - Established information
• [question] - Open questions or unknowns
• [todo] - Action items

Relations

Relations connect documents to form the knowledge graph:

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

You can also create inline references:

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

Common Relation Types

• 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
• replaces - Supersedes another document
• references - Citation or mention

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.

Permalinks

Every document has a unique permalink that serves as its stable identifier.

How Permalinks Work

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.

Permalink Stability

By default, a note's permalink value will not change if the file is moved - it's a stable identifier. To change this behavior, edit ~/.basic-memory/config.json:

{
  "update_permalinks_on_move": true
}

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 (resolves automatically)
memory://project/auth-approaches     # Access by path

Pattern Matching

Memory URLs support pattern matching for powerful queries:

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

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

Next Steps