# Welcome **Basic Memory** is real memory for your AI — a knowledge base you own. Built-in AI memory is small, vendor-owned, and usually invisible. Basic Memory is large, structured, and inspectable: a knowledge graph written in plain Markdown. Open it in any editor, hand it to any AI tool, and keep it forever. ::note{icon="i-lucide-megaphone"} **New in v0.23:** the search release — reranking, Milvus, and a deadlock-free indexing core. The latest patch, v0.23.2, adds complete PostgreSQL full-text search and prevents case-duplicate folders. See [What's New in v0.23](https://docs.basicmemory.com/whats-new/v0-23) . Also new in Basic Memory Cloud: [Comments and Suggestions](https://docs.basicmemory.com/whats-new/comments-and-suggestions) and [Pocketbook (Interactive MCP App)](https://docs.basicmemory.com/whats-new/interactive-mcp-app) for ChatGPT and Claude. :: ::docs-video --- alt: What Basic Memory is, in one minute poster: /videos/posters/hero.png src: https://docs.basicmemory.com/videos/hero.mp4 --- ## Pick your path :::card-group ::::card --- icon: i-lucide-lightbulb title: What is Basic Memory? to: https://docs.basicmemory.com/start-here/what-is-basic-memory --- How persistent AI memory works, and why it beats chat history. :::: ::::card --- icon: i-lucide-cloud title: Quickstart — Cloud to: https://docs.basicmemory.com/start-here/quickstart-cloud --- Connect Basic Memory Cloud and create your first note in 2 minutes, no install required. :::: ::::card --- icon: i-lucide-terminal title: Quickstart — Local to: https://docs.basicmemory.com/start-here/quickstart-local --- Run the open-source version on your machine. Your files never leave your computer. :::: ::::card --- icon: i-lucide-map title: Set Up Local Projects to: https://docs.basicmemory.com/local/getting-started --- After installing locally: create projects and choose where your notes are saved on disk. :::: ::: ## Go deeper :::card-group ::::card --- icon: i-lucide-plug title: Connect your AI tools to: https://docs.basicmemory.com/integrations --- Claude, ChatGPT, Codex, Gemini, Cursor, VS Code, Obsidian, and more via MCP. :::: ::::card --- icon: i-lucide-users title: Teams to: https://docs.basicmemory.com/teams/about --- Share one knowledge base with your team — roles, invites, and shared projects. :::: ::::card --- icon: i-simple-icons-github title: Open source to: https://github.com/basicmachines-co/basic-memory --- Run locally, self-host, contribute, or just explore the code. :::: ::::card --- icon: i-lucide-bot title: AI-friendly docs to: https://docs.basicmemory.com/reference/llms-txt --- These docs support llms.txt, so your AI assistant can read them directly. :::: ::: :: # What is Basic Memory Basic Memory is real memory for your AI — a knowledge base you own. It stores notes as plain Markdown files, so your work stays readable, portable, and searchable. Instead of losing valuable insights in conversation history, you build a persistent knowledge base that every AI tool you use can read, write, and enhance — Claude, ChatGPT, Codex, OpenClaw, Hermes, and all your team's agents, working from one shared memory. :docs-video{alt="What Basic Memory is, in one minute" poster="/videos/posters/hero.png" src="https://docs.basicmemory.com/videos/hero.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 - **One memory for all your agents** - every tool reads the same knowledge base; with [Teams](https://docs.basicmemory.com/teams/about), so does your whole team --- ## 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 stores your notes as Markdown files and keeps a search index over them. Your AI assistant connects through MCP and 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 Tools] I[Search 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 WikiLink 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 LR E1[API Authentication] -->|implements| E2[API Security Spec] E1 -->|depends_on| E3[User Service] E1 -->|relates_to| E4[Token Refresh] E1 -->|decision| O1[Use JWT tokens] E1 -->|requirement| O2[Tokens expire in 24h] E1 -->|risk| O3[Rate limit logins] --- :: - **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 --> M[Matching notes] M --> B[build_context] B --> R[Related notes] R --> C[Full context] C --> A[AI answer] --- :: **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** - In the cloud, every note keeps full [version history](https://docs.basicmemory.com/cloud/file-history); locally, notes are plain files you can track with git - **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 notes] B --> C[You review & refine] 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 refinement over time Each conversation builds on previous context, creating increasingly refined understanding: ::mermaid --- code: | flowchart LR A[Conversation 1] --> B[Memory v1] B --> C[Conversation 2] C --> D[Memory v2 · refined] D --> E[Conversation 3] E --> F[Memory v3 · richer] --- :: The result: your AI gets smarter about *your* work with every interaction. --- ## One memory for your whole team Teams is the big unlock in Basic Memory Cloud: a shared workspace where one knowledge base serves you, your teammates, and every AI agent connected to it. A decision captured in one teammate's Claude session becomes context for another's Codex run. Everyone's agents read and write the same graph, so team knowledge compounds the same way personal knowledge does. See [Basic Memory Teams](https://docs.basicmemory.com/teams/about) for workspaces, roles, and invitations. --- ## 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** - Pull and push your notes to a local folder - **Team workspaces** - one shared knowledge base for your team and all their agents - **Snapshots** - Point-in-time backups, automatically 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` - List your projects - ...and many more **Compatible assistants:** - Claude Desktop - Claude Code - ChatGPT (Plus/Pro) - Google Gemini - Cursor - VS Code (Copilot Chat) - 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/local/getting-started --- Set up projects and choose where your notes are saved. ::: :::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. ::: :::card --- icon: i-lucide-users title: Teams to: https://docs.basicmemory.com/teams/about --- One shared memory for your team and every agent connected to it. ::: :: # 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. :docs-video{alt="Meet your workspace and write your first notes" poster="/videos/posters/docs-quickstart.png" src="https://docs.basicmemory.com/videos/docs-quickstart.mp4"} ::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 [basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=quickstart-cloud){rel=""nofollow""}. You'll need an active subscription to use the MCP endpoint. After sign-up, the app prepares your workspace and opens a seeded **Getting Started** project — a short tutorial you can read (and edit) in place. A floating onboarding guide walks you through the same steps as this page: connect your agent, write your first note, and watch it appear live. The in-app **Help Center** (account menu → Help) keeps the same walkthrough available anytime — your MCP endpoint, setup guides, and a quick test prompt. --- ## 2. Connect your AI assistant The published ChatGPT and Claude listings are the quickest setup paths. Choose your assistant, connect the listing, and complete the Basic Memory authorization flow. ### For Claude :docs-video{alt="Installing the Basic Memory Cloud connector in Claude and verifying it" poster="/videos/posters/docs-connect-claude.png" src="https://docs.basicmemory.com/videos/docs-connect-claude.mp4"} 1. Open the [Claude Directory](https://claude.ai/directory){rel=""nofollow""}, or go to **Settings → Customize → Connectors** and select **+**. 2. Search for **Basic Memory Cloud**, open the published connector, and select **Install**. 3. Complete authorization, then ask Claude to list your Basic Memory projects. The remote connector works across Claude web, desktop, mobile, Cowork, and Claude Code. Full walkthrough and manual connector fallback: [Claude Desktop](https://docs.basicmemory.com/integrations/claude-desktop). ### For ChatGPT :docs-video{alt="Installing the Basic Memory Cloud plugin in ChatGPT and using it in a chat" poster="/videos/posters/docs-connect-chatgpt.png" src="https://docs.basicmemory.com/videos/docs-connect-chatgpt.mp4"} ::steps ### Open the plugin Open [Basic Memory Cloud in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6a49590bf6348191a16c0b87ca6b01b4){rel=""nofollow""}, or select **Plugins** in the ChatGPT sidebar and search for **Basic Memory Cloud**. ### Connect Select **Connect** and complete the Basic Memory authorization flow. ### Start a chat Select **Try in chat**. In an existing conversation, type `@` and choose **Basic Memory Cloud**, or select **+ → More → Basic Memory Cloud**. :: See the [ChatGPT integration guide](https://docs.basicmemory.com/integrations/chatgpt) for the full walkthrough, managed-workspace notes, and manual custom MCP fallback. ::note If you need to configure a custom connector instead of using the stores, the remote MCP endpoint is `https://cloud.basicmemory.com/mcp` . The integration guides above have the current manual steps. :: ### For other assistants See the [Integrations](https://docs.basicmemory.com/integrations) 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** — something like: ```bash You have 1 project: - getting-started (default) ``` New accounts start with the seeded **Getting Started** tutorial project as the default. ::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 "My First Note" 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 "My First Note" 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 "My First Note" in your knowledge base. The note covers: - What Basic Memory is - How the knowledge format works - Key features like semantic search and relations ``` --- ## 5. View your notes Open [app.basicmemory.com/notes](https://app.basicmemory.com/notes){rel=""nofollow""} to see your new note in the sidebar. Notes written by your agent appear live — no refresh needed — and show up in the **Activity** view alongside your own edits. In a compatible MCP client, you can also ask `Open Basic Memory` to browse the interactive app directly in the conversation. See [Pocketbook](https://docs.basicmemory.com/cloud/mcp-app). **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 ::tip See the [Web App guide](https://docs.basicmemory.com/cloud/web-app) for the full tour — editing modes, keyboard shortcuts, projects, import, and settings. :: --- ## 6. Invite your team Basic Memory is better shared — one knowledge base for you, your teammates, and every agent connected to it. A decision captured in your Claude session becomes context for a teammate's Codex run. Invite people from **Settings → Members** in the web app — they get an email, sign in, and start working in the shared projects right away. See [Basic Memory Teams](https://docs.basicmemory.com/teams/about) for workspaces, roles, and seats. :docs-video{alt="Inviting a teammate by email, and what they see when they accept" poster="/videos/posters/docs-teams-invite.png" src="https://docs.basicmemory.com/videos/docs-teams-invite.mp4"} --- ## 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?" AI: [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" AI: [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 --- Edit locally and sync with push and pull. ::: :::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] --- :: --- ::tip **Prefer not to install anything?** Basic Memory Cloud connects your AI in about 2 minutes — [sign up at basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=quickstart-local){rel=""nofollow""} and follow the [cloud quickstart](https://docs.basicmemory.com/start-here/quickstart-cloud) . :: ## 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` accepts code from this third-party tap. On older Homebrew versions the command doesn't exist yet — just skip it. Details in [Local Installation](https://docs.basicmemory.com/local/local-install) . :: ### 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.12 or higher. Check with `python --version` . :: ### Verify installation ```bash basic-memory --version ``` You should see the installed version printed. If it's older than the [latest release](https://github.com/basicmachines-co/basic-memory/releases){rel=""nofollow""}, run `bm update` (`bm` is a short alias for `basic-memory`). --- ## 2. Configure Claude Desktop Add Basic Memory to your `claude_desktop_config.json`: ```json { "mcpServers": { "basic-memory": { "command": "uvx", "args": ["basic-memory", "mcp"] } } } ``` Installed with Homebrew? Use `"command": "basic-memory", "args": ["mcp"]` instead. **Restart Claude Desktop** after editing. Config file locations per platform and ENOENT fixes: [Claude Desktop → Local Setup](https://docs.basicmemory.com/integrations/claude-desktop#local-setup). --- ## 3. Verify the connection In Claude Desktop, open the **search and tools** menu in the chat input area. You should see Basic Memory tools listed. Ask Claude: ```bash List my projects ``` **Expected response:** ```bash You have 1 project: - main (default) - ~/basic-memory - 0 notes ``` --- ## 4. Create your first note Try this prompt: ```bash Create a note called "My First Note" with a summary of what Basic Memory does. ``` Claude will create a Markdown file at `~/basic-memory/My First Note.md`. **Example conversation:** ```bash You: Create a note called "My First Note" with a summary of what Basic Memory does. Claude: I'll create a note for you. [Uses write_note tool] Done! I've created "My First Note.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 ``` --- ## 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/My\ First\ Note.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/ ├── My First Note.md ├── projects/ │ └── API Design.md ├── research/ │ └── Database Optimization.md └── meetings/ └── Team Standup 2026-06-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. For more on projects and default-project configuration, see [Set Up Local Projects](https://docs.basicmemory.com/local/getting-started). --- ## Useful CLI commands ```bash # Check project index status basic-memory status # List all projects basic-memory project list # View project statistics basic-memory project info main # Import Claude conversations basic-memory import claude conversations # Import ChatGPT conversations basic-memory import chatgpt # Rebuild the search index basic-memory reindex ``` --- ## 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. ::: :: # Basic Memory v0.23 **Basic Memory v0.23** shipped in August 2026 ([v0.23.0 release notes](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.23.0){rel=""nofollow""}). The theme is search you can trust: semantic search matures with cross-encoder reranking and pluggable vector indexes, the indexing core stops deadlocking under concurrent writers, and a new inspector shows exactly why a search returned what it did. :docs-video{alt="Semantic search answering a plain-language question" poster="/videos/posters/docs-semantic-search.png" src="https://docs.basicmemory.com/videos/docs-semantic-search.mp4"} ## Search that ranks ### Opt-in cross-encoder reranking Vector and hybrid search can now rescore their leading candidates with a cross-encoder that reads the query and each candidate together: ```bash bm config set reranker_enabled true ``` The default provider runs a local FastEmbed ONNX model — no API key, no per-query cost — and LiteLLM connects hosted rerankers from Cohere, Jina, and Voyage. On the LoCoMo long-conversation retrieval benchmark, reranking improved mean reciprocal rank from 0.616 to 0.719 — a 17% improvement in how high the right note lands in the results. Reranking is off by default and downloads its local model on the first reranked search. See [Enable reranking](https://docs.basicmemory.com/concepts/semantic-search#enable-reranking). ### Pluggable vector indexes, with first-party Milvus Postgres deployments can now choose where vectors live: the new `semantic_vector_index` setting selects `pgvector` (the default) or Milvus, Milvus Lite, and Zilliz Cloud via `pip install "basic-memory[milvus]"`. A vector-index identity and readiness manifest lets search tell "no ready index" apart from "no results", and SQLite keeps sqlite-vec. After switching backends, rebuild with `bm reindex --embeddings`. See [Run Postgres with Milvus](https://docs.basicmemory.com/local/postgres-and-milvus). ### Embedding and full-text correctness A batch of fixes makes search results more trustworthy across the board: - Notes edited directly on disk are vector-embedded when the file watcher picks them up — no more waiting for a reindex - FastEmbed embeddings are L2-normalized for non-BGE models, so semantic scores no longer silently degrade - SQLite full-text search covers complete note content (previously text beyond \~6,000 characters was invisible), and non-Latin queries — CJK, Cyrillic, Greek, Hebrew, Arabic, and more — relax correctly instead of silently degrading - `bm reindex --embeddings` exits nonzero on real failures and reports which index it wrote ## Indexing that no longer deadlocks Underneath search, the indexing and persistence core is rebuilt around generation-versioned relations and observations with compare-and-swap publication. A stale indexing pass can never clobber or deadlock against a newer write, and observations and relations land with the accepted write instead of waiting for the next file re-index. The deadlock and lost-observation failures that appeared under concurrent multi-agent write loads are gone, and a one-time migration repairs historical duplicate observation rows left behind by the old behavior. ## See what search sees The new retrieval inspector answers "why did search return that?" from the command line: - **`bm inspect chunks `** shows a note exactly as the index sees it — its search rows, the vector chunks each row produced, and per-chunk ready/pending/stale/orphaned status — separating chunking problems from freshness problems in one command - **`bm inspect query ""`** captures an execution trace from the same search call that returns the results: full-text and vector candidates, fusion, filtering, reranking, and the final page window, with stable JSON output and `--show-misses` for rejected candidates See [Retrieval inspection commands](https://docs.basicmemory.com/reference/cli-reference#retrieval-inspection-commands). ## Team workspace push and pull for every member `bm cloud push` and `bm cloud pull` now work on Team workspaces for every member. Transfers run over the cloud's permissioned WebDAV API with per-project access checks — previously these commands required owner-only storage credentials, and every other member got a 403. Flags and semantics are unchanged: transfers stay additive (nothing is ever deleted) and `--on-conflict` still defaults to `fail`. See [Push and pull](https://docs.basicmemory.com/cloud/cloud-sync#push-and-pull-additive-git-style). ## A real operator front door Day-to-day operation gets first-class commands: - **`bm config`** — `list` effective settings with environment overrides marked, `get`, `set` (validated through the config model), and `unset`. See [Configuration commands](https://docs.basicmemory.com/reference/cli-reference#configuration-commands) - **Rich `bm tool` output** — interactive commands render panels, tables, and trees on a TTY; piped output stays machine-readable, with `--plain` and `--json` overrides - **`basic_memory_diagnostics`** — a new MCP tool that reports version and system info for bug reports - **`bm status`** — redesigned around project index status - **`bm hook`** — harness lifecycle capture moves into the package: SessionStart and PreCompact handling for Claude Code and Codex, bounded envelope capture into a local inbox, and `bm hook status`, `flush`, `install`, and `remove` for standalone setups. See [Harness Capture](https://docs.basicmemory.com/integrations/harness-capture) ## Cloud additions - **`bm cloud share`** — create, list, update, and revoke public share links from the CLI. See [Manage public share links](https://docs.basicmemory.com/cloud/cloud-cli#manage-public-share-links) - **`bm cloud prune`** — targeted cleanup that deletes cloud files matching this machine's `.bmignore`, without a full mirror sync. See [Prune newly ignored cloud files](https://docs.basicmemory.com/cloud/cloud-sync#prune-newly-ignored-cloud-files) - **Optional Redis read cache** — standalone MCP servers can cache reads via `pip install "basic-memory[redis]"` and `redis_url`. See [Optional Redis read cache](https://docs.basicmemory.com/reference/configuration#optional-redis-read-cache) ## v0.23.2 patch Released August 25, 2026 ([release notes](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.23.2){rel=""nofollow""}): - **No more case-duplicate folders** — when a note is written or moved into a directory that differs from an existing folder only by case (`schemas` vs. an existing `Schemas/`), it now lands in the existing folder instead of silently creating a sibling. Nested paths resolve per segment, unknown folders are still created as given, and resolution works identically for local and cloud projects. ## v0.23.1 patch Released August 25, 2026 ([release notes](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.23.1){rel=""nofollow""}), a fast-follow patch focused on PostgreSQL search: - **Postgres full-text search now covers complete note bodies** — previously only titles and capped content stems were indexed (unlike SQLite), so deep note content was unfindable. A migration backfills existing notes automatically; Boolean queries, apostrophes, and punctuated terms like `v0.13.0b2` all resolve correctly across the full text. - **Per-project search reindex no longer wipes other projects** — rebuilding one project's search index used to clear every project sharing the database. - **`#bm:links_to` directive** — end a list item with `#bm:links_to` to force a plain `links_to` link when prose before a `[[WikiLink]]` would otherwise be parsed as a relation type: `- Mother [[Alice]] #bm:links_to`. - **`bm update` output survives in-place upgrades** — status messages no longer crash after Homebrew or uv replaces the running install's files. - **`bm doctor` works under `BASIC_MEMORY_PROJECT_ROOT`** — doctor now creates its disposable check project under the configured root instead of failing on the nested-project guard. ## Upgrading Five database migrations run automatically on first start, including a one-time repair that removes duplicate observation rows and purges their stale full-text search entries. Most local setups need no manual action, but v0.23 also removes MCP tools and legacy API routes and changes several CLI, config, sync, and pagination contracts. ::note{icon="i-lucide-arrow-up-circle"} Before upgrading an integration or automation, read [Upgrade to v0.23](https://docs.basicmemory.com/whats-new/v0-23-upgrade) for the breaking changes, required actions, and known issues. :: For the complete list of changes, see the [Changelog](https://docs.basicmemory.com/whats-new/changelog) and the GitHub release notes for [v0.23.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.23.0){rel=""nofollow""}, [v0.23.1](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.23.1){rel=""nofollow""}, and [v0.23.2](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.23.2){rel=""nofollow""}. # Comments and Suggestions Basic Memory Cloud now has a review workflow built directly into the note editor. People and connected AI assistants can comment on a passage or suggest a precise change while keeping the original text available for review. :docs-video{alt="Suggesting edits and reviewing them with an AI assistant" poster="/videos/posters/docs-comments-suggestions.png" src="https://docs.basicmemory.com/videos/docs-comments-suggestions.mp4"} ::theme-image --- alt: A replacement suggestion shown inline with the original and proposed text class: mt-6 dark: /screenshots/cloud-app/critic-inline-replacement-dark.png light: /screenshots/cloud-app/critic-inline-replacement-light.png --- :: ## Review without rewriting Select text in the rich editor to start a review: - **Add comment** starts an attributed discussion without changing the passage. - **Suggest insertion** proposes new text after the selection. - **Suggest deletion** marks the selection for removal. - **Suggest replacement** keeps the original and proposed wording visible together. Each suggestion can be accepted or rejected individually. Comments can collect replies and be resolved without changing the note text. ## Follow every open item The note toolbar shows the number of unresolved comments and suggestions. Open it to see the review rail, where each thread stays aligned with its highlighted passage and shows its author, timestamp, replies, and available actions. :theme-image{alt="The review rail with a suggestion and comment beside their highlighted passages" dark="/screenshots/cloud-app/critic-review-rail-dark.png" light="/screenshots/cloud-app/critic-review-rail-light.png"} ## Review with an AI assistant Connected assistants now use the Cloud `review_note` MCP tool to add comments or insertion, deletion, and replacement suggestions without immediately rewriting the note. The same attributed threads appear in the Cloud editor and Pocketbook (the Interactive MCP App), where people and assistants can reply, resolve comments, and accept or reject suggestions. Cloud's `read_note`, `edit_note`, and `search_notes` tools are review-aware too: reads return clean prose and structured threads by default, ordinary edits preserve active review work and reject overlapping changes, and search hides CriticMarkup while reporting review-attention counts. Try asking: ```text Review this note with comments and suggestions. Keep the original prose in place so I can accept each change individually. ``` The assistant reads the current note first, anchors each item to exact prose, and uses revision checksums before accepting or rejecting a proposal. It should use `review_note` rather than writing CriticMarkup directly. ## Learn more ::card-group :::card --- icon: i-lucide-message-square-text title: Comments and Suggestions Guide to: https://docs.basicmemory.com/cloud/comments-and-suggestions --- Add comments, propose each kind of edit, and work through unresolved review items. ::: :::card --- icon: i-lucide-panels-top-left title: Pocketbook to: https://docs.basicmemory.com/cloud/mcp-app --- Review and edit notes without leaving a supported AI conversation. ::: :: # Pocketbook (Interactive MCP App) Basic Memory Cloud can now open **Pocketbook**, its Interactive MCP App, inside supported AI conversations. Browse your knowledge base, choose where the assistant writes, and work with notes without switching to a separate browser tab. :docs-video{alt="The Pocketbook inside a conversation" poster="/videos/posters/docs-pocketbook.png" src="https://docs.basicmemory.com/videos/docs-pocketbook.mp4"} The app works in **ChatGPT web and desktop** and **Claude web and desktop** through the hosted Basic Memory Cloud connector. :theme-image{alt="The Pocketbook open inside an AI conversation" dark="/screenshots/mcp-app/mcp-app-open-dark.png" light="/screenshots/mcp-app/mcp-app-open-light.png"} ## Your knowledge base inside the conversation The app provides three connected views: | View | What you can do | | ---------- | --------------------------------------------------------------------------------------------- | | **Notes** | Browse workspaces, projects, and folders; open notes; edit content; and toggle tasks | | **Search** | Search the current project or every project you can access and open a result in place | | **Graph** | Explore notes and relations, inspect connected notes, and move from the graph into the reader | The note reader renders Basic Memory Markdown, including wiki links, tables, code, Mermaid diagrams, observations, relations, and frontmatter. The embedded editor also supports comments and suggested changes. ## Give the assistant the right context Choose **Use this folder** to set the workspace, project, and directory where the assistant should write new notes for the conversation. Click a note title to prepare a prompt that identifies the note by workspace, project, and permalink; add your question or instructions, then send it. :theme-image{alt="A conversation prompt prepared with a Basic Memory note as context" dark="/screenshots/mcp-app/mcp-app-note-prompt-dark.png" light="/screenshots/mcp-app/mcp-app-note-prompt-light.png"} ## Open it naturally There is no separate app server or installation. Connect the hosted Cloud endpoint at `https://cloud.basicmemory.com/mcp`, then ask: ```text Open Basic Memory. Show my project notes. Open Basic Memory search for authentication. Show the knowledge graph around my architecture note. ``` Clients without interactive MCP App support can still use the normal Basic Memory data tools. ## Learn more ::card-group :::card --- icon: i-lucide-panels-top-left title: Pocketbook Guide to: https://docs.basicmemory.com/cloud/mcp-app --- See every view, writing-location controls, note prompts, editing, and review actions. ::: :::card --- icon: i-lucide-message-square-text title: Comments and Suggestions to: https://docs.basicmemory.com/cloud/comments-and-suggestions --- Review passages and accept proposed changes individually. ::: :::card --- icon: i-lucide-message-square title: ChatGPT to: https://docs.basicmemory.com/integrations/chatgpt --- Connect Basic Memory Cloud to ChatGPT. ::: :: # Introducing Teams **Basic Memory Teams** puts your whole team — and every AI agent they use — on one shared memory. A decision captured in one teammate's Claude session becomes context for another's Codex run. Invite teammates into a shared cloud workspace, work from the same projects, and everyone's agents reach the shared knowledge 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 personal and team workspaces in the app; local projects stay on your machine, reachable from the CLI and MCP alongside them. - **A shared workspace for the team** — projects everyone on the team can read and write. - **Roles** — five levels, from read-only **viewer** to **owner**, with **editor**, **user admin**, and **admin** tiers in between. - **Email invitations** — invite teammates by email; a seat is only used once they accept. - **One source of truth for every agent** — Claude, Codex, and the rest discover team projects across every workspace you can access, with no extra setup. ## Invite your team :docs-video{alt="Inviting a teammate by email, and what they see when they accept" poster="/videos/posters/docs-teams-invite.png" src="https://docs.basicmemory.com/videos/docs-teams-invite.mp4"} Invite members by email from **Settings → Members** — they sign in, pick up their role, and start working in the shared projects right away. Roles, statuses, and member management are covered in [Members and Roles](https://docs.basicmemory.com/teams/members-and-roles). ## 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: Changelog to: https://docs.basicmemory.com/whats-new/changelog --- What shipped in each release, including v0.22's team-safe cloud push and pull. ::: :: # Changelog Notable changes in each Basic Memory release, most recent first. For complete patch-by-patch notes, see [All releases](https://docs.basicmemory.com/#all-releases) below. --- ## v0.23 — Search that ranks and scales *[v0.23.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.23.0){rel=""nofollow""} · [v0.23.1](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.23.1){rel=""nofollow""} · [v0.23.2](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.23.2){rel=""nofollow""}* Semantic search takes a major step forward in v0.23. Opt-in cross-encoder reranking can rescore vector and hybrid candidates locally with FastEmbed or through LiteLLM, while Postgres deployments can move vector storage from pgvector to Milvus, Milvus Lite, or Zilliz Cloud. File-watcher writes now receive embeddings, non-BGE FastEmbed models are normalized correctly, SQLite full-text search covers complete long notes and relaxes non-Latin queries (CJK, Cyrillic, and other scripts), and reindex failures are reported honestly. The operator surface expands with **`bm inspect`** — a [retrieval inspector](https://docs.basicmemory.com/reference/cli-reference#retrieval-inspection-commands) that shows how the index sees a note (`bm inspect chunks`) and traces a query's retrieval stages (`bm inspect query`) — plus **`bm config`** for validated settings, **`bm hook`** for harness lifecycle capture, Rich interactive output for **`bm tool`**, a diagnostics MCP tool, a usable local Postgres path, Cloud share management, and targeted **`bm cloud prune`** cleanup. Team workspaces gain working **`bm cloud push`**/**`pull`**: transfers now run over the cloud's permissioned WebDAV API with per-project access checks, so every member can sync — previously these commands required owner-only storage credentials on Team workspaces. `list_directory` learns title and updated-time sorting for one-read folder navigation. The reliability tail is substantial too: incremental full-text reindexing clears stale rows, glob-filtered directory listings still traverse subfolders, root-level wikilinks resolve by filename with collision-safe case and separator aliases, transcript time ranges no longer become observation categories, and repeatedly selecting the current default project remains safe. Underneath those features, the indexing and persistence core moves to generation-versioned relations and observations, compare-and-swap materialization, consistent lock ordering, and batched resolution. Observations and relations now land with accepted writes, eliminating the deadlock and stale-projection failures that appeared under concurrent agent workloads. **The v0.23.1 patch** brings PostgreSQL full-text search to parity with SQLite by indexing complete note bodies, scopes search reindexing to the selected project, adds `#bm:links_to` for forcing an ambiguous prose wikilink to use the generic relation type, and hardens `bm doctor` and in-place `bm update` runs. **v0.23.2** prevents `write_note` and `move_note` from creating case-duplicate folders when a requested path uniquely matches an existing folder case-insensitively. This release also removes MCP tools and legacy API routes and changes several CLI, config, sync, edit, and pagination contracts. Read [What's New in v0.23](https://docs.basicmemory.com/whats-new/v0-23) for the highlights and [Upgrade to v0.23](https://docs.basicmemory.com/whats-new/v0-23-upgrade) before upgrading an integration or automation. --- ## August 2026 — Cloud review and Pocketbook *August 2026 · Basic Memory Cloud* Two new Cloud collaboration surfaces make it easier to work with people and AI assistants without leaving your notes or conversation: - **[Comments and Suggestions](https://docs.basicmemory.com/whats-new/comments-and-suggestions)** — add attributed comments or propose insertions, deletions, and replacements. The Cloud `review_note` MCP tool gives connected assistants the same reply, resolve, accept, and reject workflow with checksum conflict protection. - **[Pocketbook (Interactive MCP App)](https://docs.basicmemory.com/whats-new/interactive-mcp-app)** — browse, search, graph, read, edit, and review Basic Memory inside ChatGPT and Claude on web or desktop. Set an active writing folder or add a specific note to the conversation as context. AI-assisted review is integrated across the Cloud note tools. `read_note` returns clean prose, typed review threads, and a revision checksum; `edit_note` preserves open review work and blocks changes that overlap reviewed text; and `search_notes` keeps review markup out of results while reporting items that still need attention. See [Review with an AI assistant](https://docs.basicmemory.com/cloud/comments-and-suggestions#review-with-an-ai-assistant) for the complete workflow. These are Basic Memory Cloud product updates. The versioned Core release notes continue under [All releases](https://docs.basicmemory.com/#all-releases). --- ## v0.22 — Team-safe cloud push and pull *June 2026 · [v0.22.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.22.0){rel=""nofollow""} · [v0.22.1](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.22.1){rel=""nofollow""}* 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. They model `git push` / `git pull`: conflict-aware, with `--on-conflict` options (`fail`, `keep-cloud`, `keep-local`, `keep-both`) when a file differs on both sides. The mirror-style `bm cloud sync` command remains personal-only and exits with an error on team workspaces. Also in v0.22.0: search improvements, more capable `bm tool` and `bm status` commands, and a long list of MCP tool and embedding reliability fixes. See [Cloud Sync](https://docs.basicmemory.com/cloud/cloud-sync) for the full push/pull workflow. **The v0.22.1 patch** fixed first-run reliability and shipped a few MCP fixes and parity additions: - Fresh installs no longer get stuck when the projects table is empty — Basic Memory 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 --- ## v0.21 — Workspace-aware everywhere *May–June 2026 · [v0.21.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.21.0){rel=""nofollow""}* Every MCP tool and CLI command now routes through the same workspace/project model, and search and sync are noticeably faster. - **Cross-workspace discovery** — MCP project listing spans every accessible cloud workspace, so team projects show up without switching workspaces first, and `bm project list` includes projects from every workspace - **Create projects by workspace** — `create_memory_project(workspace=...)` from MCP, and `bm project add --visibility` for cloud projects - **Parameter aliases** — MCP tools accept training-data-friendly aliases (`q` / `search` / `text` for `query`, etc.) so assistants reach for them naturally - **`bm orphans`** — lists entities with no incoming or outgoing relations in the knowledge graph — notes not yet linked to anything - **Breaking change** — unquoted multi-word text before a wikilink no longer parses as a custom relation type. Use single-token types like `relates_to [[Target]]`, or quote multi-word types: `"relates to" [[Target]]` Notable patches: v0.21.5 fixed workspace/project routing for MCP, and v0.21.6 consolidated the satellite repositories into the main `basic-memory` tree and shipped a redesigned Claude Code plugin — a memory bridge with a guided setup interview, capture skills, and team workspace support — alongside Codex, Hermes, and OpenClaw integration packages. --- ## v0.20 — Auto-update *March 2026 · [v0.20.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.20.0){rel=""nofollow""}* A default-on auto-update system keeps CLI installs current, with a new **`bm update`** command (`--check` to check only). Install-source detection handles Homebrew and uv tool installs with the right upgrade flow for each, and MCP servers check silently in the background. Patches fixed API-key authentication for CLI cloud commands (previously only OAuth worked) and Homebrew update detection. --- ## v0.19 — Semantic search and schemas *March 2026 · [v0.19.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.19.0){rel=""nofollow""}* The biggest release of the docs era: - **Semantic vector search** for SQLite and Postgres with FastEmbed embeddings and hybrid keyword + vector fusion - **Schema system** — `schema_infer`, `schema_validate`, and `schema_diff` for validating and evolving note structure - **Per-project cloud routing** with API key authentication — route individual projects through cloud while others stay local - **JSON output mode** for MCP tools and CLI commands - **Project-prefixed permalinks** for unambiguous cross-project references - **`write_note` overwrite guard** — writing to an existing path returns an error unless `overwrite=true` - Upgraded to FastMCP 3.0 with tool annotations Upgrading from v0.18? The [v0.19.0 release notes](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.19.0){rel=""nofollow""} cover the configuration and behavior changes. --- ## All releases Full release notes for every version, from [GitHub](https://github.com/basicmachines-co/basic-memory/releases){rel=""nofollow""}: ::github-releases{:limit='30' repo="basicmachines-co/basic-memory"} :: # Upgrade to v0.23 v0.23 applies database migrations automatically, but integrations and operator scripts need review. Complete the actions below before relying on existing automation. ::note{icon="i-lucide-package-check"} Install **v0.23.2 or later** rather than stopping on v0.23.0. The two patch releases fix PostgreSQL search coverage and reindex safety, `bm doctor` and `bm update` reliability, and case-duplicate folder creation. :: ## Rebuild vectors after changing indexes If you change `semantic_vector_index` between `pgvector` and `milvus`, rebuild the configured vector store: ```bash bm reindex --embeddings ``` The default incremental run is enough. Before it finishes, vector search returns no results and hybrid search quietly serves full-text results only. See [Run Postgres with Milvus](https://docs.basicmemory.com/local/postgres-and-milvus) for the full switch and recovery procedure. Milvus requires the `basic-memory[milvus]` extra. Standalone Redis read caching requires `basic-memory[redis]`. Reranking remains off by default and downloads its local model on the first reranked search. ## Update CLI automation - `bm status` now reports project index status instead of the old sync-report tree. Scripts that parse its human output must switch to `--json` and the new shape. - `bm reindex --embeddings` exits nonzero when embedding fails. Treat that exit as a real failed rebuild instead of assuming success. - Interactive `bm tool` commands render Rich output on a TTY. Piped output remains machine-readable; pass `--json` when a script requires a stable contract. - The new top-level groups are `bm config` and `bm hook`. The top-level command set otherwise remains intact; `bm sync` was already absent in v0.22.1. ## Update MCP clients - The `canvas`, `cloud_info`, and `release_notes` MCP tools are removed. Obsidian Canvas generation and the API resource-write endpoints behind it are no longer available. - The ChatGPT compatibility tools `search` and `fetch` now accept OpenAI MCP clients only. Other clients must use `search_notes` and `read_note`. - `list_directory` is bounded and paginated. Consumers must use `page` and `page_size` instead of assuming one exhaustive response. It also supports title/update sorting, and `file_name_glob` now filters returned files without pruning traversal through nonmatching folders. - `replace_section` is heading-level-aware. By default it replaces the selected section through the next heading of the same or higher level, including nested subsections. Set `replace_subsections=false` to preserve nested subsections. - Ambiguous identifiers now raise an error instead of returning a best guess, and `write_note` rejects filename-convention twins instead of creating a duplicate. - FastMCP moves to `4.0.0b1` with MCP SDK v2. Downstream embedders pinned to FastMCP 3.x must upgrade with Basic Memory. ## Update HTTP clients Resource write endpoints and pre-v0.18.0 legacy routes are removed. Old clients that still call those routes receive `404` responses. The current v2 API remains the supported surface. ## Update configuration Basic Memory automatically migrates these config-file keys and legacy environment variables: | Old | New | | -------------- | --------------- | | `sync_delay` | `index_delay` | | `sync_changes` | `index_changes` | When old and new names are both set, the new name wins. `sync_thread_pool_size` and `sync_max_concurrent_files` are removed without aliases and are silently ignored in `config.json`. Remove them. `materialization_workers` is the nearest replacement for bounding local write materialization, but it is not a one-for-one thread-pool setting. ## Review behavior changes ::warning `bm cloud sync` is a one-way mirror and now deletes a previously synced cloud file when that file becomes ignored by `.bmignore` . Preview the exact deletion set with `bm cloud sync --name --dry-run` , or use the additive `bm cloud push` and `bm cloud pull` workflow. :: - Deleting the default project now chooses a new default instead of refusing the deletion. - `created` and `modified` frontmatter timestamps are authoritative. Historical values can change recency ordering after the first reindex. - Single transcript timestamps, spaced timestamp ranges, and Markdown checkbox markers are no longer indexed as observation categories. - Note-type filters are case-canonicalized, so values such as `Person` and `person` now match the same population. - Root-level wikilinks can resolve through a note's `.md` filename even when its title differs. A unique case-insensitive underscore/hyphen filename alias is tried only after exact identities; ambiguous aliases remain unresolved. ## Review late-release fixes Several v0.23 fixes require no migration or configuration change but affect operator expectations: - Incremental `bm reindex --search` reconciles stale full-text rows, including orphaned rows attached to unchanged files. - Re-selecting the current default project is idempotent and no longer leaves the workspace without a default. - Directory scans recheck a note's lineage and current path before applying a deletion, protecting notes accepted while a scan is running. - Standalone semantic note reads make fewer API requests, and the normal read-cache lifetime increases from 60 seconds to 5 minutes. - The Hermes integration preserves command and skill registration ownership. Follow the version-specific [Hermes patch guidance](https://github.com/basicmachines-co/basic-memory/blob/main/integrations/hermes/MONKEYPATCH.md){rel=""nofollow""}; modern Hermes versions must not replace the lifecycle-aware collector with the legacy workaround. ## Let migrations finish Six revisions run automatically when upgrading from v0.22.1 to the latest v0.23 patch: 1. A durable note-file vacate record distinguishes moves from byte-identical copies. 2. The semantic manifest gains vector-index identity and readiness state. 3. Relation-derived search refreshes become durable, retryable work items. 4. Relations and their search refreshes gain generation ownership. 5. A one-time repair removes duplicate observations and orphaned observation rows from full-text search. 6. On PostgreSQL, a child full-text index stores bounded, overlapping chunks of complete note bodies and backfills existing notes. SQLite needs no equivalent schema change because it already indexes full content. The observation repair is not reversible through a downgrade. Markdown files remain the source of truth and the index is rebuildable, but back up `memory.db` before the upgrade if you want a pre-migration database snapshot. Let the PostgreSQL migration and index build finish before testing deep full-text matches. ## Configure custom FastEmbed model prompts Basic Memory does not infer model-specific prompts for custom FastEmbed models. Configure the selected model's dimensions and any required document/query prefixes explicitly. For example, multilingual E5 uses 1024-dimensional vectors, `passage: `for indexed content, and `query: `for search queries: ```bash bm config set semantic_embedding_provider fastembed bm config set semantic_embedding_model intfloat/multilingual-e5-large bm config set semantic_embedding_dimensions 1024 bm config set semantic_embedding_query_prefix "query: " bm config set semantic_embedding_document_prefix "passage: " bm reindex --embeddings ``` The trailing spaces are meaningful and preserved. Rebuild embeddings after changing the model, dimensions, or either prefix so stored document vectors and new query vectors use the same contract. The symmetric default model (`bge-small-en-v1.5`) needs no prefixes. ## Review the v0.23.1 and v0.23.2 fixes The patch releases do not add breaking API changes, but they correct several behaviors worth knowing about: - **PostgreSQL searches complete note bodies.** v0.23.1 backfills the new full-text chunks automatically. Boolean queries and punctuated terms work across the complete text, not only titles and capped content stems. - **Reindexing is project-scoped.** Rebuilding search for one project no longer drops search rows belonging to sibling projects in the same database. The migration also repairs a missing shared search table if the old destructive path removed it. - **Use `#bm:links_to` to disambiguate prose.** End a list item with the directive when a single word before a wikilink is prose rather than a relation type: `- Mother [[Alice]] #bm:links_to`. The directive remains readable in Markdown but is removed from indexed content. - **`bm doctor` and `bm update` are safer.** Doctor waits for deferred materialization and can create its disposable project under `BASIC_MEMORY_PROJECT_ROOT`; update status output survives an in-place package replacement. - **Folder casing resolves consistently.** In v0.23.2, `write_note(directory="schemas")` and note moves land in an existing unique `Schemas/` folder instead of creating a case-duplicate sibling. Resolution happens segment by segment for nested folders and behaves the same locally and in Cloud. ## Known issues in v0.23 ### macOS file-identity edge cases Two open issues can produce duplicate entities for a single file on macOS: - **Unicode normalization (NFC/NFD):** APFS preserves whichever byte form a filename was written with, and some cross-platform sync tools (notably Syncthing) rewrite names to the other form. File-path lookups are byte-wise, so the same file can be indexed twice, accumulating `-1`-suffixed permalinks and breaking `edit_note` on the affected notes ([#1275](https://github.com/basicmachines-co/basic-memory/issues/1275){rel=""nofollow""}). - **Case-only renames:** on a case-insensitive APFS volume, renaming `config.md` to `Config.md` via `move_note` is refused as "destination already exists"; case-only folder renames can silently not change the folder's case on disk and leave duplicate index entries behind ([#1281](https://github.com/basicmachines-co/basic-memory/issues/1281){rel=""nofollow""}). Workarounds: avoid case-only and normalization-only renames from MCP tools (rename through an intermediate name instead), and run `bm reindex --full -p ` to collapse duplicates if they appear. The v0.23.2 folder-casing fix applies to the destination folders used by normal note writes and moves. It does not rename existing folders, merge existing case-variant siblings, or fix case-only and Unicode-normalization-only renames. ## Continue setup - [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search) — enable and tune reranking. - [Run Postgres with Milvus](https://docs.basicmemory.com/local/postgres-and-milvus) — start local Postgres, configure Milvus, and switch indexes safely. - [Configuration](https://docs.basicmemory.com/reference/configuration) — review every new v0.23 setting. - [CLI Reference](https://docs.basicmemory.com/reference/cli-reference) — update commands and output contracts. # Hermes Plugin The [hermes-basic-memory](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/hermes){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 ::warning **Managed install is currently blocked upstream.** This plugin ships `manifest_version: 2`, but `hermes plugins install` caps at version 1 on every released Hermes Agent (latest: v0.20.5 / `v2026.8.19`), so the command fails with *"requires manifest\_version 2, but this installer only supports up to 1."* The fix is [an open pull request](https://github.com/NousResearch/hermes-agent/pull/85893){rel=""nofollow""} that has not shipped in a release yet, so updating Hermes will not help. Until it lands, clone the repo and link the plugin in directly — the Hermes *runtime* loads manifest v2 without trouble; only the installer is capped: ```bash git clone https://github.com/basicmachines-co/basic-memory.git ln -snf "$PWD/basic-memory/integrations/hermes" ~/.hermes/plugins/basic-memory ``` :: ```bash hermes plugins install basicmachines-co/basic-memory/integrations/hermes ``` 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 current Hermes Agent releases — see the warning in the [full guide](https://docs.basicmemory.com/integrations/hermes) . :: ## 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: Plugin on GitHub to: https://github.com/basicmachines-co/basic-memory/tree/main/integrations/hermes --- Source code, issues, and contributing guide. ::: :: # Cloud App Updates Work with your knowledge base across multiple devices using cloud sync and storage. ## An interactive Basic Memory app in MCP conversations Compatible MCP clients can now open a focused Basic Memory workspace directly in the conversation. Browse projects and folders, search notes, follow wiki links, explore the knowledge graph, edit notes, toggle tasks, and review suggested changes without leaving the chat. Ask your assistant to “Open Basic Memory” or “Open Basic Memory search for…” to use it. See [Pocketbook](https://docs.basicmemory.com/cloud/mcp-app). ## Comments and suggested edits The Cloud editor now renders portable CriticMarkup as an actionable review workflow. Select text to add an attributed comment or propose an insertion, deletion, or replacement. The review rail keeps open items beside the document, with replies and resolve, accept, or reject actions. Connected agents can leave the same review markup, giving you a change-by-change approval flow instead of an immediate rewrite. See [Comments and Suggestions](https://docs.basicmemory.com/cloud/comments-and-suggestions). ## 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. - **Projects at a glance** — browse and manage every project in your workspace from 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, 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 save now creates a new version of a note automatically. Open **File history** on any note to step through its timeline, compare versions, and bring earlier content back — the fast, per-note answer to "I want to undo something," distinct from workspace-wide [Snapshots](https://docs.basicmemory.com/cloud/cloud-snapshots). See [File History](https://docs.basicmemory.com/cloud/file-history). ## 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. ::: :: # 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. ## Skill highlights | 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-continue** | Resume prior work — your AI rebuilds context from the knowledge graph | | **memory-reflect** | Your AI reviews conversations and saves the important parts as notes | …plus skills for capture, curation, schemas, defrag, metadata search, research, and more — see the full list on the [Agent Skills guide](https://docs.basicmemory.com/integrations/skills). ## Quick Install ```bash npx skills add basicmachines-co/basic-memory/skills ``` Works with Claude Desktop, Claude Code, Cursor, Windsurf, and other AI tools that support markdown-based skill files. Installation options, per-agent targeting, and usage examples are on the [Agent Skills guide](https://docs.basicmemory.com/integrations/skills). ## 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: Skills on GitHub to: https://github.com/basicmachines-co/basic-memory/tree/main/skills --- Source, contributing guide, and issue tracker in the basic-memory monorepo. ::: :: # OpenClaw Plugin The [openclaw-basic-memory](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/openclaw){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. :docs-video{alt="An agent recalling open tasks at session start, then writing back to the note" poster="/videos/posters/docs-openclaw-remembers.png" src="https://docs.basicmemory.com/videos/docs-openclaw-remembers.mp4"} ::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 - **Agent tools** — search, read, write, edit, schema validation, and project/workspace listing - **Slash commands** — `/remember`, `/recall`, `/tasks`, and more, plus one command per bundled skill - **Bundled skills** — workflow skills for notes, tasks, schemas, reflection, defrag, and more — no separate install needed - **Multi-project & cloud routing** — Access every project in your knowledge base with transparent local/cloud routing ## Quick Install :docs-video{alt="Installing the plugin and pointing it at a Basic Memory Cloud project" poster="/videos/posters/docs-openclaw-cloud.png" src="https://docs.basicmemory.com/videos/docs-openclaw-cloud.mp4"} ```bash openclaw plugins install @basicmemory/openclaw-basic-memory openclaw gateway restart ``` That's it. Installing enables the plugin and claims OpenClaw's `memory` slot automatically — no config editing required. Verify with `openclaw plugins doctor`. See the [OpenClaw plugin guide](https://docs.basicmemory.com/integrations/openclaw) for pointing it at an existing project. ## 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: Plugin on GitHub to: https://github.com/basicmachines-co/basic-memory/tree/main/integrations/openclaw --- Source code, issues, and contributing guide. ::: :: # AI-Friendly Docs ::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 ``` Every page is available as an `/llms.txt` index, a single-file `/llms-full.txt`, raw per-page markdown, and via content negotiation — the full details, URLs, and examples live on the [AI-Friendly Docs reference](https://docs.basicmemory.com/reference/llms-txt). ## 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. :docs-video{alt="What Basic Memory is, in one minute" poster="/videos/posters/hero.png" src="https://docs.basicmemory.com/videos/hero.mp4"} ::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 Open the [Claude Directory](https://claude.ai/directory){rel=""nofollow""}, search for **Basic Memory Cloud**, and select **Install**. Complete the Basic Memory authorization flow, then ask Claude to list your Basic Memory projects. The published remote connector works across Claude web, desktop, mobile, Cowork, and Claude Code. ::tip For the directory walkthrough and manual custom-connector fallback, see the [Claude Desktop Integration](https://docs.basicmemory.com/integrations/claude-desktop) guide. :: --- ## Setup with ChatGPT Open [Basic Memory Cloud in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6a49590bf6348191a16c0b87ca6b01b4){rel=""nofollow""}, select **Connect**, and complete the Basic Memory authorization flow. Select **Try in chat** to start a conversation with the app enabled. For the full Plugin-directory walkthrough, managed-workspace notes, and manual custom MCP fallback, see the [ChatGPT Integration](https://docs.basicmemory.com/integrations/chatgpt) guide. ::note For clients or advanced setups that require a server URL, the Basic Memory Cloud remote MCP endpoint remains: ```text https://cloud.basicmemory.com/mcp ``` :: --- ## 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 - **[Review changes](https://docs.basicmemory.com/cloud/comments-and-suggestions)** - Attributed comments and insertion, deletion, or replacement suggestions using portable CriticMarkup - **Collaborate with AI** - Connect an agent and watch it write alongside you in the same note - **Import data** - Bring in project ZIPs, Claude or ChatGPT exports, or memory-json from **Settings → Import** - **Manage projects** - Create, switch between, and manage projects - **Upload folders as ZIP** - Zip a folder and import it into any writable project — no CLI needed - **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) . :: Compatible MCP clients can also open a focused Basic Memory workspace inside the conversation for browsing, search, graph exploration, editing, and review. See [Pocketbook](https://docs.basicmemory.com/cloud/mcp-app). --- ## Command Line Tools The CLI tools are **optional** but enable advanced features like project management, file upload, and local file sync. **Requirements**: an up-to-date Basic Memory CLI (`bm update`). See [Local Installation](https://docs.basicmemory.com/local/local-install) for installation. ::note{icon="i-lucide-info"} **Why use the CLI?** - Manage multiple projects from terminal - Upload entire folders to cloud - Sync local files with push and pull - Automate workflows with scripts :: ### Quick Start ```bash # Authenticate — OAuth in the browser, validates your subscription bm cloud login # Check the connection: cloud host, API key status, OAuth token status bm cloud status # List projects across your workspaces bm project list # Create a cloud project (--cloud is required; add --default to make it the default) bm project add my-new-project --cloud ``` `bm cloud login` authenticates the CLI — it does **not** change project routing or start syncing files. Projects stay local unless you route them through cloud with `bm project set-cloud `; revert with `bm project set-local --local-path `. See [Local & Cloud Routing](https://docs.basicmemory.com/cloud/routing) for the full routing model. If you log in without an active subscription, you'll see **"Active subscription required"** — subscribe at [basicmemory.com/subscribe](https://basicmemory.com/subscribe?utm_source=docs&utm_medium=docs&utm_campaign=cloud-guide){rel=""nofollow""}. `bm cloud logout` removes your OAuth tokens. A saved API key is **not** removed — it keeps working for cloud-routed projects, so delete it separately if you need to revoke access. ::tip The full command walkthrough — sign-in options, API keys, workspaces, routing, sync, and snapshots — lives on the [Cloud CLI](https://docs.basicmemory.com/cloud/cloud-cli) page. :: --- ## Remove a Cloud Project and Its Data Cloud project removal keeps note files by default. Use `--delete-notes` when you also want to purge the project's active cloud storage: ::warning If the project has a configured local sync directory, `--cloud --delete-notes` also removes that local directory. Back up any local files you need before running the destructive command. Deletion is irreversible for active project storage; existing point-in-time snapshots may still contain historical copies until those snapshots are deleted or expire. :: ```bash # Stop tracking the project, but retain its cloud files bm project remove research --cloud # Remove the project and purge every object under its cloud storage prefix bm project remove research --cloud --delete-notes ``` Keep the explicit `--cloud` flag on the destructive `--delete-notes` command so the CLI also removes any configured local sync directory. Omitting `--cloud` from a cloud-routed project still purges hosted storage, but leaves the local sync copy intact. Hosted deletion is asynchronous: the project is hidden from cloud workspace operations when deletion is accepted, then a background job removes its database rows. A local routing or sync configuration entry can still appear as a config-only row in the combined `bm project list`; that does not mean the hosted project remains. With `--delete-notes`, the background job also removes indexed and unindexed objects under the project's exact storage prefix. The MCP `delete_project` tool provides the same hosted-storage purge with `delete_notes=true` when the MCP session is hosted or explicitly cloud-routed. From a local stdio MCP session, also pass `workspace` to route the request to that cloud workspace; `delete_notes=true` alone does not switch a local request to Cloud. MCP deletion does not remove a configured local sync directory, so use the explicit CLI command above when you need to delete both copies. The MCP response reports the pending deletion status and background job ID. --- ## Upload Files to Cloud ::note{icon="i-lucide-upload"} **No CLI needed for one-off uploads.** In the web app, **Settings → Import → Project ZIP** imports a zipped folder into any writable project — pick the team and target project, optionally a destination folder, and upload (ZIPs up to 100MB; markdown files are indexed automatically). The **Activity** view tracks the job after it starts. :: For scripted or repeated uploads, use `bm cloud upload` from the CLI: ```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 To edit both locally and in cloud, sync with push/pull — 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 snapshot contents bm cloud snapshot browse snap_abc123 --prefix notes/ # Restore a file from a snapshot bm cloud restore notes/example.md --snapshot 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 ``` Prefer the browser? Zip your `~/basic-memory` folder and import it via **Settings → Import → Project ZIP** — no CLI required. **Use when:** - You want to move to cloud-only - One-time migration is sufficient - Don't need ongoing local-cloud sync ### Option 2: Local File 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 your existing project as a cloud project with a local sync path bm project add main --cloud --local-path ~/basic-memory # First push (preview, then upload your local files) bm cloud push --name main --dry-run bm cloud push --name main # Ongoing: pull cloud changes down, push local changes up bm cloud pull --name main bm cloud push --name main ``` **Use when:** - You want to edit both locally (Obsidian, VS Code) and in cloud - Need offline access - Want changes to flow both ways ::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 --- Sync local files with push and pull. ::: :::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"} This page is the tour of the app itself. Writing and shortcuts live on the [Note Editor](https://docs.basicmemory.com/cloud/note-editor) page; working with agents lives on [AI Collaboration](https://docs.basicmemory.com/cloud/ai-collaboration). --- ## Layout The app is organized into three panes: | Pane | Contents | | --------------- | -------------------------------------------------------------------------------------------------------------------------- | | **Sidebar** | Pinned notes, your workspaces (personal and teams) with their project trees, search, Graph and Activity, your account menu | | **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 :docs-video{alt="Folders, search, and pinning in the note list" poster="/videos/posters/docs-navigating-notes.png" src="https://docs.basicmemory.com/videos/docs-navigating-notes.mp4"} ### 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 Open search from the sidebar (or **Cmd/Ctrl + K**) to search by title or content. Search spans **all your projects** by default — use the scope controls to narrow to a workspace, project, or folder. :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. --- ## Activity The **Activity** view in the sidebar keeps you aware of what's happening across the workspace — operations in progress (imports, indexing, large edits) and recent completed changes from every member **and connected agent**, with direct links to the affected notes. When your assistant writes a note over MCP, it shows up here live. :docs-video{alt="The Activity feed showing recent changes" poster="/videos/posters/docs-activity.png" src="https://docs.basicmemory.com/videos/docs-activity.mp4"} --- ## Explore the graph Open **Graph** in the sidebar for the Knowledge Graph, then pick a view: **Project** (cards), **Structured**, or **Explore** — a 2D/3D rendering of your knowledge graph, notes as nodes, relations as links. Drag to orbit, scroll to zoom, click a node to open the note, and filter by relation type or search for a note to focus on. :docs-video{alt="Focusing a node and its typed relations in the knowledge graph" poster="/videos/posters/docs-graph.png" src="https://docs.basicmemory.com/videos/docs-graph.mp4"} --- ## 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, download a project as a ZIP, or delete a project. To upload files, use **Upload Notes** from a project or folder's context menu in the sidebar, or import a zipped folder via **Settings → Import → Project ZIP**. :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 Bring existing content into a writable project from **Settings → Import** — pick the team, target project, and an optional destination folder. :docs-video{alt="Importing a ZIP of Markdown into a project" poster="/videos/posters/docs-import.png" src="https://docs.basicmemory.com/videos/docs-import.mp4"} | Import type | File | | --------------- | ------------------------------------------------------------------------------------ | | **Project ZIP** | A ZIP of a folder of Markdown files — directory structure is preserved (up to 100MB) | | **Claude** | `conversations.json` from a Claude export | | **ChatGPT** | The conversations JSON from a ChatGPT export (extract it from ChatGPT's export ZIP) | | **memory-json** | Entity/relation JSON exported from the memory-json MCP server | 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** (select a workspace first). 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) . :: --- ## Settings Access settings from the user menu (your avatar at the bottom 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, Look & Feel (mode, theme, note list), and editor preferences | | **Teams** | Your [teams and workspaces](https://docs.basicmemory.com/teams/about) at a glance | | **Members** | Invite and manage [team members, roles, and invitations](https://docs.basicmemory.com/teams/members-and-roles) | | **Billing** | Manage payment and [subscription seats](https://docs.basicmemory.com/teams/seats-and-billing) | | **Projects** | Create, download, and delete projects (team downloads require User Admin or above) | | **Import** | Import project ZIPs, Claude/ChatGPT exports, or memory-json | | **MCP** | Connect AI assistants via MCP | | **Notifications** | Choose what the app notifies you about | | **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) per workspace | | **Audit Logs** | Review workspace activity (team admins) | | **Shared Notes** | Manage public [share links](https://docs.basicmemory.com/cloud/shared-notes) for your notes | | **Version** | App version information | ::note Sections like **Members** , **Billing** , **Snapshots** , and **Audit Logs** 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 inside each project that matches how you think: ```bash my-project/ ├── 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. --- ## Next Steps ::card-group :::card --- icon: i-lucide-pencil title: Note Editor to: https://docs.basicmemory.com/cloud/note-editor --- Editing modes, formatting, drafts, and keyboard shortcuts. ::: :::card --- icon: i-lucide-sparkles title: AI Collaboration to: https://docs.basicmemory.com/cloud/ai-collaboration --- Connect an agent and watch it write alongside you. ::: :::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 --- Sync local files with push and pull to edit locally and in cloud. ::: :: # Note Editor Notes in the [web app](https://docs.basicmemory.com/cloud/web-app) open ready to edit, and everything you write is saved as plain Markdown. --- ## Editing modes The app has three modes, switchable from the toolbar or with keyboard shortcuts: :docs-video{alt="Switching between the three editing modes" poster="/videos/posters/docs-note-editor.png" src="https://docs.basicmemory.com/videos/docs-note-editor.mp4"} | 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. :docs-video{alt="Showing and editing a note's frontmatter" poster="/videos/posters/docs-frontmatter.png" src="https://docs.basicmemory.com/videos/docs-frontmatter.mp4"} :theme-image{alt="Edit Frontmatter" dark="/screenshots/cloud-app/v2-frontmatter-dark.png" light="/screenshots/cloud-app/v2-frontmatter-light.png"} --- ## Review notes without overwriting them Select text in the rich editor to add a comment or suggest an insertion, deletion, or replacement. Review items stay with the Markdown note so people and connected assistants can discuss and accept changes individually. See [Comments and Suggestions](https://docs.basicmemory.com/cloud/comments-and-suggestions) for the complete web app, Pocketbook, and CriticMarkup workflow. --- ## Drafts Start typing in an empty editor — or press **Cmd/Ctrl + N** for a new note — to create a **draft**. - A new draft saves into the current project automatically once it has meaningful content (a title, tags, or body text). - Use **Save Draft** in the command palette to save immediately without waiting. - 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. :: --- ## 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 you can **Rename Note** and **Copy link for your agent**; the command palette also offers **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). --- ## Keyboard Shortcuts :docs-video{alt="The command palette" poster="/videos/posters/docs-command-palette.png" src="https://docs.basicmemory.com/videos/docs-command-palette.mp4"} 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"} --- ## Next Steps ::card-group :::card --- icon: i-lucide-sparkles title: AI Collaboration to: https://docs.basicmemory.com/cloud/ai-collaboration --- Connect an agent and watch it write alongside you. ::: :::card --- icon: i-lucide-message-square-text title: Comments and Suggestions to: https://docs.basicmemory.com/cloud/comments-and-suggestions --- Review notes with comments and proposed edits. ::: :::card --- icon: i-lucide-history title: File History to: https://docs.basicmemory.com/cloud/file-history --- Every save is a version — browse, compare, and merge back. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- The semantic structure for observations and relations. ::: :: # AI Collaboration The [web app](https://docs.basicmemory.com/cloud/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. It's the same shared memory your agents reach over MCP, with a front-row seat. --- ## 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"). ## Work on a selection Select text in the editor and it appears in the agent pane, where you can send a request about it — a rewrite, a summary, or a next step. The agent's changes stream into the note as it works. If you want to review changes before applying them, ask the agent to leave **comments and suggestions** instead of rewriting the passage. Cloud-connected assistants use the `review_note` MCP tool to create attributed threads; Basic Memory renders them in the review rail, where you can reply to comments, resolve threads, and accept or reject each proposed edit. See [Comments and Suggestions](https://docs.basicmemory.com/cloud/comments-and-suggestions). :docs-video{alt="Suggesting edits and reviewing them with an AI assistant" poster="/videos/posters/docs-comments-suggestions.png" src="https://docs.basicmemory.com/videos/docs-comments-suggestions.mp4"} ## 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. ## Send a note to any agent Every note has a stable link your agents can use: open the `⋮` menu and choose **Copy link for your agent**, then paste it into any connected AI tool — "add a summary section to this note" — and watch the change land live. ## See what your agents did Agent writes over MCP appear in the [**Activity** view](https://docs.basicmemory.com/cloud/web-app#activity) alongside your teammates' edits — with direct links to the affected notes. On a team, everyone's agents share the same knowledge base; see [Basic Memory Teams](https://docs.basicmemory.com/teams/about). --- ## The loop in practice 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 Each cycle makes your AI better at answering from your actual knowledge. --- ## Next Steps ::card-group :::card --- icon: i-lucide-bot title: AI Assistant Guide to: https://docs.basicmemory.com/reference/ai-assistant-guide --- Teach your assistant when and how to use Basic Memory. ::: :::card --- icon: i-lucide-users title: Teams to: https://docs.basicmemory.com/teams/about --- One shared memory for your team and every agent connected to it. ::: :::card --- icon: i-lucide-pencil title: Note Editor to: https://docs.basicmemory.com/cloud/note-editor --- Editing modes, drafts, and keyboard shortcuts. ::: :: # 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: - **Per-project routing** - Route individual projects through cloud with `bm project set-cloud`; the rest stay local - **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 Personal and Team workspaces alike - **Offline access** - Work locally, sync when ready ### The sync commands | 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 prune` | cloud cleanup | Deletes cloud files matching this machine's `.bmignore` | ✅ | ❌ | **`push` and `pull` are the standard workflow.** They are additive — they never delete files on the destination — and conflict-aware, so they are safe everywhere, including shared Team workspaces where a mirror operation could delete a teammate's files. `sync` is a mirror operation: your local tree becomes authoritative and cloud files missing locally get deleted. That can be useful on a Personal workspace when local is the single source of truth, but it is blocked on Team workspaces, where it exits early with a clear error pointing you at `push`/`pull`. In v0.23, this deletion set also includes previously synced files that now match `.bmignore`. --- ## 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?utm_source=docs&utm_medium=docs&utm_campaign=cloud-sync){rel=""nofollow""} - **Basic Memory CLI**: See [Install Basic Memory locally](https://docs.basicmemory.com/local/local-install) 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 want changes to flow both ways (pull cloud changes down, push local changes up) - You're working with large knowledge bases - You want offline access with periodic syncing **Alternatives to sync:** - **Web App**: Upload and edit files in the [Cloud web app](https://docs.basicmemory.com/cloud/web-app) - **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 only on your machine (the default for `bm project add`) **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 cloud sync-setup research ~/Documents/research bm cloud sync-setup work ~/work-notes # temp needs no setup — it stays cloud-only # Now you can sync individually: bm cloud pull --name research bm cloud pull --name work ``` **What happens under the covers:** - Config stores each project as an entry with a `local_sync_path` in `~/.basic-memory/config.json` - Rclone transfers files using a tenant-scoped remote per workspace (`basic-memory-cloud` for your Personal workspace) - Projects can live anywhere on your filesystem --- ## Quick Start ### 1. Sign in to Cloud Authenticate the CLI: ```bash bm cloud login ``` **What this does:** 1. Opens browser to Basic Memory Cloud authentication page 2. Stores authentication token 3. Validates your subscription status Login doesn't change project routing or start syncing — projects stay local unless you route or sync them explicitly. ### 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 a tenant-scoped rclone remote for the workspace (`basic-memory-cloud` for your Personal workspace) ::note **Team workspaces skip this step.** `bm cloud setup` provisions the rclone remote used by Personal-workspace transfers. On a Team workspace, `push` and `pull` run over the cloud's permissioned WebDAV API instead — no rclone remote and no storage credentials — and every request is authorized against your access to that specific project: read access is enough to `pull` , edit access is required to `push` . New in v0.23; previously Team push/pull required owner-only storage credentials, so most members couldn't run them at all. :: ### 3. Add Projects with Sync Create projects with optional local sync paths: ```bash # Create cloud project without local sync bm project add research --cloud # Create cloud project WITH local sync bm project add research --cloud --local-path ~/Documents/research # Or configure sync for an existing cloud project bm cloud sync-setup research ~/Documents/research ``` ### 4. Pull the Project Down Fetch the cloud copy into your local directory. **Preview with `--dry-run` first:** ```bash # Step 1: Preview what would transfer bm cloud pull --name research --dry-run # Step 2: Fetch cloud files into your local directory bm cloud pull --name research ``` `pull` is additive — it fetches new and changed files without deleting anything local. ### 5. Daily Workflow Pull before you start, edit locally, push when you're done: ```bash # Fetch changes made in the web app, by MCP tools, or by teammates bm cloud pull --name research # ... edit files locally ... # Upload your changes to the cloud bm cloud push --name research ``` **What happens on `push`:** 1. New and changed local files transfer to cloud 2. If a file differs on both sides, the command aborts and lists the conflicts 3. The cloud instance detects the new files and reindexes them automatically ::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: - `OAuth: token valid` - `Cloud connected` --- ## 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 sync` | Local → Cloud | One-way mirror, make cloud match local (Personal only) | | `bm cloud prune` | Cloud cleanup | Delete files that match this machine's `.bmignore` (Personal only) | | `bm cloud check` | Verify | Check if files match (Personal only) | ### 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`. The transport depends on the workspace, but the commands and flags are identical. Personal-workspace transfers run through the tenant-scoped rclone remote configured by `bm cloud setup`. Team-workspace transfers (v0.23+) run over the cloud's WebDAV API, where each request is checked against your access to that project — members with read access can `pull`, members with edit access can `push`, and no `bm cloud setup` is needed. **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. Use `--dry-run` to preview differences before transferring ( `bm cloud check` is Personal-only). :: ### 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). ::warning Starting in v0.23, adding a pattern to `.bmignore` makes a previously synced matching file eligible for deletion from cloud on the next `bm cloud sync` . Preview with `bm cloud sync --name research --dry-run` before applying a new ignore rule. Use additive `push` / `pull` if you do not want local deletions or ignore changes propagated. :: ### Prune newly ignored cloud files Use `prune` when you want only the `.bmignore` cleanup without a full mirror sync: ```bash # Show the exact remote paths that match this machine's ignore file bm cloud prune --name research --dry-run # Show the paths again, then ask for confirmation before deletion bm cloud prune --name research # Skip the confirmation prompt after reviewing a dry run bm cloud prune --name research --yes ``` `prune` can run without a configured local sync directory because it inspects remote paths against `~/.basic-memory/.bmignore`. It is Personal-workspace-only and permanently deletes only the exact paths shown in its preview. ### Preview Changes (Dry Run) ```bash bm cloud pull --name research --dry-run bm cloud push --name research --dry-run ``` Shows what would transfer without actually syncing. ### Verify Integrity ```bash bm cloud check --name research ``` Compares file checksums without making changes (Personal workspaces only). --- ## Multiple Projects ### Syncing Multiple Projects ```bash # Setup multiple projects bm project add research --cloud --local-path ~/Documents/research bm project add work --cloud --local-path ~/work-notes bm project add personal --cloud --local-path ~/personal # Daily workflow: pull, edit, push bm cloud pull --name research bm cloud pull --name work bm cloud pull --name personal # ... edit locally ... bm cloud push --name research bm cloud push --name work bm cloud push --name personal ``` ### Mixed Usage ```bash # Projects with sync bm project add research --cloud --local-path ~/Documents/research bm project add work --cloud --local-path ~/work # Cloud-only projects bm project add archive --cloud bm project add temp-notes --cloud # Sync only the configured ones bm cloud pull --name research bm cloud pull --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 # Hidden files and version control .* .git # Python __pycache__ *.pyc .venv # Node.js node_modules # Basic Memory internals *.db *.db-shm *.db-wal config.json # Editors and OS files .obsidian .DS_Store *.tmp ``` ::note Basic Memory also respects `.gitignore` files in your projects. Use `.bmignore` for global patterns across all projects. :: ::warning Ignore rules are part of one-way mirror retention behavior. A file that was uploaded before you added a matching `.bmignore` rule is deleted by `bm cloud sync` , or on demand by `bm cloud prune` . Always preview either operation before changing retention-sensitive patterns. :: --- ## Troubleshooting ### Authentication Issues **Problem:** Authentication failed or Invalid token **Solution:** ```bash bm cloud logout bm cloud login ``` ### Push or Pull Reports Conflicts **Problem:** "pull aborted: N file(s) differ between local and cloud" **Solution:** This is the conflict guard working as intended. Preview the differences, then choose what survives: ```bash bm cloud pull --name research --dry-run bm cloud pull --name research --on-conflict keep-both ``` ### Project Not Configured for Sync **Problem:** "Error: Project 'research' has no local sync path configured" **Solution:** ```bash bm cloud sync-setup research ~/Documents/research bm cloud pull --name research ``` ### Workspace Is Not Set Up for Sync **Problem:** "Workspace '...' is not set up for sync." **Solution:** A Personal workspace's rclone remote hasn't been provisioned yet: ```bash bm cloud setup ``` Team workspaces never need `bm cloud setup` — their `push`/`pull` run over the permissioned WebDAV API, so this error only appears on the Personal path. --- ## Sign out ```bash bm cloud logout ``` Logout removes your stored OAuth tokens (a saved API key survives and keeps routing cloud projects). It doesn't change project routing — to route a project locally again, use `bm project set-local --local-path `. --- ## 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**: Personal transfers use scoped S3 credentials (read-write to your tenant only); Team transfers use your OAuth session over WebDAV with per-project access checks - **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 Setup ```bash bm project add --cloud # Create cloud project (no sync) bm project add --cloud --local-path # Create with local sync bm cloud sync-setup # Add sync to an existing cloud project ``` Full project and auth commands (list, remove, login, status): [CLI Reference](https://docs.basicmemory.com/reference/cli-reference). ### File Synchronization ```bash # Standard workflow (Personal + Team) bm cloud pull --name # Fetch cloud changes (additive) bm cloud push --name # Upload local changes (additive) bm cloud pull --name --dry-run bm cloud push --name --dry-run bm cloud pull --name --on-conflict keep-both # One-way mirror (local → cloud, Personal only) bm cloud sync --name bm cloud sync --name --dry-run # Targeted deletion of cloud files matching ~/.basic-memory/.bmignore bm cloud prune --name --dry-run bm cloud prune --name # Integrity check (Personal only) bm cloud check --name # List remote files bm project ls --name ``` --- ## Summary **Basic Memory Cloud uses project-scoped sync:** 1. **Sign in** - `bm cloud login` 2. **Install rclone** - `bm cloud setup` (Personal workspaces; Team push/pull needs no setup) 3. **Add projects with sync** - `bm project add research --cloud --local-path ~/Documents/research` 4. **Preview the first pull** - `bm cloud pull --name research --dry-run` 5. **Pull the project down** - `bm cloud pull --name research` 6. **Daily workflow** - pull, edit locally, then `bm cloud push --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 (additive transfers, conflict guard) - 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. ::: :: # 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""}. :docs-video{alt="Creating a snapshot, deleting a note, and restoring it from the snapshot" poster="/videos/posters/docs-snapshots.png" src="https://docs.basicmemory.com/videos/docs-snapshots.mp4"} ### View Snapshots Go to **Settings → Snapshots** and select a workspace to see its 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. On the snapshot's row, click **Restore** 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" ``` The command confirms the snapshot with its ID (a UUID), creation time, and description. ### List Snapshots ```bash bm cloud snapshot list ``` Lists your snapshots in a table: ID, description, whether it was automatic, and creation time. ### View Snapshot Details ```bash bm cloud snapshot show ``` ### Browse Snapshot Contents View files in a snapshot without restoring: ```bash bm cloud snapshot browse ``` Lists the files in the snapshot with their sizes. Paths start with the project name (e.g. `my-project/notes/ideas.md`). Filter by path: ```bash bm cloud snapshot browse --prefix my-project/notes/ ``` ### Restore Files Restore paths start with the project name, exactly as `snapshot browse` shows them. Restore a specific file: ```bash bm cloud restore my-project/notes/important.md --snapshot ``` Restore an entire folder: ```bash bm cloud restore my-project/research/ --snapshot ``` ### Delete a Snapshot ```bash bm cloud snapshot delete ``` ::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. Confirm the exact path exists in the snapshot: `bm cloud snapshot browse --prefix ` 2. Make sure the path is project-prefixed, exactly as browse shows it (e.g. `my-project/notes/file.md`) 3. Re-run the restore with the corrected path — files always restore to their original location --- ## 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 --- Sync local files with push and pull. ::: :::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 The Basic Memory web app ships with a set of curated color themes, each with coordinated palettes for light and dark mode. Pick both under **Settings → General**, in the **Look & Feel** card. :docs-video{alt="Choosing a theme and color mode" poster="/videos/posters/docs-themes.png" src="https://docs.basicmemory.com/videos/docs-themes.mp4"} --- ## Color mode Use the **Mode** control to choose **Light**, **Dark**, or **System**. System follows your operating system's preference and switches automatically. --- ## Choosing a theme The **Theme** control shows a row of color swatches — each previews a theme's palette, labeled with the theme's name. Click a swatch to apply it instantly, no save needed. - Themes and mode are independent: every theme has coordinated colors for both light and dark, so switching mode keeps your theme. - Theme choices are saved locally in this browser — pick your theme on each device you use. - The theme applies across the whole app — sidebar, editor, preview, and settings. Try a few — clicking around is faster than reading about them. --- ## Next Steps ::card-group :::card --- icon: i-lucide-layout-panel-left title: Web App Guide to: https://docs.basicmemory.com/cloud/web-app --- The full tour — editing modes, shortcuts, projects, and settings. ::: :::card --- icon: i-lucide-keyboard title: Keyboard Shortcuts to: https://docs.basicmemory.com/cloud/note-editor#keyboard-shortcuts --- Switch view modes and run commands without the mouse. ::: :: # 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 Keys are grouped by workspace. Click **Create Key** next to the workspace you want the key for (Personal or a Team), then confirm with **Create**. ### Name Your Key Enter a descriptive name like "Claude Desktop" or "Work Laptop" ### 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. Each key belongs to a specific workspace — anyone with the key can access that workspace. Never commit keys to version control or share them publicly. :: --- ## Using API Keys ### With Claude Desktop Claude Desktop connects to Basic Memory Cloud through its **Connectors** OAuth flow, not an API key — see [Claude Desktop](https://docs.basicmemory.com/integrations/claude-desktop). If you specifically need bearer-token auth (for example on an account without browser OAuth), bridge through a stdio proxy in `claude_desktop_config.json`: ```json { "mcpServers": { "basic-memory": { "command": "npx", "args": [ "mcp-remote", "https://cloud.basicmemory.com/mcp", "--header", "Authorization: Bearer bmc_your_key_here" ] } } } ``` ### With Codex CLI Add to `~/.codex/config.toml`: ```toml [mcp_servers.basic-memory] url = "https://cloud.basicmemory.com/mcp" bearer_token_env_var = "BASIC_MEMORY_API_KEY" ``` Full walkthrough (key export, shell setup): [Codex integration](https://docs.basicmemory.com/integrations/codex). 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 for the CLI to use: ```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" ``` The key authenticates cloud-routed projects — for routing projects through cloud (`bm project set-cloud` / `set-local`), see [Local & Cloud Routing](https://docs.basicmemory.com/cloud/routing). --- ## 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" - **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 | | Access | Full workspace access (project-scoped keys available via API) | Full account access | 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. ::: :: # Shared Notes Shared Notes are **public** shares: publish a single note as a read-only web page that anyone with the link can read, no account required — handy for a document, a spec, or a writeup you want to show people outside your workspace. ::tip **Sharing with your team doesn't need a link.** Teammates see notes automatically through [team projects](https://docs.basicmemory.com/teams/team-projects) — everyone in the workspace (or everyone invited to an invite-only project) already has them. Use Shared Notes only for readers outside Basic Memory. :: :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**. :docs-video{alt="Sharing a note as a public link, viewing it logged out, and revoking it" poster="/videos/posters/docs-shared-notes.png" src="https://docs.basicmemory.com/videos/docs-shared-notes.mp4"} ::theme-image --- alt: Share note action in the note menu class: mt-6 dark: /screenshots/cloud-app/v2-shared-note-button-dark.png light: /screenshots/cloud-app/v2-shared-note-button-light.png --- :: A dialog opens with a warning — "Anyone with this link can view the note without signing in." — and a **Create Link** button. Click it to generate the public link, then **Copy** to copy it. :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/note-editor#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, with a **Readable/Full** toggle to switch between a comfortable reading width and the full content width. 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 in the workspace — in a team workspace, that includes links created by teammates. :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"} | Action | Where | What it does | | ------------------------ | ----------------------- | ------------------------------------------------------------ | | **Sharing link** | Note's `⋮` menu | View and copy the existing public link | | **Disable** / **Enable** | Settings → Shared Notes | Pause a link without deleting it, then turn it back on later | | **Stop sharing** | Both | 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), any member except a **Viewer** — Editors, User Admins, Admins, and Owners — can create, disable, and revoke share links. 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. ::: :: # 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. :docs-video{alt="Opening File history and restoring an earlier version of a note" poster="/videos/posters/docs-file-history.png" src="https://docs.basicmemory.com/videos/docs-file-history.mp4"} ::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 workspace-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. :docs-video{alt="Creating a snapshot and restoring a deleted note from it" poster="/videos/posters/docs-snapshots.png" src="https://docs.basicmemory.com/videos/docs-snapshots.mp4"} ::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, automatic vs manual, CLI options — 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 (a UUID) — 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 # List a specific folder bm cloud snapshot browse --prefix my-project/notes/ # Show snapshot metadata bm cloud snapshot show ``` The web app's snapshot browser does the same thing under **Settings → Snapshots** — select the workspace, then the 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 restore my-project/notes/important.md --snapshot ``` Or in the web app: browse the snapshot, find the file, choose **Restore**. #### A folder ```bash bm cloud restore my-project/research/ --snapshot ``` 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 restore / --snapshot ``` ::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 --prefix my-project/ bm cloud restore my-project/ --snapshot ``` Restore recreates the project entry automatically if it's missing — after restoring, open **Settings → Projects** to confirm the project reappeared. --- ## What if the snapshot is too old? If no snapshot predates the loss — the content was created and deleted between snapshots, or the change is very old — two backstops: - **Local sync copy.** If you had [cloud sync](https://docs.basicmemory.com/cloud/cloud-sync) 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 (**Settings → Projects** → the project's `⋮` menu → **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/" ``` --- ## Still stuck? Contact support If you've lost content and no snapshot or backstop covers it, don't give up — Basic Memory runs **nightly backups** of cloud data independently of your snapshots, and we may be able to recover it for you. Email `support@basicmemory.com` — or use the **feedback button** in the app's lower-left navbar — with your account email, the workspace and project, roughly when the content was lost, and what it was. See [Contact Support](https://docs.basicmemory.com/reference/contact-support) for what else to include. --- ## 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, browsing, restore, CLI options) - [Cloud Sync](https://docs.basicmemory.com/cloud/cloud-sync) — a synced local folder 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 workspace-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. :: :docs-video{alt="Opening File history and restoring an earlier version of a note" poster="/videos/posters/docs-file-history.png" src="https://docs.basicmemory.com/videos/docs-file-history.mp4"} --- ## 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. Apply can also **fail after clicking** with *"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 version. --- ## Who can see and use it - **View history** — anyone with read access to the note (Viewer and above). - **Apply a version** — anyone with edit access (Editor and above). 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) — workspace-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 # Cloud CLI You do **not** need the CLI to use Basic Memory Cloud. The web app and hosted MCP endpoint are enough for most people. Install the CLI when you want Cloud to participate in terminal workflows: - Check Cloud connection and project status. - Manage API keys for scripts or MCP clients. - Sync a Cloud project with a local Markdown folder. - Route selected local projects through Cloud. - Create and restore Cloud snapshots. - Automate repeatable knowledge tasks from shell scripts or CI jobs. ::note{icon="i-lucide-cloud"} Cloud CLI commands use the same Cloud account, workspaces, projects, and permissions as the web app and hosted MCP endpoint. :: --- ## Install and check the CLI If you have not installed Basic Memory locally yet, use `uv`: ```bash uv tool install basic-memory ``` Confirm the command is available: ```bash bm --version ``` Update an older install: ```bash bm update ``` See [Install Basic Memory locally](https://docs.basicmemory.com/local/local-install) for Homebrew and local MCP setup. --- ## Sign in to Cloud Use browser-based login for an interactive terminal: ```bash bm cloud login bm cloud status ``` `bm cloud login` authenticates the CLI. It does not automatically move local projects into Cloud or start syncing files. For automation, scripts, shared terminals, or clients that need bearer-token authentication, use an API key: ```bash # Save an existing key from Settings -> API Keys bm cloud api-key save bmc_your_key_here # Or create and save a new key from the CLI # Requires an active `bm cloud login` session bm cloud api-key create "work-laptop" ``` See [API Keys](https://docs.basicmemory.com/cloud/api-keys) for the full key workflow and security guidance. --- ## Inspect workspaces and projects List the Cloud workspaces available to your account: ```bash bm cloud workspace list ``` Set the default workspace used by Cloud commands when one is not specified: ```bash bm cloud workspace set-default acme ``` List projects across local and Cloud workspaces: ```bash bm project list ``` `bm project list` is the fastest sanity check when a terminal command or local MCP server is not using the project you expected. --- ## Manage public share links Create a public link for one note, optionally with an expiration: ```bash bm cloud share create research notes/my-idea bm cloud share create research notes/my-idea --expires-at 2099-12-31 ``` List all links or filter them by project: ```bash bm cloud share list bm cloud share list --project research ``` Disable a link without deleting it, enable it again, or update its expiration: ```bash bm cloud share update SHARE_TOKEN --disable bm cloud share update SHARE_TOKEN --enable bm cloud share update SHARE_TOKEN --expires-at 2099-12-31 bm cloud share update SHARE_TOKEN --expires-at none ``` Revoke a link permanently: ```bash bm cloud share revoke SHARE_TOKEN bm cloud share revoke SHARE_TOKEN --force ``` Use `--workspace ` on any share command when the link belongs to a non-default workspace or when a project name is ambiguous. Create resolves the workspace from the explicit option, the project's configured workspace, or your default workspace; the other commands can route by the explicit workspace. --- ## Route selected local projects through Cloud Routing is for hybrid setups where you have the CLI or a local MCP server installed, but want specific projects to use Cloud. ```bash # Route one project through Cloud bm project set-cloud research # Route a project through a specific workspace bm project set-cloud research --workspace acme # Return the project to local routing bm project set-local research --local-path ~/Documents/research ``` Routing is separate from file sync. A Cloud-routed project can be used by CLI and local MCP commands without keeping a local Markdown mirror. See [Local & Cloud Routing](https://docs.basicmemory.com/cloud/routing) for the routing model, precedence, and troubleshooting. --- ## Sync Cloud with local files Use Cloud Sync when you want a local Markdown folder and a Cloud project to stay aligned. The additive `push` and `pull` commands work the same on personal and team workspaces. These commands assume the Cloud project already exists — create one in the web app or with `bm project add research --cloud`: ```bash bm cloud setup # Personal workspaces only — Team push/pull needs no setup bm cloud sync-setup research ~/Documents/research # Fetch cloud changes, then upload local ones bm cloud pull --name research bm cloud push --name research --dry-run bm cloud push --name research ``` On Team workspaces (v0.23+), `push` and `pull` run over the cloud's permissioned WebDAV API — no rclone remote or storage credentials — with each request authorized against your access to the specific project. See [Cloud Sync](https://docs.basicmemory.com/cloud/cloud-sync) for the full workflow reference, including conflict handling with `--on-conflict`. The Personal-workspace mirror command can delete cloud files, including files that become newly ignored: ```bash bm cloud sync --name research --dry-run bm cloud sync --name research ``` Delete only remote files that match this machine's `.bmignore`: ```bash bm cloud prune --name research --dry-run bm cloud prune --name research ``` ::warning Starting in v0.23, `bm cloud sync` deletes a previously synced cloud file when it becomes ignored by `.bmignore` . Preview the mirror or prune operation before confirming deletion. Additive `bm cloud push` and `bm cloud pull` do not delete destination files. :: --- ## Recover content from the terminal Cloud snapshots are available from the CLI: ```bash bm cloud snapshot list bm cloud snapshot create "Before reorganization" bm cloud snapshot browse SNAPSHOT_ID --prefix research/ bm cloud restore research/important-note.md --snapshot SNAPSHOT_ID ``` The CLI asks for confirmation before restore operations. Use `--force` only when you intentionally want to skip confirmation. See [Cloud Snapshots](https://docs.basicmemory.com/cloud/cloud-snapshots) and [Recover Notes](https://docs.basicmemory.com/cloud/restore-lost-content). --- ## Related reference ::card-group :::card --- icon: i-lucide-terminal title: CLI Reference to: https://docs.basicmemory.com/reference/cli-reference --- Complete command and option reference. ::: :::card --- icon: i-lucide-key title: API Keys to: https://docs.basicmemory.com/cloud/api-keys --- Create keys for automation and bearer-token MCP clients. ::: :::card --- icon: i-lucide-route title: Local & Cloud Routing to: https://docs.basicmemory.com/cloud/routing --- Choose which projects use local or Cloud operations. ::: :::card --- icon: i-lucide-refresh-cw title: Cloud Sync to: https://docs.basicmemory.com/cloud/cloud-sync --- Keep local Markdown folders aligned with Cloud projects. ::: :: # 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 | **Default** | — | Local. Projects run on your machine unless routed | Credentials (`bm cloud login` or an API key) don't change routing — they just let cloud-routed calls authenticate. **Examples:** - Everything defaults to local; `bm project set-cloud shared-notes` routes just that project through cloud. - A cloud-routed project stays cloud-routed until you run `bm project set-local` — logging out doesn't change it. - You need a quick check against a cloud project: `bm tool search-notes "meeting notes" --project shared-notes` — routing follows the project, so the call runs against cloud. --- ## 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. ::warning **`set-cloud` changes routing only — it doesn't upload your notes.** Upload existing content first ( `bm cloud upload ~/Documents/research --project research --create-project` ) or expect to populate the cloud project separately. Your local files stay on disk, but they're removed from the local index and the stored local path is cleared. :: ### Check Routing Status ```bash # See each project's routing in the CLI Route column bm project list # Verify cloud credentials and connectivity bm cloud status ``` ### Revert to Local ```bash # Switch a project back to local (--local-path is required — # set-cloud cleared the stored local path) bm project set-local research --local-path ~/Documents/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 Two ways to live fully in the cloud: - **Skip the CLI entirely** — connect your AI tools directly to the hosted MCP endpoint (`https://cloud.basicmemory.com/mcp`) and use the web app. Nothing local to route. - **Route every registered project through cloud** — `bm project set-cloud ` for each project (after uploading its content). ### 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); save cloud credentials once bm cloud api-key save bmc_your_key_here # or: bm cloud login # 2. Upload a project's content to cloud bm cloud upload ~/my-notes --project my-notes --create-project # 3. Route the (locally registered) project to cloud 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 | `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. --- ## Next Steps ::card-group :::card --- icon: i-lucide-refresh-cw title: Cloud Sync to: https://docs.basicmemory.com/cloud/cloud-sync --- Keep local folders and cloud projects aligned. ::: :::card --- icon: i-lucide-terminal title: Cloud CLI to: https://docs.basicmemory.com/cloud/cloud-cli --- The full command walkthrough for cloud workflows. ::: :::card --- icon: i-lucide-key title: API Keys to: https://docs.basicmemory.com/cloud/api-keys --- Credentials for cloud-routed projects. ::: :: # Comments and Suggestions Basic Memory keeps review feedback with the note, so people and connected AI assistants can discuss a passage or propose a change without overwriting the original text. Under the rich editor, comments and suggestions use portable [CriticMarkup](https://github.com/CriticMarkup/CriticMarkup-toolkit){rel=""nofollow""}. You can review the same note in the Cloud web app or the **Pocketbook** inside a compatible AI conversation. :docs-video{alt="Suggesting edits and reviewing them with an AI assistant" poster="/videos/posters/docs-comments-suggestions.png" src="https://docs.basicmemory.com/videos/docs-comments-suggestions.mp4"} --- ## Start from a text selection Open the note in [Rich editor mode](https://docs.basicmemory.com/cloud/note-editor#editing-modes), then select the passage you want to review. The selection toolbar keeps the usual formatting actions—bold, italic, strikethrough, inline code, and link—and adds two review actions: - **Add comment** opens a discussion without changing the selected text. - **Suggest edit** proposes a change that can be accepted or rejected later. :theme-image{alt="Selected text and the review actions in the rich editor toolbar" dark="/screenshots/cloud-app/critic-selection-dark.png" light="/screenshots/cloud-app/critic-selection-light.png"} --- ## Add a comment 1. Select the text you want to discuss. 2. Choose **Add comment** from the selection toolbar. 3. Write the comment and press **Enter**. Use **Shift + Enter** for a new line. The review rail keeps unresolved threads beside their highlighted text. Open a thread to reply, resolve it, or delete it. Resolving a comment removes its inline review markers while leaving the original passage unchanged. --- ## Suggest an edit Select text, choose **Suggest edit**, and then choose the kind of change: | Action | Result | | ----------------------- | ------------------------------------------ | | **Suggest insertion** | Propose text to add after the selection | | **Suggest deletion** | Mark the selected text for removal | | **Suggest replacement** | Propose new text in place of the selection | Open a suggestion from the review rail to **Accept** or **Reject** it. Accepting applies the proposal; rejecting restores the original document state. :theme-image{alt="Insertion, deletion, and replacement options in the Cloud editor" dark="/screenshots/cloud-app/critic-suggestion-menu-dark.png" light="/screenshots/cloud-app/critic-suggestion-menu-light.png"} Insertion and replacement open a composer for the proposed text. Deletion can be proposed immediately because the selected passage already identifies what should be removed. ### Read the proposed change inline Suggestions remain visible in the document while they are unresolved. Deleted or replaced text appears in red with a strikethrough; inserted or replacement text appears in green. This makes the original and proposed versions readable together. :theme-image{alt="A replacement suggestion shown inline with removed text in red and proposed text in green" dark="/screenshots/cloud-app/critic-inline-replacement-dark.png" light="/screenshots/cloud-app/critic-inline-replacement-light.png"} ### Open the suggestion thread Select the highlighted suggestion to open its thread. The card shows who authored it, when it was created, and a plain-language summary of the change. From there you can: - Select the green check to **accept** the suggestion. - Select the red X to **reject** it. - Reply to discuss the proposal before deciding. Press **Enter** to send or **Shift + Enter** for a new line. :theme-image{alt="A replacement suggestion thread with author, timestamp, accept, reject, and reply controls" dark="/screenshots/cloud-app/critic-suggestion-thread-dark.png" light="/screenshots/cloud-app/critic-suggestion-thread-light.png"} ::note Review ranges cannot overlap other review markup. If a comment or suggestion action is unavailable, narrow the selection so it does not cross an existing review item or unsupported content such as inline code. :: --- ## Follow unresolved review items When a note has open review work, the message icon in the note toolbar shows the number of unresolved comments and suggestions. Select it from Preview mode to open the note in the review editor. :theme-image{alt="Note toolbar showing two unresolved review items" dark="/screenshots/cloud-app/critic-review-count-dark.png" light="/screenshots/cloud-app/critic-review-count-light.png"} The review rail keeps every unresolved item beside its highlighted passage. Suggestions use red and green change highlighting; comments use an amber highlight. Compact cards show the author, time, and a summary, and selecting a card expands its available actions and replies. :theme-image{alt="Review rail with a replacement suggestion and a comment aligned beside their highlighted passages" dark="/screenshots/cloud-app/critic-review-rail-dark.png" light="/screenshots/cloud-app/critic-review-rail-light.png"} --- ## Review with an AI assistant Cloud-connected assistants use the `review_note` MCP tool to create and manage the same attributed threads you see in the editor. Ask one to: ```text Review this note with comments and suggestions. Keep the original prose in place so I can accept each change individually. ``` The supported workflow is: 1. Call `read_note` with `review_mode="structured"` (the Cloud default) to get clean note prose, typed review items, and a `revision_checksum`. 2. Call `review_note(command="comment")` or `review_note(command="suggest")` with an exact, single-line prose anchor copied from that read. 3. Use the returned review IDs to `reply` or `resolve` a comment, or to `accept` or `reject` a suggestion. 4. Pass the latest checksum when accepting or rejecting. If the note changed, read it again instead of applying a decision to stale text. For example: ```text review_note( identifier="Launch plan", command="suggest", anchor={"exact": "Ship the beta on Friday."}, suggestion_kind="replacement", replacement="Ship the beta after the security review." ) ``` Anchors can include exact `prefix` or `suffix` context, or a one-based `occurrence`, when the same sentence appears more than once. New threads are attributed to the detected MCP client. ::warning Do not ask an assistant to write CriticMarkup directly. Raw markup does not create the structured thread records used for attribution, replies, resolution, and accept/reject controls. Use `review_note` ; reserve `read_note(review_mode="raw")` for inspecting exact persisted Markdown. :: The common CriticMarkup forms are: ```markdown {==text under review==}{>>Comment<<} {++proposed addition++} {--proposed deletion--} {~~original text~>replacement text~~} ``` Basic Memory adds stable IDs and attributed review records when it creates a thread. Let the editor and `review_note` manage that metadata rather than changing it by hand. The metadata stays out of the editor body and is removed from public shared-note output. ### Edit prose while review work is open Cloud's normal `edit_note` tool preserves active review records. When a note contains review work, first read it in structured mode and pass that read's `revision_checksum` as `expected_checksum`. An edit that intersects reviewed prose is rejected with the blocking review ID; resolve the comment or accept/reject the suggestion before changing that passage. `write_note(overwrite=true)` remains an intentional full replacement and can remove review state. Search results also hide CriticMarkup storage bytes. JSON results include `review_summary` counts so an assistant can see that a matching note still needs review without loading every thread. --- ## Review inside a conversation The [Pocketbook](https://docs.basicmemory.com/cloud/mcp-app) brings the same focused review workflow into compatible AI clients. From the embedded note reader you can: - Add attributed comments - Suggest insertions, deletions, and replacements - Resolve or delete comments - Accept or reject suggestions - Open the note in the full Cloud web app for threaded replies --- ## Next steps ::card-group :::card --- icon: i-lucide-file-pen-line title: Note Editor to: https://docs.basicmemory.com/cloud/note-editor --- Learn the editing modes, formatting tools, and shortcuts. ::: :::card --- icon: i-lucide-sparkles title: AI Collaboration to: https://docs.basicmemory.com/cloud/ai-collaboration --- Connect assistants that can read, write, and review your notes. ::: :::card --- icon: i-lucide-panels-top-left title: Pocketbook to: https://docs.basicmemory.com/cloud/mcp-app --- Browse and review Basic Memory without leaving the conversation. ::: :: # Pocketbook (Interactive MCP App) Basic Memory Cloud includes **Pocketbook**, its Interactive MCP App, inside compatible AI clients. It brings a focused version of your workspace into the conversation, so you can browse notes, set a writing location, or make a quick edit without switching to a separate browser tab. The app is part of the hosted Cloud connector at `https://cloud.basicmemory.com/mcp`; there is no second server or separate installation. :docs-video{alt="The Pocketbook inside a conversation" poster="/videos/posters/docs-pocketbook.png" src="https://docs.basicmemory.com/videos/docs-pocketbook.mp4"} ::note Pocketbooks are currently supported in: - **ChatGPT** — web and desktop - **Claude** — web and desktop Other MCP clients can still use the normal Basic Memory tools, and your assistant can link you to the full web app. :: ## Open Basic Memory in a conversation Ask naturally for a visual or interactive view: ```text Open Basic Memory. Show my project notes. Open my note about API design. Let me browse the research folder. Open Basic Memory search for authentication. Show the knowledge graph around my architecture note. ``` Your assistant calls `open_basic_memory` and opens the requested view. The default workspace and project resolve automatically, so you do not need to list or choose a project first unless you want a different location. :theme-image{alt="The Pocketbook open to the Notes gallery inside an AI conversation" dark="/screenshots/mcp-app/mcp-app-open-dark.png" light="/screenshots/mcp-app/mcp-app-open-light.png"} ## Expand the app to full screen When your AI client supports full-screen MCP Apps, the diagonal-arrow **Expand** action appears in the app header beside the link to the full Basic Memory web app. :theme-image{alt="The Expand action in Pocketbook header" dark="/screenshots/mcp-app/mcp-app-expand-control-dark.png" light="/screenshots/mcp-app/mcp-app-expand-control-light.png"} Choose **Expand** to move from the compact conversation card into a larger workspace. Full-screen mode keeps the project or folder picker, **Notes**, **Search**, **Graph**, the active writing-location control, and the full web-app link together while giving note cards, editors, and graphs more room. The exact full-screen frame is controlled by the AI client. Use its close or return control to go back to the conversation. :theme-image{alt="The Pocketbook expanded to a full-screen workspace in an AI client" dark="/screenshots/mcp-app/mcp-app-fullscreen-dark.png" light="/screenshots/mcp-app/mcp-app-fullscreen-light.png"} ## Choose where new notes go The **Notes** view is both a browser and a location picker. Use the breadcrumb at the top to switch workspaces, projects, and folders. Folder cards show their note counts, note cards open in place, and **Load more** pages through longer directories. The external-link action opens the current location in the full Basic Memory web app. :theme-image{alt="The Use this folder button before a writing location is selected in Pocketbook" dark="/screenshots/mcp-app/mcp-app-use-folder-dark.png" light="/screenshots/mcp-app/mcp-app-use-folder-light.png"} Choose **Use this folder** to make the current workspace, project, and directory the active writing location for the conversation. The app marks it as **Active folder**, and the copy action lets you reuse its Basic Memory location elsewhere. :theme-image{alt="A folder selected as the active writing location in Pocketbook" dark="/screenshots/mcp-app/mcp-app-active-folder-dark.png" light="/screenshots/mcp-app/mcp-app-active-folder-light.png"} The app sends the location into the conversation and asks the assistant to write new notes there until you choose another folder. The assistant can then keep the workspace, project, and directory attached to later Basic Memory calls instead of asking you to select them again. :theme-image{alt="An assistant confirming the active Basic Memory workspace, project, and folder" dark="/screenshots/mcp-app/mcp-app-folder-confirmed-dark.png" light="/screenshots/mcp-app/mcp-app-folder-confirmed-light.png"} ## Read and reuse a note Open a note from **Notes**, **Search**, a wiki link, or the knowledge graph. The reader renders Basic Memory Markdown, including wiki links, task lists, tables, syntax-highlighted code, Mermaid diagrams, observations, relations, and frontmatter. From the reader you can: - Toggle task checkboxes - Refresh the note or inspect its frontmatter - See how many review threads remain unresolved - Copy a note link or open the note in the full web app - Click the note title to use the note in the conversation - Switch to **Edit** without leaving the conversation :theme-image{alt="A Basic Memory note rendered inside the MCP App reader" dark="/screenshots/mcp-app/mcp-app-note-reader-dark.png" light="/screenshots/mcp-app/mcp-app-note-reader-light.png"} ### Add a note to your prompt In the Notes gallery, hover over a note card and choose **Use note in conversation**. The app prepares a prompt that tells the assistant to use that note in the current conversation thread. :theme-image{alt="The Use note in conversation action on a note card in Pocketbook gallery" dark="/screenshots/mcp-app/mcp-app-use-note-gallery-dark.png" light="/screenshots/mcp-app/mcp-app-use-note-gallery-light.png"} You can also open the note and click its title in the reader to use it in the conversation. :theme-image{alt="The clickable note title in the full Pocketbook reader header" dark="/screenshots/mcp-app/mcp-app-use-note-title-dark.png" light="/screenshots/mcp-app/mcp-app-use-note-title-light.png"} The prompt identifies the note by workspace, project, and permalink, so the assistant can read the right note and use it as context. You can add your question or instructions before sending it. :theme-image{alt="A conversation prompt prepared with a Basic Memory note's workspace, project, and permalink" dark="/screenshots/mcp-app/mcp-app-note-prompt-dark.png" light="/screenshots/mcp-app/mcp-app-note-prompt-light.png"} ## Search across your notes Open **Search**, enter a query, and choose whether to search the current project or all projects you can access. Results show matching excerpts and their locations; select one to open it in the reader without leaving the app. :theme-image{alt="Search results in Pocketbook" dark="/screenshots/mcp-app/mcp-app-search-dark.png" light="/screenshots/mcp-app/mcp-app-search-light.png"} ## Edit and review in place Choose **Edit** from the note reader to open the rich editor. It includes headings, lists, task lists, links, tables, undo and redo, and a preview mode. Changes autosave after a short pause, the status changes to **Saved**, and the app checks for a newer remote revision before overwriting. The same editor supports shared review markup. You can add attributed comments, suggest insertions, deletions, or replacements, and open any unresolved thread. Suggestions remain inline with the note until someone **Accepts** or **Rejects** them; comments can be resolved or deleted without changing the note text. Notes and search results show pending comment and suggestion counts, so review work is visible before you open the editor. Excerpts remain clean prose and never expose the underlying CriticMarkup storage. :theme-image{alt="A replacement suggestion with Accept and Reject actions in the MCP App editor" dark="/screenshots/mcp-app/mcp-app-review-dark.png" light="/screenshots/mcp-app/mcp-app-review-light.png"} For the full review workflow, see [Comments and Suggestions](https://docs.basicmemory.com/cloud/comments-and-suggestions). ## Explore the knowledge graph Open **Graph** for an overview of the current project's notes and relations. Switch to the full graph to explore the complete connected view, select nodes to inspect their details, and follow a note back into the reader. Graph controls let you zoom, fit the graph to the viewport, and toggle labels; **Overview** returns to the summary. :theme-image{alt="The full Basic Memory knowledge graph inside the MCP App" dark="/screenshots/mcp-app/mcp-app-graph-dark.png" light="/screenshots/mcp-app/mcp-app-graph-light.png"} ## Choose the app or a data tool The interactive app is for something you want to **see or operate**. Normal MCP data tools are for information the assistant needs to **reason with**. | Goal | Tool | | ----------------------------------------------------- | ------------------- | | Show an interactive note, folder, search, or graph | `open_basic_memory` | | Read note content for an answer or summary | `read_note` | | Search for information the assistant will use | `search_notes` | | Get a directory listing as data | `list_directory` | | Add, reply to, resolve, accept, or reject review work | `review_note` | For example, “What did we decide about authentication?” should use search and read tools. “Open my authentication notes so I can browse them” should use the interactive app. ## Next steps ::card-group :::card --- icon: i-lucide-message-square title: ChatGPT to: https://docs.basicmemory.com/integrations/chatgpt --- Connect the published Basic Memory Cloud plugin or a custom MCP server. ::: :::card --- icon: i-lucide-message-square-text title: Comments and Suggestions to: https://docs.basicmemory.com/cloud/comments-and-suggestions --- Review passages and accept proposed changes individually. ::: :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- See the parameters for the interactive app and data tools. ::: :: # Basic Memory Teams Basic Memory Teams puts your whole team — and every AI agent they use — on one shared memory. Anything a teammate writes is immediately available to everyone else and to their agents: a decision captured in one person's Claude session becomes context for another's Codex run. 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 a team 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** | Just you | Your personal cloud subscription and notes | | **Team** | Your team | Shared projects, members, roles, and seats | :docs-video{alt="Inviting a teammate by email, and what they see when they accept" poster="/videos/posters/docs-teams-invite.png" src="https://docs.basicmemory.com/videos/docs-teams-invite.mp4"} In the app, each workspace — personal and every team — appears as its own section in the sidebar. Projects and notes are scoped to the workspace you're in; local projects stay on your machine, reachable from the CLI and MCP alongside them. --- ## Working together Everyone on the team reads and writes the same knowledge base. A note a teammate saves is available to you — and to your agents — the next time you open it, and every change is listed in the Activity feed with a link to the note it touched. ### AI agents as collaborators AI agents work with the shared knowledge base through MCP. They 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. When an agent writes or updates a note, the change appears in the Activity feed alongside your teammates' edits. ### 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). --- ## Security and isolation Each team 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. --- ## Explore Teams ::card-group :::card --- icon: i-lucide-users title: Members and Roles to: https://docs.basicmemory.com/teams/members-and-roles --- Roles, member statuses, invitations, and member management. ::: :::card --- icon: i-lucide-credit-card title: Seats and Billing to: https://docs.basicmemory.com/teams/seats-and-billing --- Per-seat billing, seat usage, and the grace period. ::: :::card --- icon: i-lucide-folder-kanban title: Team Projects to: https://docs.basicmemory.com/teams/team-projects --- Project access, invite-only projects, and workspace targeting. ::: :::card --- icon: i-lucide-door-open title: Joining a Team Workspace to: https://docs.basicmemory.com/teams/join-a-team --- Got an invite? Your first-day walkthrough. ::: :::card --- icon: i-lucide-copy title: Copy Content Between Workspaces to: https://docs.basicmemory.com/teams/copy-between-workspaces --- Bring personal notes into the team workspace. ::: :::card --- icon: i-lucide-handshake title: Partners (MSP) to: https://docs.basicmemory.com/partners/about --- Run Basic Memory for your customers as a managed service provider. ::: :: # Members and Roles Every member of a team has a role that determines what they can do, and a status that tracks their seat. This page is the canonical reference for both, plus the inviter's side of getting people in. Joining a team yourself? See [Joining a Team Workspace](https://docs.basicmemory.com/teams/join-a-team). --- ## Roles | Role | Can do | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Viewer** | Read-only access to team projects and notes (can edit an [invite-only project](https://docs.basicmemory.com/teams/team-projects) if granted edit access on it) | | **Editor** | Read and write notes, and create projects | | **User Admin** | Everything an editor can, plus manage members and invitations, view the audit log, and download project archives | | **Admin** | Everything a user admin can, plus manage API keys | | **Owner** | Everything an admin can, plus manage billing, snapshots, rename the team, and transfer ownership. A team can have only one member with the Owner role. | Once an invitation has been extended to a user, members also have a **status**: - **Pending** — invited, but hasn't finished linking their account yet - **Active** — accepted the invitation, claiming a seat, with full access according to their role - **Suspended** — access paused because the team stayed over its seat allocation past the 14-day grace period; reactivating is instant once a seat frees up - **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-team-invite-dark.png" light="/screenshots/cloud-app/v2-team-invite-light.png"} --- ## Inviting members :docs-video{alt="Inviting a teammate by email, and what they see when they accept" poster="/videos/posters/docs-teams-invite.png" src="https://docs.basicmemory.com/videos/docs-teams-invite.mp4"} Owners, admins, and user admins invite people by email from **Settings → Members** — click **Invite Member**. ::note **Invite Member is disabled when you have no available seats.** Check **Seat Usage** at the top of the page — if it reads *0 available* , add a seat under [Settings → Billing](https://docs.basicmemory.com/teams/seats-and-billing) first. Pending invitations don't consume a seat, but you can't create one without a seat for it to land in. :: ::steps ### Send an invitation Enter the person's email address and choose a role. You can assign any role at or below your own — Owner is never an invite option. :theme-image{alt="Invite Member dialog" dark="/screenshots/cloud-app/v2-team-invitation-dark.png" light="/screenshots/cloud-app/v2-team-invitation-light.png"} ### They accept by email The invitee gets an email with an accept link, signs in with the invited address, and becomes an active member. The full invitee-side walkthrough is on [Joining a Team Workspace](https://docs.basicmemory.com/teams/join-a-team). :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"} :: ::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. :: --- ## Managing members From **Settings → Members**, anyone with the **User Admin** role or above can: - **Change a member's role** — promote a viewer to editor, or vice versa. Roles can only be assigned at or below your own, and only the owner can act on another owner. - **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. Only the **owner** can: - **Transfer ownership** — hand the workspace (and its subscription) to another member. The new owner takes over billing and management. - **Rename the team.** --- ## Next Steps ::card-group :::card --- icon: i-lucide-credit-card title: Seats and Billing to: https://docs.basicmemory.com/teams/seats-and-billing --- Per-seat billing, the grace period, and seat management. ::: :::card --- icon: i-lucide-door-open title: Joining a Team Workspace to: https://docs.basicmemory.com/teams/join-a-team --- The invitee's first-day walkthrough. ::: :::card --- icon: i-lucide-folder-kanban title: Team Projects to: https://docs.basicmemory.com/teams/team-projects --- Project access, invite-only projects, and workspace targeting. ::: :: # 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. Members over the limit after the grace period are **suspended** (access paused, data intact) until a seat frees up. --- ## Managing seats and payment 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"} Team details, the billing contact, and seat usage are also visible under **Settings → Teams**: :theme-image{alt="Team settings and seat usage" dark="/screenshots/cloud-app/v2-settings-teams-dark.png" light="/screenshots/cloud-app/v2-settings-teams-light.png"} ::note Billing and ownership transfer are **owner** actions — see [Members and Roles](https://docs.basicmemory.com/teams/members-and-roles) for who can do what. :: --- ## Next Steps ::card-group :::card --- icon: i-lucide-users title: Members and Roles to: https://docs.basicmemory.com/teams/members-and-roles --- Roles, invitations, and member management. ::: :::card --- icon: i-lucide-handshake title: Partners (MSP) to: https://docs.basicmemory.com/partners/about --- Managing Basic Memory for customers? Partner billing works differently. ::: :: # Team Projects Projects are how a team organizes its knowledge base. Every project in a team workspace has an access level, and every member's reach into it follows their [role](https://docs.basicmemory.com/teams/members-and-roles). --- ## Project access :docs-video{alt="Switching a project to invite-only, watching it disappear for a teammate, and opening it back up" poster="/videos/posters/docs-teams-access.png" src="https://docs.basicmemory.com/videos/docs-teams-access.mp4"} Every project in a team workspace has an access level that decides who can find it: | Access | Who can see it | When to use | | -------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | **Team** — *default* | Everyone in the team, according to their [role](https://docs.basicmemory.com/teams/members-and-roles) | Most team work — the open, shared knowledge base | | **Invite-only** | Only the teammates you invite to it | Sensitive topics — hiring, contracts, security reviews — or work you want to keep to yourself | ### Changing a project's access Open **Settings → Projects**. Each project lists its current access underneath its name. Click **Edit Access**, choose **Team** or **Invite-only**, and save. Access can be changed at any time — it isn't fixed when the project is created. ### Choosing who can see an invite-only project An invite-only project gets a **Manage Members** button next to **Edit Access**. Use it to invite specific teammates. Anyone you don't invite can't find or open the project. An invite-only project with nobody invited is visible only to you. That's the way to keep drafts or scratch work in a team workspace without the rest of the team seeing them. ::note **Keeping something entirely out of the team is simpler than it looks.** Your [personal workspace](https://docs.basicmemory.com/teams/about#workspaces) is separate from every team you belong to, and teammates never see it. You only need an invite-only project when the work should live in the team workspace but stay narrow. :: ::warning **`bm project add --visibility` does not work.** The CLI accepts `workspace` , `shared` , and `private` and then ignores them — every project is created **Team** -visible regardless. It is also not possible to read a project's access level back from the CLI. Set access in the app instead, and confirm it there. Tracked in [basic-memory#1343](https://github.com/basicmachines-co/basic-memory/issues/1343){rel=""nofollow""} . :: --- ## Working with team projects Once you're part of a team, projects show up everywhere you work: - **In the app** — Select the project 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. - **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")`). ### Targeting a team project explicitly If a project name exists in more than one workspace (say, `research` in both your personal and team workspaces), resolution prefers your default workspace — or asks you to disambiguate. To be explicit, use a **workspace-qualified memory URL**: ```text memory://acme/research/architecture-decisions ``` The form is `memory:////`. From the CLI, pass `--workspace` on the command instead. --- ## Bringing existing notes into a team project 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. --- ## Next Steps ::card-group :::card --- icon: i-lucide-copy title: Copy Content Between Workspaces to: https://docs.basicmemory.com/teams/copy-between-workspaces --- Move personal notes into the team workspace. ::: :::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. ::: :: # 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. :: --- :docs-video{alt="Accepting an invitation, creating an account, and landing in the team workspace" poster="/videos/posters/docs-teams-invite.png" src="https://docs.basicmemory.com/videos/docs-teams-invite.mp4"} ## 1. Accept the invitation Open the invitation email and click the **Accept invitation** link. It opens an accept page in the app. - Click **Accept** — the app then routes you through sign-in. - Sign in with the email the invite was sent to (you'll create an account during sign-in if you don't have one). - If you're already signed in with a different account, the app will prompt you to sign in again with the invited email. On first sign-in, your account is linked to the pending membership, and you become an active team member. --- ## 2. Find the projects Your team appears as its own section in the sidebar, alongside your personal workspace, with its projects listed underneath. Open one to see its folders and notes. Your **role** determines what you can do — from read-only **Viewer** up to **Owner**, with Editor, User Admin, and Admin tiers in between. The full capability table is on [Members and Roles](https://docs.basicmemory.com/teams/members-and-roles). Not sure of your role? Open **Settings → Teams** to see your teams and your role in each. If you need a different role, ask an owner, admin, or user admin — they manage members from **Settings → Members**. --- ## 3. 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). - **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 reference notes with a workspace-qualified memory URL — `memory://acme/research/note-title`. See [Team Projects](https://docs.basicmemory.com/teams/team-projects) for the full targeting guide. --- ## 4. 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 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) — the team workspace overview - [Members and Roles](https://docs.basicmemory.com/teams/members-and-roles) — roles, invitations, member management - [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) — 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** to the target project. Downloading a whole project as a ZIP additionally requires the **User Admin** role or above in the source workspace. - **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 Find the **target workspace's** section in the sidebar. ### 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 push them up: 1. Run `bm cloud pull` 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 push --name ` to upload the new files to the target workspace. 4. Verify in the app, then delete the originals from the source project in the app or via MCP (push is additive, so local deletions don't propagate). 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) — push/pull 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` # Partner Program The Basic Memory partner program is built for **managed service providers** who operate Basic Memory on behalf of their customers. You provision and manage customer organizations from a dedicated partner portal; Basic Memory bills you once, and you bill your customers however you like. What you get as a partner: - **A partner portal to provision customers** — create a customer and their [isolated workspace](https://docs.basicmemory.com/partners/customer-provisioning) is live in minutes: its own database and file storage, physically separated from every other tenant - **SSO for your customers** — connect each customer's identity provider ([WorkOS-brokered](https://docs.basicmemory.com/partners/customer-sso)); their users sign in with corporate credentials and can be provisioned automatically on first sign-in - **Consolidated invoicing** — one usage-based invoice to your account, with [per-customer statements and CSV exports](https://docs.basicmemory.com/partners/billing) to drive your own rebilling - **A full audit log** — every action your staff takes is [recorded](https://docs.basicmemory.com/partners/team-and-audit), and customers see the administrative actions you perform on their workspace, labeled as their MSP Each customer gets the full Basic Memory Cloud product: the web app, the hosted MCP endpoint for their AI tools, team members and roles, snapshots, and file history — one shared memory for their whole organization and every agent connected to it. ::note{icon="i-lucide-handshake"} **The partner program is invite-only.** Basic Memory sets up your partner account and emails your designated owner a claim link. To become a partner, contact us at `hello@basicmemory.com` — and see [basicmemory.com/partners](https://basicmemory.com/partners){rel=""nofollow""} for the program overview. :: --- ## The partner portal Partner staff work from the portal at **`/partner`**, separate from the customer-facing app: | Section | What it's for | | ------------- | --------------------------------------------------------------------------- | | **Dashboard** | Seat commitment, utilization, and period-to-date billing at a glance | | **Customers** | Managed customer organizations and their workspaces | | **Billing** | Usage statements behind your official invoices, CSV exports, seat purchases | | **Team** | Your partner staff and their scoped roles | | **Audit Log** | A record of everything partner staff do | A **Getting started** checklist on the Dashboard walks new partners through setup: claim your account, invite your team, add your first customer, set up customer SSO, and review billing. --- ## Getting set up ::steps ### Claim your invitation Basic Memory emails your account owner a one-time claim link. Open it, sign in, accept the Terms of Service, and claim the invitation. You can claim while the account is still in draft. ### Activate your subscription Until payment is set up, the Dashboard shows an **Activate your subscription** banner. An owner or billing member clicks **Set up payment** and completes checkout. Activation is automatic once payment lands — customer onboarding, seats, and billing unlock immediately. ### Invite your team From **Team**, invite staff with [scoped roles](https://docs.basicmemory.com/partners/team-and-audit). Each invitee gets a one-time claim link. ### Add your first customer From **Customers**, click **Add customer**. This [provisions the customer's isolated workspace](https://docs.basicmemory.com/partners/customer-provisioning). :: --- ## Explore ::card-group :::card --- icon: i-lucide-building-2 title: Customer Provisioning to: https://docs.basicmemory.com/partners/customer-provisioning --- Add customers, manage seat caps, and handle the customer lifecycle. ::: :::card --- icon: i-lucide-key-round title: Customer SSO to: https://docs.basicmemory.com/partners/customer-sso --- Connect each customer's identity provider with JIT provisioning. ::: :::card --- icon: i-lucide-receipt title: Billing to: https://docs.basicmemory.com/partners/billing --- Seat-day metering, consolidated invoices, and rebilling statements. ::: :::card --- icon: i-lucide-shield-check title: Team and Audit to: https://docs.basicmemory.com/partners/team-and-audit --- Partner staff roles and the full audit trail. ::: :: # Customer Provisioning The **Customers** page in the partner portal is where you create and operate customer organizations. Each customer gets a **dedicated, isolated workspace** — its own database and file storage, physically separated from every other customer and tenant. There is no shared data layer between your customers. --- ## Add a customer Click **Add customer** on the Customers page. Provisioning creates the customer's organization and workspace automatically — no infrastructure work on your side. The customer list shows each customer's **status, workspace, seat cap, JIT state, and billing label**. SSO state lives on the customer's detail page. --- ## Seat caps Each customer can have an optional **seat cap** — a per-customer limit on assigned seats: - Leave the cap blank for no per-customer limit; the customer is then bounded only by your account-wide [seat commitment](https://docs.basicmemory.com/partners/billing). - If an assignment would exceed the customer's cap, it's denied until you raise the cap. - The customer's detail page shows assigned seats, cap, available seats, and utilization. --- ## Customer lifecycle From a customer's detail page: - **Suspend** — pauses access for all of the customer's users. Their data is kept and seats stay assigned. - **Reactivate** — restores access for the customer's users. - **Archive** — the offboarding path: access ends and all open seats are closed. You confirm by typing the customer's slug. ::note{icon="i-lucide-eye"} **Transparency for your customers.** Administrative actions your staff take on a customer — lifecycle changes (create, suspend, reactivate, archive) and SSO changes — appear in the customer's own audit trail, labeled as performed by their MSP. Billing-metadata updates stay internal to your portal. :: --- ## Next Steps ::card-group :::card --- icon: i-lucide-key-round title: Customer SSO to: https://docs.basicmemory.com/partners/customer-sso --- Connect the customer's identity provider before their users sign in. ::: :::card --- icon: i-lucide-receipt title: Billing to: https://docs.basicmemory.com/partners/billing --- How customer seats turn into seat-days on your invoice. ::: :: # Customer SSO Customers sign in with **their own identity provider** — for example Microsoft Entra ID via SAML — brokered through WorkOS. You configure it per customer from the SSO panel on the customer's detail page. --- ## Set up SSO ::steps ### Verify the customer's email domain Domain verification is the entry point — enter the customer's domain (e.g. `acme.com`) and verify it. The SSO setup controls appear once a domain is verified. ### Open the setup portal Click **Start SSO setup** (or **Reconfigure SSO**). This opens the **WorkOS Admin Portal directly in a new tab** — portal links expire about 5 minutes after generation, so there's nothing to copy or email. Complete the identity-provider connection there yourself, or on a screen-share with the customer's IT admin. ### Optionally require SSO Turn on the require-SSO policy to make the customer's identity provider the only sign-in path for their users. :: --- ## JIT provisioning With SSO active and **JIT (just-in-time) provisioning** enabled, a user from the customer's verified domain is provisioned into the customer's workspace automatically on first sign-in — and starts consuming a seat. ::warning **JIT is on by default for new customers.** As soon as SSO is active, users from the verified domain will auto-provision and consume seats on first sign-in. If you want to control membership manually, turn JIT off on the customer's detail page *before* completing SSO setup. :: --- ## Next Steps ::card-group :::card --- icon: i-lucide-building-2 title: Customer Provisioning to: https://docs.basicmemory.com/partners/customer-provisioning --- Seat caps and the customer lifecycle. ::: :::card --- icon: i-lucide-receipt title: Billing to: https://docs.basicmemory.com/partners/billing --- JIT-provisioned users consume seats — here's how they're metered. ::: :: # Billing Basic Memory bills your partner account **once, monthly**, based on actual seat usage across all your customers — with per-customer statements so you can rebill on your own terms. There is no fixed recurring charge beyond your committed-seat minimum. --- ## How seat-days are metered - Billing periods are **UTC calendar months**. - Each UTC date on which a member has an active seat assignment counts as **one seat-day** for that member. Adding and removing the same member on the same date counts once; a seat removed mid-day still counts for that day. - `seat-months = seat-days ÷ days in the month`. - Your monthly charge is **whichever is larger**: actual seat-months used, or your committed-seat minimum (prorated for partial months). This means short-lived users cost you days, not months — and your floor is predictable. --- ## The Billing tab - **Billing periods** — actual, minimum, and billable seat-months per period, with subtotal, payment status, and a link to the official invoice. - **Customer statements** — per-customer seat-days, seat-months, and active-user counts for any period, with **Export CSV** for your PSA or accounting system. - **Billing portal** — opens the payment portal for official invoices and payment methods. ::note{icon="i-lucide-receipt"} Customer statements and CSV exports are **rebilling support data for your own invoicing** — they are not invoices. The only official invoice is the one issued to your partner account. :: --- ## Seats and capacity - The Dashboard shows committed seats, assigned seats, available seats, and utilization. - **Add seats** schedules a commitment increase effective at the next UTC month boundary. Seat purchases are an **Owner or Billing role** action. - If a customer's [seat cap](https://docs.basicmemory.com/partners/customer-provisioning) would be exceeded, new assignments to that customer are denied until you raise the cap. - At your account-wide commitment: with overage disabled, new assignments are blocked until a scheduled increase lands; with overage enabled, extra seats are allowed and metered as overage. - Billing contacts get an email alert at **90% utilization** or when overage starts accruing. --- ## Next Steps ::card-group :::card --- icon: i-lucide-building-2 title: Customer Provisioning to: https://docs.basicmemory.com/partners/customer-provisioning --- Per-customer seat caps and lifecycle. ::: :::card --- icon: i-lucide-shield-check title: Team and Audit to: https://docs.basicmemory.com/partners/team-and-audit --- Which roles can purchase seats and view billing. ::: :: # Team and Audit Your partner staff get **scoped roles** — sales and support people don't need billing access, and billing people don't need to touch SSO. Everything anyone does is recorded in the audit log. --- ## Partner staff roles | Role | Can do | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **Owner** | Full control, including ownership transfer and seat purchases. An account always keeps at least one owner, and only owners can grant the owner role | | **Admin** | Manage customers, SSO, team, and billing — except seat purchases (Owner and Billing only) | | **Billing** | Billing reads, the billing portal, and seat purchases | | **Support** | Customer reads and SSO setup links | | **Viewer** | Read-only customer and billing views | Manage staff from the **Team** page: invite by email with a role (each invitee gets a one-time claim link), suspend and reactivate members, and revoke pending invitations. ::note Partner staff roles are separate from the [team roles](https://docs.basicmemory.com/teams/members-and-roles) inside customer workspaces — partner roles govern the portal, team roles govern a workspace. :: --- ## The audit log The **Audit Log** page records everything partner staff do — customer lifecycle changes, SSO configuration, seat assignments, team management, billing actions — with who did it and when. Your customers get transparency too: administrative actions on their organization — lifecycle changes (create, suspend, reactivate, archive) and SSO changes — appear in **their** audit trail, labeled as performed by their MSP. Your billing metadata stays internal to your portal. --- ## Getting help Partner account, billing, and provisioning questions are handled directly by the Basic Memory team — email `hello@basicmemory.com`. --- ## Next Steps ::card-group :::card --- icon: i-lucide-handshake title: Partner Program to: https://docs.basicmemory.com/partners/about --- The program overview and getting set up. ::: :::card --- icon: i-lucide-users title: Team Roles (customer workspaces) to: https://docs.basicmemory.com/teams/members-and-roles --- The five roles inside each customer's workspace. ::: :: # Local install Local mode runs the MCP server on your machine and stores notes in local folders you control. ::note Followed [Quickstart: Local](https://docs.basicmemory.com/start-here/quickstart-local) ? You've already done this — continue to [Set Up Local Projects](https://docs.basicmemory.com/local/getting-started) or [CLI Basics](https://docs.basicmemory.com/local/cli-basics) . :: ## 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. :: ## Connect your MCP client Configure your MCP client to run the local server. For Claude Desktop, add this to `claude_desktop_config.json` ([file locations per platform](https://docs.basicmemory.com/integrations/claude-desktop#local-setup)): ```json [claude_desktop_config.json] { "mcpServers": { "basic-memory": { "command": "uvx", "args": ["basic-memory", "mcp"] } } } ``` ::note **Installed with Homebrew?** Use `"command": "basic-memory", "args": ["mcp"]` instead — `uvx` only exists if you installed uv. If your client can't find the command, use the full path ( `which basic-memory` ). :: Restart your MCP client after editing the config. Other clients — Codex, Cursor, VS Code, Gemini — are covered in [Integrations](https://docs.basicmemory.com/integrations). ## Choose where notes live By default, notes are stored in a `main` project under `~/basic-memory` — see [Set Up Local Projects](https://docs.basicmemory.com/local/getting-started) to point Basic Memory at any folder. ## 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. ::: :: # Getting Started Already installed? (If not, start with [Quickstart: Local](https://docs.basicmemory.com/start-here/quickstart-local).) This page covers what comes next: where your notes are saved, working with multiple projects, and keeping Basic Memory updated. --- title: "Quickstart: Cloud" icon: i-lucide-cloud to: /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: ```text Create a new project called "my project" in the "/Users/yourname/Documents/Notes" directory ``` Then: ```text 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:** ```text 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 — it's the same setting the command above writes: ```bash basic-memory project default "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. ::: :: # 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" ``` When semantic search is enabled (the default), plain searches already run in **hybrid** mode. Use these flags to force a specific retrieval mode: ```bash bm tool search-notes "authentication architecture" --hybrid bm tool search-notes "login flow" --vector ``` Search observations by category (e.g. every `[decision]` you've captured): ```bash bm tool search-notes --entity-type observation --category decision ``` ## Read and write notes ```bash bm tool read-note "docs/api-auth" echo "New note content" | bm tool write-note --title "Notes" --folder "drafts" ``` `read-note` accepts a title, permalink, or file path as the identifier. ## Schema workflows ```bash bm schema infer person bm schema validate person bm schema diff person ``` Infer a schema from existing notes, validate notes against it, and detect drift — see the [Schema System](https://docs.basicmemory.com/concepts/schema-system) for concepts and the full workflow. ## 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 Once your MCP client runs the local server (see [Local install](https://docs.basicmemory.com/local/local-install#connect-your-mcp-client)), tools read and write your local project folders — unless you've routed a project through cloud with [per-project routing](https://docs.basicmemory.com/cloud/routing). ## 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 graph traversal via [memory:// URLs](https://docs.basicmemory.com/concepts/memory-urls) Most tools default to `output_format="text"` (human-readable) and also accept `"json"` (machine-readable); `build_context` defaults to `"json"` — see the [MCP Tools Reference](https://docs.basicmemory.com/reference/mcp-tools-reference) for per-tool defaults. ## 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/local/getting-started#choosing-where-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: ```bash memory://coffee-brewing-methods # Reference by permalink memory://coffee-brewing-methods/relates_to/* # Follow relations ``` See [Memory URLs](https://docs.basicmemory.com/concepts/memory-urls) for the full addressing syntax, including project-prefixed forms. ### 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 enable `update_permalinks_on_move` — see [Configuration](https://docs.basicmemory.com/reference/configuration) ). :: --- ## Memory URL resolution (local server) At runtime, the local MCP server resolves memory URLs in this order: ### 1. Project constraints If the MCP server was started with `BASIC_MEMORY_MCP_PROJECT=research`, unprefixed URLs (and URLs prefixed with `research`) resolve in the `research` project. A URL prefixed with a *different* known project returns an error rather than resolving: ```text memory://docs/auth → resolves in "research" memory://main/docs/auth → error: project is constrained to "research" ``` ### 2. Explicit project prefix If no constraint is set, the URL is checked for a project prefix. The first path segment is always compared against known project names; when it matches, 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. ### 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") ``` ::note Prefix detection always runs — it isn't controlled by configuration. The `permalinks_include_project` setting governs whether *generated permalinks* include the project slug; see [Configuration](https://docs.basicmemory.com/reference/configuration) . :: --- ## Building Knowledge Connections Connect knowledge with relations and structure facts with categorized observations: ```markdown ## Observations - [decision] We chose JWT tokens for stateless auth - [requirement] Must support 2FA for sensitive operations ## Relations - implements [[Authentication System]] - requires [[Database Schema]] ``` Categories and relation types are open-ended — use whatever fits. The full syntax, conventions, and edge cases live in [Observations and Relations](https://docs.basicmemory.com/concepts/observations-and-relations). --- ## Multi-Project Workflows Basic Memory supports multiple projects for organizing different knowledge bases — the AI checks your projects at the start of a conversation and remembers your choice for the session. Project setup, creation commands, and the default-project fallback are covered in [Set Up Local Projects](https://docs.basicmemory.com/local/getting-started). ### 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 - `insert_before_section` / `insert_after_section` - Insert content adjacent to a section 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 project index status basic-memory status # View project information basic-memory project info main ``` ### Force Re-sync Sync runs automatically — file changes are picked up in real time. If something still seems out of sync: ```bash # Rebuild the search index basic-memory reindex # Reset and rebuild the database (use if issues persist) basic-memory reset --reindex ``` ::warning `basic-memory reset` deletes only the index database — your files are never touched. Pass `--reindex` to rebuild the index from your files afterward (a plain reset leaves the index empty until the next reindex). Rebuilding 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 The two most common symptoms: - **Changes not showing up** — check `basic-memory status`, then rebuild the index with `basic-memory reindex` - **Claude can't find knowledge** — confirm the files are in the right project and the frontmatter is valid YAML For the full runbook — sync, search, install, config, and logs — see [Troubleshooting](https://docs.basicmemory.com/reference/troubleshooting). ### 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 status --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. ::: :: # Postgres and Milvus SQLite remains the simplest local backend. Use this guide when you need to exercise the Postgres runtime or move a Postgres deployment's vector storage from pgvector to Milvus. ## Start local Postgres Basic Memory's Postgres backend requires the pgvector extension even when Milvus will own semantic vectors. Create `docker-compose-postgres.yml` with the same local service used by the Basic Memory repository: ```yaml [docker-compose-postgres.yml] services: postgres: image: pgvector/pgvector:pg17 container_name: basic-memory-postgres environment: POSTGRES_DB: basic_memory POSTGRES_USER: basic_memory_user POSTGRES_PASSWORD: dev_password ports: - "5433:5432" volumes: - postgres_data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U basic_memory_user -d basic_memory"] interval: 10s timeout: 5s retries: 5 volumes: postgres_data: ``` Start the database: ```bash docker compose -f docker-compose-postgres.yml up -d docker compose -f docker-compose-postgres.yml ps ``` Point Basic Memory at it before starting the MCP server or running a CLI command: ```bash export BASIC_MEMORY_DATABASE_BACKEND=postgres export BASIC_MEMORY_DATABASE_URL='postgresql+asyncpg://basic_memory_user:dev_password@localhost:5433/basic_memory' bm status ``` The first startup applies migrations and seeds the default project automatically. The credentials above are for a private local development database only; choose real credentials and network controls for any shared deployment. ::note Plain `postgres:17` does not include pgvector. Use the `pgvector/pgvector:pg17` image or run `CREATE EXTENSION IF NOT EXISTS vector;` on an existing Postgres server before Basic Memory migrates it. :: ## Use the default pgvector index Postgres uses pgvector unless you change `semantic_vector_index`. Build embeddings for already indexed notes with: ```bash bm reindex --embeddings ``` SQLite ignores `semantic_vector_index` and continues to use sqlite-vec. ## Install Milvus support Install Basic Memory with the optional Milvus dependency: ::code-group ```bash [uv] uv tool install 'basic-memory[milvus]' ``` ```bash [pip] pip install 'basic-memory[milvus]' ``` :: The extra supports Milvus Lite on macOS and Linux and remote Milvus or Zilliz Cloud on every supported platform. Windows cannot run Milvus Lite but can connect to a remote deployment. ## Configure Milvus Lite Create the parent directory first, then use an absolute URI ending in `.db`: ```bash mkdir -p "$PWD/.basic-memory-milvus" bm config set semantic_vector_index milvus bm config set milvus_uri "$PWD/.basic-memory-milvus/basic-memory.db" ``` Despite the suffix, Milvus Lite creates a **directory tree** at that path, including `collections/`, `databases/`, and `LOCK`; it does not create one database file. Pymilvus rejects a URI without the `.db` suffix or a URI whose parent directory does not already exist. `milvus_database` is ignored by Milvus Lite because Lite does not support named databases. Leave its default value in place. ## Connect remote Milvus or Zilliz ```bash bm config set semantic_vector_index milvus bm config set milvus_uri http://localhost:19530 bm config set milvus_token root:Milvus ``` For Zilliz Cloud, set its endpoint and token instead. `milvus_timeout_seconds` applies to every client operation and defaults to 30 seconds. Collections reload across processes, so a restart reuses an existing compatible collection. ## Reindex after every index switch Run an incremental embedding rebuild immediately after changing `semantic_vector_index`: ```bash bm reindex --embeddings ``` The incremental rebuild is sufficient; `--full` is not required. Until the configured index has ready rows: - vector search returns no results; - hybrid search quietly serves full-text results only; and - `bm reindex --embeddings` reports which index it populated and exits nonzero on failure. Hands-on verification found identical vector rankings and scores to four decimal places across sqlite-vec, pgvector, and Milvus Lite on the same corpus. Basic Memory also refuses dimension mismatches, reports a missing Milvus extra directly, honors the configured timeout, and reloads collections after restart. ## Switch indexes safely Vector-index ownership is fail-closed. If a switch or switch-back finds manifest rows owned by another index, Basic Memory refuses to mutate them instead of guessing which vector store is authoritative. 1. Restore the previously configured index if a premature switch raises `SemanticVectorIndexExtensionError`. 2. Remove the current index's project-scoped vectors and the corresponding vector-manifest rows while that index is still configured. 3. Change `semantic_vector_index`. 4. Run `bm reindex --embeddings` and confirm it exits successfully. There is no general cleanup command yet. Treat manual vector-store and manifest cleanup as an operator procedure and back up the database first. ::warning Switching from pgvector to Milvus leaves the old rows in Postgres's `search_vector_embeddings` projection. They are not used by the Milvus search path, but they continue to consume disk until you remove them manually. Do not delete them until the Milvus rebuild is successful and you have decided not to switch back using that projection. :: ## Stop local Postgres ```bash docker compose -f docker-compose-postgres.yml down ``` Add `--volumes` only when you intentionally want to delete the local database volume. ## Related pages - [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search) — retrieval modes, reranking, and reindex behavior. - [Configuration](https://docs.basicmemory.com/reference/configuration) — all Postgres, Milvus, and embedding settings. - [Upgrade to v0.23](https://docs.basicmemory.com/whats-new/v0-23-upgrade) — breaking changes and migration notes. # 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. ::tip **Why choose? Get the best of both.** Tell your agent to save this to its memory — one paste, and its built-in memory carries the routing rule from then on: ```text Save this to your memory: Use Basic Memory as my long-term knowledge store — record durable decisions, research, and context there as notes. Keep your built-in memory for short-term working context, and have your memories reference Basic Memory notes for the details. Use Basic Memory's search_notes, recent_activity, and build_context tools to find information before answering questions about past work. ``` Built-in memory becomes the short-term cache; Basic Memory becomes the long-term store — and each knows about the other. For fuller standing instructions (skills, project settings, CLAUDE.md/AGENTS.md), see the [AI Assistant Guide](https://docs.basicmemory.com/reference/ai-assistant-guide). :: --- ## 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, indexed by a `MEMORY.md` file whose first 200 lines 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 --- 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 app](https://docs.basicmemory.com/cloud/note-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 created: 2026-08-01T14:30:00Z modified: 2026-08-10T09:15:00Z --- # 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 created: 2026-08-01T14:30:00Z modified: 2026-08-10T09:15:00Z --- ``` - **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 file's path (and prefixed with the project name by default) if you don't set one. Stays the same even if you later move the file. - **created** and **modified** — Optional authoritative timestamps for the note. When present, Basic Memory uses them for recency ordering instead of filesystem timestamps. Historical `created` or `modified` values can move a note earlier in `recent_activity` and date-sorted search results after the note is reindexed. Use valid date or datetime values and change them only when you intend to change the note's recorded chronology. ::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 does not treat Markdown checkbox markers such as `[ ]` , `[x]` , `[X]` , `[-]` , `[/]` , `[>]` , and `[?]` , or timestamp-shaped transcript prefixes, as categories. :: For category conventions, tags, and worked examples, see the deep dive: [Observations and Relations](https://docs.basicmemory.com/concepts/observations-and-relations). --- ## 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. Quoting rules and edge cases (multi-word types, bare wikilinks) are covered in [Observations and Relations](https://docs.basicmemory.com/concepts/observations-and-relations). 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. ### How wikilinks resolve Basic Memory tries exact identities first: permalink, title, and file path. At the project root, a filename-stem link such as `[[alpha_note]]` can resolve `alpha_note.md` even when the note's frontmatter title is different. If no exact identity matches, Basic Memory can try a Unicode case-insensitive file-path alias that treats underscores and hyphens as equivalent. The fallback must identify exactly one note; `[[alpha-note]]` remains unresolved when multiple files collapse to the same alias. This forgiving lookup applies only to link resolution—writes and updates keep their exact note identity rules and never use the alias to choose a file to overwrite or move. Directory casing is handled separately. Since v0.23.2, each destination-folder segment on a note write or move resolves to an existing folder when there is exactly one case-insensitive match, so `schemas/drafts` can land in `Schemas/Drafts`. Unknown folders are created with the requested spelling, existing case-variant siblings remain ambiguous, and the note's basename is never case-corrected by this folder rule. For relation-type conventions and how inline references index, see [Observations and Relations](https://docs.basicmemory.com/concepts/observations-and-relations). --- ## 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 file path (project-prefixed by default). Permalinks are how Basic Memory addresses notes internally and how `memory://` URLs work — and by default they stay unchanged when a file is renamed or moved: ```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 — the knowledge graph is built from the content of your notes, not from where they sit on disk. See [Projects and Folders](https://docs.basicmemory.com/concepts/projects-and-folders) for organizing with projects and folder structure. ::note `write_note` rejects filename-convention twins instead of creating a duplicate. For example, if a folder already contains the conventional equivalent of `Project Plan.md` , writing `project-plan.md` returns an error. Read or edit the existing note, or choose a genuinely different name. :: --- ## 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 the project you name — each call carries a `project` parameter or CLI argument. If you don't specify one, it goes to the **default project**, and you can target a different project at any time, including mid-conversation. ## 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 simply pass `project="personal"` on its next tool calls — there's no switch step; it discovers your projects with `list_memory_projects`. From the CLI, change the fallback for commands that don't specify a project: ```bash bm project default "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 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 By default, Basic Memory prefixes newly generated permalinks with the project name, so notes with the same title in different projects stay distinct: ```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 when a permalink is generated — existing permalinks aren't rewritten. You don't 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. ### Avoid checkbox and timestamp markers Observation categories are semantic labels, not task state or transcript time. Basic Memory does not index these Markdown checkbox markers as categories: ```markdown - [ ] Not started - [x] Complete - [X] Complete - [-] Canceled - [/] In progress - [>] Deferred - [?] Needs clarification ``` Timestamp-shaped prefixes on transcript lines are also ignored as categories. Use a descriptive label such as `[decision]`, `[status]`, or `[follow-up]` when you want the line indexed as an observation. That includes both a single clock value and a spaced range: ```markdown [24:33.098] Speaker: We should keep the existing API. [24:33.098 - 24:41.260] Speaker: The migration can happen later. ``` Only clock-shaped transcript markers are excluded. A descriptive category that happens to contain time-like text is still treated as a category. ### 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""} .) :: ### Force a generic relation from single-word prose A single token before a wikilink normally looks like an explicit relation type. When that token is prose instead, end the list item with `#bm:links_to`: ```markdown - Mother [[Alice]] #bm:links_to ``` This creates the generic `links_to` relation instead of a `Mother` relation. The directive stays in the Markdown source so the intent is visible, but Basic Memory removes it from the indexed observation and relation text. This syntax was added in v0.23.1. ### 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 list with a leading word have explicit types (`depends_on`, `relates_to`), while inline references create a generic `links_to` connection. Both are useful. Wikilinks resolve exact permalinks, titles, and paths first. Root-level filename stems receive the same `.md` fallback as nested paths. If exact resolution fails, a unique case-insensitive filename alias can bridge underscore/hyphen differences; aliases that match more than one note stay unresolved. See [Knowledge Format](https://docs.basicmemory.com/concepts/knowledge-format#how-wikilinks-resolve) for examples and write-identity rules. ## 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. You can then validate notes on demand — ask your AI to check them (the `schema_validate` tool) or run `bm schema validate` — and the report flags anything that's missing. Validation warns rather than blocking writes. ::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 or permalink ```text memory://auth-approaches-2024 memory://Auth Approaches 2024 ``` Both a permalink and an exact note title resolve. ### By path ```text memory://docs/authentication memory://docs/authentication.md ``` ### By wildcard ```text memory://docs/* memory://auth* ``` --- ## Project-prefixed URLs Memory URLs can include project scope as the first path segment: ```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 — you can write it in a relation: ```markdown - relates_to [[research::specs/api]] ``` The `project::note-path` form is treated as `project/note-path`, and the same syntax works inside `memory://` URLs. 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 URLs resolve to a project by explicit prefix first, then fall back to the default project. The full resolution order — including local-server project constraints — is covered in the [local User Guide](https://docs.basicmemory.com/local/user-guide#memory-url-resolution-local-server); these controls aren't exposed in cloud. --- ## 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 --- Teach your assistant when and how to use Basic Memory. ::: :: # 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. :docs-video{alt="Schema validation catching a bad record, fixed with one sentence" poster="/videos/posters/docs-schema-system.png" src="https://docs.basicmemory.com/videos/docs-schema-system.mp4"} 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 can use it as a creation guide — ask it to check the schema when writing, or install the [memory-schema skill](https://docs.basicmemory.com/integrations/skills) to make this automatic. 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 | 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." With the [memory-schema skill](https://docs.basicmemory.com/integrations/skills) installed (or a standing instruction to check schemas), the AI consults your schemas when creating notes of that type, so your notes 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 ``` The result is a table of notes with their warning and error counts — a valid note shows zero of each. If a note has a frontmatter value outside the allowed enum: ```yaml --- title: Iris West type: person status: retired # not in [draft, published, archived] --- ``` Validation reports: `Frontmatter key 'status' has invalid value: retired (allowed: draft, published, archived)`. 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 ``` Validation reports: `Missing required frontmatter key: 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 # 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 ``` A valid note shows zero warnings and errors in the results table. If `[name]` were missing, validation would report: `Missing required field: name (expected [name] observation)`. --- ## 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 --- Teach your assistant when and how to use Basic Memory. ::: :: # 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. :docs-video{alt="Semantic search answering a plain-language question" poster="/videos/posters/docs-semantic-search.png" src="https://docs.basicmemory.com/videos/docs-semantic-search.mp4"} 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 --> RR{Reranking enabled?} RR -->|No| R[Results] RR -->|Yes| X[Cross-encoder rerank] X --> R --- :: --- ## 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 (for example, after switching embedding providers): ```bash bm reindex --embeddings ``` Changing the Postgres vector index between pgvector and Milvus also requires this command. Until it completes, vector search returns nothing and hybrid search serves full-text results only. Follow [Run Postgres with Milvus](https://docs.basicmemory.com/local/postgres-and-milvus) for setup, switching, and recovery details. Running on an Intel Mac? See [Platform compatibility](https://docs.basicmemory.com/#platform-compatibility) below for a workaround. --- ## Enable reranking Reranking adds a cross-encoder after vector or hybrid retrieval. Retrieval finds a candidate set; the reranker reads the query and each candidate together, then replaces the leading candidates' scores with a more precise relevance order. Text-only search is unchanged. Reranking is opt-in: ```bash bm config set reranker_enabled true ``` The default `fastembed` provider runs locally with `jinaai/jina-reranker-v1-tiny-en`. The first reranked search downloads the model, so expect that first request to take longer. Later requests reuse the cached process-wide model. To use a hosted or self-hosted reranker through LiteLLM: ```bash bm config set reranker_enabled true bm config set reranker_provider litellm bm config set reranker_model cohere/rerank-v3.5 export COHERE_API_KEY=... ``` LiteLLM models use explicit `provider/model` names. You can set `reranker_api_base` for a custom endpoint and `reranker_api_key` to pass the credential directly; otherwise LiteLLM uses its normal provider environment variables. ### Choose a provider | Provider | Runs | Default model | Tradeoff | | ----------- | ------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `fastembed` | Local ONNX | `jinaai/jina-reranker-v1-tiny-en` | No API key or per-query cost; downloads on first use and adds local inference latency. | | `litellm` | Hosted or self-hosted API | Set an explicit `provider/model` | Supports Cohere, Jina, Voyage, and other LiteLLM rerank providers; adds network latency, provider cost, and credential requirements. | ### Configure reranking | Config field | Default | Description | | ----------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `reranker_enabled` | `false` | Enable cross-encoder reranking for vector and hybrid search; semantic search must also be enabled. | | `reranker_provider` | `fastembed` | Use local `fastembed` or API-backed `litellm`. | | `reranker_model` | `jinaai/jina-reranker-v1-tiny-en` | Model identifier; LiteLLM requires `provider/model` form. | | `reranker_candidates` | `20` | Number of leading retrieval candidates to rescore. Larger windows can improve recall but cost more time or provider usage. | | `reranker_max_document_chars` | `0` | Maximum candidate characters sent to the cross-encoder. `0` sends the full matched text. | | `reranker_timeout` | `30.0` | Maximum seconds per LiteLLM request. FastEmbed ignores this setting. | | `reranker_api_base` | unset | Custom API base for a self-hosted LiteLLM reranker. | | `reranker_api_key` | unset | Credential passed directly to LiteLLM; normal provider environment variables work when unset. | Every field is also available as `BASIC_MEMORY_`. See [Configuration](https://docs.basicmemory.com/reference/configuration#reranker-settings) for types and environment-variable names. ### Tune latency Reranking cost depends heavily on candidate length and count: - Short-note benchmarks add about **90 ms at p50** with the default local model and settings. - In a long transcript-chunk benchmark, p95 latency rose from **420 ms to about 2.1 seconds** when reranking was enabled — about **5×** — while retrieval quality improved. - Lower `reranker_candidates` when a smaller recall window still contains the right results. - Set `reranker_max_document_chars` to a positive cap for long notes or transcript chunks. The matched chunk leads the reranker document, so the strongest retrieval signal is kept first. Measure quality on your corpus before standardizing a cap; the v0.23 default remains unbounded. Changing reranker settings does not change stored embeddings, so it does not require `bm reindex --embeddings`. ### Handle reranker failures An enabled reranker is part of the requested ranking contract. Basic Memory deliberately does not fall back to the original retrieval order when reranking fails: - Temporary provider, rate-limit, connection, timeout, or first-download failures return HTTP `503` so callers can retry. - Malformed or incomplete provider responses return HTTP `502`. - Authentication, model, dependency, and permanent configuration failures surface directly. - A retryable failure from any project aborts a multi-project result page instead of returning partially reranked results. Disable reranking if retrieval-only results are preferable to a failed request in your application. --- ## 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 Results are returned as note-level items — plus individual observations and relations — ranked by their best-matching chunks, 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. Question-form queries rarely match every keyword, so when the strict all-words text query comes back empty, hybrid search retries it as a relaxed any-word query rather than letting the text half go silent. As of v0.23 this relaxation works for queries in any script — CJK, Cyrillic, Greek, Arabic, and other non-Latin alphabets included. SQLite and PostgreSQL both search complete note bodies. Since v0.23.1, PostgreSQL stores long bodies in bounded, overlapping full-text chunks, allowing deep matches and preserving Boolean query behavior across chunk boundaries. The upgrade migration backfills existing notes automatically. A later `bm reindex --search` replaces rows only for the selected project; it does not clear sibling projects that share the same database. ### 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 The settings you're most likely to tune: | Config field | Default | Description | | ----------------------------- | ------------- | ---------------------------------------------------------------------------- | | `semantic_search_enabled` | `true` | Enable semantic search | | `semantic_embedding_provider` | `"fastembed"` | Common values: `fastembed` (local), `openai` (API) | | `semantic_min_similarity` | `0.55` | Minimum similarity threshold | | `semantic_vector_index` | `"pgvector"` | Postgres vector index: `pgvector` or `milvus`; SQLite always uses sqlite-vec | | `reranker_enabled` | `false` | Opt in to cross-encoder reranking of vector and hybrid candidates | The full list — models, dimensions, batch size, vector candidates, env vars — is in the [Configuration reference](https://docs.basicmemory.com/reference/configuration#semantic-search-settings). ### 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 #### Configure a custom FastEmbed model Choose a model from FastEmbed's installed catalog and set its actual output dimensions. Some asymmetric models also require different literal prompts for indexed passages and search queries; Basic Memory does not infer these model-specific prefixes. For example, configure multilingual E5 with its 1024 dimensions and required `passage: `/ `query: `prefixes: ```bash bm config set semantic_embedding_provider fastembed bm config set semantic_embedding_model intfloat/multilingual-e5-large bm config set semantic_embedding_dimensions 1024 bm config set semantic_embedding_document_prefix "passage: " bm config set semantic_embedding_query_prefix "query: " bm reindex --embeddings ``` The trailing spaces are part of the model input. Rebuild embeddings after changing the model, dimensions, or either prefix so document and query vectors use the same contract. The default BGE model is symmetric and does not need prefixes. ### 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** (uv installs) ```bash uv tool install basic-memory --with 'onnxruntime<1.24' bm reindex --embeddings ``` For MCP configs that launch via `uvx`, use `uvx --with 'onnxruntime<1.24' basic-memory mcp`. Homebrew installs can't pin the runtime — use the OpenAI option or switch to a uv install. --- ## Reindexing ```bash # Incremental reindex of search index and embeddings (skips unchanged content) bm reindex # Force a full rebuild, re-embedding everything bm reindex --full # 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 - **Switching the Postgres vector index** — Run `bm reindex --embeddings` after changing between pgvector and Milvus; the incremental rebuild is enough - **After a database reset** — `bm reset` clears everything - **Troubleshooting** — a full rebuild (`bm reindex --full`) can fix index issues; the default run is incremental and skips unchanged content `bm reindex --embeddings` exits nonzero if any embedding fails. Treat that as an incomplete vector index and fix the reported provider or index error before retrying. An incremental `bm reindex --search` also reconciles stale full-text rows, including orphaned entries for files whose contents have not changed. Try it before a full rebuild when text search returns content that was removed from disk or the current index. --- ## Inspecting retrieval Two read-only CLI commands, new in v0.23, show what search actually did — so you can tell an indexing problem from a ranking problem: ```bash # Is this note indexed, embedded, and current? bm inspect chunks "my-note" # What stages did this query run, and why did results rank the way they did? bm inspect query "how do we handle auth" --mode hybrid bm inspect query "auth" --mode vector --show-misses ``` `inspect chunks` shows a note's search rows and vector chunks with a per-chunk status (`ready`, `pending`, `stale`, or `orphaned`). `orphaned` means the chunk was embedded under a different model or vector index than the one configured — the classic "I switched models and now vector search finds nothing" state, fixed by `bm reindex --embeddings`. `inspect query` traces one search execution — matching, filtering, fusion, reranking, and the final page — with scores and rerank movement, captured from the same call that returned the results. Add `--show-misses` to see why near-miss candidates were dropped. See the [CLI Reference](https://docs.basicmemory.com/reference/cli-reference#retrieval-inspection-commands) for all flags and the JSON output contract. --- ## 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). - **Enable reranking.** If retrieval finds the right material but orders it poorly, opt in with `bm config set reranker_enabled true`, then measure the added latency on your notes. - **Check that embeddings are built.** Run `bm reindex --embeddings` to make sure the index is up to date. - **Inspect what retrieval did.** `bm inspect query "your query" --show-misses` shows every stage and why candidates were dropped; `bm inspect chunks ` shows whether a note you expected is embedded and current. See [Inspecting retrieval](https://docs.basicmemory.com/#inspecting-retrieval). - **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. :docs-video{alt="Filtering notes by frontmatter fields in Structured search" poster="/videos/posters/docs-metadata-search.png" src="https://docs.basicmemory.com/videos/docs-metadata-search.mp4"} 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. :: ::note Observation categories such as `[decision]` , `[rule]` , or `[follow-up]` are not frontmatter fields — see [Searching observations by category](https://docs.basicmemory.com/#searching-observations-by-category) below instead of `metadata_filters` . :: --- ## 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 or string | Comparison (gte/lte inclusive); strings compare lexicographically — dates as ISO strings | | `$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 tag:alpha") # repeated tag: tokens # Both require BOTH tags to be present. ``` A bare word after a `tag:` token isn't a tag — `"tag:tier1 alpha"` filters on `tier1` and treats `alpha` as ordinary query text. 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]}}` | | Decisions since April | `{"type": "decision", "date": {"$gte": "2026-04-01"}}` — dates compare as ISO strings | | 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}}` | --- ## Searching observations by category Observation categories (`- [decision] ...`, `- [rule] ...`) live on observations, not in frontmatter — so they get their own filter, `categories`, instead of `metadata_filters`: ```python # All decision observations, anywhere search_notes(categories=["decision"]) # Decisions mentioning auth search_notes("auth", categories=["decision"], entity_types=["observation"]) ``` Matching is exact, and when you pass `categories` without `entity_types`, results default to observations. From the CLI: ```bash bm tool search-notes "auth" --entity-type observation --category decision ``` --- ## 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) # Connect AI tools Basic Memory is most useful when the AI tools you already use can read and write the same shared knowledge base. Start with the tool you use most, then connect others to the same workspace as needed. ::tip For Basic Memory Cloud, install the published **Basic Memory Cloud** plugin from ChatGPT's Plugin directory or the published **Basic Memory Cloud** connector from Claude's Connectors Directory. The web app's Help Center (account menu → **Help**) also has setup guidance, your MCP endpoint for manual connections, and a quick test prompt. For local/open-source Basic Memory, use the local MCP server from your computer. See [Local MCP tools](https://docs.basicmemory.com/local/mcp-tools-local). :: --- ## Recommended Cloud Connections These are the best starting points for most Basic Memory Cloud users. ::card-group :::card --- icon: i-simple-icons-anthropic title: Claude to: https://docs.basicmemory.com/integrations/claude-desktop --- Install the published connector from Claude's Connectors Directory. One connection works across web, desktop, mobile, Cowork, and Claude Code. ::: :::card --- icon: i-simple-icons-anthropic title: Claude Code to: https://docs.basicmemory.com/integrations/claude-code --- Give Claude Code access to shared project knowledge while you work in a repository. ::: :::card --- icon: i-lucide-code title: Codex to: https://docs.basicmemory.com/integrations/codex --- Use Basic Memory from the Codex app and CLI. ::: :::card --- icon: i-simple-icons-openai title: ChatGPT to: https://docs.basicmemory.com/integrations/chatgpt --- Install Basic Memory Cloud from ChatGPT's Plugin directory, then start from the listing or enable it in an existing chat. ::: :: --- ## Coding And Local Editors Use these when you work from a code editor, terminal agent, or synced Markdown folder. ::card-group :::card --- icon: i-simple-icons-googlegemini title: Gemini CLI to: https://docs.basicmemory.com/integrations/gemini --- Connect Google's command-line AI agent through MCP. ::: :::card --- icon: i-lucide-mouse-pointer-2 title: Cursor to: https://docs.basicmemory.com/integrations/cursor --- Use Basic Memory knowledge while coding in Cursor. ::: :::card --- icon: i-lucide-code-2 title: VS Code to: https://docs.basicmemory.com/integrations/vscode --- Work with Basic Memory from VS Code and local Markdown files. ::: :::card --- icon: i-lucide-notebook title: Obsidian to: https://docs.basicmemory.com/integrations/obsidian --- Use Obsidian as a local editor for Basic Memory Markdown projects. ::: :: --- ## Extensions And Agent Workflows These integrations add richer workflows on top of the core MCP connection. ::card-group :::card --- icon: i-lucide-sparkles title: Agent Skills to: https://docs.basicmemory.com/integrations/skills --- Optional instruction packs that teach agents when and how to use Basic Memory well. ::: :::card --- icon: i-lucide-bot title: OpenClaw to: https://docs.basicmemory.com/integrations/openclaw --- Use the OpenClaw plugin for bundled Basic Memory tools and skills. ::: :::card --- icon: i-lucide-send title: Hermes to: https://docs.basicmemory.com/integrations/hermes --- Use Hermes for Basic Memory-aware agent workflows. ::: :: --- ## Choosing Cloud Or Local - **Use Cloud** when you want the web app, remote MCP, collaboration, and the same knowledge available from multiple tools or devices. - **Run locally** when you want files and indexing to stay on your machine, or when your AI client expects a local stdio MCP server. - **Use both** when you want Cloud for shared projects and local files for editor-first workflows. Not sure? Start with [Quickstart: Cloud](https://docs.basicmemory.com/start-here/quickstart-cloud). # 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 Basic Memory is published in Claude's **Connectors Directory**. This is the recommended way to connect Basic Memory Cloud. :docs-video{alt="Installing the Basic Memory Cloud connector in Claude and verifying it" poster="/videos/posters/docs-connect-claude.png" src="https://docs.basicmemory.com/videos/docs-connect-claude.mp4"} ::steps ### Sign Up Create your account at [basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=claude-desktop){rel=""nofollow""} ### Open the Connectors Directory Open the [Claude Directory](https://claude.ai/directory){rel=""nofollow""}. You can also go to **Settings → Customize → Connectors** and select **+**. From a chat, select **+ → Connectors → Manage connectors**, then select **+** next to Connectors. ### Find Basic Memory Cloud Search for **Basic Memory Cloud** and open the published connector. Review its description and capabilities. ![Basic Memory Cloud in Claude's Connectors Directory](https://docs.basicmemory.com/screenshots/claude/connectors-directory-basic-memory-cloud.jpg) ### Connect Select **Install**, then complete the Basic Memory authorization flow. If it is already connected, the directory shows **Manage** instead. ### Verify Setup Return to a chat and ask: ```text List my Basic Memory projects. ``` :: ::tip Claude remote connectors work across Claude on the web, Claude Desktop, mobile, Cowork, and Claude Code. Once connected to your Claude account, no separate setup is needed on each surface. :: ## Manual Cloud Setup Use the custom-connector flow only if the directory listing is unavailable or you specifically need to add the MCP endpoint yourself. ::steps ### Open connector settings In Claude Desktop or Claude.ai, go to **Settings → Customize → Connectors**. ![Claude Settings - Connectors](https://docs.basicmemory.com/screenshots/claude/settings-connectors.png) ### Add a custom connector Select **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 Select **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) ### Configure Tools (Optional) Select **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 in chat. ![Claude - Tools menu](https://docs.basicmemory.com/attachments/claude-tools-menu.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 Install Basic Memory first — see [Quickstart: Local](https://docs.basicmemory.com/start-here/quickstart-local) for the Homebrew and uv install commands. ### Edit the Claude Desktop config | 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"] } } } ``` ::note **Installed with Homebrew?** Use `"command": "basic-memory", "args": ["mcp"]` instead — `uvx` only exists if you installed uv. :: ::warning **ENOENT error?** Use the full path to the command. Find it with `which uvx` (or `which basic-memory` for Homebrew installs) and replace the `"command"` value with the full path (e.g., `"/Users/yourname/.local/bin/uvx"` ). :: ### Restart and verify Restart Claude Desktop, then open the **search and tools** menu in the chat input area — Basic Memory tools should be listed. ![Claude - Tools menu with Basic Memory](https://docs.basicmemory.com/screenshots/claude/tools-menu-local.png) --- ## 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. **Open your knowledge base in the conversation:** ```text Open Basic Memory ``` Claude displays the **[Pocketbook](https://docs.basicmemory.com/cloud/mcp-app)** — a working interface inside the chat. Browse folders and notes, open the full editor to make changes in place, or point the agent at a folder so new notes land where you want them. :docs-video{alt="Pocketbook running inside Claude Desktop" poster="/videos/posters/docs-pocketbook-claude.png" src="https://docs.basicmemory.com/videos/docs-pocketbook-claude.mp4"} 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 - **Directory connector**: Open **Settings → Customize → Connectors** and confirm Basic Memory is connected. In a managed workspace, an owner may need to enable the connector first. - **Custom cloud connector**: Re-open Claude Desktop after adding it. 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. ### Tools appear but return errors - **Cloud**: check the [Activity view](https://docs.basicmemory.com/cloud/web-app#activity) for failed operations, or disconnect and reconnect the connector. - **Local**: check Basic Memory is installed (`basic-memory --version`), verify project index status (`basic-memory status`), and check file permissions in your `~/basic-memory` directory. ### Changes not showing up (local) - Real-time sync is on by default. Run `basic-memory status` to confirm. - Make sure the file is in the correct project directory. - If the index is stale, rebuild it with `bm reindex` (file watching runs automatically inside the MCP server). ### 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" } ``` For Claude's current platform instructions, see [Use connectors to extend Claude's capabilities](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities){rel=""nofollow""}. --- ## 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. ::: :: # 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 [basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=claude-code){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 In Claude Code, run `/mcp`, select **basic-memory-cloud**, and choose **Authenticate** to complete the OAuth flow in your browser. ### Verify Re-run `/mcp` and confirm the Basic Memory tools are listed. :: ::tip The [Cloud Guide](https://docs.basicmemory.com/cloud/cloud-guide) covers the rest of cloud — web app, CLI, snapshots, and migration. For problems, see [Troubleshooting](https://docs.basicmemory.com/reference/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 project index status: `basic-memory status` - Look for errors in `~/.basic-memory/basic-memory.log` --- ## 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. --- ::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 every Basic Memory tool. ::: :::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-activity title: Harness Capture to: https://docs.basicmemory.com/integrations/harness-capture --- Understand SessionStart, PreCompact, checkpoint, capture, and hook health behavior. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Structure effective development 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 Install Basic Memory first if you haven't — see [Quickstart: Local](https://docs.basicmemory.com/start-here/quickstart-local) — or run it without installing via `uvx`: ```bash basic-memory mcp --transport streamable-http --port 8000 # or, with no install: uvx 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** — Check the MCP config (`codex mcp list`) and re-add the server if the entry looks wrong; for a local uvx setup, verify uvx can run it (`uvx basic-memory --version`): ```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 project index 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-activity title: Harness Capture to: https://docs.basicmemory.com/integrations/harness-capture --- Understand SessionStart, PreCompact, post-compaction checkpoints, and hook health. ::: :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- Structure effective development documentation. ::: :: # ChatGPT Basic Memory Cloud is available in ChatGPT's **Plugin directory**. Connecting the published plugin is the recommended setup; it does not require Developer mode or a server URL. Since ChatGPT connects to the hosted service, **Basic Memory Cloud is required**. ## Install from the Plugin directory :docs-video{alt="Installing the Basic Memory Cloud plugin in ChatGPT and using it in a chat" poster="/videos/posters/docs-connect-chatgpt.png" src="https://docs.basicmemory.com/videos/docs-connect-chatgpt.mp4"} ::steps ### Open Basic Memory Cloud Open [Basic Memory Cloud in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6a49590bf6348191a16c0b87ca6b01b4){rel=""nofollow""}. You can also select **Plugins** in the ChatGPT sidebar and search for **Basic Memory Cloud**. ![Basic Memory Cloud in ChatGPT's Plugin directory](https://docs.basicmemory.com/screenshots/chatgpt/plugin-directory-basic-memory-cloud.jpg) ### Connect your account Select **Connect** and complete the Basic Memory authorization flow. If you do not have an account yet, you can create one during sign-in. ### Start a chat Select **Try in chat** from the plugin page. In an existing conversation, type `@` and choose **Basic Memory Cloud**, or select **+ → More → Basic Memory Cloud**. ### Verify the connection Ask: ```text List my Basic Memory projects. ``` :: ::tip See the [Cloud Guide](https://docs.basicmemory.com/cloud/cloud-guide) for account setup, the web app, and sync options. :: ## Manual setup with custom MCP Use this only when you need a custom MCP connection or cannot use the published plugin. Plugin-directory users can skip Developer mode entirely. ::steps ### Create a Basic Memory account Sign up at [basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=chatgpt){rel=""nofollow""}. ### Enable Developer mode In ChatGPT, go to **Settings → Apps & Connectors → Advanced settings** and enable **Developer mode**. ### Add the MCP server Select **Create** and enter: - **Name**: Basic Memory - **Server URL**: `https://cloud.basicmemory.com/mcp` ### Authenticate and enable Complete the OAuth flow, then select Basic Memory from the app or MCP selector in your conversation. :: ## 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" — the default `search` tool already searches semantically (hybrid mode) ChatGPT will call the appropriate tools behind the scenes, searching and fetching documents as needed. ## Use the interactive Basic Memory app When you ask to open or browse Basic Memory, ChatGPT can display the **Pocketbook** directly in the conversation. From there you can switch projects and folders, browse or search notes, explore the graph, follow wiki links, edit notes, toggle tasks, and work through comments and suggested edits. :docs-video{alt="Pocketbook inside a ChatGPT conversation" poster="/videos/posters/docs-pocketbook.png" src="https://docs.basicmemory.com/videos/docs-pocketbook.mp4"} Try: ```text Open Basic Memory search for quarterly planning. ``` If you only ask a question about your notes, ChatGPT uses the normal search and read tools instead of opening the interface. See [Pocketbook](https://docs.basicmemory.com/cloud/mcp-app) for the full workflow. ## Important Notes ::warning Plugin availability can depend on your ChatGPT plan, region, workspace settings, and role. If **Connect** is unavailable or marked **Disabled by admin** , ask your workspace admin to enable the plugin and its Basic Memory Cloud app. :: ::note **Plugin and app terminology** ChatGPT calls the directory listing a **plugin**. The plugin contains the **Basic Memory Cloud app**, which connects ChatGPT to your knowledge base. You may see both terms in ChatGPT's settings. :: ## Troubleshooting **Plugin not found** — Open the [direct plugin page](https://chatgpt.com/plugins/plugin_asdk_app_6a49590bf6348191a16c0b87ca6b01b4){rel=""nofollow""} or search the Plugin directory for the exact name **Basic Memory Cloud**. **Connect is disabled** — Your plan, region, role, or workspace policy may restrict the app. In a managed workspace, ask an admin to review **Workspace settings → Plugins** and the underlying app in **Workspace settings → Apps**. **Authentication errors** — Disconnect and reconnect the Basic Memory Cloud app, then complete the OAuth flow again. If you used the manual custom MCP flow, remove and re-add that server. **Basic Memory is not used in a chat** — Type `@Basic Memory Cloud` or select **+ → More → Basic Memory Cloud**. Starting from **Try in chat** on the plugin page also creates a conversation with it enabled. **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""}. For ChatGPT's current platform instructions, see [Plugins in ChatGPT and Codex](https://help.openai.com/en/articles/20001256-plugins-in-chatgpt-and-codex){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 every MCP tool. ::: :::card --- icon: i-lucide-panels-top-left title: Pocketbook to: https://docs.basicmemory.com/cloud/mcp-app --- Browse and edit Basic Memory inside a compatible conversation. ::: :::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 [basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=gemini){rel=""nofollow""}. ### Add the Remote MCP Server ```bash gemini mcp add -t http basic-memory-cloud https://cloud.basicmemory.com/mcp ``` ### Authenticate Start `gemini` — your browser opens to authorize Basic Memory Cloud (or run `/mcp auth basic-memory-cloud` inside Gemini). ### 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 uvx can run it (`uvx 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/basic-memory.log`. --- ## 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. ::: :: # OpenClaw Plugin The [openclaw-basic-memory](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/openclaw){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 and lives in the basic-memory monorepo — browse the source in [`integrations/openclaw`](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/openclaw){rel=""nofollow""}. ::tip Requires [OpenClaw](https://openclaw.dev){rel=""nofollow""} and [uv](https://docs.astral.sh/uv/){rel=""nofollow""} ( `brew install uv` or the curl installer). The plugin auto-installs the `bm` CLI via uv on first startup if it's not already on your PATH. :: --- ## Installation :docs-video{alt="Installing the plugin and pointing it at a Basic Memory Cloud project" poster="/videos/posters/docs-openclaw-cloud.png" src="https://docs.basicmemory.com/videos/docs-openclaw-cloud.mp4"} Install the plugin and restart the gateway: ```bash openclaw plugins install @basicmemory/openclaw-basic-memory openclaw gateway restart ``` That's the whole install. It enables the plugin and claims OpenClaw's `memory` slot for you — you should see it report: ```text Exclusive slot "memory" switched from "memory-core" to "openclaw-basic-memory". Installed plugin: openclaw-basic-memory ``` Verify with `openclaw plugins doctor`, which prints the project it resolved and `No plugin issues detected.` By default the plugin creates and uses a project named `openclaw-{hostname}`. To point it at a project you already have, add a `config` block in `~/.openclaw/openclaw.json`: ```json5 { plugins: { entries: { "openclaw-basic-memory": { enabled: true, config: { project: "My Project" } } } } } ``` ::note OpenClaw needs to be working with a model provider before any of this. Setting that up is covered in OpenClaw's own documentation, not here. :: ### Using Basic Memory Cloud By default the plugin writes to a **local** project on that machine. If you want your agent's memory in Basic Memory Cloud — synced across devices, shared with a team, reachable from hosted agents — point it at a cloud-routed project. Sign in once: ```bash bm cloud login ``` Then either use a project you already have, or create one routed to Cloud: ```bash bm project add my-agent --cloud --workspace "My Workspace" ``` Name that project for the plugin: ```bash openclaw config set plugins.entries.openclaw-basic-memory.config.project "my-agent" ``` That writes the same thing you could set by hand in `~/.openclaw/openclaw.json`: ```json5 { plugins: { entries: { "openclaw-basic-memory": { enabled: true, config: { project: "my-agent" } } } } } ``` `openclaw plugins doctor` will report the project it resolved. Confirm the routing with `bm project list` — the project's **Route** column should read `cloud`. From then on everything the agent writes lands in your cloud workspace, and anything already there is available to it. --- ## Configuration The plugin works out of the box with `enabled: true`. For advanced setups, configure via your OpenClaw plugin settings: | Option | Default | Description | | ------------- | --------------------- | --------------------------------------------------- | | `project` | `openclaw-{hostname}` | Basic Memory project name | | `projectPath` | `.` (workspace root) | 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. :docs-video{alt="An agent recalling open tasks at session start, then writing back to the note" poster="/videos/posters/docs-openclaw-remembers.png" src="https://docs.basicmemory.com/videos/docs-openclaw-remembers.mp4"} ### 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, then pass the optional `project` parameter on any tool call to operate on a different project. 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 Basic Memory's 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, replace section) | | `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 Three built-ins, plus one command per bundled skill (the skill name minus the `memory-` prefix): | Command | Description | | ------------------------------------------------------------------ | ---------------------------------------------------- | | `/bm-setup` | Install or update the Basic Memory CLI (requires uv) | | `/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 | | `/notes`, `/ingest`, `/lifecycle`, `/metadata-search`, `/research` | One per remaining bundled skill | --- ## Bundled Skills The plugin bundles a core subset of the [skills collection](https://docs.basicmemory.com/integrations/skills) — drawn from the same source, covering note format, tasks, schemas, reflection, defrag, metadata search, ingest, lifecycle, and research. No separate install needed for those. ::note Skills not bundled (like memory-capture, memory-continue, memory-curate, and memory-literary-analysis) can be installed from the [full collection](https://docs.basicmemory.com/integrations/skills) . :: --- ## 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/basic-memory/tree/main/integrations/openclaw --- Source code, issues, and contributing guide. ::: :: # Hermes Plugin The [hermes-basic-memory](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/hermes){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 and lives in the basic-memory monorepo — browse the source in [`integrations/hermes`](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/hermes){rel=""nofollow""}. ::warning **Slash commands may need a Hermes Agent-side patch.** The plugin's agent tools ( `bm_*` ) and auto-capture work as documented once installed. On affected Hermes Agent releases, the native `/bm-*` **slash commands** don't appear in gateway sessions — a Hermes plugin-loading gap (exclusive memory-provider plugins aren't loaded during gateway slash-command discovery), not a plugin bug. **How to tell if you're affected:** install the plugin, restart the gateway, and type `/bm-` — if no commands autocomplete, apply the Hermes Agent-side patch in [MONKEYPATCH.md](https://github.com/basicmachines-co/basic-memory/blob/main/integrations/hermes/MONKEYPATCH.md){rel=""nofollow""} (it also lists affected versions). This affects only the slash-command surface; nothing else on this page depends on it. :: ::tip [Hermes Agent](https://github.com/NousResearch/hermes-agent){rel=""nofollow""} (see the installation note below — managed install is blocked on every current release) 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 ::warning **Managed install is currently blocked upstream.** This plugin ships `manifest_version: 2`, but `hermes plugins install` caps at version 1 on every released Hermes Agent (latest: v0.20.5 / `v2026.8.19`), so the command fails with *"requires manifest\_version 2, but this installer only supports up to 1."* The fix is [an open pull request](https://github.com/NousResearch/hermes-agent/pull/85893){rel=""nofollow""} that has not shipped in a release yet, so updating Hermes will not help. Until it lands, clone the repo and link the plugin in directly — the Hermes *runtime* loads manifest v2 without trouble; only the installer is capped: ```bash git clone https://github.com/basicmachines-co/basic-memory.git ln -snf "$PWD/basic-memory/integrations/hermes" ~/.hermes/plugins/basic-memory ``` :: Install the plugin: ```bash hermes plugins install basicmachines-co/basic-memory/integrations/hermes ``` 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 ``` ### Using Basic Memory Cloud By default the plugin runs in **local** mode and writes to a project on that machine. In cloud mode, tool calls route directly through the Basic Memory Cloud API — no local file mirror, no bisync. Sign in, then create a cloud-routed project: ```bash bm cloud login bm project add hermes-memory-cloud bm project set-cloud hermes-memory-cloud --workspace "My Workspace" ``` `--workspace` is required if you belong to more than one; otherwise it resolves the only one available. Then point the plugin at it in `~/.hermes/basic-memory.json` (or run `hermes memory setup basic-memory`): ```json { "mode": "cloud", "project": "hermes-memory-cloud" } ``` Restart the gateway and confirm with `hermes memory status`. Check the routing with `bm project list` — the project's **Route** column should read `cloud`. ::note In cloud mode the plugin does **not** create the project for you, unlike local mode. Create it first with the commands above, or initialization fails. :: ```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 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 affected Hermes Agent releases, these commands require the Hermes Agent-side patch in [MONKEYPATCH.md](https://github.com/basicmachines-co/basic-memory/blob/main/integrations/hermes/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 — a longer reference doc on top of the short usage guidance the plugin always injects into the agent's context. It covers 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/basic-memory/tree/main/integrations/hermes --- Source code, issues, and contributing guide. ::: :: # 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 [basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=cursor){rel=""nofollow""} ### Configure Remote MCP in Cursor Add the server to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project root — you can also reach this from **Cursor Settings → MCP**: ```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 to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project) — see the [Cursor MCP docs](https://cursor.com/docs/context/mcp){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 uvx can run it (`uvx 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** — Verify project directory permissions. If you installed the CLI (`uv tool install basic-memory`), run `basic-memory status` to check sync — `which basic-memory` only resolves for installed setups, not uvx. **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 [basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=vscode){rel=""nofollow""} :::note The sync workflow needs the Basic Memory CLI — see [Local Installation](https://docs.basicmemory.com/local/local-install) for setup. ::: ### Log In to Basic Memory Cloud Authenticate with your account: ```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 local workspace: ```bash # For a project-specific docs folder bm project add my-project --cloud --local-path ~/workspace/my-project/docs # Or for a shared knowledge base bm project add knowledge --cloud --local-path ~/Documents/knowledge ``` Full setup mechanics — conflicts, one-way mirrors, team workspaces — are in the [Cloud Sync Guide](https://docs.basicmemory.com/cloud/cloud-sync). ### Pull Your Project Down Preview and run the initial pull: ```bash # Preview first (recommended) bm cloud pull --name my-project --dry-run # Fetch the cloud files bm cloud pull --name my-project ``` ### 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 Pull cloud changes down before you start, push local changes up when you're done: ```bash bm cloud pull --name my-project bm cloud push --name my-project ``` Changes flow both directions — additively, so nothing gets deleted on either side. :: ::note **Additive sync** : `pull` and `push` never delete files on the destination. If the same note changed on both sides, the command aborts and lists the conflicts — resolve with `--on-conflict` . See the [Cloud Sync Guide](https://docs.basicmemory.com/cloud/cloud-sync) for details. :: --- ## 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 ~/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 echo "Decided to version the API from day one" | 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. Add Basic Memory in your VS Code MCP settings — local: command `uvx` with args `["basic-memory", "mcp"]`; cloud: the remote endpoint `https://cloud.basicmemory.com/mcp` — 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 project index 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 pull --name my-project --dry-run` to preview before syncing, and use `--on-conflict` to choose what survives. 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 [basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=obsidian){rel=""nofollow""} ### Log In to Basic Memory Cloud Authenticate with your account: ```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 --cloud --local-path ~/path/to/obsidian-vault # Or create a new project bm project add notes --cloud --local-path ~/Documents/notes ``` ### First Sync **Existing vault?** The new cloud project is empty — push your notes up to seed it: ```bash bm cloud push --name my-vault --dry-run bm cloud push --name my-vault ``` **Notes already in cloud?** Pull them down instead: ```bash bm cloud pull --name my-vault --dry-run bm cloud pull --name my-vault ``` The login/setup mechanics are covered in full in the [Cloud Sync Guide](https://docs.basicmemory.com/cloud/cloud-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, push your changes up; after changes land in the cloud (AI assistants, web app), pull them down: ```bash bm cloud pull --name my-vault bm cloud push --name my-vault ``` :: ::note **Additive sync** : `pull` and `push` never delete files on the destination. If the same note changed on both sides, the command aborts and lists the conflicts — resolve with `--on-conflict` . See the [Cloud Sync Guide](https://docs.basicmemory.com/cloud/cloud-sync) for details. :: --- ## 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. 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. **Notes not syncing to cloud**: Run `bm cloud push --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"} Sync your vault with cloud using push and pull. ::: :::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 ready-made instructions that help Claude and ChatGPT use Basic Memory well. They teach your assistant when to save something, how to organize it, and how to pick up where you left off. ::tip New to Basic Memory? Start with [**memory-onboarding**](https://docs.basicmemory.com/#choose-a-skill) . It guides you through setting up a useful knowledge system by asking a few questions and doing the technical work for you. :: --- ## Install a skill in Claude or ChatGPT ### Add the skill to Claude 1. [Choose a skill](https://docs.basicmemory.com/#choose-a-skill) from the list below. 2. Open **Customize → Skills** and click **+**. 3. Choose **Upload a skill** and select its `SKILL.md` file. For `memory-onboarding`, upload the packaged ZIP instead. 4. Turn the skill on. [See Claude's walkthrough with screenshots](https://support.claude.com/en/articles/12512180-getting-started-with-skills-on-claude-ai){rel=""nofollow""}. ### Add the skill to ChatGPT 1. [Choose a skill](https://docs.basicmemory.com/#choose-a-skill) from the list below. 2. Click your **profile icon → Skills**. 3. Choose **New skill → Upload from your computer** and select its `SKILL.md` file. For `memory-onboarding`, upload the packaged ZIP instead. 4. Wait for ChatGPT to finish scanning it. [See the ChatGPT skills walkthrough](https://help.openai.com/en/articles/20001066-skills-in-chatgpt){rel=""nofollow""}. --- ## Choose a skill Most skills are a single `SKILL.md` file that you can upload directly. **memory-onboarding** includes supporting reference files, so it uses a packaged ZIP. | Skill | Purpose | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | [**memory-onboarding**](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-onboarding.zip){rel=""nofollow""} | Guided setup — interview, design, and build a complete knowledge system from scratch | | [**memory-notes**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-notes/SKILL.md){rel=""nofollow""} | Core note format — frontmatter, observations, relations, memory:// URLs | | [**memory-capture**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-capture/SKILL.md){rel=""nofollow""} | Capture the state of a working thread into a single coherent note | | [**memory-continue**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-continue/SKILL.md){rel=""nofollow""} | Resume prior work by rebuilding context from the knowledge graph | | [**memory-tasks**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-tasks/SKILL.md){rel=""nofollow""} | Structured task tracking that survives context compaction | | [**memory-schema**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-schema/SKILL.md){rel=""nofollow""} | Schema lifecycle — infer, validate, create definitions, detect drift | | [**memory-curate**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-curate/SKILL.md){rel=""nofollow""} | Find orphan notes, propose relations, merge duplicates, build hub notes | | [**memory-reflect**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-reflect/SKILL.md){rel=""nofollow""} | Review conversations, extract insights, consolidate knowledge | | [**memory-defrag**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-defrag/SKILL.md){rel=""nofollow""} | Split bloated files, merge duplicates, restructure hierarchy | | [**memory-lifecycle**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-lifecycle/SKILL.md){rel=""nofollow""} | Status transitions through folder-based organization, archive-never-delete | | [**memory-metadata-search**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-metadata-search/SKILL.md){rel=""nofollow""} | Query notes by custom frontmatter fields (equality, range, array filters) | | [**memory-ingest**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-ingest/SKILL.md){rel=""nofollow""} | Process transcripts, emails, and documents into structured notes | | [**memory-research**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-research/SKILL.md){rel=""nofollow""} | Web research synthesized into knowledge entities | | [**memory-literary-analysis**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-literary-analysis/SKILL.md){rel=""nofollow""} | Analyze a complete literary work into a structured knowledge graph | ::note The skills are open source. You can read every `SKILL.md` file in the [Basic Memory skills collection](https://github.com/basicmachines-co/basic-memory/tree/main/skills){rel=""nofollow""} . :: --- ## Install skills in a coding agent If you use Claude Code or Codex, install skills from the terminal with `npx`. It ships with Node.js; [install Node.js](https://nodejs.org/en/download){rel=""nofollow""} first if needed. ### Install with npx Install all Basic Memory skills: ```bash npx skills add basicmachines-co/basic-memory/skills ``` Or install one skill: ```bash npx skills add basicmachines-co/basic-memory/skills --skill memory-onboarding ``` List the available skills: ```bash npx skills add basicmachines-co/basic-memory/skills --list ``` ::note If the command cannot load `basicmachines-co/basic-memory/skills` , update the Skills CLI or install manually. :: ### Install manually Clone the repo and copy a skill folder into your agent's skills directory. This example installs `memory-notes` for Claude Code: ```bash git clone https://github.com/basicmachines-co/basic-memory.git cp -r basic-memory/skills/memory-notes ~/.claude/skills/ ``` For a project-scoped Claude Code skill, copy it to `.claude/skills/` in your project root. --- ## Use a skill Skills activate automatically when your request matches what they teach. You can also name the skill directly: ```text "Use memory-onboarding to help me set up Basic Memory." "Use memory-notes to write up what we just discussed." ``` In Claude Code and Codex, you can also invoke an installed skill as a slash command, such as `/memory-notes`. --- ## 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: Skills on GitHub to: https://github.com/basicmachines-co/basic-memory/tree/main/skills --- Source, contributing guide, and issue tracker in the basic-memory monorepo. ::: :: # Harness Capture Basic Memory plugins for Claude Code and Codex use `bm hook` as one shared lifecycle front door. Plugin hook scripts only pass the harness event into Basic Memory; context recall, checkpoint coordination, capture, retention, and health reporting live in the installed Basic Memory package. ## Understand the lifecycle events | Command | Harness event | What Basic Memory does | | ----------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bm hook session-start` | SessionStart | Reads configured projects, prints a bounded context brief, and captures a `session_started` envelope when capture is enabled. After Codex compaction, it can also request an agent-authored checkpoint. | | `bm hook pre-compact` | PreCompact | Captures a `compaction_imminent` envelope. Claude can write a durable checkpoint from its transcript; Codex defers the checkpoint request to the post-compaction SessionStart because Codex ignores PreCompact output. | | `bm hook stop` | Retired Stop hook | Returns a continue response so stale pre-upgrade Codex hook entries do not block a session. New installs do not register it. | Active lifecycle commands are fail-open: a capture or recall error is reported without interrupting the agent session. ## Use plugin-managed hooks The Basic Memory Claude Code and Codex plugins register SessionStart and PreCompact automatically. Their status workflows also surface the shared local inbox, pending and archived counts, last flush, resolved project mapping, capture state, checkpoint state, Basic Memory version, and uv version. Run the core status command directly when you need the underlying evidence: ::code-group ```bash [Codex] bm hook status --harness codex --project-dir /path/to/repository ``` ```bash [Claude Code] bm hook status --harness claude --project-dir /path/to/repository ``` :: The plugin's `bm-status` workflow includes this hook health in its broader Basic Memory configuration and reachability report. ## Install hooks without a plugin Standalone users can add the same user-level hooks directly: ```bash bm hook install --harness codex bm hook install --harness claude ``` Install is idempotent. It adds ownership-tagged entries to `~/.codex/hooks.json` or `~/.claude/settings.json` and preserves unrelated user hooks and settings. Remove only the entries Basic Memory installed: ```bash bm hook remove --harness codex bm hook remove --harness claude ``` The plugin and standalone flows use the same runtime behavior. Do not manually register both for one harness. ::note For development against a nonstandard Basic Memory executable, `BM_BIN` overrides the uv-managed command used by plugin hook shims. :: ## Control local event capture Lifecycle capture is enabled by default. Each event appends one bounded JSON envelope to the owner-private local WAL at the Basic Memory data directory's `inbox/` path, normally `~/.basic-memory/inbox/`. The envelope contains lifecycle metadata such as the event, session, working directory, project hint, and model; it is not a transcript or a knowledge-graph note. Set `captureEvents` to the JSON boolean `false` to opt out: ::code-group ```json [.codex/basic-memory.json] { "basicMemory": { "captureEvents": false } } ``` ```json [.claude/settings.json] { "basicMemory": { "captureEvents": false } } ``` :: Malformed capture settings fail closed: Basic Memory disables capture rather than guessing that an invalid value means `true`. ## Flush and retain envelopes Archive pending envelopes locally: ```bash bm hook flush bm hook flush --older-than-days 30 ``` Flush moves valid envelopes into `inbox/processed/`, deduplicates replays, leaves unresolved pending work visible, and prunes processed or unresolved-pending envelopes older than the retention window. It never writes graph notes or sends the lifecycle trace to a team project. Use `bm hook status` after flushing to confirm the pending count, archived count, and last-flush timestamp. ## Related pages - [Claude Code](https://docs.basicmemory.com/integrations/claude-code) — connect Claude Code to Basic Memory. - [OpenAI Codex](https://docs.basicmemory.com/integrations/codex) — connect the Codex app or CLI. - [CLI Reference](https://docs.basicmemory.com/reference/cli-reference) — exact `bm hook` command reference. # 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 Create a project for your documentation — ask your AI, and it works the same on cloud and local: ```text Create a new project called "my-project-docs" ``` The AI calls `create_memory_project` behind the scenes. **Cloud is a great home for project docs**: browse and edit them in the [web app](https://docs.basicmemory.com/cloud/web-app), give the whole [team](https://docs.basicmemory.com/teams/about) (and their agents) access, and publish any page externally with a [share link](https://docs.basicmemory.com/cloud/shared-notes). Prefer docs living inside the repo? On a local install, point the project at your `docs/` folder instead: ```bash bm project add my-project ~/code/my-project/docs ``` That's it. Your AI assistant can now read and write documentation in that project. 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 record a status, context, decision, and consequences." 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 --- ``` Schema fields are satisfied by observations — an ADR with `- [status] accepted` and `- [decision] Use JWT tokens` passes; markdown headings alone don't count (see [Schema System](https://docs.basicmemory.com/concepts/schema-system)). 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?" The AI combines the right filters for each: `status` on an ADR is an observation category, so it filters with `categories=["status"]`; tags and note types are frontmatter, filtered with [metadata search](https://docs.basicmemory.com/concepts/metadata-search). 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. ::note **This isn't about AI writing your book.** The failure mode is slop — generated text you never read. Use the agent the other way around: to organize and clarify *your* thinking. You write; it tracks the characters, connections, timelines, and research so nothing gets lost. Everything in the knowledge base should be something you've read and own. :: ## Setting Up a Writing Project Create a dedicated project — ask your AI, and it works the same on cloud and local: ```text Create a new project called "my-novel" ``` A cloud project lets you write from any device and read your notes in the [web app](https://docs.basicmemory.com/cloud/web-app); on a local install you can point the project at a folder instead: ```bash bm 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 record 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 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 `battery-technology` that relate to a specific concept. See [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search) for the full query syntax. ### Exploring Connections Ask your AI to build context around a note to follow its links: ```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: - `key-finding` observations for the takeaways - `source` observations for references - `open-question` observations for what's unresolved - Relations linking to related topics Schemas validate observations, relations, and frontmatter — not markdown headings. With the schema in place (and a [schema-aware assistant](https://docs.basicmemory.com/concepts/schema-system)), every research note comes out 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. Behind the scenes, the AI enhances your existing note with `edit_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 "budget concerns" and search for "spending pushback," 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 all meeting notes with status open." > "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 follows the schema's structure when creating typed notes, and you can validate anytime — "Validate my meeting notes against the schema" — with warn mode as the gentle default. 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 grows through contributions from both you and the AI — and in [Basic Memory Cloud](https://docs.basicmemory.com/cloud/file-history), every save is a version you can step back through. ## 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/local/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's semantic search 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 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** — you can keep personal notes in a local-only project while routing work projects through Basic Memory Cloud. Your journal entries and health notes stay on your laptop; your work projects run against cloud (to move existing notes there, [push them up](https://docs.basicmemory.com/cloud/cloud-sync) first). Different projects, different rules — see [Local & Cloud Routing](https://docs.basicmemory.com/cloud/routing). ```bash # Personal notes stay local bm project add personal ~/notes/personal # Work notes route through cloud bm project add work ~/notes/work bm project set-cloud work ``` **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 the current project-index observation: how many project files were seen, with file details under `--verbose`. The v0.23 display replaces the old sync-report tree; use `--json` for automation. ```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 | | `--full` | Force a complete rebuild and re-embed (the default run is incremental and skips unchanged content) | | `--project`, `-p` | Target a specific project (default: all projects) | When neither `--search` nor `--embeddings` is specified, both are rebuilt. `bm reindex --embeddings` exits nonzero if any embedding fails and reports the configured vector index. Changing `semantic_vector_index` requires this command; until it succeeds, vector search returns no results and hybrid search serves full-text results only. ### `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 Homebrew and `uv tool` installs (uvx environments are skipped — uvx resolves its own cache); 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 | --- ## Retrieval inspection commands Read-only diagnostics for search, new in v0.23. When a note doesn't come back for a query you expected it to, `bm inspect chunks` answers "is this note indexed, embedded, and current?" and `bm inspect query` answers "what did retrieval actually do with my query?". ### `bm inspect chunks` Show how the retrieval index decomposes one note into search rows and vector chunks. Accepts the same identifiers as `read_note`: a title, permalink, or `memory://` URL. ```bash bm inspect chunks "coffee-brewing-methods" bm inspect chunks "Coffee Brewing Methods" --project research bm inspect chunks coffee-brewing-methods --json ``` The output shows the note's entity, observation, and relation search rows with the vector chunks each row produced, plus a readiness summary and a per-chunk status: | Status | Meaning | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `ready` | Embedded under the configured model and vector index — visible to vector search | | `pending` | Awaiting embedding — not yet visible to vector search | | `stale` | The stored chunk no longer matches the note's current search rows | | `orphaned` | Embedded under a different model or vector index than the one configured — retrieval cannot see it; rebuild with `bm reindex --embeddings` | A freshness state (`fresh`, `not_indexed`, `index_behind_rows`, `rows_behind_file`, or `unknown`) distinguishes a chunking problem from an indexing-lag problem, with the checksum or fingerprint evidence for any non-fresh state. | Flag | Description | | -------------- | --------------------------------------------------------------------------- | | `--json` | Output raw JSON — the stable machine-readable schema (automatic when piped) | | `--plain` | Undecorated plain-text output | | `--project` | Target a specific project | | `--project-id` | Project external ID (UUID); takes precedence over `--project` | | `--local` | Force local routing (ignore cloud mode) | | `--cloud` | Force cloud routing | ### `bm inspect query` Run a search and trace its execution: every retrieval stage — matching, hydration, filtering, fusion, reranking, and the final page window — that produced the result page. The trace is captured by the same call that returns the results, so it reflects the actual execution rather than a reconstruction, and ordinary searches are unaffected. ```bash bm inspect query "how do we handle auth" bm inspect query "auth" --mode vector --show-misses bm inspect query "auth" --mode hybrid --page 1 --page-size 10 --json ``` The output shows the engine identity (vector index, embedding model, fusion formula, minimum similarity, reranker status), a stage table with in/out/dropped counts and timings, and the ranked results with final scores and rerank movement (Δ). | Flag | Description | | --------------- | ------------------------------------------------------------------------------------------ | | `--mode` | Retrieval mode: `text` (default), `vector`, or `hybrid` | | `--show-misses` | Also render bounded rejected candidates and why each was dropped (vector and hybrid modes) | | `--show-ids` | Include stable entity IDs in human output | | `--page` | Result page to inspect (default `1`) | | `--page-size` | Results per page (default `10`) | | `--json` | Output raw JSON — every captured candidate, stable schema (automatic when piped) | | `--plain` | Undecorated plain-text output | | `--project` | Target a specific project | | `--project-id` | Project external ID (UUID); takes precedence over `--project` | | `--local` | Force local routing (ignore cloud mode) | | `--cloud` | Force cloud routing | --- ## Configuration commands ### `bm config list` List every scalar setting with its effective value and source. Environment overrides are marked with the exact `BASIC_MEMORY_*` variable. ```bash bm config list bm config list --json ``` ### `bm config get` Show one effective value and report any environment override: ```bash bm config get reranker_enabled bm config get milvus_uri ``` ### `bm config set` Validate a value through the same config model used at startup, then write it to `config.json`: ```bash bm config set reranker_enabled true bm config set cli_output_style plain ``` Invalid keys or values exit nonzero without changing the config file. If an environment variable overrides the file value, the command writes the value but warns that the environment still wins. ### `bm config unset` Remove a setting from `config.json`: ```bash bm config unset reranker_enabled ``` The effective value then falls back to an environment override when one exists, otherwise to the built-in default. `list`, `get`, `set`, and `unset` mask secret values and redact credentials embedded in URLs. Structured fields such as projects are managed by their dedicated command groups and do not appear as writable scalar settings. --- ## Harness hook commands `bm hook` is the lifecycle front door used by the Basic Memory Claude Code and Codex plugins. See [Harness Capture](https://docs.basicmemory.com/integrations/harness-capture) for event behavior, settings, and retention. ```bash # Inspect shared inbox and harness settings health bm hook status --harness codex --project-dir /path/to/repository bm hook status --harness claude --project-dir /path/to/repository # Archive local lifecycle envelopes bm hook flush bm hook flush --older-than-days 30 # Wire or remove user-level hooks without a plugin bm hook install --harness codex bm hook remove --harness codex bm hook install --harness claude bm hook remove --harness claude ``` | Command | Description | | --------------- | ------------------------------------------------------------------------------------ | | `session-start` | Print the configured context brief and capture a session-start envelope when enabled | | `pre-compact` | Capture the compaction event and coordinate a durable checkpoint | | `stop` | Compatibility no-op for stale pre-upgrade Stop hooks; not registered by new installs | | `status` | Show inbox depth, last flush, settings, capture/checkpoint state, and tool versions | | `flush` | Archive pending envelopes locally; never writes graph notes | | `install` | Add ownership-tagged user-level harness hooks idempotently | | `remove` | Remove only the entries written by `bm hook install` | --- ## 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. Files are retained by default; pass `--delete-notes` to remove them too. For a cloud project with a configured local sync directory, also pass `--cloud` to remove both the hosted objects and that local copy. ```bash # Stop tracking a project while retaining its files bm project remove research # Delete a local project's files bm project remove research --delete-notes # Purge cloud storage and remove any configured local sync directory bm project remove research --cloud --delete-notes ``` | Flag | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `--delete-notes` | Also delete project files: local files for a local project, or all active objects under the project prefix for a cloud project | | `--local` | Force local routing | | `--cloud` | Force cloud routing | Cloud deletion is accepted asynchronously. Without `--delete-notes`, the project is removed from the hosted database but its cloud files remain. With `--delete-notes`, the background job purges indexed and unindexed objects under the exact project storage prefix before completing the hard delete. Existing cloud snapshots follow their own retention and deletion lifecycle. ::warning For a cloud project configured with a local sync path, explicitly passing both `--cloud` and `--delete-notes` also removes that local sync directory. Back up any local files you need before running the command. :: ### `bm project default` Set the default project used as fallback when no project is specified. ```bash bm project default main ``` ### `bm project move` Update a local project's configured filesystem path. This changes configuration only — move the files to the new path yourself (Basic Memory does not move them). ```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 # provision the rclone remote (Personal workspaces; Team push/pull needs no 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 --name research # Preview and delete cloud files matching ~/.basic-memory/.bmignore (Personal only) bm cloud prune --name research --dry-run bm cloud prune --name research # Verify file integrity between local and cloud (Personal only) bm cloud check --name research # 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. On Team workspaces they run over the cloud's permissioned WebDAV API (v0.23+) — no `bm cloud setup` required, and access is checked per project. `sync` is a destructive mirror and is blocked on Team workspaces. In v0.23 it also deletes previously synced files that become ignored by `.bmignore`; preview with `--dry-run`. `prune` performs only that ignore-based remote cleanup and asks for confirmation unless you pass `--yes`. See the [Cloud Sync guide](https://docs.basicmemory.com/cloud/cloud-sync) for details. ### Public shares ```bash bm cloud share create research notes/my-idea bm cloud share create research notes/my-idea --expires-at 2099-12-31 bm cloud share list bm cloud share list --project research bm cloud share update SHARE_TOKEN --disable bm cloud share update SHARE_TOKEN --enable bm cloud share update SHARE_TOKEN --expires-at none bm cloud share revoke SHARE_TOKEN bm cloud share revoke SHARE_TOKEN --force ``` All share commands accept `--workspace` to route by workspace slug, display name, or tenant ID. `revoke` confirms before deletion unless `--force` is set. ### 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 team 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 — exit 1 if any validation errors are found 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` | Exit with code 1 if any validation errors are found (warnings never affect the exit code) | | `--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 # 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. Search, read, context, and activity commands use Rich tables, panels, trees, or Markdown when stdout is a TTY. Output precedence is: 1. `--json` for raw machine-readable JSON. 2. `--plain` for undecorated human-readable text. 3. Non-TTY output defaults to JSON, preserving piped and redirected scripts. 4. TTY output follows `cli_output_style` (`rich` by default, or `plain`). `--json` and `--plain` are mutually exclusive. Set the interactive default with `bm config set cli_output_style plain`. ### `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 # Replace an existing note (past the overwrite guard) bm tool write-note --title "API Notes" --folder specs --content "..." --overwrite ``` | 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`) | | `--overwrite` | Replace an existing note at the same path (past the overwrite guard) | | `--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 ``` | Flag | Description | | ----------------------- | ---------------------------------- | | `--include-frontmatter` | Include YAML frontmatter in output | | `--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" bm tool edit-note my-note --operation replace_section --section "## Notes" --content "updated" --no-replace-subsections ``` | Flag | Description | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--operation` | Edit operation: `append`, `prepend`, `find_replace`, `replace_section`, `insert_before_section`, `insert_after_section` (required; the insert operations also require `--section`) | | `--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`) | | `--replace-subsections`, `--no-replace-subsections` | For `replace_section`, replace nested subsections by default or preserve them with `--no-replace-subsections` | | `--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 observations by category bm tool search-notes "auth" --entity-type observation --category decision # 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) | | `--category` | Filter observation results to exact categories (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 `10`) | | `--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 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 claude projects 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. - Most `bm tool` subcommands accept `--project-id` (the project's external UUID from `bm project list --json`) to disambiguate same-named projects across cloud workspaces. - `--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) # Contact Support For private account, billing, or Cloud workspace help, email: ```text support@basicmemory.com ``` You can also reach us with the **feedback button** in the web app's lower-left navbar. Use email or feedback when the issue involves information that should not be posted publicly. (For sales and partner inquiries, use `hello@basicmemory.com`.) --- ## Email support for private issues Contact support when you need help with: - Account access or sign-in problems. - Billing, subscriptions, seats, or checkout. - Cloud workspace access, invitations, or team membership. - Private projects, notes, or shared-note links. - API keys, OAuth sessions, or suspected credential exposure. - Product bugs that require private workspace context. ::warning Never post API keys, OAuth tokens, billing information, private notes, or invitation links in public support channels. :: --- ## What to include To help diagnose the problem, include: - The email address you use for Basic Memory Cloud. - The workspace name, if relevant. - What you expected to happen. - What happened instead. - The page, command, or AI client where the issue occurred. - Screenshots or error text with secrets removed. For CLI issues, these commands are usually safe to include after checking for private paths or tokens: ```bash bm --version bm status bm project list bm cloud status ``` Do not include full API keys, OAuth tokens, raw private notes, or billing details unless support specifically asks for them through a trusted channel. --- ## Public help Use public channels for general questions, local open-source issues, and reproducible bugs that do not require private context: - [Basic Memory Discord](https://discord.gg/tyvKNccgqN){rel=""nofollow""} - [GitHub issues](https://github.com/basicmachines-co/basic-memory/issues){rel=""nofollow""} Public channels are best for installation issues, local MCP configuration, feature requests, documentation problems, and open-source bug reports. --- ## Related guides ::card-group :::card --- icon: i-lucide-life-buoy title: Troubleshooting to: https://docs.basicmemory.com/reference/troubleshooting --- Diagnose common Cloud, MCP, sync, local install, and search issues. ::: :::card --- icon: i-lucide-users title: Teams to: https://docs.basicmemory.com/teams/about --- Understand workspaces, members, roles, seats, and invitations. ::: :::card --- icon: i-lucide-key title: API Keys to: https://docs.basicmemory.com/cloud/api-keys --- Create and revoke Cloud API keys safely. ::: :: # 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 | Project name. Constrained project env → explicit parameter → `default_project` config | | `project_id` | string | — | Project external UUID from `list_memory_projects`. Prefer this when the same project name exists in more than one workspace | | `output_format` | `"text"` or `"json"` | `"text"` | Machine-readable JSON output. `build_context` defaults to `"json"`; most other tools default to `"text"` | `workspace` is not a universal parameter. It appears on the note-writing tools (`write_note`, `edit_note`) and on the tools that create or delete cloud projects. For ordinary read, search, and schema calls, use `project` or `project_id`. --- ## 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. Since v0.23.2, each segment resolves to a unique existing case-insensitive folder match | | `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 or JSON string | No | Extra frontmatter fields merged into the note's YAML header | | `overwrite` | boolean | No | Default follows `write_note_overwrite_default` config (`false` unless changed). Pass `true` to replace an existing note; without it, writing to an existing path returns an error | | `workspace` | string | No | Cloud workspace to write into (name or tenant ID) | 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`. Aliases accepted for `directory`: `folder`, `dir`, and `path`. Folder casing resolution uses known indexed directories, so local and Cloud writes behave identically. Exact matches win; a unique case-insensitive match reuses the existing spelling; no match creates the folder as requested; and existing case-variant siblings keep exact-match behavior. ### `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 | | `review_mode` | `structured` or `raw` | No | Cloud only; default `structured`. Returns clean prose and typed review threads, or exact persisted CriticMarkup in `raw` mode | On Cloud, structured JSON also returns `revision_checksum` and a `review` object containing summary counts and typed comment/suggestion items. Use that checksum for review decisions and for ordinary edits while review work is open. Raw mode is an inspection escape hatch; agents should not author or mutate CriticMarkup directly. ### `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` | | `replace_subsections` | boolean | No | For `replace_section`; default `true` replaces nested subsections. Set `false` to preserve them | | `metadata` | object | No | Merge frontmatter fields independently of the body operation; provided keys overwrite or add values | | `workspace` | string | No | Cloud workspace containing the note (name or tenant ID) | | `expected_checksum` | string | No | Cloud reviewed notes require the checksum from structured `read_note`; stale or intersecting edits are rejected | `replace_section` now follows Markdown heading levels. By default, a selected section extends through the next heading of the same or higher level, so replacing an `##` section also replaces its nested `###` subsections. Set `replace_subsections=false` to stop at the next heading of any level and keep nested subsections. `metadata` preserves unrelated frontmatter and the note body. It ignores `title`, `type`, and `permalink`, which have dedicated handling, and does not support deleting keys. On Cloud, `edit_note` preserves active review markers byte-for-byte. If an edit would change an anchored review range, it fails with the blocking review ID; use `review_note` to resolve or decide that item first. `write_note(overwrite=true)` is a full replacement and may remove review state. ### `review_note` (Cloud) Manage comments and suggestions on an existing Markdown note. Always begin with `read_note(review_mode="structured", output_format="json")`, and do not write CriticMarkup directly. | Parameter | Type | Required | Notes | | ------------------- | --------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `identifier` | string | Yes | Exact title, permalink, file path, external ID, or `memory://` URL | | `command` | `comment`, `suggest`, `reply`, `resolve`, `accept`, or `reject` | Yes | One review lifecycle action | | `anchor` | object | Conditional | Required for `comment` and `suggest`. `exact` is a single-line prose selection; optional `prefix`, `suffix`, or one-based `occurrence` disambiguates repeated text | | `body` | string | Conditional | Required for `comment` and `reply`; optional final reply when resolving a comment | | `suggestion_kind` | `addition`, `deletion`, or `replacement` | Conditional | Required for `suggest` | | `replacement` | string | Conditional | Required for addition and replacement suggestions; omit for deletion | | `review_id` | string | Conditional | Required for `reply`, `resolve`, `accept`, and `reject`; obtain it from structured `read_note` or a prior mutation response | | `expected_checksum` | string | Conditional | Required for `accept` and `reject`; optional stale-write guard for other commands | `comment` and `suggest` create attributed review records and return their IDs. `reply` works on comments or suggestions. `resolve` closes a comment without changing its anchored prose and can include a final reply. `accept` applies a pending suggestion; `reject` keeps the original prose. Every mutation is atomic and returns the new `revision_checksum`. ```text # Create a replacement suggestion review_note( identifier="Launch plan", command="suggest", anchor={"exact": "Ship the beta on Friday."}, suggestion_kind="replacement", replacement="Ship the beta after the security review." ) # After a fresh structured read, accept it review_note( identifier="Launch plan", command="accept", review_id="suggestion-id", expected_checksum="checksum-from-read-note" ) ``` See [Comments and Suggestions](https://docs.basicmemory.com/cloud/comments-and-suggestions) for the complete human-and-agent workflow. ### `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`; parent folders receive v0.23.2 casing resolution | | `destination_folder` | string | Conditional | Target folder — moves note into folder preserving filename. Mutually exclusive with `destination_path`; each segment can reuse a unique case-insensitive folder match | | `is_directory` | boolean | No | Default `false`. Set to `true` to move an entire directory | Folder casing resolution applies to note destinations, not directory renames. The response reports the actual landing path after a case-corrected move. Case-only folder renames and merging already duplicated case variants remain separate operations. ### `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 a file's content by path or permalink. Text files return as plain text; images are resized/optimized for display; other binary files return base64-encoded (subject to size limits). Useful for non-markdown files like images, PDFs, or attachments. | Parameter | Type | Required | Notes | | --------- | ------ | -------- | ------------------------------------------------------------------------------------- | | `path` | string | Yes | File path, permalink, or `memory://...` URL. Aliases: `file_path`, `filepath`, `file` | ### `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 | ### `open_basic_memory` (Cloud) Open the interactive Pocketbook in a compatible client. Use this when the user wants to see, browse, navigate, or interact with Basic Memory visually. Use `read_note`, `search_notes`, or `list_directory` instead when the assistant only needs data for its answer. The default workspace and project resolve automatically. Do not call `list_memory_projects` first unless the user asks for project metadata or wants a non-default location. | Parameter | Type | Required | Notes | | ------------ | ------------------------------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `view` | `notes`, `note`, `folders`, `search`, or `graph` | No | Default `notes`. Destination screen | | `workspace` | string | No | Workspace slug, name, or tenant ID. Omit for the default | | `project` | string | No | Project name or qualified workspace/project name. Omit for the default | | `project_id` | string | No | Exact external project UUID. Takes precedence over `project` | | `directory` | string | No | Initial folder for `notes`, `folders`, `note`, or `search` views | | `identifier` | string | Conditional | Required for `view="note"`; optional for `view="graph"` to focus a note. Accepts a title, permalink, `memory://` URL, or exact note UUID | | `query` | string | No | Initial query for `view="search"` only | | `graph_mode` | `overview` or `full` | No | Default `overview`. Used only with `view="graph"` | | `note_mode` | `view` or `edit` | No | Default `view`. Use `edit` to open a note directly in the editor; used only with `view="note"` | Examples: ```text open_basic_memory() open_basic_memory(view="search", query="authentication") open_basic_memory(view="folders", directory="research") open_basic_memory(view="note", identifier="memory://main/plans/api", note_mode="edit") open_basic_memory(view="graph", identifier="Architecture", graph_mode="full") ``` See [Pocketbook](https://docs.basicmemory.com/cloud/mcp-app) for the user workflow. --- ## 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] or string | No | Case-insensitive frontmatter `type` filter (e.g., `["person", "meeting"]`). Aliases: `note_type`, `types` | | `entity_types` | list [string] or string | No | Knowledge graph result filter: `entity`, `observation`, `relation`. Alias: `entity_type` | | `categories` | list [string] or string | No | Exact observation category filter (e.g., `["decision", "rule"]`). When provided without `entity_types`, results default to observations. | | `after_date` | string | No | Date/time filter (ISO format) | | `metadata_filters` | object or JSON string | 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. Search results expose each note's stable `external_id` in JSON and Markdown output. Use it for web-app deep links or exact follow-up operations instead of parsing a title or permalink. Cloud search projects reviewed notes as clean prose rather than CriticMarkup. JSON note results include `review_summary` counts (`open_comments`, `resolved_comments`, `pending_suggestions`, and `total_pending`). If a stale search fragment splits or exposes review markup during asynchronous index reconciliation, Cloud omits that hit instead of returning ambiguous storage bytes. Use `categories` for observation categories such as `[decision]`, `[rule]`, or `[follow-up]`. `metadata_filters` only checks note frontmatter, so `metadata_filters={"category": "decision"}` matches a frontmatter field named `category`, not observation categories. The singular `category` is accepted as an alias, and comma-separated strings work (`categories="decision,rule"`). Matching is exact, and categories only exist on observations — explicitly passing `entity_types=["entity"]` alongside `categories` returns nothing. ::note **Parameter aliases.** `search_notes` accepts `q` , `search` , or `text` as aliases for `query` ; `all_projects` for `search_all_projects` ; `page_number` for `page` ; and `limit` / `per_page` for `page_size` . 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 no project can be resolved at all (no parameter, no default project), it returns activity across all projects (discovery mode); otherwise it uses the resolved project. Entity rows include `external_id` so clients can address the exact note returned. | 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, external project ID, and sync/workspace metadata 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 | | --------------- | -------------------- | -------- | ------------------------------------------------------------------------------- | | `output_format` | `"text"` or `"json"` | No | Use `"json"` when an agent needs exact `project_id` values for later tool calls | ### `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. Note files are retained by default. | Parameter | Type | Required | Notes | | -------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `project_name` | string | Yes | Name of the project to remove | | `delete_notes` | boolean | No | Default `false`. Set to `true` to delete local files or purge every active cloud object under the project's storage prefix | | `workspace` | string | No | Cloud workspace selector. From a local stdio MCP session, provide this to route deletion to cloud unless the session is already explicitly cloud-routed | Cloud purge behavior applies when the MCP session is hosted or factory-routed to cloud, explicitly cloud-routed, or given a `workspace` selector. From a local stdio MCP session, `delete_notes=true` alone does not switch this tool to cloud routing; pass `workspace` to ensure the hosted project and objects are targeted. Hosted deletion is asynchronous. The tool response reports the project deletion status and background job ID when the cloud backend queues the work. With `delete_notes=false`, cloud objects are retained even though the project and its indexed database rows are removed. With `delete_notes=true`, the background job removes indexed and unindexed objects under the exact project prefix before completing the hard delete. Existing snapshots follow their separate retention lifecycle. ### `list_directory` List directory contents with optional depth, glob filter, and sorting. | 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 returned files (e.g., `*.md`, `schemas/*`). Nonmatching directories are still traversed within `depth` | | `sort` | string | No | Ordering: `title_asc`, `title_desc`, `updated_asc`, or `updated_desc`. Omit for the default filename ordering | | `page` | integer | No | One-indexed page; default `1` | | `page_size` | integer | No | Nodes per page; default `10`, maximum `200`. Aliases: `limit`, `per_page` | | `output_format` | `"text"` or `"json"` | No | JSON includes structured pagination metadata | Large listings are bounded. Continue with the next `page` instead of assuming one response contains every file. File nodes include `external_id` in both text and JSON output. Glob filtering applies to returned nodes, not traversal. For example, `depth=2` with `file_name_glob="*.md"` still finds Markdown files inside a folder whose own name does not match `*.md`. Explicit sorts (v0.23) order folders before files, apply deterministically before pagination, and use note titles for `title_*` modes. Folders have no canonical update timestamp, so `updated_*` modes keep folders name-ascending while still listing them first. ### `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 | | `output_format` | `"text"` or `"json"` | No | Machine-readable validation report | ### `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`) | | `output_format` | `"text"` or `"json"` | No | Machine-readable inference report | ### `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`) | | `output_format` | `"text"` or `"json"` | No | Machine-readable drift report | --- ## Diagnostics ### `basic_memory_diagnostics` Return a read-only Markdown report for support and installation troubleshooting. It takes no parameters and includes: - Basic Memory package and API versions; - Python, operating-system, and architecture details; and - the config path and current config contents with secrets and URL credentials redacted. ::note v0.23 removes the `canvas` , `cloud_info` , and `release_notes` MCP tools. Use the Cloud documentation, GitHub release notes, and your editor's native visualization features instead. See [Upgrade to v0.23](https://docs.basicmemory.com/whats-new/v0-23-upgrade) . :: --- ## ChatGPT compatibility tools These are compatibility wrappers for ChatGPT's MCP implementation, which uses a simplified two-tool interface by default. v0.23 gates them by MCP client identity: only OpenAI clients can call them. - **`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`. Non-OpenAI MCP clients receive a clear rejection and must call `search_notes` and `read_note` directly. 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 Connecting Basic Memory over MCP gives your assistant the tools. It doesn't teach it *when* to reach for them. A few standing instructions are the difference between an assistant that occasionally writes a note and one that actually maintains your knowledge base — searching before it answers, capturing decisions as they happen, and linking new notes into the graph. There are three ways to give those instructions, from least to most effort. --- ## 1. Install Agent Skills (recommended) [Agent Skills](https://docs.basicmemory.com/integrations/skills) are packaged instructions that teach agents Basic Memory best practices — the note format, when to capture, how to search and resume work, schema workflows, and knowledge-base maintenance. If your client supports skills, this replaces hand-written guidance: ```bash npx skills add basicmachines-co/basic-memory/skills ``` That installs the full set. To start smaller, add just one: `npx skills add basicmachines-co/basic-memory/skills --skill memory-notes` — the core note-writing skill — and add others as you need them. --- ## 2. Add project-level instructions If you'd rather write your own guidance — or your client doesn't support skills — put it where your assistant reads standing instructions: - **Claude Projects** — in Claude (web or desktop), open your project's settings and paste your guidance into the **project instructions**. Every conversation in that project starts with it. - **Claude Code** — add it to the repo's `CLAUDE.md`. Claude Code loads it automatically in that repository. - **Codex and other coding agents** — add it to `AGENTS.md` in the repo root, the convention most coding agents read. - **Other clients** — use the custom-instructions or system-prompt field your client provides. ### A starting instruction block Paste this and adapt it to your workflow: ```markdown ## Basic Memory You have persistent memory through Basic Memory's MCP tools. - Before answering questions about prior work or decisions, search first: `search_notes`, then `build_context` on relevant `memory://` URLs. - Capture important decisions, findings, and context as notes with `write_note` during the conversation — don't wait to be asked. - Structure notes semantically: observations as `- [category] fact #tag` and relations as `- relates_to [[Other Note]]`. Use exact titles of existing notes in wikilinks so they resolve. - Update existing notes with `edit_note` instead of creating duplicates. - If the target project is ambiguous, ask once, then stick with it. ``` ::note Want more to work from? The [extended AI assistant guide](https://github.com/basicmachines-co/basic-memory/blob/main/docs/ai-assistant-guide-extended.md){rel=""nofollow""} is a full instruction document you can download and customize, and a [condensed version](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/resources/ai_assistant_guide.md){rel=""nofollow""} ships as an MCP resource inside Basic Memory itself. :: --- ## 3. Say it in the conversation Instructions don't have to be configured up front. Basic Memory is designed so you can direct it naturally as you work: ```text "Make sure you add observations and relations to this note." "Search my notes before answering — what did we decide about auth?" "Record this decision in Basic Memory." ``` Your assistant can even write a note about *how you like your notes* — and find it again in the next conversation. ::tip **Using your tool's built-in memory too?** There's a paste-once routing rule that teaches the agent to treat built-in memory as the short-term cache and Basic Memory as the long-term store — see [Using Basic Memory with Built-in AI Memory](https://docs.basicmemory.com/concepts/vs-built-in-memory) . :: --- ## What good usage looks like - **Search before answering.** Questions like "what did we decide about X?" should trigger `search_notes`, not a guess from the conversation so far. - **Capture as you go.** Decisions, requirements, and findings get recorded when they happen, structured with observations and relations. - **Build context on follow-ups.** `build_context` with a `memory://` URL pulls in a note *and* its connected notes, so continuation conversations start warm. - **Edit, don't duplicate.** Existing notes grow with `edit_note`; new notes link back to what they extend. For the full tool surface — parameters, aliases, defaults — see the [MCP Tools Reference](https://docs.basicmemory.com/reference/mcp-tools-reference). --- ## Related ::card-group :::card --- icon: i-lucide-sparkles title: Agent Skills to: https://docs.basicmemory.com/integrations/skills --- Packaged instructions that teach agents Basic Memory best practices. ::: :::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 --- The note structure your assistant should write. ::: :: # 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://modelcontextprotocol.io){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 ### Tags Additional categorization for entities and observations :: This structure emerges from simple text patterns in standard Markdown. The example below is saved as `Coffee Notes/Coffee Brewing Methods.md` — its frontmatter sets an explicit `permalink`, which overrides the path-derived one: ### Example Markdown Input ```markdown --- 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]] ``` ### 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-brewing-methods", "to_id": "coffee/proper-grinding-technique", "relation_type": "requires", "permalink": "coffee/coffee-brewing-methods/requires/coffee/proper-grinding-technique", "to_name": "Proper Grinding Technique" }, { "from_id": "coffee/coffee-brewing-methods", "to_id": "coffee/flavor-extraction", "relation_type": "affects", "permalink": "coffee/coffee-brewing-methods/affects/coffee/flavor-extraction", "to_name": "Flavor Extraction" } ], "created_at": "2025-03-06T13:34:48.563606", "updated_at": "2025-03-06T14:01:23.445071" } ] } ``` Basic Memory understands how to build context via its semantic graph. ### 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** — a comprehensive set of 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 :: --- ## Next Steps ::card-group :::card --- icon: i-lucide-file-text title: Knowledge Format to: https://docs.basicmemory.com/concepts/knowledge-format --- The markdown patterns behind the entity model. ::: :::card --- icon: i-lucide-settings title: Configuration to: https://docs.basicmemory.com/reference/configuration --- Every config field and environment variable. ::: :: # 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 index 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 authentication and connection 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?utm_source=docs&utm_medium=docs&utm_campaign=troubleshooting){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 ``` --- ## Indexing Issues ### Changes Not Indexing **Problem:** File changes not appearing in knowledge base. **Solutions:** 1. **Check index 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. **Rebuild the index** (or reset if issues persist): ```bash basic-memory reindex # heavier: drop and rebuild the database basic-memory reset --reindex ``` :warning[Plain `basic-memory reset` only deletes the index — pass `--reindex` to rebuild it from your files. May take time for large knowledge bases.] ### Duplicate Notes on macOS **Problem:** The same file appears twice — duplicate search results, `-1`-suffixed permalinks, or `edit_note` failing on an affected note. Typically triggered by cross-platform sync tools that rewrite Unicode filename forms ([#1275](https://github.com/basicmachines-co/basic-memory/issues/1275){rel=""nofollow""}) or by case-only renames on case-insensitive APFS ([#1281](https://github.com/basicmachines-co/basic-memory/issues/1281){rel=""nofollow""}). **Solution:** Collapse the duplicates with a full rebuild, and avoid case-only or normalization-only renames. These rename edge cases remain open in v0.23.2: ```bash basic-memory reindex --full -p ``` Ordinary `write_note` and note-move destinations are different: v0.23.2 reuses a uniquely matching existing folder regardless of case, preventing a new `schemas/` folder beside `Schemas/`. It does not repair existing duplicates or perform case-only folder renames. See [Known issues in v0.23](https://docs.basicmemory.com/whats-new/v0-23-upgrade#known-issues-in-v023) for details. ### Cloud Sync Issues **Problem:** Push or pull not working — setup errors, conflicts, or "no local sync path configured". The [Cloud Sync Guide's troubleshooting section](https://docs.basicmemory.com/cloud/cloud-sync#troubleshooting) owns the fixes: re-running setup, previewing transfers with `--dry-run`, resolving conflicts with `--on-conflict`, and configuring sync paths. --- ## 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. **Rebuild the search index**: ```bash basic-memory reindex ``` ### Entity Not Found **Problem:** Note doesn't exist at specified path. **Solutions:** 1. **Search for the note** — ask your AI assistant: ```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 knowledge base statistics**: ```bash basic-memory project info main ``` 2. **Archive old content** - Move inactive notes to archive folder 3. **Coalesce rapid file saves** - Increase the index delay when an editor writes the same file repeatedly in a short burst: ```bash bm config set index_delay 2000 ``` 4. **Tune concurrent accepted writes carefully** - For workloads that submit many local writes at once, increase materialization workers from the default of `4`: ```bash bm config set materialization_workers 8 ``` :brThis affects local write materialization, not general indexing concurrency. ### 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:** Unsupported Python version error. **Solution:** Install Python 3.12 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 pull --name research ``` ### 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. **Clean up SQLite WAL/shared-memory files** — after closing all clients, the supported path is: ```bash basic-memory reset --reindex ``` :br(It removes `memory.db-shm`/`memory.db-wal` itself — deleting the `-wal` file by hand can silently discard recently indexed changes.) ### Corrupted Database **Problem:** Database errors or inconsistent state. **Solution:** Reset and re-index: ```bash basic-memory reset --reindex ``` ::warning With `--reindex` , the index is rebuilt from your markdown files. All files are preserved. :: --- ## Getting Help ### Check Logs ```bash # View the log file (Windows uses per-process basic-memory-.log names) cat ~/.basic-memory/basic-memory.log # For cloud connection diagnostics bm cloud status ``` ### Command Help ```bash # View all commands basic-memory --help # Get help for specific commands basic-memory status --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/local/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. --- ## Manage settings from the CLI Use `bm config` for scalar settings instead of editing JSON by hand: ```bash bm config list bm config get reranker_enabled bm config set reranker_enabled true bm config unset reranker_enabled ``` `set` validates the complete configuration before writing. `list` shows whether each effective value comes from a default, `config.json`, or an environment override. Secret fields are masked and credentials embedded in URLs are redacted from `list` and `get` output. Structured project mappings still use `bm project`; `bm config` intentionally handles only scalar settings. --- ## New v0.23 settings All 28 new settings can be written with `bm config set ` or supplied as `BASIC_MEMORY_` environment variables. | Key | Default | Purpose | | ------------------------------------ | --------------------------------- | ------------------------------------------------------------------- | | `reranker_enabled` | `false` | Enable cross-encoder reranking for vector and hybrid candidates. | | `reranker_provider` | `fastembed` | Select local FastEmbed or API-backed LiteLLM reranking. | | `reranker_model` | `jinaai/jina-reranker-v1-tiny-en` | Select the reranker model; LiteLLM uses `provider/model`. | | `reranker_candidates` | `20` | Set the leading retrieval window rescored before returning a page. | | `reranker_max_document_chars` | `0` | Cap characters per candidate; `0` sends full matched text. | | `reranker_timeout` | `30.0` | Limit each LiteLLM rerank request in seconds; FastEmbed ignores it. | | `reranker_api_base` | unset | Set a custom LiteLLM reranker endpoint. | | `reranker_api_key` | unset | Pass a reranker credential directly to LiteLLM. | | `semantic_vector_index` | `pgvector` | Select pgvector or Milvus for Postgres; SQLite remains sqlite-vec. | | `milvus_uri` | unset | Connect to Milvus, Milvus Lite, or Zilliz Cloud. | | `milvus_token` | unset | Authenticate to Milvus or Zilliz. | | `milvus_timeout_seconds` | `30.0` | Limit each Milvus client operation. | | `milvus_collection_prefix` | `basic_memory` | Prefix project-isolated Milvus collections. | | `milvus_database` | `default` | Select a Milvus database; ignored by Milvus Lite. | | `semantic_embedding_api_base` | unset | Set a custom LiteLLM embedding endpoint. | | `semantic_embedding_api_key` | unset | Pass an embedding credential directly to LiteLLM. | | `semantic_embedding_document_prefix` | unset | Prefix indexed chunks for asymmetric embedding models. | | `semantic_embedding_query_prefix` | unset | Prefix queries for asymmetric embedding models. | | `redis_url` | unset | Enable optional Redis caching for standalone MCP reads. | | `redis_max_connections` | `20` | Bound the standalone read-cache connection pool. | | `materialization_workers` | `4` | Bound local accepted-write materialization concurrency. | | `sqlite_synchronous` | `NORMAL` | Set SQLite `PRAGMA synchronous`. | | `sqlite_mmap_size` | `268435456` | Set SQLite `PRAGMA mmap_size` in bytes. | | `sqlite_wal_autocheckpoint` | `1000` | Set SQLite WAL checkpoint frequency in pages. | | `sqlite_page_size` | `4096` | Set SQLite page size for a new database or the next `VACUUM`. | | `index_delay` | `1000` | Wait this many milliseconds after file changes before indexing. | | `index_changes` | `true` | Index local file changes in real time. | | `cli_output_style` | `rich` | Select Rich or plain interactive `bm tool` output. | Detailed constraints and operating guidance follow below. --- ## 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 ```json { "default_project": "main", "projects": { "main": { "path": "/Users/you/basic-memory", "mode": "local" }, "research": { "path": "/Users/you/research-notes", "mode": "cloud", "local_sync_path": "/Users/you/research-notes", "last_sync": "2026-02-15T18:30:00Z" } }, "semantic_search_enabled": true, "semantic_min_similarity": 0.55, "permalinks_include_project": true } ``` --- ## 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` - `local_sync_path` (optional; legacy `cloud_sync_path` keys are accepted and migrated on load) - `last_sync` (optional) ### `default_project` Fallback project name used when tools/commands do not pass a project. - Type: `string | null` - Default: unset — the first configured project is used (`"main"` on fresh installs, where a `main` project is seeded). Setting it explicitly to `null` disables automatic project resolution. ::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_vector_index` Vector index used by Postgres deployments. - Type: `"pgvector" | "milvus"` - Default: `"pgvector"` - Env: `BASIC_MEMORY_SEMANTIC_VECTOR_INDEX` SQLite always uses sqlite-vec and ignores this selector. After changing the Postgres index, run `bm reindex --embeddings`; before it succeeds, vector search returns nothing and hybrid search serves full-text results only. ### Milvus settings | Key | Type | Default | Environment variable | | -------------------------- | -------------------- | ---------------- | --------------------------------------- | | `milvus_uri` | string or null | `null` | `BASIC_MEMORY_MILVUS_URI` | | `milvus_token` | string or null | `null` | `BASIC_MEMORY_MILVUS_TOKEN` | | `milvus_timeout_seconds` | float greater than 0 | `30.0` | `BASIC_MEMORY_MILVUS_TIMEOUT_SECONDS` | | `milvus_collection_prefix` | string | `"basic_memory"` | `BASIC_MEMORY_MILVUS_COLLECTION_PREFIX` | | `milvus_database` | string | `"default"` | `BASIC_MEMORY_MILVUS_DATABASE` | Install `basic-memory[milvus]` before selecting Milvus. `milvus_uri` accepts a remote Milvus/Zilliz endpoint or a Milvus Lite path. Lite requires a `.db` suffix and an existing parent directory, creates a directory tree at that path, and ignores `milvus_database`. See [Postgres and Milvus](https://docs.basicmemory.com/local/postgres-and-milvus). ### `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: `2` - Env: `BASIC_MEMORY_SEMANTIC_EMBEDDING_BATCH_SIZE` ### LiteLLM endpoint and asymmetric-model settings | Key | Type | Default | Environment variable | Purpose | | ------------------------------------ | -------------- | ------- | ------------------------------------------------- | -------------------------------------------------------------------------------- | | `semantic_embedding_api_base` | string or null | `null` | `BASIC_MEMORY_SEMANTIC_EMBEDDING_API_BASE` | Custom OpenAI-compatible or self-hosted LiteLLM endpoint. | | `semantic_embedding_api_key` | string or null | `null` | `BASIC_MEMORY_SEMANTIC_EMBEDDING_API_KEY` | Credential passed directly to LiteLLM; normal provider env vars work when unset. | | `semantic_embedding_document_prefix` | string or null | `null` | `BASIC_MEMORY_SEMANTIC_EMBEDDING_DOCUMENT_PREFIX` | Literal prefix added to indexed chunks. | | `semantic_embedding_query_prefix` | string or null | `null` | `BASIC_MEMORY_SEMANTIC_EMBEDDING_QUERY_PREFIX` | Literal prefix added to queries. | Use the prefix pair for models whose document and query roles are expressed in input text. Rebuild embeddings after changing either prefix. ### `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. :: --- ## Reranker settings Reranking is disabled by default and applies only to vector and hybrid search. Enable the local provider with: ```bash bm config set reranker_enabled true ``` | Key | Type | Default | Environment variable | | ----------------------------- | --------------------------------- | ----------------------------------- | ------------------------------------------ | | `reranker_enabled` | boolean | `false` | `BASIC_MEMORY_RERANKER_ENABLED` | | `reranker_provider` | string (`fastembed` or `litellm`) | `"fastembed"` | `BASIC_MEMORY_RERANKER_PROVIDER` | | `reranker_model` | string | `"jinaai/jina-reranker-v1-tiny-en"` | `BASIC_MEMORY_RERANKER_MODEL` | | `reranker_candidates` | integer greater than 0 | `20` | `BASIC_MEMORY_RERANKER_CANDIDATES` | | `reranker_max_document_chars` | integer at least 0 | `0` | `BASIC_MEMORY_RERANKER_MAX_DOCUMENT_CHARS` | | `reranker_timeout` | float greater than 0 | `30.0` | `BASIC_MEMORY_RERANKER_TIMEOUT` | | `reranker_api_base` | string or null | `null` | `BASIC_MEMORY_RERANKER_API_BASE` | | `reranker_api_key` | string or null | `null` | `BASIC_MEMORY_RERANKER_API_KEY` | FastEmbed downloads the configured local model on first use. LiteLLM requires an explicit `provider/model` name and uses normal provider credentials when `reranker_api_key` is unset. Increase the candidate window to widen recall at a latency cost; use a positive document-character cap to bound long-note cost. FastEmbed ignores `reranker_timeout` because it runs locally. See [Semantic Search](https://docs.basicmemory.com/concepts/semantic-search#enable-reranking) for provider setup, measured latency, tuning, and fail-fast `503`/`502` behavior. --- ## 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` --- ## Indexing and watch settings ### `index_changes` Index local file changes in real time. - Type: boolean - Default: `true` - Env: `BASIC_MEMORY_INDEX_CHANGES` The old `sync_changes` config key and `BASIC_MEMORY_SYNC_CHANGES` environment variable are migrated automatically. If both old and new names are present, the new name wins. ### `index_delay` Wait this many milliseconds after a file change before indexing it. - Type: integer - Default: `1000` - Env: `BASIC_MEMORY_INDEX_DELAY` The old `sync_delay` config key and `BASIC_MEMORY_SYNC_DELAY` environment variable are migrated automatically. If both old and new names are present, the new name wins. ### `materialization_workers` Bound the number of accepted writes that materialize to local storage concurrently. - Type: integer greater than `0` - Default: `4` - Env: `BASIC_MEMORY_MATERIALIZATION_WORKERS` This controls local write materialization, not general indexing concurrency. The removed `sync_thread_pool_size` and `sync_max_concurrent_files` settings are silently ignored; use this setting only when tuning concurrent accepted writes. ### `skip_initialization_sync` Skip local initialization — database setup and project reconciliation/seeding — for cloud/stateless deployments where projects are managed in the database. Not a local performance knob; it does not gate the initial file scan. - 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`. With no `formatter_command` configured, markdown is formatted by the built-in mdformat; setting a command (or the per-extension `formatters` map) overrides it with an external tool. - Type: boolean - Default: `false` - Env: `BASIC_MEMORY_FORMAT_ON_SAVE` ### `formatter_command` External command to use for formatting markdown files. The file path is substituted via a `{file}` placeholder — for example `npx prettier --write {file}`. A per-extension `formatters` map is also available for different tools per file type. - 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+asyncpg://user:pass@host:5432/dbname` ### SQLite tuning These settings map directly to SQLite pragmas. The defaults are suitable for most installations. | Key | Type | Default | Environment variable | Guidance | | --------------------------- | ----------------------------------- | ----------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `sqlite_synchronous` | `OFF`, `NORMAL`, `FULL`, or `EXTRA` | `NORMAL` | `BASIC_MEMORY_SQLITE_SYNCHRONOUS` | `NORMAL` is the safe WAL-mode default. Testing found no meaningful gain from `OFF`, which weakens durability. | | `sqlite_mmap_size` | integer at least `0` | `268435456` | `BASIC_MEMORY_SQLITE_MMAP_SIZE` | Memory-map up to this many bytes; `0` disables memory mapping. | | `sqlite_wal_autocheckpoint` | integer at least `0` | `1000` | `BASIC_MEMORY_SQLITE_WAL_AUTOCHECKPOINT` | Checkpoint after this many WAL pages; `0` disables automatic checkpoints. Larger values can reduce checkpoint stalls but allow a larger WAL. | | `sqlite_page_size` | integer from `512` to `65536` | `4096` | `BASIC_MEMORY_SQLITE_PAGE_SIZE` | Applies to a fresh database or after `VACUUM`; changing it does not rewrite an existing database immediately. | --- ## Optional Redis read cache Standalone MCP servers can cache read results in Redis. Install the optional dependency and set a URL: ```bash pip install "basic-memory[redis]" bm config set redis_url redis://localhost:6379/0 ``` | Key | Type | Default | Environment variable | | ----------------------- | ------------------------ | ------- | ------------------------------------ | | `redis_url` | string or null | `null` | `BASIC_MEMORY_REDIS_URL` | | `redis_max_connections` | integer greater than `0` | `20` | `BASIC_MEMORY_REDIS_MAX_CONNECTIONS` | The cache is optional and limited to standalone MCP read paths. An unset URL disables it. If Redis is unavailable, Basic Memory fails open to authoritative storage reads rather than failing the request. --- ## CLI output settings ### `cli_output_style` Choose the default presentation for interactive `bm tool` commands. - Type: `"rich" | "plain"` - Default: `"rich"` - Env: `BASIC_MEMORY_CLI_OUTPUT_STYLE` This setting affects interactive `search`, `read-note`, `build-context`, and `recent-activity` output. Redirected output defaults to JSON. Explicit `--json` and `--plain` flags take precedence over TTY detection and this setting. --- ## Cloud settings ### `cloud_mode` Cloud deployment mode (derived, not a config-file setting). - Type: boolean (read-only property) - Env: `BASIC_MEMORY_CLOUD_MODE` Set by managed cloud deployments via the environment variable. A `cloud_mode` key in `config.json` is ignored and removed on load — don't set it for local installs. ### `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` - `sync_changes` to `index_changes` - `sync_delay` to `index_delay` The corresponding `BASIC_MEMORY_SYNC_CHANGES` and `BASIC_MEMORY_SYNC_DELAY` environment variables are also accepted as migration aliases, but the new environment names win when both are set. Removed `sync_thread_pool_size` and `sync_max_concurrent_files` keys are ignored. After file-based 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) - [Postgres and Milvus](https://docs.basicmemory.com/local/postgres-and-milvus) - [Upgrade to v0.23](https://docs.basicmemory.com/whats-new/v0-23-upgrade) # Docker ::warning Docker is an advanced deployment path. For most local desktop and coding tools, install Basic Memory with `uv tool install basic-memory` or Homebrew and let the tool launch `uvx basic-memory mcp` . :: ## What Docker is for The official Docker image runs the Basic Memory MCP server in a container. It is useful when you want: - A repeatable server deployment - Docker Compose or Kubernetes orchestration - A shared test environment - CI jobs that need Basic Memory available over HTTP - A controlled self-hosted MCP experiment It is **not** the recommended path for day-one local use. Local MCP clients usually expect a stdio process they can launch themselves. See [Local Install](https://docs.basicmemory.com/local/local-install) for that setup. ## Image The image is published to GitHub Container Registry: ```bash docker pull ghcr.io/basicmachines-co/basic-memory:latest ``` The image is built from the [Basic Memory repository](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""} and runs as a non-root user. ## Run a container Mount a local knowledge folder and expose the MCP server: ```bash docker run -d \ --name basic-memory-server \ -p 8000:8000 \ -v "$PWD/knowledge:/app/data" \ -v basic-memory-config:/home/appuser/.basic-memory \ ghcr.io/basicmachines-co/basic-memory:latest ``` The server listens on port `8000`. ::caution The container's SSE and HTTP endpoints are not secured by Basic Memory. Do not expose them directly to the public internet. Put authentication, TLS, and network access controls in front of any remote deployment. :: ## Docker Compose Use Compose when you want persistent configuration and a repeatable project mount: ```yaml services: basic-memory: image: ghcr.io/basicmachines-co/basic-memory:latest container_name: basic-memory-server ports: - "8000:8000" volumes: - basic-memory-config:/home/appuser/.basic-memory:rw - ./knowledge:/app/data:rw environment: - BASIC_MEMORY_DEFAULT_PROJECT=main - BASIC_MEMORY_INDEX_CHANGES=true - BASIC_MEMORY_LOG_LEVEL=INFO - BASIC_MEMORY_INDEX_DELAY=1000 command: ["basic-memory", "mcp", "--transport", "sse", "--host", "0.0.0.0", "--port", "8000"] restart: unless-stopped healthcheck: test: ["CMD", "basic-memory", "--version"] interval: 30s timeout: 10s retries: 3 start_period: 30s volumes: basic-memory-config: ``` Start it: ```bash docker compose up -d ``` Check logs: ```bash docker logs basic-memory-server ``` ## Configuration Configuration comes from these environment variables — the image itself sets `BASIC_MEMORY_HOME` and `BASIC_MEMORY_PROJECT_ROOT`; the rest are set by the Compose example (shown with their application defaults): | Variable | Default | Purpose | | ------------------------------ | ----------------------------- | ------------------------------------------ | | `BASIC_MEMORY_HOME` | `/app/data/basic-memory` | Basic Memory home inside the container | | `BASIC_MEMORY_PROJECT_ROOT` | `/app/data` | Root directory for mounted projects | | `BASIC_MEMORY_DEFAULT_PROJECT` | `main` in the Compose example | Default project name | | `BASIC_MEMORY_INDEX_CHANGES` | `true` in the Compose example | Enable real-time indexing of file changes | | `BASIC_MEMORY_LOG_LEVEL` | `INFO` in the Compose example | Log verbosity | | `BASIC_MEMORY_INDEX_DELAY` | `1000` in the Compose example | File-change indexing delay in milliseconds | Mount two kinds of storage: - **Knowledge files:** mount your Markdown/project directory at `/app/data`. - **Configuration and local index:** mount `/home/appuser/.basic-memory` to a named volume so configuration and database state survive container restarts. ## Connect a client The Docker image starts Basic Memory with SSE transport by default: ```bash basic-memory mcp --transport sse --host 0.0.0.0 --port 8000 ``` Use Docker only with clients or gateways that can reach an HTTP/SSE MCP server. If your client expects local stdio config, use the local install path instead: ```json { "mcpServers": { "basic-memory": { "command": "uvx", "args": ["basic-memory", "mcp"] } } } ``` ## Run CLI commands inside the container You can inspect the container with normal Basic Memory commands: ```bash docker exec basic-memory-server basic-memory --version docker exec basic-memory-server bm status docker exec basic-memory-server bm project list ``` Use `docker exec` for diagnostics and scripted maintenance. For everyday local work, use the installed CLI on your host machine. ## PostgreSQL backend Basic Memory supports **PostgreSQL with `pgvector`** as a database backend — it's the same configuration Basic Memory Cloud runs on. Point your container at a Postgres instance with two environment variables: ```bash BASIC_MEMORY_DATABASE_BACKEND=postgres BASIC_MEMORY_DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/dbname ``` Connection pooling is tuned via `db_pool_size`, `db_pool_overflow`, and `db_pool_recycle` — see [Configuration](https://docs.basicmemory.com/reference/configuration#database-settings). SQLite remains the default and needs no setup. ## Troubleshooting ### Port 8000 is already in use Map a different host port: ```bash docker run -d \ -p 3000:8000 \ -v "$PWD/knowledge:/app/data" \ -v basic-memory-config:/home/appuser/.basic-memory \ ghcr.io/basicmachines-co/basic-memory:latest ``` The container still listens on `8000`; the host listens on `3000`. ### Permission denied on mounted files The container runs as a non-root user. If it cannot read or write your mounted directory, fix ownership or run with a matching user: ```bash sudo chown -R 1000:1000 ./knowledge ``` or: ```bash docker run --user "$(id -u):$(id -g)" ... ``` ### The client cannot connect Check three things: 1. The container is running: `docker ps` 2. The server logs are clean: `docker logs basic-memory-server` 3. Your client supports the transport you configured If the client only supports local stdio MCP, Docker is the wrong connection path. Use [Local MCP tools](https://docs.basicmemory.com/local/mcp-tools-local) instead. ## Build from source Clone the Basic Memory source repository and build the image locally: ```bash git clone https://github.com/basicmachines-co/basic-memory.git cd basic-memory docker build -t basic-memory:local . ``` You can pass custom UID/GID build arguments if your deployment needs specific file ownership: ```bash docker build \ --build-arg UID=1001 \ --build-arg GID=1001 \ -t basic-memory:custom . ``` ## See also ::card-group :::card --- icon: i-lucide-terminal title: Local Install to: https://docs.basicmemory.com/local/local-install --- Install Basic Memory for local desktop and coding tools. ::: :::card --- icon: i-lucide-square-terminal title: CLI Reference to: https://docs.basicmemory.com/reference/cli-reference --- Look up Basic Memory commands and flags. ::: :::card --- icon: i-lucide-life-buoy title: Troubleshooting to: https://docs.basicmemory.com/reference/troubleshooting --- Diagnose install, MCP, sync, and routing problems. ::: :: # 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: ```text 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 --- ## Next Steps ::card-group :::card --- icon: i-lucide-wrench title: MCP Tools Reference to: https://docs.basicmemory.com/reference/mcp-tools-reference --- The tools your AI uses once it's read the docs. ::: :::card --- icon: i-lucide-lightbulb title: What is Basic Memory to: https://docs.basicmemory.com/start-here/what-is-basic-memory --- The overview, human-readable edition. ::: ::