User Guide

This guide covers everything from creating your first notes to building a comprehensive knowledge graph using Basic Memory Cloud.

Basic Memory Workflow

Using Basic Memory follows a natural cycle:

1. Have conversations with AI assistants like Claude
2. Capture knowledge as notes in your cloud storage
3. Build connections between pieces of knowledge
4. Reference your knowledge in future conversations
5. Edit notes in the web app when needed

Creating Knowledge

Through Conversations

The most natural way to create knowledge is during conversations:

You: We've covered several authentication approaches. Could you create a note
     summarizing what we've discussed?

Claude: I'll create a note summarizing our authentication discussion.

[Uses write_note tool]

Done! I've created "Authentication Approaches.md" with:
- Overview of options we discussed
- Observations about JWT vs sessions
- Relations to your security notes

This creates a Markdown file with semantic markup in your cloud knowledge base.

Through the Web App

You can also create notes directly in the web app:

1. Navigate to Notes in the web app
2. Click New Note or create in a specific folder
3. Add frontmatter with title and optional tags
4. Structure content with observations and relations
5. Save - changes sync automatically

Example note structure:

---
title: API Design Decisions
tags: [api, architecture, decisions]
---

# API Design Decisions

## Context
We needed to choose an approach for the new API.

## Observations
- [decision] Use REST over GraphQL for simplicity #api
- [requirement] Must support versioning from day one
- [risk] Rate limiting needed for public endpoints

## Relations
- implements [[API Specification]]
- depends_on [[Authentication System]]

Using Special Prompts

Basic Memory includes special prompts that help you leverage your knowledge base effectively.

Continue Conversation

Resume previous topics with full context:

"Let's continue our conversation about [topic]"

What happens:

• Searches your knowledge base for relevant content
• Builds context from related documents
• Resumes with awareness of previous discussions

Recent Activity

See what you've been working on:

"What have we been discussing recently?"

What happens:

• Retrieves recently modified documents
• Summarizes main topics and points
• Offers to continue any discussions

Search

Find specific information:

"Find information about [topic]"

What happens:

• Searches across all your documents
• Summarizes key findings
• Offers to explore specific documents

Working with Memory URLs

Basic Memory uses special memory:// URLs to reference knowledge:

URL Formats

memory://title                   # Reference by title
memory://folder/title            # Reference by folder and title
memory://permalink               # Reference by permalink
memory://path/relation_type/*    # Follow all relations of type

Using Memory URLs

Reference existing knowledge in conversations:

You: "Take a look at memory://coffee-brewing-methods and let's discuss improvements"

Claude will load that specific document and any related context.

Building Knowledge Connections

Creating Relations

Use WikiLink syntax to connect knowledge:

## Relations
- implements [[Authentication System]]
- requires [[Database Schema]]
- relates_to [[Security Guidelines]]

Common Relation Types

Adding Observations

Structure facts with semantic categories:

## Observations
- [decision] We chose JWT tokens for stateless auth
- [requirement] Must support 2FA for sensitive operations
- [technique] Use bcrypt for password hashing
- [issue] Rate limiting needed for login attempts
- [fact] Average response time is 50ms
- [question] Should we support OAuth?

Multi-Project Workflows

How Projects Work

Basic Memory Cloud supports multiple projects for organizing different knowledge bases. When you start a conversation, the AI will:

1. Check your available projects
2. Suggest the most active project based on recent activity
3. Ask which project to use for this conversation
4. Remember your choice throughout the session

Example conversation:

You: "Let's work on documentation"

Claude: I see you have 3 projects: main, work-notes, personal
Your most active project is work-notes.
Should I use work-notes for this task?

You: "Yes, let's use work-notes"

Claude: I'll use the 'work-notes' project for our session.

Managing Projects in Web App

In the web app:

1. Use the Project dropdown in the upper left to switch projects
2. Click Manage Projects to create, rename, or delete projects
3. Use the more menu (...) on any project to upload files or download archives

Organizing Your Knowledge

