# Basic Memory ::u-page-hero --- class: py-0 orientation: horizontal --- ![Basic Memory](https://docs.basicmemory.com/computer.png) #title AI memory that grows with you. #description Build persistent knowledge that both you and AI can read, write, and enhance together. Learn how it works. See why your AI needs Basic Memory. #links :::u-button --- color: neutral size: xl to: https://docs.basicmemory.com/start-here/what-is-basic-memory trailing-icon: i-lucide-arrow-right --- Get started ::: :::u-button --- color: neutral icon: simple-icons-github size: xl to: https://github.com/basicmachines-co/basic-memory variant: outline --- Star on GitHub ::: #headline :::u-button --- size: sm to: https://docs.basicmemory.com/whats-new/v0.22.0 variant: outline --- v0.22 → ::: :: ::u-page-section{.pt-0} :::u-page-grid ::::u-page-card --- spotlight: true class: lg:col-span-1 description: Every piece of AI context is a file you can read and edit. No mystery, no lock-in—just plain Markdown you own forever. title: See into the black box --- :::: ::::u-page-card --- spotlight: true class: lg:col-span-2 description: Unlike chat history that disappears, Basic Memory creates a semantic knowledge graph. Every note connects to related ideas, revealing patterns and insights that grow smarter over time. title: Knowledge that compounds --- :::: ::::u-page-card --- spotlight: true class: lg:col-span-2 description: Connect to Claude, ChatGPT, Gemini, Cursor, VS Code, and more via the Model Context Protocol. Your AI assistant reads your entire knowledge history instantly. title: Works with your AI assistant --- ![MCP Integration with Claude](https://docs.basicmemory.com/screenshots/claude/create-first-note.png) :::: ::::u-page-card --- spotlight: true class: lg:col-span-1 description: Write and organize notes from any browser. Search your knowledge, make connections, and watch your ideas grow—no installation required. title: Your web editor for knowledge --- :theme-image{alt="Web editor" dark="/screenshots/cloud-app/v2-edit-mode-dark.png" light="/screenshots/cloud-app/v2-edit-mode-light.png"} :::: ::::u-page-card --- class: lg:col-span-1 description: Start with Basic Memory Cloud for instant access from any browser, or run locally on your machine. Sync between them, or keep everything offline—your choice. icon: i-lucide-cloud title: Cloud or local to: https://docs.basicmemory.com/start-here/quickstart-cloud --- :::: ::::u-page-card --- class: lg:col-span-2 description: Human-readable files, not proprietary formats. Your knowledge works in Obsidian, VS Code, or any text editor. Export, backup, or migrate anytime. icon: i-lucide-file-text title: Plain Markdown --- ```markdown --- title: Project Ideas tags: [ideas, projects] --- ## Observations - [insight] AI collaboration improves over time #growth ## Relations - relates_to [[AI Tools]] - builds_on [[Past Research]] ``` :::: ::::u-page-card --- class: lg:col-span-1 description: Basic Memory is fully open source. Run locally, self-host, contribute, or just explore the code. Your knowledge, your rules. icon: i-simple-icons-github title: Open source to: https://github.com/basicmachines-co/basic-memory --- :::: ::::u-page-card --- class: lg:col-span-1 description: This documentation is optimized for AI consumption with llms.txt support and content negotiation. AI assistants can read these docs directly. icon: i-lucide-bot title: AI-friendly docs to: https://docs.basicmemory.com/reference/llms-txt --- :::: ::::u-page-card --- spotlight: true class: lg:col-span-1 description: Create your first note in under 2 minutes. Build AI memory that actually remembers. title: Ready to start? to: https://docs.basicmemory.com/start-here/quickstart-cloud --- :::: ::: :: # What is Basic Memory Basic Memory is a knowledge base that you and your AI assistant share. It stores notes as Markdown files so your work stays readable, portable, and searchable. Instead of losing valuable insights in conversation history, you build a persistent knowledge base where both you and AI can read, write, and enhance each other's work. --- :video{autoplay controls loop muted src="https://basicmemory.com/videos/explainer-video.mp4"} ## Why Basic Memory? **The problem:** AI conversations are ephemeral. You have a great discussion, make important decisions, learn something new - and then it's gone, buried in chat history. **The solution:** Basic Memory gives your AI assistant a persistent memory. Knowledge captured in one conversation is available in all future conversations. Your AI can reference past discussions, decisions, and context. **Key benefits:** - **Persistent context** - Knowledge survives across conversations - **You own your data** - Plain Markdown files you control - **Structured knowledge** - Observations and relations create a semantic graph - **Works with any AI** - Claude, ChatGPT, and other MCP-compatible assistants --- ## What it does ::card-group :::card{icon="i-lucide-file-text" title="Stores notes as Markdown"} Notes are plain files you can edit with any editor. No lock-in, no proprietary formats. ::: :::card{icon="i-lucide-link" title="Connects ideas with links"} Relations and tags turn notes into a knowledge graph that grows over time. ::: :::card{icon="i-lucide-search" title="Lets assistants search and write"} MCP tools let your assistant read, write, search, and organize notes. ::: :::card{icon="i-lucide-cloud" title="Cloud or Local"} Use the hosted cloud service or run everything locally - your choice. ::: :: --- ## How it works Basic Memory runs an MCP server that can read and write Markdown files. A SQLite index keeps search fast. Your assistant calls tools like `search_notes`, `read_note`, and `write_note` to work with your notes. ::mermaid --- code: | flowchart LR subgraph You A[AI Assistant] E[Editor] end subgraph Basic Memory M[MCP Server] I[Index] end subgraph Storage F[Markdown Files] end A <-->|MCP Tools| M E <-->|Edit| F M <-->|Read/Write| F M <-->|Query| I F -.->|Sync| I --- :: ### The workflow 1. **Capture a note** - You write or ask your assistant to write a note during a conversation. 2. **Index and connect** - The system indexes the note, extracts observations and relations, and links it to related notes. 3. **Reuse later** - In future conversations, your assistant searches and loads relevant context automatically. ### Example conversation ```bash You: "What did we decide about the authentication approach?" AI: [Searches knowledge base, finds your past notes] "Based on your notes, you decided to use JWT tokens for API authentication. The decision was made on January 15th and documented in 'Decision: API Authentication'." You: "Add a note about implementing refresh tokens" AI: [Creates a new note linked to the authentication decision] "I've created a note about refresh tokens and linked it to your authentication decision notes." ``` --- ## What a note looks like Notes are standard Markdown with optional semantic structure: ```bash --- title: API Authentication Decision tags: [security, api, auth] --- # API Authentication Decision ## Context We needed to choose an authentication approach for the new API. ## Observations - [decision] Use JWT tokens for API auth #security - [requirement] Tokens expire after 24 hours - [risk] Rate limiting needed on login endpoint #auth ## Relations - implements [[API Security Spec]] - depends_on [[User Service]] - relates_to [[Token Refresh]] ``` **Key concepts:** - **Observations** - Categorized facts: `[decision]`, `[requirement]`, `[risk]`, etc. - **Relations** - Links to other notes: `[[Other Note]]` in simple WiliLink format - **Tags** - Searchable metadata: `#security`, `#api` ::tip The headings '## Observations' and '## Relations' are only informative. Basic Memory will parse elements from any where in the Markdown. :: --- ## What the AI sees When your AI assistant searches your knowledge base, it doesn't just find text - it navigates a semantic graph of connected ideas. ### The knowledge graph Each note becomes an **entity** with structured data: ::mermaid --- code: | flowchart TD subgraph "Knowledge Graph" E1[API Authentication] E2[API Security Spec] E3[User Service] E4[Token Refresh] end subgraph "API Authentication: Facts" O1[JWT] O2[Tokens exgire] O3[Rate limiting] end E1 -->|implements| E2 E1 -->|depends_on| E3 E1 -->|relates_to| E4 E1 -->|decision| O1 E1 -->|requirement| O2 E1 -->|risk| O3 --- :: - **Entities** - Each note is an entity with a title, content, and metadata - **Observations** - Categorized facts extracted from the note (decisions, requirements, risks) - **Relations** - Typed links connecting entities (`implements`, `depends_on`, `relates_to`) ### Building context When you ask a question, the AI doesn't just return one note. It traverses the graph to build rich context: ::mermaid --- code: | flowchart LR Q[Your Question] --> S[search_notes] S --> R[Matching Notes] R --> G[Relationed Notes] R -->|Build| C[Context] C --> A[AI Response] G -->|Follow| R --- :: **The flow:** 1. **Search** - Your question triggers a search across all notes 2. **Expand** - The AI uses `build_context` to follow relations and gather connected notes 3. **Synthesize** - With the full context loaded, the AI can give a complete answer This recursive traversal means asking about "API authentication" automatically pulls in related decisions, dependencies, and connected topics - giving your AI the full picture. ### Memory URLs The AI references knowledge using `memory://` URLs: ```bash memory://api-authentication # Reference by permalink memory://api-authentication/relates_to/* # Follow all 'relates_to' links memory://folder/note-title # Reference by path ``` These stable identifiers let the AI (and you) pinpoint exactly what context to load. ::tip You don't have to understand or think about the object graph or relations. You can just ask the AI to manage it for you. :: ```bash You: "Make sure you add observations and relations to this note" AI: [Update the note with semantic information] "OK I've updated the note with observations and relations...." You: "Make sure you do this for all our other notes :)" AI: [Makes a note in its own memory to keep notes annotated with semantic information] "I'll remember that...." ``` --- ## Seeing into the black box Built-in AI memory shows you a short digest at best - not the full context the AI draws on or how it got there. Basic Memory makes all of it transparent. - **See what your AI sees** - Every piece of context is a file you can read - **Edit what your AI knows** - Modify, delete, or reorganize knowledge anytime - **Watch changes happen** - See exactly what your AI adds or updates - **Keep your memory** - Plain Markdown files you own forever - **Audit trail** - Every note has a history; you can see what was added when - **No surprises** - The AI can only know what's in your files; no hidden context - **Portable knowledge** - Plain markdown means you're never locked in; chat with one AI, bring your knowledge to the next --- ## Closing the loop AI agents work best when they can observe the results of their actions. Basic Memory creates a feedback loop where each conversation builds on the last. **How it works:** - **Cumulative intelligence** - Each conversation adds to the knowledge base, making future conversations smarter - **Human-in-the-loop refinement** - You can correct and improve AI-generated notes, and the AI learns from your edits - **Context compounds** - Unlike chat history that gets truncated, knowledge persists and connects - **Pattern recognition** - Over time, the AI can recognize patterns across your entire knowledge base ### The feedback loop ::mermaid --- code: | flowchart LR A[Conversation] --> B[AI Writes Memory] B --> C[Human Reviews/Edits] C --> D[AI Reads Context] D --> A --- :: Each cycle reinforces learning. You ask questions, the AI searches and responds, creates notes from the conversation, and you review and refine. The knowledge base grows with each iteration. ### Knowledge growth over time ::mermaid --- code: | flowchart TD subgraph "The Loop" A[Ask Question] --> B[AI Searches Memory] B --> C[AI Responds + Writes] C --> D[You Review & Refine] D --> E[Knowledge Base Grows] E --> B end --- :: ### Knowledge refinement over time Each conversation builds on previous context, creating increasingly refined understanding: ::mermaid --- code: | flowchart TD A[Conversation 1] --> B[Memory v1] B --> C[Conversation 2] C --> D[Memory v2 - refined] D --> E[Conversation 3] E --> F[Memory v3 - richer] F --> G[...] --- :: The result: your AI gets smarter about *your* work with every interaction. --- ## Where it runs ### Cloud Basic Memory Cloud provides: - **Hosted MCP endpoint** - Connect without installing anything - **Access from any device** - Use your memory from desktop, mobile, cli, multiple AIs - **Web app** - Browse and edit notes in your browser - **Local sync** - Sync your notes locally for easy management - **Snapshots** - Point-in-time backups, automaticly done daily or manual as needed ### Local The open-source local version provides: - **Full control** - Everything runs on your machine - **No account needed** - Use immediately after install - **CLI tools** - Command-line access to all features - **Offline access** - Works without internet **Both use the same Markdown format**, so you can start with one and switch to the other later. --- ## MCP Integration Basic Memory uses the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/){rel=""nofollow""} to connect with AI assistants. MCP is an open standard that lets AI assistants use external tools. **Available tools:** - `write_note` - Create or update notes - `read_note` - Read notes with context - `search_notes` - Full-text search - `edit_note` - Incremental editing - `build_context` - Load related notes - `list_memory_projects` - Manage projects - ...and many more **Compatible assistants:** - Claude Desktop - Claude Code - ChatGPT (Pro/Max) - Google Gemini - Cursor - VS Code (with MCP extension) - Codex --- ## Getting started Ready to try Basic Memory? ::card-group :::card --- icon: i-lucide-cloud title: "Quickstart: Cloud" to: https://docs.basicmemory.com/start-here/quickstart-cloud --- Connect in 2 minutes. No installation required. ::: :::card --- icon: i-lucide-hard-drive title: "Quickstart: Local" to: https://docs.basicmemory.com/start-here/quickstart-local --- Install locally and run everything on your machine. ::: :: --- ## Next steps ::card-group :::card --- icon: i-lucide-rocket title: Getting Started to: https://docs.basicmemory.com/start-here/getting-started --- Full installation guide with configuration options. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Learn the note structure with observations and relations. ::: :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- All available tools for AI assistants. ::: :: # Quickstart: Cloud Basic Memory Cloud gives you a hosted MCP endpoint and a web app. Connect your AI assistant and start writing notes in minutes - no installation required. ::mermaid --- code: | flowchart LR A[Sign Up] --> B[Connect AI] B --> C[Create Note] C --> D[View in App] --- :: --- ## 1. Create an account Sign up at [app.basicmemory.com](https://app.basicmemory.com){rel=""nofollow""}. You'll need an active subscription to use the MCP endpoint. ![Cloud signup page](https://docs.basicmemory.com/screenshots/cloud/signup.png) --- ## 2. Connect your AI assistant Use the remote MCP endpoint URL: ```bash https://cloud.basicmemory.com/mcp ``` ### For Claude Desktop ::steps ### Open Settings In Claude Desktop or Claude.ai, go to **Settings → Claude → Connectors** ![Claude Settings - Connectors](https://docs.basicmemory.com/screenshots/claude/settings-connectors.png) ### Add Custom Connector Click **Add custom connector** and enter: - **Name**: Basic Memory - **Remote MCP server URL**: `https://cloud.basicmemory.com/mcp` ![Claude - Add connector dialog](https://docs.basicmemory.com/screenshots/claude/add-connector.png) ### Authenticate Click **Connect** to start the OAuth flow. You'll be redirected to Basic Memory to authorize access. ![OAuth authorization](https://docs.basicmemory.com/screenshots/claude/oauth-connect.png) ![OAuth authorization](https://docs.basicmemory.com/screenshots/claude/oauth-authorize.png) ### Configure Tools (Optional) Click **Configure** to customize which tools are enabled. ![Claude - Configure tools](https://docs.basicmemory.com/screenshots/claude/configure-tools.png) ### Verify Setup Confirm Basic Memory appears in the tools menu (+ icon in chat). ![Claude - Tools menu](https://docs.basicmemory.com/attachments/claude-tools-menu.png) :: ### For ChatGPT ::note ChatGPT requires a **Pro or Max subscription** to use Remote MCP servers. :: ::steps ### Enable MCP Open **Settings → Beta features** and enable MCP ### Add Endpoint Add the Basic Memory endpoint URL: `https://cloud.basicmemory.com/mcp` ### Authenticate Complete the OAuth flow when prompted :: ::tip Watch the [ChatGPT setup video](https://youtube.com/watch?v=NvU0Jo38P_k){rel=""nofollow""} for a complete walkthrough. :: ### For other assistants See the [Integrations](https://docs.basicmemory.com/integrations/claude-desktop) section for setup guides for: - [Google Gemini](https://docs.basicmemory.com/integrations/gemini) - [Cursor](https://docs.basicmemory.com/integrations/cursor) - [VS Code](https://docs.basicmemory.com/integrations/vscode) - [Claude Code](https://docs.basicmemory.com/integrations/claude-code) --- ## 3. Verify the connection Ask your assistant: ```bash List my basic memory projects ``` **Expected response:** ```bash You have 1 project: - main (default) - /app/data/basic-memory - 0 notes ``` ![Claude - Project list response](https://docs.basicmemory.com/screenshots/claude/project-list-response.png) ::warning If you get an error, check the [Troubleshooting](https://docs.basicmemory.com/reference/troubleshooting) guide. :: --- ## 4. Create your first note Try this prompt: ```bash Create a note called "Getting Started" with a summary of what Basic Memory does. ``` Your assistant will use the `write_note` tool to create a Markdown file in your cloud storage. **Example conversation:** ```bash You: Create a note called "Getting Started" with a summary of what Basic Memory does. AI: I'll create a note summarizing Basic Memory for you. [Uses write_note tool] I've created "Getting Started" in your knowledge base. The note covers: - What Basic Memory is - How the knowledge format works - Key features like semantic search and relations ``` ![Claude - Creating first note](https://docs.basicmemory.com/screenshots/claude/create-first-note.png) --- ## 5. View your notes Open [app.basicmemory.com/notes](https://app.basicmemory.com/notes){rel=""nofollow""} to see your new note. ![Web app - First note](https://docs.basicmemory.com/screenshots/cloud-app/first-note.png) **What you can do in the web app:** - Browse all your notes in the folder tree - Edit notes with the live Markdown editor - Search across your knowledge base - Import existing data from Claude, ChatGPT, or files - Manage multiple projects - Create snapshots for backup --- ## What you can do now Try these prompts with your assistant: | Prompt | What it does | | ----------------------------------------- | ------------------------------------------ | | `Create a note about [topic]` | Creates a new note with semantic structure | | `What have we discussed recently?` | Shows recently modified notes | | `Find notes about [topic]` | Searches your knowledge base | | `Continue our conversation about [topic]` | Loads context from previous notes | | `Add to my notes about [topic]` | Edits an existing note | | `Show me my notes on [topic]` | Displays a formatted note | ### Example workflow ```bash You: "I've been researching coffee brewing methods. Create a note about pour-over technique." AI: [Creates note with observations and tags] --- Later --- You: "What do I know about coffee brewing?" Claude: [Searches knowledge base, finds your pour-over note] "Based on your notes, you've been exploring pour-over techniques..." You: "Add a section about water temperature to my coffee notes" Claude: [Uses edit_note to append new content] ``` --- ## Next steps ::card-group :::card --- icon: i-lucide-cloud title: Cloud Guide to: https://docs.basicmemory.com/cloud/cloud-guide --- Full cloud features including CLI tools, snapshots, and migration. ::: :::card --- icon: i-lucide-layout-panel-left title: Web App Guide to: https://docs.basicmemory.com/cloud/web-app --- Learn the web interface for browsing and editing notes. ::: :::card --- icon: i-lucide-refresh-cw title: Cloud Sync to: https://docs.basicmemory.com/cloud/cloud-sync --- Set up bidirectional sync with local files. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Learn the note structure with observations and relations. ::: :: # Quickstart: Local Local mode keeps notes on your machine and runs the MCP server locally. It's open-source and free to use. ::mermaid --- code: | flowchart LR A[Install] --> B[Configure] B --> C[Connect] C --> D[Create Notes] --- :: --- ## 1. Install Basic Memory Choose your installation method. All installs include semantic search for hybrid (keyword + meaning-based) search. ### macOS (Homebrew) - Recommended ```bash brew tap basicmachines-co/basic-memory brew trust basicmachines-co/basic-memory brew install basic-memory ``` ::note `brew trust` tells Homebrew you accept code from this third-party tap. Recent Homebrew versions warn about untrusted taps, and Homebrew 6 will require the trust step before installing or upgrading from them. On older Homebrew versions the command doesn't exist yet — just skip it. :: ### All platforms (uv) First install `uv` from [astral.sh](https://docs.astral.sh/uv/getting-started/installation/){rel=""nofollow""}, then: ```bash uv tool install basic-memory ``` ::note **Requirements:** Python 3.13 or higher. Check with `python --version` . :: ### Verify installation ```bash basic-memory --version ``` **Expected output:** ```bash basic-memory, version 0.19.x ``` --- ## 2. Configure Claude Desktop Edit your Claude Desktop config file: | Platform | Config Location | | -------- | ----------------------------------------------------------------- | | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | | Linux | `~/.config/Claude/claude_desktop_config.json` | Add this configuration: ```json { "mcpServers": { "basic-memory": { "command": "uvx", "args": ["basic-memory", "mcp"] } } } ``` ::warning **ENOENT error?** Use the full path to uvx. Find it with `which uvx` and replace `"uvx"` with the full path (e.g., `"/Users/yourname/.local/bin/uvx"` ). :: **Restart Claude Desktop** after editing the config. --- ## 3. Verify the connection In Claude Desktop, click the **tools icon** (hammer) in the bottom-right of the chat interface. You should see Basic Memory tools listed. ![Claude - Tools menu with Basic Memory](https://docs.basicmemory.com/screenshots/claude/tools-menu-local.png) Ask Claude: ```bash List my projects ``` **Expected response:** ```bash You have 1 project: - main (default) - ~/basic-memory - 0 notes ``` ![Claude - Project list](https://docs.basicmemory.com/screenshots/claude/project-list-response.png) --- ## 4. Create your first note Try this prompt: ```bash Create a note called "Getting Started" with a summary of what Basic Memory does. ``` Claude will create a Markdown file at `~/basic-memory/Getting Started.md`. **Example conversation:** ```bash You: Create a note called "Getting Started" with a summary of what Basic Memory does. Claude: I'll create a note for you. [Uses write_note tool] Done! I've created "Getting Started.md" in your basic-memory folder. It includes an overview of Basic Memory's key features: - Knowledge storage in Markdown - Semantic observations and relations - Search across your knowledge base ``` ![Claude - Creating first note](https://docs.basicmemory.com/screenshots/claude/create-first-note.png) --- ## 5. View your notes Your notes are stored at `~/basic-memory` by default. You can: ### Open in any text editor ```bash # View in terminal cat ~/basic-memory/Getting\ Started.md # Open folder open ~/basic-memory # macOS explorer ~/basic-memory # Windows ``` ### Use Obsidian for visual navigation 1. Open Obsidian 2. **Create new vault** → select `~/basic-memory` 3. Use the **graph view** to see connections between notes ### Example note structure After creating a few notes, your folder might look like: ```bash ~/basic-memory/ ├── Getting Started.md ├── projects/ │ └── API Design.md ├── research/ │ └── Database Optimization.md └── meetings/ └── Team Standup 2024-01-15.md ``` --- ## What you can do now Try these prompts with Claude: | Prompt | What it does | | ----------------------------------------- | --------------------------------- | | `Create a note about [topic]` | Creates a new Markdown file | | `What have we discussed recently?` | Shows recently modified notes | | `Find notes about [topic]` | Searches your knowledge base | | `Continue our conversation about [topic]` | Loads context from previous notes | | `Add to my [topic] notes` | Edits an existing note | | `Move my [note] to the archive folder` | Reorganizes files | ### Example workflow ```bash You: "Let's document our API design decisions" Claude: I'll create a note for the API design decisions. [Creates ~/basic-memory/API Design Decisions.md] --- Later --- You: "What did we decide about authentication?" Claude: [Searches knowledge base] "Based on your 'API Design Decisions' note, you decided to use JWT tokens..." You: "Add a section about rate limiting" Claude: [Uses edit_note to append] "I've added a rate limiting section to your API design notes." ``` --- ## Customize your setup ### Change where notes are saved ```bash # Create a new project in a different location basic-memory project add "my-notes" ~/Documents/notes # Make it the default basic-memory project default "my-notes" ``` Restart Claude Desktop for changes to take effect. ### Skip project selection prompts If you only use one project, add to `~/.basic-memory/config.json`: ```json { "default_project": "main" } ``` --- ## Useful CLI commands ```bash # Check sync status basic-memory status # List all projects basic-memory project list # View project statistics basic-memory project info # Import Claude conversations basic-memory import claude conversations # Import ChatGPT conversations basic-memory import chatgpt # Force re-sync all files basic-memory sync ``` --- ## Troubleshooting ### ENOENT error Claude Desktop can't find `uvx`. Use the full path: ```bash # Find the path which uvx # Output: /Users/yourname/.local/bin/uvx # Update config to use full path { "mcpServers": { "basic-memory": { "command": "/Users/yourname/.local/bin/uvx", "args": ["basic-memory", "mcp"] } } } ``` ### No tools showing 1. Verify installation: `basic-memory --version` 2. Check the config file syntax (valid JSON) 3. Restart Claude Desktop completely ### Permission errors ```bash # Fix permissions on the notes folder chmod -R u+rw ~/basic-memory ``` See the full [Troubleshooting](https://docs.basicmemory.com/reference/troubleshooting) guide for more solutions. --- ## Next steps ::card-group :::card --- icon: i-lucide-terminal title: CLI Basics to: https://docs.basicmemory.com/local/cli-basics --- Learn the command line tools for managing your knowledge. ::: :::card --- icon: i-lucide-settings title: Configuration to: https://docs.basicmemory.com/reference/configuration --- All configuration options and environment variables. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Learn the note structure with observations and relations. ::: :::card --- icon: i-lucide-hexagon title: Obsidian Integration to: https://docs.basicmemory.com/integrations/obsidian --- Visual knowledge navigation with graph view. ::: :: # Getting Started Ready to set up Basic Memory? Start with the quickstart guides: ::card-group :::card --- icon: i-lucide-cloud title: "Quickstart: Cloud" to: https://docs.basicmemory.com/start-here/quickstart-cloud --- Connect in 2 minutes. No installation required. ::: :::card --- icon: i-lucide-hard-drive title: "Quickstart: Local" to: https://docs.basicmemory.com/start-here/quickstart-local --- Install locally and run everything on your machine. ::: :: --- ## Choosing Where Notes Are Saved By default, Basic Memory saves notes in a project called `main` in `~/basic-memory`. To save notes elsewhere: ### Use Your Existing Notes Folder Ask your AI assistant directly: ```bash Create a new project called "my project" in the "/Users/yourname/Documents/Notes" directory ``` Then: ```bash Set the default project to "my project" ``` Or use the command line: ```bash # Point Basic Memory to your existing notes folder basic-memory project add "my project" # Make it your default location basic-memory project default "my project" ``` ::warning If you change default projects from the command line, new notes will be saved in your chosen folder after restarting Claude Desktop. :: **Want to use Obsidian?** Just open your folder location as a vault. See the [Obsidian Integration](https://docs.basicmemory.com/integrations/obsidian) guide. ::note **Advanced configuration** : Basic Memory stores its settings in `~/.basic-memory/config.json` . While CLI commands are recommended for configuration, you can edit this file directly. Changes require restarting Claude Desktop. :: --- ## Multi-Project Setup Basic Memory supports multiple projects for organizing different knowledge bases (work, personal, research, etc.). **How it works:** 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:** ```bash 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" ``` **Creating projects:** ```bash # Command line basic-memory project add "work-notes" ~/Documents/work # Or ask your AI assistant You: "Create a new project called 'work-notes' in ~/Documents/work" ``` **For users who primarily work in one project:** Set a default fallback project in `~/.basic-memory/config.json`: ```json { "default_project": "main" } ``` With this set, the AI uses your default project when no project is specified. --- ## Staying Updated To update Basic Memory when new versions are released: ```bash # Update with uv uv tool upgrade basic-memory # Or Homebrew brew upgrade basic-memory ``` ::note After updating, restart Claude Desktop for changes to take effect. :: --- ## Next Steps ::card-group :::card --- icon: i-lucide-book-open title: User Guide to: https://docs.basicmemory.com/local/user-guide --- Comprehensive usage instructions for daily workflows. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Learn how knowledge is structured with semantic patterns. ::: :::card --- icon: i-lucide-terminal title: CLI Reference to: https://docs.basicmemory.com/reference/cli-reference --- Complete command line tools reference. ::: :::card --- icon: i-lucide-wrench title: Troubleshooting to: https://docs.basicmemory.com/reference/troubleshooting --- Common issues and solutions. ::: :::card --- icon: i-lucide-shield-check title: Schema System to: https://docs.basicmemory.com/concepts/schema-system --- Define and validate note structure with schemas. ::: :::card --- icon: i-lucide-search title: Semantic Search to: https://docs.basicmemory.com/concepts/semantic-search --- Search by meaning with vector and hybrid modes. ::: :: # Why Basic Memory Every AI tool is adding memory. Claude builds a memory summary from your chats, and Claude Code has CLAUDE.md and auto memory. ChatGPT remembers facts about you. Obsidian users have been doing this with markdown for years. And a new wave of startups is building memory-as-a-service on top of databases. So why Basic Memory? Because none of these solve the whole problem. They each handle a piece of it, but they leave gaps that matter more as your knowledge grows. --- ## The three alternatives ### 1. Built-in AI memory Claude, ChatGPT, Cursor, and others now ship with some form of memory. Claude builds an editable memory summary from your chat history, with a separate memory for each Project. Claude Code has CLAUDE.md files and auto memory. ChatGPT has saved memories and reference chat history. These are useful for quick preferences and recurring context — "I use TypeScript," "I'm vegetarian," "use 2-space indentation." **Where it falls short:** - **Capacity-limited.** ChatGPT's saved memories top out around 1,200–1,400 words total — once full, nothing new is saved until you delete entries. Claude keeps one rolling summary per account (plus one per Project). Claude Code's auto memory index caps at 200 lines. None of them can hold a detailed architecture decision, a meeting summary, or a research synthesis. - **Siloed.** Claude's memory only works in Claude. ChatGPT's only works in ChatGPT. Each one also learns only from its own conversations — it can't ingest your docs, repos, or existing notes. If you use more than one AI tool, your knowledge is fragmented. A decision captured in Claude Code isn't available when you switch to Cursor or ChatGPT. - **Search stops at chat history.** Claude can search past conversations and ChatGPT can reference chat history, but there's no semantic search over structured knowledge, no knowledge graph, no way to ask "find everything related to our authentication approach" and get structured results. - **Not yours to keep.** Your memories live in your account on that platform — they're not portable files. If the platform changes its terms, shuts down, or you switch tools, your memories don't come with you. Basic Memory works alongside built-in memory — it doesn't replace it. Use built-in memory for preferences. Use Basic Memory for everything deeper. See [Basic Memory vs Built-in AI Memory](https://docs.basicmemory.com/concepts/vs-built-in-memory) for the detailed comparison. --- ### 2. Obsidian Obsidian is excellent — and it's the approach closest to Basic Memory's philosophy. Plain markdown files, wiki links, graph view, local-first. With the recent addition of headless mode and CLI commands, Obsidian can even be integrated with AI tools through skills and automation. If you're already an Obsidian user, you're halfway to Basic Memory's worldview. The question is what you get by adding Basic Memory on top. **What Basic Memory adds to the Obsidian experience:** - **Semantic search.** Obsidian's search finds exact text matches. Basic Memory finds notes about "error handling" when you wrote "exception management" — it searches by meaning, not just keywords. Hybrid search combines vector similarity with text matching for the best of both. - **A semantic knowledge graph.** Basic Memory parses observations and relations from your notes to build a typed knowledge graph. You can ask "what depends on this decision?" and traverse connections across your entire knowledge base — not just follow backlinks, but navigate structured relationships. - **Schemas.** Define what a meeting note or decision record should contain. The AI validates notes against schemas automatically, keeping your knowledge base consistent as it grows. - **Cloud access.** Your knowledge is available from any device, with any AI tool. Basic Memory Cloud means your notes aren't stuck on one machine — use them from Claude Desktop at work, ChatGPT on your phone, or Cursor on your laptop. - **Cross-tool portability.** Notes created in Claude Code are searchable in ChatGPT, editable in Cursor, and visible in Obsidian. One knowledge base, every AI tool you use. The best part: you don't have to choose. [Obsidian is a great companion](https://docs.basicmemory.com/integrations/obsidian) for Basic Memory. Point both at the same folder and you get Obsidian's graph view and rich editing, plus AI-powered semantic search, schemas, and cloud access on top. --- ### 3. Database-only memory services A growing number of startups offer AI memory as a service — Mem0, Letta, Supermemory, and others. They store memories in databases behind APIs, often with vector search and cloud infrastructure. **Where it falls short:** - **You can't read what the AI knows.** Your knowledge lives in a database you access through an API. You can't open a file, read what's there, fix a mistake, or reorganize your notes. The AI's understanding of you is opaque. - **You can't edit it naturally.** Want to refine a decision the AI captured? You need to go through the API or a dashboard. You can't just open a markdown file in your editor and fix it. - **Vendor lock-in.** Your knowledge is in a proprietary format in someone else's database. If the service shuts down, changes pricing, or pivots, migrating is painful — if it's possible at all. - **Not built for humans.** These tools treat memory as something the AI manages *about* you. Basic Memory treats knowledge as something you and your AI build *together*. You're a participant, not a subject. Plain text files from 1975 are still readable today. Can you say that about any proprietary database format? --- ## What makes Basic Memory different Basic Memory takes a different position from all three alternatives: **Your memory is a file you can read.** Not a database entry you can't see. Not a single sentence in a settings page. A full markdown note with observations, relations, and tags — readable in any editor, trackable with git, portable forever. **Your AI is a collaborator, not a recorder.** Both you and your AI read and write the same files. You capture rough notes, the AI structures them. The AI writes a summary, you refine it. Knowledge flows in both directions. **It works across every AI tool.** Notes created in Claude Code are available in ChatGPT, Cursor, Gemini, or any MCP-compatible tool. One knowledge base, many interfaces. **Search finds meaning, not just keywords.** Semantic search finds notes about "login security" even when you wrote "authentication hardening." Combined with text search, metadata filtering, and knowledge graph traversal, you can find anything in your knowledge base. **Structure grows with you.** Start with simple notes. Add observations and relations when they're useful. Define schemas when you want consistency. The system meets you where you are. --- ## The best of all worlds You don't have to choose one approach. The strongest setup combines them: - **Built-in memory** for quick preferences your AI tool handles automatically - **Basic Memory** for structured knowledge, decisions, research, and context - **Obsidian** for visual graph exploration and rich editing alongside Basic Memory - **Git** for version history on your knowledge base Basic Memory is the connective layer that makes your knowledge available everywhere, searchable by meaning, and yours to keep. --- ## Get started ::card-group :::card --- icon: i-lucide-cloud title: "Quickstart: Cloud" to: https://docs.basicmemory.com/start-here/quickstart-cloud --- Connect in 2 minutes, no install needed. ::: :::card --- icon: i-lucide-hard-drive title: "Quickstart: Local" to: https://docs.basicmemory.com/start-here/quickstart-local --- Run everything on your machine. ::: :::card --- icon: i-lucide-layers title: Basic Memory vs Built-in AI Memory to: https://docs.basicmemory.com/concepts/vs-built-in-memory --- Detailed comparison with Claude, ChatGPT, and Cursor memory. ::: :::card --- icon: i-lucide-book-open title: What is Basic Memory to: https://docs.basicmemory.com/start-here/what-is-basic-memory --- How it works under the hood. ::: :: # Basic Memory Teams **Basic Memory Teams** brings your whole team into one shared knowledge base. Invite teammates into a shared cloud workspace, work from the same projects, and your AI assistant reaches those shared projects automatically. Teams adds a **team workspace alongside your personal one** — your own notes and projects stay where they are, and you switch between workspaces in the app whenever you want. ::note{icon="i-lucide-users"} Teams is a cloud feature and requires a subscription with one or more seats. Billing is per seat. Your personal cloud workspace (and any local projects) keep working alongside it. :: ## What you get - **Three workspaces, side by side** — local, personal cloud, and your team's shared workspace. Switch between them in the app, or target one explicitly from the CLI and MCP. - **A shared workspace for the team** — projects everyone on the team can read and write. - **Roles** — assign **owner**, **editor**, or **viewer** to control what each member can do. - **Email invitations** — invite teammates by email; a seat is only used once they accept. - **One source of truth for your AI** — your assistant discovers team projects across every workspace you can access, with no extra setup. ## Invite your team Owners invite members from **Settings → Teams**. Each member signs in with the invited email, picks up their role, and starts working in the shared projects right away. Promote, demote, deactivate, or hand off ownership at any time. ## Get started ::card-group :::card --- icon: i-lucide-users title: Teams Guide to: https://docs.basicmemory.com/teams/about --- Roles, invitations, seats, and project sharing — the full walkthrough. ::: :::card --- icon: i-lucide-layout-panel-left title: Web App to: https://docs.basicmemory.com/cloud/web-app --- Browse, edit, and collaborate on notes in the browser. ::: :::card --- icon: i-lucide-megaphone title: What's New in v0.22.0 to: https://docs.basicmemory.com/whats-new/v0.22.0 --- Team-safe cloud push and pull. ::: :: # v0.22.0 v0.22.0 makes cloud sync safe for teams. New **`bm cloud push`** and **`bm cloud pull`** commands transfer changes additively — they never delete files on the destination — so you can collaborate on a shared Team workspace without risking a teammate's work. The release also brings search improvements, more capable `bm tool` and `bm status` commands, and a long list of MCP tool and embedding reliability fixes. --- ## v0.22.1 patch A follow-up patch to v0.22.0 focused on first-run reliability: - **Fresh installs no longer get stuck** when the projects table is empty — Basic Memory now routes you to project setup and promotes your first project to the default automatically. - **Sync skips projects without a valid local path** and ignores stale projects left in the database but missing from your config. - **MCP qualified project routes** resolve workspace display names and tenant ids correctly. - **`search_notes`** comma-splits `note_types`, `entity_types`, and `categories`, matching how tags already behave. - **`write_note`** gains a `workspace` parameter for parity with `edit_note`. - **Faster CLI startup** — heavy imports are deferred out of the command path. Full details in the [changelog](https://docs.basicmemory.com/whats-new/changelog). --- ## Team-Safe Push and Pull `push` and `pull` model `git push` / `git pull`: additive, conflict-aware transfers that work on both Personal and Team workspaces. ```bash # Fetch cloud changes into your local directory bm cloud pull --name research # Upload your local changes to the cloud bm cloud push --name research # Preview either direction first bm cloud pull --name research --dry-run ``` If a file differs on both sides, the command aborts and lists the conflicts — like a rejected `git push`. Re-run with `--on-conflict` to choose what survives: | Value | Behavior | | ---------------- | -------------------------------- | | `fail` (default) | Abort and list conflicting files | | `keep-cloud` | Take the cloud version | | `keep-local` | Keep the local version | | `keep-both` | Keep both, renaming one copy | Each Team workspace gets its own scoped rclone remote, so credentials and sync state stay isolated per workspace. ### Mirror commands are now Personal-only `bm cloud sync` and `bm cloud bisync` are mirror operations — one side becomes authoritative and missing files get deleted on the other. That's correct for a Personal workspace with a single writer, but unsafe on a shared Team bucket. On Team workspaces these commands now exit early with a clear error and point you at `push`/`pull` instead. See the [Cloud Sync guide](https://docs.basicmemory.com/cloud/cloud-sync) for details. --- ## Search Improvements - **Observation category filter** — narrow search results to specific observation categories like `[decision]` or `[fact]`. - **Comma-separated tags just work** — `tags="alpha,beta"` and the `tag:alpha,beta` shorthand now split and match consistently everywhere. - **`note_types` filter is case-insensitive**, so `Task` and `task` find the same notes. --- ## CLI Improvements - **`bm status --wait --timeout 60`** — block until sync completes, handy for scripting. - **`bm tool write-note --type`** — set the note type at creation time. - **`bm tool delete-note`** — delete notes from the command line. - **`bm tool` commands align with MCP behavior** — consistent error exit codes, overwrite handling, and defaults across the CLI wrappers and the MCP tools they mirror. --- ## Experimental: LiteLLM Embeddings Semantic search can now use a [LiteLLM](https://github.com/BerriAI/litellm){rel=""nofollow""}-backed embedding provider, opening the door to hosted embedding models beyond the built-in FastEmbed. This is experimental — expect the configuration surface to evolve. Embedding reliability also improved across the board: FastEmbed vectors are L2-normalized for correct similarity scoring with custom models, corrupt model caches self-heal, and a single embedding provider is reused per process. --- ## Reliability Fixes A large round of MCP tool fixes: - `build_context` resolves observations by the same permalink the search index uses, and truncated observation permalinks no longer collide. - `edit_note` recovers when a file exists on disk but isn't indexed yet. - `move_note` resolves `memory://` URLs, no longer falsely rejects same-project moves, and no longer reports false success across project boundaries. - `read_note` accepts `page`/`page_size` like its sibling tools. - `recent_activity` shows the correct project, and navigation pagination is validated. - `bm cloud setup` no longer overwrites an existing rclone remote. --- ## Upgrading No breaking changes. Upgrade as usual: ```bash uv tool upgrade basic-memory # or brew upgrade basic-memory ``` Full details in the [changelog](https://docs.basicmemory.com/whats-new/changelog). # Hermes Plugin The [hermes-basic-memory](https://github.com/basicmachines-co/hermes-basic-memory){rel=""nofollow""} plugin gives [Hermes Agent](https://github.com/NousResearch/hermes-agent){rel=""nofollow""} a persistent knowledge graph across sessions. [Basic Memory](https://docs.basicmemory.com/start-here/what-is-basic-memory) is a knowledge base that you and your AI share. Hermes ships with no external memory provider by default — this plugin replaces that with a real graph your agent reads from and writes to as plain Markdown. ::tip **[Read the full Hermes Plugin guide →](https://docs.basicmemory.com/integrations/hermes)** — installation, configuration, the complete tool reference, slash commands, and the slash-command patch. :: ## Key Capabilities - **Search before answering** — The agent recalls prior decisions and context before responding, instead of starting cold - **Automatic capture** — Every exchange is logged to a session transcript; an end-of-session summary is written and linked back - **10 agent tools** — search, read, write, edit, context, delete, move, recent, projects, workspaces - **8 slash commands** — `/bm-search`, `/bm-read`, `/bm-context`, `/bm-recent`, `/bm-status`, `/bm-remember`, `/bm-project`, `/bm-workspace` - **Cross-project & workspace routing** — Read or write any project per call via `project` / `project_id`, with transparent local/cloud routing - **Bundled skill** — A `basic-memory` skill teaching the note format, routing, and a worked discovery → write → verify recipe ## Quick Install ```bash hermes plugins install basicmachines-co/hermes-basic-memory ``` Activate it in `~/.hermes/config.yaml`: ```yaml memory: provider: basic-memory ``` Restart the gateway (`hermes gateway restart`) and verify with `hermes memory status`. ::note The agent tools and auto-capture work out of the box. The native `/bm-*` slash commands need a Hermes Agent-side patch on releases through `v0.14.0` / `v2026.5.16` — see the warning in the full guide. :: ## Next Steps ::card-group :::card --- icon: i-lucide-puzzle title: Hermes Plugin Guide to: https://docs.basicmemory.com/integrations/hermes --- Full guide with configuration, tool reference, slash commands, and the slash-command patch. ::: :::card --- icon: i-lucide-github title: GitHub Repository to: https://github.com/basicmachines-co/hermes-basic-memory --- Source code, issues, and contributing guide. ::: :: # Basic Memory Cloud Work with your knowledge base across multiple devices using cloud sync and storage. ## A redesigned web app The Basic Memory web app has been rebuilt around a fast, three-pane layout (sidebar, note list, note detail) where notes open ready to edit. - **Three editing modes** — a **Rich editor** for WYSIWYG writing, a **Source mode** for plain Markdown and frontmatter, and a **Preview** with clickable wiki links. - **See all your Projects at once** - see all your projects at once in the **Projects** list. - **Share notes** — create a public, read-only link for any saved note. - **Keyboard-first** — a command palette (Cmd/Ctrl + K) and shortcuts for everything. - **Live updates** — see changes made by your agent in real time, and save your own changes instantly. For the full walkthrough, see the [Web App Guide](https://docs.basicmemory.com/cloud/web-app). ## Teams You can now share a cloud workspace with your team. Invite members by email, assign roles (owner, editor, viewer), and collaborate on the same projects — your AI assistant reaches team projects automatically across workspaces. See the [Teams guide](https://docs.basicmemory.com/teams/about) to get started. ## Shared Notes Publish any saved note as a public, read-only link — anyone with the link can read it without an account. Create a link from a note's **Share note** action, then manage all your links from **Settings → Shared Notes**. Available in every cloud workspace, personal and team. See [Shared Notes](https://docs.basicmemory.com/cloud/shared-notes) for details. ## Snapshots Basic Memory Cloud includes point-in-time snapshots for backup and recovery. Create manual snapshots before major changes, or rely on automatic daily backups — from **Settings → Snapshots** or the CLI. See [Cloud Snapshots](https://docs.basicmemory.com/cloud/cloud-snapshots). ## File History Every saved version of a note is preserved automatically in Basic Memory Cloud. Open **File history** on any note to see its full timeline, compare an earlier version side-by-side with the current one, and apply changes back into the live note. It's the fast, per-note answer to "I want to undo something" — distinct from [Snapshots](https://docs.basicmemory.com/cloud/cloud-snapshots), which are project-wide point-in-time backups. ## Next Steps ::card-group :::card --- icon: i-lucide-layout-panel-left title: Web App to: https://docs.basicmemory.com/cloud/web-app --- Browse, edit, and collaborate on notes in the browser. ::: :::card --- icon: i-lucide-users title: Teams to: https://docs.basicmemory.com/teams/about --- Share a workspace and collaborate with your team. ::: :::card --- icon: i-lucide-cloud title: Cloud Guide to: https://docs.basicmemory.com/cloud/cloud-guide --- Get started with Basic Memory Cloud. ::: :: # Basic Memory All notable changes to [Basic Memory](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""}. ::github-releases{:limit='30' repo="basicmachines-co/basic-memory"} :: # Agent Skills AI assistants are powerful, but they don't automatically know the best way to organize your notes. Agent skills are ready-made instructions that teach your AI how to write well-structured notes, track tasks, and more. [Basic Memory](https://docs.basicmemory.com/start-here/what-is-basic-memory) is a knowledge base that you and your AI share. Skills make the AI better at using it — so your notes are more consistent, your tasks are tracked reliably, and your conversations produce lasting value. ## Available Skills | Skill | What it does for you | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **memory-notes** | Your AI writes well-structured notes automatically — with consistent formatting, links between notes, and proper metadata | | **memory-tasks** | Track tasks in notes that survive across conversations — your AI picks up where you left off | | **memory-schema** | Your AI learns your note patterns and helps keep them consistent over time | | **memory-reflect** | Your AI reviews conversations and saves the important parts as notes | | **memory-defrag** | Split bloated files, merge duplicates, and reorganize your notes | | **memory-lifecycle** | Move notes through stages (draft → active → archive) using folders | | **memory-metadata-search** | Your AI searches notes by properties like status, tags, and custom fields | | **memory-ingest** | Process transcripts, emails, and documents into structured notes | | **memory-research** | Your AI researches topics on the web and saves findings as notes | ## Quick Install ```bash npx skills add basicmachines-co/basic-memory-skills ``` Or install a single skill: ```bash npx skills add basicmachines-co/basic-memory-skills --skill memory-tasks ``` Works with Claude Desktop, Claude Code, Cursor, Windsurf, and other AI tools that support markdown-based skill files. ## Next Steps ::card-group :::card --- icon: i-lucide-sparkles title: Agent Skills Guide to: https://docs.basicmemory.com/integrations/skills --- Full guide with installation options, skill details, and recommended combinations. ::: :::card --- icon: i-lucide-github title: GitHub Repository to: https://github.com/basicmachines-co/basic-memory-skills --- Source code, contributing guide, and issue tracker. ::: :: # OpenClaw Plugin The [openclaw-basic-memory](https://github.com/basicmachines-co/openclaw-basic-memory){rel=""nofollow""} plugin gives your OpenClaw agent a persistent memory across sessions — zero configuration required. [Basic Memory](https://docs.basicmemory.com/start-here/what-is-basic-memory) is a knowledge base that you and your AI share. This plugin connects it to OpenClaw so your agent remembers past conversations, decisions, and context. ::tip **[Read the full OpenClaw Plugin guide →](https://docs.basicmemory.com/integrations/openclaw)** — configuration options, the complete tool reference, slash commands, and bundled skills. :: ## Key Capabilities - **Search across everything** — Searches your notes, knowledge graph, and active tasks at once - **Automatically saves conversation highlights** — Records important conversation turns as daily notes - **Loads your recent work at startup** — Active tasks and recent notes are ready when you begin a new session - **14 agent tools** — Full Basic Memory toolset including search, read, write, edit, schema, and project management - **7 slash commands** — `/remember`, `/recall`, `/tasks`, `/reflect`, `/defrag`, `/schema`, `/bm-setup` - **6 bundled skills** — memory-notes, memory-tasks, memory-schema, memory-reflect, memory-defrag, memory-metadata-search - **Multi-project & cloud routing** — Access every project in your knowledge base with transparent local/cloud routing ## Quick Install ```bash openclaw plugins install @basicmemory/openclaw-basic-memory openclaw gateway restart ``` Works out of the box with zero configuration. ## Next Steps ::card-group :::card --- icon: i-lucide-puzzle title: OpenClaw Plugin Guide to: https://docs.basicmemory.com/integrations/openclaw --- Full guide with configuration options, tool reference, and slash commands. ::: :::card --- icon: i-lucide-github title: GitHub Repository to: https://github.com/basicmachines-co/openclaw-basic-memory --- Source code, issues, and contributing guide. ::: :: # AI-Friendly Documentation ::tip This documentation site supports the [llms.txt specification](https://llmstxt.org/){rel=""nofollow""} — AI agents can fetch clean markdown directly, no HTML parsing required. See the full reference at [Reference → AI-Friendly Documentation](https://docs.basicmemory.com/reference/llms-txt) . :: Ask your AI to read the docs and it just works: ```text Fetch https://docs.basicmemory.com/llms.txt and read the Basic Memory documentation ``` ## Access Methods | Method | URL | What you get | | ----------------------- | ---------------------------------- | -------------------------------------------- | | **Index** | `/llms.txt` | List of all pages with direct markdown links | | **Full docs** | `/llms-full.txt` | Complete documentation in one file | | **Raw markdown** | `/raw/.md` | Any single page as markdown | | **Content negotiation** | Any page + `Accept: text/markdown` | Returns markdown instead of HTML | ## Quick Examples ```bash # Get the full docs index curl https://docs.basicmemory.com/llms.txt # Fetch a specific page as markdown curl https://docs.basicmemory.com/raw/start-here/what-is-basic-memory.md # Content negotiation — same URL, markdown response curl -H "Accept: text/markdown" https://docs.basicmemory.com/start-here/what-is-basic-memory ``` ## Next Steps ::card-group :::card --- icon: i-lucide-bot title: AI-Friendly Docs Reference to: https://docs.basicmemory.com/reference/llms-txt --- Full reference with usage patterns and code examples. ::: :::card --- icon: i-lucide-external-link title: llms.txt Specification to: https://llmstxt.org/ --- The open standard for AI-friendly documentation. ::: :: # Basic Memory Cloud Basic Memory Cloud provides hosted MCP access with no local installation required. Bring your knowledge to the cloud - all your existing notes, connections, and context accessible from anywhere. ::note{icon="i-lucide-cloud"} **Why use Basic Memory Cloud?** - Access from any device - Easily import your data - 2-minute setup - Local sync optional - OAuth authentication :: --- ## Setup with Claude Basic Memory Cloud uses Remote MCP to connect to AI assistants. The connection URL is: ```text https://cloud.basicmemory.com/mcp ``` ::steps ### Open Claude Settings In Claude Web or Desktop, go to **Settings → Claude → Connectors** ### Add Custom Connector Click **Add custom connector** and enter: - **Name**: Basic Memory - **Remote MCP server URL**: `https://cloud.basicmemory.com/mcp` Click **Add** ### Authenticate Click **Connect** to authenticate and grant permissions to Claude. This opens an OAuth flow to authorize Claude to access your Basic Memory Cloud account. ### Configure Tools (Optional) Click **Configure** to customize which tools are enabled. You can enable or disable specific tools and configure permissions. ### Verify Setup Confirm Basic Memory is available in the "search and tools" menu for a chat. All your notes will be saved to your cloud instance. :: ::tip For detailed Claude setup instructions, see the [Claude Desktop Integration](https://docs.basicmemory.com/integrations/claude-desktop) guide. :: --- ## Setup with ChatGPT ::note ChatGPT requires a **Pro or Max subscription** to use Remote MCP servers. :: For detailed ChatGPT setup instructions, see the [ChatGPT Integration](https://docs.basicmemory.com/integrations/chatgpt) guide. --- ## Web App Browse, edit, and collaborate on your cloud notes directly in your browser at [app.basicmemory.com](https://app.basicmemory.com){rel=""nofollow""}. **Key features:** - **Edit notes** - A rich editor, plain Markdown source mode, and a read-only preview with clickable wiki links - **Collaborate with AI** - Connect an agent and watch it write alongside you in the same note - **Import conversations** - Import ChatGPT, Claude, or JSON data - **Manage projects** - Create, switch between, and manage projects - **Upload files** - Bulk upload markdown files and directories - **Download archives** - Export projects as zip files for backup ::tip For the complete web app guide including editing modes, drafts, AI collaboration, importing, and project management, see the [Web App Guide](https://docs.basicmemory.com/cloud/web-app) . :: --- ## Command Line Tools The CLI tools are **optional** but enable advanced features like project management, file upload, and bidirectional sync. **Requirements**: Basic Memory CLI v0.16.0 or later. See [Getting Started](https://docs.basicmemory.com/start-here/getting-started) for installation. ::note{icon="i-lucide-info"} **Why use the CLI?** - Manage multiple projects from terminal - Upload entire folders to cloud - Set up bidirectional sync with local files - Automate workflows with scripts :: ### Quick Start ```bash # 1. Authenticate bm cloud login # 2. Check Status bm cloud status # 3. List Projects bm project list ``` ### Authentication Basic Memory uses JWT-based cloud authentication with OAuth 2.1 and automatic subscription validation. #### Login to Cloud ```bash bm cloud login ``` **What happens:** 1. Opens browser to OAuth authorization page 2. Handles PKCE challenge/response automatically 3. Validates active subscription status 4. Stores JWT token in `~/.basic-memory/basic-memory-cloud.json` 5. Token automatically refreshed when needed A confirmation code will be displayed in both the browser and terminal. Confirm the codes match and press the **Confirm** button on the web page. After login: ```text ✅ Successfully authenticated with Basic Memory Cloud! Verifying subscription access... ✓ Cloud mode enabled CLI commands use cloud routing unless a project is explicitly set to local mode ✓ Tokens saved to ~/.basic-memory/basic-memory-cloud.json ``` ### Per-project Cloud Routing You can route specific projects through cloud while keeping others local: ```bash # Save or create an API key bm cloud api-key save bmc_... bm cloud api-key create "my-laptop" # Route one project through cloud bm project set-cloud research # Revert to local for that project bm project set-local research ``` ::tip For the full routing model — including priority levels, hybrid setups, and common configurations — see [Local & Cloud Routing](https://docs.basicmemory.com/cloud/routing) . :: **If no subscription:** ```text Active subscription required Subscribe at: https://basicmemory.com/subscribe ``` #### Check Status ```bash bm cloud status ``` Shows: authentication status, subscription status, last sync time, cloud project count, tenant information, and sync directory configuration. #### Logout ```bash bm cloud logout ``` Removes `~/.basic-memory/basic-memory-cloud.json` and clears cached credentials. ### Project Management ```bash # Create a new cloud project bm project add my-new-project # Create and set as default bm project add my-new-project --default # List all cloud projects bm project list ``` Example output: ```text Basic Memory Projects ┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓ ┃ Name ┃ Path ┃ Default ┃ ┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩ │ main │ /app/data/basic-memory │ ✓ │ └──────┴────────────────────────┴─────────┘ ``` ::tip For more project management commands, see `bm project --help` or the [CLI Reference](https://docs.basicmemory.com/reference/cli-reference) . :: --- ## Upload Files to Cloud Upload local files or directories to cloud projects using `bm cloud upload`: ```bash # Upload a directory to existing project bm cloud upload ~/my-notes --project research # Upload a single file bm cloud upload important-doc.md --project research # Upload and create project in one step bm cloud upload ~/local-project --project new-research --create-project # Upload without triggering sync bm cloud upload ~/bulk-data --project archives --no-sync ``` **File Filtering:** The upload command respects `.bmignore` and `.gitignore` patterns, automatically excluding: - Hidden files (`.git`, `.DS_Store`) - Build artifacts (`node_modules`, `__pycache__`) - Database files (`*.db`, `*.db-wal`) - Environment files (`.env`) **Complete Example:** ```bash # 1. Login to cloud bm cloud login # 2. Upload local project (creates project if needed) bm cloud upload ~/specs --project specs --create-project # 3. Verify upload bm project list ``` After sync completes, the notes are available in the [web app](https://app.basicmemory.com){rel=""nofollow""} and for AI conversations. ::tip For bidirectional sync (editing both locally and in cloud), see the [Cloud Sync Guide](https://docs.basicmemory.com/cloud/cloud-sync) . :: --- ## Cloud Snapshots Basic Memory Cloud includes point-in-time snapshots for backup and recovery. Create manual snapshots before major changes, or rely on automatic daily backups. **Key features:** - Create unlimited manual snapshots - Automatic daily snapshots - Browse historical versions - Restore individual files or folders ```bash # Create a snapshot before major changes bm cloud snapshot create "Before reorganization" # List all snapshots bm cloud snapshot list # Browse and restore files bm cloud snapshot browse snap_abc123 ``` ::tip For complete snapshot management including restore procedures and best practices, see the [Cloud Snapshots Guide](https://docs.basicmemory.com/cloud/cloud-snapshots) . :: --- ## Migrating to Cloud Already using Basic Memory locally? You have two options: ### Option 1: One-Time Upload (Fastest) Upload your existing local project to cloud: ```bash # Login first bm cloud login # Upload entire project bm cloud upload ~/basic-memory --project main --create-project ``` **Use when:** - You want to move to cloud-only - One-time migration is sufficient - Don't need ongoing local-cloud sync ### Option 2: Bidirectional Sync (Hybrid Workflow) Set up sync to work both locally and in cloud: ```bash # Login and setup sync bm cloud login bm cloud setup # Add existing project with sync enabled bm project add main --local-path ~/basic-memory # Initial sync (resync creates baseline) bm cloud bisync --name main --resync --dry-run # preview first bm cloud bisync --name main --resync # establish baseline # Ongoing sync (run after local or cloud changes) bm cloud bisync --name main ``` **Use when:** - You want to edit both locally (Obsidian, VS Code) and in cloud - Need offline access - Want automatic bidirectional sync ::note{icon="i-lucide-info"} Both methods preserve all your notes, relations, and tags. Choose based on whether you want cloud-only or hybrid local+cloud workflow. See the [Cloud Sync Guide](https://docs.basicmemory.com/cloud/cloud-sync) for detailed sync configuration. :: ### Moving between cloud workspaces If your notes already live in one cloud workspace (say, your personal one) and you want to bring them into a [team workspace](https://docs.basicmemory.com/teams/about) — or vice versa — see [Copy Content Between Workspaces](https://docs.basicmemory.com/teams/copy-between-workspaces) for the project ZIP, single-note, MCP, and local-sync recipes. --- ## Next Steps ::card-group :::card --- icon: i-lucide-route title: Local & Cloud Routing to: https://docs.basicmemory.com/cloud/routing --- Run some projects locally and others in the cloud. ::: :::card --- icon: i-lucide-refresh-cw title: Cloud Sync Guide to: https://docs.basicmemory.com/cloud/cloud-sync --- Set up bidirectional sync for local editing. ::: :::card --- icon: i-lucide-terminal title: CLI Reference to: https://docs.basicmemory.com/reference/cli-reference --- Complete CLI command reference. ::: :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- All available MCP tools for AI assistants. ::: :: # Web App The Basic Memory web app at [app.basicmemory.com](https://app.basicmemory.com){rel=""nofollow""} is a full-featured interface for working with your knowledge base. Notes open ready to edit, your AI assistant can join you live, and everything is saved as plain Markdown. Anything your AI assistant can do, you can do here too. :theme-image{alt="Web App Overview" dark="/screenshots/cloud-app/v2-overview-dark.png" light="/screenshots/cloud-app/v2-overview-light.png"} --- ## Layout The app is organized into three panes: | Pane | Contents | | --------------- | ------------------------------------------------------- | | **Sidebar** | Project and folder tree, search, your account avatar | | **Note list** | Notes in the current folder or project, grouped by date | | **Note detail** | The selected note, opened ready to edit | Click a folder in the sidebar to filter the note list. Select a note to open it in the detail pane. --- ## Navigating notes ### Browse by folder Expand folders in the sidebar to navigate your project structure. Click a folder to filter the note list to that location. ### Filter with tabs Switch between views above the note list: | Tab | Shows | | ---------- | ---------------------------------------- | | **All** | Every note in the current folder/project | | **Pinned** | Notes you've pinned for quick access | ### Search notes Use the search field in the sidebar to filter by title or content. Search is instant and scoped to the current project. :theme-image{alt="Search notes" dark="/screenshots/cloud-app/v2-search-dark.png" light="/screenshots/cloud-app/v2-search-light.png"} ### Pin important notes Open a note's `⋮` menu (or use the command palette) and choose **Pin Note**. Pinned notes appear in the Pinned tab. --- ## Editing notes Notes open ready to edit. The app has three modes, switchable from the toolbar or with keyboard shortcuts: | Mode | Shortcut | Description | | --------------- | -------------------- | ---------------------------------------------------------------------------------------------- | | **Rich editor** | Cmd/Ctrl + Shift + I | WYSIWYG editing — type and format directly, with tables, code blocks, callouts, and task lists | | **Source mode** | Cmd/Ctrl + Shift + R | Plain Markdown editing with full frontmatter visible — for power users | | **Preview** | Cmd/Ctrl + Shift + P | Read-only rendered view with clickable `[[wiki links]]` for navigating your knowledge graph | :theme-image{alt="Rich editor mode" dark="/screenshots/cloud-app/v2-edit-mode-dark.png" light="/screenshots/cloud-app/v2-edit-mode-light.png"} And here's the same note in **Preview** mode, with clickable wiki links: :theme-image{alt="Preview mode" dark="/screenshots/cloud-app/v2-edit-preview-dark.png" light="/screenshots/cloud-app/v2-edit-preview-light.png"} ::tip Press **Cmd/Ctrl + Option + Z** to toggle Zen mode — a distraction-free full-screen editor. Press **Escape** to drop back to Preview from the editor. :: ### Markdown formatting The rich editor supports full Markdown including: - Headers, bold, italic, inline code - Code blocks with syntax highlighting - Tables - Links and images - Task lists (`- [ ]` and `- [x]`) - Basic Memory semantic syntax (observations, relations) Press **Cmd/Ctrl + /** to see all formatting shortcuts. ### Edit frontmatter Open the **Frontmatter** panel from the toolbar (or the command palette) to edit a note's YAML metadata separately from its content. :theme-image{alt="Edit Frontmatter" dark="/screenshots/cloud-app/v2-frontmatter-dark.png" light="/screenshots/cloud-app/v2-frontmatter-light.png"} --- ## Drafts Start typing in an empty editor — or press **Cmd/Ctrl + N** for a new note — to create a **draft**. Drafts let you write before committing a file to a project. - A draft shows a status dot until it's saved. - Click **Save Draft** (or use the command palette) to write it into the current project as a Markdown file. - Once saved, the note syncs like any other and is available to your AI assistant. ::note Saved notes are written automatically as you edit. Status dots tell you the state: unsaved, saving, or draft — no dot means saved. :: --- ## Working with your AI assistant The web app treats your AI assistant as a real collaborator — you can watch it write, and steer it, in the same note you're editing. ### Connect an agent Click **Connect Agent** in the editor to start or resume an agent session for the workspace. When an agent is connected, the button shows its live status (for example, "Claude live"). ### Improve a selection Select text in the editor and choose **Improve** to ask the agent to rewrite, summarize, or extend it. The agent's changes stream into the note as it works — connecting automatically if no agent is attached yet. ### The agent pane The agent pane shows the session: what the agent is working on, its progress, and a place to steer it ("Ask for a rewrite, summary, or next step…"). Updates flow into the note in real time, so you can follow along while it writes. --- ## Creating and managing notes ### Create a note - Start typing in an empty editor, or - Press **Cmd/Ctrl + N**, or - Open the command palette (**Cmd/Ctrl + K**) → **New Note** :theme-image{alt="New note" dark="/screenshots/cloud-app/v2-new-note-dark.png" light="/screenshots/cloud-app/v2-new-note-light.png"} ### Move notes - Use a note's `⋮` menu → **Move** to relocate it to another folder, or - Drag the note card from the list onto the desired folder, or - Drag a folder in the tree to move an entire directory. ### Delete notes Open a note's `⋮` menu → **Delete**. ::warning Deletion is permanent. Create a snapshot before bulk deletions if you want the ability to restore. :: ### Copy permalink and rename From a note's `⋮` menu or the command palette, you can also **Rename Note** and **Copy Permalink**. ### Share a note From a note's `⋮` menu, choose **Share note** to create a public, read-only link anyone can open without an account. See [Shared Notes](https://docs.basicmemory.com/cloud/shared-notes). ### See a note's history Every save creates a new version. Click the **File history** icon (clock) in a note's toolbar to browse the timeline, compare any earlier version against the current one, and merge old content back in. See [File History](https://docs.basicmemory.com/cloud/file-history). --- ## Projects Projects are top-level containers. Each has its own folder tree, notes, and sync configuration. ### Switch projects Use the project selector in the sidebar to switch between projects. ### Manage projects Go to **Settings → Projects** to create new projects, upload files, download a project as a ZIP, or delete a project. :theme-image{alt="Manage projects" dark="/screenshots/cloud-app/v2-manage-projects-dark.png" light="/screenshots/cloud-app/v2-manage-projects-light.png"} ::tip Upload entire folders and folder trees via the [command line tools](https://docs.basicmemory.com/cloud/cloud-guide#command-line-tools) — directory structure is preserved. :: --- ## Import data Import your existing AI conversations from **Settings → Import**. | Format | File | | --------------------- | ----------------------------------------- | | **Claude** | `conversations.json` from a Claude export | | **ChatGPT** | Export ZIP or JSON from ChatGPT settings | | **Basic Memory JSON** | Memory exports with entities & relations | 1. Go to **Settings → Import** 2. Select the import type 3. Choose a target project (or use the default) 4. Set a destination folder (default: `imports`) 5. Upload your file and start the import :theme-image{alt="Import data" dark="/screenshots/cloud-app/v2-import-dark.png" light="/screenshots/cloud-app/v2-import-light.png"} ::note Imported conversations are converted to Basic Memory's knowledge format automatically. :: --- ## Snapshots Create point-in-time backups of your cloud data from **Settings → Snapshots**. Use them before major changes like bulk imports or reorganizations. ::tip For complete snapshot management including creating, browsing, and restoring snapshots, see the [Cloud Snapshots Guide](https://docs.basicmemory.com/cloud/cloud-snapshots) . :: --- ## Keyboard Shortcuts The web app is designed for keyboard-first navigation. Press **Cmd/Ctrl + /** to see the full list in the app. ### Command palette Press **Cmd/Ctrl + K** to open the command palette and search for any action — navigate to notes, settings, the graph, or projects; create a new note; switch view modes; change theme; or run note and editor actions. :theme-image{alt="Command palette" dark="/screenshots/cloud-app/v2-command-dark.png" light="/screenshots/cloud-app/v2-command-light.png"} ### Formatting | Shortcut | Action | | ------------------------- | ------------- | | **Cmd/Ctrl + B** | Bold | | **Cmd/Ctrl + I** | Italic | | **Cmd/Ctrl + E** | Inline code | | **Cmd/Ctrl + Option + 1** | Heading 1 | | **Cmd/Ctrl + Option + 2** | Heading 2 | | **Cmd/Ctrl + Option + 3** | Heading 3 | | **Cmd/Ctrl + D** | Task checkbox | ### Structure | Shortcut | Action | | ----------------- | ------------ | | **Cmd/Ctrl + ]** | Indent list | | **Cmd/Ctrl + \[** | Outdent list | ### View | Shortcut | Action | | ------------------------ | ------------------- | | **Cmd/Ctrl + Shift + I** | Rich editor | | **Cmd/Ctrl + Shift + P** | Preview | | **Cmd/Ctrl + Shift + R** | Source mode | | **Escape** | Preview from editor | ### Global | Shortcut | Action | | ------------------------- | ------------------ | | **Cmd/Ctrl + K** | Commands | | **Cmd/Ctrl + N** | New note | | **Cmd/Ctrl + Option + E** | Focus editor | | **Cmd/Ctrl + Option + Z** | Toggle Zen mode | | **Cmd/Ctrl + /** | Keyboard shortcuts | :theme-image{alt="Keyboard shortcuts" dark="/screenshots/cloud-app/v2-shortcuts-dark.png" light="/screenshots/cloud-app/v2-shortcuts-light.png"} --- ## Settings Access settings from the user menu (top of the sidebar) or the command palette. :theme-image{alt="Settings" dark="/screenshots/cloud-app/v2-settings-dark.png" light="/screenshots/cloud-app/v2-settings-light.png"} | Section | What it does | | ---------------- | ------------------------------------------------------------------------------------------------- | | **General** | Account and profile settings | | **Projects** | Create, upload to, download, and delete projects | | **Import** | Import Claude, ChatGPT, or JSON exports | | **MCP** | Connect AI assistants via MCP | | **Teams** | Manage [team members, roles, and invitations](https://docs.basicmemory.com/teams/about) | | **Billing** | Manage payment and subscription | | **API Keys** | Create and manage [API keys](https://docs.basicmemory.com/cloud/api-keys) for programmatic access | | **Snapshots** | Manage [point-in-time backups](https://docs.basicmemory.com/cloud/cloud-snapshots) | | **Shared Notes** | Manage public [share links](https://docs.basicmemory.com/cloud/shared-notes) for your notes | ::note The **Teams** , **Billing** , and **Audit Logs** sections appear based on your workspace and role. See [Teams](https://docs.basicmemory.com/teams/about) for collaboration features. :: You can also customize appearance — see [Themes](https://docs.basicmemory.com/cloud/themes). --- ## Tips for Effective Use ### Organize with folders Create a folder structure that matches how you think: ```bash ~/basic-memory/ ├── projects/ # Active projects ├── research/ # Learning and exploration ├── decisions/ # Decision records ├── meetings/ # Meeting notes └── archive/ # Completed/old content ``` ### Use pinned notes Pin your most-accessed notes (project overviews, quick references) for one-click access. ### Create snapshots before big changes Before reorganizing folders, bulk importing, or deleting lots of notes, create a manual snapshot. ### Collaborate with your assistant The web app and your AI assistant work together: 1. **AI creates** detailed notes during conversations — or writes alongside you with Connect Agent 2. **You browse and refine** in the web app 3. **AI references** your refined notes in future conversations --- ## Next Steps ::card-group :::card --- icon: i-lucide-users title: Teams to: https://docs.basicmemory.com/teams/about --- Share a workspace and collaborate with your team. ::: :::card --- icon: i-lucide-refresh-cw title: Cloud Sync to: https://docs.basicmemory.com/cloud/cloud-sync --- Set up bidirectional sync to edit locally and in cloud. ::: :::card --- icon: i-lucide-terminal title: CLI Reference to: https://docs.basicmemory.com/reference/cli-reference --- Advanced cloud commands including snapshot CLI. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Learn the semantic structure for observations and relations. ::: :: # Cloud Sync Guide The Basic Memory Cloud CLI provides seamless integration between local and cloud knowledge bases using **project-scoped synchronization**. Each project can optionally sync with the cloud, giving you fine-grained control over what syncs and where. --- ## Overview The cloud CLI enables you to: - **Toggle cloud mode** - All regular `bm` commands work with cloud when enabled - **Project-scoped sync** - Each project independently manages its sync configuration - **Explicit operations** - Sync only what you want, when you want - **Team-safe push/pull** - Additive, git-style transfers that work on shared Team workspaces - **Bidirectional sync** - Keep local and cloud in sync with rclone bisync (Personal workspaces) - **Offline access** - Work locally, sync when ready ### Personal vs Team Workspaces | Command | Direction | Behavior | Personal | Team | | ----------------- | ------------- | ------------------------------------------------ | -------- | ---- | | `bm cloud pull` | cloud → local | **additive** — never deletes local | ✅ | ✅ | | `bm cloud push` | local → cloud | **additive** — never deletes cloud | ✅ | ✅ | | `bm cloud sync` | local → cloud | **mirror** — deletes cloud files missing locally | ✅ | ❌ | | `bm cloud bisync` | local ↔ cloud | **mirror** — can delete/overwrite both sides | ✅ | ❌ | `sync` and `bisync` are mirror operations: one tree becomes authoritative and files missing on the other side get deleted. That is correct for a Personal workspace (one user, one source of truth) but unsafe on a shared Team bucket, where it could delete a teammate's files. On Team workspaces these commands exit early with a clear error and point you at `push`/`pull`. `push` and `pull` are additive (they never delete on the destination), so they are safe on both Personal and Team workspaces. --- ## Prerequisites Before using Basic Memory Cloud sync, you need: - **Active Subscription**: An active Basic Memory Cloud subscription - **Subscribe**: Visit [basicmemory.com/subscribe](https://basicmemory.com/subscribe){rel=""nofollow""} - **Basic Memory CLI**: See [Getting Started](https://docs.basicmemory.com/start-here/getting-started#local-installation) for installation ::warning If you attempt to log in without an active subscription, you'll receive a "Subscription Required" error. :: ### When to Use Sync ::tip **Sync is designed for hybrid workflows** where you want to edit files locally (in tools like Obsidian or VS Code) while keeping cloud in sync. **Use sync when:** - You want to edit notes locally in your preferred editor - You need bidirectional sync (changes flow both ways automatically) - You're working with large knowledge bases - You want offline access with periodic syncing **Alternatives to sync:** - **Web Editor**: Upload and edit files in the [Cloud web interface](https://docs.basicmemory.com/cloud/cloud-guide#web-editor) - **MCP Tools Only**: Use AI assistants to manage notes entirely in cloud :: --- ## Architecture: Project-Scoped Sync ### How It Works Projects can exist in three states: 1. **Cloud-only** - Project exists on cloud, no local copy 2. **Cloud + Local (synced)** - Project has a local working directory that syncs 3. **Local-only** - Project exists locally (when cloud mode is disabled) **Example:** ```bash # You have 3 projects on cloud: # - research: wants local sync at ~/Documents/research # - work: wants local sync at ~/work-notes # - temp: cloud-only, no local sync needed bm project add research --local-path ~/Documents/research bm project add work --local-path ~/work-notes bm project add temp # No local sync # Now you can sync individually (after initial --resync): bm cloud bisync --name research bm cloud bisync --name work # temp stays cloud-only ``` **What happens under the covers:** - Config stores `cloud_projects` dict mapping project names to local paths - Each project gets its own bisync state in `~/.basic-memory/bisync-state/{project}/` - Rclone syncs using single remote: `basic-memory-cloud` - Projects can live anywhere on your filesystem --- ## Quick Start ### 1. Enable Cloud Mode Authenticate and enable cloud mode: ```bash bm cloud login ``` **What this does:** 1. Opens browser to Basic Memory Cloud authentication page 2. Stores authentication token 3. Enables cloud mode - all CLI commands now work against cloud 4. Validates your subscription status ### 2. Set Up Sync Install rclone and configure credentials: ```bash bm cloud setup ``` **What this does:** 1. Installs rclone automatically (if needed) 2. Fetches your tenant information from cloud 3. Generates scoped S3 credentials for sync 4. Configures single rclone remote: `basic-memory-cloud` ### 3. Add Projects with Sync Create projects with optional local sync paths: ```bash # Create cloud project without local sync bm project add research # Create cloud project WITH local sync bm project add research --local-path ~/Documents/research # Or configure sync for existing project bm cloud sync-setup research ~/Documents/research ``` ### 4. Sync Your Project Establish the initial sync baseline. **Always preview with `--dry-run` first:** ```bash # Step 1: Preview the initial sync bm cloud bisync --name research --resync --dry-run # Step 2: If all looks good, run the actual sync bm cloud bisync --name research --resync ``` ::note{icon="i-lucide-info"} **Why `--resync`?** This is an rclone requirement for the first bisync run. It establishes the initial state that future syncs will compare against. After the first sync, don't use `--resync` unless you need to force a new baseline. :: ### 5. Subsequent Syncs After the first sync, just run bisync without `--resync`: ```bash bm cloud bisync --name research ``` **What happens:** 1. Rclone compares local and cloud states 2. Syncs changes in both directions 3. Auto-resolves conflicts (newer file wins) 4. Basic Memory reindexes all changed files 5. Updates `last_sync` timestamp in config ::note **Reindexing after sync** : Basic Memory automatically reindexes all synced changes to update the knowledge graph. :: ### 6. Verify Setup ```bash bm cloud status ``` You should see: - `Mode: Cloud (enabled)` - `Cloud instance is healthy` --- ## File Synchronization ### Understanding the Sync Commands | Command | Direction | Use Case | | ----------------- | ------------- | -------------------------------------------------------- | | `bm cloud pull` | Cloud → Local | Fetch cloud changes additively (Personal + Team) | | `bm cloud push` | Local → Cloud | Upload local changes additively (Personal + Team) | | `bm cloud bisync` | Local ↔ Cloud | Two-way mirror (Personal only, recommended for solo use) | | `bm cloud sync` | Local → Cloud | One-way mirror, make cloud match local (Personal only) | | `bm cloud check` | Verify | Check if files match (Personal only) | If you collaborate on a shared Team workspace, use **`push`/`pull`**. If you are the only writer (a Personal workspace), the mirror commands `sync`/`bisync` give you a single source of truth. ### Team Workspaces: Push and Pull (Additive, Git-Style) `push` and `pull` model `git push` / `git pull`: ```bash # Preview what would transfer bm cloud pull --name research --dry-run # Fetch cloud changes into your local directory bm cloud pull --name research # Upload your local changes to the cloud bm cloud push --name research ``` Both commands are additive — they never delete files on the destination. New and changed files transfer; if any file differs on both sides, the command aborts and lists the conflicts, like a rejected `git push`. **Resolving conflicts:** re-run with `--on-conflict` to choose what survives. The value names what is kept, so it reads the same in both directions: | Value | Behavior | | ---------------- | ---------------------------------------------------------------------- | | `fail` (default) | Abort and list conflicting files | | `keep-cloud` | Take the cloud version (pull: overwrite local; push: skip those files) | | `keep-local` | Keep the local version (pull: skip those files; push: overwrite cloud) | | `keep-both` | Keep both versions, renaming one copy | ```bash # A teammate edited notes you also changed locally — pull reports a conflict: bm cloud pull --name research # pull aborted: 1 file(s) differ between local and cloud. # Take the cloud version: bm cloud pull --name research --on-conflict keep-cloud # Or keep both copies to merge by hand: bm cloud pull --name research --on-conflict keep-both ``` ::note `push` / `pull` are deliberately simple, conflict-aware transfers — not a full reconciler. They compare the current state of both sides without a sync baseline. On Team workspaces, use `bm cloud pull --dry-run` / `bm cloud push --dry-run` to preview differences ( `bm cloud check` is Personal-only). :: ### Two-Way Sync (Recommended) ```bash # First time - establish baseline bm cloud bisync --name research --resync # Subsequent syncs bm cloud bisync --name research ``` **Conflict resolution:** When the same file is edited both locally and in cloud, the newer file wins (based on modification time). ::warning `bisync` is a two-way mirror that can delete and overwrite on both sides, so it is limited to Personal workspaces. On Team workspaces, use `bm cloud pull` then `bm cloud push` instead. :: ### One-Way Sync ```bash bm cloud sync --name research ``` Makes cloud identical to local — including deleting cloud files that are missing locally. Use when local is the source of truth. Personal workspaces only; on Team workspaces use `bm cloud push` (additive). ### Preview Changes (Dry Run) ```bash bm cloud bisync --name research --dry-run ``` Shows what would change without actually syncing. ### Verify Integrity ```bash bm cloud check --name research ``` Compares file checksums without making changes. --- ## Multiple Projects ### Syncing Multiple Projects ```bash # Setup multiple projects bm project add research --local-path ~/Documents/research bm project add work --local-path ~/work-notes bm project add personal --local-path ~/personal # Establish baselines bm cloud bisync --name research --resync bm cloud bisync --name work --resync bm cloud bisync --name personal --resync # Daily workflow: sync everything bm cloud bisync --name research bm cloud bisync --name work bm cloud bisync --name personal ``` ### Mixed Usage ```bash # Projects with sync bm project add research --local-path ~/Documents/research bm project add work --local-path ~/work # Cloud-only projects bm project add archive bm project add temp-notes # Sync only the configured ones bm cloud bisync --name research bm cloud bisync --name work # archive and temp-notes stay cloud-only ``` --- ## Filter Configuration ### Understanding .bmignore Basic Memory uses `.bmignore` for global ignore patterns (similar to `.gitignore`). **Location:** `~/.basic-memory/.bmignore` **Default patterns:** ```gitignore # Version control .git/** # Python __pycache__/** *.pyc .venv/** # Node.js node_modules/** # Basic Memory internals memory.db/** memory.db-shm/** memory.db-wal/** # OS files .DS_Store/** # Environment files .env/** ``` ::note Basic Memory also respects `.gitignore` files in your projects. Use `.bmignore` for global patterns across all projects. :: --- ## Troubleshooting ### Authentication Issues **Problem:** Authentication failed or Invalid token **Solution:** ```bash bm cloud logout bm cloud login ``` ### First Bisync Requires --resync **Problem:** Bisync fails on first run **Solution:** ```bash bm cloud bisync --name research --resync ``` This establishes the initial baseline state. ### Empty Directory Issues **Problem:** "Empty prior Path1 listing. Cannot sync to an empty directory" **Solution:** Add at least one file before running `--resync`: ```bash echo "# Research Notes" > ~/Documents/research/README.md bm cloud bisync --name research --resync ``` ### Bisync State Corruption **Problem:** Bisync fails with errors about corrupted state **Solution:** ```bash bm cloud bisync-reset research bm cloud bisync --name research --resync ``` ### Too Many Deletes **Problem:** "max delete limit (25) exceeded" **Solution:** Review what's being deleted, then force resync if correct: ```bash bm cloud bisync --name research --dry-run bm cloud bisync --name research --resync ``` ### Project Not Configured for Sync **Problem:** "Project has no local\_sync\_path configured" **Solution:** ```bash bm cloud sync-setup research ~/Documents/research bm cloud bisync --name research --resync ``` --- ## Disable Cloud Mode Return to local mode: ```bash bm cloud logout ``` All `bm` commands now work with local projects. --- ## Security - **Authentication**: OAuth 2.1 with PKCE flow - **Tokens**: Stored securely in `~/.basic-memory/basic-memory-cloud.json` - **Transport**: All data encrypted in transit (HTTPS) - **Credentials**: Scoped S3 credentials (read-write to your tenant only) - **Isolation**: Your data isolated from other tenants - **Ignore patterns**: Sensitive files excluded via `.bmignore` --- ## Command Reference ### Cloud Mode Management ```bash bm cloud login # Authenticate and enable cloud mode bm cloud logout # Disable cloud mode bm cloud status # Check cloud mode and instance health ``` ### Setup ```bash bm cloud setup # Install rclone and configure credentials ``` ### Project Management ```bash bm project list # List cloud projects bm project add # Create cloud project (no sync) bm project add --local-path # Create with local sync bm cloud sync-setup # Add sync to existing project bm project rm # Delete project ``` ### File Synchronization ```bash # Two-way sync (recommended) bm cloud bisync --name # After first --resync bm cloud bisync --name --resync # First time / force baseline bm cloud bisync --name --dry-run bm cloud bisync --name --verbose # One-way sync (local → cloud) bm cloud sync --name bm cloud sync --name --dry-run # Integrity check bm cloud check --name # List remote files bm project ls --name ``` --- ## Summary **Basic Memory Cloud uses project-scoped sync:** 1. **Enable cloud mode** - `bm cloud login` 2. **Install rclone** - `bm cloud setup` 3. **Add projects with sync** - `bm project add research --local-path ~/Documents/research` 4. **Preview first sync** - `bm cloud bisync --name research --resync --dry-run` 5. **Establish baseline** - `bm cloud bisync --name research --resync` 6. **Daily workflow** - `bm cloud bisync --name research` **Key benefits:** - Each project independently syncs (or doesn't) - Projects can live anywhere on disk - Explicit sync operations (no magic) - Safe by design (max delete limits, conflict resolution) - Full offline access (work locally, sync when ready) --- ## Next Steps ::card-group :::card --- icon: i-lucide-cloud title: Cloud Guide to: https://docs.basicmemory.com/cloud/cloud-guide --- Cloud features and setup options. ::: :::card --- icon: i-lucide-terminal title: CLI Reference to: https://docs.basicmemory.com/reference/cli-reference --- Complete CLI command reference. ::: :::card --- icon: i-lucide-hexagon title: Obsidian Integration to: https://docs.basicmemory.com/integrations/obsidian --- Use cloud sync with Obsidian. ::: :::card --- icon: i-lucide-code title: VS Code Integration to: https://docs.basicmemory.com/integrations/vscode --- Use cloud sync with VS Code. ::: :: # User Guide This guide covers everything from creating your first notes to building a comprehensive knowledge graph using Basic Memory Cloud. ::tip Using Basic Memory locally? See the [Local User Guide](https://docs.basicmemory.com/local/user-guide) for file-based workflows and CLI commands. :: --- ## Basic Memory Workflow Using Basic Memory follows a natural cycle: ::mermaid --- code: | flowchart LR A[Conversation] --> B[Capture] B --> C[Connect] C --> D[Reference] D --> E[Edit] E --> A --- :: 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: ```bash 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](https://app.basicmemory.com/notes){rel=""nofollow""}: 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:** ```bash --- 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: ```bash "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: ```bash "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: ```bash "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 ```bash 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: ```bash You: "Take a look at memory://coffee-brewing-methods and let's discuss improvements" ``` Claude will load that specific document and any related context. ::tip Memory URLs are stable identifiers. Even if you rename or move a file, the permalink stays the same. :: --- ## Building Knowledge Connections ### Creating Relations Use WikiLink syntax to connect knowledge: ```bash ## Relations - implements [[Authentication System]] - requires [[Database Schema]] - relates_to [[Security Guidelines]] ``` ### Common Relation Types | Type | Use for | | ------------- | ---------------------------- | | `implements` | One thing implements another | | `requires` | Dependencies | | `relates_to` | General connections | | `part_of` | Hierarchy relationships | | `extends` | Extensions or enhancements | | `pairs_with` | Things that work together | | `inspired_by` | Source of ideas | | `replaces` | Supersedes another document | ### Adding Observations Structure facts with semantic categories: ```bash ## 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:** ```bash 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](https://app.basicmemory.com/notes){rel=""nofollow""}: 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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 ::tip Imported conversations are converted to Basic Memory's markdown format with observations and relations extracted automatically. :: ### 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: ```bash 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](https://docs.basicmemory.com/cloud/cloud-guide#cloud-snapshots) 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: ```bash bm cloud login bm cloud setup bm cloud bisync --name main ``` This syncs your cloud notes to a local folder. Changes in either location sync automatically. See the [Cloud Sync Guide](https://docs.basicmemory.com/cloud/cloud-sync) 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 cloud bisync --name main` 3. Check for conflicts in the sync log ### Getting Help - **Discord**: [discord.gg/tyvKNccgqN](https://discord.gg/tyvKNccgqN){rel=""nofollow""} - #help channel - **GitHub**: [github.com/basicmachines-co/basic-memory/issues](https://github.com/basicmachines-co/basic-memory/issues){rel=""nofollow""} --- ## Next Steps ::card-group :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Learn the semantic patterns for observations and relations. ::: :::card --- icon: i-lucide-layout-panel-left title: Web App Guide to: https://docs.basicmemory.com/cloud/web-app --- Detailed guide to the web editor interface. ::: :::card --- icon: i-lucide-refresh-cw title: Cloud Sync to: https://docs.basicmemory.com/cloud/cloud-sync --- Set up bidirectional sync with local files. ::: :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- All available tools for AI assistants. ::: :: # Cloud Snapshots Basic Memory Cloud includes point-in-time snapshots for backup and recovery. Create manual snapshots before major changes, or rely on automatic daily backups. ::note{icon="i-lucide-info"} Create as many snapshots as you need—there's no limit. Basic Memory Cloud also creates daily automatic snapshots, so you're always protected. :: ::tip **Need to recover something now?** Go to [Restore Lost Content](https://docs.basicmemory.com/cloud/restore-lost-content) for a step-by-step recovery guide. For a single note's recent edits, [File History](https://docs.basicmemory.com/cloud/file-history) is usually faster than restoring from a snapshot. :: --- ## What Snapshots Do - **Rollback** to a previous state after accidental changes - **Browse** historical versions of your notes - **Restore** individual files or entire folders - **Protect** against accidental deletion --- ## Using the Web App Manage snapshots directly in your browser at [app.basicmemory.com](https://app.basicmemory.com){rel=""nofollow""}. ### View Snapshots Go to **Settings → Snapshots** to see all snapshots with creation time and description. ![Snapshots list](https://docs.basicmemory.com/screenshots/cloud-app/snapshots-list.png) ### Create a Snapshot 1. Click **Create Snapshot** 2. Add an optional description (e.g., "Before reorganizing projects") 3. Confirm ![Create snapshot](https://docs.basicmemory.com/screenshots/cloud-app/create-snapshot.png) ### Restore from a Snapshot 1. Click on a snapshot → **Restore Files** 2. Filter by project or search for specific files 3. Select files or folders to restore 4. Click **Restore** to copy them back ![Restore from snapshot](https://docs.basicmemory.com/screenshots/cloud-app/restore-files.png) ::note Restored files overwrite existing files with the same path. Consider creating a new snapshot before restoring if you want to preserve current state. :: --- ## Using the CLI Manage snapshots from the command line with `bm cloud snapshot` commands. ### Create a Snapshot ```bash bm cloud snapshot create "Before reorganization" ``` **Output:** ```text Created snapshot: snap_abc123 (2026-01-27T10:30:00) ``` ### List Snapshots ```bash bm cloud snapshot list ``` **Output:** ```text snap_abc123 "Before reorganization" Jan 27, 2026 42 MB snap_xyz789 "daily-auto" Jan 26, 2026 41 MB snap_def456 "daily-auto" Jan 25, 2026 40 MB ``` ### View Snapshot Details ```bash bm cloud snapshot show snap_abc123 ``` ### Browse Snapshot Contents View files in a snapshot without restoring: ```bash bm cloud snapshot browse snap_abc123 ``` **Output:** ```text notes/project.md notes/ideas.md research/analysis.md meetings/2026-01-15.md ``` Filter by path: ```bash bm cloud snapshot browse snap_abc123 --path notes/ ``` ### Restore Files Restore a specific file: ```bash bm cloud snapshot restore snap_abc123 --file notes/important.md ``` Restore an entire folder: ```bash bm cloud snapshot restore snap_abc123 --path research/ ``` ### Delete a Snapshot ```bash bm cloud snapshot delete snap_abc123 ``` ::warning Deleted snapshots cannot be recovered. Make sure you no longer need the snapshot before deleting. :: --- ## When to Create Snapshots - Before reorganizing your folder structure - Before bulk imports from Claude or ChatGPT - Before deleting multiple notes - Before running automated scripts - At project milestones --- ## Automatic Snapshots Basic Memory Cloud creates automatic daily snapshots: - **Frequency**: Once per day - **Naming**: `daily-auto` prefix - **No action required**: Happens automatically You can rely on automatic snapshots for basic protection, but manual snapshots are recommended before major changes. --- ## Best Practices 1. **Name snapshots descriptively** - Use names like "Before Q1 reorganization" instead of "backup1" 2. **Create before bulk operations** - Imports, reorganizations, and deletions 3. **Review automatic snapshots** - Check that daily snapshots are being created 4. **Test restore occasionally** - Verify you can restore files when needed 5. **Clean up old snapshots** - Delete manual snapshots you no longer need --- ## Troubleshooting ### Snapshot Creation Failed 1. Check your subscription status: `bm cloud status` 2. Verify you're authenticated: `bm cloud login` 3. Check available storage in your account ### Can't Find a File in Snapshot 1. Use `browse` with different paths to locate the file 2. Check if the file existed at the snapshot time 3. Try an earlier snapshot if the file was deleted before the snapshot ### Restore Didn't Work 1. Check file permissions in your project 2. Verify the file path is correct 3. Try restoring to a different location first --- ## Next Steps ::card-group :::card --- icon: i-lucide-cloud title: Cloud Guide to: https://docs.basicmemory.com/cloud/cloud-guide --- Complete cloud setup and features overview. ::: :::card --- icon: i-lucide-refresh-cw title: Cloud Sync to: https://docs.basicmemory.com/cloud/cloud-sync --- Set up bidirectional sync with local files. ::: :::card --- icon: i-lucide-layout-panel-left title: Web App Guide to: https://docs.basicmemory.com/cloud/web-app --- Browse and edit notes in your browser. ::: :: # Themes Basic Memory Cloud includes a comprehensive theme system with 40+ preset themes and support for custom CSS. Personalize your workspace with colors, fonts, and styles that work for you. ## ![Themes](https://docs.basicmemory.com/screenshots/cloud-app/themes.gif) ## Color Mode Switch between light, dark, or system-based color modes: 1. Open **Settings** in the web app 2. Find the **Theme** section 3. Click **Light**, **Dark**, or **System** System mode automatically matches your operating system preference. --- ## Preset Themes Choose from 40+ curated themes, each with coordinated colors for both light and dark modes. ### Selecting a Theme 1. Open **Settings** in the web app 2. Find the **Theme** section 3. Click the theme dropdown 4. Preview themes by hovering - see the color palette 5. Click to apply ### Available Themes **Popular presets include:** - **Default** - Clean white/dark gray base - **Modern Minimal** - Blue-focused minimal design - **Violet Bloom** - Purple-focused theme - **T3 Chat** - Inspired by T3 Chat interface - And 35+ more options Each theme defines: - Background and foreground colors - Primary and accent colors - Sidebar colors - Card and border styles - Typography (optional) --- ## Custom Themes Create your own theme with custom CSS variables. ### Adding a Custom Theme 1. Open **Settings** in the web app 2. Find the **Theme** section 3. Click **Custom Theme** 4. Paste your CSS or drag-and-drop a `.css` file 5. Click **Save** ### CSS Format Custom themes use CSS variables in TweakCN format: ```css :root { --background: oklch(1 0 0); --foreground: oklch(0.145 0 0); --card: oklch(1 0 0); --card-foreground: oklch(0.145 0 0); --popover: oklch(1 0 0); --popover-foreground: oklch(0.145 0 0); --primary: oklch(0.205 0 0); --primary-foreground: oklch(0.985 0 0); --secondary: oklch(0.97 0 0); --secondary-foreground: oklch(0.205 0 0); --muted: oklch(0.97 0 0); --muted-foreground: oklch(0.556 0 0); --accent: oklch(0.97 0 0); --accent-foreground: oklch(0.205 0 0); --destructive: oklch(0.577 0.245 27.325); --border: oklch(0.922 0 0); --input: oklch(0.922 0 0); --ring: oklch(0.708 0 0); --radius: 0.625rem; } .dark { --background: oklch(0.145 0 0); --foreground: oklch(0.985 0 0); /* ... dark mode overrides */ } ``` ### Required Variables Your custom theme must define these variables for both light (`:root`) and dark (`.dark`) modes: | Variable | Purpose | | ------------------------ | -------------------------- | | `--background` | Page background | | `--foreground` | Primary text | | `--card` | Card backgrounds | | `--card-foreground` | Card text | | `--popover` | Dropdown/menu backgrounds | | `--popover-foreground` | Dropdown/menu text | | `--primary` | Primary buttons, links | | `--primary-foreground` | Text on primary elements | | `--secondary` | Secondary elements | | `--secondary-foreground` | Text on secondary elements | | `--muted` | Muted backgrounds | | `--muted-foreground` | Muted text | | `--accent` | Accent highlights | | `--accent-foreground` | Text on accents | | `--destructive` | Delete/danger actions | | `--border` | Borders | | `--input` | Input field borders | | `--ring` | Focus rings | ### Optional Variables Customize typography and layout: ```css :root { /* Typography */ --font-sans: 'Inter', sans-serif; --font-serif: 'Georgia', serif; --font-mono: 'JetBrains Mono', monospace; --letter-spacing: -0.01em; /* Layout */ --radius: 0.5rem; --spacing: 1rem; } ``` ### Sidebar Variables Customize the sidebar separately: ```css :root { --sidebar: oklch(0.985 0 0); --sidebar-foreground: oklch(0.145 0 0); --sidebar-primary: oklch(0.205 0 0); --sidebar-primary-foreground: oklch(0.985 0 0); --sidebar-accent: oklch(0.97 0 0); --sidebar-accent-foreground: oklch(0.205 0 0); --sidebar-border: oklch(0.922 0 0); --sidebar-ring: oklch(0.708 0 0); } ``` --- ## Using TweakCN [TweakCN](https://tweakcn.com){rel=""nofollow""} is a theme generator compatible with Basic Memory Cloud. ### Export from TweakCN 1. Visit [tweakcn.com](https://tweakcn.com){rel=""nofollow""} 2. Customize your theme with the visual editor 3. Export as CSS 4. Paste into Basic Memory Cloud's custom theme editor ### Color Format TweakCN uses OKLCH color format for better perceptual uniformity: ```css /* OKLCH format: oklch(lightness chroma hue) */ --primary: oklch(0.6 0.2 250); /* Blue */ --accent: oklch(0.7 0.15 330); /* Purple */ ``` --- ## Theme Persistence Your theme choice is saved locally in your browser: - Persists across sessions - Applies immediately on page load - Separate settings for each browser/device ::note Theme settings are stored in your browser's localStorage, not in your cloud account. If you switch browsers or devices, you'll need to set your theme again. :: --- ## Troubleshooting ### Theme Not Applying 1. Check browser console for CSS errors 2. Verify all required variables are defined 3. Ensure both `:root` and `.dark` sections exist 4. Try refreshing the page ### Colors Look Wrong 1. Verify OKLCH values are valid (lightness 0-1, chroma 0-0.4, hue 0-360) 2. Check for typos in variable names 3. Test in both light and dark modes ### Custom Theme Rejected The editor validates your CSS. Common issues: - Missing required variables - Invalid CSS syntax - CSS too large (size limit applies) --- ## Next Steps ::card-group :::card --- icon: i-lucide-layout-panel-left title: Web App Guide to: https://docs.basicmemory.com/cloud/web-app --- Complete guide to the web editor interface. ::: :::card --- icon: i-lucide-key title: API Keys to: https://docs.basicmemory.com/cloud/api-keys --- Create API keys for programmatic access. ::: :: # API Keys API keys provide an alternative to OAuth for authenticating with Basic Memory Cloud. Use them for CLI tools, automation scripts, or any MCP client that supports bearer token authentication. --- ## Why Use API Keys? - **Simpler setup** - No OAuth flow required - **Automation friendly** - Use in scripts and CI/CD - **Multiple keys** - Create separate keys for different tools - **Revocable** - Disable a key without affecting others --- ## Creating an API Key ::steps ### Open Settings In the [web app](https://app.basicmemory.com){rel=""nofollow""}, go to **Settings → API Keys** ### Click Create Key Click **Create New API Key** ### Name Your Key Enter a descriptive name like "Claude Desktop" or "Work Laptop" ### Set Expiration (Optional) Choose when the key should expire, or leave blank for no expiration ### Copy Your Key **Important:** Copy the key immediately. It's only shown once and cannot be retrieved later. The key looks like: `bmc_abc123def456...` :: ::warning Store your API key securely. Anyone with the key can access your Basic Memory account. Never commit keys to version control or share them publicly. :: --- ## Using API Keys ### With Claude Desktop Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): ```json { "mcpServers": { "basic-memory": { "url": "https://cloud.basicmemory.com/mcp", "headers": { "Authorization": "Bearer bmc_your_key_here" } } } } ``` ### With Codex CLI Add to `~/.codex/config.toml`: ```toml [[mcp_servers]] name = "basic-memory" url = "https://cloud.basicmemory.com/mcp" bearer_token_env_var = "BASIC_MEMORY_API_KEY" ``` Then set the environment variable: ```bash export BASIC_MEMORY_API_KEY=bmc_your_key_here ``` ### With Other MCP Clients Any MCP client that supports HTTP headers can use API keys: ```text Authorization: Bearer bmc_your_key_here ``` ### With curl Test your key with curl: ```bash curl -H "Authorization: Bearer bmc_your_key_here" \ https://cloud.basicmemory.com/api/v2/projects ``` ### With Basic Memory CLI (per-project routing) Save a key and route only selected projects through cloud: ```bash # Save an existing key from the web app bm cloud api-key save bmc_your_key_here # Or create and save a new key (requires active OAuth session — run bm cloud login first) bm cloud api-key create "work-laptop" # Route one project through cloud bm project set-cloud research # Revert that project to local routing bm project set-local research ``` This lets you keep a hybrid setup where some projects stay local and others use cloud. See [Local & Cloud Routing](https://docs.basicmemory.com/cloud/routing) for the full routing model, priority levels, and common configurations. --- ## Managing Keys ### View Your Keys In **Settings → API Keys**, you'll see: - Key name - Key prefix (first few characters for identification) - Creation date - Last used timestamp - Status (active/expired/revoked) ### Revoking a Key To disable a key: 1. Go to **Settings → API Keys** 2. Find the key you want to revoke 3. Click **Revoke** 4. Confirm the action Revoked keys stop working immediately. This cannot be undone. ::tip If you suspect a key has been compromised, revoke it immediately and create a new one. :: --- ## Security Best Practices ### Do - **Use descriptive names** - "Claude Desktop Work" is better than "key1" - **Set expiration dates** - Especially for temporary access - **Use environment variables** - Don't hardcode keys in config files - **Revoke unused keys** - Clean up keys you no longer need - **Create separate keys** - One per device or application ### Don't - **Share keys** - Each user should have their own account and keys - **Commit keys to git** - Add config files with keys to `.gitignore` - **Use keys in URLs** - Always use the Authorization header - **Ignore suspicious activity** - Check "last used" timestamps regularly --- ## Key Format API keys follow this format: ```text bmc_ ``` - Prefix `bmc_` identifies it as a Basic Memory Cloud key - 32 bytes of cryptographically random data - URL-safe base64 encoding Example: `bmc_K7xR2pQmNvLwYhT9sU3fAeBcDgHiJkMnOpQrStUv` --- ## API Keys vs OAuth | Feature | API Keys | OAuth | | ------------- | ------------------------ | --------------------------- | | Setup | Copy/paste key | Browser-based flow | | Best for | CLI, scripts, automation | Interactive apps | | Token refresh | No (long-lived) | Yes (short-lived + refresh) | | Revocation | Per-key | Per-session | | Scopes | Full access | Configurable | Use **API keys** for: - Command-line tools - Automation scripts - Headless environments - Multiple concurrent sessions Use **OAuth** for: - Web applications - First-time setup in Claude/ChatGPT - When you want automatic token refresh --- ## Troubleshooting ### Key Not Working 1. Verify the key is copied correctly (no extra spaces) 2. Check the key hasn't been revoked 3. Check the key hasn't expired 4. Ensure the Authorization header format is correct: `Bearer bmc_...` ### "Unauthorized" Error 1. Confirm your subscription is active 2. Verify the key belongs to your account 3. Try creating a new key ### Key Not Showing in List Keys are only shown once at creation. If you lost the key: 1. Revoke the old key 2. Create a new one 3. Update your configuration --- ## Next Steps ::card-group :::card --- icon: i-lucide-cloud title: Cloud Guide to: https://docs.basicmemory.com/cloud/cloud-guide --- Complete cloud setup and features overview. ::: :::card --- icon: i-lucide-message-square title: Claude Desktop Integration to: https://docs.basicmemory.com/integrations/claude-desktop --- Set up Claude Desktop with Basic Memory. ::: :::card --- icon: i-lucide-terminal title: CLI Reference to: https://docs.basicmemory.com/reference/cli-reference --- Command-line tools for Basic Memory. ::: :: # Local & Cloud Routing Basic Memory is a knowledge base that you and your AI share. By default, your notes live on your computer. With Basic Memory Cloud, you can also store notes in the cloud — accessible from any device. Routing lets you choose where each project lives. ::note{icon="i-lucide-info"} **When does routing apply?** This page is for people who have Basic Memory installed on their computer and want to connect some projects to the cloud. If you use Basic Memory Cloud directly (through the web app or by adding `cloud.basicmemory.com` to your AI tool), your notes are already in the cloud — no routing setup needed. :: --- ## How Routing Works When Basic Memory runs on your computer, it decides where to handle each request based on your settings: - **Local mode** — Files and database stay on your machine. No network requests. This is the default. - **Cloud mode** — Requests are forwarded to your Basic Memory Cloud instance. Notes are stored in the cloud and accessible from any device. You use the same commands and your AI uses the same tools either way — the only difference is where your notes are stored. --- ## Routing Levels Routing decisions follow a priority order — the most specific level wins: | Priority | Level | How to set | What it does | | -------- | --------------- | ------------------------------------ | ----------------------------------------- | | Highest | **Per-command** | `--local` / `--cloud` flags | Override for a single command | | Medium | **Per-project** | `bm project set-cloud` / `set-local` | Persistent setting for a specific project | | Lowest | **Global** | `bm cloud login` / `logout` | Default for all projects | **Examples:** - Global cloud mode is active, but `bm project set-local research` keeps the `research` project on your machine. - You're in local-only mode, but `bm project set-cloud shared-notes` routes just that project through cloud. - You need a quick cloud check: `bm search_notes --cloud "meeting notes"` overrides everything for that one call. --- ## Setting Up Cloud Routing ### Save an API Key API keys are the simplest way to enable cloud routing for specific projects. ```bash # Save a key you created in the web app bm cloud api-key save bmc_your_key_here # Or create a new key from the CLI (requires being logged in via `bm cloud login`) bm cloud api-key create "my-laptop" ``` See [API Keys](https://docs.basicmemory.com/cloud/api-keys) for details on creating and managing keys. ### Route a Project to Cloud ```bash # Route a specific project through cloud bm project set-cloud research ``` After this, all MCP tool calls for the `research` project go through your cloud instance. ### Check Routing Status ```bash # See which projects are cloud-routed bm cloud status ``` ### Revert to Local ```bash # Switch a project back to local bm project set-local research ``` The project returns to local mode immediately. Your cloud data remains in the cloud — this only changes where new requests are handled. --- ## Common Setups ### All Local (Default) No configuration needed. Every project runs on your machine. This is how Basic Memory works out of the box. ### All Cloud Log in and everything routes through cloud: ```bash bm cloud login ``` All projects use your cloud instance. Use `bm cloud logout` to return to local-only. ### Hybrid (Local + Cloud) This is the most popular setup — keep private notes on your computer while sharing specific projects across devices. ```bash # Save your API key for per-project routing bm cloud api-key save bmc_your_key_here # Route shared projects to cloud bm project set-cloud shared-notes bm project set-cloud team-wiki # Personal projects stay local (no action needed — local is the default) ``` This is useful when you want to: - Keep sensitive or personal projects on your machine - Share specific projects across devices - Collaborate on cloud projects while working locally on others ### Gradual Migration Start local and move projects to cloud one at a time: ```bash # 1. Start with everything local (default) # 2. Upload a project to cloud bm cloud upload ~/my-notes --project my-notes --create-project # 3. Route that project to cloud bm cloud api-key save bmc_your_key_here bm project set-cloud my-notes # 4. Repeat for other projects as needed ``` --- ## Authentication Cloud-routed projects need credentials. Basic Memory supports two methods: | Method | Best for | How to set up | | ----------------- | ---------------------------------- | ------------------------------- | | **API keys** | CLI, hybrid setups, automation | `bm cloud api-key save bmc_...` | | **Browser login** | Interactive use, global cloud mode | `bm cloud login` | Both methods work for any cloud-routed project. API keys are preferred for hybrid setups because they don't require opening a browser. See [API Keys](https://docs.basicmemory.com/cloud/api-keys) for detailed setup instructions. --- ## How It Works Under the Hood - **Local mode** — Requests are handled directly on your machine with no network involved. - **Cloud mode** — Requests are forwarded to `cloud.basicmemory.com` using your credentials (API key or login token). The cloud instance processes the request and returns the result. In both cases, the same tools and commands work identically. The only difference is where the work happens. # Shared Notes Shared Notes let you publish a single note as a public, read-only web page. Anyone with the link can read it without signing in — handy for sharing a document, a spec, or a writeup with people outside your workspace. :theme-image{alt="A shared note" dark="/screenshots/cloud-app/v2-shared-note-public-note-dark.png" light="/screenshots/cloud-app/v2-shared-note-public-note-light.png"} ::note{icon="i-lucide-link"} Sharing is available in every cloud workspace — personal and team. No extra setup or feature flag required. :: --- ## Share a note Open a saved note, then use its `⋮` menu → **Share note**. :theme-image{alt="Share note action in the note menu" dark="/screenshots/cloud-app/v2-shared-note-button-dark.png" light="/screenshots/cloud-app/v2-shared-note-button-light.png"} Basic Memory creates a public link and shows it in a dialog: > **Share note** — A public read-only link for this note was created. > ⚠️ Anyone with this link can view the note without signing in. :theme-image{alt="Share note dialog with the public link and Copy button" dark="/screenshots/cloud-app/v2-shared-note-dialog-dark.png" light="/screenshots/cloud-app/v2-shared-note-dialog-light.png"} Click **Copy** to copy the link, then share it however you like. The link looks like: ```text https://cloud.basicmemory.com/s/ ``` ::note Only **saved** notes can be shared. A [draft](https://docs.basicmemory.com/cloud/web-app#drafts) has to be saved to a project first — once it has a project and path, the **Share note** action appears. :: --- ## What the recipient sees The shared link opens a clean, full-page rendered view of the note. Visitors: - **Don't need an account** and **can't edit** — it's read-only. - Can follow `[[wiki links]]` in the note (they render as preview links). - Can view the note's frontmatter and copy the link. - Can grab the raw Markdown by adding `/raw` to the URL — useful for feeding a note to a tool or LLM. If a link is invalid, disabled, or revoked, the page simply returns a generic "not found" — your workspace and share details are never exposed. --- ## Manage your shares Go to **Settings → Shared Notes** to see and manage every link you've created. :theme-image{alt="Shared Notes settings" dark="/screenshots/cloud-app/v2-shared-note-settings-dark.png" light="/screenshots/cloud-app/v2-shared-note-settings-light.png"} From a note's `⋮` menu or the settings screen you can: | Action | What it does | | ------------------------ | ------------------------------------------------------------ | | **Sharing link** | View and copy the existing public link | | **Disable** / **Enable** | Pause a link without deleting it, then turn it back on later | | **Stop sharing** | Permanently revoke the link | Moving or renaming a note **doesn't break** its share link — the link follows the note. Deleting the note retires the link. --- ## Who can share In a [team workspace](https://docs.basicmemory.com/teams/about), **owners and editors** can create, disable, and revoke share links. **Viewers** can't manage shares. In a personal workspace, you manage your own. --- ## Good to know - Each note has **one** public link in the app. - Links have **no password** — anyone who has the link can read the note, so only share notes you're comfortable making public. - Revoke or disable a link from **Settings → Shared Notes** the moment you no longer want it reachable. --- ## Next Steps ::card-group :::card --- icon: i-lucide-layout-panel-left title: Web App to: https://docs.basicmemory.com/cloud/web-app --- Browse, edit, and collaborate on notes in the browser. ::: :::card --- icon: i-lucide-users title: Teams to: https://docs.basicmemory.com/teams/about --- Share a whole workspace with your team. ::: :: # Edit Locally and in the App You want the best of both worlds: edit the same project in your local editor (Obsidian, VS Code, Cursor…) **and** in the [cloud app](https://docs.basicmemory.com/cloud/web-app), with both sides staying in sync. This page is the happy path — get a project sync'd in five steps, then the day-to-day routine. ::note{icon="i-lucide-info"} This is a stitched-together how-to. For the deep reference on bidirectional sync — architecture, filters, conflict handling — see [Cloud Sync](https://docs.basicmemory.com/cloud/cloud-sync) . :: --- ## What you'll have when you're done - A cloud project that mirrors a local folder on your machine. - Edits in either place propagate to the other with `bm cloud bisync`. - Your AI assistant (via MCP) sees the same notes whether you're working locally or remotely. --- ## One-time setup ::steps ### Sign in to cloud ```bash bm cloud login ``` A browser tab walks you through OAuth. After confirming the displayed code, you're authenticated and CLI commands route through cloud by default. ### Install sync tooling ```bash bm cloud setup ``` This installs and configures `rclone`, which Basic Memory uses under the hood for bidirectional sync. ### Add or attach the project Two starting points — pick the one that matches you: **You already have local notes** you want to push to cloud: ```bash bm project add my-notes --cloud --local-path ~/notes ``` This creates a cloud project named `my-notes` and points its local mirror at `~/notes`. **The project already exists in cloud** and you want to clone it locally: ```bash bm cloud sync-setup my-notes ~/notes ``` This wires an existing cloud project to a new local path. ### Establish a baseline (`--resync`) The first bisync needs a baseline. Preview it first: ```bash bm cloud bisync --name my-notes --resync --dry-run ``` Look at the plan, then run it for real: ```bash bm cloud bisync --name my-notes --resync ``` After this, both sides are aligned and ready for ongoing sync. ### Verify Open the project in the [web app](https://app.basicmemory.com){rel=""nofollow""} and confirm your notes are there. Then check your local folder — you should see the same files. :: --- ## The day-to-day routine Once the baseline is set, sync is a single command: ```bash bm cloud bisync --name my-notes ``` Run it: - After a session of local edits, before switching to the app. - After working in the app, before opening your local editor. - Whenever you want to be sure both sides agree. That's it. The rest is editing wherever you like. ::tip **Editor of choice.** Once your project syncs to a local folder, any markdown editor works — [Obsidian](https://docs.basicmemory.com/integrations/obsidian) (point a vault at the folder), [VS Code](https://docs.basicmemory.com/integrations/vscode) , [Cursor](https://docs.basicmemory.com/integrations/cursor) , or just `vim` . Your AI assistant reads the same notes either way. :: --- ## A few habits that help - **Sync before and after a session.** It's cheap and avoids surprise conflicts. - **Don't fight an active sync.** If `bm cloud bisync` is running, let it finish before editing again. - **Keep one project per local folder.** Don't nest project folders inside each other — Basic Memory expects each project's local path to be self-contained. - **`.bmignore` if you have to.** If a folder contains files you don't want synced (build output, caches), add it to `.bmignore` at the project root — bisync respects it. --- ## What if I want some projects local-only and others in cloud? That's the [routing](https://docs.basicmemory.com/cloud/routing) model. You can keep personal projects entirely local while syncing only a couple of projects to cloud. The hybrid setup on this page is one routing configuration; routing covers the others (all-local, all-cloud, mixed, per-command overrides). --- ## When sync needs help `bm cloud bisync` is conservative by design — if it sees something it can't safely resolve, it stops and tells you. The [Cloud Sync guide](https://docs.basicmemory.com/cloud/cloud-sync) covers the deeper cases: conflict resolution, `bm cloud check` for integrity verification, and `bm cloud bisync-reset` if you ever need to start the baseline over. --- ## Related - [Cloud Sync](https://docs.basicmemory.com/cloud/cloud-sync) — deep reference for bidirectional sync - [Local & Cloud Routing](https://docs.basicmemory.com/cloud/routing) — choose where each project lives - [Web App](https://docs.basicmemory.com/cloud/web-app) — what the cloud side looks like - [Obsidian](https://docs.basicmemory.com/integrations/obsidian) · [VS Code](https://docs.basicmemory.com/integrations/vscode) · [Cursor](https://docs.basicmemory.com/integrations/cursor) — local editor integrations - [CLI Reference](https://docs.basicmemory.com/reference/cli-reference) — every `bm cloud` command # Restore Lost Content You deleted a note you needed. A bulk reorganize went sideways. A teammate cleared out the wrong folder. Basic Memory Cloud has two recovery tiers — pick the one that matches what you lost. | Lost what? | Use | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **One note, recent edits** | [File history](https://docs.basicmemory.com/#file-history) — open the note and roll back from its version timeline | | **A folder, a project, or older content** | [Snapshots](https://docs.basicmemory.com/#snapshots) — find a snapshot from before the change and restore from it | Start with File history if you can — it's faster and works without leaving the note. Drop to Snapshots when the change is bigger than a single note or older than the note's recent history. --- ## File history File history is per-note. Every save creates a new version, so you can step back to any earlier state of a single note without touching anything else. ::steps ### Open the note Find and open the note in the [web app](https://docs.basicmemory.com/cloud/web-app). (If the note itself was deleted, skip ahead to [Snapshots](https://docs.basicmemory.com/#snapshots).) ### Open File history Click the **File history** icon (clock) in the note's toolbar. ### Pick the version you want Select a version from the timeline on the left. The diff on the right shows it side-by-side with the current note. ### Restore it Use the `>` revert controls in the diff to bring back exactly what you need (or just edit the right-side draft manually), then click **Apply**. This saves the merged content as a new version — your existing history stays intact. :: See [File History](https://docs.basicmemory.com/cloud/file-history) for the full reference, including who can apply and what to do if Apply is disabled. --- ## Snapshots Snapshots are project-wide point-in-time backups. Use them when you need to roll back more than one note — a deleted folder, a botched reorganization, or a project you wish you hadn't deleted. ::note{icon="i-lucide-info"} Basic Memory Cloud creates snapshots automatically every day, and you can create manual ones before risky changes. As long as the content existed in some snapshot, you can get it back. For the snapshots reference itself — what they are, retention, automatic vs manual — see [Cloud Snapshots](https://docs.basicmemory.com/cloud/cloud-snapshots) . :: ### 1. Find a snapshot from before the loss You need a snapshot that contains the content as it was *before* the deletion or change. ::code-group ```bash [CLI] bm cloud snapshot list ``` ```text [Web app] Settings → Snapshots ``` :: Pick the most recent snapshot with a timestamp **before** the change you regret. Note its ID (e.g. `snap_abc123`) — you'll use it in the restore step. ::tip Not sure when the loss happened? Pick the snapshot just before your last known-good edit. Worst case, restore a single file to a sandbox folder first and confirm it has what you expect before doing a bigger restore. :: --- ### 2. Look inside the snapshot Before restoring, peek at what the snapshot actually contains — it saves a step if it turns out the file isn't there. ```bash # List everything in the snapshot bm cloud snapshot browse snap_abc123 # List a specific folder bm cloud snapshot browse snap_abc123 --path notes/ # Show snapshot metadata bm cloud snapshot show snap_abc123 ``` The web app's snapshot browser does the same thing under **Settings → Snapshots → (snapshot)**. --- ### 3. Restore Restore is targeted — you pick the file, folder, or project you want back, not the whole snapshot. #### A single note ```bash bm cloud snapshot restore snap_abc123 --file notes/important.md ``` Or in the web app: browse the snapshot, find the file, choose **Restore**. #### A folder ```bash bm cloud snapshot restore snap_abc123 --path research/ ``` Restores everything under that path as it existed in the snapshot. #### A whole project If you lost most of a project — or deleted it — restore the project root: ```bash bm cloud snapshot restore snap_abc123 --path / ``` ::note **Restore is additive, not destructive.** Restored files are written back into the project. If a file with the same name exists in the live project, the restored version replaces it. Files in the live project that aren't in the snapshot are left alone — restore won't wipe newer work elsewhere in the project. :: ### 4. Verify After the restore, open the affected notes in the [app](https://docs.basicmemory.com/cloud/web-app) and confirm they look right. Spot-check a few: - File content matches what you expected. - Frontmatter intact (tags, type, status). - Wikilinks resolve to the right targets. If the restore didn't get you everything, try a different snapshot — there may be a more recent one that still has the content but also includes other changes you want to keep. --- ## What if I deleted a whole project? You can recover a deleted project the same way: find a snapshot from before the deletion, browse its `/` path, and restore the project root. The CLI is the most direct path here: ```bash bm cloud snapshot list bm cloud snapshot browse snap_abc123 --path my-project/ bm cloud snapshot restore snap_abc123 --path my-project/ ``` You may need to re-create the project entry in the workspace before the restored files appear as a live project — open the app, go to **Settings → Projects**, and verify. --- ## What if the snapshot is too old? Snapshots cover the recent history of your cloud workspace. If the content you want is older than your retention window, two backstops: - **Local sync mirror.** If you had [hybrid editing](https://docs.basicmemory.com/cloud/edit-locally-and-in-the-app) set up, your local folder is an independent copy. Check there. - **A project ZIP download.** If you'd previously downloaded the project as a ZIP (Manage Projects → Download), unpack it locally and re-upload to the project. For ongoing safety: take a manual snapshot before any change you might want to roll back. They're free and instant. ```bash bm cloud snapshot create "Before reorganizing research/" ``` --- ## Related - [File History](https://docs.basicmemory.com/cloud/file-history) — per-note version timeline and diff/merge restore - [Cloud Snapshots](https://docs.basicmemory.com/cloud/cloud-snapshots) — the full snapshot reference (creation, retention, browsing, CLI options) - [Edit Locally and in the App](https://docs.basicmemory.com/cloud/edit-locally-and-in-the-app) — bidirectional sync gives you a local backstop - [Copy Content Between Workspaces](https://docs.basicmemory.com/teams/copy-between-workspaces) — for restoring from a downloaded project ZIP - [CLI Reference](https://docs.basicmemory.com/reference/cli-reference) — every `bm cloud snapshot` command # File History Every saved version of a note is preserved automatically in Basic Memory Cloud. Open **File history** on any note to see its full timeline, compare an earlier version side-by-side with the current one, and apply changes back into the live note. It's the fast, per-note answer to "I want to undo something" — distinct from [Snapshots](https://docs.basicmemory.com/cloud/cloud-snapshots), which are project-wide point-in-time backups. ::note{icon="i-lucide-history"} File history is a cloud feature. Versions are created automatically on every save — no setup, nothing to turn on. :: --- ## Open File history In the [web app](https://docs.basicmemory.com/cloud/web-app), open the note you want to look back at, then click the **File history** icon (clock) in the note's toolbar. :theme-image{alt="File history button in the note toolbar" dark="/screenshots/cloud-app/v2-file-history-button-dark.png" light="/screenshots/cloud-app/v2-file-history-button-light.png"} A modal opens with two panes: - **Left**: the timeline of versions, newest first. Each row shows the timestamp, a short version ID, and the file size. The latest version is marked **Current**. - **Right**: a side-by-side **diff** between the version you've selected (read-only, on the left of the diff) and the current note (editable, on the right). :theme-image{alt="File history modal with version timeline and diff" dark="/screenshots/cloud-app/v2-file-history-dialog-dark.png" light="/screenshots/cloud-app/v2-file-history-dialog-light.png"} Select a version on the left to load it into the diff. Use **Load more** at the bottom of the list if you have a long history. --- ## Restore (or merge) an old version The diff view isn't just a viewer — the right side is a live, editable draft of what your note will become when you click **Apply**. You have two ways to bring old content forward: - **Pick exactly what you want.** Use the `>` revert controls in the diff to accept individual changes from the old version into the draft. - **Edit the draft directly.** Type into the right pane to make manual tweaks before applying. When the draft looks right, click **Apply**. That saves the merged content as a **new** version — it doesn't overwrite or rewind history. Your existing versions stay intact, with the freshly applied content sitting on top as the new Current. ::note **Apply creates a new version, not a rollback.** If you change your mind, just open File history again and merge back from any earlier version. Nothing's ever lost. :: ### When Apply is disabled A few states will gray out the **Apply** button: - **Unsaved edits in the main editor.** Save your current draft first, then apply from history. - **"File history is catching up."** Your most recent save hasn't reached the storage layer yet. Wait a moment and refresh. - **"Current file version changed; refresh before applying."** Someone (or something) wrote the note while you were merging. Refresh history and reapply on top of the new current. --- ## Who can see and use it - **View history** — anyone with read access to the note (viewers, editors, owners). - **Apply a version** — anyone with edit access (editors and owners). Viewers can browse history but can't write. In a [team workspace](https://docs.basicmemory.com/teams/about), this follows the project's normal access rules. --- ## File history vs. Snapshots | | File history | [Snapshots](https://docs.basicmemory.com/cloud/cloud-snapshots) | | ------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------- | | **Scope** | One note at a time | The whole project / workspace | | **Created** | Automatically on every save | Automatically daily + manually on demand | | **Use it for** | "I want to undo the last few changes to this note" | "I want to roll back a bulk reorganization" or "I deleted a folder by accident" | | **Restore creates** | A new version of the note | Files written back into the live project | | **Best for** | Granular per-note recovery | Project-scale recovery | Both work alongside each other — start with File history for a single note, fall back to a Snapshot when you need a bigger rollback. See [Restore Lost Content](https://docs.basicmemory.com/cloud/restore-lost-content) for a recovery decision guide. --- ## Under the hood File history is built on **object versioning** in our underlying storage (Tigris). Each save writes a new object version, so every meaningful state of every note is preserved — without any extra storage choreography on your part. For more on the architecture, see the Tigris case study: [Own Your AI Context with Basic Memory](https://www.tigrisdata.com/blog/case-study-basic-memory/){rel=""nofollow""}. --- ## Related - [Restore Lost Content](https://docs.basicmemory.com/cloud/restore-lost-content) — when to use File history vs. Snapshots - [Cloud Snapshots](https://docs.basicmemory.com/cloud/cloud-snapshots) — project-wide point-in-time backups - [Web App](https://docs.basicmemory.com/cloud/web-app) — the editor and surrounding UI - [Teams](https://docs.basicmemory.com/teams/about) — permissions in a shared workspace # Basic Memory Teams Basic Memory Teams gives your team a single, shared cloud workspace. Knowledge isn't confined to one person — anything a teammate writes is immediately available to everyone else and to their AI assistants. Edit a note together in real time, hand work off between humans and agents, and build one connected knowledge base instead of scattered copies. ::note{icon="i-lucide-users"} **Teams requires a subscription with one or more seats.** Billing is per seat. Joining or starting a team doesn't change anything about your existing setup — your personal cloud subscription (if you have one) and any local projects keep working exactly as before. Teams adds an organization workspace alongside them. :: --- ## Workspaces Your account can have more than one workspace. Each keeps its own projects, notes, and members. | Workspace | Who can access it | Notes | | ------------------ | ------------------------- | ------------------------------------------------ | | **Local** | Just you, on your machine | No team features; runs entirely on your computer | | **Personal Cloud** | Just you | Your personal cloud subscription and notes | | **Organization** | Your team | Shared projects, members, roles, and seats | Switch between workspaces using the workspace selector in the app. Projects and notes are scoped to the workspace you're in. --- ## Roles Every member of an organization workspace has a role that determines what they can do. | Role | Can do | | ---------- | ----------------------------------------------------------------------------------------------------- | | **Owner** | Everything an editor can, plus manage members and invitations, manage billing, and transfer ownership | | **Editor** | Read and write notes, and manage invitations | | **Viewer** | Read-only access to shared projects | Members also have a **status**: - **Pending** — invited, but hasn't finished linking their account yet - **Active** — full access according to their role - **Deactivated** — removed from the team; their history is preserved and their seat is released :theme-image{alt="Team members list" dark="/screenshots/cloud-app/v2-settings-teams-dark.png" light="/screenshots/cloud-app/v2-settings-teams-light.png"} --- ## Working together in real time When two people open the same note, they see each other's edits as they happen. The editor is built on CRDTs (Yjs), so every keystroke syncs instantly across collaborators with no merge conflicts to resolve. A presence avatar appears in the note header for each active collaborator — each one gets a distinct color so you can tell at a glance who's typing where. ### AI agents as collaborators ::note{icon="i-lucide-sparkles"} **Coming soon.** AI agents will join as first-class collaborators alongside your team. :: Once available, you'll connect an agent to a note and it shows up in the same presence list as your teammates with a live status indicator — *working*, *just updated*, or *waiting for input*. Agents read the shared knowledge graph for context and write structured observations and relations back into it, so the more your team uses Basic Memory, the better your AI gets at answering from your team's actual knowledge. ### Activity feed The **Activity** view in the app keeps you aware of what's happening across the workspace. It shows operations in progress (imports, indexing, large edits) and recent completed changes — from every team member and agent — with direct links to the affected notes. --- ## File history — undo on the file level Every save creates a new version of a note, automatically. If a teammate overwrites something or an agent edits go sideways, open **File history** on the note to step back through the timeline, compare any version against the current one, and merge content back in. Restored content saves as a *new* version, so nothing is ever lost. See [File History](https://docs.basicmemory.com/cloud/file-history) for the full reference, or [Restore Lost Content](https://docs.basicmemory.com/cloud/restore-lost-content) for the broader recovery decision guide (File history for a single note, Snapshots for bigger rollbacks). --- ## Inviting members Owners invite people by email from **Settings → Teams**. :theme-image{alt="Invite a member" dark="/screenshots/cloud-app/v2-team-invite-dark.png" light="/screenshots/cloud-app/v2-team-invite-light.png"} To invite a member, click the "Invite Member" button. ::steps ### Send an invitation Enter the person's email address and choose a role (Editor or Viewer). They'll receive an email with an invitation link. :theme-image{alt="Team invitation email" dark="/screenshots/cloud-app/v2-team-invitation-dark.png" light="/screenshots/cloud-app/v2-team-invitation-light.png"} ### They receive an email The invitee gets an email invitation. :theme-image{alt="Email invitation" dark="/screenshots/cloud-app/v2-team-accept-invite-email.png" light="/screenshots/cloud-app/v2-team-accept-invite-email.png"} Click the accept button. ### They accept The link opens an accept page. The invitee signs in (or creates an account) using the email the invitation was sent to. If they're already signed in with a different account, they'll be asked to sign in again with the invited email. :theme-image{alt="Accept an invitation" dark="/screenshots/cloud-app/v2-team-accept-invite-dark.png" light="/screenshots/cloud-app/v2-team-accept-invite-light.png"} ### Account linking On first sign-in, their authenticated account is linked to the pending membership, and they become an active member. :: ::note{icon="i-lucide-credit-card"} **Seats are assigned when an invitation is claimed, not when it's sent.** Inviting someone doesn't consume a seat until they accept — so a pending invitation won't be billed until the person joins. :: ::tip **For invitees:** see [Joining a Team Workspace](https://docs.basicmemory.com/teams/join-a-team) for a step-by-step walkthrough of accepting the invite, switching workspaces, and connecting your AI assistant. :: --- ## Managing members From **Settings → Teams**, an owner can: - **Change a member's role** — promote a viewer to editor, or vice versa. - **Deactivate a member** — removes their access and frees their seat. Their authored history stays intact. - **Reactivate a member** — restores access, reassigning a seat if one is available. - **Transfer ownership** — hand the workspace (and its subscription) to another member. The new owner takes over billing and management. --- ## Seats and billing Teams billing is **per seat**. The number of seats on your subscription sets how many active members the workspace can have. - Each active member occupies one seat. - Deactivating a member frees their seat for someone else. - Reactivating a member requires an available seat. - Pending invitations don't consume a seat until they're accepted. - If your team grows past your current seat allocation, there's a **14-day grace period** before any restrictions kick in — so a new hire never gets locked out while you're adding seats. Manage seats and payment from **Settings → Billing**. :theme-image{alt="Seats and billing" dark="/screenshots/cloud-app/v2-team-manage-billing-dark.png" light="/screenshots/cloud-app/v2-team-manage-billing-light.png"} Track current seat usage from the same screen: :theme-image{alt="Team seat usage" dark="/screenshots/cloud-app/v2-team-usage-dark.png" light="/screenshots/cloud-app/v2-team-usage-light.png"} --- ## Projects Team projects come in three visibilities. The right one depends on who needs to see the work: | Visibility | Who can see it | When to use | | -------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | **Standard** (`workspace`) — *default* | Everyone in the organization, based on their workspace role (viewer/editor/owner) | Most team work — the open, shared knowledge base | | **Shared** (`shared`) | Only people you grant access to, each at **editor** or **viewer** level | Sensitive topics (hiring, contracts, security audits) where you want a controlled group | | **Private** (`private`) | Only the creator | Personal scratch space inside the team workspace | When you create a cloud project, you can set its visibility from the CLI: ```bash # Standard — visible to everyone in the team workspace (default) bm project add team-wiki --cloud --workspace acme --visibility workspace # Shared — only people you grant access to bm project add hiring-2026 --cloud --workspace acme --visibility shared # Private — just you bm project add my-scratch --cloud --workspace acme --visibility private ``` See the [CLI Reference](https://docs.basicmemory.com/reference/cli-reference) for full `bm project add` options. --- ## Bringing existing notes into a team workspace When you join (or start) a team, you'll often want to promote work from your personal workspace into the shared one. Cross-workspace transfers are a **copy** workflow — export from the source, import into the target, verify, then optionally delete the original. See [Copy Content Between Workspaces](https://docs.basicmemory.com/teams/copy-between-workspaces) for the project ZIP, single-note, MCP, and local-sync workflows, along with caveats around wikilinks, permissions, and share links. --- ## Working with team projects Once you're part of a team workspace, team projects show up everywhere you work: - **In the app** — switch to the organization workspace and your shared projects appear in the sidebar. - **In your AI assistant (MCP)** — your assistant's project list spans every cloud workspace you can access, so it reaches team projects without extra setup. See [v0.21.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.21.0){rel=""nofollow""} for details on cross-workspace discovery. - **In the CLI** — `bm project list` shows projects across all your workspaces. ### Workspace commands ```bash # List the cloud workspaces available to you bm cloud workspace list # Set the default workspace for CLI and MCP routing bm cloud workspace set-default acme ``` You can also target a specific workspace when creating a project, either from the CLI (`--workspace`) or from MCP (`create_memory_project(workspace="acme")`). --- ## Security and isolation Each organization gets its **own** isolated database and file storage in the cloud — there is no shared tenancy at the data layer. Your team's knowledge is physically separated from every other team's. Authentication runs through [WorkOS AuthKit](https://workos.com/authkit){rel=""nofollow""} for enterprise-grade identity management. --- ## Next Steps ::card-group :::card --- icon: i-lucide-layout-dashboard title: Web App to: https://docs.basicmemory.com/cloud/web-app --- Browse, edit, and collaborate on notes in the app. ::: :::card --- icon: i-lucide-route title: Local & Cloud Routing to: https://docs.basicmemory.com/cloud/routing --- Run some projects locally and others in the cloud. ::: :::card --- icon: i-lucide-terminal title: CLI Reference to: https://docs.basicmemory.com/reference/cli-reference --- Full `bm project` and `bm cloud workspace` commands. ::: :::card --- icon: i-lucide-megaphone title: What's New in v0.22.0 to: https://docs.basicmemory.com/whats-new/v0.22.0 --- Team-safe cloud push and pull. ::: :: # Joining a Team Workspace You got an invite to a Basic Memory [team workspace](https://docs.basicmemory.com/teams/about). This page walks through what to do on day one — accept the invite, get into the workspace, find the shared projects, and point your AI assistant at the same knowledge base. ::note **You'll need a Basic Memory account on the email address the invite was sent to.** If you don't have one yet, the accept flow walks you through creating it. :: --- ## 1. Accept the invitation Open the invitation email and click the **Accept invitation** link. It opens an accept page in the app. - Sign in with the email the invite was sent to. - If you're already signed in with a different account, the app will prompt you to sign in again with the invited email. - If this is your first time, you'll create an account during sign-in. On first sign-in, your account is linked to the pending membership, and you become an active team member. --- ## 2. Switch to the team workspace Open the app at [app.basicmemory.com](https://app.basicmemory.com){rel=""nofollow""}. Use the **workspace selector** to switch from your personal workspace to the team's organization workspace. - Each workspace has its own sidebar, projects, and notes. - Switch back to personal anytime — your personal work isn't visible to teammates. --- ## 3. Find the shared projects In the team workspace, the sidebar shows the projects you have access to. Open one to see its folders and notes. Your **role** determines what you can do: | Role | You can | | ---------- | ------------------------------------------------------------------------------ | | **Viewer** | Read shared projects | | **Editor** | Read and write shared projects; create new notes; manage invitations | | **Owner** | Everything an editor can, plus manage members, billing, and project visibility | Not sure of your role? Open **Settings → Teams** to see it next to your name. If you need a different role, ask an owner. --- ## 4. Connect your AI assistant Your assistant works with the team workspace through the same MCP endpoint as your personal cloud. Pick the path that matches your tool: - **Claude Desktop / Claude Code** — see [Claude Desktop](https://docs.basicmemory.com/integrations/claude-desktop) or [Claude Code](https://docs.basicmemory.com/integrations/claude-code). Use the OAuth flow; your assistant will see team projects automatically once you've accepted the invite. - **ChatGPT** — see [ChatGPT](https://docs.basicmemory.com/integrations/chatgpt). - **Codex / Cursor / VS Code / Obsidian** — see the [integrations index](https://docs.basicmemory.com/integrations/claude-desktop). - **CLI** — `bm cloud login` once, then `bm project list` shows projects across every workspace you can access (personal and team). ::tip With v0.21, your assistant's project list spans **every** workspace you can reach, so team projects show up without extra configuration. See [v0.21.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.21.0){rel=""nofollow""} for the cross-workspace discovery story. :: ### Targeting the team workspace explicitly If you want a CLI command or MCP call to act on a team project (and avoid ambiguity with a same-named personal project), be explicit: ```bash # Make the team workspace your default bm cloud workspace set-default acme # Or target it per command bm project list --workspace acme ``` From MCP, pass the workspace through `create_memory_project(workspace="acme")` or use a [project-prefixed permalink](https://docs.basicmemory.com/concepts/memory-urls). --- ## 5. Get oriented A few good first steps in any new team workspace: - **Browse the project tree** to see what your team already has. - **Search a topic you care about** — see what's already been written. - **Pin** the projects or notes you'll come back to. - **Read the team's conventions** if they've documented any (look for an `onboarding`, `README`, or `team-norms` note). --- ## Bringing your existing notes with you Already have personal notes you want to share with the team? Cross-workspace transfer is a **copy** workflow — see [Copy Content Between Workspaces](https://docs.basicmemory.com/teams/copy-between-workspaces) for the project ZIP, single-note, and MCP recipes. --- ## Related - [Teams](https://docs.basicmemory.com/teams/about) — workspaces, roles, invitations, billing - [Web App](https://docs.basicmemory.com/cloud/web-app) — the three-pane editor and shortcuts - [Copy Content Between Workspaces](https://docs.basicmemory.com/teams/copy-between-workspaces) — bring personal notes into the team workspace - [Integrations](https://docs.basicmemory.com/integrations/claude-desktop) — connect your AI assistant # Copy Content Between Workspaces You'll often want to promote work from your personal workspace into a [team workspace](https://docs.basicmemory.com/teams/about), or pull team content back into a personal one. Today, this is a **copy-then-(optionally)-delete** workflow rather than an atomic move — you export from the source, import into the target, verify, and only then remove the original if you wanted a true move. ::note{icon="i-lucide-info"} **There is no built-in cross-workspace "Move to…" action yet.** Workspaces have separate auth and storage boundaries, so cross-workspace transfers are explicit copies. Use the workflows below. :: --- ## Before you start A few things to know about any cross-workspace copy: - **You need read access** to the source project and **write access** (editor or owner) to the target project. - **Imported content takes on the target's permissions.** It picks up the target workspace's project visibility, sharing rules, and member access. Source-side permissions don't follow it. - **Share links don't follow content.** Existing [Shared Notes](https://docs.basicmemory.com/cloud/shared-notes) links live on the original. If you want a shared link in the new location, create one there after importing. - **Wikilinks are preserved as text.** A `[[Wiki Link]]` only *resolves* in the target workspace if the linked note is also present there. For best results, **copy linked notes together** so the graph stays intact. - **Verify before you delete.** Treat the source as a backup until you've confirmed the imported content looks right in the target. --- ## Copy a whole project The safest workflow for project-sized content. You'll end up with a clean copy in the target workspace with all folders and notes intact. ::steps ### Export from the source In the app, switch to the **source workspace** and open **Settings → Projects**. From the source project's `⋮` menu, choose **Download** — you'll get a project ZIP. ### Switch to the target Switch to the **target workspace** in the workspace selector. ### Import the ZIP Open **Settings → Import** and choose the project ZIP option. Pick the writable target project (or create a new one) and an optional destination folder. ### Watch indexing finish The import runs in the background. Watch the activity until indexing completes so you know the new notes are searchable. ### Verify Open the imported notes in the target workspace and confirm everything looks right — content, frontmatter, folder structure, links. ### Delete the source (optional) If your intent was a move, delete the original project from the source workspace **after** you've verified the target copy. :: --- ## Copy a single note or small batch For one note or a handful, the simplest path is download + upload. ::steps ### Download from the source In the source project, open a note's `⋮` menu → **Download** to save it as a `.md` file. Repeat for any other notes you want to bring along. (Tip: copy linked notes together so wikilinks stay resolvable.) ### Upload into the target Switch workspaces, open the target project, and upload the `.md` files into the target folder. ### Verify Open the copied notes and check everything looks right. ### Delete the source (optional) Remove the originals from the source project once you're satisfied. :: --- ## Copy with MCP MCP doesn't expose an atomic cross-project or cross-workspace move. Express it as **read → write → (optionally) delete** instead. Your AI assistant can drive this for you, or you can run the tools directly. ```text read_note("source note", project="source-project") write_note("Note Title", "", "target-folder", project="target-project") delete_note("source note", project="source-project") # optional, only after verifying ``` A few notes on this pattern: - Pass `project` on each call so the read and write hit the right place. In a team setup, use a [project-prefixed permalink](https://docs.basicmemory.com/concepts/memory-urls) or workspace-qualified routing to be unambiguous. - For many notes, loop the read/write pair — there's no batch move, but the pattern is straightforward to script. - Don't `delete_note` until the new copy is in place and verified. Treat this as **copy-then-optional-delete**, never as a transactional move. See the [MCP Tools Reference](https://docs.basicmemory.com/reference/mcp-tools-reference) for full parameter details on each tool. --- ## Copy via local sync (power-user) If both projects already have [local sync](https://docs.basicmemory.com/cloud/cloud-sync) set up, you can move files in the filesystem and let bisync push them up: 1. Run `bm cloud bisync` for both projects so each is up to date locally. 2. In your file manager (or with `cp -r`), copy the notes or folder from the source project's local path into the target project's local path. 3. Run `bm cloud bisync --name ` to push the new files to the target workspace. 4. Verify in the app, then delete from the source side and bisync again. This is the fastest option when you have lots of notes and both projects already sync to your machine. --- ## What about renaming or restructuring? Within a single workspace, you can rename and move notes and folders freely from the app or with `move_note`. Cross-workspace, do the copy first, then reorganize on the target side. --- ## Related - [Teams](https://docs.basicmemory.com/teams/about) — workspaces, roles, and project sharing - [Web App](https://docs.basicmemory.com/cloud/web-app) — projects, downloads, and imports - [Cloud Sync](https://docs.basicmemory.com/cloud/cloud-sync) — bidirectional sync setup - [Shared Notes](https://docs.basicmemory.com/cloud/shared-notes) — public links for individual notes - [MCP Tools Reference](https://docs.basicmemory.com/reference/mcp-tools-reference) — `read_note`, `write_note`, `delete_note` # Local install Local mode runs the MCP server on your machine and stores notes in local folders you control. ## Install the CLI ::code-group ```bash [uv] uv tool install basic-memory ``` ```bash [homebrew] brew tap basicmachines-co/basic-memory brew trust basicmachines-co/basic-memory brew install basic-memory ``` :: ::note If you install with Homebrew: `brew trust` tells Homebrew you accept code from this third-party tap. Recent Homebrew versions warn about untrusted taps, and Homebrew 6 will require the trust step before installing or upgrading from them. On older Homebrew versions the command doesn't exist yet — just skip it. :: ## Start the MCP server Configure your MCP client to run the server: ```json [claude_desktop_config.json] { "mcpServers": { "basic-memory": { "command": "uvx", "args": ["basic-memory", "mcp"] } } } ``` Restart your MCP client after editing the config. ## Choose where notes live By default, notes are stored in a `main` project under `~/basic-memory`. You can point Basic Memory to any folder by creating a project and setting it as default. ```bash bm project add "work" ~/Documents/work-notes bm project default "work" ``` ## Next steps ::card-group :::card --- icon: i-lucide-terminal title: CLI Basics to: https://docs.basicmemory.com/local/cli-basics --- Learn common commands for projects, notes, and search. ::: :::card --- icon: i-lucide-folder title: Projects and Folders to: https://docs.basicmemory.com/concepts/projects-and-folders --- Organize notes with projects and folder structure. ::: :: # CLI basics The CLI is the fastest way to manage projects and run MCP tools directly from the terminal. ## Use the short alias `bm` is a short alias for `basic-memory`. ## List and create projects ```bash bm project list bm project add "research" ~/Documents/research ``` ## Set the default project ```bash bm project default "research" ``` ## Search notes ```bash bm tool search-notes "authentication" ``` Semantic modes: ```bash bm tool search-notes "authentication architecture" --hybrid bm tool search-notes "login flow" --vector ``` ## Read and write notes ```bash bm tool read-note "docs/api-auth.md" echo "New note content" | bm tool write-note --title "Notes" --folder "drafts" ``` ## Schema workflows ```bash bm schema infer person bm schema validate person bm schema diff person ``` ## Format files ```bash bm format bm format --project research bm format notes/meeting.md ``` ## Next steps ::card-group :::card --- icon: i-lucide-terminal title: CLI Reference to: https://docs.basicmemory.com/reference/cli-reference --- Complete command reference with all options. ::: :::card --- icon: i-lucide-wrench title: MCP Tools (Local) to: https://docs.basicmemory.com/local/mcp-tools-local --- Learn how assistants use tools locally. ::: :: # MCP tools (local) MCP tools are the same in Cloud and Local. In local mode, they operate on folders on your machine. ## Use tools in local mode When you run the local MCP server, tools read and write local project folders by default. ## Common tools - `search_notes` to find notes - `read_note` to load a note - `write_note` to create or update a note - `edit_note` to append or replace sections - `schema_validate`, `schema_infer`, `schema_diff` for schema workflows - `build_context` for memory URL graph traversal `search_notes` and `read_note` also support terminal-friendly formats: - `output_format=\"default\"` (structured) - `output_format=\"ascii\"` (plain table/preview) - `output_format=\"ansi\"` (colorized table/preview) ## Example ```python search_notes(query="architecture", project="main") ``` ## Next steps ::card-group :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- Complete tool documentation with all parameters. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Learn about note structure and semantic patterns. ::: :: # User Guide This guide covers everything from creating your first notes to building a comprehensive knowledge graph. ::tip Using Basic Memory Cloud? Your notes are automatically synced and accessible from anywhere. See the [Cloud Guide](https://docs.basicmemory.com/cloud/cloud-guide) for setup and the [Web App](https://docs.basicmemory.com/cloud/web-app) for browser-based editing. :: --- ## Basic Memory Workflow Using Basic Memory follows a natural cycle: ::mermaid --- code: | flowchart LR A[Conversation] --> B[Capture] B --> C[Connect] C --> D[Reference] D --> E[Edit] E --> F[Sync] F --> A --- :: 1. **Have conversations** with AI assistants like Claude 2. **Capture knowledge** in Markdown files 3. **Build connections** between pieces of knowledge 4. **Reference your knowledge** in future conversations 5. **Edit files directly** when needed 6. **Sync changes** automatically --- ## Creating Knowledge ### Through Conversations The most natural way to create knowledge is during conversations: ```bash 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 knowledge base. ::tip You can store your knowledge at any location. `~/basic-memory` is the default project location. See [Getting Started](https://docs.basicmemory.com/start-here/getting-started#choosing-where-your-notes-are-saved) for more information. :: ### Direct File Creation You can also create files directly: 1. Create a new Markdown file in your project directory 2. Add frontmatter with title, type, and optional tags 3. Structure content with observations and relations 4. Save the file - it syncs automatically **Example file structure:** ```bash --- 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: ```bash "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: ```bash "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: ```bash "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 ```bash 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: ```bash You: "Take a look at memory://coffee-brewing-methods and let's discuss improvements" ``` Claude will load that specific document and any related context. ::tip Memory URLs are stable identifiers. Even if you rename or move a file, the permalink stays the same (unless you configure otherwise). :: --- ## Building Knowledge Connections ### Creating Relations Use WikiLink syntax to connect knowledge: ```bash ## Relations - implements [[Authentication System]] - requires [[Database Schema]] - relates_to [[Security Guidelines]] ``` ### Common Relation Types | Type | Use for | | ------------- | ---------------------------- | | `implements` | One thing implements another | | `requires` | Dependencies | | `relates_to` | General connections | | `part_of` | Hierarchy relationships | | `extends` | Extensions or enhancements | | `pairs_with` | Things that work together | | `inspired_by` | Source of ideas | | `replaces` | Supersedes another document | ### Adding Observations Structure facts with semantic categories: ```bash ## 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 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:** ```bash 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. ``` ### Single Project Users If you only use one project, you can skip the selection prompt. Add this to `~/.basic-memory/config.json`: ```json { "default_project": "main" } ``` This sets your fallback project when no explicit project is passed. You can still override by specifying a different project. ### Single Project Mode (Locked) For focused sessions or automation, lock the MCP server to one project: ```bash basic-memory mcp --project work-notes ``` This **locks** the entire MCP session - the `project` parameter in tool calls will be ignored. **When to use:** - Automation workflows that should only access one project - Focused sessions where you want to prevent cross-project operations - Team environments with project-specific access ::note **Key difference:** - **Default project fallback**: Uses `default_project` when no project is specified, but can still switch - **Single Project Mode**: Locked to one project, cannot switch :: ### Moving Notes Between Projects ::warning Moving notes from one project to another is not currently supported directly. The easiest approach is to: 1. Copy the file manually between project directories 2. Or create a new note in the destination project, then delete the original :: --- ## File Organization ### Directory Structure Organize files in any structure that suits you: ```bash ~/basic-memory/ ├── 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 ### Controlling What Gets Indexed Basic Memory respects `.gitignore` patterns to skip sensitive files. **Pattern sources:** - **Global patterns**: `~/.basic-memory/.bmignore` (all projects) - **Project patterns**: `{project}/.gitignore` (specific project) **Example `.gitignore`:** ```gitignore # Sensitive files .env *.key credentials.json # Build artifacts node_modules/ __pycache__/ dist/ # OS files .DS_Store Thumbs.db ``` Files matching these patterns are automatically skipped during indexing. --- ## Enhanced Editing ### Incremental Editing Edit notes without rewriting entire documents: ```bash 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 ### Smart File Organization Move and rename notes with database consistency: ```bash 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." ``` ### Directory Operations Move or delete entire folders: ```bash You: "Move the old-projects folder to archive" Claude: [Uses move_note with is_directory=true] "Moved old-projects/ → archive/old-projects/ (15 files)" You: "Delete the empty temp folder" Claude: [Uses delete_note with is_directory=true] "Deleted temp/ and all 3 contained files" ``` ### Enhanced Search Tags and frontmatter fields are searchable. Use `tag:` shorthand or metadata filters to narrow results: ```bash You: "Find all my notes tagged with security" Claude: [Uses search_notes with query="tag:security"] You: "Show me in-progress specs" Claude: [Uses search_notes with note_types=["spec"], metadata_filters={"status": "in-progress"}] You: "Find high priority items from this year" Claude: [Uses search_notes with metadata_filters={"priority": {"$in": ["high", "critical"]}}, after_date="2026-01-01"] ``` You can also search purely by metadata — no text query needed: ```bash You: "What notes have status draft?" Claude: [Uses search_notes with status="draft"] ``` --- ## Schema Workflows As your knowledge base grows, you may want consistent structure for certain note types. Schemas let you define what a "good" note of a particular type should contain, then validate notes against that definition. **Conversational example:** ```bash You: "I've been writing a lot of person notes. Can you help me standardize them?" Claude: Let me analyze your existing person notes to find common patterns. [Uses schema_infer with note_type="person"] Based on your notes, here's what most of them include: - name (in 95% of notes) - role (in 80%) - works_at relation (in 60%) I can create a schema note that formalizes this pattern. Would you like me to save it? You: "Yes, and validate my existing notes against it" Claude: [Creates schema note, then validates] 3 of your 15 person notes are missing the [name] observation. Here are the ones that need updating... ``` See the [Schema System](https://docs.basicmemory.com/concepts/schema-system) guide for full details on picoschema syntax, validation modes, and the infer-validate-diff lifecycle. --- ## Semantic Search Semantic search lets you find notes by meaning rather than exact keywords. This is helpful when you remember the concept but not the exact words used in the note. **Conversational example:** ```bash You: "Find my notes about making the app faster" Claude: [Uses search_notes with search_type="hybrid"] I found several relevant notes: 1. "React Performance Optimization" — contains observations about bundle size and lazy loading 2. "Database Query Tuning" — discusses index strategies and query plans 3. "Caching Architecture" — your design decisions for the Redis cache layer Would you like me to build context from any of these? ``` Semantic search is included by default. Embeddings are generated automatically on first startup. See the [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search) guide for configuration details. --- ## Syncing and Updates ### Real-time Sync Basic Memory automatically syncs file changes in real-time. When you edit a file in your editor: 1. The change is detected within \~1 second 2. The file is re-parsed for observations and relations 3. The database is updated 4. Search index is refreshed No manual sync needed for normal workflows. ### Checking Status ```bash # View sync status basic-memory status # View project information basic-memory project info ``` ### Force Re-sync If something seems out of sync: ```bash # Re-sync all files basic-memory sync # Reset and rebuild database (use if issues persist) basic-memory reset ``` ::warning `basic-memory reset` rebuilds the entire database from your files. This is safe (files are never deleted) but may take time for large knowledge bases. :: --- ## Integration Tips ### With Obsidian 1. Open your `~/basic-memory` directory as an Obsidian vault 2. Use **Graph View** to visualize connections 3. Edit files directly in Obsidian 4. Changes sync automatically - ask the AI to read a note to see updates ![Obsidian graph view](https://docs.basicmemory.com/attachments/obsidian-coffee.png) ::tip Obsidian's graph view is excellent for discovering unexpected connections in your knowledge base. :: ### With Git Basic Memory files are git-friendly: ```bash cd ~/basic-memory git init git add . git commit -m "Initial knowledge base" ``` Benefits: - Version history for all changes - Backup to GitHub/GitLab - Collaborate with others - Track what changed over time ### With Other Editors Basic Memory uses standard Markdown that works with: - **VS Code** with Markdown extensions - **Typora** for rich text editing - **Any text editor** for quick edits - **Web editors** for remote access The database syncs regardless of how you edit files. --- ## 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. **Backup regularly** - Use git, cloud sync, or snapshots --- ## Troubleshooting ### Changes Not Syncing 1. Check sync status: `basic-memory status` 2. Verify file permissions 3. Check if file matches ignore patterns 4. Reset database: `basic-memory reset` ### Claude Can't Find Knowledge 1. Confirm files are in correct project directory 2. Check frontmatter formatting (valid YAML) 3. Use `memory://` URLs for direct references 4. Trigger re-sync: `basic-memory sync` ### Performance Issues 1. Check database size: `basic-memory project info` 2. Archive old content 3. Adjust sync delay in config (default: 1000ms) ### Getting Help - **Discord**: [discord.gg/tyvKNccgqN](https://discord.gg/tyvKNccgqN){rel=""nofollow""} - #help channel - **GitHub**: [github.com/basicmachines-co/basic-memory/issues](https://github.com/basicmachines-co/basic-memory/issues){rel=""nofollow""} ```bash # View all commands basic-memory --help # Help for specific commands basic-memory sync --help basic-memory project --help ``` --- ## Next Steps ::card-group :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Learn the semantic patterns for observations and relations. ::: :::card --- icon: i-lucide-settings title: Configuration to: https://docs.basicmemory.com/reference/configuration --- All configuration options and environment variables. ::: :::card --- icon: i-lucide-terminal title: CLI Reference to: https://docs.basicmemory.com/reference/cli-reference --- Complete command line tools reference. ::: :::card --- icon: i-lucide-hexagon title: Obsidian Integration to: https://docs.basicmemory.com/integrations/obsidian --- Visual knowledge navigation with graph view. ::: :: # Using Basic Memory with Built-in AI Memory Your AI tools already have built-in memory features. Basic Memory doesn't replace them — it works alongside them. This page explains what each system is good at and how to use them together effectively. For a broader comparison of Basic Memory with all the alternatives — including Obsidian, database-only memory services, and more — see [Why Basic Memory](https://docs.basicmemory.com/start-here/why-basic-memory). --- ## What each tool offers **Claude** (web, desktop, and mobile) has a memory system available to all users: - **Memory summary** — Claude automatically synthesizes a summary of you from your chat history, refreshed roughly every 24 hours. You can view and edit it (Settings → Capabilities → "View and edit memory"), or update it just by asking Claude in chat. - **Project memory** — Each Claude Project gets its own isolated memory space and summary. - **Chat search** — Claude can also search your raw conversation history. Controls include pausing memory, resetting it, and incognito chats. **Claude Code** has two built-in systems: - **CLAUDE.md files** — Instructions you write for how Claude should work in a project. Coding standards, build commands, architectural conventions. - **Auto memory** — Notes Claude writes itself when it notices patterns or preferences. Stored in `~/.claude/projects/` as markdown files. The first 200 lines of `MEMORY.md` load into every session. **ChatGPT** has two memory systems: - **Saved memories** — Facts you tell it to remember ("I'm vegetarian," "I live in San Francisco"). These persist until you delete them, and total capacity is limited to roughly 1,200–1,400 words — once full, nothing new is saved until you delete entries. ChatGPT may also save details on its own if they seem useful. The Manage Memories panel lets you view and delete entries; to change one, ask ChatGPT in chat. - **Reference chat history** — ChatGPT can look back at past conversations to pick up preferences and context. Unlike saved memories, these details change over time as ChatGPT decides what's most relevant. **Cursor** has a "Memories" feature for storing brief preference strings and rules. **Basic Memory** is a full knowledge base with structured notes, semantic search, a knowledge graph, and schemas. It works across all of these tools through MCP. --- ## How they work together The best setup uses both. Here's how they complement each other: | | Built-in memory | Basic Memory | | --------------- | -------------------------------------- | ------------------------------------------- | | **Best for** | Quick preferences, tool-specific rules | Structured knowledge, decisions, research | | **Scope** | One AI tool | Every AI tool you use | | **Source** | That tool's own chats | Anything — chats, docs, your own writing | | **Format** | Short summaries / instructions | Full markdown notes with semantic structure | | **Search** | That tool's chat history | Semantic, text, metadata, and tag search | | **Connections** | None | Knowledge graph with typed relations | | **Portability** | Bound to your account | Plain files, works everywhere | | **Setup** | Automatic | One-time MCP connection | ### In practice **Claude:** Let Claude's memory summary and project memory handle who you are and what you're working on — it builds that automatically, and you can edit it in Settings. Use Basic Memory for knowledge at a different scale: full notes, decision records, and research that one rolling summary can't hold, and that you can open in any other tool. **Claude Code:** Use CLAUDE.md for project instructions ("use 2-space indentation," "run tests before committing"). Use auto memory for small learnings Claude picks up. Use Basic Memory for everything deeper — architecture decisions, API design notes, research, meeting summaries, project context that you want searchable and linked. **ChatGPT:** Let ChatGPT's saved memories and chat history handle personal preferences — "I'm vegetarian," "I live in San Francisco." Use Basic Memory for structured knowledge — project documentation, decision records, research notes — especially anything you also need in your IDE or other AI tools. **Cursor:** Use Cursor's built-in memories for quick rules. Use Basic Memory for the project knowledge that should survive across tools and sessions. --- ## A concrete example Say you're designing an authentication system. Here's what goes where: **Built-in memory** stores: - "We use TypeScript with strict mode" - "Preferred test framework: vitest" - "Always use 2-space indentation" **Basic Memory** stores: ```markdown --- title: Authentication Design Decision type: decision tags: [auth, security, api] --- # Authentication Design Decision ## Observations - [decision] Using JWT with refresh tokens for stateless auth - [rationale] Chose JWT over sessions for horizontal scaling - [constraint] Refresh tokens rotate on each use - [risk] Token revocation requires a blacklist check ## Relations - implements [[API Security Requirements]] - depends_on [[User Database Schema]] - informs [[Rate Limiting Strategy]] ``` The built-in memory tells the AI *how you like to work*. Basic Memory tells the AI *what you know and what you've decided*. Both make the AI more useful, in different ways. --- ## Getting started If you're already using an AI tool with built-in memory, adding Basic Memory takes a few minutes: ::card-group :::card --- icon: i-lucide-cloud title: "Quickstart: Cloud" to: https://docs.basicmemory.com/start-here/quickstart-cloud --- Connect in 2 minutes, no install needed. ::: :::card --- icon: i-lucide-hard-drive title: "Quickstart: Local" to: https://docs.basicmemory.com/start-here/quickstart-local --- Run everything on your machine. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- How notes, observations, and relations work. ::: :::card --- icon: i-lucide-plug title: Integrations to: https://docs.basicmemory.com/integrations/claude-desktop --- Connect Basic Memory to your AI tool. ::: :: # Knowledge Format Basic Memory is a knowledge base that you and your AI share. Everything is stored as plain markdown files on your machine — files you can open in any text editor, track with git, browse in Obsidian, or back up however you like. You own your data completely. This page explains how those files are structured and how that structure turns a folder of notes into a connected knowledge graph. ::tip Using Basic Memory Cloud? The knowledge format is the same — create notes through AI conversations or edit them directly in the [Web Editor](https://docs.basicmemory.com/cloud/cloud-guide#web-editor) . :: --- ## What a Note Looks Like Here's a note that an AI might create during a conversation about a project: ```markdown --- title: Authentication Design type: note tags: [auth, security, backend] permalink: authentication-design --- # Authentication Design ## Observations - [decision] Using JWT tokens for stateless authentication #security - [approach] Refresh tokens stored in HTTP-only cookies to prevent XSS - [constraint] Tokens expire after 15 minutes to limit exposure window - [status] Implementation complete and deployed to staging ## Relations - implements [[API Security Requirements]] - depends_on [[User Database Schema]] - relates_to [[Session Management]] ``` That's it. Markdown with a few simple patterns. The AI handles writing notes like this for you — you just tell it what you want to remember and it produces well-structured notes. But it helps to understand what you're looking at, so let's walk through the pieces. --- ## Frontmatter The YAML block at the top of each file holds metadata: ```yaml --- title: Authentication Design type: note tags: [auth, security, backend] permalink: authentication-design --- ``` - **title** — The name of the note. Used for linking and display. - **type** — What kind of note this is (e.g. `note`, `meeting`, `decision`). You can use any type you want. - **tags** — For organization and filtering. - **permalink** — A stable identifier for this note. Generated automatically from the title if you don't set one. Stays the same even if you move the file. ::tip Frontmatter is just standard YAML. You can add any fields you want — `status` , `priority` , `author` , `due_date` , whatever is useful for your workflow. The AI can set these automatically when creating notes, and you can search by them later with metadata search. If you want to formalize which fields a note type should have, that's what [schemas](https://docs.basicmemory.com/concepts/schema-system) are for. :: --- ## Observations Observations are individual facts, decisions, or details captured as list items with a category in brackets: ```markdown ## Observations - [decision] Using JWT tokens for stateless authentication #security - [approach] Refresh tokens stored in HTTP-only cookies - [constraint] Tokens expire after 15 minutes (based on security audit) ``` The pattern is: `- [category] content #optional-tags (optional context)` Categories can be anything that makes sense for what you're capturing — `[decision]`, `[fact]`, `[preference]`, `[question]`, `[todo]`, `[risk]`, `[idea]`, whatever fits. There's no fixed list. Use what feels natural and the AI will follow your lead. The power of observations is that each one is indexed individually. When you search your knowledge base, Basic Memory can surface the specific fact you need rather than just pointing you at a whole document. See [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search) for how this works. ::note Basic Memory recognizes `[category]` syntax as observations but won't confuse them with markdown checkboxes ( `[ ]` or `[x]` ). :: --- ## Relations Relations link notes together using `[[wiki-link]]` syntax: ```markdown ## Relations - implements [[API Security Requirements]] - depends_on [[User Database Schema]] - relates_to [[Session Management]] ``` The word before the link becomes the relationship type. Like categories, you can use any relation type — `implements`, `inspired_by`, `blocks`, `part_of`, `contrasts_with`, whatever describes the connection. Relation types are a single token; for a multi-word type, **quote it**: `"depends on" [[User Database Schema]]`. A list item that's just a wikilink (or has unquoted prose before it) is indexed as a generic `links_to` connection. You can also reference other notes inline anywhere in the document: ```markdown This builds on the patterns established in [[Core Architecture]] and addresses the concerns raised in [[Security Review Q4]]. ``` Relations can link to notes that don't exist yet. When those notes are created later, the connections are already in place. --- ## The Knowledge Graph Every note you write becomes a node. Every relation becomes an edge. Together, they form a knowledge graph that grows with your conversations. This graph is what makes Basic Memory more than a folder of files. When the AI uses `build_context`, it can follow connections across notes to pull together relevant information from across your entire knowledge base — not just the one note you asked about, but the notes it links to, and the notes that link back to it. --- ## Permalinks Every note has a permalink — a stable identifier derived from its title. Permalinks are how Basic Memory addresses notes internally and how `memory://` URLs work: ```text memory://authentication-design ``` Permalinks stay the same even if you rename or move the file. For more on how memory URLs work, including pattern matching and graph traversal, see [Memory URLs](https://docs.basicmemory.com/concepts/memory-urls). --- ## File Organization Organize your files however you want. Flat folders, nested hierarchies, topic-based groupings — the knowledge graph is built from the content of your notes, not from where they sit on disk. ```text knowledge/ projects/ auth-design.md api-roadmap.md meetings/ 2026-03-01-standup.md decisions/ database-choice.md ``` The graph connects everything regardless of folder structure. --- ## Schemas If you want consistency across certain types of notes — say, all meeting notes should include attendees and action items — you can define schemas that describe what a note type should contain. The AI will follow them automatically. See [Schema System](https://docs.basicmemory.com/concepts/schema-system) for details. ## Agent Skills You can teach your AI best practices for writing notes using agent skills. The `memory-notes` skill gives the AI guidance on structuring knowledge effectively. See [Agent Skills](https://docs.basicmemory.com/whats-new/agent-skills) for how to set this up. --- ## Next Steps ::card-group :::card --- icon: i-lucide-link title: Observations and Relations to: https://docs.basicmemory.com/concepts/observations-and-relations --- Detailed patterns and examples for semantic markup. ::: :::card --- icon: i-lucide-at-sign title: Memory URLs to: https://docs.basicmemory.com/concepts/memory-urls --- URL patterns for navigating and querying the knowledge graph. ::: :::card --- icon: i-lucide-shield-check title: Schema System to: https://docs.basicmemory.com/concepts/schema-system --- Define structure and validation for note types. ::: :::card --- icon: i-lucide-search title: Semantic Search to: https://docs.basicmemory.com/concepts/semantic-search --- How observations power precise, fact-level search. ::: :: # Projects and folders Most people start Basic Memory with a single project and a single folder. That works fine for a while, but eventually you need boundaries. Maybe you want work notes separate from personal notes. Maybe you have three clients and their knowledge should never overlap. That is what projects are for. ## What is a project? A project is a separate knowledge base. Each project maps to a folder on disk (or a cloud instance), has its own set of notes, its own knowledge graph, and its own search index. Notes in one project do not appear in another. Relations in one project cannot link to notes in a different project. Think of projects the way you think of separate notebooks, not separate pages in the same notebook. When you run a command or an AI tool like `write_note`, it targets whichever project is currently active. You can switch projects at any time, and one project is always set as the default so you do not have to specify it every time. ## Creating and managing projects Add a project by pointing Basic Memory at a folder: ```bash bm project add "work" ~/Documents/work-notes bm project add "personal" ~/Documents/personal-notes ``` List your projects: ```bash bm project list ``` Set a default so commands go there automatically: ```bash bm project default "work" ``` Switch to a different project in conversation using the MCP tool: ```text Switch to the "personal" project. ``` The AI will call `switch_project` behind the scenes. You can also use the CLI: ```bash bm project switch "personal" ``` ## When to use multiple projects The key question is: **do these notes need to be connected, or separate?** If notes should link to each other and show up in the same search results, keep them in the same project. If they should stay isolated, split them. Here are some common patterns: - **Work vs personal.** Keep company knowledge separate from your own notes. Different contexts, different purposes, no accidental leakage. - **Multiple clients.** Each client gets a project. Their notes, decisions, and context stay contained. You can switch between clients mid-conversation. - **A coding project's docs folder.** Point a project at the `docs/` folder inside a repo. The AI builds context about that specific codebase without pulling in unrelated notes. - **A writing project.** A book, a course, or a research paper. Give it a project so its outline, drafts, and references form their own knowledge graph. If you're unsure, start with one project. You can always create another later and move notes into it. ## Folders within a project Inside a project, organize however you like. Create folders, nest them, rename them. The knowledge graph does not care about folder structure. It indexes notes by their content, observations, and relations, not by which directory they live in. Folders are for you. They help you browse and find things visually. But when the AI searches your knowledge base or follows a relation link, it works at the note level, not the folder level. ```text ~/Documents/work-notes/ meetings/ decisions/ architecture/ onboarding/ ``` This is a perfectly good layout. So is a flat folder with everything at the top level. The graph works the same either way. ## Mixing local and cloud projects Starting in v0.19, you can keep some projects local and route others to Basic Memory Cloud. Your personal notes stay on your machine. Your work projects sync to the cloud and are accessible from any device. Both are available in the same conversation. This is configured through per-project cloud routing. Each project independently decides whether it talks to a local database or a cloud instance. For setup details, see the [Local and Cloud Routing](https://docs.basicmemory.com/cloud/routing) guide. ## Project-prefixed permalinks When you have multiple projects, Basic Memory automatically prefixes note permalinks with the project name to prevent ambiguity: ```text memory://work/architecture/auth-system memory://personal/reading-list ``` This means a note called "Auth System" in your work project and a note called "Auth System" in your personal project are distinct and addressable. The prefix is added automatically when notes are indexed. You do not need to manage it yourself. For more on how memory URLs work, see [Memory URLs](https://docs.basicmemory.com/concepts/memory-urls). ## Next steps ::card-group :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Learn the note structure with observations and relations. ::: :::card --- icon: i-lucide-cloud title: Local and Cloud Routing to: https://docs.basicmemory.com/cloud/routing --- Keep some projects local and route others to the cloud. ::: :::card --- icon: i-lucide-link title: Memory URLs to: https://docs.basicmemory.com/concepts/memory-urls --- How memory:// URLs address notes across projects. ::: :::card --- icon: i-lucide-layout-panel-left title: Notes Interface to: https://docs.basicmemory.com/cloud/web-app --- Use notes in the Cloud app. ::: :: # 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: ```markdown - [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: ```markdown - [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: ```markdown - [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: ```markdown ## 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: ```markdown - 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. ::note **Quote multi-word relation types.** A relation type is a single token ( `depends_on` , `relates_to` ). If you want a multi-word type, **quote it** — `"depends on" [[Caching Layer]]` . Unquoted prose before a wikilink is no longer treated as a relation type: a bare or prose list item like `- [[Caching Layer]]` or `- see also [[Caching Layer]]` is indexed as a generic `links_to` connection. (Changed in [v0.21.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.21.0){rel=""nofollow""} .) :: ### Inline references You can also link to other notes anywhere in a note's body text using `[[wiki links]]`: ```markdown 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. ::note See [Schema System](https://docs.basicmemory.com/concepts/schema-system) for details on defining and applying schemas. :: ## 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. ::note See [Agent Skills](https://docs.basicmemory.com/whats-new/agent-skills) for details on how skills work. :: ## Next steps ::card-group :::card --- icon: i-lucide-search title: Semantic Search to: https://docs.basicmemory.com/concepts/semantic-search --- Learn how observations power precise semantic search across your knowledge base. ::: :::card --- icon: i-lucide-shield-check title: Schema System to: https://docs.basicmemory.com/concepts/schema-system --- Validate and enforce structure on your notes with schemas. ::: :::card --- icon: i-lucide-at-sign title: Memory URLs to: https://docs.basicmemory.com/concepts/memory-urls --- See how links resolve and navigate knowledge. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Learn the base note format that observations and relations build on. ::: :: # Memory URLs Basic Memory is a knowledge base that you and your AI share. Memory URLs are how notes are addressed — by your AI, by CLI commands, and by links between notes. Every note in Basic Memory has an address — a `memory://` URL that works like a web link for your knowledge base. Your AI uses these behind the scenes to read notes, follow connections, and build context. You'll see them in tool output and can use them directly when you want to point your AI at something specific. --- ## Basic forms ### By title/permalink ```text memory://auth-approaches-2024 ``` ### By path ```text memory://docs/authentication memory://docs/authentication.md ``` ### By wildcard ```text memory://docs/* memory://auth* ``` --- ## Project-prefixed URLs With project-prefixed permalink behavior enabled (default), memory URLs can include project scope: ```text memory://main/docs/authentication memory://research/specs/search-ranking ``` This is useful when the same note title exists in multiple projects. --- ## Cross-project references in links Within notes, project namespace syntax is normalized: ```text project::note-path ``` is treated as: ```text project/note-path ``` This improves cross-project resolution and keeps links explicit. --- ## Where Memory URLs are used Your AI uses memory URLs when reading notes, building context, and following links between notes. You can also use them directly in conversation — "read memory://docs/authentication" — or in CLI commands. Behind the scenes, tools like `read_note` and `build_context` accept memory URLs as their primary input, and assistant workflows pass them between calls to maintain stable references. --- ## Resolution behavior At runtime, Basic Memory resolves memory URLs in this order: ### 1. Project constraints If the MCP server was started with `BASIC_MEMORY_MCP_PROJECT=research`, all URLs are resolved within the `research` project regardless of any prefix in the URL: ```text memory://docs/auth → resolves in "research" project only ``` ### 2. Explicit project prefix If no constraint is set, the URL is checked for a project prefix. The first path segment is compared against known project names: ```text memory://main/docs/auth → resolves in "main" project memory://research/specs/api → resolves in "research" project ``` ### 3. Default project fallback If no constraint exists and no project prefix matches, the URL resolves in the default project: ```text memory://docs/auth → resolves in default project (typically "main") ``` ### Project-prefix extraction When `permalinks_include_project` is enabled (the default), Basic Memory checks whether the first path segment of a URL matches a known project name. If it does, that segment is stripped and used as the project context: ```text memory://main/specs/api-design ^^^^ → project = "main" ^^^^^^^^^^^^^^^^ → path = "specs/api-design" ``` If the first segment doesn't match any known project, the entire path is treated as a note path within the default project. --- ## Best practices - Use project-prefixed URLs in multi-project workflows - Prefer permalinks for stability over titles when possible - Use wildcards for discovery, then switch to exact references --- ## Next steps ::card-group :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- See which tools accept memory URLs. ::: :::card --- icon: i-lucide-bot title: AI Assistant Guide to: https://docs.basicmemory.com/reference/ai-assistant-guide --- Patterns for memory URL usage in assistant workflows. ::: :: # Canvas Visualizations Basic Memory can create visual knowledge maps using Obsidian's Canvas feature. These visualizations help you understand relationships between concepts, map out processes, and visualize your knowledge structure. ## Creating Canvas Visualizations Ask Claude to create a visualization by describing what you want to map: - **Example Requests** — - "Create a canvas visualization of my project components and their relationships." - "Make a concept map showing the main themes from our discussion about climate change." - "Can you make a canvas diagram of the perfect pour over method?" ![Canvas Visualization Example](https://docs.basicmemory.com/attachments/Canvas.png) ## Types of Visualizations Basic Memory can create several types of visual maps: - **Document Maps** — Visualize connections between your notes and documents - **Concept Maps** — Create visual representations of ideas and their relationships - **Process Diagrams** — Map workflows, sequences, and procedures - **Thematic Analysis** — Organize ideas around central themes ### Relationship Networks Show how different entities relate to each other in your knowledge base. ## Visualization Sources Claude can create visualizations based on: ### Documents in Your Knowledge Base ```example You: "Create a canvas showing the connections between my project planning documents" ``` ### Conversation Content ```example You: "Make a canvas visualization of the main points we just discussed" ``` ### Search Results ```example You: "Find all my notes about psychology and create a visual map of the concepts" ``` ### Themes and Relationships ```example You: "Create a visual map showing how different philosophical schools relate to each other" ``` ## Visualization Workflow ::steps ### Request a visualization Describe what you want to see by asking Claude to create a canvas ### Claude creates the canvas file The canvas file is automatically created in your Basic Memory directory ### Open the file in Obsidian View the visualization in Obsidian's Canvas feature ### Refine the visualization Ask Claude for adjustments: - "Could you reorganize the canvas to group related components together?" - "Please add more detail about the connection between these two concepts." :: ## Technical Details Behind the scenes, the AI: ::note 1. Creates a `.canvas` file in JSON format 2. Adds nodes for each concept or document 3. Creates edges to represent relationships 4. Sets positions for visual clarity 5. Includes any relevant metadata :: The resulting file is fully compatible with Obsidian's Canvas feature and can be edited directly in Obsidian. ## Tips for Effective Visualizations - **Be Specific** — Clearly describe what you want to visualize - **Specify Detail Level** — Mention how much detail you need - **Mention Type** — Specify the visualization type (concept map, process flow, etc.) - **Start Simple** — Begin with basic visualizations and ask for refinements ::note **Provide context** about what documents or concepts to include for the best results. :: # Schema System In Basic Memory, your notes are Markdown files with structured information — facts (called [observations](https://docs.basicmemory.com/concepts/observations-and-relations)) and links to other notes (called [relations](https://docs.basicmemory.com/concepts/observations-and-relations)). A schema describes what a particular type of note should contain — like making sure every person note has a name. Schemas are optional. You can use Basic Memory without ever defining one. But as your knowledge base grows, schemas help you keep notes consistent and give your AI a guide for creating well-structured notes. --- ## Why schemas? After writing hundreds of notes over several months, you might notice inconsistency: some person notes have a name, some don't. Some link to an employer with "works\_at", others say "employed\_by." The information is all there, but the lack of consistency makes it harder to search and build on. Schemas let you define what "consistent" means for a note type, and then check your notes against that definition. The key insight is that schemas describe your *existing* patterns — they don't force a rigid template upfront. You write notes however feels natural, then add schemas later to bring order to what you've already created. --- ## How it works The most natural way to use schemas is through conversation with your AI assistant. **Discovering patterns:** ```text You: "I've been writing a lot of person notes. Can you figure out what structure they have in common?" AI: [Analyzes your person notes] Looking at your 45 person notes, here's what I found: - "name" appears in 95% of notes - "role" appears in 80% - "works_at" link appears in 60% - "expertise" appears in 40% Want me to create a schema based on these patterns? ``` **Creating a schema:** ```text You: "Yes, make name required and the rest optional." AI: [Creates a schema note] Done! I've created a Person schema. Notes with type "person" will be checked against it. ``` **Validating notes:** ```text You: "How do my existing person notes look against that schema?" AI: [Validates all person notes] 42 of 45 notes pass. Three are missing a name: - people/mystery-contact.md - people/quick-note-jane.md - people/old-import-2024.md Want me to fix those? ``` **Checking for drift later:** ```text You: "It's been a few months — are my person notes still consistent?" AI: [Compares schema against actual usage] Most notes still follow the schema. I notice "linkedin" is showing up in 35% of newer notes but isn't in the schema. Want me to add it as an optional field? ``` **Writing with schema guidance:** When a schema exists for a note type, your AI uses it as a creation guide automatically. It includes all required fields and relevant optional ones without you having to ask. Your schemas do double duty: they help you maintain consistency *and* they guide AI assistants toward producing notes that match your preferred format. --- ## What schemas check Schemas check that your notes include the information you care about: - **Facts** — A schema can require specific facts. If your person schema says "name" is required, Basic Memory expects to find a name in the note. - **Links** — A schema can define expected links to other notes. If "works\_at" is defined, Basic Memory expects a link to an organization. - **Metadata** — Schemas can check for specific properties in the metadata block at the top of a note (title, tags, type). Schemas are just regular notes themselves. There's nothing special about them — they live in your knowledge base alongside everything else. --- ## Validation By default, schemas give gentle warnings when something's missing — they don't block anything. You can make them stricter once your patterns stabilize. | Mode | What happens | When to use | | ------------------ | ------------------------------------------------- | --------------------------------------- | | **Warn** (default) | Reports what's missing but doesn't block anything | Active writing, gradual adoption | | **Strict** | Treats missing fields as errors | Mature schemas, enforced workflows | | **Off** | No checking | Temporarily disable while restructuring | Start with warn mode. Move to strict only after your note patterns have settled down and you're confident in the schema. --- ## Schema ideas to try You don't need to write schemas by hand. Tell your AI what you want to track, and it creates the schema for you. Here are some starting points. ### Task tracking Keep a simple task list without a separate project management tool. **Prompt your AI:** > "Create a schema for tasks. Each task should have a status (todo, in-progress, done), a priority (low, medium, high), and optionally link to a project." **What the AI creates:** ```yaml schema: title: string, what needs to be done status(enum, current state): [todo, in-progress, done] priority?(enum, how urgent): [low, medium, high] due_date?: string, target completion date belongs_to?: Project, related project blocked_by?(array, dependencies): Task ``` **Then use it naturally:** > "Create a task to update the API docs, medium priority, for the v2 project." > "What tasks are in progress right now?" > "Mark the API docs task as done." ### Meeting notes Capture decisions and action items so they don't get lost in a wall of text. **Prompt your AI:** > "I want a schema for meeting notes. Track who attended, what we decided, and what needs to happen next." **What the AI creates:** ```yaml schema: date: string, when the meeting happened attendees(array, who was there): string summary?: string, brief overview decisions?(array, what was agreed on): string action_items?(array, follow-up tasks): string relates_to?(array, projects discussed): Project ``` **Then use it naturally:** > "Write up today's meeting with Sarah and Tom. We decided to delay the launch by a week. Sarah will update the timeline, Tom will notify partners." > "What action items came out of meetings this week?" ### Research notes Organize what you're learning about a topic — articles, key takeaways, open questions. **Prompt your AI:** > "Create a schema for research notes. I want to track the source, key findings, and how it connects to other research." **What the AI creates:** ```yaml schema: topic: string, what this research is about source?: string, where the information came from findings?(array, key takeaways): string questions?(array, open questions or things to explore): string relates_to?(array, connected research notes): Research supports?: Hypothesis, hypothesis this evidence supports ``` **Then use it naturally:** > "I just read this article about sleep and memory consolidation. The key finding is that deep sleep within 4 hours of learning improves retention by 40%. This relates to my learning-techniques research." > "What open questions do I have across my research notes?" ### Recipes Track what you cook, what worked, and what to tweak next time. **Prompt your AI:** > "Make a schema for recipes. I want to track ingredients, steps, and my own notes about what I'd change." **What the AI creates:** ```yaml schema: cuisine?: string, type of cuisine servings?: integer, how many it feeds prep_time?: string, how long to prepare ingredients(array, what you need): string steps(array, how to make it): string notes?(array, personal tweaks and observations): string inspired_by?: Recipe, adapted from another recipe ``` **Then use it naturally:** > "Save this pasta recipe I tried tonight. It's a carbonara, serves 2. I used guanciale instead of pancetta and it was way better. Next time use less pepper." > "What recipes have I noted tweaks for?" ### Roll your own These are just starting points. The real power is that you can describe *any* structure and the AI builds it: > "Create a schema for book notes with author, genre, my rating out of 10, key quotes, and what I'd tell a friend about it." > "I want to track my workouts. Sets, reps, weight, and how I felt." > "Make a schema for project decisions — the context, what we chose, what we rejected, and why." The AI reads your schemas automatically when creating notes of that type, so once a schema exists, your notes just come out consistent. --- ## Best practices - **Use specific note types** — Choose clear type values like `person`, `meeting`, `decision` rather than leaving everything as `note`. - **Let the AI infer first** — Let Basic Memory analyze your existing patterns before writing schemas by hand. - **Keep schema notes together** — Use a `schemas/` folder for easy discovery. - **Check for drift periodically** — Run a schema check every few weeks to keep schemas aligned with how you actually write notes. - **Adopt gradually** — Start with warn mode. Move to strict only after patterns stabilize. - **Version your schemas** — Track schema evolution over time as your needs change. --- ## Technical Reference The sections below cover schema syntax, configuration, and tool parameters. You don't need to read this section to use schemas — your AI handles the details for you. --- ### Picoschema syntax Schemas use [Picoschema](https://google.github.io/dotprompt/reference/picoschema/){rel=""nofollow""} — a compact YAML-based syntax for defining fields. Each line declares a field name, its type, and an optional description. #### Types | Type | Meaning | Example | | ----------------- | --------------------------- | ------------------------ | | `string` | Free-text value | `name: string` | | `integer` | Whole number | `priority: integer` | | `number` | Any numeric value | `score: number` | | `boolean` | True/false | `active: boolean` | | `any` | Any value accepted | `notes: any` | | `CapitalizedName` | Reference to another entity | `works_at: Organization` | When a type name is capitalized (like `Organization`), it signals an entity reference — Basic Memory expects a wiki-link relation rather than a plain observation. #### Modifiers | Syntax | Meaning | Example | | ------------------------ | ------------------------------------- | ------------------------------------------- | | `field: type` | Required field | `name: string` | | `field?: type` | Optional field | `role?: string` | | `field(array): type` | Required array (multiple values) | `skills(array): string` | | `field?(array): type` | Optional array | `expertise?(array): string` | | `field?(enum): [values]` | Value must be one of listed options | `status?(enum): [active, inactive, alumni]` | | `field?(object):` | Nested object (indented fields below) | See example below | #### Descriptions Add a description after a comma to document what a plain field means: ```yaml name: string, full legal name role?: string, current job title or position works_at?: Organization, primary employer ``` For fields with modifiers like `array`, `enum`, or `object`, put the description inside the parentheses after the modifier: ```yaml expertise?(array, areas of knowledge): string status?(enum, current relationship status): [active, inactive, alumni] ``` #### Complete annotated example ```yaml schema: name: string, full legal name role?: string, current job title email?: string, primary contact email works_at?: Organization, primary employer expertise?(array, areas of knowledge): string status?(enum, current relationship status): [active, inactive, alumni] contact_info?(object): phone?: string location?: string ``` This schema says: every note of this type *must* have a `name` observation. It *should* have a `role`, `email`, `works_at` relation, and so on — but those are optional. The `expertise` field expects multiple observations (an array). The `status` field constrains values to one of three choices. --- ### Defining schemas There are three ways to create a schema. #### 1. Dedicated schema note (recommended) Create a markdown file with `type: schema` in its frontmatter. This is the best approach for note types you use repeatedly — `person`, `meeting`, `decision`, `project`, and so on. ```yaml --- title: Person type: schema entity: person version: 1 schema: name: string, full name role?: string, job title email?: string, contact email works_at?: Organization, employer expertise?(array, areas of knowledge): string settings: validation: warn --- # Person Schema for people in the knowledge base. Every person note should have a name and optionally include their role, contact info, and employer. Use `type: person` in your note frontmatter to match this schema. ``` The note body is regular markdown — use it to describe the schema's purpose, provide examples, or document conventions. Basic Memory reads the schema definition from the frontmatter; the body is for humans. **Frontmatter fields for schema notes:** | Field | Required | Description | | ---------- | -------- | ------------------------------------------------------------- | | `type` | Yes | Must be `schema` | | `entity` | Yes | The note type this schema applies to (e.g., `person`) | | `version` | No | Schema version number for tracking changes | | `schema` | Yes | The field definitions in picoschema syntax | | `settings` | No | Configuration like `validation: warn` and `frontmatter` rules | Place schema notes in a `schemas/` folder by convention (e.g., `schemas/person.md`), though any location works. #### 2. Inline schema in a single note Useful for one-off structure or prototyping before committing to a reusable schema: ```yaml --- title: Team Standup 2026-02-10 type: meeting schema: attendees(array, participants): string decisions?(array, outcomes): string blockers?(array, unresolved issues): string action_items?(array, follow-up tasks): string --- ``` The schema applies only to this specific note. If you find yourself copying the same inline schema into multiple notes, promote it to a dedicated schema note. #### 3. Explicit schema reference Point a note to a schema by name or path: ```yaml --- title: Ada Lovelace type: person schema: Person --- ``` Or by path: ```yaml --- title: Ada Lovelace type: person schema: schemas/person --- ``` This is useful when the note's `type` doesn't match the schema's `entity` field, or when you want to be explicit about which schema to use. --- ### Schema resolution order When validating a note, Basic Memory finds the right schema by checking in this order: 1. **Inline schema** — If the note has a `schema` dict in its frontmatter, use that directly. 2. **Explicit reference** — If the note has a `schema` string in its frontmatter (like `schema: Person`), look up that schema note by title or path. 3. **Implicit by type** — Look for a schema note whose `entity` field matches the note's `type`. For example, a note with `type: person` automatically matches a schema note with `entity: person`. 4. **No schema** — If none of the above match, no validation is performed. This is fine — not every note needs a schema. --- ### How fields map to notes Each field in a schema corresponds to something Basic Memory expects to find in the note: | Schema declaration | What it expects in the note | Example in note | | ----------------------------------- | ---------------------------------------- | ------------------------------------------------------- | | `name: string` | Required observation | `- [name] Ada Lovelace` | | `role?: string` | Optional observation | `- [role] Mathematician` | | `expertise?(array): string` | Multiple observations with same category | `- [expertise] Mathematics`:br`- [expertise] Computing` | | `works_at?: Organization` | Optional relation (wiki-link) | `- works_at [[Analytical Engine Project]]` | | `status?(enum): [active, inactive]` | Observation with constrained value | `- [status] active` | ### Validating frontmatter fields Schemas can also validate a note's YAML frontmatter — not just observations and relations. Use `settings.frontmatter` to declare rules for frontmatter keys using the same picoschema syntax: ```yaml --- title: Person type: schema entity: person schema: name: string, full name role?: string, job title settings: validation: warn frontmatter: tags?(array): string status?(enum): [draft, published, archived] --- ``` This schema validates two things about each `person` note's frontmatter: - **`tags`** — optional array of strings (e.g., `tags: [engineer, python]`) - **`status`** — optional enum that must be one of `draft`, `published`, or `archived` A conforming note: ```yaml --- title: Grace Hopper type: person tags: [computing, compilers] status: published --- # Grace Hopper ## Observations - [name] Grace Hopper - [role] Computer Scientist ``` Validation checks both the body fields (`name`, `role`) and the frontmatter fields (`tags`, `status`): ```bash $ bm schema validate people/grace-hopper.md ✓ grace-hopper: valid (0 warnings) ``` If a note has a frontmatter value outside the allowed enum: ```yaml --- title: Iris West type: person status: archived # not in [draft, published] --- ``` ```bash $ bm schema validate people/iris-west.md ⚠ iris-west: frontmatter field 'status' enum mismatch (got 'archived', expected one of: draft, published) ``` If a required frontmatter key is missing (no `?` suffix), validation warns or errors depending on the mode: ```yaml settings: frontmatter: status: string # required — no ? suffix ``` ```bash $ bm schema validate people/hank-pym.md ⚠ hank-pym: missing required frontmatter field: status ``` ::note Frontmatter rules use the same picoschema syntax as body fields. Add `?` for optional, `(array)` for lists, and `(enum)` for constrained values. :: --- ### CLI reference ```bash # Analyze your existing notes to discover patterns bm schema infer person # Save the inferred schema as a note bm schema infer person --save # Validate a single note bm schema validate people/ada-lovelace.md # Validate all notes of a type bm schema validate person # Check for drift over time bm schema diff person ``` See the [CLI Reference](https://docs.basicmemory.com/reference/cli-reference) for full flag documentation. --- ### MCP tool parameters See the [MCP Tools Reference](https://docs.basicmemory.com/reference/mcp-tools-reference) for full `schema_validate`, `schema_infer`, and `schema_diff` parameter tables. --- ## Complete example Here's a full workflow for adding schemas to an existing knowledge base. **Schema note** (`schemas/person.md`): ```yaml --- title: Person type: schema entity: person version: 1 schema: name: string, full name role?: string, job title email?: string, contact email works_at?: Organization, employer expertise?(array, areas of knowledge): string settings: validation: warn frontmatter: tags?(array): string status?(enum): [active, inactive, archived] --- ``` **A conforming person note** (`people/ada-lovelace.md`): ```yaml --- title: Ada Lovelace type: person tags: [mathematics, computing] status: active --- # Ada Lovelace ## Observations - [name] Ada Lovelace - [role] Mathematician and Writer - [expertise] Mathematics - [expertise] Computing theory ## Relations - works_at [[Analytical Engine Project]] ``` **Validation:** ```bash $ bm schema validate people/ada-lovelace.md ✓ ada-lovelace: valid (0 warnings) ``` If `[name]` were missing: ```bash $ bm schema validate people/ada-lovelace.md ⚠ ada-lovelace: missing required field: name ``` --- ## Common issues **`No schema found`** — Create a schema note with `type: schema` for that note type, add an inline schema, or use an explicit `schema:` reference in frontmatter. **`Missing required field`** — Add the observation or relation expected by the schema. For example, if `name: string` is required, add `- [name] Ada Lovelace` to the note. **`Too many warnings`** — Either relax the schema by making more fields optional (`?`), or lower the inference threshold and regenerate with `bm schema infer person --threshold 0.1`. --- ## Next steps ::card-group :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- Schema tool parameters and examples. ::: :::card --- icon: i-lucide-terminal title: CLI Reference to: https://docs.basicmemory.com/reference/cli-reference --- Full `bm schema` command reference. ::: :::card --- icon: i-lucide-bot title: AI Assistant Guide to: https://docs.basicmemory.com/reference/ai-assistant-guide --- How assistants can use schema tools in workflows. ::: :: # Semantic Search Most knowledge tools make you organize everything up front so you can find it later. Basic Memory takes the opposite approach — write naturally, and let search figure out the connections. When you or your AI save a note, Basic Memory indexes it two ways: by the exact words it contains, and by what it *means*. Search for "login security improvements" and find notes about "authentication hardening" even though the exact words don't match. This happens automatically — no tagging system to maintain, no folder hierarchy to get right. What makes this different from a typical search tool is that your AI is part of the loop. It writes notes, searches them, and builds on what it finds — all through the same tools. The search index updates incrementally as notes change, so the AI is always working with current knowledge, not a stale snapshot. ::mermaid --- code: | flowchart LR Q[Query] --> T[Text Search] Q --> V[Vector Search] T --> SF[Score Fusion] V --> SF SF --> R[Results] --- :: --- ## Search modes Basic Memory supports three search modes. Your AI already knows when to use each one — just describe what you're looking for in plain language. You can also use them directly from the command line. ### Text Keyword search. You type words, it finds notes containing those words. Supports boolean operators like `AND` and `OR`. ::code-group ```text [Conversation] You: "Search my notes for project AND planning" AI: [Finds notes containing both words] ``` ```bash [CLI] bm tool search-notes "project AND planning" ``` :: Best when you know the exact terms — names, identifiers, tags. The CLI doesn't have a text-only flag — keyword matching (including `AND`/`OR` operators) runs as part of the default hybrid search, and searches are text-only when semantic search is disabled. ### Vector Meaning-based search. Your query is compared against all indexed content by meaning, not exact words. Searching for "ways to make the frontend faster" finds notes about "React performance optimization" and "bundle size reduction." ::code-group ```text [Conversation] You: "Find notes about ways to make the frontend faster" AI: [Finds notes about React performance, bundle size, lazy loading] ``` ```bash [CLI] bm tool search-notes "ways to make the frontend faster" --vector ``` :: Best for conceptual queries when you aren't sure what words were used. ### Hybrid (default) Runs both text and vector search, then combines results. Notes found by both methods rank highest. Notes found by only one method still appear but rank lower. ::code-group ```text [Conversation] You: "Search for authentication security" AI: [Finds notes matching the words AND notes about related concepts] ``` ```bash [CLI] bm tool search-notes "authentication security" ``` :: This is the default. You get keyword precision plus meaning-based recall. ### You don't need to pick Basic Memory describes each search mode to your AI, so it already knows when to use text, vector, or hybrid search. Just ask for what you want in plain language: - "Find my notes about authentication security" — the AI runs a hybrid search - "Search for the exact phrase project AND planning" — the AI switches to text search - "What have I written about handling failures gracefully?" — the AI uses vector search If you're using the CLI directly, pass the query as an argument — hybrid is the default and covers most cases. Use `--vector` when you're exploring by concept, or `--hybrid` to combine both explicitly. --- ## Filtering ### Tag search Search by tag using a simple prefix: ::code-group ```text [Conversation] You: "Search for notes tagged security" You: "Search for tag:coffee AND tag:brewing" ``` ```bash [CLI] bm tool search-notes "tag:security" ``` :: ### Metadata filters Search by note properties — like status, tags, or any custom frontmatter field — without needing a text query: ::code-group ```text [Conversation] You: "Show me all my in-progress notes" You: "Find notes tagged security and oauth" You: "What are my high-priority items?" ``` ```bash [CLI] bm tool search-notes "" --meta status=in-progress bm tool search-notes "" --tag security --tag oauth bm tool search-notes "" --filter '{"priority": {"$in": ["high", "critical"]}}' ``` :: ::tip See [Metadata Search](https://docs.basicmemory.com/concepts/metadata-search) for the full operator reference, nested-field syntax, and worked examples. :: ### Combining text and filters Combine a text or meaning-based search with property filters: ::code-group ```text [Conversation] You: "Search for authentication notes that are specs" You: "Find active error handling notes" ``` ```bash [CLI] bm tool search-notes "authentication" --type spec bm tool search-notes "error handling" --meta status=active ``` :: --- ## Enabling semantic search Semantic search works automatically — there's nothing to set up. It's included and enabled by default in all standard Basic Memory installs (Homebrew and uv). Embeddings are generated automatically on first startup for existing notes. For a few hundred notes, expect 1–3 minutes for the initial index build. After that, new and edited notes are indexed incrementally during normal sync. To manually rebuild the search index (e.g., after switching providers): ```bash bm reindex --embeddings ``` ### Platform compatibility | Platform | FastEmbed (local) | OpenAI (API) | | --------------------------- | ------------------- | ------------ | | macOS ARM64 (Apple Silicon) | Yes | Yes | | macOS x86\_64 (Intel Mac) | No (see workaround) | Yes | | Linux x86\_64 | Yes | Yes | | Linux ARM64 | Yes | Yes | | Windows x86\_64 | Yes | Yes | ### Intel Mac workaround The default local embedding model doesn't run on Intel Macs. You have two options: **Option 1: Use OpenAI embeddings (recommended)** Requires an [OpenAI API subscription](https://platform.openai.com/api-keys){rel=""nofollow""} — create a key there and set it as an environment variable. ```bash export BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER=openai export OPENAI_API_KEY=sk-... bm reindex --embeddings ``` **Option 2: Pin ONNX Runtime** ```bash uv pip install 'onnxruntime<1.24' bm reindex --embeddings ``` --- ## Under the Hood You don't need to read this section to use search — it's here for the curious. ### Chunking Notes are not searched as whole documents. Basic Memory breaks each note into smaller pieces before indexing, so search can surface the specific *part* of a note that's relevant. ::mermaid --- code: | flowchart TD N[Note] --> H[Headers] N --> O[Observations] N --> R[Relations] N --> P[Prose] H --> C1[Section Chunks] O --> C2[Observation Chunks] R --> C3[Relation Chunks] P --> C4[Merged Chunks ~900 chars] C1 --> E[Embeddings] C2 --> E C3 --> E C4 --> E --- :: The chunking follows the note's structure: - **Headers** create chunk boundaries — each section becomes its own chunk - **Observations** (categorized facts like `- [technique] Water temperature...`) are indexed individually - **Relations** (links to other notes like `- works_at [[Company]]`) are indexed individually - **Prose** paragraphs are merged into chunks of \~900 characters with \~120 character overlap at boundaries This means a search for "water temperature for brewing" can surface the specific fact `Water temperature at 205°F extracts optimal compounds` rather than returning the entire "Coffee Brewing Methods" note. ### How results are ranked Search results return whole notes ranked by relevance, with the matched chunk text showing which part of the note was most relevant. ### Hybrid fusion Hybrid mode runs text and vector search independently, then merges results using score-based fusion: ::mermaid --- code: | flowchart LR Q[Query] --> FTS[Text Search] Q --> VS[Vector Search] FTS --> R1[Scored Results] VS --> R2[Scored Results] R1 --> SF[Score Fusion] R2 --> SF SF --> F[Final Ranking] --- :: Results found by both keyword and meaning match rank highest. The dominant signal (whichever source scored higher) is preserved, while the weaker signal adds a 30% bonus. Items found by only one source keep their original score. ### Deduplication Each chunk has a content hash. When notes are re-synced or reindexed, unchanged chunks skip re-indexing. Only modified content triggers new embeddings. Editing one note in a thousand-note knowledge base only re-indexes the chunks that changed. --- ## Configuration | Config field | Env var | Default | Description | | ------------------------------- | -------------------------------------------- | --------------------- | ----------------------------------------- | | `semantic_search_enabled` | `BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED` | `true` | Enable semantic search | | `semantic_embedding_provider` | `BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER` | `"fastembed"` | `"fastembed"` (local) or `"openai"` (API) | | `semantic_embedding_model` | `BASIC_MEMORY_SEMANTIC_EMBEDDING_MODEL` | `"bge-small-en-v1.5"` | Embedding model identifier | | `semantic_embedding_dimensions` | `BASIC_MEMORY_SEMANTIC_EMBEDDING_DIMENSIONS` | auto-detected | 384 (FastEmbed), 1536 (OpenAI) | | `semantic_embedding_batch_size` | `BASIC_MEMORY_SEMANTIC_EMBEDDING_BATCH_SIZE` | `64` | Texts per embedding batch | | `semantic_vector_k` | `BASIC_MEMORY_SEMANTIC_VECTOR_K` | `100` | Vector candidate count | | `semantic_min_similarity` | `BASIC_MEMORY_SEMANTIC_MIN_SIMILARITY` | `0.55` | Minimum similarity threshold | ### Similarity threshold The `semantic_min_similarity` setting controls which results are "similar enough" to return. The value ranges from `0.0` to `1.0`: - **Higher** (e.g., `0.7`) — Fewer results, stronger relevance. Good for focused queries. - **Lower** (e.g., `0.3`) — More results, looser associations. Good for exploration. - **`0.0`** — Disables filtering. All vector results returned regardless of score. The default `0.55` is a reasonable middle ground. See [Configuration](https://docs.basicmemory.com/reference/configuration) for the full config reference. --- ## Embedding providers ### FastEmbed (default) - Runs locally — no API key, no network calls, no cost - Model: `BAAI/bge-small-en-v1.5` - Dimensions: 384 ### OpenAI - Requires an [OpenAI API subscription](https://platform.openai.com/api-keys){rel=""nofollow""} and `OPENAI_API_KEY` environment variable - Model: `text-embedding-3-small` - Dimensions: 1536 - Higher dimensions capture more nuance, which can improve results for large or domain-specific knowledge bases Switching provider or model requires rebuilding the index: ```bash bm reindex --embeddings ``` --- ## Platform compatibility | Platform | FastEmbed (local) | OpenAI (API) | | --------------------------- | ------------------- | ------------ | | macOS ARM64 (Apple Silicon) | Yes | Yes | | macOS x86\_64 (Intel Mac) | No (see workaround) | Yes | | Linux x86\_64 | Yes | Yes | | Linux ARM64 | Yes | Yes | | Windows x86\_64 | Yes | Yes | ### Intel Mac workaround The default local embedding model doesn't run on Intel Macs. You have two options: **Option 1: Use OpenAI embeddings (recommended)** Requires an [OpenAI API subscription](https://platform.openai.com/api-keys){rel=""nofollow""} — create a key there and set it as an environment variable. ```bash export BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER=openai export OPENAI_API_KEY=sk-... bm reindex --embeddings ``` **Option 2: Pin ONNX Runtime** ```bash uv pip install 'onnxruntime<1.24' bm reindex --embeddings ``` --- ## Reindexing ```bash # Rebuild both search index and embeddings bm reindex # Rebuild only vector embeddings bm reindex --embeddings # Rebuild only full-text search index bm reindex --search # Reindex a specific project bm reindex -p my-project ``` ### When you need to reindex - **First time** — Happens automatically on first startup - **Switching provider or model** — Embeddings from different models aren't compatible - **After a database reset** — `bm reset` clears everything - **Troubleshooting** — A fresh reindex can fix index issues --- ## FAQ ### Is this RAG? Sort of. RAG (retrieval-augmented generation) usually means fetching relevant documents and feeding them to an AI as context. Basic Memory does that — but it's tighter than a typical RAG pipeline in two ways. First, your AI reads and writes notes directly through MCP tools, and search is just one of several ways it navigates your knowledge. It's less "retrieve and generate" and more "the AI already lives in your notes." Second, most RAG setups assume static content — you load documents once and query them. Basic Memory watches for changes and selectively re-indexes only the chunks that were modified. Your knowledge base is alive, and the search index stays current as you and your AI work. ### Do I need an API key to use semantic search? No. The default embedding provider (FastEmbed) runs entirely on your machine — no API key, no network calls, no cost. If you want to use OpenAI embeddings instead, that does require an OpenAI API key. See [Embedding providers](https://docs.basicmemory.com/#embedding-providers). ### Does semantic search send my notes to the cloud? Not with the default setup. FastEmbed generates embeddings locally on your machine. Nothing leaves your computer. If you switch to OpenAI embeddings, your note text is sent to OpenAI's API for embedding — but the resulting vectors are stored locally. ### How many notes can it handle? Thousands without issue. The initial indexing takes a few minutes for a few hundred notes, and after that new or edited notes are indexed incrementally. The SQLite-based vector store is fast for typical personal knowledge bases. ### My search results aren't great. What can I do? A few things to try: - **Be more specific in your query.** "authentication" is vague; "how we handle JWT token refresh" gives the vector search more meaning to work with. - **Lower the similarity threshold.** The default `0.55` filters out loosely related results. Try `0.3` if you want broader recall. See [Configuration](https://docs.basicmemory.com/#configuration). - **Check that embeddings are built.** Run `bm reindex --embeddings` to make sure the index is up to date. - **Try a different search mode.** If you're looking for an exact term, use text search. If you're exploring a concept, use vector search directly instead of hybrid. ### Can I use a different embedding model? Yes. You can switch between FastEmbed (local, free) and OpenAI (API, paid). See [Embedding providers](https://docs.basicmemory.com/#embedding-providers). After switching, run `bm reindex --embeddings` since embeddings from different models aren't compatible. ### Does Basic Memory Cloud support semantic search? Yes. Cloud instances have semantic search enabled by default, using the same hybrid search. No setup required — it works the same way as local. ### What inspired Basic Memory's search? Basic Memory's hybrid search draws on ideas from the open source community — in particular [QMD](https://github.com/tobi/qmd){rel=""nofollow""}, which combines BM25 keyword search with vector semantic search in a local-first design. We loved the approach and wanted it integrated into Basic Memory's read-write knowledge system, where the AI doesn't just search your notes but actively works in them. --- ## Next steps ::card-group :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- `search_notes` parameters and search modes. ::: :::card --- icon: i-lucide-settings title: Configuration to: https://docs.basicmemory.com/reference/configuration --- All semantic settings and environment variables. ::: :::card --- icon: i-lucide-shield-check title: Schema System to: https://docs.basicmemory.com/concepts/schema-system --- Define and validate note structure with schemas. ::: :: # Metadata Search Every note in Basic Memory has YAML frontmatter at the top. Metadata search lets you find notes by those fields — status, type, tags, custom fields, anything you put there. It's how you ask things like *"show me all in-progress specs tagged security"* or *"find decisions made in the last quarter with priority high or critical"* without scanning text. Metadata search is a parameter on the same [`search_notes`](https://docs.basicmemory.com/reference/mcp-tools-reference#search_notes) tool you use for text and [semantic search](https://docs.basicmemory.com/concepts/semantic-search). You can use it on its own, or combine it with a text query and tag filters. ::tip Frontmatter is structured data. The richer your frontmatter, the sharper your search. A note with `type: meeting` , `status: open` , `priority: high` , and `attendees: [...]` is reachable from many more angles than one with just a title. :: --- ## What's in your frontmatter Anything you put in the YAML block at the top of a note becomes searchable: ```markdown --- title: Auth Design type: spec tags: [security, oauth] status: in-progress priority: high confidence: 0.85 --- ``` A few fields have shortcuts in `search_notes` (`tags`, `status`, `type`), but all custom fields work the same way through `metadata_filters`. You can also reach into nested objects with **dot notation** — `schema.confidence` targets the `confidence` key inside a `schema` object. ::note Field **names** must match the chars `A-Z a-z 0-9 _ -` (with `.` for nesting). Field **values** can be strings, numbers, booleans, dates, or lists. :: --- ## Filter syntax `metadata_filters` is a JSON object. Each key is a field name; each value is either a literal (for equality) or an operator object. Multiple top-level keys combine with **AND** — all conditions must match. ### Equality ```json {"status": "in-progress"} ``` ### Array contains (all values present) For list-valued fields like `tags`, an array means *"all of these"*: ```json {"tags": ["security", "oauth"]} ``` ### `$in` — any of Match if the field equals **any** value in the list. This is how you express OR within a single field: ```json {"priority": {"$in": ["high", "critical"]}} ``` ### Comparison — `$gt`, `$gte`, `$lt`, `$lte` Numeric or lexicographic comparison; boundaries on `$gte`/`$lte` are inclusive. ```json {"confidence": {"$gt": 0.7}} {"score": {"$lte": 100}} ``` ### `$between` — inclusive range Both ends included; the value must be exactly two items: ```json {"confidence": {"$between": [0.5, 0.9]}} ``` ### Nested fields (dot notation) ```json {"schema.confidence": {"$gt": 0.7}} ``` ### Operator reference | Operator | Value | Behavior | | ---------------------------- | ----------------------------- | -------------------------------------------- | | *(scalar)* | string / number / bool / date | Exact match | | *(array)* | list of scalars | All values must be present (for list fields) | | `$in` | non-empty list | Any of | | `$gt`, `$gte`, `$lt`, `$lte` | number | Comparison (gte/lte inclusive) | | `$between` | `[min, max]` | Inclusive range, exactly 2 values | ::note Each operator object holds **one** operator. `{"$gt": 0.5, "$lt": 1.0}` is invalid — use `{"$between": [0.5, 1.0]}` instead. There's no `$ne` , `$nin` , `$regex` , or `$exists` ; combine multiple top-level keys with AND, and use `$in` for OR within a field. :: --- ## Convenience shortcuts `search_notes` exposes a few common metadata filters as top-level parameters: | Shortcut | Equivalent filter | | --------------------------------- | ------------------------ | | `tags=["security"]` | `{"tags": ["security"]}` | | `status="draft"` | `{"status": "draft"}` | | `note_types=["spec", "decision"]` | type filter (any of) | You can also write a tag filter directly in the query string: ```python # All equivalent search_notes("tag:security") search_notes(tags=["security"]) search_notes(metadata_filters={"tags": ["security"]}) ``` Multiple tags in the shorthand mean *all of them*: ```python search_notes("tag:tier1,alpha") # comma-separated search_notes("tag:tier1 alpha") # space-separated # Both require BOTH tags to be present. ``` If a key appears in both a shortcut and `metadata_filters`, the explicit filter wins. --- ## Combining with text and semantic search Metadata filters compose with everything else `search_notes` does. The text query and the filters apply together (AND): ```python # OAuth-related notes that are still in progress search_notes("OAuth", metadata_filters={"status": "in-progress"}) # Pure metadata — no text query search_notes(metadata_filters={"type": "spec", "status": "active"}) # Text + tag shortcut + metadata search_notes("auth", tags=["security"], metadata_filters={"priority": {"$in": ["high", "critical"]}}) ``` See [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search) for how text and vector modes interact. --- ## From the CLI `bm tool search-notes` mirrors the same surface: ```bash # Simple equality bm tool search-notes "" --meta status=draft # Multiple --meta flags AND together bm tool search-notes "" --meta status=active --meta priority=high # Full JSON filter bm tool search-notes "" --filter '{"confidence": {"$between": [0.3, 0.8]}}' # Convenience shortcuts bm tool search-notes "auth" --tag security --tag oauth --status draft --type spec ``` See [CLI Reference](https://docs.basicmemory.com/reference/cli-reference#bm-tool-search-notes) for every flag. --- ## Worked examples Given a few notes like this: ```markdown --- title: Auth Design type: spec status: in-progress priority: high tags: [security, oauth] confidence: 0.85 --- ``` ```markdown --- title: Search Redesign type: spec status: planning priority: medium tags: [search, performance] confidence: 0.6 --- ``` | You want… | `metadata_filters` | | ---------------------------------------------- | ----------------------------------------------------------------------- | | All in-progress specs | `{"status": "in-progress", "type": "spec"}` | | Specs with confidence above 0.7 | `{"type": "spec", "confidence": {"$gt": 0.7}}` | | Anything high or critical priority | `{"priority": {"$in": ["high", "critical"]}}` | | Specs in confidence range [0.5, 0.9] | `{"type": "spec", "confidence": {"$between": [0.5, 0.9]}}` | | Notes tagged both `security` AND `oauth` | `{"tags": ["security", "oauth"]}` | | "OAuth" matches in still-open work | use `search_notes("OAuth", metadata_filters={"status": "in-progress"})` | | Anything with nested `schema.confidence` ≥ 0.7 | `{"schema.confidence": {"$gte": 0.7}}` | --- ## Type handling - **Strings** match exactly (case-sensitive). - **Numbers** — comparison operators detect numeric values automatically, so `"0.5"` and `0.5` compare the same way. - **Booleans** are compared as the strings `"True"` and `"False"`. - **Dates and datetimes** are normalized to ISO strings. - **Missing fields** never match — filtering on a key the note doesn't have returns no result for that note (not a null match). --- ## Limits and caveats - **AND only at the top level.** Combine multiple keys to AND; use `$in` for OR within a single field. There's no top-level `$or`. - **No full-text matching inside metadata.** Use exact, range, or `$in` matching — for free-text search across note bodies, use [text or semantic search](https://docs.basicmemory.com/concepts/semantic-search). - **Lists in filters must be non-empty.** `{"tags": []}` is rejected. - **`$between` requires exactly two values.** - **No `$exists`, `$ne`, `$nin`, `$regex`.** They're not in the operator set. --- ## Related - [Search Notes (MCP Tools Reference)](https://docs.basicmemory.com/reference/mcp-tools-reference#search_notes) - [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search) — text, vector, and hybrid modes - [Schema System](https://docs.basicmemory.com/concepts/schema-system) — make required frontmatter fields explicit - [Knowledge Format](https://docs.basicmemory.com/concepts/knowledge-format) — the structure of a note - [CLI: `bm tool search-notes`](https://docs.basicmemory.com/reference/cli-reference#bm-tool-search-notes) # Claude Desktop Claude Desktop is the flagship way to use Basic Memory. Connect once, and Claude gains full access to your knowledge base — reading, writing, searching, and building on past conversations automatically. Basic Memory describes its tools to Claude through the Model Context Protocol, so Claude already knows how to use them. You just ask in plain language. ## Cloud Setup ::steps ### Sign Up Create your account at [app.basicmemory.com](https://app.basicmemory.com){rel=""nofollow""} ### Add Remote MCP Connector In Claude Desktop, go to **Settings > Claude > Connectors** Click "Add connector" and enter: - **Name**: Basic Memory - **Remote MCP server URL**: `https://cloud.basicmemory.com/mcp` ![Add connector](https://docs.basicmemory.com/claude-settings-add-connector.png) ### Authenticate Click "Connect" and follow the OAuth flow to grant permissions ![Configure connector](https://docs.basicmemory.com/claude-settings-configure.png) ### Verify Setup In Claude, click the tools icon to see Basic Memory tools ![Tools menu](https://docs.basicmemory.com/claude-settings-tools.png) Try prompting: `List my projects` :: ::tip See the [Cloud Guide](https://docs.basicmemory.com/cloud/cloud-guide) for web editor usage and troubleshooting. :: --- ## Local Setup For local installation, follow the [Quickstart: Local](https://docs.basicmemory.com/start-here/quickstart-local) guide. It walks you through installing Basic Memory and configuring Claude Desktop in a few minutes. --- ## Try It Once connected, try these prompts to see Basic Memory in action: **Save something from a conversation:** ```text Create a note summarizing what we just discussed about API rate limiting. ``` Claude will write a structured note with observations, tags, and relations to other topics in your knowledge base. **Search with meaning, not just keywords:** ```text Find my notes about login security. ``` Even if your notes use terms like "authentication hardening" or "credential rotation," semantic search surfaces them based on meaning. See [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search) for details. **Pick up where you left off:** ```text What have we been working on this week? ``` Claude checks recent activity and offers to continue any thread. Changes sync in real time — edits you make in any text editor appear instantly in your next conversation. You can also reference specific notes with `memory://` URLs. Learn more in [Memory URLs](https://docs.basicmemory.com/concepts/memory-urls). --- ## Troubleshooting ### Tools not appearing - **Cloud**: Re-open Claude Desktop after adding the connector. Check that the connector URL is exactly `https://cloud.basicmemory.com/mcp`. - **Local**: Verify `uv` is installed (`which uvx`), check config JSON syntax, and restart Claude Desktop. - **Advanced research is on**: Research mode runs in a separate environment that can't reach any MCP connectors. See [Claude Research Mode](https://docs.basicmemory.com/integrations/claude-research-mode). ### Tools appear but return errors - Check Basic Memory is installed: `basic-memory --version` - Verify sync status: `basic-memory status` - Check file permissions in your `~/basic-memory` directory ### Changes not showing up - Real-time sync is on by default. Run `basic-memory status` to confirm. - Make sure the file is in the correct project directory. - If needed, run the watcher manually: `basic-memory watch` ### Project selection Projects are selected at the start of each conversation. For single-project setups, set a default in `~/.basic-memory/config.json`: ```json { "default_project": "main" } ``` --- ## Next Steps ::card-group :::card --- icon: i-lucide-book-open title: User Guide to: https://docs.basicmemory.com/local/user-guide --- Daily workflows and usage patterns for getting the most out of Basic Memory. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- How observations, relations, and tags create a semantic knowledge graph. ::: :::card --- icon: i-lucide-bot title: AI Assistant Guide to: https://docs.basicmemory.com/reference/ai-assistant-guide --- How Claude uses Basic Memory tools under the hood. ::: :::card --- icon: i-lucide-sparkles title: Agent Skills to: https://docs.basicmemory.com/integrations/skills --- Pre-built skills that teach Claude best practices for Basic Memory. ::: :: # OpenClaw Plugin The [openclaw-basic-memory](https://github.com/basicmachines-co/openclaw-basic-memory){rel=""nofollow""} plugin connects Basic Memory to OpenClaw, giving agents persistent, searchable memory stored as plain Markdown files. Agents gain composited memory search, automatic context recall, conversation capture, slash commands, and bundled workflow skills — all with zero configuration. The plugin is open source — browse the source on [GitHub](https://github.com/basicmachines-co/openclaw-basic-memory){rel=""nofollow""}. ::tip Requires [OpenClaw](https://openclaw.dev){rel=""nofollow""} and a local Basic Memory installation. The plugin auto-installs the `bm` CLI on first startup if it's not already on your PATH. :: --- ## Installation Install the plugin and restart the gateway: ```bash openclaw plugins install @basicmemory/openclaw-basic-memory openclaw gateway restart ``` That's it — the plugin works with zero configuration by default. --- ## Configuration The plugin works out of the box with `enabled: true`. For advanced setups, configure via your OpenClaw plugin settings: | Option | Default | Description | | ------------- | ----------- | --------------------------------------------------- | | `project` | — | Basic Memory project name | | `projectPath` | — | Path to project directory | | `memoryDir` | `memory/` | Directory for memory files | | `memoryFile` | `MEMORY.md` | Primary memory file name | | `autoCapture` | `true` | Record conversation turns as daily notes | | `autoRecall` | `true` | Load active tasks and recent notes at session start | | `debug` | `false` | Enable debug logging | --- ## How It Works ### Composited Memory Search When your agent searches memory, the plugin queries three sources in parallel and merges the results: 1. **MEMORY.md** — Text search of your primary memory file 2. **Knowledge Graph** — Hybrid full-text + vector search across all notes 3. **Active Tasks** — Scans `memory/tasks/` for in-progress work This means a single search returns context from structured notes, free-form memory, and active task tracking simultaneously. ### Auto-Recall At session start, the plugin automatically loads active tasks and recent notes so your agent has immediate context without you needing to ask. ### Auto-Capture Conversation turns are recorded as timestamped entries in daily notes, building a searchable log of your interactions over time. ### Persistent Connection The plugin maintains a long-lived Basic Memory process over stdio, avoiding startup overhead on each tool call. ### Multi-Project & Cloud Access Because the plugin uses the full Basic Memory stack, your OpenClaw agent has access to every project in your knowledge base — not just a single workspace. Use `list_memory_projects` to browse projects and switch between them on the fly. This also means your agent benefits from [local/cloud routing](https://docs.basicmemory.com/cloud/routing). You can keep the agent's own memory local while routing shared or team projects through Basic Memory Cloud, or run everything in the cloud for cross-device access. The agent uses the same tools either way — routing is transparent. In practice, your OpenClaw agent gets: - **Its own long-term memory** — auto-captured conversations and task tracking that persist across sessions - **Access to external projects** — search and read notes from any project in your knowledge base - **Local/cloud hybrid** — mix local and cloud-routed projects depending on sensitivity, collaboration needs, or device portability --- ## Agent Tools The plugin exposes 14 tools to your OpenClaw agent: | Tool | Description | | ---------------------- | ------------------------------------------------- | | `memory_search` | Composited search across all memory sources | | `memory_get` | Retrieve a specific memory entry | | `search_notes` | Full-text and semantic search across notes | | `read_note` | Read a note by title, permalink, or memory:// URL | | `write_note` | Create or update a note | | `edit_note` | Incremental edits (append, prepend, find/replace) | | `delete_note` | Delete a note from the knowledge base | | `move_note` | Move a note with database consistency | | `build_context` | Navigate the knowledge graph via memory:// URLs | | `list_memory_projects` | List all projects with status | | `list_workspaces` | List available workspaces | | `schema_validate` | Validate notes against a schema | | `schema_infer` | Infer a schema from existing notes | | `schema_diff` | Detect schema drift | --- ## Slash Commands | Command | Description | | ----------- | -------------------------------------------------- | | `/bm-setup` | Initialize Basic Memory configuration | | `/remember` | Save something to memory | | `/recall` | Search and retrieve from memory | | `/tasks` | Manage structured task notes | | `/reflect` | Review conversations and extract insights | | `/defrag` | Split bloated files, merge duplicates, restructure | | `/schema` | Schema lifecycle — infer, validate, detect drift | --- ## Bundled Skills The plugin ships with 6 pre-built skills that teach agents best practices for Basic Memory workflows: | Skill | Purpose | | -------------------------- | ------------------------------------------------------------- | | **memory-notes** | Core note format — frontmatter, observations, relations | | **memory-tasks** | Structured task tracking that survives context compaction | | **memory-schema** | Schema lifecycle — infer, validate, detect drift | | **memory-reflect** | Review conversations, extract insights, consolidate knowledge | | **memory-defrag** | Split bloated files, merge duplicates, restructure hierarchy | | **memory-metadata-search** | Query notes by custom frontmatter fields | ::note These are the same skills available in the standalone [skills collection](https://docs.basicmemory.com/integrations/skills) , bundled for convenience. :: --- ## Next Steps ::card-group :::card --- icon: i-lucide-sparkles title: Agent Skills to: https://docs.basicmemory.com/integrations/skills --- Learn more about the individual skills bundled with the plugin. ::: :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- Full reference for all Basic Memory MCP tools. ::: :::card --- icon: i-lucide-cloud title: Local & Cloud Routing to: https://docs.basicmemory.com/cloud/routing --- Run some projects locally and others in the cloud. ::: :::card --- icon: i-lucide-shield-check title: Schema System to: https://docs.basicmemory.com/concepts/schema-system --- Understand schema validation for structured notes. ::: :::card --- icon: i-lucide-github title: GitHub Repository to: https://github.com/basicmachines-co/openclaw-basic-memory --- Source code, issues, and contributing guide. ::: :: # Hermes Plugin The [hermes-basic-memory](https://github.com/basicmachines-co/hermes-basic-memory){rel=""nofollow""} plugin connects Basic Memory to [Hermes Agent](https://github.com/NousResearch/hermes-agent){rel=""nofollow""}, giving agents a persistent knowledge graph stored as plain Markdown. Hermes ships with no external memory provider by default; this plugin replaces that with a real graph — search-before-answer recall, automatic conversation capture, end-of-session summaries, and a curated set of `bm_*` tools the agent can call directly. The plugin is open source — browse the source on [GitHub](https://github.com/basicmachines-co/hermes-basic-memory){rel=""nofollow""}. ::warning **Slash commands need a Hermes Agent-side patch on current releases.** The plugin's agent tools ( `bm_*` ) and auto-capture work as documented once installed. The native `/bm-*` **slash commands** , however, do not appear in gateway sessions on Hermes Agent releases through `v0.14.0` / `v2026.5.16` (verified 2026-05-16). This is a Hermes Agent plugin-loading gap — exclusive memory-provider plugins aren't loaded during gateway slash-command discovery — not a plugin bug. The plugin ships a best-effort workaround, but it isn't sufficient for gateway startup discovery in affected builds. Until the upstream Hermes fix lands, apply the Hermes Agent-side patch documented in [MONKEYPATCH.md](https://github.com/basicmachines-co/hermes-basic-memory/blob/main/MONKEYPATCH.md){rel=""nofollow""} . This affects only the slash-command surface; nothing else in this page depends on it. :: ::tip Requires [Hermes Agent](https://github.com/NousResearch/hermes-agent){rel=""nofollow""} and [`uv`](https://docs.astral.sh/uv/){rel=""nofollow""} on your PATH. The plugin auto-installs the `bm` CLI on first init via `uv tool install basic-memory` (a one-time ~10s pause if it isn't already present). :: --- ## Installation Install the plugin: ```bash hermes plugins install basicmachines-co/hermes-basic-memory ``` Then activate it in `~/.hermes/config.yaml`: ```yaml memory: provider: basic-memory ``` If you run the gateway, restart it: ```bash hermes gateway restart ``` Verify the plugin is live: ```bash hermes memory status ``` ```text Provider: basic-memory Plugin: installed ✓ Status: available ✓ ``` ::note The plugin needs the `mcp` Python package in the Hermes venv. `hermes plugins install` usually installs it from the plugin's `pip_dependencies` . If it doesn't, run `uv pip install --python ~/.hermes/hermes-agent/venv/bin/python mcp` . :: --- ## Configuration Defaults are reasonable for local use — no configuration required. To override, write `~/.hermes/basic-memory.json` or run `hermes memory setup basic-memory`: | Key | Default | Description | | --------------------- | ------------------ | --------------------------------------------------------------------------------- | | `mode` | `local` | `local` (in-process) or `cloud` (route through Basic Memory Cloud) | | `project` | `hermes-memory` | Basic Memory project name | | `project_path` | `~/hermes-memory/` | Local mode only — where the project's files live | | `capture_per_turn` | `true` | Append every user/assistant exchange to a session transcript note | | `capture_session_end` | `true` | Write a summary note when the session ends | | `capture_folder` | `hermes-sessions` | Folder for auto-captured session notes | | `remember_folder` | `bm-remember` | Folder for `/bm-remember` quick captures (kept separate from session transcripts) | ```json { "mode": "local", "project": "hermes-memory", "project_path": "~/hermes-memory/", "capture_per_turn": true, "capture_session_end": true, "capture_folder": "hermes-sessions", "remember_folder": "bm-remember" } ``` --- ## How It Works ### Search-Before-Answer Recall Before the agent answers a question about prior work, it searches the knowledge graph so it can build on what's already documented instead of starting cold. Recall is injected into context automatically each turn. ### Auto-Capture Every user/assistant exchange is appended to a running session-transcript note. When the session ends, a separate summary note is written and linked back to the transcript via a `summary_of` relation — so a session is both fully logged and quickly skimmable. ### Persistent Connection The plugin holds a long-lived `bm mcp` process open over stdio for the agent's lifetime (\~0.1s per tool call). Shelling out to the `bm` CLI would spawn a fresh Python process per call (1–2s cold start) and bypass automatic capture — so the agent is steered to use the `bm_*` tools directly. ### Cross-Project & Workspace Routing Every read/write tool accepts an optional `project` (name, optionally workspace-qualified like `"personal/main"`) or `project_id` (UUID from `bm_projects`). The agent can read or write against any project in your knowledge base without reconfiguring the plugin — and disambiguate same-named projects across cloud workspaces. See [local/cloud routing](https://docs.basicmemory.com/cloud/routing) for how project modes work. In practice the Hermes agent gets: - **Its own long-term memory** — auto-captured conversations and summaries that persist across sessions - **Access to external projects** — search and write notes in any project, routed per call - **Local/cloud hybrid** — keep the agent's memory local while routing shared projects through Basic Memory Cloud; the tools behave identically either way --- ## Agent Tools The plugin exposes 10 tools (a curated subset of Basic Memory's MCP surface): | Tool | Description | | --------------- | ------------------------------------------------------------------ | | `bm_search` | Semantic + full-text search; the agent calls this before answering | | `bm_read` | Read a note by title, permalink, or `memory://` URL | | `bm_write` | Create a note (decisions, meeting notes, insights) | | `bm_edit` | Incremental edits — append, prepend, find/replace, replace-section | | `bm_context` | Navigate the graph via `memory://` URLs to find related notes | | `bm_delete` | Delete a note | | `bm_move` | Move a note to a different folder | | `bm_recent` | List notes updated within a timeframe (default `7d`) | | `bm_projects` | List available projects with their UUIDs for routing | | `bm_workspaces` | List Basic Memory Cloud workspaces | ::note Every read/write tool also accepts `project` / `project_id` for per-call routing. `bm_projects` and `bm_workspaces` are discovery tools — they list across everything and take no routing arguments. :: --- ## Slash Commands ::note On Hermes Agent releases through `v0.14.0` / `v2026.5.16` , these commands require the Hermes Agent-side patch in [MONKEYPATCH.md](https://github.com/basicmachines-co/hermes-basic-memory/blob/main/MONKEYPATCH.md){rel=""nofollow""} — see the warning at the top of this page. The agent tools above are unaffected. :: For direct, in-session use without going through the agent: | Command | Description | | -------------------------- | ----------------------------------------------------- | | `/bm-search ` | Search the knowledge graph | | `/bm-read ` | Read a note by title, permalink, or `memory://` URL | | `/bm-context ` | Show the context graph for a note | | `/bm-recent [timeframe]` | Recently updated notes (default `7d`) | | `/bm-status` | Plugin/provider status — mode, project, capture flags | | `/bm-remember ` | Quick-capture a note (title from the first line) | | `/bm-project` | List available projects; the active one is marked | | `/bm-workspace` | List Basic Memory Cloud workspaces (cloud mode) | --- ## Bundled Skill The plugin ships a `basic-memory` skill that gives the agent a longer reference doc on top of the always-on guidance: the note format, cross-project routing, permalink shapes, and a worked discovery → route → write → verify recipe. It's opt-in via `skill:view basic-memory:basic-memory`. --- ## Next Steps ::card-group :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- Full reference for all Basic Memory MCP tools. ::: :::card --- icon: i-lucide-cloud title: Local & Cloud Routing to: https://docs.basicmemory.com/cloud/routing --- Run some projects locally and others in the cloud. ::: :::card --- icon: i-lucide-link title: Memory URLs to: https://docs.basicmemory.com/concepts/memory-urls --- How `memory://` addressing and permalinks work. ::: :::card --- icon: i-lucide-plug title: OpenClaw Plugin to: https://docs.basicmemory.com/integrations/openclaw --- The sibling plugin for OpenClaw agents. ::: :::card --- icon: i-lucide-github title: GitHub Repository to: https://github.com/basicmachines-co/hermes-basic-memory --- Source code, issues, and contributing guide. ::: :: # Claude Research Mode When you turn on **advanced research**, Claude hands your request to a dedicated research agent that works across the web and Google Drive. That agent runs in its own environment and **does not have access to your connected MCP servers** — including Basic Memory, Gmail, Google Calendar, and any other connectors. This is a limitation of research mode itself, not of any individual connector: every MCP connector is unavailable during a research run, in the same way. What this means in practice: - **During a research run,** Claude can't read from or write to Basic Memory (or call any other connector's tools). It will research using web and Drive sources only. - **After a research run finishes,** control returns to the normal conversation — which *does* have your connectors. At that point Claude can save the results to Basic Memory, draft an email, add a calendar event, and so on. So research and your connectors aren't combined in a single step, but they chain cleanly: **research first, then act on the results with your connectors second.** --- ## Recommended flow: research → save to Basic Memory ::steps ### Turn advanced research on Toggle **advanced research** in the message composer, then run your query — for example, *"survey how other agent-memory tools expose graph APIs."* ### Wait for the report Let the research run complete. The report comes back inline in the conversation. ### Turn advanced research off Use the same toggle to drop back into normal conversation. This is the important step — leaving research on keeps connectors out of reach. ### Ask Claude to save it Now you're back in the normal tool path. Ask Claude to write up the results — *"Save that as a note in my `research` project"* — and it can call Basic Memory's [`write_note`](https://docs.basicmemory.com/reference/mcp-tools-reference#write_note) directly. :: The same pattern works in reverse for context you already have: if you need Claude to *use* your Basic Memory notes as input, keep research off and ask normally — Claude can read your notes and reason over them directly. Use research only when you specifically want fresh web/Drive sources. ::tip **Which mode do I need?** If the question is "go find out what's out there on the web," use research. If it's "do something with my notes/data," keep research off. :: --- ## Why this happens Research mode runs a separate agent with its own toolset (web search, Google Drive). MCP connectors live on the main Claude conversation, not inside the research agent's environment. The research agent doesn't know your connectors exist, so it can't call them — and there's no way to "pass through" a connector during a research run. This is the same for **every** MCP connector, not specific to Basic Memory. If you have a workflow that wants both web research *and* your private knowledge base in a single step, today the answer is to run them sequentially: research first, then a follow-up turn that uses your connectors on the results. --- ## Related ::card-group :::card --- icon: i-lucide-monitor title: Claude Desktop to: https://docs.basicmemory.com/integrations/claude-desktop --- Connect Basic Memory to Claude Desktop or Claude on the web. ::: :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- Every tool Claude can call when research mode is off. ::: :::card --- icon: i-lucide-layout-dashboard title: Web App to: https://docs.basicmemory.com/cloud/web-app --- Save and organize research results in the cloud app. ::: :: # Claude Code Claude Code is powerful, but every session starts from zero. Basic Memory gives it a persistent knowledge base -- so your AI remembers project decisions, code patterns, and context across every session. > New to this setup? [Basic Memory for Claude Code](https://basicmemory.com/for/claude-code){rel=""nofollow""} has a two-minute overview of what persistent memory changes. ## Cloud Setup ::steps ### Sign Up Create your account at [app.basicmemory.com](https://app.basicmemory.com){rel=""nofollow""}. ### Add Remote MCP Server In your terminal, add the remote MCP server: ```bash claude mcp add -s user -t http basic-memory-cloud https://cloud.basicmemory.com/mcp ``` ### Authenticate Follow the OAuth flow in Claude Code to grant permissions. ### Verify Run `/mcp` in Claude Code and confirm Basic Memory tools are listed. :: ::tip See the [Cloud Guide](https://docs.basicmemory.com/cloud/cloud-guide) for detailed instructions and troubleshooting. :: --- ## Local Setup Install Basic Memory locally ([Quickstart: Local](https://docs.basicmemory.com/start-here/quickstart-local)), then add it to Claude Code: ```bash claude mcp add basic-memory basic-memory mcp ``` Run `/mcp` in Claude Code to confirm the tools are available. --- ## Try It Once connected, try these prompts in Claude Code: ```text "Create a note about our authentication strategy -- we're using JWT with refresh tokens, and here's why..." ``` ```text "Search my notes for anything related to database migration patterns" ``` ```text "What do my notes say about the API rate limiting decision we made last week?" ``` Basic Memory supports [semantic search](https://docs.basicmemory.com/concepts/semantic-search), so your queries don't need to match exact keywords -- it finds notes by meaning. For the full list of tools Claude Code can use, see the [MCP Tools Reference](https://docs.basicmemory.com/reference/mcp-tools-reference). --- ## CLAUDE.md and Basic Memory Claude Code uses `CLAUDE.md` files for project-level instructions. Basic Memory complements this nicely: `CLAUDE.md` tells Claude Code *how* to work in a project, while Basic Memory stores the *knowledge* -- decisions, architecture notes, research, context -- that doesn't belong in a static instruction file. --- ## Agent Skills Install [agent skills](https://docs.basicmemory.com/integrations/skills) to teach Claude Code best practices for writing well-structured notes. Skills give your AI reusable patterns so notes are consistent and useful from the start. --- ## Troubleshooting **Tools not showing up in `/mcp`?** - For local: verify Basic Memory is installed (`basic-memory --version`) and re-add the server: `claude mcp remove basic-memory && claude mcp add basic-memory basic-memory mcp` - For cloud: re-run the `claude mcp add` command and complete the OAuth flow again **Notes not syncing?** - Check sync status: `basic-memory status` - Look for errors in `~/.basic-memory/logs/` --- ## FAQ ### Claude Code already has CLAUDE.md and auto memory. Why add Basic Memory? Claude Code's built-in memory is great for project instructions and short learnings. Basic Memory adds a full knowledge base on top — searchable notes with semantic connections, observations, and relations that span across projects and AI tools. Think of CLAUDE.md as "how to work here" and Basic Memory as "everything we know." See [Using Basic Memory with Built-in AI Memory](https://docs.basicmemory.com/concepts/vs-built-in-memory) for a deeper comparison. ### How does Basic Memory work alongside CLAUDE.md? They complement each other. `CLAUDE.md` holds project instructions and coding standards. Basic Memory holds evolving knowledge — decisions, architecture notes, research, meeting notes, and context that grows over time. Claude Code's auto memory captures small preferences; Basic Memory captures structured knowledge you can search, link, and reuse across any AI tool. --- ::note **Basic Memory also works with:** [Cursor](https://docs.basicmemory.com/integrations/cursor) · [OpenAI Codex](https://docs.basicmemory.com/integrations/codex) · [Claude Desktop](https://docs.basicmemory.com/integrations/claude-desktop) · [VS Code](https://docs.basicmemory.com/integrations/vscode) · [Obsidian](https://docs.basicmemory.com/integrations/obsidian) :: ## Next Steps ::card-group :::card --- icon: i-lucide-folder-kanban title: Project Documentation to: https://docs.basicmemory.com/how-to/project-documentation --- Learn how to document your development projects. ::: :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- Full reference for all 17 Basic Memory tools. ::: :::card --- icon: i-lucide-sparkles title: Agent Skills to: https://docs.basicmemory.com/integrations/skills --- Pre-built skills that teach Claude Code best practices for Basic Memory. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Structure effective development documentation. ::: :: # ChatGPT ChatGPT supports remote MCP servers, giving it access to your Basic Memory knowledge base. Since ChatGPT only connects to remote servers, **Basic Memory Cloud is required**. ## Cloud Setup ::steps ### Sign Up Create your account at [app.basicmemory.com](https://app.basicmemory.com){rel=""nofollow""}. ### Get Your MCP Endpoint Your remote MCP URL: `https://cloud.basicmemory.com/mcp` ### Configure ChatGPT In ChatGPT, go to **Settings > Developer > Custom MCP Servers** and add: - **Name**: Basic Memory - **Server URL**: `https://cloud.basicmemory.com/mcp` ### Authenticate Follow the OAuth flow to grant ChatGPT access to your Basic Memory account. ### Enable in Conversations When chatting, enable Basic Memory from the MCP server selector to start using your knowledge base. :: ::tip See the [Cloud Setup Guide](https://docs.basicmemory.com/cloud/cloud-guide) for detailed instructions. :: ## Try It Once connected, ask ChatGPT to work with your knowledge base: - **Search**: "Find my notes about authentication design" - **Retrieve**: "Show me the full contents of my API documentation" - **Semantic search**: "Find notes conceptually related to microservice architecture" (requires full MCP access) ChatGPT will call the appropriate tools behind the scenes, searching and fetching documents as needed. ## Important Notes ::warning **ChatGPT Plus or Pro subscription required.** MCP integration is not available on ChatGPT's free tier. :: ::note **Default vs full MCP access** By default, ChatGPT exposes two tools: `search` for finding content and `fetch` for retrieving documents. To unlock all 17+ MCP tools — including `write_note`, `edit_note`, semantic search with text/vector/hybrid modes, and project management — explicitly enable the Basic Memory MCP server in ChatGPT's developer settings. See the [MCP Tools Reference](https://docs.basicmemory.com/reference/mcp-tools-reference) for full tool documentation and the [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search) guide for search mode details. :: ## Troubleshooting **"MCP server not available"** — Confirm you have a ChatGPT Plus or Pro subscription. MCP is not available on the free tier. **Authentication errors** — Re-add the MCP server in ChatGPT settings and complete the OAuth flow again. **No results returned** — Make sure your Basic Memory Cloud account has synced content. Check your project at [app.basicmemory.com](https://app.basicmemory.com){rel=""nofollow""}. ## Next Steps ::card-group :::card --- icon: i-lucide-cloud title: Cloud Setup Guide to: https://docs.basicmemory.com/cloud/cloud-guide --- Detailed cloud configuration and sync options. ::: :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- Complete documentation for all 17+ MCP tools. ::: :::card --- icon: i-lucide-message-square title: Claude Desktop to: https://docs.basicmemory.com/integrations/claude-desktop --- Full local and remote MCP integration. ::: :: # Google Gemini Google Gemini has native MCP support, so connecting it to Basic Memory takes a single command. ## Cloud Setup No local install needed -- Basic Memory Cloud gives you hosted MCP access. ::steps ### Sign Up Create your account at [app.basicmemory.com](https://app.basicmemory.com){rel=""nofollow""}. ### Add the Remote MCP Server ```bash gemini mcp add -t http basic-memory-cloud https://cloud.basicmemory.com/mcp ``` ### Authenticate Follow the OAuth flow to grant Gemini access to your Basic Memory account. ### Verify ```bash gemini mcp list ``` You should see `basic-memory-cloud` with Connected status. :: ::tip See the [Cloud Setup Guide](https://docs.basicmemory.com/cloud/cloud-guide) for detailed instructions and troubleshooting. :: --- ## Local Setup ### Video Tutorial Watch this quick guide to get started with Basic Memory and Google Gemini: ::div --- style: "position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; margin: 2rem 0;" --- :iframe{allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowFullScreen="true" frameBorder="0" src="https://www.youtube.com/embed/yM3B0e6c9yM" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border-radius: 0.5rem;" title="Basic Memory + Google Gemini Setup Guide"} :: ### Configure Gemini ::steps ### Install ```bash gemini mcp add basic-memory bash -c "uvx basic-memory mcp" ``` ### Verify ```bash gemini mcp list ``` You should see `basic-memory` listed with Connected status. :: ::tip To target a specific project: ```bash gemini mcp add basic-memory bash -c "uvx basic-memory mcp --project your-project-name" ``` To install globally for your user profile, add the `-s user` flag: ```bash gemini mcp add -s user basic-memory bash -c "uvx basic-memory mcp" ``` :: --- ## Try It Once Gemini is connected, give these a spin: **Save a decision** ```text "Create a note about our decision to use JWT-based auth for the API, including the trade-offs we discussed." ``` **Pick up where you left off** ```text "What have I been working on this week? Check recent activity." ``` **Semantic search** ```text "Search my notes for anything related to database migration strategies." ``` For the full list of available tools, see the [MCP Tools Reference](https://docs.basicmemory.com/reference/mcp-tools-reference). --- ## Troubleshooting **Gemini can't find Basic Memory** -- Verify it's installed (`basic-memory --version`), then check `gemini mcp list`. If the entry looks wrong, remove and re-add it: ```bash gemini mcp remove basic-memory gemini mcp add basic-memory bash -c "uvx basic-memory mcp" ``` **memory:// URLs not resolving** -- Make sure the note exists in your current project and that sync is running (`basic-memory status`). **Notes not updating** -- Check file permissions in your knowledge base directory and look for errors in `~/.basic-memory/logs`. --- ## Next Steps ::card-group :::card --- icon: i-lucide-folder-kanban title: Project Documentation to: https://docs.basicmemory.com/how-to/project-documentation --- Learn how to document your projects. ::: :::card --- icon: i-lucide-graduation-cap title: Research & Learning to: https://docs.basicmemory.com/how-to/research-learning --- Build knowledge from your sessions. ::: :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- See every tool Basic Memory exposes. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Structure effective documentation. ::: :: # OpenAI Codex OpenAI Codex is a powerful coding agent, but it starts fresh every time. Basic Memory gives it persistent context through MCP — architecture decisions, API designs, and project knowledge carry over between sessions. Notes created in Codex are immediately available in Claude Code, Cursor, Claude Desktop, or any other MCP client. > New to this setup? [Basic Memory for Codex](https://basicmemory.com/for/codex){rel=""nofollow""} has a two-minute overview of what persistent memory changes. Codex comes in two forms, and both connect to Basic Memory: - **Codex app** — the agent inside ChatGPT (or the Codex desktop app) - **Codex CLI** — the terminal-based coding agent Each one can connect to either a **local** Basic Memory (running on your machine) or **Basic Memory Cloud** (remote MCP). Pick the combination that fits your workflow. ::tip **Cloud is the easiest path for the Codex app.** App clients only speak HTTP/SSE, so connecting to Basic Memory Cloud takes one URL and a sign-in — no local servers to keep running. :: --- ## Codex app The Codex app talks to MCP servers over HTTP, so you give it a URL. ### Connect to Basic Memory Cloud (remote MCP) ::steps ### Get your MCP endpoint Your Basic Memory Cloud URL is: ```text https://cloud.basicmemory.com/mcp ``` ### Add it in Codex In the Codex app, open **Settings → Connectors → Custom MCP** (the exact label may be "MCP Servers" or "Developer → MCP" depending on your version) and add: - **Name**: Basic Memory - **Server URL**: `https://cloud.basicmemory.com/mcp` ### Authenticate Sign in to authorize Codex. Basic Memory Cloud uses OAuth — when prompted, complete the sign-in flow in your browser. ### Enable in conversations Turn on the Basic Memory connector for the conversation, and Codex can read, write, and search your notes. :: ### Connect to a local Basic Memory (local MCP) To point the app at a Basic Memory running on your own machine, start a local HTTP MCP server, then add its URL to Codex: ::steps ### Start a local server ```bash basic-memory mcp --transport streamable-http --port 8000 ``` This exposes Basic Memory at `http://localhost:8000/mcp`. ### Add it in Codex In Codex's MCP/connector settings, add: - **Name**: Basic Memory (local) - **Server URL**: `http://localhost:8000/mcp` :: ::note Local MCP for an app means keeping that `basic-memory mcp` process running while you use Codex. For most app users, the Cloud setup is simpler. :: --- ## Codex CLI The [Codex CLI](https://github.com/openai/codex){rel=""nofollow""} can spawn local MCP servers as subprocesses **or** connect to a remote MCP endpoint via its config file. ### Local MCP ::steps ### Add Basic Memory as a local MCP server ```bash codex mcp add basic-memory bash -c "uvx basic-memory mcp" ``` :::tip To lock it to a specific project, add the `--project` flag: ```bash codex mcp add basic-memory bash -c "uvx basic-memory mcp --project your-project-name" ``` ::: ### Verify ```bash codex mcp list ``` You should see `basic-memory` listed with the command `bash -c uvx basic-memory mcp`. :: #### Video walkthrough ::div --- style: "position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; margin: 2rem 0;" --- :iframe{allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowFullScreen="true" frameBorder="0" src="https://www.youtube.com/embed/BfISDQ0p-UM" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border-radius: 0.5rem;" title="Basic Memory + OpenAI Codex Setup Guide"} :: ### Remote MCP (Basic Memory Cloud) ::steps ### Get an API key Create one in the [web app](https://app.basicmemory.com){rel=""nofollow""} under **Settings → API Keys**. See the [API Keys guide](https://docs.basicmemory.com/cloud/api-keys) for details. ### Export it Add the key to your shell profile (`~/.zshrc` or `~/.bashrc`): ```bash export BASIC_MEMORY_API_KEY= ``` Reload your shell: ```bash source ~/.zshrc ``` ### Configure `~/.codex/config.toml` ```toml [mcp_servers.basic-memory] url = "https://cloud.basicmemory.com/mcp" bearer_token_env_var = "BASIC_MEMORY_API_KEY" ``` The Codex CLI will now connect to Basic Memory Cloud using your API key for authentication. :: --- ## Try it Once configured, try these prompts to see Basic Memory in action: ```text "Create a note about our authentication strategy for the API" ``` Codex creates a structured note with technical details and rationale, saved to your knowledge base. ```text "Search my notes for everything related to database migrations" ``` Codex uses semantic search to find relevant notes across your projects — even when they don't contain the exact words. ```text "What decisions have we made about the API design? Check my notes." ``` Codex loads context from your knowledge base and gives answers grounded in your actual project history. For the full list of tools Codex can use, see the [MCP Tools Reference](https://docs.basicmemory.com/reference/mcp-tools-reference). --- ## Troubleshooting **Codex CLI can't find Basic Memory** — Verify it's installed (`basic-memory --version`), check MCP config (`codex mcp list`), and reinstall if needed: ```bash codex mcp remove basic-memory codex mcp add basic-memory bash -c "uvx basic-memory mcp" ``` **Codex app can't reach a local server** — Confirm `basic-memory mcp --transport streamable-http` is still running and the port matches the URL you gave Codex. Apps can't spawn subprocesses, so the server has to be live. **Cloud authentication errors** — For the CLI, make sure `BASIC_MEMORY_API_KEY` is exported in the shell Codex was launched from. For the app, remove and re-add the connector to redo the OAuth flow. **Context not loading from memory:// URLs** — Confirm the note exists in your current project, check the URL syntax (`memory://folder/note`), and verify sync status with `basic-memory status`. --- ## FAQ ### Does Codex have persistent memory? Not by default. Basic Memory adds persistent, searchable context through MCP, so Codex can access your full project knowledge every session. ### Can I share notes between Codex and other AI tools? Yes. Basic Memory uses plain Markdown files as the source of truth. Notes created in Codex are immediately available in Claude Code, Cursor, Claude Desktop, or any MCP client. ### App or CLI — which should I use? They're complementary. Many people use the **CLI** with local MCP while coding, and the **app** with cloud MCP for planning or review on another device. Both read the same knowledge base. ### Local or remote MCP? - **Local** keeps everything on your machine — best for personal projects and when you don't want anything in the cloud. - **Remote** (Basic Memory Cloud) means your notes are reachable from any device and any client, with no local processes to manage. Required for the app unless you're willing to run a local HTTP server. --- ::note **Basic Memory also works with:** [Claude Code](https://docs.basicmemory.com/integrations/claude-code) · [Cursor](https://docs.basicmemory.com/integrations/cursor) · [Claude Desktop](https://docs.basicmemory.com/integrations/claude-desktop) · [VS Code](https://docs.basicmemory.com/integrations/vscode) · [Obsidian](https://docs.basicmemory.com/integrations/obsidian) :: ## Next Steps ::card-group :::card --- icon: i-lucide-folder-kanban title: Project Documentation to: https://docs.basicmemory.com/how-to/project-documentation --- Learn how to document your development projects. ::: :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- See every tool available to Codex through MCP. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Structure effective development documentation. ::: :: # Cursor Cursor's built-in memories store short preference strings. Basic Memory gives it a full knowledge base — searchable notes with semantic connections that persist across every session and grow with your project. > New to this setup? [Basic Memory for Cursor](https://basicmemory.com/for/cursor){rel=""nofollow""} has a two-minute overview of what persistent memory changes. ## Cloud Setup ::steps ### Sign Up Create your account at [app.basicmemory.com](https://app.basicmemory.com){rel=""nofollow""} ### Configure Remote MCP in Cursor Go to **Settings > Developer > Edit Config**, select **MCP Tools**, click **Add Custom MCP**, and add: ```json { "mcpServers": { "basic-memory-cloud": { "url": "https://cloud.basicmemory.com/mcp" } } } ``` ### Authenticate Follow the OAuth flow to grant Cursor access to your Basic Memory account. ### Verify Ask the AI: `"What Basic Memory tools do you have?"` :: ::tip See the [Cloud Setup Guide](https://docs.basicmemory.com/cloud/cloud-guide) for detailed instructions and troubleshooting. :: --- ## Local Setup ::steps ### Configure MCP Cursor supports MCP natively. Add Basic Memory following the [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol){rel=""nofollow""}: ```json { "mcpServers": { "basic-memory": { "command": "uvx", "args": ["basic-memory", "mcp"] } } } ``` ### Install Basic Memory (optional) ```bash # With uv uv tool install basic-memory # Or with pip pip install basic-memory ``` ### Verify Ask the AI: `"What Basic Memory tools do you have?"` You should see tools for note creation, search, and project management. :: --- ## Try It Once configured, try these prompts in Cursor: ```text "Create a note documenting our API authentication approach and link it to the user-auth module." ``` ```text "Search my notes for anything related to database migration strategy." ``` ```text "What have I been working on this week? Check recent activity." ``` For the full list of available tools, see the [MCP Tools Reference](https://docs.basicmemory.com/reference/mcp-tools-reference). --- ## Troubleshooting **MCP tools not appearing** — Verify Basic Memory is installed (`basic-memory --version`), check your JSON config syntax, and restart Cursor. Try an absolute path to `uvx` if needed. **Tools appear but don't work** — Run `basic-memory status` to check sync. Verify project directory permissions and that `which basic-memory` resolves. **Cloud connection issues** — See the [Cloud Setup Guide](https://docs.basicmemory.com/cloud/cloud-guide) for OAuth troubleshooting. --- ## Frequently Asked Questions ### Does Cursor have memory? Cursor has a built-in "Memories" feature for storing short preferences, but it is limited to simple rules. Basic Memory provides full knowledge management — searchable notes, semantic connections, and rich context that grows with your project. ### Can I use Basic Memory and Cursor's built-in memories together? Yes. Cursor's built-in memories handle quick preferences and rules. Basic Memory handles everything deeper — architecture decisions, project history, detailed technical context, and cross-session knowledge. --- ::note **Basic Memory also works with:** [Claude Code](https://docs.basicmemory.com/integrations/claude-code) · [OpenAI Codex](https://docs.basicmemory.com/integrations/codex) · [Claude Desktop](https://docs.basicmemory.com/integrations/claude-desktop) · [VS Code](https://docs.basicmemory.com/integrations/vscode) · [Obsidian](https://docs.basicmemory.com/integrations/obsidian) :: ## Next Steps ::card-group :::card --- icon: i-lucide-folder-kanban title: Project Documentation to: https://docs.basicmemory.com/how-to/project-documentation --- Learn how to document your development projects. ::: :::card --- icon: i-lucide-edit title: Note Taking to: https://docs.basicmemory.com/how-to/note-taking --- Master note-taking techniques for development. ::: :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- See every tool Basic Memory exposes to your AI. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Structure your development documentation. ::: :: # VS Code Edit your knowledge base directly in VS Code -- full syntax highlighting, markdown preview, and the Basic Memory CLI right in your terminal. > New to this setup? [Basic Memory for VS Code](https://basicmemory.com/for/vscode){rel=""nofollow""} has a two-minute overview of what persistent memory changes. ## Cloud Sync Workflow Basic Memory Cloud lets you edit locally in VS Code while keeping notes synced to the cloud. ::steps ### Sign Up for Basic Memory Cloud Create your account at [app.basicmemory.com](https://app.basicmemory.com){rel=""nofollow""} ### Enable Cloud Mode Authenticate and enable cloud mode: ```bash bm cloud login ``` ### Set Up Sync Install rclone and configure credentials: ```bash bm cloud setup ``` This installs rclone automatically and configures your cloud credentials. :::note Sync requires the Basic Memory CLI. See [Local Installation](https://docs.basicmemory.com/local/local-install) for setup. ::: ### Create Project with Local Sync Point Basic Memory to your local workspace: ```bash # For a project-specific docs folder bm project add my-project --local-path ~/workspace/my-project/docs # Or for a shared knowledge base bm project add knowledge --local-path ~/Documents/knowledge ``` ### Establish Sync Baseline Preview and run the initial sync: ```bash # Preview first (recommended) bm cloud bisync --name my-project --resync --dry-run # Establish baseline bm cloud bisync --name my-project --resync ``` Only use `--resync` for the first sync. ### Edit in VS Code Open your local directory in VS Code. Edit files with full IDE features -- syntax highlighting, markdown preview, split editors, and search all work out of the box. ### Sync Changes After editing locally or making changes in cloud, run bidirectional sync: ```bash bm cloud bisync --name my-project ``` Changes flow both directions. Edit locally or in the cloud, both stay in sync. :: ::note **Bidirectional sync** : `bisync` keeps local and cloud in sync automatically. Newer files win conflicts. For one-way sync and advanced configuration, see the [Cloud Sync Guide](https://docs.basicmemory.com/cloud/cloud-sync) . :: --- ## Local Setup If you're running Basic Memory locally (no cloud), setup is simple: ```bash # Install Basic Memory uv tool install basic-memory # Add a project pointing to a folder bm project add my-project --local-path ~/workspace/my-project/docs ``` Then open that folder in VS Code. That's it -- your markdown files are the knowledge base. Every edit you make is automatically synced to the knowledge graph. --- ## Try It ### Edit Files Directly VS Code is a first-class way to work with Basic Memory notes. Open any markdown file, edit it, save. Basic Memory watches for changes and updates the knowledge graph automatically. Use split editors to view code on one side and documentation on the other. Use VS Code's built-in search to find content across your knowledge base. ### Terminal CLI Open VS Code's integrated terminal for quick operations: ```bash # Search your knowledge base (including semantic search) bm tool search-notes "authentication flow" bm tool search-notes "how to handle errors" --hybrid # Check recent activity bm tool recent-activity --timeframe "2 days" # Write a quick note bm tool write-note --title "API Design Decision" --folder "decisions" ``` Set up aliases in your shell profile (`.bashrc`, `.zshrc`, etc.) for faster access: ```bash alias note="bm tool write-note" alias search="bm tool search-notes" alias recent="bm tool recent-activity" ``` ### Copilot Chat with MCP VS Code's Copilot Chat now supports MCP servers. You can add Basic Memory as an MCP server in your VS Code settings and use it directly through Copilot -- search your knowledge base, write notes, and build context without leaving the chat panel. See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers){rel=""nofollow""} for setup details. --- ## Troubleshooting **Sync not picking up changes?** Check sync status with `bm status` and verify file permissions in your project directory. **Search missing results?** VS Code's built-in search works for text matches. For knowledge graph queries and semantic search, use the CLI: `bm tool search-notes "your query"`. **Cloud sync conflicts?** Run `bm cloud bisync --name my-project --dry-run` to preview before syncing. See the [Cloud Sync Guide](https://docs.basicmemory.com/cloud/cloud-sync) for conflict resolution. --- ## Next Steps ::card-group :::card --- icon: i-lucide-folder-kanban title: Project Documentation to: https://docs.basicmemory.com/how-to/project-documentation --- Learn effective project documentation strategies. ::: :::card --- icon: i-lucide-edit title: Note Taking to: https://docs.basicmemory.com/how-to/note-taking --- Master note-taking techniques for development. ::: :::card --- icon: i-lucide-terminal title: CLI Reference to: https://docs.basicmemory.com/reference/cli-reference --- Full Basic Memory command line reference. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Learn the semantic markdown format. ::: :: # Obsidian Obsidian gives you a visual window into your Basic Memory knowledge base. Point it at your Basic Memory folder and you get graph view, backlinks, rich editing, and more — while your AI keeps working through MCP tools on the same files. > New to this setup? [Basic Memory for Obsidian](https://basicmemory.com/for/obsidian){rel=""nofollow""} has a two-minute overview of what persistent memory changes. ::note For more information about Obsidian, [visit the Obsidian home page](https://obsidian.md) . :: ## Cloud Sync Workflow Basic Memory Cloud enables a hybrid workflow: edit locally in Obsidian while your notes sync to the cloud. ::note Sync requires the Basic Memory CLI. See [Local Installation](https://docs.basicmemory.com/local/local-install) for installation steps. :: ::steps ### Sign Up for Basic Memory Cloud Create your account at [app.basicmemory.com](https://app.basicmemory.com){rel=""nofollow""} ### Enable Cloud Mode Authenticate and enable cloud mode: ```bash bm cloud login ``` ### Set Up Sync Install rclone and configure credentials: ```bash bm cloud setup ``` This installs rclone automatically and configures your cloud credentials. ### Create Project with Local Sync Point Basic Memory to your Obsidian vault: ```bash # If you have an existing vault bm project add my-vault --local-path ~/path/to/obsidian-vault # Or create a new project bm project add notes --local-path ~/Documents/notes ``` ### Establish Sync Baseline Preview and run the initial sync: ```bash # Preview first (recommended) bm cloud bisync --name my-vault --resync --dry-run # If all looks good, establish baseline bm cloud bisync --name my-vault --resync ``` Only use `--resync` for the first sync. ### Open Your Vault in Obsidian Open your local directory as a vault in Obsidian. You get full graph view, plugins, and editing. ### Sync Changes After editing in Obsidian or making changes via AI assistants in the cloud, sync both directions: ```bash bm cloud bisync --name my-vault ``` :: ::note **Bidirectional sync** : `bisync` keeps local and cloud in sync. Changes flow both ways, with newer files winning conflicts. For one-way sync and advanced options, see the [Cloud Sync Guide](https://docs.basicmemory.com/cloud/cloud-sync) . :: --- ## Local Setup You can either use an existing Obsidian vault or create a new one for Basic Memory. ### Option 1: Use an Existing Vault ::steps ### Configure Basic Memory project ```bash # Point Basic Memory to your existing vault basic-memory project add main ~/path/to/your/obsidian-vault # Set it as default basic-memory project default main ``` ### Restart your AI client Restart Claude Desktop (or your MCP client) for the changes to take effect. ### Test the integration Ask your AI to create a note — it will appear in your vault immediately. :: ### Option 2: Create a New Vault ::steps ### Download Obsidian Download and install [Obsidian](https://obsidian.md){rel=""nofollow""}. ### Create a new vault Create a new vault pointing to your Basic Memory directory (`~/basic-memory` by default). ### Enable core plugins Enable Graph View, Backlinks, and Tags in Obsidian's settings. :: ## What You Get Because Basic Memory uses standard markdown with wiki links, Obsidian understands your knowledge base natively. - **Graph View** — See your entire knowledge network as an interactive graph. Each note is a node, and relations become connecting lines. Local graphs let you focus on one note's neighborhood. - **Backlinks** — Every `[[wiki link]]` your AI creates is a clickable backlink in Obsidian. See all documents that reference the current note and navigate connections easily. - **Tag Explorer** — Tags from observations and frontmatter show up in Obsidian's tag pane. Filter, browse, and combine tags to find what you need. - **Live Updates** — Notes created by your AI (in Claude Desktop, Claude Code, or any MCP client) automatically appear in Obsidian since they share the same markdown files. No import or export needed. - **Canvas** — Basic Memory's `canvas` tool generates Obsidian Canvas files. Ask your AI to visualize project structure or concept maps, then open the `.canvas` file in Obsidian to view and edit it. Use [schemas](https://docs.basicmemory.com/concepts/schema-system) to keep your notes consistent whether you're writing in Obsidian or through your AI. ## Troubleshooting **Links not appearing in graph**: Make sure you're using wiki link syntax (`[[Note Title]]`) and that referenced documents exist in the vault. **Tags not showing up**: Use `#tag` syntax (no spaces — use hyphens instead). Ensure the tag panel is enabled in Obsidian settings. **Canvas files not opening**: Update to the latest Obsidian version and enable the Canvas core plugin. **Notes not syncing to cloud**: Run `bm cloud bisync --name ` after editing. See the [Cloud Sync Guide](https://docs.basicmemory.com/cloud/cloud-sync) for details. ## Next Steps ::card-group :::card --- title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Learn about observations, relations, and frontmatter. ::: :::card --- title: Schema System to: https://docs.basicmemory.com/concepts/schema-system --- Define consistent structures for your notes. ::: :::card{title="Cloud Sync" to="https://docs.basicmemory.com/cloud/cloud-sync"} Set up bidirectional sync between local and cloud. ::: :::card --- title: Claude Desktop to: https://docs.basicmemory.com/integrations/claude-desktop --- Connect your AI assistant to the same knowledge base. ::: :: # Agent Skills Agent skills are markdown instruction files (`SKILL.md`) that teach AI coding agents best practices for using Basic Memory's MCP tools. Your agent already has access to the tools — skills teach it *when* and *how* to use them effectively, with examples and patterns for specific workflows. The skills are open source — browse the full collection on [GitHub](https://github.com/basicmachines-co/basic-memory-skills){rel=""nofollow""}. ::tip Skills work with Claude Desktop, Claude Code, Cursor, Windsurf, and any agent that supports markdown-based skill files. :: --- ## Installation ### npx (Recommended) Install all skills at once: ```bash npx skills add basicmachines-co/basic-memory-skills ``` Or install a single skill: ```bash npx skills add basicmachines-co/basic-memory-skills --skill memory-tasks ``` Target a specific agent: ```bash npx skills add basicmachines-co/basic-memory-skills --agent claude ``` ### Claude Desktop 1. Open **Settings → Capabilities** 2. Enable **Code execution** and **Skills** 3. Upload the `SKILL.md` files from each skill folder ### Manual Clone the repo and copy skill folders to your agent's skills directory: ```bash git clone https://github.com/basicmachines-co/basic-memory-skills.git cp -r basic-memory-skills/memory-notes ~/.claude/skills/ ``` For project-scoped skills, copy to `.claude/skills/` in your project root instead. --- ## Available Skills | Skill | Purpose | | -------------------------- | -------------------------------------------------------------------------- | | **memory-notes** | Core note format — frontmatter, observations, relations, memory:// URLs | | **memory-tasks** | Structured task tracking that survives context compaction | | **memory-schema** | Schema lifecycle — infer, validate, create definitions, detect drift | | **memory-reflect** | Review conversations, extract insights, consolidate knowledge | | **memory-defrag** | Split bloated files, merge duplicates, restructure hierarchy | | **memory-lifecycle** | Status transitions through folder-based organization, archive-never-delete | | **memory-metadata-search** | Query notes by custom frontmatter fields (equality, range, array filters) | | **memory-ingest** | Process transcripts, emails, and documents into structured notes | | **memory-research** | Web research synthesized into knowledge entities | ::note Start with **memory-notes** — it covers foundational note-writing patterns that all other skills build on. :: ### Core Skills **memory-notes** — The foundation. Teaches proper note structure: frontmatter, semantic observation categories, relations with wiki-links, and memory:// URL usage. Install this first. **memory-tasks** — Structured task tracking with typed Task notes. Tasks survive context compaction, making this essential for multi-step work that spans beyond a single context window. **memory-schema** — Schema lifecycle management. Discovers unschemaed notes, infers schemas from existing content, creates and edits definitions, validates notes against schemas, and detects drift. ### Knowledge Maintenance **memory-reflect** — Inspired by sleep-time compute patterns. Reviews recent conversations, extracts insights, and consolidates them into your knowledge base. Works well as a scheduled daily or twice-daily routine. **memory-defrag** — Memory defragmentation. Splits bloated files, merges duplicates, removes stale information, and restructures folder hierarchy. Run weekly or when your knowledge base feels disorganized. **memory-lifecycle** — Entity lifecycle management. Manages status transitions through folder-based organization with an archive-never-delete philosophy — information is preserved through moves, not removal. ### Advanced Workflows **memory-metadata-search** — Structured metadata search. Query notes by custom frontmatter fields using equality, range, array, and nested filters. Useful for finding notes by status, priority, or any custom YAML fields. **memory-ingest** — Processes unstructured external input into structured entities. Parses meeting transcripts, conversation logs, and pasted documents into properly formatted Basic Memory notes. **memory-research** — Performs web research and synthesizes findings into Basic Memory entities. Use for researching companies, people, technologies, or any topic you want to capture in your knowledge base. --- ## Recommended Combinations **Developers** — `memory-notes` + `memory-tasks` + `memory-schema` :br Core note writing, task tracking across sessions, and schema consistency for project documentation. **Researchers** — `memory-notes` + `memory-research` + `memory-ingest` :br Capture web research and process external documents into structured knowledge. **Knowledge Maintenance** — `memory-notes` + `memory-defrag` + `memory-lifecycle` + `memory-reflect` :br Keep your knowledge base organized with regular reflection, defragmentation, and lifecycle management. **Everything** — Install all 9 skills for comprehensive memory management across ingestion, organization, reflection, and lifecycle. ```bash npx skills add basicmachines-co/basic-memory-skills ``` --- ## Next Steps ::card-group :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Understand the semantic markup skills teach agents to write. ::: :::card --- icon: i-lucide-shield-check title: Schema System to: https://docs.basicmemory.com/concepts/schema-system --- Learn about schema validation that memory-schema manages. ::: :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- The tools that skills teach agents to use effectively. ::: :::card --- icon: i-lucide-github title: GitHub Repository to: https://github.com/basicmachines-co/basic-memory-skills --- Source code, contributing guide, and issue tracker. ::: :: # Code Project Documentation Basic Memory turns your project's `docs/` folder into a shared knowledge base that both you and your AI can read and write. Architecture decisions, API docs, coding patterns -- they all live as markdown files right next to your code, connected through a knowledge graph that makes them easy to find and keep current. ## Setting Up Point Basic Memory at a docs folder in your project: ```bash # Create a docs folder if you don't have one mkdir docs # Register it as a Basic Memory project basic-memory project add my-project ~/code/my-project/docs ``` That's it. Your AI assistant can now read and write documentation in that folder. You'll end up with a structure like this: ```text my-project/ ├── src/ ├── tests/ ├── docs/ # Your Basic Memory knowledge base │ ├── architecture/ │ ├── decisions/ │ ├── guides/ │ ├── patterns/ │ └── api/ └── README.md ``` ## Key Documentation Patterns The real power is that you can just tell your AI what to document and it handles the structure. ### Architecture Decision Records When your team makes a significant technical choice, capture it: > "We just decided to use PostgreSQL instead of MongoDB for the financial app. Write an ADR explaining why -- ACID compliance, analytical queries, and team SQL experience were the main factors." Your AI creates a well-structured decision record with the context, rationale, alternatives considered, and consequences. The note gets linked to related architecture docs automatically. If you want all your ADRs to follow the same structure, ask the AI to create a schema: > "Create a schema for our architecture decision records. They should always have a status, context, decision, and consequences section." The AI writes a schema note like this: ```yaml --- title: ADR type: schema entity: adr version: 1 schema: status: string, current decision status context: string, background and problem statement decision: string, what was decided consequences?(array, outcomes of the decision): string supersedes?: ADR, previous decision this replaces settings: validation: warn --- ``` From that point on, every ADR the AI creates follows this structure. You can validate existing ones too: ```bash bm schema validate adr ``` See the [Schema System](https://docs.basicmemory.com/concepts/schema-system) guide for full details on defining and using schemas. ### API Documentation > "Document the authentication endpoints -- login, refresh, and logout. Include the request/response formats and error codes." The AI creates API docs with practical details: endpoint paths, payload examples, error responses, and links to related concepts like rate limiting or token management. You can set up a schema for API docs the same way you did for ADRs, so every endpoint doc has a consistent format. ### Architecture Overviews > "Write up our system architecture. We have a React frontend, a FastAPI backend, and PostgreSQL. Everything runs in Docker on Kubernetes." The AI produces an architecture overview with components, data flows, and relations to other docs like your database schema and deployment guide. As the system evolves, you update the doc in conversation: > "Add the new Redis caching layer to the architecture overview." Notes are protected from accidental overwrites -- the AI uses incremental edits to update existing docs rather than replacing them, so you never lose content by mistake. ## Finding and Reviewing Documentation Basic Memory's search understands meaning, not just keywords. Ask for what you need in plain language: > "Find our docs about how we handle user authentication." This finds notes about JWT validation, OAuth flows, and login endpoints -- even if none of them contain the exact phrase "user authentication." That's semantic search at work. You can also search by specific note properties when you know what you're looking for: > "Show me all accepted ADRs." > "Find API docs tagged with authentication." > "What patterns have we documented for error handling?" These use metadata search -- filtering by type, status, tags, and other frontmatter fields. You can also use the `tag:` shorthand in searches, like `tag:api` or `tag:security`. For a deeper dive, see [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search). ## Development Workflows ### During Development When you build something new, document it in the same conversation: > "Document the user preference system we just implemented." When you're picking up where you left off: > "What do our docs say about the notification service? I need to extend it." ### Before a Pull Request Check whether your changes need doc updates: > "I changed how refresh tokens work. Do we have docs that need updating?" The AI searches your knowledge base, finds the relevant API docs and architecture notes, and either updates them or tells you what needs attention. ### Sprint Reviews > "Update our architecture overview with the changes from this sprint." The AI reviews what's changed and makes targeted updates to the relevant docs. ## Best Practices 1. **Document decisions, not just implementations** -- Capture the "why" behind choices. Six months from now, the reasoning matters more than the code. 2. **Use schemas for recurring doc types** -- ADRs, API docs, runbooks. Define the structure once and every doc of that type stays consistent. 3. **Let relations do the linking** -- When the AI writes `relates_to [[Database Schema]]`, it creates a navigable connection in the knowledge graph. This is how you build docs that are easy to explore. 4. **Keep docs next to code** -- Version-controlled documentation in your repo means docs and code stay in sync through the same PR process. 5. **Search before writing** -- Ask the AI to check for existing docs before creating new ones. This prevents duplication and keeps your knowledge base clean. ## Next Steps ::card-group :::card --- icon: i-lucide-edit title: Note Taking to: https://docs.basicmemory.com/how-to/note-taking --- Techniques for capturing knowledge during development. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- How Basic Memory structures notes into a knowledge graph. ::: :::card --- icon: i-lucide-check-square title: Schema System to: https://docs.basicmemory.com/concepts/schema-system --- Define consistent structure for your documentation types. ::: :: # Organizing Notes for Writing Basic Memory is a knowledge base that you and your AI share. You write notes in markdown, and they become a connected graph that both of you can read, search, and build on. For writing projects — novels, screenplays, nonfiction — this means your characters, plot arcs, research, and drafts all live in one place where your AI can help you stay organized across hundreds of pages. This page walks through setting up a writing project, developing characters and plot, tracking research, and using schemas and search to keep everything consistent as the project grows. ## Setting Up a Writing Project Create a dedicated Basic Memory project for your writing: ```bash basic-memory project add my-novel ~/writing/my-novel ``` Then organize your folders however makes sense. A common structure: ```text my-novel/ ├── characters/ ├── worldbuilding/ ├── plot/ ├── research/ ├── chapters/ └── log/ ``` You don't need to get this right upfront. Basic Memory indexes everything by content and meaning, so you can always find notes regardless of where they live. Reorganize as the project takes shape. ## Character Development The fastest way to create character notes is to ask your AI. ```text You: "Create a character profile for Sarah Chen. She's 28, a software engineer at a tech company, estranged from her wealthy father, and driven by the death of her brother in a technology accident." ``` The AI creates a structured note with observations, tags, and relations to other notes in your project: ```markdown --- title: Sarah Chen - Protagonist type: character tags: [character, protagonist] --- # Sarah Chen - Protagonist ## Background - [age] 28 years old #demographics - [occupation] Software engineer at NeuroLink Corp #background - [location] Capitol Hill, Seattle #setting - [motivation] Expose corporate corruption after brother's death #driving-force ## Personality - [strength] Brilliant analytical mind #personality - [weakness] Struggles with trust issues #personality - [quirk] Carries a vintage pocket notebook everywhere #details ## Character Arc - [starting-point] Loyal corporate employee #arc - [catalyst] Discovers illegal experiments #arc - [growth] Learns to trust others #arc - [resolution] Becomes a whistleblower #arc ## Relations - works_for [[NeuroLink Corporation]] - opposes [[Marcus Webb - Antagonist]] - mentored_by [[Old Tom]] ``` From here, you build out the character through conversation: ```text You: "Add a section about Sarah's relationship with her brother. He was a test subject for neural implants — she didn't know until after he died." You: "What do we know about Sarah's weaknesses? I want to make sure they create real obstacles in the plot." ``` The AI reads the existing note, adds to it with `edit_note`, and connects it to related notes in your project. Because notes can't be accidentally overwritten (the AI uses `edit_note` for updates), your polished character work stays safe. ### Character Relationships Track how characters connect to each other: ```text You: "Create a note mapping the relationships between Sarah, Marcus, and Old Tom. Include the tensions and what each relationship does for the story." ``` The AI creates a note with relations linking back to each character profile, so you can navigate between them. ## Plot and Story Structure Outline your story the same way — tell the AI what you're thinking, and let it create structured notes. ```text You: "Outline a three-act structure. Act I: Sarah discovers anomalous data and a patient dies under suspicious circumstances. Act II: She investigates, meets Old Tom, and discovers her brother was a test subject. Act III: She goes underground and exposes the conspiracy." ``` The AI creates a plot arc note with observations for each beat and relations linking to characters, settings, and themes. For chapter-level planning: ```text You: "Break down Chapter 3. Sarah finds deleted patient files late at night, then cross-references them at a coffee shop and realizes patients are dying within 72 hours of surgery." You: "What plot threads are still unresolved as of Chapter 8?" ``` That second question is where Basic Memory shines — the AI can read across all your plot and chapter notes to find loose threads, because everything is connected. ## Research Organization Keep research alongside your creative notes so the AI can draw on it while helping you write. ```text You: "Create a research note about current neural interface technology. Include what's real today and what I'm extrapolating for the 2035 story setting." You: "Based on my neuroscience research, are there any plot points that don't hold up scientifically?" ``` The AI links research notes to the plot points and worldbuilding notes they support. For a deeper look at research workflows, see the [Research and Learning](https://docs.basicmemory.com/how-to/research-learning) guide. ## Writing Process ### Daily Log A simple running log helps you (and the AI) track momentum: ```text You: "Log today's writing session. I wrote 1,250 words on Chapter 3, the discovery scene. Found a good metaphor for data analysis. Tomorrow I'll tackle the coffee shop scene." ``` Over time, the AI can answer questions like "How many words did I write this week?" or "What was I working on last Tuesday?" by reading through the log. ### Idea Capture When an idea hits, get it down fast: ```text You: "Quick idea — scene where a neural implant patient starts speaking in corporate advertising slogans while dying. Horror element. Park it for later." ``` The AI drops it into an ideas note. When you're ready to plan a new chapter, ask: "What ideas have I parked that might fit into Act II?" ## Using Schemas for Consistency As your project grows, you'll want consistency across notes of the same type. Schemas define what a character note, chapter outline, or research note should contain. ```text You: "Look at my character notes and figure out what structure they have in common. Then create a schema so new characters are consistent." ``` The AI analyzes your existing notes, identifies patterns, and creates a schema: ```text AI: Looking at your 8 character notes, here's what I found: - "age" appears in all of them - "motivation" appears in 7 of 8 - "arc" section appears in 6 of 8 - Relations to other characters in all of them Want me to create a Character schema with those fields? ``` Once the schema exists, the AI uses it automatically when you ask for a new character. You can do the same for chapters, research notes, or any other note type: ```text You: "Create a schema for chapter outlines. Each one should have a purpose section, scene breakdown, key details, and a word count target." ``` Schemas are optional and flexible — they describe patterns, not rigid templates. See the [Schema System](https://docs.basicmemory.com/concepts/schema-system) docs for details. ## Finding Your Way Around a Big Project A novel-length project can have hundreds of notes. Basic Memory gives you three ways to find what you need. ### Semantic Search Search by meaning, not just keywords. This is especially powerful for writing, where you might not remember the exact words you used: ```text You: "Find all scenes where Sarah confronts authority." You: "What have I written about the theme of isolation?" You: "Search for anything related to the neural implant side effects." ``` Semantic search finds relevant notes even when the words don't match exactly. "Confronts authority" finds scenes where Sarah challenges her boss, defies corporate security, or argues with her father — because the meaning overlaps. See [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search) for how it works. ### Metadata Search Search by properties like type, tags, or status: ```text You: "Show me all notes with type character." You: "Find chapter notes tagged as draft." You: "What research notes are tagged neuroscience?" ``` This is useful for getting an overview — how many characters do I have? Which chapters are still in draft? What research have I collected on a topic? ### Knowledge Graph Navigation Follow connections between notes: ```text You: "Build context around Sarah Chen — show me everything connected to her character." ``` The AI follows relations outward from Sarah's note and pulls in related characters, plot points, settings, and themes. This is how you get a full picture of how one element fits into the whole story. ## Best Practices 1. **Let the AI create structure.** Describe what you want in plain language. The AI writes well-structured notes with observations, tags, and relations. 2. **Link everything.** Characters to plots, research to scenes, themes to chapters. The more connections, the more useful the knowledge graph becomes. 3. **Capture ideas immediately.** A quick "park this idea" message takes seconds and prevents lost inspiration. 4. **Use schemas once you have a pattern.** Don't start with schemas — write naturally first, then add schemas to bring consistency to what you've already created. 5. **Search by meaning for creative work.** Thematic questions ("What have I written about trust?") work better as semantic searches than keyword searches. 6. **Review weekly.** Ask the AI "What did I work on this week?" or "Are there any plot threads I haven't touched in a while?" to stay on top of a large project. ## Next Steps ::card-group :::card --- icon: i-lucide-graduation-cap title: Research & Learning to: https://docs.basicmemory.com/how-to/research-learning --- Organize research and build knowledge systematically. ::: :::card --- icon: i-lucide-edit title: Note Taking to: https://docs.basicmemory.com/how-to/note-taking --- Master effective note-taking techniques. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Learn Basic Memory's semantic patterns. ::: :::card --- icon: i-lucide-user title: Personal Knowledge to: https://docs.basicmemory.com/how-to/personal-knowledge --- Build your personal knowledge management system. ::: :: # Research & Learning Basic Memory turns your AI into a research partner that remembers everything. Instead of losing insights in chat history, every research conversation produces real markdown notes -- linked together, searchable, and always available for the next session. Whether you're exploring a new field, tracking a long-running project, or just trying to make sense of what you've been reading, Basic Memory gives you a shared knowledge base where both you and your AI can build on prior work. ## How Research Works in Basic Memory The key insight: when you ask your AI to research something, it doesn't just answer in chat. It creates detailed notes in your knowledge base with structured observations, tags, and relations to other notes. Those notes persist. Next time you pick up the thread -- even weeks later -- the AI reads your existing research and builds on it. This means your knowledge compounds. A note about quantum computing links to your note about cryptography. A synthesis note ties together three papers you read last month. Your AI can navigate these connections to give you better answers over time. ## Starting a Research Project Tell your AI what you're exploring and ask it to start building notes: ```text You: "I'm starting a research project on renewable energy storage. Create an overview note covering the main approaches -- battery technology, hydrogen, thermal storage, and gravity-based systems." ``` The AI creates a detailed note with observations categorized by approach, tagged for easy discovery, and ready to link to future deep-dives. To get consistent structure across all your research notes, set up a schema: ```text You: "Create a schema for my research notes. Each one should have sections for key findings, sources, open questions, and connections to other topics." ``` Now every research note the AI writes follows the same format. You can validate notes against the schema later, and your whole research library stays organized without extra effort. See [Schema System](https://docs.basicmemory.com/concepts/schema-system) for details. ## Building Connected Knowledge The real power shows up when notes start linking to each other. As you go deeper, ask the AI to connect new findings to what you already have: ```text You: "Research solid-state batteries and connect it to my renewable energy storage overview." ``` The AI creates a new note with technical detail on solid-state batteries and adds relations back to your overview. Your knowledge graph grows naturally -- each note is both a standalone document and a node in a larger web. Over time, you can ask for synthesis: ```text You: "Look at my energy storage notes and create a synthesis -- what are the main trade-offs between approaches, and where are the biggest open questions?" ``` The AI reads across your existing notes, identifies patterns, and produces a new note that ties everything together. This is where having persistent, connected knowledge pays off -- the AI isn't starting from scratch each time. ## Finding and Exploring Your Research This is where Basic Memory v0.19 really shines. Once you've built up a collection of research notes, you need to find things -- and not just by exact title. ### Semantic Search Semantic search finds conceptually related notes, even when the wording doesn't match: ```text You: "Find everything I've learned about energy density improvements" ``` This returns notes about battery chemistry, hydrogen storage capacity, and thermal systems -- anything conceptually related to energy density, regardless of whether those exact words appear. It's the difference between keyword matching and actual understanding. ### Tag and Metadata Search Filter your research library by tags or metadata: ```text You: "Show me all research notes tagged battery-technology" You: "Find notes with status: needs-review" You: "Search for tag:open-question in my energy storage project" ``` Combine these with semantic search when you need precision. For example, find all notes tagged `literature-review` that relate to a specific concept. See [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search) for the full query syntax. ### Exploring Connections Use `build_context` to follow the links between notes: ```text You: "Show me what connects to my solid-state batteries note" ``` The AI traces relations outward, showing you the web of connected research -- what links in, what links out, and how topics cluster together. ## Keeping Research Organized ### Note Types Use note types to categorize your research: - **research** -- Primary research notes on specific topics - **literature-review** -- Summaries and analysis of papers or books - **synthesis** -- Notes that pull together findings across multiple topics - **question** -- Open research questions to investigate ```text You: "Create a literature-review note on the latest solid-state battery papers I've been reading" ``` ### Schemas for Consistency Once you find a structure that works, lock it in with a schema. A research schema might require: - A "Key Findings" section with categorized observations - A "Sources" section for references - An "Open Questions" section - A "Relations" section linking to related topics The AI follows the schema automatically. When you come back to your research after a break, everything is in the same format and easy to scan. ## Learning Workflows ### Daily Capture When you read something interesting, tell your AI: ```text You: "I just read a paper on perovskite solar cells. Create a note with the key findings and connect it to my energy research." ``` Don't worry about perfect organization in the moment. The tags and relations make it findable later. ### Weekly Synthesis Once a week, ask for a rollup: ```text You: "Review my research notes from this week. What themes are emerging? What should I dig into next?" ``` The AI reads your recent notes, identifies patterns, and suggests directions -- all saved as a new synthesis note in your knowledge base. ## Best Practices 1. **Let the AI write detailed notes.** Don't settle for short summaries. The more detail in each note, the more useful it is when the AI references it later. 2. **Ask for connections explicitly.** "Connect this to my existing research on X" tells the AI to create relations, which makes your knowledge graph navigable. 3. **Use schemas for recurring note types.** If you write a lot of literature reviews or research summaries, a schema keeps them consistent without extra effort. 4. **Search semantically first, filter second.** Start broad with semantic search, then narrow down with tags or metadata when you need specifics. 5. **Synthesize regularly.** The most valuable notes are often the ones that connect other notes together. Ask for synthesis often. 6. **Tag generously.** Tags are cheap and make filtering powerful. Use them for topics, status (`needs-review`, `complete`), and anything else you might want to filter on later. ## Next Steps ::card-group :::card --- icon: i-lucide-edit title: Note Taking to: https://docs.basicmemory.com/how-to/note-taking --- Master effective note-taking techniques for any subject. ::: :::card --- icon: i-lucide-user title: Personal Knowledge to: https://docs.basicmemory.com/how-to/personal-knowledge --- Build your comprehensive personal knowledge system. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Learn Basic Memory's semantic patterns. ::: :::card --- icon: i-lucide-bot title: AI Assistant Guide to: https://docs.basicmemory.com/reference/ai-assistant-guide --- Understand how AI assistants work with Basic Memory. ::: :: # Note Taking Basic Memory is a knowledge base that you and your AI share. You write notes in markdown. Your AI reads and writes notes through MCP tools. Every note becomes part of a connected knowledge graph that both of you can search, enhance, and build on over time. This page covers practical note-taking workflows — from quick capture to structured meeting notes to finding things weeks later. ## The Two-Way Flow The core idea: you capture quickly, the AI enhances later. Or the AI drafts something, and you refine it. Notes flow in both directions. **You jot down rough meeting notes:** ```markdown # Team Meeting - Project Alpha - Sarah mentioned database issues - Need to update API docs - Budget concerns raised by finance - Next milestone is March 15th ``` **Then you ask the AI to clean them up:** > "Enhance my meeting notes for Project Alpha. Add structure, connect to what we already know about the project, and pull out action items." The AI reads your note, adds semantic observations with tags, links to existing project notes, and creates clear action items with owners. Your raw capture becomes structured knowledge — without you having to do the formatting work. It works the other way too. You can ask the AI to draft notes from a topic you describe, then you add your own perspective, correct details, or highlight what matters most to you. ## Meeting Notes Meeting notes are the most common use case. Here's the workflow. **During the meeting**, capture fast. Don't worry about structure: ```markdown # Marketing Strategy Meeting - Q1 Planning Sarah (Marketing), Mike (Product), Jenny (Sales) - Q4 conversion rates down 15% - New competitor launched similar product - Need to revise messaging strategy - Sarah wants $50k for ads - Mike concerned about feature parity - Follow-up meeting Jan 29 ``` **After the meeting**, hand it to the AI: > "Clean up today's marketing strategy meeting notes. Structure the discussion points, add action items, and connect to our Q4 performance review and competitor analysis." The AI transforms your rough notes into something like this: ```markdown --- title: Marketing Strategy Meeting - Q1 Planning type: meeting tags: [marketing, strategy, q1-planning] --- # Marketing Strategy Meeting - Q1 Planning ## Meeting Context - [date] January 15, 2025 #timeline - [attendees] Sarah (Marketing), Mike (Product), Jenny (Sales) #participants ## Discussion - [metric] Q4 conversion rates decreased 15% year-over-year #performance - [context] New competitor launch adding market pressure #competitive - [proposal] Revise messaging to emphasize unique value props #strategy - [request] $50k additional advertising budget for Q1 #budget - [concern] Feature parity gap with competitor #product ## Action Items - [ ] Sarah: Draft new messaging framework by Jan 22 - [ ] Mike: Assess feature gap and provide development timeline - [ ] Jenny: Analyze Q4 sales cycle data for conversion insights - [ ] All: Follow-up meeting January 29 ## Relations - follows_up [[Q4 Performance Review]] - addresses [[Competitor Analysis - New Market Entrant]] - informs [[Q1 Marketing Strategy]] ``` Notice the `type: meeting` in the frontmatter. Note types help you categorize and filter your knowledge base — meeting, lecture, idea, code-review, or whatever types make sense for your work. Also notice that the AI used `edit_note` to enhance your existing note rather than creating a new one. Basic Memory's write protection means the AI won't accidentally overwrite your content — it adds to it. ## Learning and Lecture Notes Same pattern, different context. Capture the key points during a lecture or while reading: ```markdown # Quantum Computing - Entanglement Prof. Martinez - Physics 451 - Quantum entanglement = spooky action at distance - Bell's theorem proves local realism is wrong - EPR paradox - Einstein didn't like this - Applications in quantum teleportation ``` Then ask the AI to expand: > "Expand my lecture notes on entanglement. Add explanations for each concept and connect to my previous quantum mechanics notes." The AI fills in the details, adds mathematical context where helpful, and links back to your earlier notes on related topics. You review and add your own questions or insights. ## Quick Capture and Idea Parking Not everything needs structure right away. Use quick notes to park ideas: > "Write a note called 'Ideas - Mobile App Features' with these thoughts: push notifications for habit tracking, gamification with points and badges, social sharing, calendar integration, offline mode." The AI creates a simple note. Later — maybe days later — you can come back: > "Look at my mobile app feature ideas and flesh them out. Add feasibility notes and connect to our product roadmap." Ideas grow into plans when you're ready for them to. ## Finding Your Notes Later This is where Basic Memory's search capabilities shine. You don't need to remember exact titles or tags. ### Semantic Search Ask by meaning, not keywords: > "What did we discuss about the authentication redesign?" > "Find notes related to budget concerns." > "What do I know about Sarah's marketing proposals?" Semantic search finds relevant notes even when your query uses different words than your notes do. If you wrote about "conversion rates declining" and search for "budget concerns," it still surfaces the right meeting notes because they're semantically related. ### Metadata Search For more precise filtering, search by note properties: > "Show me all meeting notes from this month." > "Find notes with action items assigned to Sarah." > "List all notes tagged with q1-planning." You can combine metadata filters with text search to narrow results further. ## Keeping Notes Consistent with Schemas When you take the same kind of note regularly — meeting notes, lecture notes, one-on-ones — you want consistency. Schemas define what a note type should contain. > "Create a schema for meeting notes that includes attendees, discussion points, decisions, and action items." Once a schema exists, every meeting note the AI creates follows the same structure. No more forgetting to add action items or attendees. You can create schemas for any repeating note type: > "Create a schema for lecture notes with course info, key concepts, questions, and connections to previous lectures." > "Create a schema for code review notes with files reviewed, issues found, and suggested fixes." The AI validates notes against schemas as it creates them, so your knowledge base stays organized without extra effort from you. ## Progressive Note Building Notes don't have to be finished in one sitting. Basic Memory supports an iterative workflow where a note grows over days or weeks. **Day 1** — You create a stub: > "Write a note called 'Project Planning - E-commerce Site' with a note that we need to plan the new site for Q2 launch." **Day 3** — After gathering requirements, you add to it: > "Add requirements to the e-commerce planning note: mobile-responsive design, Stripe payments, inventory management, customer portal." **Day 5** — The AI connects it to existing knowledge: > "Review the e-commerce planning note and add connections to our previous e-commerce projects, Stripe integration docs, and Q2 revenue goals." Each iteration uses `edit_note` to append or update sections. The note's history reflects contributions from both you and the AI — and Basic Memory tracks who made each update. ## Best Practices **Capture first, structure later.** Don't slow yourself down formatting notes during a meeting or lecture. Get the content down, then let the AI do the formatting work. **Use consistent language.** If you call your team meetings "standups," stick with that. Consistent terminology helps the AI connect related notes. **Review AI enhancements.** The AI is good at structure and connections, but you know the nuance. Read what it adds and correct anything that's off. **Let relations build naturally.** You don't need to manually connect every note. As your knowledge base grows, the AI finds and suggests connections through semantic search and the knowledge graph. **Create schemas for repeating formats.** If you take the same kind of note more than a few times, define a schema. It saves time and keeps your knowledge base consistent. ## Next Steps ::card-group :::card --- icon: i-lucide-user title: Personal Knowledge to: https://docs.basicmemory.com/how-to/personal-knowledge --- Organize your personal life and development. ::: :::card --- icon: i-lucide-pen-tool title: Writing Organization to: https://docs.basicmemory.com/how-to/writing-organization --- Structure creative writing and storytelling projects. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Master Basic Memory's semantic patterns. ::: :::card --- icon: i-lucide-bot title: AI Assistant Guide to: https://docs.basicmemory.com/reference/ai-assistant-guide --- Understand collaborative AI workflows. ::: :: # Personal Knowledge Management Basic Memory gives you a shared knowledge base with your AI that works across every conversation. For personal knowledge management, this means you can track goals, log reflections, note decisions, and build up a picture of your life over time. The AI reads everything you've written, connects the dots, and helps you see patterns you'd miss on your own. Think of it as a personal life graph. Every note you write — about a goal, a habit, a relationship, a decision — becomes a node. The relations between notes become edges. Over time, your AI can traverse that graph and surface insights like "your energy levels correlate with exercise consistency" or "you tend to make better decisions after journaling." ## Getting Started If you haven't set up Basic Memory yet, see the [getting started guide](https://docs.basicmemory.com/start-here/getting-started). Once it's running, you can start building your personal knowledge base by simply talking to your AI: > "Create a note about my goal to run a half marathon by December. I've been running 3 times a week and just finished my first 5K in 28 minutes." The AI writes a structured note with observations, tags, and relations — all in plain markdown on your machine. You can also create notes directly in your editor or Obsidian. Basic Memory syncs everything automatically. ## Life Domains You Can Track Basic Memory works well for any area of life where you want to build up knowledge over time. Here are some common domains: **Goals and milestones** — Career goals, fitness targets, financial milestones, learning objectives. Track progress, record achievements, and let the AI remind you how far you've come. > "Write a note tracking my 2026 goals: lead a major project at work, run a half marathon, read 24 books, and build an emergency fund to 6 months expenses." **Health and wellness** — Exercise habits, sleep patterns, stress management, energy levels. Over time, the AI can identify what actually works for you versus what doesn't. > "Log that I've been meditating 10 minutes daily for 30 days. I've noticed it helps with anxiety before presentations." **Relationships** — Important conversations, shared experiences, things you want to remember about the people in your life. Thoughtful notes help you show up better. > "Note that Mom's retirement party is in June and she mentioned wanting to visit the national parks this year." **Finances** — Investment decisions and rationale, spending patterns, financial goals and progress. Having a written record of *why* you made financial decisions is invaluable during market downturns. > "Record my investment decision: moving to 70/30 stock/bond index fund split because of my long time horizon and low-cost evidence-based approach." **Personal growth** — Reflections, values clarification, lessons learned from experiences. This is where the knowledge graph really shines — connecting insights across years of reflection. > "Write a reflection on what I learned from the team conflict this week. I noticed I tend to avoid direct conversations and that makes things worse." Each note becomes part of your personal knowledge graph, connected to every other note through relations and semantic meaning. ## The Power of Connections The real value of personal knowledge management isn't any single note — it's the connections between them. When you tell your AI about a stressful week at work and it can see your notes about exercise habits, sleep patterns, and previous stress episodes, it can offer genuinely personalized insights. ```text You: "I've been feeling low energy this week. Any patterns in my notes?" AI: [Searches across your knowledge graph] Looking at your recent notes alongside historical patterns: - You skipped your morning routine 4 of 5 days this week - Last time this happened (October), it coincided with a project deadline - Your notes consistently show that exercise before 10am correlates with better energy for the rest of the day - You also noted last month that evening workouts disrupt your sleep ``` This kind of cross-domain insight is only possible because the AI has access to your full knowledge graph. It's not guessing — it's reading what you've actually written about yourself over time. ## Finding Patterns in Your Life ### Semantic Search Basic Memory v0.19 introduces semantic vector search, which means you can search by *meaning* rather than exact words. This is especially powerful for personal knowledge: > "What patterns do I notice about what energizes me?" This searches across all your notes — goals, reflections, habit logs, weekly reviews — and finds relevant content even if you used different words each time. You might have written about "feeling alive" in one note, "high energy" in another, and "in the zone" in a third. Semantic search connects them all. > "Find anything I've written about managing stress" > "What have I learned about making big decisions?" ### Metadata Search You can also filter notes by their properties — tags, types, dates: > "Show me all my goals marked in-progress" > "Find reflections from the last 3 months" > "List all notes tagged with health" Combining semantic and metadata search gives you powerful ways to review and analyze your personal knowledge. "Show me health-related reflections where I mentioned energy" narrows down to exactly what you need. ## Keeping Things Organized with Schemas Schemas are a v0.19 feature that let you define consistent structure for different kinds of notes. For personal knowledge management, this means your goals always have the same fields, your reflections follow the same format, and your weekly reviews are easy to compare. > "Create a schema for goal tracking with fields for status, target date, progress notes, and related life domain." Now when you create a goal note, the AI validates that it includes the right structure. This makes it much easier to search, filter, and review your goals later. > "Create a schema for reflections with fields for what happened, what I learned, what I'd do differently, and emotional state." You can create schemas for any note type: goals, reflections, habits, decisions, relationships, weekly reviews. The consistency pays off when you want to do things like "show me all goals with status in-progress" or "compare my last four weekly reviews." See the [schema system guide](https://docs.basicmemory.com/concepts/schema-system) for details on creating and using schemas. ## Weekly and Monthly Reviews Regular reflection turns scattered notes into genuine self-knowledge. A weekly review is one of the highest-value habits you can build with Basic Memory. > "Let's do my weekly review. Look at what I wrote this week and help me reflect." The AI pulls together your recent notes and helps you spot patterns: ```text You: "Write my weekly review for this week." AI: Based on your notes this week, here's a summary: ## Weekly Review - March 3, 2026 ## What Went Well - [achievement] Finished conference presentation outline - [habit] Maintained meditation 6/7 days - [relationship] Meaningful conversation with Alex about future plans ## Challenges - [pattern] Procrastinated on admin tasks until deadline pressure - [pattern] Stayed up late on screens three nights — sleep quality dropped ## Insights - [discovery] Exercise before difficult conversations improved communication - [pattern] Creative energy highest on early-wake days ## Next Week Intentions - Schedule admin time proactively instead of waiting for deadlines - Phone on do-not-disturb after 9pm - Continue Spanish practice, add speaking component ## Relations - continues [[February Weekly Reviews]] - informs [[Q1 2026 Goals]] ``` Over months, these reviews create a rich record of your patterns, growth, and recurring challenges. Monthly and quarterly reviews can pull from weekly reviews to identify bigger trends. > "Look at my weekly reviews from the past month. What themes keep coming up?" ## Privacy and Boundaries Personal knowledge is, well, personal. Basic Memory is designed with this in mind. **Local-first by default** — Your notes live as markdown files on your machine. Nothing leaves your computer unless you choose to sync it. **Per-project routing** — With v0.19's per-project routing, you can keep personal notes in a local-only project while routing work projects to the cloud. Your journal entries and health notes stay on your laptop; your team documentation syncs to Basic Memory Cloud. Different projects, different rules. ```bash # Personal notes stay local basic-memory project add personal ~/notes/personal # Work notes can sync to cloud basic-memory project add work ~/notes/work --cloud ``` **Choose your level of detail** — You control what goes into your knowledge base. Focus on patterns and insights rather than raw personal details if that feels more comfortable. "I noticed conflict avoidance makes things worse" is more useful than a play-by-play of an argument. ## Best Practices 1. **Start with one domain** — Don't try to document everything at once. Pick one area (goals, reflections, or health) and build the habit before expanding. 2. **Use note types** — Tag notes as `goal`, `reflection`, `habit`, `decision`, or `relationship` to make them easy to find and filter later. 3. **Write regularly, review periodically** — Quick daily notes plus weekly reviews is a sustainable rhythm that compounds over time. 4. **Let the AI connect things** — Don't worry about manually linking every note. Semantic search and the knowledge graph will surface connections naturally. 5. **Iterate on your schemas** — Start simple and add structure as you learn what's useful. You can always refine your schemas as your needs evolve. ## Next Steps ::card-group :::card --- icon: i-lucide-folder-kanban title: Project Documentation to: https://docs.basicmemory.com/how-to/project-documentation --- Organize your professional and technical projects. ::: :::card --- icon: i-lucide-edit title: Note Taking to: https://docs.basicmemory.com/how-to/note-taking --- Master collaborative note-taking with AI. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Learn Basic Memory's semantic patterns. ::: :::card --- icon: i-lucide-bot title: AI Assistant Guide to: https://docs.basicmemory.com/reference/ai-assistant-guide --- Understand how AI works with personal knowledge. ::: :: # CLI Reference Use `bm` (short) or `basic-memory` (full). Examples below use `bm`. --- ## Core commands ### `bm status` Show sync status between files and database. ```bash bm status bm status --verbose bm status --json bm status --project research bm status --wait --timeout 60 ``` | Flag | Description | | ----------------- | ----------------------------------------------- | | `--project` | Target a specific project | | `--verbose`, `-v` | Show detailed file information | | `--json` | Machine-readable JSON output | | `--wait` | Poll until sync completes (no pending changes) | | `--timeout` | Deadline in seconds for `--wait` (default `30`) | | `--local` | Force local routing (ignore cloud mode) | | `--cloud` | Force cloud routing | ### `bm doctor` Run local consistency checks to verify file/database sync. Defaults to local routing since it scans the local filesystem. ```bash bm doctor ``` | Flag | Description | | --------- | --------------------------------------- | | `--local` | Force local routing (ignore cloud mode) | | `--cloud` | Force cloud routing | ### `bm mcp` Run the MCP server with configurable transport options. The server handles initialization, file sync, and cleanup automatically. ```bash # Default: stdio transport (for Claude Desktop, Claude Code, etc.) bm mcp # Lock to a single project bm mcp --project main # HTTP transport for web deployments bm mcp --transport streamable-http --port 8000 # SSE transport for compatibility with existing clients bm mcp --transport sse ``` | Flag | Description | | ------------- | ----------------------------------------------------------- | | `--transport` | Transport type: `stdio` (default), `streamable-http`, `sse` | | `--host` | Host for HTTP transports (default `0.0.0.0`) | | `--port` | Port for HTTP transports (default `8000`) | | `--path` | Path prefix for streamable-http transport (default `/mcp`) | | `--project` | Restrict MCP server to a single project | ::note This command works regardless of cloud mode setting. Users with cloud mode enabled can still run a local MCP server for Claude Code and Claude Desktop. :: ### `bm reindex` Rebuild search indexes and/or vector embeddings without dropping the database. ```bash # Rebuild everything (search + embeddings) bm reindex # Rebuild only full-text search index bm reindex --search bm reindex -s # Rebuild only vector embeddings bm reindex --embeddings bm reindex -e # Reindex a specific project bm reindex -p main ``` | Flag | Description | | -------------------- | ------------------------------------------------- | | `--search`, `-s` | Rebuild only the full-text search index | | `--embeddings`, `-e` | Rebuild only vector embeddings | | `--project`, `-p` | Target a specific project (default: all projects) | When neither `--search` nor `--embeddings` is specified, both are rebuilt. ### `bm reset` Reset database — drops all tables and recreates them. Files are never deleted. ```bash bm reset bm reset --reindex ``` | Flag | Description | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--reindex` | Rebuild the database index from filesystem after reset | | `--force` | Skip the pre-flight check that refuses to reset while a `basic-memory mcp` process is running. Use only in automation where you've ensured no MCP clients are attached. | ::warning This rebuilds the entire database from your files. Safe (files are untouched) but may take time for large knowledge bases. `bm reset` refuses to run while an MCP server is attached to the database — stop it first, or pass `--force` in automated workflows. :: ### `bm orphans` List entities that have no relations — no incoming or outgoing connections in the knowledge graph. Useful for finding notes that aren't yet linked to anything, or notes that had their relations removed. ```bash bm orphans bm orphans --json bm orphans --project research ``` | Flag | Description | | ----------- | --------------------------------------- | | `--project` | Target a specific project | | `--json` | Machine-readable JSON output | | `--local` | Force local routing (ignore cloud mode) | | `--cloud` | Force cloud routing | ### `bm update` Check for a newer Basic Memory release and install it when supported. Basic Memory also checks for updates automatically in the background for CLI installs (Homebrew, `uv tool`, `uvx`); MCP server processes check silently and never block. ```bash # Check for updates and install if available bm update # Check only — report without installing bm update --check ``` | Flag | Description | | --------- | -------------------------------------- | | `--check` | Check for updates only; do not install | ::note Auto-update behavior is configurable — see [Configuration](https://docs.basicmemory.com/reference/configuration) for the `auto_update` and `update_check_interval` settings. :: ### `bm format` Format files using configured formatters. Uses the `formatter_command` or `formatters` settings from your config. By default, formats all `.md`, `.json`, and `.canvas` files in the current project. ```bash bm format # Format all files in current project bm format --project research # Format files in specific project bm format notes/meeting.md # Format a specific file bm format notes/ # Format all files in a directory ``` | Flag | Description | | ----------------- | ------------------------- | | `--project`, `-p` | Target a specific project | --- ## Project management ### `bm project list` List projects from local config and (when available) cloud. ```bash bm project list bm project list --json bm project list --workspace my-workspace ``` | Flag | Description | | ------------- | ---------------------------------------------- | | `--json` | Machine-readable JSON output | | `--workspace` | Cloud workspace name, slug, type, or tenant ID | | `--local` | Force local routing | | `--cloud` | Force cloud routing | ### `bm project info` Display detailed information and statistics about a project. Shows an htop-inspired compact dashboard with horizontal bar charts for note types, embedding coverage bars, and colored status dots. ```bash bm project info main bm project info main --json ``` | Flag | Description | | --------- | --------------------------------------- | | `--json` | Machine-readable JSON output | | `--local` | Force local routing (ignore cloud mode) | | `--cloud` | Force cloud routing | ### `bm project add` Add a new project. ```bash # Local project bm project add research ~/Documents/research # Cloud project (no local sync) bm project add research --cloud # Cloud project with local sync path bm project add research --cloud --local-path ~/docs # Cloud project in a specific team workspace, visible to all members bm project add team-wiki --cloud --workspace acme --visibility workspace # Cloud project restricted to specific people you grant access to bm project add hiring --cloud --workspace acme --visibility shared # Add and set as default bm project add research ~/Documents/research --default ``` | Flag | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `--local-path` | Local sync path for cloud mode | | `--workspace` | Cloud workspace name, slug, type, or tenant ID (cloud mode only) | | `--visibility` | Cloud project visibility: `workspace` (default — visible to all members), `shared` (restricted to granted users), or `private` (creator only) | | `--default` | Set as default project | | `--local` | Force local routing | | `--cloud` | Force cloud routing | ### `bm project remove` Remove a project from configuration. ```bash bm project remove research bm project remove research --delete-notes ``` | Flag | Description | | ---------------- | ----------------------------------- | | `--delete-notes` | Also delete project files from disk | | `--local` | Force local routing | | `--cloud` | Force cloud routing | ### `bm project default` Set the default project used as fallback when no project is specified. ```bash bm project default main ``` ### `bm project move` Move a local project to a new filesystem location. Updates the configured path in the database. ```bash bm project move research /new/path/to/research ``` ### `bm project ls` List files in a project directory. ```bash bm project ls --name research bm project ls --name research subfolder bm project ls --name research --local bm project ls --name research --cloud ``` | Flag | Description | | --------- | ------------------------------ | | `--name` | Project name (required) | | `--local` | List files from local instance | | `--cloud` | List files from cloud instance | ### Routing modes (per project) Route specific projects through cloud while keeping others local: ```bash bm project set-cloud research bm project set-local research ``` --- ## Cloud commands ### Authentication and status ```bash bm cloud login bm cloud status bm cloud logout ``` ### API keys ```bash bm cloud api-key save bmc_... bm cloud api-key create "my-laptop" ``` ::note `bm cloud api-key create` requires an active OAuth session. Run `bm cloud login` first. :: ### Setup and upload ```bash bm cloud setup bm cloud upload ~/my-notes --project research --create-project ``` ### Sync ```bash # Fetch cloud changes additively (Personal + Team workspaces) bm cloud pull --name research # Upload local changes additively (Personal + Team workspaces) bm cloud push --name research # Choose conflict resolution: fail (default) | keep-local | keep-cloud | keep-both bm cloud pull --name research --on-conflict keep-cloud # One-way mirror: local → cloud (Personal workspaces only) bm cloud sync # Two-way mirror: local ↔ cloud (Personal workspaces only) bm cloud bisync # Verify file integrity between local and cloud (Personal only) bm cloud check # Clear bisync state bm cloud bisync-reset # Configure local sync for an existing cloud project bm cloud sync-setup research ~/Documents/research ``` `push`/`pull` are additive (never delete on the destination) and abort on conflicts by default, git-style. `sync`/`bisync` are destructive mirrors and are blocked on Team workspaces. See the [Cloud Sync guide](https://docs.basicmemory.com/cloud/cloud-sync) for details. ### Snapshots ```bash bm cloud snapshot create "Before migration" bm cloud snapshot list bm cloud snapshot show bm cloud snapshot browse bm cloud snapshot delete ``` ### Restore ```bash bm cloud restore --snapshot ``` ### Workspaces ```bash # List cloud workspaces available to the current session bm cloud workspace list # Set the default workspace for CLI and MCP routing bm cloud workspace set-default acme ``` See [Teams](https://docs.basicmemory.com/teams/about) for working with shared organization workspaces. ### Promo controls ```bash bm cloud promo --off bm cloud promo --on ``` --- ## Schema commands Tools for defining, validating, and evolving note structure. See [Schema System](https://docs.basicmemory.com/concepts/schema-system) for concepts and workflow. ### `bm schema validate` Validate notes against their schema definition. Pass a note type to validate all notes of that type, a specific file path to validate one note, or omit to validate all notes that have schemas. ```bash # Validate all notes with schemas bm schema validate # Validate all notes of a type bm schema validate person # Validate one specific note bm schema validate people/ada-lovelace.md # Strict mode — treat warnings as errors bm schema validate person --strict # Machine-readable output bm schema validate person --json # Target a specific project bm schema validate person --project research ``` | Flag | Description | | ----------- | -------------------------------------------------------------- | | `--strict` | Treat validation warnings as errors (exit code 1 on any issue) | | `--json` | Machine-readable JSON output | | `--project` | Target a specific project | | `--local` | Force local routing | | `--cloud` | Force cloud routing | ### `bm schema infer` Analyze existing notes of a type and suggest a schema based on common observation categories, relation types, and frontmatter fields. Fields present in 95%+ of notes become required; fields above the threshold become optional. ```bash # Infer schema for a note type bm schema infer person # Lower the threshold to include less common fields bm schema infer person --threshold 0.1 # Save the inferred schema directly as a schema note bm schema infer person --save # Machine-readable output bm schema infer person --json # Target a specific project bm schema infer person --project research ``` | Flag | Description | | ------------- | -------------------------------------------------------------------------------- | | `--threshold` | Minimum field frequency for inclusion (default `0.25` — fields in 25%+ of notes) | | `--save` | Save the inferred schema as a schema note in the `schemas/` directory | | `--json` | Machine-readable JSON output | | `--project` | Target a specific project | | `--local` | Force local routing | | `--cloud` | Force cloud routing | ### `bm schema diff` Compare a schema definition against actual note usage to detect drift. Shows new fields appearing, old fields disappearing, and cardinality changes. ```bash # Check drift for a note type bm schema diff person # Machine-readable output bm schema diff person --json # Target a specific project bm schema diff person --project research ``` | Flag | Description | | ----------- | ---------------------------- | | `--json` | Machine-readable JSON output | | `--project` | Target a specific project | | `--local` | Force local routing | | `--cloud` | Force cloud routing | --- ## Tool commands (CLI wrapper for MCP tools) Command group: `bm tool` (singular). This provides CLI access to the same MCP tools that AI assistants use, useful for scripting, debugging, and quick operations from the terminal. ### `bm tool write-note` ```bash # Create a note with inline content bm tool write-note --title "API Notes" --folder specs --content "# API Notes" # Pipe content from stdin echo "# My Note" | bm tool write-note --title "My Note" --folder notes # Set the note type at creation time bm tool write-note --title "Standup" --folder meetings --type meeting ``` | Flag | Description | | ----------- | ---------------------------------------------- | | `--title` | Note title (required) | | `--folder` | Destination folder (required) | | `--content` | Note content (reads from stdin if omitted) | | `--tags` | Tags to apply | | `--type` | Frontmatter note type (e.g. `meeting`, `task`) | | `--project` | Target project | | `--local` | Force local routing | | `--cloud` | Force cloud routing | ### `bm tool read-note` ```bash bm tool read-note "specs/api-notes" bm tool read-note my-note --include-frontmatter bm tool read-note my-note --page 2 --page-size 5 ``` | Flag | Description | | ----------------------- | ---------------------------------------- | | `--include-frontmatter` | Include YAML frontmatter in output | | `--page` | Page number for pagination (default `1`) | | `--page-size` | Results per page (default `10`) | | `--project` | Target project | | `--local` | Force local routing | | `--cloud` | Force cloud routing | ### `bm tool edit-note` ```bash bm tool edit-note my-note --operation append --content "new content" bm tool edit-note my-note --operation find_replace --find-text "old" --content "new" bm tool edit-note my-note --operation replace_section --section "## Notes" --content "updated" ``` | Flag | Description | | ------------------------- | --------------------------------------------------------------------------------- | | `--operation` | Edit operation: `append`, `prepend`, `find_replace`, `replace_section` (required) | | `--content` | Content for the edit (required) | | `--find-text` | Text to find (required for `find_replace`) | | `--section` | Section heading (required for `replace_section`) | | `--expected-replacements` | Expected replacement count for `find_replace` (default `1`) | | `--project` | Target project | | `--local` | Force local routing | | `--cloud` | Force cloud routing | ### `bm tool delete-note` ```bash bm tool delete-note notes/old-draft bm tool delete-note docs/archive --is-directory ``` | Flag | Description | | ---------------- | ------------------------------------------------------------- | | `--is-directory` | Delete a directory instead of a single note | | `--project` | Target project | | `--project-id` | Project external ID (UUID); takes precedence over `--project` | | `--local` | Force local routing | | `--cloud` | Force cloud routing | ### `bm tool search-notes` ```bash # Text search (query is a positional argument) bm tool search-notes "authentication" # Tag and metadata filters (query is optional) bm tool search-notes --tag python --tag async bm tool search-notes --meta status=draft bm tool search-notes --type person --type meeting # Search modes bm tool search-notes "how to speed up the app" --hybrid bm tool search-notes "how to speed up the app" --vector bm tool search-notes --permalink "specs/*" bm tool search-notes --title "API Design" # Advanced metadata filter (JSON) bm tool search-notes --filter '{"priority": {"$in": ["high", "critical"]}}' # Pagination bm tool search-notes "api" --page 2 --page-size 20 ``` | Flag | Description | | --------------- | ----------------------------------------------------------------------- | | `--hybrid` | Use hybrid search (keyword + semantic) | | `--vector` | Use vector (semantic-only) search | | `--permalink` | Search permalink values | | `--title` | Search title values | | `--tag` | Filter by frontmatter tag (repeatable) | | `--status` | Filter by frontmatter status | | `--type` | Filter by frontmatter type (repeatable) | | `--entity-type` | Filter by result type: `entity`, `observation`, `relation` (repeatable) | | `--meta` | Filter by frontmatter `key=value` (repeatable) | | `--filter` | JSON metadata filter (advanced) | | `--after_date` | Date filter (e.g., `2d`, `1 week`) | | `--page` | Page number (default `1`) | | `--page-size` | Results per page (default `10`) | | `--project` | Target project | | `--local` | Force local routing | | `--cloud` | Force cloud routing | ### `bm tool build-context` ```bash bm tool build-context memory://specs/search bm tool build-context specs/search --depth 2 --timeframe 30d ``` | Flag | Description | | --------------- | ------------------------------------ | | `--depth` | Traversal depth (default `1`) | | `--timeframe` | Time window filter (default `7d`) | | `--page` | Page number (default `1`) | | `--page-size` | Results per page (default `10`) | | `--max-related` | Maximum related items (default `10`) | | `--project` | Target project | | `--local` | Force local routing | | `--cloud` | Force cloud routing | ### `bm tool recent-activity` ```bash bm tool recent-activity bm tool recent-activity --timeframe 30d --page-size 20 bm tool recent-activity --type entity --type observation ``` | Flag | Description | | ------------- | -------------------------------- | | `--type` | Filter by item type (repeatable) | | `--depth` | Context depth (default `1`) | | `--timeframe` | Time window (default `7d`) | | `--page` | Page number (default `1`) | | `--page-size` | Results per page (default `50`) | | `--project` | Target project | | `--local` | Force local routing | | `--cloud` | Force cloud routing | ### Schema tool commands These are CLI wrappers around the schema MCP tools with JSON output: ```bash bm tool schema-validate --entity-type person bm tool schema-infer person bm tool schema-diff person bm tool list-projects bm tool list-workspaces ``` --- ## Import commands ```bash bm import claude conversations bm import chatgpt bm import memory-json /path/to/export.json ``` --- ## Notes on defaults - If `--project` is omitted, Basic Memory falls back to `default_project` when configured. - All `bm tool` subcommands support `--workspace` for cloud workspace targeting. - `--local` and `--cloud` flags are available on most commands for routing overrides. --- ## Related pages - [Configuration](https://docs.basicmemory.com/reference/configuration) - [MCP Tools Reference](https://docs.basicmemory.com/reference/mcp-tools-reference) - [Cloud Guide](https://docs.basicmemory.com/cloud/cloud-guide) - [Schema System](https://docs.basicmemory.com/concepts/schema-system) - [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search) # MCP Tools Reference ::note This is a technical reference for developers and AI integrations. For a conceptual overview of what Basic Memory can do, see [What is Basic Memory](https://docs.basicmemory.com/start-here/what-is-basic-memory) . :: This page lists core Basic Memory MCP tools and their current parameters. ::tip Project resolution order is: constrained project env -> explicit `project` parameter -> `default_project` fallback. :: ### Common parameters Most tools accept these optional parameters. They are **not** repeated in every table below. | Parameter | Type | Default | Notes | | --------------- | -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------- | | `project` | string | resolved via fallback | Constrained project env → explicit parameter → `default_project` config | | `workspace` | string | — | Cloud workspace name or tenant ID | | `output_format` | `"text"` or `"json"` | `"text"` | Machine-readable JSON output. `build_context` defaults to `"json"`; all other tools default to `"text"` | --- ## Knowledge tools ### `write_note` Create or update a markdown note. | Parameter | Type | Required | Notes | | ----------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `title` | string | Yes | Note title | | `content` | string | Yes | Markdown body | | `directory` | string | Yes | Relative folder path | | `tags` | list [string] or string | No | Comma-separated string accepted | | `note_type` | string | No | Default `note`. Sets the `type` frontmatter field (e.g., `person`, `meeting`, `decision`) | | `metadata` | object | No | Extra frontmatter fields merged into the note's YAML header | | `overwrite` | boolean | No | Default `false`. Must be `true` to replace an existing note. Without this, writing to an existing path returns an error. Set `write_note_overwrite_default: true` in config to change the default | The `note_type` parameter controls the `type` field in frontmatter, which is used for schema resolution and filtering. The `metadata` parameter accepts any key-value pairs that get written directly into the note's frontmatter — useful for custom fields like `status`, `priority`, or `due_date`. ### `read_note` Read note content by title/permalink/memory URL. | Parameter | Type | Required | Notes | | --------------------- | ------- | -------- | ----------------------------------------------------------------- | | `identifier` | string | Yes | Title, permalink, or `memory://...` | | `page` | integer | No | Pagination page number | | `page_size` | integer | No | Results per page | | `include_frontmatter` | boolean | No | Default `false`. When `true`, includes YAML frontmatter in output | ### `edit_note` Edit an existing note incrementally. | Parameter | Type | Required | Notes | | ----------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------- | | `identifier` | string | Yes | Exact note identifier | | `operation` | string | Yes | `append`, `prepend`, `find_replace`, `replace_section`, `insert_before_section`, `insert_after_section` | | `content` | string | Yes | New content | | `section` | string | Conditional | Required for `replace_section`, `insert_before_section`, `insert_after_section` | | `find_text` | string | Conditional | Required for `find_replace` | | `expected_replacements` | integer | No | Default `1` | ### `move_note` Move a note or directory. | Parameter | Type | Required | Notes | | -------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------ | | `identifier` | string | Yes | Note or directory identifier | | `destination_path` | string | Conditional | Target path. Mutually exclusive with `destination_folder` | | `destination_folder` | string | Conditional | Target folder — moves note into folder preserving filename. Mutually exclusive with `destination_path` | | `is_directory` | boolean | No | Default `false`. Set to `true` to move an entire directory | ### `delete_note` Delete a note or directory. | Parameter | Type | Required | Notes | | -------------- | ------- | -------- | ------------------------------------------------------------ | | `identifier` | string | Yes | Note or directory | | `is_directory` | boolean | No | Set to `true` to delete an entire directory and its contents | ### `read_content` Read raw file content by path or permalink. Returns the file's raw bytes — useful for non-markdown files like images, PDFs, or binary attachments. | Parameter | Type | Required | Notes | | --------- | ------ | -------- | ------------------------------------------- | | `path` | string | Yes | File path, permalink, or `memory://...` URL | ### `view_note` Render a note as a formatted artifact for display in MCP clients. Returns the note content in a presentation-friendly format. | Parameter | Type | Required | Notes | | ------------ | ------- | -------- | -------------------------------------------- | | `identifier` | string | Yes | Note title, permalink, or `memory://...` URL | | `page` | integer | No | Pagination page number | | `page_size` | integer | No | Results per page | --- ## Search and context tools ### `search_notes` Main search tool with text, vector, and hybrid modes plus structured filters. | Parameter | Type | Required | Notes | | --------------------- | ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | No | Search query. Optional for metadata-only searches. Supports `tag:` shorthand (e.g., `"tag:security"`) | | `page` | integer | No | Default `1` | | `page_size` | integer | No | Default `10` | | `search_type` | string | No | Default `None` — resolves to `hybrid` when semantic search is enabled, `text` otherwise. Options: `text`, `title`, `permalink`, `vector`, `semantic`, `hybrid` | | `note_types` | list [string] | No | Frontmatter type filter (e.g., `["person", "meeting"]`) | | `entity_types` | list [string] | No | Result type filter: `entity`, `observation`, `relation` | | `after_date` | string | No | Date/time filter (ISO format) | | `metadata_filters` | object | No | Structured metadata filters | | `tags` | list [string] | No | Tag filter shorthand | | `status` | string | No | Status shorthand | | `min_similarity` | float | No | Overrides global `semantic_min_similarity` threshold per query | | `search_all_projects` | boolean | No | Default `false`. Search stays scoped to the resolved project; set `true` to search across every accessible project and workspace | The `search_type` parameter controls the search strategy. `hybrid` is the default — it combines keyword and semantic search. `text` is keyword-only. `vector` and `semantic` are equivalent — pure meaning-based similarity. See [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search) for details on each mode. ::note **Parameter aliases.** `search_notes` accepts `q` , `search` , or `text` as aliases for `query` , so assistants can use the parameter name they reach for naturally. Search responses also include a result total for pagination. :: ### `build_context` Build context graph from a memory URL. Traverses the knowledge graph from a starting entity, following relations to a configurable depth. | Parameter | Type | Required | Notes | | --------------- | ----------------- | -------- | ----------------------------------------------------------------------------------------- | | `url` | string | Yes | `memory://` URL or path | | `depth` | string or integer | No | Traversal depth (default `1`). Use `2` or `3` for broader context | | `timeframe` | string | No | Time window filter (default `7d`). Accepts formats like `7d`, `1 week`, `30d`, `3 months` | | `page` | integer | No | Default `1` | | `page_size` | integer | No | Default `10` | | `max_related` | integer | No | Maximum related entities per level (default `10`) | | `output_format` | string | No | Default `"json"`. Also accepts `"text"` for human-readable output | **TimeFrame examples:** | Value | Meaning | | ---------- | ------------- | | `7d` | Last 7 days | | `30d` | Last 30 days | | `1 week` | Last week | | `3 months` | Last 3 months | | `1 year` | Last year | ### `recent_activity` Recent activity in one project or cross-project discovery mode. When called without a `project` parameter, returns activity across all projects. | Parameter | Type | Required | Notes | | ----------- | ----------------------- | -------- | ---------------------------------------------------------------- | | `type` | string or list [string] | No | Filter by result type: `"entity"`, `"relation"`, `"observation"` | | `depth` | integer | No | Relation traversal depth for context | | `timeframe` | string | No | Time window (e.g., `7d`, `30d`, `1 week`) | | `page` | integer | No | Default `1` | | `page_size` | integer | No | Default `10` | --- ## Project and filesystem tools ### `list_memory_projects` List projects and project stats. Returns name, path, default status, note count, and last sync time for each project. In cloud mode, this discovers projects across **every** accessible workspace, not just the current one — so a team's projects show up without switching workspaces first. | Parameter | Type | Required | Notes | | ----------- | ------ | -------- | --------------------------------------------------------------- | | `workspace` | string | No | Limit results to a specific cloud workspace (name or tenant ID) | ### `create_memory_project` Create a project. | Parameter | Type | Required | Notes | | -------------- | ------- | -------- | ------------------------------------------------------------------ | | `project_name` | string | Yes | Name for the new project | | `project_path` | string | Yes | Filesystem path for the project | | `set_default` | boolean | No | Default `false`. Set to `true` to make this the default project | | `workspace` | string | No | Cloud workspace name or slug to create the project in (cloud only) | ### `delete_project` Remove a project from Basic Memory config. | Parameter | Type | Required | Notes | | -------------- | ------ | -------- | ----------------------------- | | `project_name` | string | Yes | Name of the project to remove | ### `list_directory` List directory contents with optional depth and glob filter. | Parameter | Type | Required | Notes | | ---------------- | ------- | -------- | -------------------------------------------------------- | | `dir_name` | string | No | Directory path to list (root if omitted) | | `depth` | integer | No | How many levels deep to list | | `file_name_glob` | string | No | Glob pattern to filter files (e.g., `*.md`, `schemas/*`) | ### `canvas` Create Obsidian canvas files for visual knowledge graph exploration. | Parameter | Type | Required | Notes | | ----------- | ------ | -------- | ----------------------------------------- | | `nodes` | list | Yes | List of node definitions for the canvas | | `edges` | list | Yes | List of edge definitions connecting nodes | | `title` | string | Yes | Canvas file title | | `directory` | string | Yes | Relative folder path for the canvas file | ### `list_workspaces` List available cloud workspaces. Returns workspace names and tenant IDs for the authenticated user. --- ## Schema tools Tools for defining, validating, and evolving note structure. See [Schema System](https://docs.basicmemory.com/concepts/schema-system) for concepts and workflow. ### `schema_validate` Validate notes against their schema. Pass `note_type` to validate all notes of a type, or `identifier` to validate a specific note. | Parameter | Type | Required | Notes | | ------------ | ------ | ----------- | ----------------------------------------------------------------------------------- | | `note_type` | string | Conditional | Note type to validate (e.g., `person`). One of `note_type` or `identifier` required | | `identifier` | string | Conditional | Specific note path or permalink to validate | ### `schema_infer` Analyze existing notes of a type and suggest a schema based on common patterns. | Parameter | Type | Required | Notes | | ----------- | ------ | -------- | ------------------------------------------------------ | | `note_type` | string | Yes | Note type to analyze (e.g., `person`) | | `threshold` | float | No | Minimum field frequency for inclusion (default `0.25`) | ### `schema_diff` Compare a schema definition against actual note usage to detect drift. | Parameter | Type | Required | Notes | | ----------- | ------ | -------- | ------------------------------------- | | `note_type` | string | Yes | Note type to compare (e.g., `person`) | --- ## Discovery tools ### Cloud discovery tools - **`cloud_info()`** — Returns cloud connection information including authentication status, subscription details, and tenant info. No parameters. - **`release_notes()`** — Returns the latest Basic Memory release notes and changelog. No parameters. --- ## ChatGPT compatibility tools These are compatibility wrappers for ChatGPT's MCP implementation, which uses a simplified two-tool interface by default. - **`search(query)`** — Search across the knowledge base. Equivalent to `search_notes` with default parameters. - **`fetch(id)`** — Retrieve full document content by permalink. Equivalent to `read_note`. See the [ChatGPT integration guide](https://docs.basicmemory.com/integrations/chatgpt) for usage details and limitations. --- ## Related pages - [CLI Reference](https://docs.basicmemory.com/reference/cli-reference) - [AI Assistant Guide](https://docs.basicmemory.com/reference/ai-assistant-guide) - [Memory URLs](https://docs.basicmemory.com/concepts/memory-urls) - [Schema System](https://docs.basicmemory.com/concepts/schema-system) - [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search) # AI Assistant Guide ::note This is a technical guide for developers and AI integrations. For an overview of how Basic Memory works, see [What is Basic Memory](https://docs.basicmemory.com/start-here/what-is-basic-memory). This guide is for AI assistants using Basic Memory tools through MCP. For setup instructions, see [Getting Started](https://docs.basicmemory.com/start-here/getting-started). Download the [AI Assistant Guide](https://github.com/basicmachines-co/basic-memory/blob/main/docs/ai-assistant-guide-extended.md){rel=""nofollow""} and customize it to your own workflow. A [condensed version](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/resources/ai_assistant_guide.md){rel=""nofollow""} is available as an MCP Resource in Basic Memory. :: ::tip **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](https://docs.basicmemory.com/reference/llms-txt) 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: ```python # List all projects projects = await list_memory_projects() # Response includes: # - name # - path # - is_default # - note_count # - last_synced ``` **Recommended workflow:** 1. Call `list_memory_projects()` at conversation start 2. Identify active project from metadata 3. Ask user which project to use 4. Store choice for the session 5. Pass project parameter to all tool calls ### Cross-Project Operations Some tools work across all projects when project parameter is omitted: ```python # 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()` --- ## 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 **Note types** (set via the `type` frontmatter field): - `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:** ```bash ## 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:** ```bash ## 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: ```python # Create note with forward reference await write_note( title="API Implementation", content="## Relations\n- implements [[API Specification]]", directory="api", project="main" ) # Forward reference created # Later, create referenced entity await write_note( title="API Specification", content="# API Specification\n...", directory="specs", project="main" ) # Forward reference automatically resolved ``` --- ## Core Tools ### Writing Knowledge Create new notes: ```python await write_note( title="Topic", content="# Topic\n## Observations\n- [category] fact\n## Relations\n- relates_to [[Other]]", directory="notes", project="main" ) ``` **Parameters:** - `title` (required) - Note title - `content` (required) - Markdown content - `directory` (required) - Destination folder - `tags` (optional) - List of tags - `note_type` (optional) - Note type (default: `note`) - `metadata` (optional) - Extra frontmatter fields - `overwrite` (optional) - Default `false`. Must be `true` to replace an existing note - `project` (optional) - Uses `default_project` fallback when configured ::warning **`write_note` is non-destructive by default.** If a note already exists at the target path, the call returns an error instead of silently overwriting. This prevents accidental data loss. - To update an existing note incrementally, use `edit_note` - To fully replace an existing note, pass `overwrite=True` - Always search before writing to check whether the note already exists :: ### Reading Knowledge Read notes with knowledge graph context: ```python # 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: ```python results = await search_notes( query="authentication", project="main", page_size=10 ) ``` **Filter by note type:** ```python # Find all specs about authentication specs = await search_notes( query="authentication", note_types=["spec"], project="main" ) # Find all meeting notes and decisions results = await search_notes( note_types=["meeting", "decision"], project="main" ) ``` **Filter by date:** ```python recent = await search_notes( query="api", after_date="2025-01-01", project="main" ) ``` **Search by tags:** ```python # tag: shorthand in the query string results = await search_notes(query="tag:security", project="main") results = await search_notes(query="tag:coffee AND tag:brewing", project="main") # tags parameter shorthand results = await search_notes(tags=["security"], project="main") results = await search_notes(tags=["security", "oauth"], project="main") ``` **Search by frontmatter metadata:** The `query` parameter is optional — you can search purely by frontmatter fields. Use `metadata_filters` for structured queries against any frontmatter field, or convenience shorthands for common fields. ```python # Find all notes with a specific status results = await search_notes( metadata_filters={"status": "in-progress"}, project="main" ) # Find high-priority items results = await search_notes( metadata_filters={"priority": {"$in": ["high", "critical"]}}, project="main" ) # Filter by team results = await search_notes( metadata_filters={"team": "backend"}, project="main" ) # Combine text search with metadata filters results = await search_notes( query="authentication", metadata_filters={"status": "draft"}, project="main" ) # Convenience shorthands for common fields results = await search_notes(status="draft", project="main") results = await search_notes(tags=["security"], project="main") ``` **Supported filter operators:** | Operator | Example | Meaning | | ----------- | --------------------------------------------- | -------------------------- | | exact match | `{"status": "draft"}` | Field equals value | | `$in` | `{"priority": {"$in": ["high", "critical"]}}` | Field is one of the values | | `$contains` | `{"tags": {"$contains": "security"}}` | Array field contains value | **Semantic search:** Semantic search is enabled by default. `hybrid` mode (combining keyword and meaning-based retrieval) is the default search type — no opt-in needed. You can also use pure semantic search: ```python # Pure semantic similarity — finds related concepts even with different wording results = await search_notes( query="how to speed up the application", search_type="vector", project="main" ) # Hybrid — combines keyword precision with semantic recall (recommended for most queries) results = await search_notes( query="authentication security", search_type="hybrid", project="main" ) # Adjust similarity threshold for tighter or looser results results = await search_notes( query="error handling patterns", search_type="hybrid", min_similarity=0.7, project="main" ) ``` **When to use which search mode:** - `hybrid` (default) — General-purpose. Start here for most queries. - `text` — You know the exact terms. Best for names, identifiers, boolean queries. - `vector` — Conceptual discovery. The note may not contain your exact words. ### Building Context Navigate the knowledge graph. `build_context` defaults to JSON output (unlike other tools which default to text). ```python 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") - `output_format` (optional) - Default `"json"`. Pass `"text"` for human-readable output - `project` (optional) - Uses `default_project` fallback when configured **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: ```python # 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: ```python 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. Generated permalinks include the project slug by default, so most URLs you encounter will be project-prefixed. **By title:** ```text memory://title ``` **By folder and title:** ```text memory://folder/title ``` **Project-prefixed (default format):** ```text memory://project-slug/folder/title ``` **By permalink:** ```text memory://permalink ``` **All in folder:** ```text 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:** ```text 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:** 1. **Decisions and Rationales** 2. **Important Discoveries** 3. **Action Items and Plans** 4. **Connected Topics** ### Recording Patterns **Conversation summary:** ```python 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} """, directory="conversations", tags=["conversation"], project="main" ) ``` **Decision record:** ```python 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} """, directory="decisions", note_type="decision", project="main" ) ``` --- ## Schemas Schemas define what a "good" note of a particular type should contain. They formalize observation categories and relation types so you can validate notes against a consistent structure. Schemas are optional — you can use Basic Memory without ever defining one — but they help maintain consistency as a knowledge base grows and give you a guide for creating well-structured notes. A schema is just a regular note with `type: schema` in frontmatter: ```yaml --- title: Person type: schema entity: person version: 1 schema: name: string, full legal name role?: string, current job title works_at?: Organization, primary employer expertise?(array, areas of knowledge): string settings: validation: warn --- ``` Fields without `?` are required. Fields with `?` are optional. Capitalized types like `Organization` indicate entity references (wiki-link relations). Array fields expect multiple observations of the same category. ### Schema tools Three tools are available for working with schemas: - **`schema_infer`** — Analyze existing notes of a type and suggest a schema based on common patterns. Use this when the user wants to create a schema from their existing notes. - **`schema_validate`** — Check notes against their schema. Pass `note_type` to validate all notes of a type, or `identifier` to validate a single note. - **`schema_diff`** — Compare a schema against actual note usage to detect drift. Shows which fields are defined but unused, and which undeclared fields appear in practice. ### Creating notes with schemas When a schema exists for a note type, use it as a creation guide: 1. **Look up the schema** before creating a note of a known type: ```python # Check what fields a "person" note should have schema = await schema_infer(note_type="person") ``` 2. **Create the note** following the schema's field definitions: ```python await write_note( title="Grace Hopper", content="""# Grace Hopper ## Observations - [name] Grace Hopper - [role] Computer Scientist and Navy Admiral - [expertise] Compiler design - [expertise] Programming languages ## Relations - works_at [[US Navy]] - works_at [[Harvard University]] """, directory="people", note_type="person", metadata={"status": "historical"}, project="main" ) ``` 3. **Validate** after creation to confirm conformance: ```python result = await schema_validate(identifier="people/grace-hopper", project="main") ``` ### Discovering and evolving schemas Users may ask you to help create or refine schemas. The typical workflow: ```python # 1. Infer a schema from existing notes schema = await schema_infer(note_type="meeting", project="main") # 2. Review the suggested schema with the user, then write it await write_note( title="Meeting", content="...", # schema frontmatter + description directory="schemas", note_type="schema", project="main" ) # 3. Validate existing notes against the new schema results = await schema_validate(note_type="meeting", project="main") # 4. Later, check for drift as note patterns evolve drift = await schema_diff(note_type="meeting", project="main") ``` ### Using `note_type` and `metadata` The `note_type` parameter sets the `type` frontmatter field, which controls schema resolution and search filtering. Use it whenever creating notes of a specific type: ```python await write_note( title="Sprint Planning 2026-02-15", content="...", directory="meetings", note_type="meeting", metadata={"sprint": 12, "team": "backend"}, project="main" ) ``` The `metadata` parameter accepts any key-value pairs that get merged into the note's frontmatter. Use it for custom fields like `status`, `priority`, `due_date`, or `team` — these become searchable via `metadata_filters` in `search_notes`. See the full [Schema System](https://docs.basicmemory.com/concepts/schema-system) guide for syntax details and validation modes. --- ## Best Practices ### 1. Project Discovery Always start with discovery: ```python # 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:** ```bash --- 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. `write_note` returns an error if a note already exists at the target path, so searching first prevents failed writes and lets you choose the right tool: ```python # Before writing new note existing = await search_notes( query="topic name", project="main" ) if existing["total"] > 0: # Update existing with edit_note 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: ```python # 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: ```python # Session 1: Create foundation await write_note( title="Topic", content="Basic structure with initial observations", directory="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. ::note When in doubt, create a snapshot (Cloud) or suggest a backup (Local). :: --- ## Error Handling ### Note Already Exists The most common error. `write_note` returns an error when a note already exists at the target path. This is intentional — it prevents accidental overwrites. **Solution:** ```python # Option 1: Update the existing note incrementally await edit_note( identifier="existing-note-path", operation="append", content="New content to add", project="main" ) # Option 2: Explicitly replace the note await write_note( title="Topic", content="Completely new content", directory="notes", overwrite=True, project="main" ) ``` ### Missing Project Parameter **Solution:** ```python 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:** ```python try: note = await read_note("Nonexistent Note", project="main") except: results = await search_notes(query="Note", project="main") # Suggest alternatives to user ``` ### Forward References **Not an error:** Forward references resolve automatically when targets are created. No action needed. --- ## Tool Reference ### Content Management | Tool | Purpose | | -------------- | --------------------------------------------------------------------------- | | `write_note` | Create new markdown notes (errors on existing path unless `overwrite=True`) | | `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 (text, vector, hybrid modes) | ### Schema Tools | Tool | Purpose | | ----------------- | -------------------------------------------- | | `schema_validate` | Validate notes against schema definitions | | `schema_infer` | Analyze notes and suggest schema patterns | | `schema_diff` | Detect drift between schema and actual usage | ### Project Management | Tool | Purpose | | ----------------------- | --------------------------------- | | `list_memory_projects` | List all available projects | | `create_memory_project` | Create new project | | `delete_project` | Delete project from configuration | | `list_workspaces` | List available cloud workspaces | ### Visualization | Tool | Purpose | | -------- | ---------------------- | | `canvas` | Create Obsidian canvas | --- ## Next Steps ::card-group :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- Complete tool documentation with parameters and examples. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Understanding the note structure and semantic patterns. ::: :: # Technical Information ::note This page describes the architecture of the open-source [Basic Memory](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""} project. [Basic Memory Cloud](https://docs.basicmemory.com/cloud/cloud-guide) builds on this foundation with hosted infrastructure and additional features. :: ## Architecture Basic Memory consists of: - **Core Knowledge Engine** — Parses and indexes Markdown files - **Database** — Provides fast querying and search - **MCP Server** — Implements the Model Context Protocol - **CLI Tools** — Command-line utilities for management - **File Watcher** — Monitors file changes and indexes the database ::note The system follows a **file-first architecture** where all knowledge is represented in standard Markdown files and the database serves as a secondary index. :: ## Model Context Protocol (MCP) Basic Memory implements the [Model Context Protocol](https://github.com/modelcontextprotocol/spec){rel=""nofollow""}, an open standard for enabling AI models to access external tools: - **Standardized Interface** — Common protocol for tool integration - **Tool Registration** — Basic Memory registers as a tool provider - **Asynchronous Communication** — Enables efficient interaction with AI models - **Standardized Schema** — Structured data exchange format Integration with Claude Desktop uses the MCP to grant Claude access to your knowledge base through a set of specialized tools that search, read, and write knowledge. ## Licensing Basic Memory is licensed under the [GNU Affero General Public License v3.0 (AGPL-3.0)](https://www.gnu.org/licenses/agpl-3.0.en.html){rel=""nofollow""}: - **Free Software** — You can use, study, share, and modify the software - **Copyleft** — Derivative works must be distributed under the same license - **Network Use** — Network users must be able to receive the source code - **Commercial Use** — Allowed, subject to license requirements ::note The AGPL license ensures Basic Memory remains open source while protecting against proprietary forks. :: ## Source Code Basic Memory is developed as an open-source project: - **GitHub Repository** — {rel=""nofollow""} - **Issue Tracker** — Report bugs and request features on GitHub - **Contributions** — Pull requests are welcome following the contributing guidelines - **Documentation** — Source for this documentation is also available in the repository ## Data Storage and Privacy Basic Memory is designed with privacy as a core principle: ::note **Privacy-First Design:** - **Local-First**: All data remains on your machine - **No Cloud Dependency**: No remote servers or accounts required - **Telemetry**: Optional and disabled by default - **Standard Formats**: All data is stored in standard file formats you control :: ## Implementation Details Knowledge in Basic Memory is organized as a semantic graph: ::steps ### Entities Distinct concepts represented by Markdown documents ### Observations Categorized facts and information about entities ### Relations Connections between entities that form the knowledge graph :: This structure emerges from simple text patterns in standard Markdown: ### Example Markdown Input ```bash --- title: Coffee Brewing Methods type: note permalink: coffee/coffee-brewing-methods tags: - '#coffee' - '#brewing' - '#methods' - '#demo' --- # Coffee Brewing Methods An exploration of different coffee brewing techniques, their characteristics, and how they affect flavor extraction. ## Overview Coffee brewing is both an art and a science. Different brewing methods extract different compounds from coffee beans, resulting in unique flavor profiles, body, and mouthfeel. The key variables in any brewing method are: - Grind size - Water temperature - Brew time - Coffee-to-water ratio - Agitation/turbulence ## Observations - [principle] Coffee extraction follows a predictable pattern: acids extract first, then sugars, then bitter compounds #extraction - [method] Pour over methods generally produce cleaner, brighter cups with more distinct flavor notes #clarity ## Relations - requires [[Proper Grinding Technique]] - affects [[Flavor Extraction]] ``` ### Parsed JSON Structure ### Resulting JSON Entity Structure ```json { "entities": [ { "permalink": "coffee/coffee-brewing-methods", "title": "Coffee Brewing Methods", "file_path": "Coffee Notes/Coffee Brewing Methods.md", "entity_type": "note", "entity_metadata": { "title": "Coffee Brewing Methods", "type": "note", "permalink": "coffee/coffee-brewing-methods", "tags": "['#coffee', '#brewing', '#methods', '#demo']" }, "checksum": "bfa32a0f23fa124b53f0694c344d2788b0ce50bd090b55b6d738401d2a349e4c", "content_type": "text/markdown", "observations": [ { "category": "principle", "content": "Coffee extraction follows a predictable pattern: acids extract first, then sugars, then bitter compounds #extraction", "tags": [ "extraction" ], "permalink": "coffee/coffee-brewing-methods/observations/principle/coffee-extraction-follows-a-predictable-pattern-acids-extract-first-then-sugars-then-bitter-compounds-extraction" }, { "category": "method", "content": "Pour over methods generally produce cleaner, brighter cups with more distinct flavor notes #clarity", "tags": [ "clarity" ], "permalink": "coffee/coffee-brewing-methods/observations/method/pour-over-methods-generally-produce-cleaner-brighter-cups-with-more-distinct-flavor-notes-clarity" } ], "relations": [ { "from_id": "coffee/coffee-bean-origins", "to_id": "coffee/coffee-brewing-methods", "relation_type": "pairs_with", "permalink": "coffee/coffee-bean-origins/pairs-with/coffee/coffee-brewing-methods", "to_name": "Coffee Brewing Methods" }, { "from_id": "coffee/flavor-extraction", "to_id": "coffee/coffee-brewing-methods", "relation_type": "affected_by", "permalink": "coffee/flavor-extraction/affected-by/coffee/coffee-brewing-methods", "to_name": "Coffee Brewing Methods" } ], "created_at": "2025-03-06T14:01:23.445071", "updated_at": "2025-03-06T13:34:48.563606" } ] } ``` Basic Memory understands how to build context via its semantic graph. ### Entity Model Basic Memory's core data model consists of: - **Entities** — Documents in your knowledge base - **Observations** — Facts or statements about entities - **Relations** — Connections between entities - **Tags** — Additional categorization for entities and observations The system parses Markdown files to extract this structured information while preserving the human-readable format. ### Files as Source of Truth Plain Markdown files store all knowledge, making it accessible with any text editor and easy to version with git. ::mermaid --- code: | flowchart TD User((User)) <--> |Conversation| Claude["Claude or other LLM"] Claude <-->|API Calls| BMCP["Basic Memory MCP Server"] KnowledgeFiles["Markdown Files - Source of Truth"] KnowledgeIndex[(Knowledge Graph Index)] BMCP <-->|"write_note() read_note()"| KnowledgeFiles BMCP <-->|"search_notes() build_context()"| KnowledgeIndex KnowledgeFiles <-.->|Sync Process| KnowledgeIndex KnowledgeFiles <-->|Direct Editing| Editors((Text Editors & Git)) User -.->|"Complete control, Privacy preserved"| KnowledgeFiles --- :: ### Database The database maintains the knowledge graph topology for fast queries and semantic traversal. It contains: - **Knowledge Graph Schema** — Database tables for the knowledge graph structure - **Search Index** — Full text search index across the knowledge base ### Sync Process The sync process: ::steps ### Detect Changes Detects changes to files in the knowledge directory ### Parse Files Parses modified files to extract structured data ### Update Database Updates the database with changes ### Resolve References Resolves forward references when new entities are created ### Update Search Index Updates the search index for fast querying :: ### Search Engine The search functionality: - **Hybrid Search** — Uses a combination of full-text search and semantic matching - **Comprehensive Indexing** — Indexes observations, relations, and content - **Pattern Matching** — Supports wildcards and pattern matching in memory:// URLs - **Graph Traversal** — Traverses the knowledge graph to follow relationships ::note Results are ranked by relevance to the query using advanced scoring algorithms. :: ## System Architecture ### Component Interaction The Basic Memory system is built with a modular architecture: ::tabs :::div{label="File Layer"} **Markdown Files** — The foundation of your knowledge base - **Human-Readable** — Edit with any text editor - **Version Control Friendly** — Works seamlessly with Git - **Standard Format** — Plain Markdown with YAML frontmatter - **Complete Ownership** — Your files, your control ::: :::div{label="Processing Layer"} **Sync Service** — Keeps everything in sync - **File Monitoring** — Watches for changes in real-time - **Markdown Parsing** — Extracts structure from content - **Entity Extraction** — Identifies entities, observations, relations - **Database Updates** — Maintains the knowledge graph index ::: :::div{label="Storage Layer"} **Database** — Fast indexing - **Fast Querying** — Optimized for knowledge graph queries - **Full-Text Search** — Search across all content - **Relationship Mapping** — Tracks entity connections - **Metadata Storage** — Stores parsed entity information ::: :::div{label="Interface Layer"} **MCP Server** — AI integration layer - **Standardized Tools** — 17 MCP tools for AI access - **Real-Time Access** — Live knowledge base queries - **Secure Auth** — JWT-based authentication for cloud - **Cross-Platform** — Works with Claude, VS Code, Cursor ::: :: ### Performance Characteristics - **Local Performance** — All operations are local with no network latency - **Scalability** — Handles knowledge bases with thousands of documents - **Resource Efficiency** — Minimal CPU and memory footprint ## Development Philosophy Basic Memory embodies several key principles: ::note **Core Principles:** - **Local-First**: Your data stays on your machine - **Open Standards**: Uses standard formats and protocols - **Human-Readable**: Everything is accessible without special tools - **AI-Native**: Designed specifically for AI collaboration - **Privacy-Preserving**: No data collection or tracking :: # Troubleshooting This guide covers common issues and their solutions. For live help, visit our [Discord server](https://discord.gg/tyvKNccgqN){rel=""nofollow""}. --- ## MCP Connection Issues ### Claude Says "No Basic Memory Tools Available" **Problem:** Claude Desktop can't find Basic Memory tools. **Solutions:** 1. **Check absolute paths** - Use complete paths in Claude Desktop config: ```json { "mcpServers": { "basic-memory": { "command": "/Users/yourusername/.local/bin/uvx", "args": ["basic-memory", "mcp"] } } } ``` :brFind your path with: `which uvx` 2. **Verify installation**: ```bash basic-memory --version ``` 3. **Restart applications** - Close and reopen both Terminal and Claude Desktop 4. **Check sync status**: ```bash basic-memory status ``` ### ENOENT Error **Problem:** Claude Desktop cannot find the `uv` installation. **Solution:** 1. Find the absolute path: `which uvx` 2. Update Claude Desktop config with the full path 3. Restart Claude Desktop ### MCP Endpoint Connection Fails (Cloud) **Problem:** Remote MCP connection not working. **Solutions:** 1. **Verify endpoint URL**: `https://cloud.basicmemory.com/mcp` 2. **Re-authenticate**: ```bash bm cloud logout bm cloud login ``` 3. **Check subscription status**: ```bash bm cloud status ``` 4. **Restart your MCP client** (Claude Desktop, VS Code, etc.) --- ## Cloud Issues ### Cloud Mode Not Working **Problem:** CLI commands not working in cloud mode. **Solution:** ```bash bm cloud logout bm cloud login ``` ### Subscription Required Error **Problem:** "Active subscription required" message. **Solution:** 1. Visit [basicmemory.com/subscribe](https://basicmemory.com/subscribe){rel=""nofollow""} 2. Complete subscription 3. Run `bm cloud login` again Access is immediate when subscription becomes active. ### Authentication Failed or Invalid Token **Problem:** Token expired or invalid. **Solution:** ```bash bm cloud logout bm cloud login ``` --- ## Sync Issues ### Changes Not Syncing **Problem:** File changes not appearing in knowledge base. **Solutions:** 1. **Check sync status**: ```bash basic-memory status ``` 2. **Verify file permissions** - Ensure Basic Memory can read/write to the project directory 3. **Check .gitignore patterns** - Files matching ignore patterns are skipped 4. **Reset the database**: ```bash basic-memory reset ``` :warning[This re-indexes all files. May take time for large knowledge bases.] ### Sync In Progress **Problem:** Operations failing with "sync in progress" message. **Solution:** Wait for sync to complete, then retry. Check progress with: ```bash basic-memory status ``` ### Cloud Sync Issues **Problem:** Bisync not working. **Solutions:** 1. **Re-run setup**: ```bash bm cloud setup ``` 2. **First bisync requires --resync**: ```bash bm cloud bisync --name research --resync ``` 3. **Empty directory error** - Add at least one file: ```bash echo "# Notes" > ~/Documents/research/README.md bm cloud bisync --name research --resync ``` 4. **Bisync state corruption** - Reset state: ```bash bm cloud bisync-reset research bm cloud bisync --name research --resync ``` 5. **Too many deletes error** - Review changes, then force: ```bash bm cloud bisync --name research --dry-run bm cloud bisync --name research --resync ``` --- ## Search and Content Issues ### Claude Can't Find Knowledge **Problem:** AI assistant not finding your notes. **Solutions:** 1. **Confirm files are in correct directory**: ```bash basic-memory project list ls ~/basic-memory ``` 2. **Check frontmatter formatting** - Ensure YAML is valid: ```yaml --- title: My Note tags: [tag1, tag2] --- ``` 3. **Use memory:// URLs for direct access**: ```text memory://my-note-title ``` 4. **Trigger a re-sync**: ```bash basic-memory sync ``` ### Entity Not Found **Problem:** Note doesn't exist at specified path. **Solutions:** 1. **Search for the note**: ```text Find notes about [topic] ``` 2. **Check exact title/permalink** - Titles are case-sensitive 3. **List directory contents**: ```text List files in [folder] ``` --- ## Performance Issues ### Slow Operations **Problem:** Commands or syncing taking too long. **Solutions:** 1. **Check database size**: ```bash basic-memory project info ``` 2. **Archive old content** - Move inactive notes to archive folder 3. **Adjust sync delay** - Add to `~/.basic-memory/config.json`: ```json { "sync_delay": 2000 } ``` 4. **Increase thread pool** for large knowledge bases: ```json { "sync_thread_pool_size": 8 } ``` ### High Memory Usage **Problem:** Basic Memory using too much memory. **Solutions:** 1. **Limit context depth** in MCP calls (use `depth=1` or `depth=2`) 2. **Reduce search page size** 3. **Archive old content** --- ## Installation Issues ### Python Version Error **Problem:** "Python 3.13+ required" error. **Solution:** Install Python 3.13 or higher: ```bash # macOS with Homebrew brew install python@3.13 # Or use pyenv pyenv install 3.13.0 pyenv global 3.13.0 ``` ### uv Not Found **Problem:** `uv` command not found. **Solution:** Install uv: ```bash # macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Then add to PATH (restart terminal or run) source ~/.bashrc # or ~/.zshrc ``` ### Permission Errors **Problem:** Can't create files or access directories. **Solutions:** 1. **Check directory permissions**: ```bash ls -la ~/basic-memory ``` 2. **Fix permissions**: ```bash chmod -R u+rw ~/basic-memory ``` 3. **Ensure Claude Desktop can execute uvx** --- ## Project Issues ### Project Not Found **Problem:** Project doesn't exist in configuration. **Solutions:** 1. **List available projects**: ```bash basic-memory project list ``` 2. **Add the project**: ```bash basic-memory project add my-project ~/path/to/project ``` ### Project Not Configured for Sync (Cloud) **Problem:** "Project has no local\_sync\_path configured" **Solution:** ```bash bm cloud sync-setup research ~/Documents/research bm cloud bisync --name research --resync ``` ### Moving Notes Between Projects **Problem:** Can't move notes from one project to another. **Current solution:** Copy the file manually or create a new note in the destination project, then delete the original. --- ## Configuration Issues ### Config Changes Not Taking Effect **Problem:** Updated config.json but nothing changed. **Solution:** Restart your MCP client (Claude Desktop, VS Code, etc.) after changing configuration. ### Invalid JSON in Config **Problem:** Configuration file has syntax errors. **Solution:** Validate your JSON: ```bash cat ~/.basic-memory/config.json | python -m json.tool ``` Common issues: - Missing commas between properties - Trailing commas after last property - Unquoted strings --- ## Database Issues ### Database Locked **Problem:** "database is locked" error. **Solutions:** 1. **Close other applications** accessing the database 2. **Restart Basic Memory**: ```bash # Find and kill processes pkill -f "basic-memory" ``` 3. **Remove lock files** (if they exist): ```bash rm ~/.basic-memory/memory.db-shm rm ~/.basic-memory/memory.db-wal ``` ### Corrupted Database **Problem:** Database errors or inconsistent state. **Solution:** Reset and re-index: ```bash basic-memory reset ``` ::warning This rebuilds the database from your markdown files. All files are preserved. :: --- ## Getting Help ### Check Logs ```bash # View log files cat ~/.basic-memory/basic-memory-*.log # Or for Cloud mode cat ~/.basic-memory/basic-memory-cloud.json ``` ### Command Help ```bash # View all commands basic-memory --help # Get help for specific commands basic-memory sync --help basic-memory project --help bm cloud --help ``` ### Community Support - **Discord**: [discord.gg/tyvKNccgqN](https://discord.gg/tyvKNccgqN){rel=""nofollow""} - #help channel - **GitHub Issues**: [github.com/basicmachines-co/basic-memory/issues](https://github.com/basicmachines-co/basic-memory/issues){rel=""nofollow""} --- ## Next Steps ::card-group :::card --- icon: i-lucide-rocket title: Getting Started to: https://docs.basicmemory.com/start-here/getting-started --- Installation guide and initial setup. ::: :::card --- icon: i-lucide-terminal title: CLI Reference to: https://docs.basicmemory.com/reference/cli-reference --- Complete command documentation. ::: :::card --- icon: i-lucide-refresh-cw title: Cloud Sync Guide to: https://docs.basicmemory.com/cloud/cloud-sync --- Cloud sync configuration and troubleshooting. ::: :: # Configuration Basic Memory reads configuration from: 1. Environment variables (`BASIC_MEMORY_*`) 2. Config file (`~/.basic-memory/config.json` by default) 3. Built-in defaults Environment variables override config file values. --- ## Config file location Default location: ```bash ~/.basic-memory/config.json ``` To isolate config and default SQLite data per workspace/process, set: ```bash export BASIC_MEMORY_CONFIG_DIR=/path/to/custom-dir ``` When set, Basic Memory stores config and default app DB in that directory. --- ## Example config (v0.19+) ```json { "default_project": "main", "projects": { "main": { "path": "/Users/you/basic-memory", "mode": "local" }, "research": { "path": "/Users/you/research-notes", "mode": "cloud", "cloud_sync_path": "/Users/you/research-notes", "bisync_initialized": true, "last_sync": "2026-02-15T18:30:00Z" } }, "semantic_search_enabled": true, "semantic_min_similarity": 0.55, "permalinks_include_project": true, "cloud_mode": false } ``` --- ## Project and routing settings ### `projects` Projects are now stored as structured entries, not just name -> path strings. Each project entry supports: - `path`: local filesystem path - `mode`: `local` or `cloud` - `cloud_sync_path` (optional) - `bisync_initialized` (optional) - `last_sync` (optional) ### `default_project` Fallback project name used when tools/commands do not pass a project. - Type: `string | null` - Default: `"main"` ::note `default_project_mode` is deprecated/removed from active config behavior. Use `default_project` as fallback instead. :: ### `BASIC_MEMORY_MCP_PROJECT` Environment-level project constraint for MCP sessions. - Locks operations to one project for that process/session - Highest-priority project constraint ### Per-project routing mode Use CLI to manage per-project routing: ```bash bm project set-cloud research bm project set-local research ``` Cloud-routed projects use cloud credentials/API key; local-routed projects use local ASGI transport. --- ## Semantic search settings ### `semantic_search_enabled` Enable vector/hybrid retrieval. - Type: boolean - Default: `true` - Env: `BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED` Semantic search is enabled and included by default in all standard installs. Embeddings are generated automatically on first startup. If sqlite-vec fails to load, search gracefully falls back to text-only mode. ### `semantic_embedding_provider` Embedding provider. - Type: string - Default: `"fastembed"` - Common values: `fastembed`, `openai` - Env: `BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER` ### `semantic_embedding_model` Embedding model name. - Type: string - Default: `"bge-small-en-v1.5"` - Env: `BASIC_MEMORY_SEMANTIC_EMBEDDING_MODEL` ### `semantic_embedding_dimensions` Embedding dimensions override. - Type: integer | null - Default: `null` (auto) - Env: `BASIC_MEMORY_SEMANTIC_EMBEDDING_DIMENSIONS` ### `semantic_embedding_batch_size` Embedding batch size. - Type: integer - Default: `64` - Env: `BASIC_MEMORY_SEMANTIC_EMBEDDING_BATCH_SIZE` ### `semantic_vector_k` Vector candidate count. - Type: integer - Default: `100` - Env: `BASIC_MEMORY_SEMANTIC_VECTOR_K` ### `semantic_min_similarity` Global minimum similarity threshold for vector results. - Type: float (`0.0` to `1.0`) - Default: `0.55` - Env: `BASIC_MEMORY_SEMANTIC_MIN_SIMILARITY` Set to `0.0` to disable threshold filtering globally. ::tip Semantic search dependencies are included by default in all standard installs. :: --- ## Permalink and file behavior ### `permalinks_include_project` When enabled, generated permalinks include project slug prefix. - Type: boolean - Default: `true` - Env: `BASIC_MEMORY_PERMALINKS_INCLUDE_PROJECT` ### `ensure_frontmatter_on_sync` Add frontmatter to files during sync if they don't already have it. - Type: boolean - Default: `true` - Env: `BASIC_MEMORY_ENSURE_FRONTMATTER_ON_SYNC` ### `write_note_overwrite_default` Default value for the `overwrite` parameter on `write_note`. When `false` (default), writing to an existing note path returns an error unless `overwrite=True` is passed explicitly. Set to `true` to restore the pre-v0.19 upsert behavior. - Type: boolean - Default: `false` - Env: `BASIC_MEMORY_WRITE_NOTE_OVERWRITE_DEFAULT` ### `update_permalinks_on_move` Update permalinks when files move. - Type: boolean - Default: `false` - Env: `BASIC_MEMORY_UPDATE_PERMALINKS_ON_MOVE` ### `disable_permalinks` Disable automatic permalink generation for new notes. - Type: boolean - Default: `false` - Env: `BASIC_MEMORY_DISABLE_PERMALINKS` ### `kebab_filenames` Generate kebab-case filenames for tool-created notes. - Type: boolean - Default: `false` - Env: `BASIC_MEMORY_KEBAB_FILENAMES` --- ## Sync and watch settings ### `sync_changes` Enable filesystem-to-index synchronization. - Type: boolean - Default: `true` - Env: `BASIC_MEMORY_SYNC_CHANGES` ### `sync_delay` Debounce delay for sync in milliseconds. - Type: integer - Default: `1000` - Env: `BASIC_MEMORY_SYNC_DELAY` ### `sync_thread_pool_size` Thread pool size for file operations. - Type: integer - Default: `4` - Env: `BASIC_MEMORY_SYNC_THREAD_POOL_SIZE` ### `sync_max_concurrent_files` Maximum number of files to process concurrently during sync operations. - Type: integer - Default: `10` - Env: `BASIC_MEMORY_SYNC_MAX_CONCURRENT_FILES` ### `skip_initialization_sync` Skip the initial full sync when the MCP server starts. Useful for large projects where you want the server to start faster and rely on the file watcher for incremental updates. - Type: boolean - Default: `false` - Env: `BASIC_MEMORY_SKIP_INITIALIZATION_SYNC` ### `watch_project_reload_interval` Seconds between project list reloads in watch-related services. - Type: integer - Default: `300` - Env: `BASIC_MEMORY_WATCH_PROJECT_RELOAD_INTERVAL` --- ## Update settings Basic Memory can check for new releases and install them automatically for CLI installs (Homebrew, `uv tool`, `uvx`). MCP server processes check silently in the background and never block. Run `bm update` to check and install on demand. See [`bm update`](https://docs.basicmemory.com/reference/cli-reference#bm-update) in the CLI Reference. ### `auto_update` Enable automatic update checks and installs when supported. Set to `false` to disable background update checks. - Type: boolean - Default: `true` - Env: `BASIC_MEMORY_AUTO_UPDATE` ### `update_check_interval` Seconds between automatic update checks. - Type: integer - Default: `86400` (24 hours) - Env: `BASIC_MEMORY_UPDATE_CHECK_INTERVAL` ### `auto_update_last_checked_at` Timestamp of the last automatic update check. Managed automatically — you don't normally set this yourself. - Type: datetime - Default: unset --- ## Formatter settings ### `format_on_save` Automatically format notes when they are saved via `write_note` or `edit_note`. - Type: boolean - Default: `false` - Env: `BASIC_MEMORY_FORMAT_ON_SAVE` ### `formatter_command` External command to use for formatting markdown files. When set and `format_on_save` is enabled, this command is called with the file path as an argument. - Type: string | null - Default: `null` - Env: `BASIC_MEMORY_FORMATTER_COMMAND` ### `formatter_timeout` Maximum time in seconds to wait for the formatter command to complete. - Type: float - Default: `5.0` - Env: `BASIC_MEMORY_FORMATTER_TIMEOUT` --- ## Database settings ### `database_backend` Database backend to use for the knowledge index. - Type: string - Default: `"sqlite"` - Values: `sqlite`, `postgres` - Env: `BASIC_MEMORY_DATABASE_BACKEND` SQLite is used for local installations. Postgres is used by Basic Memory Cloud and can be configured for self-hosted deployments. ### `database_url` Connection URL for the database when using the Postgres backend. - Type: string | null - Default: `null` - Env: `BASIC_MEMORY_DATABASE_URL` Only required when `database_backend` is `postgres`. Example: `postgresql://user:pass@host:5432/dbname` --- ## Cloud settings ### `cloud_mode` Global cloud mode toggle. - Type: boolean - Default: `false` - Env: `BASIC_MEMORY_CLOUD_MODE` ### `cloud_api_key` Account-level cloud API key (`bmc_...`) used for cloud-routed projects. - Type: string | null - Default: `null` - Env: `BASIC_MEMORY_CLOUD_API_KEY` Use CLI: ```bash bm cloud api-key save bmc_... bm cloud api-key create "my-laptop" ``` ### `cloud_promo_opt_out` Disable CLI cloud promo messages. - Type: boolean - Default: `false` - Env: `BASIC_MEMORY_CLOUD_PROMO_OPT_OUT` --- ## Logging and diagnostics ### `log_level` - Default: `INFO` - Env: `BASIC_MEMORY_LOG_LEVEL` --- ## Migration notes When loading older config files, Basic Memory automatically migrates legacy keys and formats, including: - legacy string-valued `projects` mapping - `project_modes` - `cloud_projects` - `default_project_mode` After migration, config is re-saved in current format. --- ## Related pages - [CLI Reference](https://docs.basicmemory.com/reference/cli-reference) - [MCP Tools Reference](https://docs.basicmemory.com/reference/mcp-tools-reference) - [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search) # Docker ::warning The Docker image runs Basic Memory as an **SSE server** on port 8000. This is designed for server deployments where clients connect over HTTP, not for local MCP stdio connections with Claude Desktop. :: ## Overview Basic Memory provides official Docker images published to GitHub Container Registry. The container runs the MCP server with SSE (Server-Sent Events) transport, suitable for: - Server deployments where multiple clients connect remotely - Kubernetes or Docker Compose orchestration - CI/CD environments - Development and testing For local use with Claude Desktop or other MCP clients that use stdio transport, we recommend installing via [Homebrew](https://docs.basicmemory.com/local/local-install) or [pip](https://docs.basicmemory.com/local/local-install). ## Quick Start ### Pull the Image ```bash docker pull ghcr.io/basicmachines-co/basic-memory:latest ``` ### Run the Container ```bash docker run -d \ --name basic-container \ -p 8000:8000 \ -v ~/basic-memory-data:/app/data \ ghcr.io/basicmachines-co/basic-memory:latest ``` The server will be available at `http://localhost:8000/mcp`. ::note The `-v` flag mounts a local directory for persistent storage. Without it, your data will be lost when the container stops. :: ## Image Details ### Registry Images are published to GitHub Container Registry (GHCR): ```text ghcr.io/basicmachines-co/basic-memory ``` ### Available Tags | Tag | Description | | -------- | ------------------------------ | | `latest` | Latest stable release | | `0.19.0` | Specific version | | `0.19` | Latest patch for minor version | ### Architectures Multi-platform images are available for: - `linux/amd64` (Intel/AMD) - `linux/arm64` (Apple Silicon, ARM servers) Docker automatically pulls the correct architecture for your platform. ## Configuration ### Environment Variables | Variable | Default | Description | | --------------------------- | ------------------------ | --------------------------- | | `BASIC_MEMORY_HOME` | `/app/data/basic-memory` | Path to Basic Memory data | | `BASIC_MEMORY_PROJECT_ROOT` | `/app/data` | Root directory for projects | ### Volume Mounts Mount a local directory to persist data: ```bash docker run -d \ -v /path/to/local/data:/app/data \ -p 8000:8000 \ ghcr.io/basicmachines-co/basic-memory:latest ``` ### Port Configuration The container exposes port 8000 by default. Map to a different host port if needed: ```bash docker run -d \ -p 3000:8000 \ ghcr.io/basicmachines-co/basic-memory:latest ``` ## Docker Compose For more complex setups, use Docker Compose: ```yaml version: '3.8' services: basic-container: image: ghcr.io/basicmachines-co/basic-memory:latest container_name: basic-container ports: - "8000:8000" volumes: - ./data:/app/data environment: - BASIC_MEMORY_HOME=/app/data/basic-memory restart: unless-stopped healthcheck: test: ["CMD", "basic-memory", "--version"] interval: 30s timeout: 10s retries: 3 ``` Run with: ```bash docker compose up -d ``` ## Connecting to the Server ### MCP SSE Configuration Configure your MCP client to connect via SSE transport: ```json { "mcpServers": { "basic-memory": { "transport": { "type": "sse", "url": "http://localhost:8000/mcp" } } } } ``` ### Health Check Verify the server is running: ```bash curl http://localhost:8000/health ``` Or check container health: ```bash docker inspect --format='{{.State.Health.Status}}' basic-container ``` ## Running CLI Commands You can run Basic Memory CLI commands inside the container. Note that the first argument is the container name (`basic-container`) and the second is the CLI command (`basic-memory`): ```bash # Check version docker exec basic-container basic-memory --version # Check status docker exec basic-container basic-memory status # List projects docker exec basic-container basic-memory project list ``` ## Security The container runs as a non-root user (`appuser`) for security. Key security features: - Non-root execution (UID/GID 1000 by default) - No unnecessary packages installed - Health checks enabled - Slim base image (Python 3.12 slim-bookworm) ### Custom UID/GID Build with custom user IDs for permission compatibility: ```bash docker build --build-arg UID=1001 --build-arg GID=1001 -t basic-memory:custom . ``` ## Troubleshooting ### Permission Denied Errors If you see permission errors with mounted volumes: ```bash # Fix ownership on host sudo chown -R 1000:1000 /path/to/local/data # Or run with matching UID docker run --user $(id -u):$(id -g) ... ``` ### Container Exits Immediately Check the logs: ```bash docker logs basic-container ``` Common causes: - Port 8000 already in use - Volume mount path doesn't exist - Insufficient permissions ### SSE vs Stdio Transport ::warning The Docker image is configured for SSE transport only. It cannot be used as a stdio MCP server for Claude Desktop directly. :: For Claude Desktop integration, either: 1. Install Basic Memory locally via Homebrew or pip 2. Use the SSE transport configuration (if your Claude Desktop version supports it) ## Building from Source Clone the repository and build locally: ```bash git clone https://github.com/basicmachines-co/basic-memory.git cd basic-memory docker build -t basic-memory:local . ``` ## See Also - [Getting Started](https://docs.basicmemory.com/start-here/getting-started) - Local installation options - [CLI Reference](https://docs.basicmemory.com/reference/cli-reference) - Command line interface - [MCP Tools Reference](https://docs.basicmemory.com/reference/mcp-tools-reference) - Available MCP tools # AI-Friendly Documentation This documentation is optimized for AI agents. Get clean markdown through multiple methods - no HTML parsing required. ::tip **Want your AI to read the docs?** Just ask it to fetch the documentation: ```bash Fetch https://docs.basicmemory.com/llms.txt and read the Basic Memory documentation ``` Your AI will use its fetch tool to retrieve clean markdown directly - no browser or HTML parsing needed. :: --- ## Quick reference | Method | URL | Description | | ------------------- | ---------------------------------- | ---------------------------------- | | Index | `/llms.txt` | List of all pages with links | | Full docs | `/llms-full.txt` | Complete documentation in one file | | Raw markdown | `/raw/.md` | Any page as markdown | | Content negotiation | Any page + `Accept: text/markdown` | Returns markdown directly | --- ## Content negotiation The simplest method for AI agents. Add the `Accept: text/markdown` header to any documentation URL: ```bash curl -H "Accept: text/markdown" https://docs.basicmemory.com/start-here/what-is-basic-memory ``` Returns clean markdown directly - no redirects, no HTML parsing. **Example response:** ```bash # What is Basic Memory Basic Memory is a knowledge base that you and your AI assistant share... ``` --- ## llms.txt index The `/llms.txt` endpoint provides an index of all documentation pages with direct links to raw markdown: ```bash curl https://docs.basicmemory.com/llms.txt ``` **Example response:** ```bash # Basic Memory Documentation > Documentation for Basic Memory - a knowledge management system... ## Documentation Sets - [Basic Memory Complete Documentation](https://docs.basicmemory.com/llms-full.txt) ## Docs - [What is Basic Memory](https://docs.basicmemory.com/raw/start-here/what-is-basic-memory.md) - [Quickstart: Cloud](https://docs.basicmemory.com/raw/start-here/quickstart-cloud.md) ... ``` Use this as a starting point to discover available documentation. --- ## Full documentation Get the entire documentation in a single request: ```bash curl https://docs.basicmemory.com/llms-full.txt ``` This concatenates all pages into one markdown file - useful for loading complete context. --- ## Raw markdown paths Access any page directly as markdown using the `/raw/` prefix: ```bash # Pattern https://docs.basicmemory.com/raw/.md # Examples https://docs.basicmemory.com/raw/start-here/what-is-basic-memory.md https://docs.basicmemory.com/raw/reference/mcp-tools-reference.md https://docs.basicmemory.com/raw/concepts/knowledge-format.md ``` --- ## Usage patterns ### Progressive discovery Start with the index, then fetch specific pages: ```bash # 1. Get the index curl https://docs.basicmemory.com/llms.txt # 2. Fetch specific pages based on need curl https://docs.basicmemory.com/raw/start-here/quickstart-cloud.md ``` ### Full context loading Load everything at once for comprehensive context: ```bash curl https://docs.basicmemory.com/llms-full.txt ``` ### Content negotiation in code ```python import httpx # Just add the Accept header response = httpx.get( "https://docs.basicmemory.com/start-here/what-is-basic-memory", headers={"Accept": "text/markdown"} ) markdown = response.text ``` ```typescript // Same pattern in TypeScript const response = await fetch( "https://docs.basicmemory.com/start-here/what-is-basic-memory", { headers: { Accept: "text/markdown" } } ); const markdown = await response.text(); ``` --- ## Why AI-friendly docs? - **No parsing required** - Clean markdown, not HTML - **Structured discovery** - llms.txt provides an index - **Standard patterns** - Uses [llms.txt specification](https://llmstxt.org/){rel=""nofollow""} - **Content negotiation** - Same URLs work for humans and AI # v0.19.0 Migration Guide This guide covers configuration and behavior changes when upgrading from v0.18 to v0.19. For a user-friendly overview of new features, see [What's New in v0.19.0](https://docs.basicmemory.com/whats-new/v0.19.0). --- ## `write_note` is non-destructive by default `write_note` no longer silently overwrites existing notes. If a note already exists at the target path, the tool returns an error instead of replacing it. | | Before (v0.18) | After (v0.19) | | --------------------------- | --------------------------- | --------------------- | | Writing to an existing path | Silently overwrites | Returns an error | | Explicit overwrite | Not needed | Pass `overwrite=True` | | Incremental edits | `write_note` or `edit_note` | Use `edit_note` | This prevents accidental data loss when an AI assistant writes a note without realizing one already exists. **Restore old behavior:** Set `write_note_overwrite_default: true` in `~/.basic-memory/config.json`. --- ## Semantic search enabled by default Semantic search is now on out of the box. Embeddings are generated automatically on first startup — no opt-in or manual setup required. If `sqlite-vec` fails to load, search gracefully falls back to text-only mode. | | Before (v0.18) | After (v0.19) | | ------------------------- | --------------------------- | --------------------------- | | `semantic_search_enabled` | `false` | `true` | | Embedding generation | Manual | Automatic on first startup | | Install size | Smaller (no embedding deps) | Larger (includes fastembed) | ::note After upgrading to v0.19, run `bm reindex --embeddings` to generate vector embeddings for semantic search. This is a one-time operation for local projects. Cloud projects handle embedding generation automatically. :: **Restore old behavior:** Set `semantic_search_enabled: false` in config, or set `BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=false`. --- ## Frontmatter added on sync Files without YAML frontmatter (the metadata block at the top of a note) now get it added automatically during sync. This ensures all notes have proper metadata for search, permalinks, and schema resolution. | | Before (v0.18) | After (v0.19) | | ---------------------------- | -------------- | -------------------- | | `ensure_frontmatter_on_sync` | `false` | `true` | | Files without frontmatter | Left untouched | Frontmatter injected | **Restore old behavior:** Set `ensure_frontmatter_on_sync: false` in config. --- ## Project-prefixed permalinks Generated permalinks (permanent links to notes) now include the project slug by default, making cross-project references unambiguous. | | Before (v0.18) | After (v0.19) | | ---------------------------- | --------------------- | -------------------------- | | `permalinks_include_project` | `false` | `true` | | Example permalink | `docs/authentication` | `main/docs/authentication` | Existing permalinks without a project prefix still resolve correctly — resolution tries project-prefixed first, then falls back to bare path. **Restore old behavior:** Set `permalinks_include_project: false` in config. --- ## `build_context` defaults to JSON output `build_context` now returns JSON by default instead of text. The JSON response strips redundant fields for smaller, faster responses. All other tools still default to `"text"`. | | Before (v0.18) | After (v0.19) | | ------------------------------ | -------------- | -------------------- | | `build_context` default format | `"text"` | `"json"` | | Other tools default format | `"text"` | `"text"` (unchanged) | **Get text output:** Pass `output_format="text"` explicitly. --- ## `default_project_mode` removed The `default_project_mode` setting is no longer used. Use `default_project` as the fallback when no project is explicitly passed to a tool or command. Per-project routing (`set-cloud` / `set-local`) replaces the global mode toggle. --- ## Project config format changed Project configuration now uses structured entries with `path`, `mode`, and sync metadata. Legacy config formats (string-valued `projects`, `project_modes`, `cloud_projects`) are migrated automatically when Basic Memory loads your config and re-saved in the new format. ```json // Before (v0.18) { "projects": { "main": "/Users/you/basic-memory" } } // After (v0.19) { "projects": { "main": { "path": "/Users/you/basic-memory", "mode": "local" } } } ``` Legacy configuration keys (`project_modes`, `cloud_projects`, `default_project_mode`) can be safely removed from your config file after migration.