Reference

AI Assistant Guide

Guide for AI assistants using Basic Memory through the Model Context Protocol (MCP).

This guide is for AI assistants using Basic Memory tools through MCP. For setup instructions, see Getting Started.Download the AI Assistant Guide and customize it to your own workflow. A condensed version is available as an MCP Resource in Basic Memory.

AI agents: This documentation is available as clean markdown. Fetch https://docs.basicmemory.com/llms.txt for an index or https://docs.basicmemory.com/llms-full.txt for the complete docs. See AI-Friendly Documentation for details.

This guide explains how to use Basic Memory tools effectively when working with users through the Model Context Protocol.

Overview

Basic Memory creates a semantic knowledge graph from markdown files stored locally on the user's computer. Knowledge persists across sessions, enabling continuity in conversations and collaborative development.

Architecture:

Plain-Text: Markdown files as source of truth
SQLite Index: Fast search and navigation
MCP Integration: Tools for AI interaction
Semantic Graph: Observations and relations create connections

Your role: Help users build structured knowledge that outlasts any particular AI model or session. Focus on creating observations and relations that provide lasting value.

Project Management

All tools require explicit project specification. No implicit project context is maintained between calls.

Discovery and Selection

Start conversations by discovering available projects:

# List all projects
projects = await list_memory_projects()

# Response includes:
# - name
# - path
# - is_default
# - note_count
# - last_synced

Recommended workflow:

Call list_memory_projects() at conversation start
Identify active project from metadata
Ask user which project to use
Store choice for the session
Pass project parameter to all tool calls

Cross-Project Operations

Some tools work across all projects when project parameter is omitted:

# Recent activity across all projects
activity = await recent_activity(timeframe="7d")

# Recent activity for specific project
activity = await recent_activity(timeframe="7d", project="main")

Tools supporting cross-project mode:

recent_activity()
list_memory_projects()
sync_status()

Knowledge Graph Structure

The knowledge graph consists of three core elements: entities, observations, and relations.

Entities

Each markdown file represents an entity with:

Title: Unique identifier
Permalink: Auto-generated from title
Frontmatter: YAML metadata (tags, type, dates)
Observations: Categorized facts
Relations: Links to other entities

Entity types:

note - General knowledge (default)
person - People and contacts
project - Projects and initiatives
meeting - Meeting notes
decision - Documented decisions
spec - Technical specifications

Observations

Observations are categorized facts with optional tags.

Syntax: - [category] content #tag1 #tag2

Common categories:

[fact] - Objective information
[idea] - Thoughts and concepts
[decision] - Choices made
[technique] - Methods and approaches
[requirement] - Needs and constraints
[problem] - Issues identified
[solution] - Resolutions
[insight] - Key realizations

Examples:

## Observations
- [decision] Use JWT tokens for authentication #security
- [technique] Hash passwords with bcrypt before storage #best-practice
- [requirement] Support OAuth 2.0 providers #auth
- [fact] Session timeout set to 24 hours #configuration

Relations

Relations are directional links between entities.

Syntax: - relation_type [[Target Entity]]

Common relation types:

relates_to - General connection
implements - Implementation relationship
requires - Dependency
extends - Enhancement
part_of - Hierarchical membership
contrasts_with - Alternative approach
leads_to - Sequential relationship
caused_by - Causal relationship

Examples:

## Relations
- implements [[Authentication Spec v2]]
- requires [[User Database Schema]]
- extends [[Base Security Model]]
- part_of [[API Backend Services]]
- contrasts_with [[API Key Authentication]]

Forward References

Reference entities that don't exist yet - relations resolve automatically when targets are created:

# Create note with forward reference
await write_note(
    title="API Implementation",
    content="## Relations\n- implements [[API Specification]]",
    folder="api",
    project="main"
)
# Forward reference created

# Later, create referenced entity
await write_note(
    title="API Specification",
    content="# API Specification\n...",
    folder="specs",
    project="main"
)
# Forward reference automatically resolved

Core Tools

Writing Knowledge

Create or update notes:

await write_note(
    title="Topic",
    content="# Topic\n## Observations\n- [category] fact\n## Relations\n- relates_to [[Other]]",
    folder="notes",
    project="main"
)

