Observations and relations
Basic Memory notes aren't just text. Each note can contain observations (individual facts) and relations (links to other notes). Together, they turn a folder of Markdown files into a searchable, navigable knowledge graph.
The important thing to know up front: you don't need to write these by hand. When you ask your AI assistant to write a note, it creates observations and relations automatically. You should understand what they are so you can read your notes and give feedback, but you never need to memorize the syntax.
Observations
An observation is a single fact, captured as a list item with a category in brackets:
- [decision] Use Postgres for primary storage #database
- [risk] Latency spikes under heavy load #performance
- [preference] Dark mode for all internal tools #ux
The category (the word in brackets) classifies the kind of fact. The rest of the line is the content. There is no fixed list of categories — use whatever makes sense for what you're capturing:
- [tool] Basic Memory uses SQLite for local indexing
- [recipe] Bloom the espresso for 30 seconds before extraction
- [symptom] App crashes on launch after upgrading to iOS 18
- [quote] "Simplicity is the ultimate sophistication" — Leonardo da Vinci
- [milestone] v1.0 shipped on March 15
Categories help your AI assistant understand what kind of information it's looking at. When it builds context from your knowledge base, it can distinguish a decision from a risk, a preference from a requirement. That distinction matters when it's helping you reason through a problem.
Tags within observations
The #hashtags at the end of an observation line add extra searchability:
- [decision] Switch to async job processing #architecture #backend
- [feedback] Users want faster search results #ux #search
Tags are indexed and searchable with the tag: prefix in search queries. They cut across categories — you might tag observations from many different notes with #database and then find all of them in one search.
Tags are optional. Many observations work fine without them. Add them when you want a cross-cutting way to find information later.
Relations
A relation is a link from one note to another, with a label that describes how they're connected:
## Relations
- depends_on [[Caching Layer]]
- relates_to [[Latency Budget]]
- owned_by [[Platform Team]]
The label before the [[link]] is the relation type. Like categories, there is no fixed list — use whatever describes the connection:
- implements [[RFC-042 Async Processing]]
- contrasts_with [[Monolith Architecture]]
- learned_from [[Q3 Retrospective]]
- inspired_by [[Obsidian Plugin System]]
- blocked_by [[Auth Migration]]
Relations are directional. System Design - depends_on -> Caching Layer creates a link in the knowledge graph from one note to the other. Your AI assistant can follow these links to build context — starting from one note and pulling in the connected notes to understand the bigger picture.
Inline references
You can also link to other notes anywhere in a note's body text using [[wiki links]]:
We decided to follow the approach from [[API Design Principles]]
because it aligns with our [[Team Standards]].
These inline references also create connections in the knowledge graph. The difference is that relations in a dedicated ## Relations section have explicit types (depends_on, relates_to), while inline references create a general "references" connection. Both are useful.
Why this matters
Observations and relations aren't just formatting — they're what makes Basic Memory's search and navigation powerful.
Precise search
Every observation is indexed individually. When you search your knowledge base, Basic Memory doesn't just match against whole documents — it can surface a specific fact from deep inside a long note.
If you have a 2000-word architecture document with dozens of observations, a search for "database migration strategy" can find the one relevant observation without forcing you to read the entire note. Semantic search matches the meaning of your query against each observation, so even different wording will find the right fact.
Knowledge graph navigation
Relations create a graph you can traverse. The build_context tool follows links between notes to assemble relevant information from across your knowledge base. When you ask your AI assistant about a topic, it doesn't just find one note — it follows relations to pull in connected context.
For example, if you ask about a system design decision, the assistant might start with the design note, follow a depends_on link to the caching strategy, then follow a relates_to link to the performance requirements. That chain of connections gives it a much richer understanding than any single note would.
AI context building
Categories, tags, and relation types give your AI assistant structured metadata to work with. It can filter observations by category, search by tag, and navigate by relation type. This structure means the assistant can be selective about what context it pulls in, rather than dumping entire documents into the conversation.
Enforcing structure with schemas
If you want to ensure consistency across similar notes, Basic Memory's schema system (introduced in v0.19) can validate that notes of a certain type contain the observations and relations you expect.
For example, you could define a schema that requires every "person" note to have a name observation and a works_at relation. The schema validates notes when they're written and flags anything that's missing.
Teaching your AI with skills
The memory-notes skill teaches your AI assistant best practices for writing observations and relations — what categories to use, how to structure relations, and when to add tags. Skills are a way to encode your preferences so the AI writes notes the way you want without being reminded every time.