Folder Structure

Organize notes in any structure that suits you:

main/
├── projects/          # Active project notes
│   ├── api-redesign/
│   └── mobile-app/
├── decisions/         # Decision records
├── learning/          # Research and learning notes
├── meetings/          # Meeting notes
└── archive/           # Completed/old content

Best Practices

• Use descriptive filenames
• Group related content in folders
• Include dates in time-sensitive notes (e.g., 2024-01-15 Team Standup.md)
• Archive old content regularly

Moving and Organizing

In the web app, you can drag and drop notes between folders. Or ask your AI:

You: "Move my old meeting notes to the archive folder"

Claude: [Uses move_note]
"Done! I've moved 12 meeting notes to the archive folder."

Editing Notes

In the Web App

The web app provides a live Markdown editor:

1. Click any note to open it
2. Edit directly in the editor pane
3. Changes save automatically
4. Preview renders in real-time

Through AI

Ask your AI to make changes:

You: "Add a troubleshooting section to my setup guide"

Claude: [Uses edit_note with append operation]
"I've added a troubleshooting section to the end of your setup guide."

Available operations:

• append - Add content to end
• prepend - Add content to beginning
• find_replace - Replace specific text
• replace_section - Replace entire section by heading

Directory Operations

Move or delete entire folders:

You: "Move the old-projects folder to archive"

Claude: [Uses move_note with is_directory=true]
"Moved old-projects/ → archive/old-projects/ (15 files)"

Importing Data

From Claude or ChatGPT

Import your conversation history:

1. In the web app, go to Settings → Import Data
2. Select import type (Claude or ChatGPT)
3. Choose target project and destination folder
4. Upload your export file

From Files

Upload existing markdown files:

1. In the web app, click Manage Projects
2. Click the more menu (...) on your project
3. Select Upload and choose files or folders

Snapshots and Backup

Basic Memory Cloud automatically creates daily snapshots. You can also create manual snapshots before major changes.

Creating Snapshots

In the web app or via CLI:

bm cloud snapshot create "Before reorganization"

Restoring from Snapshots

1. List available snapshots
2. Browse snapshot contents
3. Download and restore individual files as needed

See the Cloud Guide for detailed snapshot management.

Best Practices

Knowledge Creation

1. Create relations - Link related concepts with [[WikiLinks]]
2. Make observations - Structure facts with [category] syntax
3. Be descriptive - Use clear titles and rich content
4. Add context - Include background and reasoning
5. Review and refine - Edit AI-generated content for accuracy

Workflow

1. Use special prompts - "Continue conversation", "Recent activity", "Search"
2. Build incrementally - Add to existing notes rather than creating duplicates
3. Organize regularly - Move old content to archive
4. Cross-reference - Link new content to existing knowledge
5. Use projects - Separate work, personal, research

Long-term Maintenance

1. Archive old content - Keep active knowledge base focused
2. Refactor connections - Update relations as knowledge evolves
3. Regular reviews - Periodically update key documents
4. Use snapshots - Create snapshots before major reorganizations

Local Sync (Optional)

Want to edit files locally with Obsidian or VS Code? Set up bidirectional sync:

bm cloud login
bm cloud setup
bm project bisync --name main

This syncs your cloud notes to a local folder. Changes in either location sync automatically.

See the Cloud Sync Guide for detailed setup.

Troubleshooting

AI Can't Find Knowledge

1. Confirm you're connected to the correct project
2. Check that the note exists in the web app
3. Use memory:// URLs for direct references
4. Try searching with different terms

Web App Issues

1. Refresh the page
2. Check your subscription status
3. Clear browser cache if notes aren't updating
4. Try a different browser

Sync Issues

If using local sync:

1. Check sync status: bm cloud status
2. Run manual sync: bm project bisync --name main
3. Check for conflicts in the sync log

Getting Help

• Discord: discord.gg/tyvKNccgqN - #help channel
• GitHub: github.com/basicmachines-co/basic-memory/issues

Next Steps