Parameters:

title (required) - Note title
content (required) - Markdown content
folder (required) - Destination folder
tags (optional) - List of tags
entity_type (optional) - Entity type
project (required unless default_project_mode) - Target project

Reading Knowledge

Read notes with knowledge graph context:

# By title
note = await read_note("Topic", project="main")

# By folder and title
note = await read_note("specs/Authentication System", project="main")

# By memory:// URL
note = await read_note("memory://specs/auth", project="main")

Response includes:

Content
Observations (categorized)
Relations (typed, with targets)
Metadata (dates, tags, type)

Searching

Find notes across the knowledge base:

results = await search_notes(
    query="authentication",
    project="main",
    page_size=10
)

Advanced filtering:

# Filter by entity type
specs = await search_notes(
    query="authentication",
    types=["spec"],
    project="main"
)

# Filter by date
recent = await search_notes(
    query="api",
    after_date="2025-01-01",
    project="main"
)

Building Context

Navigate the knowledge graph:

context = await build_context(
    url="memory://specs/auth",
    project="main",
    depth=2,
    timeframe="1 week"
)

Parameters:

url (required) - memory:// URL
depth (optional) - Traversal depth (default: 1)
timeframe (optional) - Time window (e.g., "7d", "1 week")
project (required unless default_project_mode)

Depth control:

depth=1 - Immediate connections only
depth=2 - Two levels of relations
depth=3+ - Comprehensive (may be slow)

Editing Notes

Edit existing notes incrementally:

# Append content
await edit_note(
    identifier="Topic",
    operation="append",
    content="\n## New Section\nContent here",
    project="main"
)

# Prepend content
await edit_note(
    identifier="Topic",
    operation="prepend",
    content="## Update\nImportant note\n\n",
    project="main"
)

# Find and replace
await edit_note(
    identifier="Topic",
    operation="find_replace",
    find_text="old text",
    content="new text",
    expected_replacements=1,
    project="main"
)

# Replace section
await edit_note(
    identifier="Topic",
    operation="replace_section",
    section="## Status",
    content="## Status\nUpdated status here",
    project="main"
)

Operations:

append - Add to end
prepend - Add to beginning
find_replace - Replace specific text
replace_section - Replace markdown section

Moving Notes

Organize notes by moving them between folders:

await move_note(
    identifier="Note Title",
    destination_path="archive/note-title.md",
    project="main"
)

Behavior:

Folders created automatically
Database updated automatically
Relations preserved
Both .md extension and without work

memory:// URL Format

Basic Memory uses special URLs to reference entities:

By title:

memory://title

By folder and title:

memory://folder/title

By permalink:

memory://permalink

All in folder:

memory://folder/*

Underscores converted to hyphens automatically - memory://my_note finds entity with permalink my-note.

Recording Conversations

Capture conversations to enable long-term context and knowledge accumulation.

Permission and Transparency

Always ask before recording:

AI: "Would you like me to save our discussion about API authentication
     to Basic Memory? This helps us continue this conversation later."

User: "Yes, please"

AI: [Saves to Basic Memory]
    "I've saved our discussion as 'API Authentication Discussion'."

Principles:

Ask permission before saving
Confirm after saving
Explain what was saved
Describe how it helps future conversations

What to Record

Good candidates:

Decisions and Rationales
Important Discoveries
Action Items and Plans
Connected Topics

Recording Patterns

Conversation summary:

await write_note(
    title=f"Conversation: {topic} - {date}",
    content=f"""# Conversation: {topic}

## Summary
{brief_summary}

## Key Points
{key_points}

## Observations
{categorized_observations}

## Relations
{relevant_relations}
""",
    folder="conversations",
    tags=["conversation"],
    project="main"
)

Decision record:

await write_note(
    title=f"Decision: {decision_title}",
    content=f"""# Decision: {decision_title}

## Context
{why_decision_needed}

## Decision
{what_was_decided}

## Rationale
{reasoning}

## Relations
{related_entities}
""",
    folder="decisions",
    entity_type="decision",
    project="main"
)

Best Practices

1. Project Discovery

Always start with discovery:

# First action in conversation
projects = await list_memory_projects()

# Ask user which to use
# Store for session
# Use consistently

2. Rich Knowledge Graphs

Every note should have:

Clear, descriptive title
3-5 observations minimum
2-3 relations minimum
Appropriate categories and tags

Good structure:

---
title: Clear Descriptive Title
tags: [relevant, tags]
type: note
---

# Title

## Context
Brief background

## Observations
- [category] Specific fact #tag1 #tag2
- [category] Another fact #tag3
- [category] Third fact #tag4

## Relations
- relation_type [[Related Entity 1]]
- relation_type [[Related Entity 2]]

3. Search Before Creating

Always search first to avoid duplicates:

# Before writing new note
existing = await search_notes(
    query="topic name",
    project="main"
)

if existing["total"] > 0:
    # Update existing
    await edit_note(
        identifier=existing["results"][0]["permalink"],
        operation="append",
        content=new_information,
        project="main"
    )
else:
    # Create new
    await write_note(...)

4. Exact Entity Titles in Relations

Use exact titles when creating relations:

# Search for exact title
results = await search_notes(query="Authentication System", project="main")
exact_title = results["results"][0]["title"]

# Use in relation
content = f"## Relations\n- relates_to [[{exact_title}]]"

5. Meaningful Categories and Relations

Use semantic categories:

[decision] for choices made
[fact] for objective information
[technique] for methods
[requirement] for needs
[insight] for realizations

Use specific relation types:

implements for implementation
requires for dependencies
part_of for hierarchy
extends for enhancement
contrasts_with for alternatives

Avoid generic: Don't overuse relates_to - be specific about relationships.

6. Progressive Elaboration

Build knowledge over time:

# Session 1: Create foundation
await write_note(
    title="Topic",
    content="Basic structure with initial observations",
    folder="notes",
    project="main"
)

# Session 2: Add details
await edit_note(
    identifier="Topic",
    operation="append",
    content="Additional observations",
    project="main"
)

# Session 3: Add relations
await edit_note(
    identifier="Topic",
    operation="append",
    content="Relations to related topics",
    project="main"
)

7. Consistent Organization

Folder structure:

specs/ - Specifications
decisions/ - Decision records
meetings/ - Meeting notes
conversations/ - AI conversations
implementations/ - Code/implementations
docs/ - Documentation

8. Confirm Destructive Actions

Always ask before calling delete_note or move_note on folders.

When in doubt, create a snapshot (Cloud) or suggest a backup (Local).

Error Handling

Missing Project Parameter

Solution:

try:
    results = await search_notes(query="test")
except:
    projects = await list_memory_projects()
    # Ask user which to use
    results = await search_notes(query="test", project="main")

Entity Not Found

Solution:

try:
    note = await read_note("Nonexistent Note", project="main")
except:
    results = await search_notes(query="Note", project="main")
    # Suggest alternatives to user

Tool	Purpose
`write_note`	Create or update markdown notes
`read_note`	Read notes with knowledge graph context
`edit_note`	Edit notes incrementally
`move_note`	Move notes to new locations
`delete_note`	Delete notes from knowledge base
`view_note`	View notes as formatted artifacts
`read_content`	Read raw file content

Knowledge Graph Navigation

Tool	Purpose
`build_context`	Navigate knowledge graph
`recent_activity`	Get recent changes
`list_directory`	Browse directory contents

Search & Discovery

Tool	Purpose
`search_notes`	Search across knowledge base

Project Management

Tool	Purpose
`list_memory_projects`	List all available projects
`create_memory_project`	Create new project
`delete_project`	Delete project from configuration
`sync_status`	Check synchronization status

Visualization

Tool	Purpose
`canvas`	Create Obsidian canvas

Next Steps

MCP Tools Reference

Complete tool documentation with parameters and examples.

Knowledge Format

Understanding the note structure and semantic patterns.

Edit this pageorReport an issue

MCP Tools Reference

Complete reference of all Basic Memory MCP tools and prompts available to AI assistants.

Technical Information

Technical details about Basic Memory implementation, architecture, licensing, and Model Context Protocol integration