+
+
+
+
+
diff --git a/astro.config.mjs b/astro.config.mjs
deleted file mode 100644
index 4ab3264..0000000
--- a/astro.config.mjs
+++ /dev/null
@@ -1,33 +0,0 @@
-// @ts-check
-import { defineConfig } from 'astro/config';
-
-import mdx from '@astrojs/mdx';
-import react from '@astrojs/react';
-import pagefind from 'astro-pagefind';
-import mermaid from 'astro-mermaid';
-
-// https://astro.build/config
-export default defineConfig({
- integrations: [mdx(), react(), pagefind(), mermaid({
- theme: 'default',
- mermaidConfig: {
- themeVariables: {
- darkMode: true,
- primaryTextColor: '#f3f4f6',
- secondaryTextColor: '#e5e7eb',
- tertiaryTextColor: '#d1d5db'
- }
- }
- })],
- markdown: {
- syntaxHighlight: 'shiki',
- shikiConfig: {
- themes: {
- light: 'github-light',
- dark: 'github-dark'
- },
- wrap: false
- }
- },
- site: 'https://docs.basicmemory.com'
-});
diff --git a/components.json b/components.json
deleted file mode 100644
index 32ebeeb..0000000
--- a/components.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
- "$schema": "https://ui.shadcn.com/schema.json",
- "style": "default",
- "rsc": false,
- "tsx": true,
- "tailwind": {
- "config": "tailwind.config.js",
- "css": "src/styles/global.css",
- "baseColor": "slate",
- "cssVariables": true,
- "prefix": ""
- },
- "aliases": {
- "components": "@/components",
- "utils": "@/lib/utils"
- }
-}
\ No newline at end of file
diff --git a/content/1.start-here/.navigation.yml b/content/1.start-here/.navigation.yml
new file mode 100644
index 0000000..4c2e122
--- /dev/null
+++ b/content/1.start-here/.navigation.yml
@@ -0,0 +1,2 @@
+title: Start Here
+icon: i-lucide-rocket
diff --git a/content/1.start-here/1.what-is-basic-memory.md b/content/1.start-here/1.what-is-basic-memory.md
new file mode 100644
index 0000000..7486d74
--- /dev/null
+++ b/content/1.start-here/1.what-is-basic-memory.md
@@ -0,0 +1,434 @@
+---
+title: What is Basic Memory
+description: An overview of what Basic Memory is and how it works.
+---
+
+Basic Memory is a knowledge base that you and your AI assistant share. It stores notes as Markdown files so your work stays readable, portable, and searchable.
+
+Instead of losing valuable insights in conversation history, you build a persistent knowledge base where both you and AI can read, write, and enhance each other's work.
+
+---
+:video{autoplay controls loop muted src="https://basicmemory.com/videos/explainer-video.mp4"}
+
+## Why Basic Memory?
+
+**The problem:** AI conversations are ephemeral. You have a great discussion, make important decisions, learn something new - and then it's gone, buried in chat history.
+
+**The solution:** Basic Memory gives your AI assistant a persistent memory. Knowledge captured in one conversation is available in all future conversations. Your AI can reference past discussions, decisions, and context.
+
+**Key benefits:**
+- **Persistent context** - Knowledge survives across conversations
+- **You own your data** - Plain Markdown files you control
+- **Structured knowledge** - Observations and relations create a semantic graph
+- **Works with any AI** - Claude, ChatGPT, and other MCP-compatible assistants
+
+---
+
+## What it does
+
+:::card-group
+::card
+---
+title: Stores notes as Markdown
+icon: i-lucide-file-text
+---
+Notes are plain files you can edit with any editor. No lock-in, no proprietary formats.
+::
+
+::card
+---
+title: Connects ideas with links
+icon: i-lucide-link
+---
+Relations and tags turn notes into a knowledge graph that grows over time.
+::
+
+::card
+---
+title: Lets assistants search and write
+icon: i-lucide-search
+---
+MCP tools let your assistant read, write, search, and organize notes.
+::
+
+::card
+---
+title: Cloud or Local
+icon: i-lucide-cloud
+---
+Use the hosted cloud service or run everything locally - your choice.
+::
+:::
+
+---
+
+## How it works
+
+Basic Memory runs an MCP server that can read and write Markdown files. A SQLite index keeps search fast. Your assistant calls tools like `search_notes`, `read_note`, and `write_note` to work with your notes.
+
+::mermaid
+---
+code: |
+ flowchart LR
+ subgraph You
+ A[AI Assistant]
+ E[Editor]
+ end
+
+ subgraph Basic Memory
+ M[MCP Server]
+ I[Index]
+ end
+
+ subgraph Storage
+ F[Markdown Files]
+ end
+
+ A <-->|MCP Tools| M
+ E <-->|Edit| F
+ M <-->|Read/Write| F
+ M <-->|Query| I
+ F -.->|Sync| I
+---
+::
+
+### The workflow
+
+1. **Capture a note** - You write or ask your assistant to write a note during a conversation.
+
+2. **Index and connect** - The system indexes the note, extracts observations and relations, and links it to related notes.
+
+3. **Reuse later** - In future conversations, your assistant searches and loads relevant context automatically.
+
+### Example conversation
+
+```bash
+You: "What did we decide about the authentication approach?"
+
+AI: [Searches knowledge base, finds your past notes]
+ "Based on your notes, you decided to use JWT tokens for API
+ authentication. The decision was made on January 15th and
+ documented in 'Decision: API Authentication'."
+
+You: "Add a note about implementing refresh tokens"
+
+AI: [Creates a new note linked to the authentication decision]
+ "I've created a note about refresh tokens and linked it to
+ your authentication decision notes."
+```
+
+---
+
+## What a note looks like
+
+Notes are standard Markdown with optional semantic structure:
+
+```bash
+---
+title: API Authentication Decision
+tags: [security, api, auth]
+---
+
+# API Authentication Decision
+
+## Context
+We needed to choose an authentication approach for the new API.
+
+## Observations
+- [decision] Use JWT tokens for API auth #security
+- [requirement] Tokens expire after 24 hours
+- [risk] Rate limiting needed on login endpoint #auth
+
+## Relations
+- implements [[API Security Spec]]
+- depends_on [[User Service]]
+- relates_to [[Token Refresh]]
+```
+
+**Key concepts:**
+- **Observations** - Categorized facts: `[decision]`, `[requirement]`, `[risk]`, etc.
+- **Relations** - Links to other notes: `[[Other Note]]` in simple WiliLink format
+- **Tags** - Searchable metadata: `#security`, `#api`
+
+::tip
+The headings '## Observations' and '## Relations' are only informative. Basic Memory will parse elements from any
+where in the Markdown.
+::
+
+---
+
+## What the AI sees
+
+When your AI assistant searches your knowledge base, it doesn't just find text - it navigates a semantic graph of connected ideas.
+
+### The knowledge graph
+
+Each note becomes an **entity** with structured data:
+
+::mermaid
+---
+code: |
+ flowchart TD
+ subgraph "Knowledge Graph"
+ E1[API Authentication]
+ E2[API Security Spec]
+ E3[User Service]
+ E4[Token Refresh]
+ end
+
+ subgraph "API Authentication: Facts"
+ O1[JWT]
+ O2[Tokens exgire]
+ O3[Rate limiting]
+ end
+
+ E1 -->|implements| E2
+ E1 -->|depends_on| E3
+ E1 -->|relates_to| E4
+
+ E1 -->|decision| O1
+ E1 -->|requirement| O2
+ E1 -->|risk| O3
+---
+::
+
+- **Entities** - Each note is an entity with a title, content, and metadata
+- **Observations** - Categorized facts extracted from the note (decisions, requirements, risks)
+- **Relations** - Typed links connecting entities (`implements`, `depends_on`, `relates_to`)
+
+### Building context
+
+When you ask a question, the AI doesn't just return one note. It traverses the graph to build rich context:
+
+::mermaid
+---
+code: |
+ flowchart LR
+ Q[Your Question] --> S[search_notes]
+ S --> R[Matching Notes]
+
+ R --> G[Relationed Notes]
+ R -->|Build| C[Context]
+ C --> A[AI Response]
+ G -->|Follow| R
+---
+::
+
+**The flow:**
+
+1. **Search** - Your question triggers a search across all notes
+2. **Expand** - The AI uses `build_context` to follow relations and gather connected notes
+3. **Synthesize** - With the full context loaded, the AI can give a complete answer
+
+This recursive traversal means asking about "API authentication" automatically pulls in related decisions, dependencies, and connected topics - giving your AI the full picture.
+
+### Memory URLs
+
+The AI references knowledge using `memory://` URLs:
+
+```bash
+memory://api-authentication # Reference by permalink
+memory://api-authentication/relates_to/* # Follow all 'relates_to' links
+memory://folder/note-title # Reference by path
+```
+
+These stable identifiers let the AI (and you) pinpoint exactly what context to load.
+
+::tip
+You don't have to understand or think about the object graph or relations. You can just ask the AI to manage it for you.
+::
+
+```bash
+You: "Make sure you add observations and relations to this note"
+
+AI: [Update the note with semantic information]
+ "OK I've updated the note with observations and relations...."
+
+You: "Make sure you do this for all our other notes :)"
+
+AI: [Makes a note in its own memory to keep notes annotated with semantic information]
+ "I'll remember that...."
+```
+
+---
+
+## Seeing into the black box
+
+AI memory is typically opaque - you don't know what context the AI has or what it "remembers." Basic Memory makes this transparent.
+
+- **See what your AI sees** - Every piece of context is a file you can read
+- **Edit what your AI knows** - Modify, delete, or reorganize knowledge anytime
+- **Watch changes happen** - See exactly what your AI adds or updates
+- **Keep your memory** - Plain Markdown files you own forever
+- **Audit trail** - Every note has a history; you can see what was added when
+- **No surprises** - The AI can only know what's in your files; no hidden context
+- **Portable knowledge** - Plain markdown means you're never locked in; chat with one AI, bring your knowledge to the next
+
+---
+
+## Closing the loop
+
+AI agents work best when they can observe the results of their actions. Basic Memory creates a feedback loop where each conversation builds on the last.
+
+**How it works:**
+- **Cumulative intelligence** - Each conversation adds to the knowledge base, making future conversations smarter
+- **Human-in-the-loop refinement** - You can correct and improve AI-generated notes, and the AI learns from your edits
+- **Context compounds** - Unlike chat history that gets truncated, knowledge persists and connects
+- **Pattern recognition** - Over time, the AI can recognize patterns across your entire knowledge base
+
+### The feedback loop
+
+::mermaid
+---
+code: |
+ flowchart LR
+ A[Conversation] --> B[AI Writes Memory]
+ B --> C[Human Reviews/Edits]
+ C --> D[AI Reads Context]
+ D --> A
+---
+::
+
+Each cycle reinforces learning. You ask questions, the AI searches and responds, creates notes from the conversation, and you review and refine. The knowledge base grows with each iteration.
+
+### Knowledge growth over time
+
+::mermaid
+---
+code: |
+ flowchart TD
+ subgraph "The Loop"
+ A[Ask Question] --> B[AI Searches Memory]
+ B --> C[AI Responds + Writes]
+ C --> D[You Review & Refine]
+ D --> E[Knowledge Base Grows]
+ E --> B
+ end
+---
+::
+
+
+### Knowledge refinement over time
+
+Each conversation builds on previous context, creating increasingly refined understanding:
+
+::mermaid
+---
+code: |
+ flowchart TD
+ A[Conversation 1] --> B[Memory v1]
+ B --> C[Conversation 2]
+ C --> D[Memory v2 - refined]
+ D --> E[Conversation 3]
+ E --> F[Memory v3 - richer]
+ F --> G[...]
+---
+::
+
+The result: your AI gets smarter about *your* work with every interaction.
+
+---
+
+## Where it runs
+
+### Cloud
+
+Basic Memory Cloud provides:
+- **Hosted MCP endpoint** - Connect without installing anything
+- **Access from any device** - Use your memory from desktop, mobile, cli, multiple AIs
+- **Web app** - Browse and edit notes in your browser
+- **Local sync** - Sync your notes locally for easy management
+- **Snapshots** - Point-in-time backups, automaticly done daily or manual as needed
+
+### Local
+
+The open-source local version provides:
+- **Full control** - Everything runs on your machine
+- **No account needed** - Use immediately after install
+- **CLI tools** - Command-line access to all features
+- **Offline access** - Works without internet
+
+**Both use the same Markdown format**, so you can start with one and switch to the other later.
+
+---
+
+## MCP Integration
+
+Basic Memory uses the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) to connect with AI assistants. MCP is an open standard that lets AI assistants use external tools.
+
+**Available tools:**
+- `write_note` - Create or update notes
+- `read_note` - Read notes with context
+- `search_notes` - Full-text search
+- `edit_note` - Incremental editing
+- `build_context` - Load related notes
+- `list_memory_projects` - Manage projects
+- ...and many more
+
+**Compatible assistants:**
+- Claude Desktop
+- Claude Code
+- ChatGPT (Pro/Max)
+- Google Gemini
+- Cursor
+- VS Code (with MCP extension)
+- Codex
+
+---
+
+## Getting started
+
+Ready to try Basic Memory?
+
+:::card-group
+::card
+---
+title: "Quickstart: Cloud"
+icon: i-lucide-cloud
+to: /start-here/quickstart-cloud
+---
+Connect in 2 minutes. No installation required.
+::
+
+::card
+---
+title: "Quickstart: Local"
+icon: i-lucide-hard-drive
+to: /start-here/quickstart-local
+---
+Install locally and run everything on your machine.
+::
+:::
+
+---
+
+## Next steps
+
+:::card-group
+::card
+---
+title: Getting Started
+icon: i-lucide-rocket
+to: /start-here/getting-started
+---
+Full installation guide with configuration options.
+::
+
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+Learn the note structure with observations and relations.
+::
+
+::card
+---
+title: MCP Tools Reference
+icon: i-lucide-wrench
+to: /reference/mcp-tools-reference
+---
+All available tools for AI assistants.
+::
+:::
diff --git a/content/1.start-here/2.quickstart-cloud.md b/content/1.start-here/2.quickstart-cloud.md
new file mode 100644
index 0000000..36df50f
--- /dev/null
+++ b/content/1.start-here/2.quickstart-cloud.md
@@ -0,0 +1,239 @@
+---
+title: "Quickstart: Cloud"
+description: Connect Basic Memory Cloud and create your first note in 2 minutes.
+---
+
+Basic Memory Cloud gives you a hosted MCP endpoint and a web app. Connect your AI assistant and start writing notes in minutes - no installation required.
+
+::mermaid
+---
+code: |
+ flowchart LR
+ A[Sign Up] --> B[Connect AI]
+ B --> C[Create Note]
+ C --> D[View in App]
+---
+::
+
+---
+
+## 1. Create an account
+
+Sign up at [app.basicmemory.com](https://app.basicmemory.com). You'll need an active subscription to use the MCP endpoint.
+
+
+
+
+---
+
+## 2. Connect your AI assistant
+
+Use the remote MCP endpoint URL:
+
+```bash
+https://cloud.basicmemory.com/mcp
+```
+
+### For Claude Desktop
+
+::steps
+### Open Settings
+In Claude Desktop or Claude.ai, go to **Settings → Claude → Connectors**
+
+
+
+### Add Custom Connector
+Click **Add custom connector** and enter:
+- **Name**: Basic Memory
+- **Remote MCP server URL**: `https://cloud.basicmemory.com/mcp`
+
+
+
+### Authenticate
+Click **Connect** to start the OAuth flow. You'll be redirected to Basic Memory to authorize access.
+
+
+
+
+
+### Configure Tools (Optional)
+Click **Configure** to customize which tools are enabled.
+
+
+
+### Verify Setup
+Confirm Basic Memory appears in the tools menu (+ icon in chat).
+
+
+::
+
+### For ChatGPT
+
+::note
+ChatGPT requires a **Pro or Max subscription** to use Remote MCP servers.
+::
+
+::steps
+### Enable MCP
+Open **Settings → Beta features** and enable MCP
+
+### Add Endpoint
+Add the Basic Memory endpoint URL: `https://cloud.basicmemory.com/mcp`
+
+### Authenticate
+Complete the OAuth flow when prompted
+::
+
+::tip
+Watch the [ChatGPT setup video](https://youtube.com/watch?v=NvU0Jo38P_k) for a complete walkthrough.
+::
+
+### For other assistants
+
+See the [Integrations](/integrations/claude-desktop) section for setup guides for:
+- [Google Gemini](/integrations/gemini)
+- [Cursor](/integrations/cursor)
+- [VS Code](/integrations/vscode)
+- [Claude Code](/integrations/claude-code)
+
+---
+
+## 3. Verify the connection
+
+Ask your assistant:
+
+```bash
+List my basic memory projects
+```
+
+**Expected response:**
+```bash
+You have 1 project:
+- main (default) - /app/data/basic-memory - 0 notes
+```
+
+
+
+::warning
+If you get an error, check the [Troubleshooting](/reference/troubleshooting) guide.
+::
+
+---
+
+## 4. Create your first note
+
+Try this prompt:
+
+```bash
+Create a note called "Getting Started" with a summary of what Basic Memory does.
+```
+
+Your assistant will use the `write_note` tool to create a Markdown file in your cloud storage.
+
+**Example conversation:**
+```bash
+You: Create a note called "Getting Started" with a summary of what Basic Memory does.
+
+AI: I'll create a note summarizing Basic Memory for you.
+
+[Uses write_note tool]
+
+I've created "Getting Started" in your knowledge base. The note covers:
+- What Basic Memory is
+- How the knowledge format works
+- Key features like semantic search and relations
+```
+
+
+
+---
+
+## 5. View your notes
+
+Open [app.basicmemory.com/notes](https://app.basicmemory.com/notes) to see your new note.
+
+
+
+**What you can do in the web app:**
+- Browse all your notes in the folder tree
+- Edit notes with the live Markdown editor
+- Search across your knowledge base
+- Import existing data from Claude, ChatGPT, or files
+- Manage multiple projects
+- Create snapshots for backup
+
+---
+
+## What you can do now
+
+Try these prompts with your assistant:
+
+| Prompt | What it does |
+|--------|--------------|
+| `Create a note about [topic]` | Creates a new note with semantic structure |
+| `What have we discussed recently?` | Shows recently modified notes |
+| `Find notes about [topic]` | Searches your knowledge base |
+| `Continue our conversation about [topic]` | Loads context from previous notes |
+| `Add to my notes about [topic]` | Edits an existing note |
+| `Show me my notes on [topic]` | Displays a formatted note |
+
+### Example workflow
+
+```bash
+You: "I've been researching coffee brewing methods. Create a note about pour-over technique."
+
+AI: [Creates note with observations and tags]
+
+--- Later ---
+
+You: "What do I know about coffee brewing?"
+
+Claude: [Searches knowledge base, finds your pour-over note]
+"Based on your notes, you've been exploring pour-over techniques..."
+
+You: "Add a section about water temperature to my coffee notes"
+
+Claude: [Uses edit_note to append new content]
+```
+
+---
+
+## Next steps
+
+:::card-group
+::card
+---
+title: Cloud Guide
+icon: i-lucide-cloud
+to: /cloud/cloud-guide
+---
+Full cloud features including CLI tools, snapshots, and migration.
+::
+
+::card
+---
+title: Web App Guide
+icon: i-lucide-layout-panel-left
+to: /cloud/web-app
+---
+Learn the web interface for browsing and editing notes.
+::
+
+::card
+---
+title: Cloud Sync
+icon: i-lucide-refresh-cw
+to: /cloud/cloud-sync
+---
+Set up bidirectional sync with local files.
+::
+
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+Learn the note structure with observations and relations.
+::
+:::
diff --git a/content/1.start-here/3.quickstart-local.md b/content/1.start-here/3.quickstart-local.md
new file mode 100644
index 0000000..d10da7a
--- /dev/null
+++ b/content/1.start-here/3.quickstart-local.md
@@ -0,0 +1,355 @@
+---
+title: "Quickstart: Local"
+description: Install Basic Memory locally and connect it to your AI assistant.
+---
+
+Local mode keeps notes on your machine and runs the MCP server locally. It's open-source and free to use.
+
+::mermaid
+---
+code: |
+ flowchart LR
+ A[Install] --> B[Configure]
+ B --> C[Connect]
+ C --> D[Create Notes]
+---
+::
+
+---
+
+## 1. Install Basic Memory
+
+Choose your installation method:
+
+### macOS (Homebrew) - Recommended
+
+```bash
+brew tap basicmachines-co/basic-memory
+brew install basic-memory
+```
+
+### All platforms (uv)
+
+First install `uv` from [astral.sh](https://docs.astral.sh/uv/getting-started/installation/), then:
+
+```bash
+uv tool install basic-memory
+```
+
+::note
+**Requirements:** Python 3.13 or higher. Check with `python --version`.
+::
+
+### Verify installation
+
+```bash
+basic-memory --version
+```
+
+**Expected output:**
+```bash
+basic-memory, version 0.18.x
+```
+
+
+
+
+---
+
+## 2. Configure Claude Desktop
+
+Edit your Claude Desktop config file:
+
+| Platform | Config Location |
+|----------|-----------------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+
+Add this configuration:
+
+```json
+{
+ "mcpServers": {
+ "basic-memory": {
+ "command": "uvx",
+ "args": ["basic-memory", "mcp"]
+ }
+ }
+}
+```
+
+::warning
+**ENOENT error?** Use the full path to uvx. Find it with `which uvx` and replace `"uvx"` with the full path (e.g., `"/Users/yourname/.local/bin/uvx"`).
+::
+
+**Restart Claude Desktop** after editing the config.
+
+
+
+
+---
+
+## 3. Verify the connection
+
+In Claude Desktop, click the **tools icon** (hammer) in the bottom-right of the chat interface. You should see Basic Memory tools listed.
+
+
+
+
+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 "Getting Started" with a summary of what Basic Memory does.
+```
+
+Claude will create a Markdown file at `~/basic-memory/Getting Started.md`.
+
+**Example conversation:**
+```bash
+You: Create a note called "Getting Started" with a summary of what Basic Memory does.
+
+Claude: I'll create a note for you.
+
+[Uses write_note tool]
+
+Done! I've created "Getting Started.md" in your basic-memory folder.
+It includes an overview of Basic Memory's key features:
+- Knowledge storage in Markdown
+- Semantic observations and relations
+- Search across your knowledge base
+```
+
+
+
+
+---
+
+## 5. View your notes
+
+Your notes are stored at `~/basic-memory` by default. You can:
+
+### Open in any text editor
+
+```bash
+# View in terminal
+cat ~/basic-memory/Getting\ Started.md
+
+# Open folder
+open ~/basic-memory # macOS
+explorer ~/basic-memory # Windows
+```
+
+### Use Obsidian for visual navigation
+
+1. Open Obsidian
+2. **Create new vault** → select `~/basic-memory`
+3. Use the **graph view** to see connections between notes
+
+
+
+
+### Example note structure
+
+After creating a few notes, your folder might look like:
+
+```bash
+~/basic-memory/
+├── Getting Started.md
+├── projects/
+│ └── API Design.md
+├── research/
+│ └── Database Optimization.md
+└── meetings/
+ └── Team Standup 2024-01-15.md
+```
+
+---
+
+## What you can do now
+
+Try these prompts with Claude:
+
+| Prompt | What it does |
+|--------|--------------|
+| `Create a note about [topic]` | Creates a new Markdown file |
+| `What have we discussed recently?` | Shows recently modified notes |
+| `Find notes about [topic]` | Searches your knowledge base |
+| `Continue our conversation about [topic]` | Loads context from previous notes |
+| `Add to my [topic] notes` | Edits an existing note |
+| `Move my [note] to the archive folder` | Reorganizes files |
+
+### Example workflow
+
+```bash
+You: "Let's document our API design decisions"
+
+Claude: I'll create a note for the API design decisions.
+[Creates ~/basic-memory/API Design Decisions.md]
+
+--- Later ---
+
+You: "What did we decide about authentication?"
+
+Claude: [Searches knowledge base]
+"Based on your 'API Design Decisions' note, you decided to use JWT tokens..."
+
+You: "Add a section about rate limiting"
+
+Claude: [Uses edit_note to append]
+"I've added a rate limiting section to your API design notes."
+```
+
+---
+
+## Customize your setup
+
+### Change where notes are saved
+
+```bash
+# Create a new project in a different location
+basic-memory project add "my-notes" ~/Documents/notes
+
+# Make it the default
+basic-memory project default "my-notes"
+```
+
+Restart Claude Desktop for changes to take effect.
+
+### Skip project selection prompts
+
+If you only use one project, add to `~/.basic-memory/config.json`:
+
+```json
+{
+ "default_project": "main",
+ "default_project_mode": true
+}
+```
+
+---
+
+## Useful CLI commands
+
+```bash
+# Check sync status
+basic-memory status
+
+# List all projects
+basic-memory project list
+
+# View project statistics
+basic-memory project info
+
+# Import Claude conversations
+basic-memory import claude conversations
+
+# Import ChatGPT conversations
+basic-memory import chatgpt
+
+# Force re-sync all files
+basic-memory sync
+```
+
+
+
+
+---
+
+## Troubleshooting
+
+### ENOENT error
+
+Claude Desktop can't find `uvx`. Use the full path:
+
+```bash
+# Find the path
+which uvx
+# Output: /Users/yourname/.local/bin/uvx
+
+# Update config to use full path
+{
+ "mcpServers": {
+ "basic-memory": {
+ "command": "/Users/yourname/.local/bin/uvx",
+ "args": ["basic-memory", "mcp"]
+ }
+ }
+}
+```
+
+### No tools showing
+
+1. Verify installation: `basic-memory --version`
+2. Check the config file syntax (valid JSON)
+3. Restart Claude Desktop completely
+
+### Permission errors
+
+```bash
+# Fix permissions on the notes folder
+chmod -R u+rw ~/basic-memory
+```
+
+See the full [Troubleshooting](/reference/troubleshooting) guide for more solutions.
+
+---
+
+## Next steps
+
+:::card-group
+::card
+---
+title: CLI Basics
+icon: i-lucide-terminal
+to: /local/cli-basics
+---
+Learn the command line tools for managing your knowledge.
+::
+
+::card
+---
+title: Configuration
+icon: i-lucide-settings
+to: /reference/configuration
+---
+All configuration options and environment variables.
+::
+
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+Learn the note structure with observations and relations.
+::
+
+::card
+---
+title: Obsidian Integration
+icon: i-lucide-hexagon
+to: /integrations/obsidian
+---
+Visual knowledge navigation with graph view.
+::
+:::
diff --git a/content/1.start-here/4.getting-started.md b/content/1.start-here/4.getting-started.md
new file mode 100644
index 0000000..51f2a42
--- /dev/null
+++ b/content/1.start-here/4.getting-started.md
@@ -0,0 +1,173 @@
+---
+title: Getting Started
+description: Configure where notes are saved and manage multiple projects.
+---
+
+Ready to set up Basic Memory? Start with the quickstart guides:
+
+:::card-group
+::card
+---
+title: "Quickstart: Cloud"
+icon: i-lucide-cloud
+to: /start-here/quickstart-cloud
+---
+Connect in 2 minutes. No installation required.
+::
+
+::card
+---
+title: "Quickstart: Local"
+icon: i-lucide-hard-drive
+to: /start-here/quickstart-local
+---
+Install locally and run everything on your machine.
+::
+:::
+
+---
+
+## Choosing Where Notes Are Saved
+
+By default, Basic Memory saves notes in a project called `main` in `~/basic-memory`. To save notes elsewhere:
+
+### Use Your Existing Notes Folder
+
+Ask your AI assistant directly:
+
+```bash
+Create a new project called "my project" in the "/Users/yourname/Documents/Notes" directory
+```
+
+Then:
+
+```bash
+Set the default project to "my project"
+```
+
+Or use the command line:
+
+```bash
+# Point Basic Memory to your existing notes folder
+basic-memory project add "my project"
+
+# Make it your default location
+basic-memory project default "my project"
+```
+
+::warning
+If you change default projects from the command line, new notes will be saved in your chosen folder after restarting Claude Desktop.
+::
+
+**Want to use Obsidian?** Just open your folder location as a vault. See the [Obsidian Integration](/integrations/obsidian) guide.
+
+::note
+**Advanced configuration**: Basic Memory stores its settings in `~/.basic-memory/config.json`. While CLI commands are recommended for configuration, you can edit this file directly. Changes require restarting Claude Desktop.
+::
+
+---
+
+## Multi-Project Setup
+
+Basic Memory supports multiple projects for organizing different knowledge bases (work, personal, research, etc.).
+
+**How it works:**
+
+When you start a conversation, the AI will:
+1. Check your available projects
+2. Suggest the most active project based on recent activity
+3. Ask which project to use for this conversation
+4. Remember your choice throughout the session
+
+**Example:**
+```bash
+You: "Let's work on documentation"
+
+Claude: I see you have 3 projects: main, work-notes, personal
+Your most active project is work-notes
+Should I use work-notes for this task?
+
+You: "Yes, let's use work-notes"
+```
+
+**Creating projects:**
+```bash
+# Command line
+basic-memory project add "work-notes" ~/Documents/work
+
+# Or ask your AI assistant
+You: "Create a new project called 'work-notes' in ~/Documents/work"
+```
+
+**For users who primarily work in one project:**
+
+Enable Default Project Mode in `~/.basic-memory/config.json`:
+
+```json
+{
+ "default_project": "main",
+ "default_project_mode": true
+}
+```
+
+With this enabled, the AI uses your default project automatically 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
+---
+title: User Guide
+icon: i-lucide-book-open
+to: /local/user-guide
+---
+Comprehensive usage instructions for daily workflows.
+::
+
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+Learn how knowledge is structured with semantic patterns.
+::
+
+::card
+---
+title: CLI Reference
+icon: i-lucide-terminal
+to: /reference/cli-reference
+---
+Complete command line tools reference.
+::
+
+::card
+---
+title: Troubleshooting
+icon: i-lucide-wrench
+to: /reference/troubleshooting
+---
+Common issues and solutions.
+::
+:::
diff --git a/content/2.whats-new/.navigation.yml b/content/2.whats-new/.navigation.yml
new file mode 100644
index 0000000..8192e1d
--- /dev/null
+++ b/content/2.whats-new/.navigation.yml
@@ -0,0 +1,2 @@
+title: What's New
+icon: i-lucide-megaphone
diff --git a/content/2.whats-new/1.cloud.md b/content/2.whats-new/1.cloud.md
new file mode 100644
index 0000000..3e8f62f
--- /dev/null
+++ b/content/2.whats-new/1.cloud.md
@@ -0,0 +1,164 @@
+---
+title: Basic Memory Cloud
+description: Cloud UI updates and new features.
+---
+
+::tip
+[Basic Memory Cloud](/cloud/cloud-guide) is live! Now accessible from everywhere, in the Cloud. [Sign up](https://app.basicmemory.com) with a 7 day free trial.
+::
+
+Work with your knowledge base across multiple devices using cloud sync and storage.
+
+## Cloud App Updates
+
+Recent web UI work focuses on the notes experience:
+
+- Improved Note Search
+- Pinned notes and recent tabs
+- Rich Note Editor
+- Command palette and global shortcuts
+- Snapshots Notes - version your knowledge base
+
+### Search notes
+
+Use the search field above the notes list to filter by title or content. Search is instant and searches the current project.
+
+
+
+### Pin important notes
+
+Right-click a note (or use the ⋮ menu) to **Pin** it. Pinned notes appear in the Pinned tab for quick access.
+
+---
+
+## Editing Notes
+
+### Editor modes
+
+The editor supports three modes, toggled with the buttons in the top-right:
+
+| Mode | Description |
+|------|-------------|
+| **Live** | Split view - edit Markdown on the left, see preview on the right |
+| **Preview** | Read-only rendered view |
+| **Source** | Full-width Markdown editor |
+
+
+
+::tip
+Press **Cmd/Ctrl + Alt + Z** or click the expand icon to enter Zen mode - a distraction-free full-screen editor.
+::
+
+### Markdown formatting
+
+The editor supports full Markdown including:
+- Headers, bold, italic, strikethrough
+- 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 Note Frontmatter
+
+Select the "Frontmatter" button to edit the note's frontmatter
+
+
+
+
+## Creating and Managing Notes
+
+### Create a new note
+
+1. Start typeing in the editor to create a new note. It will save automatically
+2. Click the **+** button in the notes list, or
+3. Press **Cmd/Ctrl + Alt + N**, or
+4. Use the command palette (**Cmd/Ctrl + K**) → "New Note"
+
+
+
+### Move notes
+
+1. Right-click a note → **Move** to relocate it to a different folder.
+2. Drag the note card from the list onto the desired folder
+3. Drag a folder in the tree to a new location to move a directory of notes
+
+### Delete notes
+
+Right-click a note → **Delete**. Deleted notes are removed from the project and database.
+
+::warning
+Deletion is permanent. Create a snapshot before bulk deletions if you want the ability to restore.
+::
+
+### Command Palette
+
+Press **Cmd/Ctrl + K** to open the command palette. Search for any action:
+- Navigate to notes
+- Create new note
+- Switch projects
+- Toggle views
+- Access settings
+
+
+
+
+### Cloud Snapshots
+
+Basic Memory Cloud now includes point-in-time snapshots for backup and recovery. Create manual snapshots before major changes, or rely on automatic daily backups.
+
+### View Snapshots
+
+Go to **Settings → Snapshots** to see all snapshots with creation time and description.
+
+
+
+### Create a Snapshot
+
+1. Click **Create Snapshot**
+2. Add an optional description (e.g., "Before reorganizing projects")
+3. Confirm
+
+
+
+You can create and manage point-in-time snapshots of your cloud bucket from the cli also:
+
+```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
+
+# Show snapshot details
+bm cloud snapshot show
+```
+
+Snapshots provide a safety net for major reorganizations or experiments with your knowledge base.
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Cloud Guide
+icon: i-lucide-cloud
+to: /cloud/cloud-guide
+---
+Get started with Basic Memory Cloud.
+::
+
+::card
+---
+title: Notes Interface
+icon: i-lucide-layout-panel-left
+to: /cloud/cloud-app/notes-interface
+---
+Learn about the Cloud notes UI.
+::
+:::
diff --git a/content/2.whats-new/2.changelog.md b/content/2.whats-new/2.changelog.md
new file mode 100644
index 0000000..25182ba
--- /dev/null
+++ b/content/2.whats-new/2.changelog.md
@@ -0,0 +1,13 @@
+---
+title: Basic Memory
+description: Release notes for Basic Memory.
+---
+
+All notable changes to [Basic Memory](https://github.com/basicmachines-co/basic-memory).
+
+::github-releases
+---
+repo: basicmachines-co/basic-memory
+limit: 30
+---
+::
diff --git a/content/3.cloud/.navigation.yml b/content/3.cloud/.navigation.yml
new file mode 100644
index 0000000..c0b58cf
--- /dev/null
+++ b/content/3.cloud/.navigation.yml
@@ -0,0 +1,2 @@
+title: Cloud
+icon: i-lucide-cloud
diff --git a/content/3.cloud/1.cloud-guide.md b/content/3.cloud/1.cloud-guide.md
new file mode 100644
index 0000000..4caea80
--- /dev/null
+++ b/content/3.cloud/1.cloud-guide.md
@@ -0,0 +1,359 @@
+---
+title: Basic Memory Cloud
+description: Cloud remote MCP setup, web editor, CLI tools, and snapshots for Basic Memory Cloud.
+---
+
+Basic Memory Cloud provides hosted MCP access with no local installation required. Bring your knowledge to the cloud - all your existing notes, connections, and context accessible from anywhere.
+
+::note{icon="i-lucide-cloud"}
+**Why use Basic Memory Cloud?**
+- Access from any device
+- Easily import your data
+- 2-minute setup
+- Local sync optional
+- OAuth authentication
+::
+
+---
+
+## Setup with Claude
+
+Basic Memory Cloud uses Remote MCP to connect to AI assistants. The connection URL is:
+
+```
+https://cloud.basicmemory.com/mcp
+```
+
+::steps
+### Open Claude Settings
+
+In Claude Web or Desktop, go to **Settings → Claude → Connectors**
+
+### Add Custom Connector
+
+Click **Add custom connector** and enter:
+- **Name**: Basic Memory
+- **Remote MCP server URL**: `https://cloud.basicmemory.com/mcp`
+
+Click **Add**
+
+### Authenticate
+
+Click **Connect** to authenticate and grant permissions to Claude.
+
+This opens an OAuth flow to authorize Claude to access your Basic Memory Cloud account.
+
+### Configure Tools (Optional)
+
+Click **Configure** to customize which tools are enabled. You can enable or disable specific tools and configure permissions.
+
+### Verify Setup
+
+Confirm Basic Memory is available in the "search and tools" menu for a chat. All your notes will be saved to your cloud instance.
+::
+
+::tip
+For detailed Claude setup instructions, see the [Claude Desktop Integration](/integrations/claude-desktop) guide.
+::
+
+---
+
+## Setup with ChatGPT
+
+::note
+ChatGPT requires a **Pro or Max subscription** to use Remote MCP servers.
+::
+
+For detailed ChatGPT setup instructions, see the [ChatGPT Integration](/integrations/chatgpt) guide.
+
+---
+
+## Web Editor
+
+Edit and manage your cloud notes directly in your browser at [app.basicmemory.com/notes](https://app.basicmemory.com/notes).
+
+**Key features:**
+- **View and Edit Notes** - Browse and edit with a rich markdown editor
+- **Import Conversations** - Import ChatGPT, Claude, or JSON data
+- **Manage Projects** - Create, switch between, and manage projects
+- **Upload Files** - Bulk upload markdown files and directories
+- **Download Archives** - Export projects as zip files for backup
+
+::tip
+For the complete web app guide including detailed instructions for editing, importing, and project management, see the [Web App Guide](/cloud/web-app).
+::
+
+---
+
+## Command Line Tools
+
+The CLI tools are **optional** but enable advanced features like project management, file upload, and bidirectional sync.
+
+**Requirements**: Basic Memory CLI v0.16.0 or later. See [Getting Started](/start-here/getting-started) for installation.
+
+::note{icon="i-lucide-info"}
+**Why use the CLI?**
+- Manage multiple projects from terminal
+- Upload entire folders to cloud
+- Set up bidirectional sync with local files
+- Automate workflows with scripts
+::
+
+### Quick Start
+
+```bash
+# 1. Authenticate
+bm cloud login
+
+# 2. Check Status
+bm cloud status
+
+# 3. List Projects
+bm project list
+```
+
+### Authentication
+
+Basic Memory uses JWT-based cloud authentication with OAuth 2.1 and automatic subscription validation.
+
+#### Login to Cloud
+
+```bash
+bm cloud login
+```
+
+**What happens:**
+1. Opens browser to OAuth authorization page
+2. Handles PKCE challenge/response automatically
+3. Validates active subscription status
+4. Stores JWT token in `~/.basic-memory/basic-memory-cloud.json`
+5. Token automatically refreshed when needed
+
+A confirmation code will be displayed in both the browser and terminal. Confirm the codes match and press the **Confirm** button on the web page.
+
+After login:
+```
+✅ Successfully authenticated with Basic Memory Cloud!
+Verifying subscription access...
+✓ Cloud mode enabled
+All CLI commands now work against https://cloud.basicmemory.com
+✓ Tokens saved to ~/.basic-memory/basic-memory-cloud.json
+```
+
+::note{icon="i-lucide-info"}
+After `bm cloud login`, CLI tools access cloud endpoints instead of local MCP. Commands like `bm project list` show cloud projects, and `bm tool [name]` invokes tools in the cloud.
+::
+
+**If no subscription:**
+```
+Active subscription required
+Subscribe at: https://basicmemory.com/subscribe
+```
+
+#### Check Status
+
+```bash
+bm cloud status
+```
+
+Shows: authentication status, subscription status, last sync time, cloud project count, tenant information, and sync directory configuration.
+
+#### Logout
+
+```bash
+bm cloud logout
+```
+
+Removes `~/.basic-memory/basic-memory-cloud.json` and clears cached credentials.
+
+### Project Management
+
+```bash
+# Create a new cloud project
+bm project add my-new-project
+
+# Create and set as default
+bm project add my-new-project --default
+
+# List all cloud projects
+bm project list
+```
+
+Example output:
+```
+ Basic Memory Projects
+┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
+┃ Name ┃ Path ┃ Default ┃
+┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
+│ main │ /app/data/basic-memory │ ✓ │
+└──────┴────────────────────────┴─────────┘
+```
+
+::tip
+For more project management commands, see `bm project --help` or the [CLI Reference](/reference/cli-reference).
+::
+
+---
+
+## Upload Files to Cloud
+
+Upload local files or directories to cloud projects using `bm cloud upload`:
+
+```bash
+# Upload a directory to existing project
+bm cloud upload ~/my-notes --project research
+
+# Upload a single file
+bm cloud upload important-doc.md --project research
+
+# Upload and create project in one step
+bm cloud upload ~/local-project --project new-research --create-project
+
+# Upload without triggering sync
+bm cloud upload ~/bulk-data --project archives --no-sync
+```
+
+**File Filtering:** The upload command respects `.bmignore` and `.gitignore` patterns, automatically excluding:
+- Hidden files (`.git`, `.DS_Store`)
+- Build artifacts (`node_modules`, `__pycache__`)
+- Database files (`*.db`, `*.db-wal`)
+- Environment files (`.env`)
+
+**Complete Example:**
+```bash
+# 1. Login to cloud
+bm cloud login
+
+# 2. Upload local project (creates project if needed)
+bm cloud upload ~/specs --project specs --create-project
+
+# 3. Verify upload
+bm project list
+```
+
+After sync completes, the notes are available in the [Notes Web Editor](https://app.basicmemory.com) and for AI conversations.
+
+::tip
+For bidirectional sync (editing both locally and in cloud), see the [Cloud Sync Guide](/cloud/cloud-sync).
+::
+
+---
+
+## Cloud Snapshots
+
+Basic Memory Cloud includes point-in-time snapshots for backup and recovery. Create manual snapshots before major changes, or rely on automatic daily backups.
+
+**Key features:**
+- Create unlimited manual snapshots
+- Automatic daily snapshots
+- Browse historical versions
+- Restore individual files or folders
+
+```bash
+# Create a snapshot before major changes
+bm cloud snapshot create "Before reorganization"
+
+# List all snapshots
+bm cloud snapshot list
+
+# Browse and restore files
+bm cloud snapshot browse snap_abc123
+```
+
+::tip
+For complete snapshot management including restore procedures and best practices, see the [Cloud Snapshots Guide](/cloud/cloud-snapshots).
+::
+
+---
+
+## Migrating to Cloud
+
+Already using Basic Memory locally? You have two options:
+
+### Option 1: One-Time Upload (Fastest)
+
+Upload your existing local project to cloud:
+
+```bash
+# Login first
+bm cloud login
+
+# Upload entire project
+bm cloud upload ~/basic-memory --project main --create-project
+```
+
+**Use when:**
+- You want to move to cloud-only
+- One-time migration is sufficient
+- Don't need ongoing local-cloud sync
+
+### Option 2: Bidirectional Sync (Hybrid Workflow)
+
+Set up sync to work both locally and in cloud:
+
+```bash
+# Login and setup sync
+bm cloud login
+bm cloud setup
+
+# Add existing project with sync enabled
+bm project add main --local-path ~/basic-memory
+
+# Initial sync (resync creates baseline)
+bm project bisync --name main --resync --dry-run # preview first
+bm project bisync --name main --resync # establish baseline
+
+# Ongoing sync (run after local or cloud changes)
+bm project bisync --name main
+```
+
+**Use when:**
+- You want to edit both locally (Obsidian, VS Code) and in cloud
+- Need offline access
+- Want automatic bidirectional sync
+
+::note{icon="i-lucide-info"}
+Both methods preserve all your notes, relations, and tags. Choose based on whether you want cloud-only or hybrid local+cloud workflow. See the [Cloud Sync Guide](/cloud/cloud-sync) for detailed sync configuration.
+::
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Cloud Sync Guide
+icon: i-lucide-refresh-cw
+to: /cloud/cloud-sync
+---
+Set up bidirectional sync for local editing.
+::
+
+::card
+---
+title: CLI Reference
+icon: i-lucide-terminal
+to: /reference/cli-reference
+---
+Complete CLI command reference.
+::
+
+::card
+---
+title: Getting Started
+icon: i-lucide-rocket
+to: /start-here/getting-started
+---
+Initial setup and configuration guide.
+::
+
+::card
+---
+title: MCP Tools Reference
+icon: i-lucide-wrench
+to: /reference/mcp-tools-reference
+---
+All available MCP tools for AI assistants.
+::
+:::
diff --git a/content/3.cloud/2.web-app.md b/content/3.cloud/2.web-app.md
new file mode 100644
index 0000000..6f6f217
--- /dev/null
+++ b/content/3.cloud/2.web-app.md
@@ -0,0 +1,319 @@
+---
+title: Web App
+description: Complete guide to the Basic Memory Cloud web application - browse, edit, search, and manage your notes in the browser.
+---
+
+The Basic Memory web app at [app.basicmemory.com](https://app.basicmemory.com) provides a full-featured interface for managing your knowledge base. Everything your AI assistant can do, you can do here too.
+
+
+
+---
+
+## Navigating Notes
+
+### Browse by folder
+
+Expand folders in the left panel to navigate your project structure. Click a folder to filter the notes list to that location.
+
+### Use tabs to filter
+
+Switch between views in the notes list:
+
+| Tab | Shows |
+|-----|-------|
+| **All** | Every note in the current folder/project |
+| **Recent** | Notes modified in the last 7 days |
+| **Pinned** | Notes you've pinned for quick access |
+
+### Search notes
+
+Use the search field above the notes list to filter by title or content. Search is instant and searches the current project.
+
+
+
+### Pin important notes
+
+Right-click a note (or use the ⋮ menu) to **Pin** it. Pinned notes appear in the Pinned tab for quick access.
+
+---
+
+## Editing Notes
+
+### Editor modes
+
+The editor supports three modes, toggled with the buttons in the top-right:
+
+| Mode | Description |
+|------|-------------|
+| **Live** | Split view - edit Markdown on the left, see preview on the right |
+| **Preview** | Read-only rendered view |
+| **Source** | Full-width Markdown editor |
+
+
+
+::tip
+Press **Cmd/Ctrl + Alt + Z** or click the expand icon to enter Zen mode - a distraction-free full-screen editor.
+::
+
+### Markdown formatting
+
+The editor supports full Markdown including:
+- Headers, bold, italic, strikethrough
+- 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 Note Frontmatter
+
+Select the "Frontmatter" button to edit the note's frontmatter
+
+
+
+---
+
+## Creating and Managing Notes
+
+### Create a new note
+
+1. Start typeing in the editor to create a new note. It will save automatically
+2. Click the **+** button in the notes list, or
+3. Press **Cmd/Ctrl + Alt + N**, or
+4. Use the command palette (**Cmd/Ctrl + K**) → "New Note"
+
+
+
+### Move notes
+
+1. Right-click a note → **Move** to relocate it to a different folder.
+2. Drag the note card from the list onto the desired folder
+3. Drag a folder in the tree to a new location to move a directory of notes
+
+### Delete notes
+
+Right-click a note → **Delete**. Deleted notes are removed from the project and database.
+
+::warning
+Deletion is permanent. Create a snapshot before bulk deletions if you want the ability to restore.
+::
+
+### Download a note
+
+Right-click a note → **Download** to save it as a `.md` file to your computer.
+
+---
+
+## Projects
+
+Projects are top-level containers. Each project has its own folder tree, notes, and sync configuration.
+
+### Switch projects
+
+Use the project dropdown in the top-left to switch between projects.
+
+
+
+### Manage projects
+
+Click **Manage Projects** to:
+- Create new projects
+- Upload files to a project
+- Download project as ZIP
+- Delete projects
+
+
+
+### Upload files
+
+From Manage Projects, click the **⋮** menu on any project → **Upload** to add:
+- Individual Markdown files
+
+
+
+::tip
+Upload entire folders and folder trees via the command line tools (structure is preserved).
+::
+
+### Download project archive
+
+Click **⋮** → **Download** to export a project as a ZIP file. Useful for:
+- Creating manual backups
+- Moving data to local installation
+- Sharing projects
+
+---
+
+## Import Data
+
+Import your existing AI conversations directly in the browser.
+
+### Supported formats
+
+| Format | File |
+|--------|------|
+| **Claude** | `conversations.json` from Claude export |
+| **ChatGPT** | Export ZIP or JSON from ChatGPT settings |
+| **Basic Memory JSON** | Memory exports with entities & relations |
+
+### How to import
+
+1. Go to **Settings → Import Data**
+2. Select the import type
+3. Choose target project (or use default)
+4. Set destination folder (default: `imports`)
+5. Upload your file and click **Start Import**
+
+
+
+::note
+Imported conversations are converted to Basic Memory's knowledge format automatically.
+::
+
+---
+
+## Snapshots
+
+Create point-in-time backups of your cloud data via **Settings → Snapshots**. Use them before major changes like bulk imports or reorganizations.
+
+::tip
+For complete snapshot management including creating, browsing, and restoring snapshots, see the [Cloud Snapshots Guide](/cloud/cloud-snapshots).
+::
+
+---
+
+## Keyboard Shortcuts
+
+The web app is designed for keyboard-first navigation.
+
+### Command Palette
+
+Press **Cmd/Ctrl + K** to open the command palette. Search for any action:
+- Navigate to notes
+- Create new note
+- Switch projects
+- Toggle views
+- Access settings
+
+
+
+### Global shortcuts
+
+| Shortcut | Action |
+|--------------------------|-------------------------------|
+| **Cmd/Ctrl + K** | Open command palette |
+| **Cmd/Ctrl + Alt + O** | Quick switcher (jump to note) |
+| **Cmd/Ctrl + Shift + F** | Global search |
+| **Cmd/Ctrl + Opt + N** | New note (desktop mode) |
+| **Cmd/Ctrl + Alt + Z** | Toggle zen mode |
+
+### Editor shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| **Cmd/Ctrl + /** | Show all shortcuts |
+| **Cmd/Ctrl + B** | Bold |
+| **Cmd/Ctrl + I** | Italic |
+| **Cmd/Ctrl + K** | Insert link |
+| **Cmd/Ctrl + Shift + K** | Insert code block |
+
+Press **Cmd/Ctrl + /** in the editor to see the full list.
+
+::note
+Notes are saved automatically when changed in the editor.
+::
+
+
+
+---
+
+## Settings
+
+Access settings from the user menu (top-right) or **Cmd/Ctrl + ,**.
+
+
+### Available settings
+
+- **Profile** - Edit profile information
+- **Account** - View account information for debugging
+- **Look and Feel** - Customize [themes and appearance](/cloud/themes)
+- **Import Data** - Import Claude, ChatGPT, or JSON exports
+- **API Keys** - Create and manage [API keys](/cloud/api-keys) for programmatic access
+- **Billing** - Manage payment and subscription
+- **Snapshots** - Manage [point-in-time backups](/cloud/cloud-snapshots)
+
+---
+
+## Tips for Effective Use
+
+### Organize with folders
+
+Create a folder structure that matches how you think:
+
+```bash
+~/basic-memory/
+├── projects/ # Active projects
+├── research/ # Learning and exploration
+├── decisions/ # Decision records
+├── meetings/ # Meeting notes
+└── archive/ # Completed/old content
+```
+
+### Use pinned notes
+
+Pin your most-accessed notes (project overviews, quick references) for one-click access.
+
+### Create snapshots before big changes
+
+Before reorganizing folders, bulk importing, or deleting lots of notes - create a manual snapshot.
+
+### Combine with AI assistant
+
+The web app and AI assistant work together:
+1. **AI creates** detailed notes during conversations
+2. **You browse and refine** in the web app
+3. **AI references** your refined notes in future conversations
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Cloud Sync
+icon: i-lucide-refresh-cw
+to: /cloud/cloud-sync
+---
+Set up bidirectional sync to edit locally and in cloud.
+::
+
+::card
+---
+title: CLI Reference
+icon: i-lucide-terminal
+to: /reference/cli-reference
+---
+Advanced cloud commands including snapshot CLI.
+::
+
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+Learn the semantic structure for observations and relations.
+::
+
+::card
+---
+title: Integrations
+icon: i-lucide-plug
+to: /integrations/claude-desktop
+---
+Connect your AI assistant to work with your notes.
+::
+:::
diff --git a/content/3.cloud/3.cloud-sync.md b/content/3.cloud/3.cloud-sync.md
new file mode 100644
index 0000000..874350d
--- /dev/null
+++ b/content/3.cloud/3.cloud-sync.md
@@ -0,0 +1,502 @@
+---
+title: Cloud Sync Guide
+description: Guide to syncing your local Basic Memory projects with Basic Memory Cloud.
+---
+
+The Basic Memory Cloud CLI provides seamless integration between local and cloud knowledge bases using **project-scoped synchronization**. Each project can optionally sync with the cloud, giving you fine-grained control over what syncs and where.
+
+---
+
+## Overview
+
+The cloud CLI enables you to:
+
+- **Toggle cloud mode** - All regular `bm` commands work with cloud when enabled
+- **Project-scoped sync** - Each project independently manages its sync configuration
+- **Explicit operations** - Sync only what you want, when you want
+- **Bidirectional sync** - Keep local and cloud in sync with rclone bisync
+- **Offline access** - Work locally, sync when ready
+
+---
+
+## 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)
+- **Basic Memory CLI**: See [Getting Started](/start-here/getting-started#local-installation) for installation
+
+::warning
+If you attempt to log in without an active subscription, you'll receive a "Subscription Required" error.
+::
+
+### When to Use Sync
+
+::tip
+**Sync is designed for hybrid workflows** where you want to edit files locally (in tools like Obsidian or VS Code) while keeping cloud in sync.
+
+**Use sync when:**
+- You want to edit notes locally in your preferred editor
+- You need bidirectional sync (changes flow both ways automatically)
+- You're working with large knowledge bases
+- You want offline access with periodic syncing
+
+**Alternatives to sync:**
+- **Web Editor**: Upload and edit files in the [Cloud web interface](/cloud/cloud-guide#web-editor)
+- **MCP Tools Only**: Use AI assistants to manage notes entirely in cloud
+::
+
+---
+
+## Architecture: Project-Scoped Sync
+
+### How It Works
+
+Projects can exist in three states:
+
+1. **Cloud-only** - Project exists on cloud, no local copy
+2. **Cloud + Local (synced)** - Project has a local working directory that syncs
+3. **Local-only** - Project exists locally (when cloud mode is disabled)
+
+**Example:**
+
+```bash
+# You have 3 projects on cloud:
+# - research: wants local sync at ~/Documents/research
+# - work: wants local sync at ~/work-notes
+# - temp: cloud-only, no local sync needed
+
+bm project add research --local-path ~/Documents/research
+bm project add work --local-path ~/work-notes
+bm project add temp # No local sync
+
+# Now you can sync individually (after initial --resync):
+bm project bisync --name research
+bm project bisync --name work
+# temp stays cloud-only
+```
+
+**What happens under the covers:**
+- Config stores `cloud_projects` dict mapping project names to local paths
+- Each project gets its own bisync state in `~/.basic-memory/bisync-state/{project}/`
+- Rclone syncs using single remote: `basic-memory-cloud`
+- Projects can live anywhere on your filesystem
+
+---
+
+## Quick Start
+
+### 1. Enable Cloud Mode
+
+Authenticate and enable cloud mode:
+
+```bash
+bm cloud login
+```
+
+**What this does:**
+1. Opens browser to Basic Memory Cloud authentication page
+2. Stores authentication token
+3. Enables cloud mode - all CLI commands now work against cloud
+4. Validates your subscription status
+
+### 2. Set Up Sync
+
+Install rclone and configure credentials:
+
+```bash
+bm cloud setup
+```
+
+**What this does:**
+1. Installs rclone automatically (if needed)
+2. Fetches your tenant information from cloud
+3. Generates scoped S3 credentials for sync
+4. Configures single rclone remote: `basic-memory-cloud`
+
+### 3. Add Projects with Sync
+
+Create projects with optional local sync paths:
+
+```bash
+# Create cloud project without local sync
+bm project add research
+
+# Create cloud project WITH local sync
+bm project add research --local-path ~/Documents/research
+
+# Or configure sync for existing project
+bm project sync-setup research ~/Documents/research
+```
+
+### 4. Sync Your Project
+
+Establish the initial sync baseline. **Always preview with `--dry-run` first:**
+
+```bash
+# Step 1: Preview the initial sync
+bm project bisync --name research --resync --dry-run
+
+# Step 2: If all looks good, run the actual sync
+bm project bisync --name research --resync
+```
+
+::note{icon="i-lucide-info"}
+**Why `--resync`?** This is an rclone requirement for the first bisync run. It establishes the initial state that future syncs will compare against. After the first sync, don't use `--resync` unless you need to force a new baseline.
+::
+
+### 5. Subsequent Syncs
+
+After the first sync, just run bisync without `--resync`:
+
+```bash
+bm project bisync --name research
+```
+
+**What happens:**
+1. Rclone compares local and cloud states
+2. Syncs changes in both directions
+3. Auto-resolves conflicts (newer file wins)
+4. Basic Memory reindexes all changed files
+5. Updates `last_sync` timestamp in config
+
+::note
+**Reindexing after sync**: Basic Memory automatically reindexes all synced changes to update the knowledge graph.
+::
+
+### 6. Verify Setup
+
+```bash
+bm cloud status
+```
+
+You should see:
+- `Mode: Cloud (enabled)`
+- `Cloud instance is healthy`
+
+---
+
+## File Synchronization
+
+### Understanding the Sync Commands
+
+| Command | Direction | Use Case |
+|---------|-----------|----------|
+| `bm project bisync` | Local ↔ Cloud | Two-way sync (recommended) |
+| `bm project sync` | Local → Cloud | One-way, make cloud match local |
+| `bm project check` | Verify | Check if files match |
+
+### Two-Way Sync (Recommended)
+
+```bash
+# First time - establish baseline
+bm project bisync --name research --resync
+
+# Subsequent syncs
+bm project bisync --name research
+```
+
+**Conflict resolution:** When the same file is edited both locally and in cloud, the newer file wins (based on modification time).
+
+### One-Way Sync
+
+```bash
+bm project sync --name research
+```
+
+Makes cloud identical to local. Use when local is the source of truth.
+
+### Preview Changes (Dry Run)
+
+```bash
+bm project bisync --name research --dry-run
+```
+
+Shows what would change without actually syncing.
+
+### Verify Integrity
+
+```bash
+bm project check --name research
+```
+
+Compares file checksums without making changes.
+
+---
+
+## Multiple Projects
+
+### Syncing Multiple Projects
+
+```bash
+# Setup multiple projects
+bm project add research --local-path ~/Documents/research
+bm project add work --local-path ~/work-notes
+bm project add personal --local-path ~/personal
+
+# Establish baselines
+bm project bisync --name research --resync
+bm project bisync --name work --resync
+bm project bisync --name personal --resync
+
+# Daily workflow: sync everything
+bm project bisync --name research
+bm project bisync --name work
+bm project bisync --name personal
+```
+
+### Mixed Usage
+
+```bash
+# Projects with sync
+bm project add research --local-path ~/Documents/research
+bm project add work --local-path ~/work
+
+# Cloud-only projects
+bm project add archive
+bm project add temp-notes
+
+# Sync only the configured ones
+bm project bisync --name research
+bm project bisync --name work
+# archive and temp-notes stay cloud-only
+```
+
+---
+
+## Filter Configuration
+
+### Understanding .bmignore
+
+Basic Memory uses `.bmignore` for global ignore patterns (similar to `.gitignore`).
+
+**Location:** `~/.basic-memory/.bmignore`
+
+**Default patterns:**
+
+```gitignore
+# Version control
+.git/**
+
+# Python
+__pycache__/**
+*.pyc
+.venv/**
+
+# Node.js
+node_modules/**
+
+# Basic Memory internals
+memory.db/**
+memory.db-shm/**
+memory.db-wal/**
+
+# OS files
+.DS_Store/**
+
+# Environment files
+.env/**
+```
+
+::note
+Basic Memory also respects `.gitignore` files in your projects. Use `.bmignore` for global patterns across all projects.
+::
+
+---
+
+## Troubleshooting
+
+### Authentication Issues
+
+**Problem:** Authentication failed or Invalid token
+
+**Solution:**
+```bash
+bm cloud logout
+bm cloud login
+```
+
+### First Bisync Requires --resync
+
+**Problem:** Bisync fails on first run
+
+**Solution:**
+```bash
+bm project bisync --name research --resync
+```
+
+This establishes the initial baseline state.
+
+### Empty Directory Issues
+
+**Problem:** "Empty prior Path1 listing. Cannot sync to an empty directory"
+
+**Solution:** Add at least one file before running `--resync`:
+```bash
+echo "# Research Notes" > ~/Documents/research/README.md
+bm project bisync --name research --resync
+```
+
+### Bisync State Corruption
+
+**Problem:** Bisync fails with errors about corrupted state
+
+**Solution:**
+```bash
+bm project bisync-reset research
+bm project bisync --name research --resync
+```
+
+### Too Many Deletes
+
+**Problem:** "max delete limit (25) exceeded"
+
+**Solution:** Review what's being deleted, then force resync if correct:
+```bash
+bm project bisync --name research --dry-run
+bm project bisync --name research --resync
+```
+
+### Project Not Configured for Sync
+
+**Problem:** "Project has no local_sync_path configured"
+
+**Solution:**
+```bash
+bm project sync-setup research ~/Documents/research
+bm project bisync --name research --resync
+```
+
+---
+
+## Disable Cloud Mode
+
+Return to local mode:
+
+```bash
+bm cloud logout
+```
+
+All `bm` commands now work with local projects.
+
+---
+
+## Security
+
+- **Authentication**: OAuth 2.1 with PKCE flow
+- **Tokens**: Stored securely in `~/.basic-memory/basic-memory-cloud.json`
+- **Transport**: All data encrypted in transit (HTTPS)
+- **Credentials**: Scoped S3 credentials (read-write to your tenant only)
+- **Isolation**: Your data isolated from other tenants
+- **Ignore patterns**: Sensitive files excluded via `.bmignore`
+
+---
+
+## Command Reference
+
+### Cloud Mode Management
+
+```bash
+bm cloud login # Authenticate and enable cloud mode
+bm cloud logout # Disable cloud mode
+bm cloud status # Check cloud mode and instance health
+```
+
+### Setup
+
+```bash
+bm cloud setup # Install rclone and configure credentials
+```
+
+### Project Management
+
+```bash
+bm project list # List cloud projects
+bm project add # Create cloud project (no sync)
+bm project add --local-path # Create with local sync
+bm project sync-setup # Add sync to existing project
+bm project rm # Delete project
+```
+
+### File Synchronization
+
+```bash
+# Two-way sync (recommended)
+bm project bisync --name # After first --resync
+bm project bisync --name --resync # First time / force baseline
+bm project bisync --name --dry-run
+bm project bisync --name --verbose
+
+# One-way sync (local → cloud)
+bm project sync --name
+bm project sync --name --dry-run
+
+# Integrity check
+bm project check --name
+
+# List remote files
+bm project ls --name
+```
+
+---
+
+## Summary
+
+**Basic Memory Cloud uses project-scoped sync:**
+
+1. **Enable cloud mode** - `bm cloud login`
+2. **Install rclone** - `bm cloud setup`
+3. **Add projects with sync** - `bm project add research --local-path ~/Documents/research`
+4. **Preview first sync** - `bm project bisync --name research --resync --dry-run`
+5. **Establish baseline** - `bm project bisync --name research --resync`
+6. **Daily workflow** - `bm project bisync --name research`
+
+**Key benefits:**
+- Each project independently syncs (or doesn't)
+- Projects can live anywhere on disk
+- Explicit sync operations (no magic)
+- Safe by design (max delete limits, conflict resolution)
+- Full offline access (work locally, sync when ready)
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Cloud Guide
+icon: i-lucide-cloud
+to: /cloud/cloud-guide
+---
+Cloud features and setup options.
+::
+
+::card
+---
+title: CLI Reference
+icon: i-lucide-terminal
+to: /reference/cli-reference
+---
+Complete CLI command reference.
+::
+
+::card
+---
+title: Obsidian Integration
+icon: i-lucide-hexagon
+to: /integrations/obsidian
+---
+Use cloud sync with Obsidian.
+::
+
+::card
+---
+title: VS Code Integration
+icon: i-lucide-code
+to: /integrations/vscode
+---
+Use cloud sync with VS Code.
+::
+:::
diff --git a/content/3.cloud/4.user-guide.md b/content/3.cloud/4.user-guide.md
new file mode 100644
index 0000000..a60bcc0
--- /dev/null
+++ b/content/3.cloud/4.user-guide.md
@@ -0,0 +1,480 @@
+---
+title: User Guide
+description: Learn how to effectively use Basic Memory Cloud in your daily workflow to build rich semantic knowledge.
+---
+
+This guide covers everything from creating your first notes to building a comprehensive knowledge graph using Basic Memory Cloud.
+
+::tip
+Using Basic Memory locally? See the [Local User Guide](/local/user-guide) for file-based workflows and CLI commands.
+::
+
+---
+
+## Basic Memory Workflow
+
+Using Basic Memory follows a natural cycle:
+
+::mermaid
+---
+code: |
+ flowchart LR
+ A[Conversation] --> B[Capture]
+ B --> C[Connect]
+ C --> D[Reference]
+ D --> E[Edit]
+ E --> A
+---
+::
+
+1. **Have conversations** with AI assistants like Claude
+2. **Capture knowledge** as notes in your cloud storage
+3. **Build connections** between pieces of knowledge
+4. **Reference your knowledge** in future conversations
+5. **Edit notes** in the web app when needed
+
+---
+
+## Creating Knowledge
+
+### Through Conversations
+
+The most natural way to create knowledge is during conversations:
+
+```bash
+You: We've covered several authentication approaches. Could you create a note
+ summarizing what we've discussed?
+
+Claude: I'll create a note summarizing our authentication discussion.
+
+[Uses write_note tool]
+
+Done! I've created "Authentication Approaches.md" with:
+- Overview of options we discussed
+- Observations about JWT vs sessions
+- Relations to your security notes
+```
+
+This creates a Markdown file with semantic markup in your cloud knowledge base.
+
+### Through the Web App
+
+You can also create notes directly in the [web app](https://app.basicmemory.com/notes):
+
+1. Navigate to **Notes** in the web app
+2. Click **New Note** or create in a specific folder
+3. Add frontmatter with title and optional tags
+4. Structure content with observations and relations
+5. Save - changes sync automatically
+
+**Example note structure:**
+```bash
+---
+title: API Design Decisions
+tags: [api, architecture, decisions]
+---
+
+# API Design Decisions
+
+## Context
+We needed to choose an approach for the new API.
+
+## Observations
+- [decision] Use REST over GraphQL for simplicity #api
+- [requirement] Must support versioning from day one
+- [risk] Rate limiting needed for public endpoints
+
+## Relations
+- implements [[API Specification]]
+- depends_on [[Authentication System]]
+```
+
+---
+
+## Using Special Prompts
+
+Basic Memory includes special prompts that help you leverage your knowledge base effectively.
+
+### Continue Conversation
+
+Resume previous topics with full context:
+
+```bash
+"Let's continue our conversation about [topic]"
+```
+
+**What happens:**
+- Searches your knowledge base for relevant content
+- Builds context from related documents
+- Resumes with awareness of previous discussions
+
+### Recent Activity
+
+See what you've been working on:
+
+```bash
+"What have we been discussing recently?"
+```
+
+**What happens:**
+- Retrieves recently modified documents
+- Summarizes main topics and points
+- Offers to continue any discussions
+
+### Search
+
+Find specific information:
+
+```bash
+"Find information about [topic]"
+```
+
+**What happens:**
+- Searches across all your documents
+- Summarizes key findings
+- Offers to explore specific documents
+
+---
+
+## Working with Memory URLs
+
+Basic Memory uses special `memory://` URLs to reference knowledge:
+
+### URL Formats
+
+```bash
+memory://title # Reference by title
+memory://folder/title # Reference by folder and title
+memory://permalink # Reference by permalink
+memory://path/relation_type/* # Follow all relations of type
+```
+
+### Using Memory URLs
+
+Reference existing knowledge in conversations:
+
+```bash
+You: "Take a look at memory://coffee-brewing-methods and let's discuss improvements"
+```
+
+Claude will load that specific document and any related context.
+
+::tip
+Memory URLs are stable identifiers. Even if you rename or move a file, the permalink stays the same.
+::
+
+---
+
+## Building Knowledge Connections
+
+### Creating Relations
+
+Use WikiLink syntax to connect knowledge:
+
+```bash
+## Relations
+- implements [[Authentication System]]
+- requires [[Database Schema]]
+- relates_to [[Security Guidelines]]
+```
+
+### Common Relation Types
+
+| Type | Use for |
+|------|---------|
+| `implements` | One thing implements another |
+| `requires` | Dependencies |
+| `relates_to` | General connections |
+| `part_of` | Hierarchy relationships |
+| `extends` | Extensions or enhancements |
+| `pairs_with` | Things that work together |
+| `inspired_by` | Source of ideas |
+| `replaces` | Supersedes another document |
+
+### Adding Observations
+
+Structure facts with semantic categories:
+
+```bash
+## Observations
+- [decision] We chose JWT tokens for stateless auth
+- [requirement] Must support 2FA for sensitive operations
+- [technique] Use bcrypt for password hashing
+- [issue] Rate limiting needed for login attempts
+- [fact] Average response time is 50ms
+- [question] Should we support OAuth?
+```
+
+---
+
+## Multi-Project Workflows
+
+### How Projects Work
+
+Basic Memory Cloud supports multiple projects for organizing different knowledge bases. When you start a conversation, the AI will:
+
+1. Check your available projects
+2. Suggest the most active project based on recent activity
+3. Ask which project to use for this conversation
+4. Remember your choice throughout the session
+
+**Example conversation:**
+```bash
+You: "Let's work on documentation"
+
+Claude: I see you have 3 projects: main, work-notes, personal
+Your most active project is work-notes.
+Should I use work-notes for this task?
+
+You: "Yes, let's use work-notes"
+
+Claude: I'll use the 'work-notes' project for our session.
+```
+
+### Managing Projects in Web App
+
+In the [web app](https://app.basicmemory.com/notes):
+
+1. Use the **Project dropdown** in the upper left to switch projects
+2. Click **Manage Projects** to create, rename, or delete projects
+3. Use the **more menu** (...) on any project to upload files or download archives
+
+---
+
+## Organizing Your Knowledge
+
+### Folder Structure
+
+Organize notes in any structure that suits you:
+
+```bash
+main/
+├── projects/ # Active project notes
+│ ├── api-redesign/
+│ └── mobile-app/
+├── decisions/ # Decision records
+├── learning/ # Research and learning notes
+├── meetings/ # Meeting notes
+└── archive/ # Completed/old content
+```
+
+### Best Practices
+
+- Use descriptive filenames
+- Group related content in folders
+- Include dates in time-sensitive notes (e.g., `2024-01-15 Team Standup.md`)
+- Archive old content regularly
+
+### Moving and Organizing
+
+In the web app, you can drag and drop notes between folders. Or ask your AI:
+
+```bash
+You: "Move my old meeting notes to the archive folder"
+
+Claude: [Uses move_note]
+"Done! I've moved 12 meeting notes to the archive folder."
+```
+
+---
+
+## Editing Notes
+
+### In the Web App
+
+The web app provides a live Markdown editor:
+
+1. Click any note to open it
+2. Edit directly in the editor pane
+3. Changes save automatically
+4. Preview renders in real-time
+
+### Through AI
+
+Ask your AI to make changes:
+
+```bash
+You: "Add a troubleshooting section to my setup guide"
+
+Claude: [Uses edit_note with append operation]
+"I've added a troubleshooting section to the end of your setup guide."
+```
+
+**Available operations:**
+- `append` - Add content to end
+- `prepend` - Add content to beginning
+- `find_replace` - Replace specific text
+- `replace_section` - Replace entire section by heading
+
+### Directory Operations
+
+Move or delete entire folders:
+
+```bash
+You: "Move the old-projects folder to archive"
+
+Claude: [Uses move_note with is_directory=true]
+"Moved old-projects/ → archive/old-projects/ (15 files)"
+```
+
+---
+
+## Importing Data
+
+### From Claude or ChatGPT
+
+Import your conversation history:
+
+1. In the web app, go to **Settings → Import Data**
+2. Select import type (Claude or ChatGPT)
+3. Choose target project and destination folder
+4. Upload your export file
+
+::tip
+Imported conversations are converted to Basic Memory's markdown format with observations and relations extracted automatically.
+::
+
+### From Files
+
+Upload existing markdown files:
+
+1. In the web app, click **Manage Projects**
+2. Click the **more menu** (...) on your project
+3. Select **Upload** and choose files or folders
+
+---
+
+## Snapshots and Backup
+
+Basic Memory Cloud automatically creates daily snapshots. You can also create manual snapshots before major changes.
+
+### Creating Snapshots
+
+In the web app or via CLI:
+
+```bash
+bm cloud snapshot create "Before reorganization"
+```
+
+### Restoring from Snapshots
+
+1. List available snapshots
+2. Browse snapshot contents
+3. Download and restore individual files as needed
+
+See the [Cloud Guide](/cloud/cloud-guide#cloud-snapshots) for detailed snapshot management.
+
+---
+
+## Best Practices
+
+### Knowledge Creation
+
+1. **Create relations** - Link related concepts with `[[WikiLinks]]`
+2. **Make observations** - Structure facts with `[category]` syntax
+3. **Be descriptive** - Use clear titles and rich content
+4. **Add context** - Include background and reasoning
+5. **Review and refine** - Edit AI-generated content for accuracy
+
+### Workflow
+
+1. **Use special prompts** - "Continue conversation", "Recent activity", "Search"
+2. **Build incrementally** - Add to existing notes rather than creating duplicates
+3. **Organize regularly** - Move old content to archive
+4. **Cross-reference** - Link new content to existing knowledge
+5. **Use projects** - Separate work, personal, research
+
+### Long-term Maintenance
+
+1. **Archive old content** - Keep active knowledge base focused
+2. **Refactor connections** - Update relations as knowledge evolves
+3. **Regular reviews** - Periodically update key documents
+4. **Use snapshots** - Create snapshots before major reorganizations
+
+---
+
+## Local Sync (Optional)
+
+Want to edit files locally with Obsidian or VS Code? Set up bidirectional sync:
+
+```bash
+bm cloud login
+bm cloud setup
+bm project bisync --name main
+```
+
+This syncs your cloud notes to a local folder. Changes in either location sync automatically.
+
+See the [Cloud Sync Guide](/cloud/cloud-sync) for detailed setup.
+
+---
+
+## Troubleshooting
+
+### AI Can't Find Knowledge
+
+1. Confirm you're connected to the correct project
+2. Check that the note exists in the web app
+3. Use `memory://` URLs for direct references
+4. Try searching with different terms
+
+### Web App Issues
+
+1. Refresh the page
+2. Check your subscription status
+3. Clear browser cache if notes aren't updating
+4. Try a different browser
+
+### Sync Issues
+
+If using local sync:
+1. Check sync status: `bm cloud status`
+2. Run manual sync: `bm project bisync --name main`
+3. Check for conflicts in the sync log
+
+### Getting Help
+
+- **Discord**: [discord.gg/tyvKNccgqN](https://discord.gg/tyvKNccgqN) - #help channel
+- **GitHub**: [github.com/basicmachines-co/basic-memory/issues](https://github.com/basicmachines-co/basic-memory/issues)
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+Learn the semantic patterns for observations and relations.
+::
+
+::card
+---
+title: Web App Guide
+icon: i-lucide-layout-panel-left
+to: /cloud/web-app
+---
+Detailed guide to the web editor interface.
+::
+
+::card
+---
+title: Cloud Sync
+icon: i-lucide-refresh-cw
+to: /cloud/cloud-sync
+---
+Set up bidirectional sync with local files.
+::
+
+::card
+---
+title: MCP Tools Reference
+icon: i-lucide-wrench
+to: /reference/mcp-tools-reference
+---
+All available tools for AI assistants.
+::
+:::
diff --git a/content/3.cloud/5.cloud-snapshots.md b/content/3.cloud/5.cloud-snapshots.md
new file mode 100644
index 0000000..f07ae3d
--- /dev/null
+++ b/content/3.cloud/5.cloud-snapshots.md
@@ -0,0 +1,221 @@
+---
+title: Cloud Snapshots
+description: Point-in-time backups for your Basic Memory Cloud knowledge base.
+---
+
+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.
+::
+
+---
+
+## 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).
+
+### View Snapshots
+
+Go to **Settings → Snapshots** to see all snapshots with creation time and description.
+
+
+
+### Create a Snapshot
+
+1. Click **Create Snapshot**
+2. Add an optional description (e.g., "Before reorganizing projects")
+3. Confirm
+
+
+
+### Restore from a Snapshot
+
+1. Click on a snapshot → **Restore Files**
+2. Filter by project or search for specific files
+3. Select files or folders to restore
+4. Click **Restore** to copy them back
+
+
+
+::note
+Restored files overwrite existing files with the same path. Consider creating a new snapshot before restoring if you want to preserve current state.
+::
+
+---
+
+## Using the CLI
+
+Manage snapshots from the command line with `bm cloud snapshot` commands.
+
+### Create a Snapshot
+
+```bash
+bm cloud snapshot create "Before reorganization"
+```
+
+**Output:**
+```
+Created snapshot: snap_abc123 (2026-01-27T10:30:00)
+```
+
+### List Snapshots
+
+```bash
+bm cloud snapshot list
+```
+
+**Output:**
+```
+snap_abc123 "Before reorganization" Jan 27, 2026 42 MB
+snap_xyz789 "daily-auto" Jan 26, 2026 41 MB
+snap_def456 "daily-auto" Jan 25, 2026 40 MB
+```
+
+### View Snapshot Details
+
+```bash
+bm cloud snapshot show snap_abc123
+```
+
+### Browse Snapshot Contents
+
+View files in a snapshot without restoring:
+
+```bash
+bm cloud snapshot browse snap_abc123
+```
+
+**Output:**
+```
+notes/project.md
+notes/ideas.md
+research/analysis.md
+meetings/2026-01-15.md
+```
+
+Filter by path:
+
+```bash
+bm cloud snapshot browse snap_abc123 --path notes/
+```
+
+### Restore Files
+
+Restore a specific file:
+
+```bash
+bm cloud snapshot restore snap_abc123 --file notes/important.md
+```
+
+Restore an entire folder:
+
+```bash
+bm cloud snapshot restore snap_abc123 --path research/
+```
+
+### Delete a Snapshot
+
+```bash
+bm cloud snapshot delete snap_abc123
+```
+
+::warning
+Deleted snapshots cannot be recovered. Make sure you no longer need the snapshot before deleting.
+::
+
+---
+
+## When to Create Snapshots
+
+- Before reorganizing your folder structure
+- Before bulk imports from Claude or ChatGPT
+- Before deleting multiple notes
+- Before running automated scripts
+- At project milestones
+
+---
+
+## Automatic Snapshots
+
+Basic Memory Cloud creates automatic daily snapshots:
+
+- **Frequency**: Once per day
+- **Naming**: `daily-auto` prefix
+- **No action required**: Happens automatically
+
+You can rely on automatic snapshots for basic protection, but manual snapshots are recommended before major changes.
+
+---
+
+## Best Practices
+
+1. **Name snapshots descriptively** - Use names like "Before Q1 reorganization" instead of "backup1"
+2. **Create before bulk operations** - Imports, reorganizations, and deletions
+3. **Review automatic snapshots** - Check that daily snapshots are being created
+4. **Test restore occasionally** - Verify you can restore files when needed
+5. **Clean up old snapshots** - Delete manual snapshots you no longer need
+
+---
+
+## Troubleshooting
+
+### Snapshot Creation Failed
+
+1. Check your subscription status: `bm cloud status`
+2. Verify you're authenticated: `bm cloud login`
+3. Check available storage in your account
+
+### Can't Find a File in Snapshot
+
+1. Use `browse` with different paths to locate the file
+2. Check if the file existed at the snapshot time
+3. Try an earlier snapshot if the file was deleted before the snapshot
+
+### Restore Didn't Work
+
+1. Check file permissions in your project
+2. Verify the file path is correct
+3. Try restoring to a different location first
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Cloud Guide
+icon: i-lucide-cloud
+to: /cloud/cloud-guide
+---
+Complete cloud setup and features overview.
+::
+
+::card
+---
+title: Cloud Sync
+icon: i-lucide-refresh-cw
+to: /cloud/cloud-sync
+---
+Set up bidirectional sync with local files.
+::
+
+::card
+---
+title: Web App Guide
+icon: i-lucide-layout-panel-left
+to: /cloud/web-app
+---
+Browse and edit notes in your browser.
+::
+:::
diff --git a/content/3.cloud/6.themes.md b/content/3.cloud/6.themes.md
new file mode 100644
index 0000000..4057315
--- /dev/null
+++ b/content/3.cloud/6.themes.md
@@ -0,0 +1,241 @@
+---
+title: Themes
+description: Customize the look and feel of Basic Memory Cloud with preset themes or custom CSS.
+---
+
+Basic Memory Cloud includes a comprehensive theme system with 40+ preset themes and support for custom CSS. Personalize your workspace with colors, fonts, and styles that work for you.
+
+
+---
+
+## Color Mode
+
+Switch between light, dark, or system-based color modes:
+
+1. Open **Settings** in the web app
+2. Find the **Theme** section
+3. Click **Light**, **Dark**, or **System**
+
+System mode automatically matches your operating system preference.
+
+---
+
+## Preset Themes
+
+Choose from 40+ curated themes, each with coordinated colors for both light and dark modes.
+
+### Selecting a Theme
+
+1. Open **Settings** in the web app
+2. Find the **Theme** section
+3. Click the theme dropdown
+4. Preview themes by hovering - see the color palette
+5. Click to apply
+
+### Available Themes
+
+**Popular presets include:**
+- **Default** - Clean white/dark gray base
+- **Modern Minimal** - Blue-focused minimal design
+- **Violet Bloom** - Purple-focused theme
+- **T3 Chat** - Inspired by T3 Chat interface
+- And 35+ more options
+
+Each theme defines:
+- Background and foreground colors
+- Primary and accent colors
+- Sidebar colors
+- Card and border styles
+- Typography (optional)
+
+---
+
+## Custom Themes
+
+Create your own theme with custom CSS variables.
+
+### Adding a Custom Theme
+
+1. Open **Settings** in the web app
+2. Find the **Theme** section
+3. Click **Custom Theme**
+4. Paste your CSS or drag-and-drop a `.css` file
+5. Click **Save**
+
+### CSS Format
+
+Custom themes use CSS variables in TweakCN format:
+
+```css
+:root {
+ --background: oklch(1 0 0);
+ --foreground: oklch(0.145 0 0);
+ --card: oklch(1 0 0);
+ --card-foreground: oklch(0.145 0 0);
+ --popover: oklch(1 0 0);
+ --popover-foreground: oklch(0.145 0 0);
+ --primary: oklch(0.205 0 0);
+ --primary-foreground: oklch(0.985 0 0);
+ --secondary: oklch(0.97 0 0);
+ --secondary-foreground: oklch(0.205 0 0);
+ --muted: oklch(0.97 0 0);
+ --muted-foreground: oklch(0.556 0 0);
+ --accent: oklch(0.97 0 0);
+ --accent-foreground: oklch(0.205 0 0);
+ --destructive: oklch(0.577 0.245 27.325);
+ --border: oklch(0.922 0 0);
+ --input: oklch(0.922 0 0);
+ --ring: oklch(0.708 0 0);
+ --radius: 0.625rem;
+}
+
+.dark {
+ --background: oklch(0.145 0 0);
+ --foreground: oklch(0.985 0 0);
+ /* ... dark mode overrides */
+}
+```
+
+### Required Variables
+
+Your custom theme must define these variables for both light (`:root`) and dark (`.dark`) modes:
+
+| Variable | Purpose |
+|----------|---------|
+| `--background` | Page background |
+| `--foreground` | Primary text |
+| `--card` | Card backgrounds |
+| `--card-foreground` | Card text |
+| `--popover` | Dropdown/menu backgrounds |
+| `--popover-foreground` | Dropdown/menu text |
+| `--primary` | Primary buttons, links |
+| `--primary-foreground` | Text on primary elements |
+| `--secondary` | Secondary elements |
+| `--secondary-foreground` | Text on secondary elements |
+| `--muted` | Muted backgrounds |
+| `--muted-foreground` | Muted text |
+| `--accent` | Accent highlights |
+| `--accent-foreground` | Text on accents |
+| `--destructive` | Delete/danger actions |
+| `--border` | Borders |
+| `--input` | Input field borders |
+| `--ring` | Focus rings |
+
+### Optional Variables
+
+Customize typography and layout:
+
+```css
+:root {
+ /* Typography */
+ --font-sans: 'Inter', sans-serif;
+ --font-serif: 'Georgia', serif;
+ --font-mono: 'JetBrains Mono', monospace;
+ --letter-spacing: -0.01em;
+
+ /* Layout */
+ --radius: 0.5rem;
+ --spacing: 1rem;
+}
+```
+
+### Sidebar Variables
+
+Customize the sidebar separately:
+
+```css
+:root {
+ --sidebar: oklch(0.985 0 0);
+ --sidebar-foreground: oklch(0.145 0 0);
+ --sidebar-primary: oklch(0.205 0 0);
+ --sidebar-primary-foreground: oklch(0.985 0 0);
+ --sidebar-accent: oklch(0.97 0 0);
+ --sidebar-accent-foreground: oklch(0.205 0 0);
+ --sidebar-border: oklch(0.922 0 0);
+ --sidebar-ring: oklch(0.708 0 0);
+}
+```
+
+---
+
+## Using TweakCN
+
+[TweakCN](https://tweakcn.com) is a theme generator compatible with Basic Memory Cloud.
+
+### Export from TweakCN
+
+1. Visit [tweakcn.com](https://tweakcn.com)
+2. Customize your theme with the visual editor
+3. Export as CSS
+4. Paste into Basic Memory Cloud's custom theme editor
+
+### Color Format
+
+TweakCN uses OKLCH color format for better perceptual uniformity:
+
+```css
+/* OKLCH format: oklch(lightness chroma hue) */
+--primary: oklch(0.6 0.2 250); /* Blue */
+--accent: oklch(0.7 0.15 330); /* Purple */
+```
+
+---
+
+## Theme Persistence
+
+Your theme choice is saved locally in your browser:
+- Persists across sessions
+- Applies immediately on page load
+- Separate settings for each browser/device
+
+::note
+Theme settings are stored in your browser's localStorage, not in your cloud account. If you switch browsers or devices, you'll need to set your theme again.
+::
+
+---
+
+## Troubleshooting
+
+### Theme Not Applying
+
+1. Check browser console for CSS errors
+2. Verify all required variables are defined
+3. Ensure both `:root` and `.dark` sections exist
+4. Try refreshing the page
+
+### Colors Look Wrong
+
+1. Verify OKLCH values are valid (lightness 0-1, chroma 0-0.4, hue 0-360)
+2. Check for typos in variable names
+3. Test in both light and dark modes
+
+### Custom Theme Rejected
+
+The editor validates your CSS. Common issues:
+- Missing required variables
+- Invalid CSS syntax
+- CSS too large (size limit applies)
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Web App Guide
+icon: i-lucide-layout-panel-left
+to: /cloud/web-app
+---
+Complete guide to the web editor interface.
+::
+
+::card
+---
+title: API Keys
+icon: i-lucide-key
+to: /cloud/api-keys
+---
+Create API keys for programmatic access.
+::
+:::
diff --git a/content/3.cloud/7.api-keys.md b/content/3.cloud/7.api-keys.md
new file mode 100644
index 0000000..220aa25
--- /dev/null
+++ b/content/3.cloud/7.api-keys.md
@@ -0,0 +1,245 @@
+---
+title: API Keys
+description: Create API keys for programmatic access to Basic Memory Cloud without OAuth.
+---
+
+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), go to **Settings → API Keys**
+
+### Click Create Key
+
+Click **Create New API Key**
+
+### Name Your Key
+
+Enter a descriptive name like "Claude Desktop" or "Work Laptop"
+
+### Set Expiration (Optional)
+
+Choose when the key should expire, or leave blank for no expiration
+
+### Copy Your Key
+
+**Important:** Copy the key immediately. It's only shown once and cannot be retrieved later.
+
+The key looks like: `bmc_abc123def456...`
+::
+
+::warning
+Store your API key securely. Anyone with the key can access your Basic Memory account. Never commit keys to version control or share them publicly.
+::
+
+---
+
+## Using API Keys
+
+### With Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+ "mcpServers": {
+ "basic-memory": {
+ "url": "https://cloud.basicmemory.com/mcp",
+ "headers": {
+ "Authorization": "Bearer bmc_your_key_here"
+ }
+ }
+ }
+}
+```
+
+### With Codex CLI
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[[mcp_servers]]
+name = "basic-memory"
+url = "https://cloud.basicmemory.com/mcp"
+bearer_token_env_var = "BASIC_MEMORY_API_KEY"
+```
+
+Then set the environment variable:
+
+```bash
+export BASIC_MEMORY_API_KEY=bmc_your_key_here
+```
+
+### With Other MCP Clients
+
+Any MCP client that supports HTTP headers can use API keys:
+
+```
+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
+```
+
+---
+
+## Managing Keys
+
+### View Your Keys
+
+In **Settings → API Keys**, you'll see:
+- Key name
+- Key prefix (first few characters for identification)
+- Creation date
+- Last used timestamp
+- Status (active/expired/revoked)
+
+### Revoking a Key
+
+To disable a key:
+
+1. Go to **Settings → API Keys**
+2. Find the key you want to revoke
+3. Click **Revoke**
+4. Confirm the action
+
+Revoked keys stop working immediately. This cannot be undone.
+
+::tip
+If you suspect a key has been compromised, revoke it immediately and create a new one.
+::
+
+---
+
+## Security Best Practices
+
+### Do
+
+- **Use descriptive names** - "Claude Desktop Work" is better than "key1"
+- **Set expiration dates** - Especially for temporary access
+- **Use environment variables** - Don't hardcode keys in config files
+- **Revoke unused keys** - Clean up keys you no longer need
+- **Create separate keys** - One per device or application
+
+### Don't
+
+- **Share keys** - Each user should have their own account and keys
+- **Commit keys to git** - Add config files with keys to `.gitignore`
+- **Use keys in URLs** - Always use the Authorization header
+- **Ignore suspicious activity** - Check "last used" timestamps regularly
+
+---
+
+## Key Format
+
+API keys follow this format:
+
+```
+bmc_
+```
+
+- Prefix `bmc_` identifies it as a Basic Memory Cloud key
+- 32 bytes of cryptographically random data
+- URL-safe base64 encoding
+
+Example: `bmc_K7xR2pQmNvLwYhT9sU3fAeBcDgHiJkMnOpQrStUv`
+
+---
+
+## API Keys vs OAuth
+
+| Feature | API Keys | OAuth |
+|---------|----------|-------|
+| Setup | Copy/paste key | Browser-based flow |
+| Best for | CLI, scripts, automation | Interactive apps |
+| Token refresh | No (long-lived) | Yes (short-lived + refresh) |
+| Revocation | Per-key | Per-session |
+| Scopes | Full access | Configurable |
+
+Use **API keys** for:
+- Command-line tools
+- Automation scripts
+- Headless environments
+- Multiple concurrent sessions
+
+Use **OAuth** for:
+- Web applications
+- First-time setup in Claude/ChatGPT
+- When you want automatic token refresh
+
+---
+
+## Troubleshooting
+
+### Key Not Working
+
+1. Verify the key is copied correctly (no extra spaces)
+2. Check the key hasn't been revoked
+3. Check the key hasn't expired
+4. Ensure the Authorization header format is correct: `Bearer bmc_...`
+
+### "Unauthorized" Error
+
+1. Confirm your subscription is active
+2. Verify the key belongs to your account
+3. Try creating a new key
+
+### Key Not Showing in List
+
+Keys are only shown once at creation. If you lost the key:
+1. Revoke the old key
+2. Create a new one
+3. Update your configuration
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Cloud Guide
+icon: i-lucide-cloud
+to: /cloud/cloud-guide
+---
+Complete cloud setup and features overview.
+::
+
+::card
+---
+title: Claude Desktop Integration
+icon: i-lucide-message-square
+to: /integrations/claude-desktop
+---
+Set up Claude Desktop with Basic Memory.
+::
+
+::card
+---
+title: CLI Reference
+icon: i-lucide-terminal
+to: /reference/cli-reference
+---
+Command-line tools for Basic Memory.
+::
+:::
diff --git a/content/4.local/.navigation.yml b/content/4.local/.navigation.yml
new file mode 100644
index 0000000..9aca945
--- /dev/null
+++ b/content/4.local/.navigation.yml
@@ -0,0 +1,2 @@
+title: Local
+icon: i-lucide-hard-drive
diff --git a/content/4.local/1.local-install.md b/content/4.local/1.local-install.md
new file mode 100644
index 0000000..a5d1717
--- /dev/null
+++ b/content/4.local/1.local-install.md
@@ -0,0 +1,67 @@
+---
+title: Local install
+description: Install Basic Memory locally and choose where notes live.
+---
+
+Local mode runs the MCP server on your machine and stores notes in local folders you control.
+
+## Install the CLI
+
+::code-group
+```bash [uv]
+uv tool install basic-memory
+```
+
+```bash [homebrew]
+brew tap basicmachines-co/basic-memory
+brew install basic-memory
+```
+::
+
+## Start the MCP server
+
+Configure your MCP client to run the server:
+
+```json [claude_desktop_config.json]
+{
+ "mcpServers": {
+ "basic-memory": {
+ "command": "uvx",
+ "args": ["basic-memory", "mcp"]
+ }
+ }
+}
+```
+
+Restart your MCP client after editing the config.
+
+## Choose where notes live
+
+By default, notes are stored in a `main` project under `~/basic-memory`. You can point Basic Memory to any folder by creating a project and setting it as default.
+
+```bash
+bm project add "work" ~/Documents/work-notes
+bm project default "work"
+```
+
+## Next steps
+
+:::card-group
+::card
+---
+title: CLI Basics
+icon: i-lucide-terminal
+to: /local/cli-basics
+---
+Learn common commands for projects, notes, and search.
+::
+
+::card
+---
+title: Projects and Folders
+icon: i-lucide-folder
+to: /concepts/projects-and-folders
+---
+Organize notes with projects and folder structure.
+::
+:::
diff --git a/content/4.local/2.cli-basics.md b/content/4.local/2.cli-basics.md
new file mode 100644
index 0000000..099001a
--- /dev/null
+++ b/content/4.local/2.cli-basics.md
@@ -0,0 +1,59 @@
+---
+title: CLI basics
+description: Common commands for projects, notes, and search.
+---
+
+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 tools search-notes --query "authentication"
+```
+
+## Read and write notes
+
+```bash
+bm tools read-note --path "docs/api-auth.md"
+
+echo "New note content" | bm tools write-note --path "drafts/notes.md"
+```
+
+## Next steps
+
+:::card-group
+::card
+---
+title: CLI Reference
+icon: i-lucide-terminal
+to: /reference/cli-reference
+---
+Complete command reference with all options.
+::
+
+::card
+---
+title: MCP Tools (Local)
+icon: i-lucide-wrench
+to: /local/mcp-tools-local
+---
+Learn how assistants use tools locally.
+::
+:::
diff --git a/content/4.local/3.mcp-tools-local.md b/content/4.local/3.mcp-tools-local.md
new file mode 100644
index 0000000..b2e5598
--- /dev/null
+++ b/content/4.local/3.mcp-tools-local.md
@@ -0,0 +1,45 @@
+---
+title: MCP tools (local)
+description: Use MCP tools against local projects.
+---
+
+MCP tools are the same in Cloud and Local. In local mode, they operate on folders on your machine.
+
+## Use tools in local mode
+
+When you run the local MCP server, tools read and write local project folders by default.
+
+## Common tools
+
+- `search_notes` to find notes
+- `read_note` to load a note
+- `write_note` to create or update a note
+- `edit_note` to append or replace sections
+
+## Example
+
+```python
+search_notes(query="architecture", project="main")
+```
+
+## Next steps
+
+:::card-group
+::card
+---
+title: MCP Tools Reference
+icon: i-lucide-wrench
+to: /reference/mcp-tools-reference
+---
+Complete tool documentation with all parameters.
+::
+
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+Learn about note structure and semantic patterns.
+::
+:::
diff --git a/content/4.local/4.user-guide.md b/content/4.local/4.user-guide.md
new file mode 100644
index 0000000..34e218c
--- /dev/null
+++ b/content/4.local/4.user-guide.md
@@ -0,0 +1,581 @@
+---
+title: User Guide
+description: Learn how to effectively use Basic Memory in your daily workflow to build rich semantic knowledge.
+---
+
+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](/cloud/cloud-guide) for setup and the [Web App](/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](/start-here/getting-started#choosing-where-your-notes-are-saved) for more information.
+::
+
+### Direct File Creation
+
+You can also create files directly:
+
+1. Create a new Markdown file in your project directory
+2. Add frontmatter with title, type, and optional tags
+3. Structure content with observations and relations
+4. Save the file - it syncs automatically
+
+**Example file structure:**
+```bash
+---
+title: API Design Decisions
+tags: [api, architecture, decisions]
+---
+
+# API Design Decisions
+
+## Context
+We needed to choose an approach for the new API.
+
+## Observations
+- [decision] Use REST over GraphQL for simplicity #api
+- [requirement] Must support versioning from day one
+- [risk] Rate limiting needed for public endpoints
+
+## Relations
+- implements [[API Specification]]
+- depends_on [[Authentication System]]
+```
+
+---
+
+## Using Special Prompts
+
+Basic Memory includes special prompts that help you leverage your knowledge base effectively.
+
+### Continue Conversation
+
+Resume previous topics with full context:
+
+```bash
+"Let's continue our conversation about [topic]"
+```
+
+**What happens:**
+- Searches your knowledge base for relevant content
+- Builds context from related documents
+- Resumes with awareness of previous discussions
+
+### Recent Activity
+
+See what you've been working on:
+
+```bash
+"What have we been discussing recently?"
+```
+
+**What happens:**
+- Retrieves recently modified documents
+- Summarizes main topics and points
+- Offers to continue any discussions
+
+### Search
+
+Find specific information:
+
+```bash
+"Find information about [topic]"
+```
+
+**What happens:**
+- Searches across all your documents
+- Summarizes key findings
+- Offers to explore specific documents
+
+---
+
+## Working with Memory URLs
+
+Basic Memory uses special `memory://` URLs to reference knowledge:
+
+### URL Formats
+
+```bash
+memory://title # Reference by title
+memory://folder/title # Reference by folder and title
+memory://permalink # Reference by permalink
+memory://path/relation_type/* # Follow all relations of type
+```
+
+### Using Memory URLs
+
+Reference existing knowledge in conversations:
+
+```bash
+You: "Take a look at memory://coffee-brewing-methods and let's discuss improvements"
+```
+
+Claude will load that specific document and any related context.
+
+::tip
+Memory URLs are stable identifiers. Even if you rename or move a file, the permalink stays the same (unless you configure otherwise).
+::
+
+---
+
+## Building Knowledge Connections
+
+### Creating Relations
+
+Use WikiLink syntax to connect knowledge:
+
+```bash
+## Relations
+- implements [[Authentication System]]
+- requires [[Database Schema]]
+- relates_to [[Security Guidelines]]
+```
+
+### Common Relation Types
+
+| Type | Use for |
+|------|---------|
+| `implements` | One thing implements another |
+| `requires` | Dependencies |
+| `relates_to` | General connections |
+| `part_of` | Hierarchy relationships |
+| `extends` | Extensions or enhancements |
+| `pairs_with` | Things that work together |
+| `inspired_by` | Source of ideas |
+| `replaces` | Supersedes another document |
+
+### Adding Observations
+
+Structure facts with semantic categories:
+
+```bash
+## Observations
+- [decision] We chose JWT tokens for stateless auth
+- [requirement] Must support 2FA for sensitive operations
+- [technique] Use bcrypt for password hashing
+- [issue] Rate limiting needed for login attempts
+- [fact] Average response time is 50ms
+- [question] Should we support OAuth?
+```
+
+---
+
+## Multi-Project Workflows
+
+### How Projects Work
+
+Basic Memory supports multiple projects for organizing different knowledge bases. When you start a conversation, the AI will:
+
+1. Check your available projects
+2. Suggest the most active project based on recent activity
+3. Ask which project to use for this conversation
+4. Remember your choice throughout the session
+
+**Example conversation:**
+```bash
+You: "Let's work on documentation"
+
+Claude: I see you have 3 projects: main, work-notes, personal
+Your most active project is work-notes.
+Should I use work-notes for this task?
+
+You: "Yes, let's use work-notes"
+
+Claude: I'll use the 'work-notes' project for our session.
+```
+
+### Single Project Users
+
+If you only use one project, you can skip the selection prompt. Add this to `~/.basic-memory/config.json`:
+
+```json
+{
+ "default_project": "main",
+ "default_project_mode": true
+}
+```
+
+With this enabled, the AI uses your default project automatically. You can still override by explicitly specifying a different project.
+
+### Single Project Mode (Locked)
+
+For focused sessions or automation, lock the MCP server to one project:
+
+```bash
+basic-memory mcp --project work-notes
+```
+
+This **locks** the entire MCP session - the `project` parameter in tool calls will be ignored.
+
+**When to use:**
+- Automation workflows that should only access one project
+- Focused sessions where you want to prevent cross-project operations
+- Team environments with project-specific access
+
+::note
+**Key difference:**
+- **Default Project Mode**: Uses default automatically, but can still switch
+- **Single Project Mode**: Locked to one project, cannot switch
+::
+
+### Moving Notes Between Projects
+
+::warning
+Moving notes from one project to another is not currently supported directly. The easiest approach is to:
+1. Copy the file manually between project directories
+2. Or create a new note in the destination project, then delete the original
+::
+
+---
+
+## File Organization
+
+### Directory Structure
+
+Organize files in any structure that suits you:
+
+```bash
+~/basic-memory/
+├── projects/ # Active project notes
+│ ├── api-redesign/
+│ └── mobile-app/
+├── decisions/ # Decision records
+├── learning/ # Research and learning notes
+├── meetings/ # Meeting notes
+└── archive/ # Completed/old content
+```
+
+### Best Practices
+
+- Use descriptive filenames
+- Group related content in folders
+- Include dates in time-sensitive notes (e.g., `2024-01-15 Team Standup.md`)
+- Archive old content regularly
+
+### Controlling What Gets Indexed
+
+Basic Memory respects `.gitignore` patterns to skip sensitive files.
+
+**Pattern sources:**
+- **Global patterns**: `~/.basic-memory/.bmignore` (all projects)
+- **Project patterns**: `{project}/.gitignore` (specific project)
+
+**Example `.gitignore`:**
+```gitignore
+# Sensitive files
+.env
+*.key
+credentials.json
+
+# Build artifacts
+node_modules/
+__pycache__/
+dist/
+
+# OS files
+.DS_Store
+Thumbs.db
+```
+
+Files matching these patterns are automatically skipped during indexing.
+
+---
+
+## Enhanced Editing
+
+### Incremental Editing
+
+Edit notes without rewriting entire documents:
+
+```bash
+You: "Add a troubleshooting section to my setup guide"
+Claude: [Uses edit_note with append operation]
+"I've added a troubleshooting section to the end of your setup guide."
+```
+
+**Available operations:**
+- `append` - Add content to end
+- `prepend` - Add content to beginning
+- `find_replace` - Replace specific text
+- `replace_section` - Replace entire section by heading
+
+### Smart File Organization
+
+Move and rename notes with database consistency:
+
+```bash
+You: "Move my old meeting notes to the archive folder"
+Claude: [Uses move_note]
+"Done! I've moved 12 meeting notes to the archive folder."
+```
+
+### Directory Operations
+
+Move or delete entire folders:
+
+```bash
+You: "Move the old-projects folder to archive"
+Claude: [Uses move_note with is_directory=true]
+"Moved old-projects/ → archive/old-projects/ (15 files)"
+
+You: "Delete the empty temp folder"
+Claude: [Uses delete_note with is_directory=true]
+"Deleted temp/ and all 3 contained files"
+```
+
+### Enhanced Search
+
+Tags in frontmatter are searchable:
+
+```yaml
+---
+title: Coffee Notes
+tags: [brewing, equipment, techniques]
+---
+```
+
+Searching for "brewing notes" will find this document.
+
+---
+
+## Syncing and Updates
+
+### Real-time Sync
+
+Basic Memory automatically syncs file changes in real-time. When you edit a file in your editor:
+1. The change is detected within ~1 second
+2. The file is re-parsed for observations and relations
+3. The database is updated
+4. Search index is refreshed
+
+No manual sync needed for normal workflows.
+
+### Checking Status
+
+```bash
+# View sync status
+basic-memory status
+
+# View project information
+basic-memory project info
+```
+
+### Force Re-sync
+
+If something seems out of sync:
+
+```bash
+# Re-sync all files
+basic-memory sync
+
+# Reset and rebuild database (use if issues persist)
+basic-memory reset
+```
+
+::warning
+`basic-memory reset` rebuilds the entire database from your files. This is safe (files are never deleted) but may take time for large knowledge bases.
+::
+
+---
+
+## Integration Tips
+
+### With Obsidian
+
+1. Open your `~/basic-memory` directory as an Obsidian vault
+2. Use **Graph View** to visualize connections
+3. Edit files directly in Obsidian
+4. Changes sync automatically - ask the AI to read a note to see updates
+
+
+
+
+::tip
+Obsidian's graph view is excellent for discovering unexpected connections in your knowledge base.
+::
+
+### With Git
+
+Basic Memory files are git-friendly:
+
+```bash
+cd ~/basic-memory
+git init
+git add .
+git commit -m "Initial knowledge base"
+```
+
+Benefits:
+- Version history for all changes
+- Backup to GitHub/GitLab
+- Collaborate with others
+- Track what changed over time
+
+### With Other Editors
+
+Basic Memory uses standard Markdown that works with:
+- **VS Code** with Markdown extensions
+- **Typora** for rich text editing
+- **Any text editor** for quick edits
+- **Web editors** for remote access
+
+The database syncs regardless of how you edit files.
+
+---
+
+## Best Practices
+
+### Knowledge Creation
+
+1. **Create relations** - Link related concepts with `[[WikiLinks]]`
+2. **Make observations** - Structure facts with `[category]` syntax
+3. **Be descriptive** - Use clear titles and rich content
+4. **Add context** - Include background and reasoning
+5. **Review and refine** - Edit AI-generated content for accuracy
+
+### Workflow
+
+1. **Use special prompts** - "Continue conversation", "Recent activity", "Search"
+2. **Build incrementally** - Add to existing notes rather than creating duplicates
+3. **Organize regularly** - Move old content to archive
+4. **Cross-reference** - Link new content to existing knowledge
+5. **Use projects** - Separate work, personal, research
+
+### Long-term Maintenance
+
+1. **Archive old content** - Keep active knowledge base focused
+2. **Refactor connections** - Update relations as knowledge evolves
+3. **Regular reviews** - Periodically update key documents
+4. **Backup regularly** - Use git, cloud sync, or snapshots
+
+---
+
+## Troubleshooting
+
+### Changes Not Syncing
+
+1. Check sync status: `basic-memory status`
+2. Verify file permissions
+3. Check if file matches ignore patterns
+4. Reset database: `basic-memory reset`
+
+### Claude Can't Find Knowledge
+
+1. Confirm files are in correct project directory
+2. Check frontmatter formatting (valid YAML)
+3. Use `memory://` URLs for direct references
+4. Trigger re-sync: `basic-memory sync`
+
+### Performance Issues
+
+1. Check database size: `basic-memory project info`
+2. Archive old content
+3. Adjust sync delay in config (default: 1000ms)
+
+### Getting Help
+
+- **Discord**: [discord.gg/tyvKNccgqN](https://discord.gg/tyvKNccgqN) - #help channel
+- **GitHub**: [github.com/basicmachines-co/basic-memory/issues](https://github.com/basicmachines-co/basic-memory/issues)
+
+```bash
+# View all commands
+basic-memory --help
+
+# Help for specific commands
+basic-memory sync --help
+basic-memory project --help
+```
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+Learn the semantic patterns for observations and relations.
+::
+
+::card
+---
+title: Configuration
+icon: i-lucide-settings
+to: /reference/configuration
+---
+All configuration options and environment variables.
+::
+
+::card
+---
+title: CLI Reference
+icon: i-lucide-terminal
+to: /reference/cli-reference
+---
+Complete command line tools reference.
+::
+
+::card
+---
+title: Obsidian Integration
+icon: i-lucide-hexagon
+to: /integrations/obsidian
+---
+Visual knowledge navigation with graph view.
+::
+:::
diff --git a/content/5.concepts/.navigation.yml b/content/5.concepts/.navigation.yml
new file mode 100644
index 0000000..2b72ec4
--- /dev/null
+++ b/content/5.concepts/.navigation.yml
@@ -0,0 +1,2 @@
+title: Concepts
+icon: i-lucide-lightbulb
diff --git a/content/5.concepts/1.knowledge-format.md b/content/5.concepts/1.knowledge-format.md
new file mode 100644
index 0000000..5df53f1
--- /dev/null
+++ b/content/5.concepts/1.knowledge-format.md
@@ -0,0 +1,302 @@
+---
+title: Knowledge Format
+description: Learn Basic Memory's knowledge format using standard Markdown with semantic patterns to create a knowledge graph.
+---
+
+Understanding how Basic Memory structures knowledge helps you create richer, more connected notes. Here's how the semantic patterns work.
+
+::tip
+Using Basic Memory Cloud? The knowledge format works exactly the same - create notes through AI conversations or edit directly in the [Web Editor](/cloud/cloud-guide#web-editor).
+::
+
+---
+
+## File-First Architecture
+
+All knowledge in Basic Memory is stored in plain text Markdown files:
+
+::note{icon="i-lucide-info"}
+- Files are the source of truth for all knowledge
+- Changes to files automatically update the knowledge graph in the database
+- You maintain complete ownership and control
+- Files work with git and other version control systems
+- Knowledge persists independently of any AI conversation
+::
+
+---
+
+## Core Document Structure
+
+Every document uses this basic structure:
+
+```bash
+---
+title: Document Title
+type: note
+tags: [tag1, tag2]
+permalink: custom-path
+---
+
+# Document Title
+Regular markdown content...
+
+## Observations
+- [category] Content with #tags (optional context)
+
+## Relations
+- relation_type [[Other Document]] (optional context)
+```
+
+---
+
+## Frontmatter
+
+The YAML frontmatter at the top of each file defines essential metadata:
+
+```yaml
+---
+title: Document Title # Used for linking and references
+type: note # Document type
+tags: [tag1, tag2] # For organization and searching
+permalink: custom-link # Optional custom URL path
+---
+```
+
+::note
+The title is particularly important as it's used to create links between documents.
+::
+
+---
+
+## Observations
+
+Observations are facts or statements about a topic:
+
+```bash
+- [tech] Uses SQLite for storage #database
+- [design] Follows plain-text architecture #architecture
+- [decision] Selected bcrypt for passwords #security (Based on audit)
+```
+
+::note
+Observations are markdown list items beginning with a `[category]` value. Basic Memory knows not to make Markdown checkboxes (`[ ]` or `[x]`) into observations.
+::
+
+Each observation contains:
+- **Category** in [brackets] - classifies the information type
+- **Content text** - the main information
+- Optional **#tags** - additional categorization
+- Optional **(context)** - supporting details
+
+### Common Categories
+
+**Primary categories:**
+- `[tech]` - Technical details
+- `[design]` - Architecture decisions
+- `[feature]` - User capabilities
+- `[decision]` - Choices that were made
+
+**Additional categories:**
+- `[principle]` - Fundamental concepts
+- `[method]` - Approaches or techniques
+- `[preference]` - Personal opinions
+- `[fact]` - Established information
+- `[question]` - Open questions or unknowns
+- `[todo]` - Action items
+
+---
+
+## Relations
+
+Relations connect documents to form the knowledge graph:
+
+```bash
+- implements [[Search Design]]
+- depends_on [[Database Schema]]
+- relates_to [[User Interface]]
+```
+
+::note
+Relations are markdown list items beginning with a descriptive word, followed by a `[[wiki link]]` value. The description becomes the relationship type.
+::
+
+You can also create inline references:
+```bash
+This builds on [[Core Design]] and uses [[Utility Functions]].
+```
+
+### Common Relation Types
+
+- `implements` - Implementation of a specification
+- `depends_on` - Required dependency
+- `relates_to` - General connection
+- `inspired_by` - Source of ideas
+- `extends` - Enhancement
+- `part_of` - Component relationship
+- `contains` - Hierarchical relationship
+- `pairs_with` - Complementary relationship
+- `replaces` - Supersedes another document
+- `references` - Citation or mention
+
+---
+
+## Knowledge Graph
+
+Basic Memory automatically builds a knowledge graph from your document connections:
+
+- Each document becomes a node in the graph
+- Relations create edges between nodes
+- Relation types add semantic meaning to connections
+- Forward references can link to documents that don't exist yet
+
+::mermaid
+---
+code: |
+ erDiagram
+ ENTITY ||--o{ OBSERVATION : has
+ ENTITY ||--o{ RELATION : has
+ RELATION }o--|| ENTITY : "links to"
+
+ ENTITY {
+ string title
+ string permalink
+ string content
+ array tags
+ }
+
+ OBSERVATION {
+ string category
+ string content
+ array tags
+ string context
+ }
+
+ RELATION {
+ string type
+ string target
+ string context
+ }
+---
+::
+
+This graph enables rich context building and navigation across your knowledge base.
+
+---
+
+## Permalinks
+
+Every document has a unique **permalink** that serves as its stable identifier.
+
+### How Permalinks Work
+
+::note{icon="i-lucide-info"}
+- **Automatically assigned**: The system generates a permalink for each document
+- **Based on title**: By default, derived from the document title
+- **Always unique**: If conflicts exist, the system adds a suffix
+- **Stable reference**: Remains the same even if the file moves
+- **Used in memory:// URLs**: Forms the basis of the addressing scheme
+::
+
+You can specify a custom permalink in the frontmatter:
+```yaml
+---
+title: Authentication Approaches
+permalink: auth-approaches-2024
+---
+```
+
+If not specified, one will be generated automatically from the title.
+
+### Permalink Stability
+
+By default, a note's permalink value will not change if the file is moved - it's a **stable** identifier. To change this behavior, edit `~/.basic-memory/config.json`:
+
+```json
+{
+ "update_permalinks_on_move": true
+}
+```
+
+---
+
+## Memory URLs
+
+The `memory://` URL scheme provides a reliable way to reference knowledge:
+
+```
+memory://auth-approaches-2024 # Direct access by permalink
+memory://Authentication Approaches # Access by title (resolves automatically)
+memory://project/auth-approaches # Access by path
+```
+
+### Pattern Matching
+
+Memory URLs support pattern matching for powerful queries:
+
+```
+memory://auth* # All documents starting with "auth"
+memory://*/approaches # All documents ending with "approaches"
+memory://project/*/requirements # All requirements in project folder
+memory://docs/search/implements/* # Follow all implements relations
+```
+
+This addressing scheme ensures content remains accessible even as your knowledge base evolves and files are reorganized.
+
+---
+
+## File Organization
+
+Organize files in any structure that suits your needs:
+
+```
+docs/
+ architecture/
+ design.md
+ patterns.md
+ features/
+ search.md
+ auth.md
+```
+
+You can:
+- Group by topic in folders
+- Use a flat structure with descriptive filenames
+- Tag files for easier discovery
+- Add custom metadata in frontmatter
+
+::note
+The system builds the semantic knowledge graph regardless of how you organize your files.
+::
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Observations and Relations
+icon: i-lucide-link
+to: /concepts/observations-and-relations
+---
+Detailed patterns and examples for semantic markup.
+::
+
+::card
+---
+title: Projects and Folders
+icon: i-lucide-folder
+to: /concepts/projects-and-folders
+---
+Organizing multiple knowledge bases.
+::
+
+::card
+---
+title: Memory URLs
+icon: i-lucide-at-sign
+to: /concepts/memory-urls
+---
+Advanced URL patterns for navigation.
+::
+:::
diff --git a/content/5.concepts/2.projects-and-folders.md b/content/5.concepts/2.projects-and-folders.md
new file mode 100644
index 0000000..42f40af
--- /dev/null
+++ b/content/5.concepts/2.projects-and-folders.md
@@ -0,0 +1,48 @@
+---
+title: Projects and folders
+description: How projects map to folders on disk or in the Cloud.
+---
+
+Projects are top‑level containers. Each project maps to a folder tree.
+
+## Create a project
+
+```bash
+bm project add "work" ~/Documents/work-notes
+```
+
+## Set the default project
+
+```bash
+bm project default "work"
+```
+
+## Organize with folders
+
+Use normal folders inside a project. The folder structure is preserved in Cloud and local modes.
+
+## When to use multiple projects
+
+Use separate projects when you want strict boundaries (work vs personal, client vs internal).
+
+## Next steps
+
+:::card-group
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+Learn the note structure with observations and relations.
+::
+
+::card
+---
+title: Notes Interface
+icon: i-lucide-layout-panel-left
+to: /cloud/cloud-app/notes-interface
+---
+Use notes in the Cloud app.
+::
+:::
diff --git a/content/5.concepts/3.observations-and-relations.md b/content/5.concepts/3.observations-and-relations.md
new file mode 100644
index 0000000..eaba9f3
--- /dev/null
+++ b/content/5.concepts/3.observations-and-relations.md
@@ -0,0 +1,51 @@
+---
+title: Observations and relations
+description: Use structured lines to make notes searchable and connected.
+---
+
+Observations and relations are light structure on top of Markdown. They help search and give your assistant more context.
+
+## Capture observations
+
+Use short, tagged statements:
+
+```bash [notes/system-design.md]
+- [decision] Use Postgres for primary storage #database
+- [risk] Latency spikes under heavy load #performance
+```
+
+## Add relations
+
+Use wiki‑style links to connect notes with meaning:
+
+```bash [notes/system-design.md]
+## Relations
+- depends_on [[Caching Layer]]
+- relates_to [[Latency Budget]]
+```
+
+## Why it matters
+
+Observations make search precise. Relations explain how notes connect, which helps assistants build better context.
+
+## Next steps
+
+:::card-group
+::card
+---
+title: Memory URLs
+icon: i-lucide-at-sign
+to: /concepts/memory-urls
+---
+See how links resolve and navigate knowledge.
+::
+
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+Learn the base note format.
+::
+:::
diff --git a/content/5.concepts/4.memory-urls.md b/content/5.concepts/4.memory-urls.md
new file mode 100644
index 0000000..d4c923b
--- /dev/null
+++ b/content/5.concepts/4.memory-urls.md
@@ -0,0 +1,46 @@
+---
+title: Memory URLs
+description: Address notes directly with memory:// paths.
+---
+
+Memory URLs let tools reference notes directly by path or permalink. They are useful for linking and for tool calls like `build_context`.
+
+## Reference a note by path
+
+```
+memory://project/authentication.md
+```
+
+## Reference a note by permalink
+
+```
+memory://auth-approaches-2024
+```
+
+## Use wildcards
+
+```
+memory://auth*
+```
+
+## Next steps
+
+:::card-group
+::card
+---
+title: MCP Tools Reference
+icon: i-lucide-wrench
+to: /reference/mcp-tools-reference
+---
+Learn how tools use URLs in their parameters.
+::
+
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+See examples of URLs in notes.
+::
+:::
diff --git a/src/pages/guides/canvas.mdx b/content/5.concepts/5.canvas.md
similarity index 53%
rename from src/pages/guides/canvas.mdx
rename to content/5.concepts/5.canvas.md
index e501334..590d51d 100644
--- a/src/pages/guides/canvas.mdx
+++ b/content/5.concepts/5.canvas.md
@@ -1,11 +1,7 @@
---
-layout: '@/layouts/DocsLayout.astro'
-title: 'Canvas Visualizations'
-description: "Create visual knowledge maps using Obsidian's Canvas feature to understand relationships between concepts"
+title: Canvas Visualizations
+description: Create visual knowledge maps using Obsidian's Canvas feature to understand relationships between concepts
---
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step, CodeGroup, CodeTab } from '@/components'
-
# Canvas Visualizations
Basic Memory can create visual knowledge maps using Obsidian's Canvas feature. These visualizations help you understand relationships between concepts, map out processes, and visualize your knowledge structure.
@@ -14,13 +10,7 @@ Basic Memory can create visual knowledge maps using Obsidian's Canvas feature. T
Ask Claude to create a visualization by describing what you want to map:
-
-
-- "Create a canvas visualization of my project components and their relationships."
-- "Make a concept map showing the main themes from our discussion about climate change."
-- "Can you make a canvas diagram of the perfect pour over method?"
-
-
+- **Example Requests** — - "Create a canvas visualization of my project components and their relationships." - "Make a concept map showing the main themes from our discussion about climate change." - "Can you make a canvas diagram of the perfect pour over method?"
@@ -28,20 +18,10 @@ Ask Claude to create a visualization by describing what you want to map:
Basic Memory can create several types of visual maps:
-
-
-Visualize connections between your notes and documents
-
-
-Create visual representations of ideas and their relationships
-
-
-Map workflows, sequences, and procedures
-
-
-Organize ideas around central themes
-
-
+- **Document Maps** — Visualize connections between your notes and documents
+- **Concept Maps** — Create visual representations of ideas and their relationships
+- **Process Diagrams** — Map workflows, sequences, and procedures
+- **Thematic Analysis** — Organize ideas around central themes
### Relationship Networks
@@ -77,54 +57,44 @@ You: "Create a visual map showing how different philosophical schools relate to
## Visualization Workflow
-
-
+::steps
+### Request a visualization
Describe what you want to see by asking Claude to create a canvas
-
-
+
+### Claude creates the canvas file
The canvas file is automatically created in your Basic Memory directory
-
-
+
+### Open the file in Obsidian
View the visualization in Obsidian's Canvas feature
-
-
+
+### Refine the visualization
Ask Claude for adjustments:
- "Could you reorganize the canvas to group related components together?"
- "Please add more detail about the connection between these two concepts."
-
-
+
+::
## Technical Details
-Behind the scenes, Claude:
+Behind the scenes, the AI:
-
+::note
1. Creates a `.canvas` file in JSON format
2. Adds nodes for each concept or document
3. Creates edges to represent relationships
4. Sets positions for visual clarity
5. Includes any relevant metadata
-
+::
The resulting file is fully compatible with Obsidian's Canvas feature and can be edited directly in Obsidian.
## Tips for Effective Visualizations
-
-
-Clearly describe what you want to visualize
-
-
-Mention how much detail you need
-
-
-Specify the visualization type (concept map, process flow, etc.)
-
-
-Begin with basic visualizations and ask for refinements
-
-
-
-
+- **Be Specific** — Clearly describe what you want to visualize
+- **Specify Detail Level** — Mention how much detail you need
+- **Mention Type** — Specify the visualization type (concept map, process flow, etc.)
+- **Start Simple** — Begin with basic visualizations and ask for refinements
+
+::note
**Provide context** about what documents or concepts to include for the best results.
-
\ No newline at end of file
+::
diff --git a/content/6.integrations/.navigation.yml b/content/6.integrations/.navigation.yml
new file mode 100644
index 0000000..1b57262
--- /dev/null
+++ b/content/6.integrations/.navigation.yml
@@ -0,0 +1,2 @@
+title: Integrations
+icon: i-lucide-plug
diff --git a/content/6.integrations/1.claude-desktop.md b/content/6.integrations/1.claude-desktop.md
new file mode 100644
index 0000000..f7e4001
--- /dev/null
+++ b/content/6.integrations/1.claude-desktop.md
@@ -0,0 +1,191 @@
+---
+title: Claude Desktop
+description: Set up Basic Memory with Claude Desktop for persistent conversations and knowledge management
+---
+
+Claude Desktop is the recommended way to use Basic Memory. Integration through the Model Context Protocol (MCP) gives Claude direct access to your knowledge base.
+
+## Cloud Setup
+
+::steps
+### Sign Up
+Create your account at [app.basicmemory.com](https://app.basicmemory.com)
+
+### Add Remote MCP Connector
+In Claude Desktop, go to **Settings → Claude → Connectors**
+
+Click "Add connector" and enter:
+- **Name**: Basic Memory
+- **Remote MCP server URL**: `https://cloud.basicmemory.com/mcp`
+
+
+
+### Authenticate
+Click "Connect" and follow the OAuth flow to grant permissions
+
+
+
+### Verify Setup
+In Claude, click the tools icon (🔨) to see Basic Memory tools
+
+
+
+Try Prompting: `List my projects`
+
+::
+
+::tip
+See the [Cloud Guide](/cloud/cloud-guide) for web editor usage and troubleshooting.
+::
+
+---
+
+## Local Setup
+
+For local installation, see [Quickstart: Local](/start-here/quickstart-local) to install Basic Memory and configure Claude Desktop.
+
+---
+
+## Features
+
+### Core Capabilities
+
+- **Knowledge Creation** — Create and update notes through natural conversation
+- **Knowledge Search** — Find information across your entire knowledge base
+- **Context Building** — Load context from previous conversations using memory:// URLs
+- **Project Management** — Work with multiple knowledge projects in each conversation
+- **Visual Note Display** — View notes as formatted artifacts for better readability
+
+### Real-time Sync
+
+Changes you make to files are immediately available in conversations:
+
+1. Edit a file in any text editor
+2. Save the changes
+3. Ask Claude to read the note - it will see your updates
+
+### Memory URLs
+
+Reference specific knowledge with `memory://` URLs:
+
+```bash
+You: "Take a look at memory://project-planning and let's continue our discussion"
+```
+
+Claude will load that specific note and any related context.
+
+## Common Workflows
+
+### Creating Knowledge
+
+**During a conversation:**
+```bash
+You: "Could you create a note summarizing our discussion about API design?"
+Claude: I'll create a note capturing our API design discussion...
+[Creates structured note with observations and relations]
+```
+
+**Building on existing knowledge:**
+```bash
+You: "Add a section about authentication to my API documentation"
+Claude: [Uses edit_note to append new content without rewriting]
+```
+
+### Searching and Discovery
+
+**Find information:**
+```bash
+You: "What did we decide about the database schema?"
+Claude: [Searches knowledge base and provides relevant information]
+```
+
+**View formatted notes:**
+```bash
+You: "Show me the project documentation as a formatted artifact"
+Claude: [Uses view_note to display the note as a readable artifact]
+```
+
+**Recent activity:**
+```bash
+You: "What have we been working on lately?"
+Claude: [Shows recently modified notes and offers to continue discussions]
+```
+
+### Project Management
+
+Projects are selected at the start of each conversation. Claude will suggest your most active project and ask which one to use.
+
+**For single-project users**, add this to `~/.basic-memory/config.json`:
+```json
+{
+ "default_project": "main",
+ "default_project_mode": true
+}
+```
+
+This skips project selection and uses your default project automatically.
+
+## Troubleshooting
+
+### Claude can't find Basic Memory tools
+**Solutions:**
+- Verify `uv` is installed: `which uvx`
+- Check config file syntax is valid JSON
+- Restart Claude Desktop after config changes
+- Try absolute path to uvx in config
+
+### Tools appear but don't work
+**Solutions:**
+- Check Basic Memory is installed: `basic-memory --version`
+- Verify sync is running: `basic-memory status`
+- Check file permissions in `~/basic-memory`
+- Look for error messages in Claude Desktop
+
+### Changes not syncing
+**Solutions:**
+- Confirm real-time sync is enabled (default)
+- Check `basic-memory status` for sync status
+- Restart sync: `basic-memory sync --watch`
+- Verify file is in the correct project directory
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: User Guide
+icon: i-lucide-book-open
+to: /local/user-guide
+---
+Learn comprehensive usage patterns for daily workflows.
+::
+
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+Understand the semantic markup with observations and relations.
+::
+
+::card
+---
+title: CLI Reference
+icon: i-lucide-terminal
+to: /reference/cli-reference
+---
+Command line tools and options.
+::
+
+::card
+---
+title: AI Assistant Guide
+icon: i-lucide-bot
+to: /how-to/ai-assistant-guide
+---
+How AI assistants use Basic Memory tools.
+::
+:::
diff --git a/content/6.integrations/2.claude-code.md b/content/6.integrations/2.claude-code.md
new file mode 100644
index 0000000..29a2c5a
--- /dev/null
+++ b/content/6.integrations/2.claude-code.md
@@ -0,0 +1,183 @@
+---
+title: Claude Code
+description: Set up Basic Memory with Claude Code for persistent development knowledge and enhanced coding sessions
+---
+
+Claude Code provides native support for Basic Memory through the Model Context Protocol (MCP), enabling persistent context across development sessions and building comprehensive coding knowledge.
+
+## Cloud Setup
+
+::steps
+### Sign Up
+Create your account at [app.basicmemory.com](https://app.basicmemory.com)
+
+### Add Remote MCP Server
+In Claude Code, add the remote MCP server:
+
+```bash
+claude mcp add -s user -t http basic-memory-cloud https://cloud.basicmemory.com/mcp
+```
+
+### Authenticate
+Follow the OAuth flow in Claude Code to grant permissions
+
+### Verify Setup
+In Claude Code, check available tools:
+
+```bash
+You: "What tools do you have access to?"
+```
+
+You should see Basic Memory tools listed
+
+::
+
+::tip
+See the [Cloud Guide](/cloud/cloud-guide) for detailed instructions and troubleshooting.
+::
+
+---
+
+## Local Setup
+
+### Configure Claude Code
+
+Install with:
+
+```bash
+claude mcp add basic-memory basic-memory mcp
+```
+
+::note
+For Basic Memory installation, see [Quickstart: Local](/start-here/quickstart-local).
+::
+
+### Verify Installation
+
+In Claude Code, check that Basic Memory tools are available:
+
+```bash
+You: "What tools do you have access to?"
+```
+
+You should see Basic Memory tools listed, including note creation, search, and project management.
+
+## Quick Start
+
+Once configured, you can immediately start using Basic Memory in your development workflow:
+
+```bash
+You: "Create a note about our authentication strategy for the API"
+Claude: I'll document the authentication strategy we discussed...
+[Creates structured note with technical details and rationale]
+
+You: "Switch to my personal coding project"
+Claude: [Changes context to personal project knowledge base]
+```
+
+## MCP Integration Benefits
+
+Claude Code's native MCP support provides:
+
+- **Automatic tool access** - No manual setup required
+- **Project-aware context** - Maintains separate knowledge bases per project
+- **Real-time sync** - Changes are immediately available
+- **Persistent memory** - Context survives between sessions
+- **Structured knowledge** - Uses Basic Memory's semantic format
+
+### Available Tools
+
+Through MCP, Claude Code can access all Basic Memory functionality:
+
+- **write_note** - Create and update documentation
+- **read_note** - Access existing knowledge and context
+- **search_notes** - Find relevant information across projects
+- **edit_note** - Update documentation incrementally
+- **recent_activity** - Check what you've been working on
+- **project management** - Switch between different knowledge bases
+- **build_context** - Load conversation context from memory:// URLs
+
+## Integration with Development
+
+### CLAUDE.md Enhancement
+
+Claude Code uses CLAUDE.md files for project instructions. Basic Memory complements this by:
+
+- **Storing detailed knowledge** outside the context window
+- **Enabling search** across your entire knowledge base
+- **Maintaining history** of decisions and learnings
+- **Linking related concepts** through relations
+
+### Project Context
+
+Basic Memory maintains separate knowledge bases for different projects:
+
+```bash
+You: "Switch to my work project"
+Claude: [Loads work project context and knowledge]
+
+You: "Based on our API design notes, what's the next step?"
+Claude: [References existing documentation to provide contextual guidance]
+```
+
+## Troubleshooting
+
+### Claude Code can't access Basic Memory
+**Solutions:**
+- Verify Basic Memory is installed: `basic-memory --version`
+- Check MCP server status: `/mcp` in Claude Code
+- Reinstall if needed: `claude mcp remove basic-memory` then `claude mcp add basic-memory basic-memory mcp`
+
+### Context not loading from memory:// URLs
+**Solutions:**
+- Confirm files exist in current project
+- Check memory:// URL syntax (e.g., `memory://folder/note`)
+- Verify sync is working: `basic-memory status`
+
+### Notes not updating
+**Solutions:**
+- Check file permissions in knowledge base directory
+- Check ~/.basic-memory for logs containing error messages
+- Report error messages to the Basic Memory team
+
+---
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Project Documentation
+icon: i-lucide-folder-kanban
+to: /how-to/project-documentation
+---
+Learn how to document your development projects.
+::
+
+::card
+---
+title: Research & Learning
+icon: i-lucide-graduation-cap
+to: /how-to/research-learning
+---
+Build knowledge from your coding sessions.
+::
+
+::card
+---
+title: CLI Reference
+icon: i-lucide-terminal
+to: /reference/cli-reference
+---
+Master Basic Memory command line tools.
+::
+
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+Structure effective development documentation.
+::
+:::
diff --git a/src/pages/integrations/chatgpt.mdx b/content/6.integrations/3.chatgpt.md
similarity index 67%
rename from src/pages/integrations/chatgpt.mdx
rename to content/6.integrations/3.chatgpt.md
index dc35ae4..2bbf39b 100644
--- a/src/pages/integrations/chatgpt.mdx
+++ b/content/6.integrations/3.chatgpt.md
@@ -1,69 +1,61 @@
---
-layout: '@/layouts/DocsLayout.astro'
-title: "ChatGPT"
-description: "Connect ChatGPT to Basic Memory using remote MCP integration"
+title: ChatGPT
+description: Connect ChatGPT to Basic Memory using remote MCP integration
---
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step } from '@/components'
-
ChatGPT connects to Basic Memory through OpenAI's Model Context Protocol implementation, providing search and document retrieval from your knowledge base.
-
+::note
ChatGPT **only works with remote MCP servers**. Basic Memory Cloud provides this out of the box.
-
+::
## Cloud Setup (Recommended)
Basic Memory Cloud provides the remote MCP endpoint ChatGPT requires.
-
-
- Create your account at [app.basicmemory.com](https://app.basicmemory.com)
-
+::steps
+### Sign Up
+Create your account at [app.basicmemory.com](https://app.basicmemory.com)
-
- Your remote MCP URL: `https://cloud.basicmemory.com/mcp`
-
+### Get Your MCP Endpoint
+Your remote MCP URL: `https://cloud.basicmemory.com/mcp`
-
- In ChatGPT, go to Settings → Developer → Custom MCP Servers
+### Configure ChatGPT
+In ChatGPT, go to Settings → Developer → Custom MCP Servers
- Add Basic Memory:
- - **Name**: Basic Memory
- - **Server URL**: `https://cloud.basicmemory.com/mcp`
-
+Add Basic Memory:
+- **Name**: Basic Memory
+- **Server URL**: `https://cloud.basicmemory.com/mcp`
-
- Follow the OAuth flow to grant ChatGPT access to your Basic Memory account
-
+### Authenticate
+Follow the OAuth flow to grant ChatGPT access to your Basic Memory account
-
- When chatting, enable Basic Memory from the MCP server selector to access your knowledge base
-
-
+### Enable in Conversations
+When chatting, enable Basic Memory from the MCP server selector to access your knowledge base
-
-See the [Cloud Setup Guide](/guides/cloud) for detailed instructions and troubleshooting.
-
+::
+
+::tip
+See the [Cloud Setup Guide](/cloud/cloud-guide) for detailed instructions and troubleshooting.
+::
---
## Requirements
-
+::warning
**ChatGPT Plus or Pro subscription required**
MCP integration is not available on ChatGPT's free tier.
- **ChatGPT Plus**: $20/month
- **ChatGPT Pro**: $200/month (includes advanced features)
-
+::
-
+::warning
**Remote MCP server required**
ChatGPT only supports remote MCP servers, not local connections like Claude Desktop.
-
+::
## Available Tools
@@ -84,10 +76,10 @@ You: "Search my knowledge base for authentication notes"
ChatGPT internally calls:
{
- "tool": "search",
- "arguments": {
- "query": "authentication notes"
- }
+"tool": "search",
+"arguments": {
+"query": "authentication notes"
+}
}
Response:
@@ -118,10 +110,10 @@ You: "Show me the Auth Design document"
ChatGPT internally calls:
{
- "tool": "fetch",
- "arguments": {
- "id": "auth-design"
- }
+"tool": "fetch",
+"arguments": {
+"id": "auth-design"
+}
}
Response:
@@ -148,9 +140,9 @@ Here's the Auth Design document:
You: "Find my notes about database design"
ChatGPT: [Calls search tool with query "database design"]
ChatGPT: I found 3 relevant documents:
- 1. Database Schema Design
- 2. PostgreSQL Performance Tips
- 3. Database Migration Strategy
+1. Database Schema Design
+2. PostgreSQL Performance Tips
+3. Database Migration Strategy
```
### Fetch Workflow
@@ -183,12 +175,11 @@ ChatGPT tools automatically resolve projects using:
**Recommended configuration:**
```json
{
- "default_project": "main",
- "default_project_mode": true
+"default_project": "main",
+"default_project_mode": true
}
```
-
## Limitations
### ChatGPT-Specific Constraints
@@ -213,14 +204,31 @@ ChatGPT tools automatically resolve projects using:
## Next Steps
-
-
- Configure automatic project resolution
-
-
- Full MCP integration with 17+ tools
-
-
- Complete MCP tool documentation
-
-
+:::card-group
+::card
+---
+title: Technical Information
+icon: i-lucide-settings
+to: /reference/technical-information
+---
+Configure automatic project resolution and defaults.
+::
+
+::card
+---
+title: Claude Desktop
+icon: i-lucide-message-square
+to: /integrations/claude-desktop
+---
+Full MCP integration with 17+ tools.
+::
+
+::card
+---
+title: MCP Tools Reference
+icon: i-lucide-wrench
+to: /reference/mcp-tools-reference
+---
+Complete MCP tool documentation.
+::
+:::
diff --git a/content/6.integrations/4.gemini.md b/content/6.integrations/4.gemini.md
new file mode 100644
index 0000000..9b1824f
--- /dev/null
+++ b/content/6.integrations/4.gemini.md
@@ -0,0 +1,213 @@
+---
+title: Google Gemini
+description: Set up Basic Memory with Google Gemini for persistent development knowledge and enhanced AI sessions
+---
+Google Gemini provides native support for Basic Memory through the Model Context Protocol (MCP), enabling persistent context across AI sessions and building comprehensive knowledge bases.
+
+## Cloud Setup
+
+Basic Memory Cloud provides hosted MCP access with no local installation required.
+
+::steps
+### Sign Up
+Create your account at [app.basicmemory.com](https://app.basicmemory.com)
+
+### Configure Remote MCP in Gemini
+Add Basic Memory Cloud using HTTP transport:
+
+```bash
+gemini mcp add -t http basic-memory-cloud https://cloud.basicmemory.com/mcp
+```
+
+### Authenticate
+Follow the OAuth flow to grant Gemini access to your Basic Memory account
+
+### Verify Setup
+Check that Basic Memory is configured:
+
+```bash
+gemini mcp list
+```
+
+You should see `basic-memory-cloud` with Connected status
+
+::
+
+::tip
+See the [Cloud Setup Guide](/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:
+
+
+
+
+
+### Configure Gemini
+
+Basic Memory works with Gemini through MCP. Install it with:
+
+```bash
+gemini mcp add basic-memory bash -c "uvx basic-memory mcp"
+```
+
+::tip
+If you want to use a specific Basic Memory project, modify the command like so:
+```bash
+gemini mcp add basic-memory bash -c "uvx basic-memory mcp --project your-project-name"
+```
+
+You can also install it globally for your profile with:
+```bash
+gemini mcp add -s user basic-memory bash -c "uvx basic-memory mcp"
+```
+::
+
+### Verify Installation
+
+Check that Basic Memory is configured correctly:
+
+```bash
+gemini mcp list
+```
+
+You should see `basic-memory` listed with the command `bash -c uvx basic-memory mcp` and a Connected status.
+
+## Quick Start
+
+Once configured, you can immediately start using Basic Memory in your workflow:
+
+```
+You: "Create a note about our authentication strategy for the API"
+Gemini: I'll document the authentication strategy we discussed...
+[Creates structured note with technical details and rationale]
+
+You: "Switch to my personal project"
+Gemini: [Changes context to personal project knowledge base]
+```
+
+## MCP Integration Benefits
+
+Gemini's native MCP support provides:
+
+- **Automatic tool access** - No manual setup required
+- **Project-aware context** - Maintains separate knowledge bases per project
+- **Real-time sync** - Changes are immediately available
+- **Persistent memory** - Context survives between sessions
+- **Structured knowledge** - Uses Basic Memory's semantic format
+
+### Available Tools
+
+Through MCP, Gemini can access all Basic Memory functionality:
+
+- **write_note** - Create and update documentation
+- **read_note** - Access existing knowledge and context
+- **search_notes** - Find relevant information across projects
+- **edit_note** - Update documentation incrementally
+- **recent_activity** - Check what you've been working on
+- **project management** - Switch between different knowledge bases
+- **build_context** - Load conversation context from memory:// URLs
+
+## Integration with Development
+
+### Project Context
+
+Basic Memory maintains separate knowledge bases for different projects:
+
+```
+You: "Switch to my work project"
+Gemini: [Loads work project context and knowledge]
+
+You: "Based on our API design notes, what's the next step?"
+Gemini: [References existing documentation to provide contextual guidance]
+```
+
+## Troubleshooting
+
+### Common Issues
+
+### Gemini can't access Basic Memory
+**Solutions:**
+- Verify Basic Memory is installed: `basic-memory --version`
+- Check MCP server configuration: `gemini mcp list`
+- Reinstall if needed: `gemini mcp remove basic-memory` then `gemini mcp add basic-memory bash -c "uvx basic-memory mcp"`
+
+### Context not loading from memory:// URLs
+**Solutions:**
+- Confirm files exist in current project
+- Check memory:// URL syntax (e.g., `memory://folder/note`)
+- Verify sync is working: `basic-memory status`
+
+### Notes not updating
+**Solutions:**
+- Check file permissions in knowledge base directory
+- Check ~/.basic-memory for logs containing error messages
+- Report error messages to the Basic Memory team
+
+### Performance Tips
+
+- **Multiple projects**: Use separate Basic Memory projects for different use cases
+- **Organized structure**: Keep consistent folder organization across projects
+- **Regular cleanup**: Archive old projects to maintain performance
+
+## Alternative Usage
+
+If MCP isn't working, you can still use Basic Memory:
+
+- **CLI Integration** — Use Basic Memory CLI tools from your terminal
+- **File Editing** — Edit Basic Memory notes directly and sync manually
+- **Manual Context** — Copy content from Basic Memory into conversations
+- **Parallel Usage** — Use Claude Desktop or other MCP clients alongside Gemini. With Basic Memory they can see the same notes and share context.
+
+## Next Steps
+
+:::card-group
+::card
+---
+title: Project Documentation
+icon: i-lucide-folder-kanban
+to: /how-to/project-documentation
+---
+Learn how to document your projects.
+::
+
+::card
+---
+title: Research & Learning
+icon: i-lucide-graduation-cap
+to: /how-to/research-learning
+---
+Build knowledge from your sessions.
+::
+
+::card
+---
+title: CLI Reference
+icon: i-lucide-terminal
+to: /reference/cli-reference
+---
+Master Basic Memory command line tools.
+::
+
+::card
+---
+title: Knowledge Format
+icon: i-lucide-file-text
+to: /concepts/knowledge-format
+---
+Structure effective documentation.
+::
+:::
diff --git a/src/pages/integrations/codex.mdx b/content/6.integrations/5.codex.md
similarity index 50%
rename from src/pages/integrations/codex.mdx
rename to content/6.integrations/5.codex.md
index 4c816e3..16b82b0 100644
--- a/src/pages/integrations/codex.mdx
+++ b/content/6.integrations/5.codex.md
@@ -1,11 +1,7 @@
---
-layout: '@/layouts/DocsLayout.astro'
-title: "OpenAI Codex"
-description: "Set up Basic Memory with OpenAI Codex for persistent development knowledge and enhanced coding sessions"
+title: OpenAI Codex
+description: Set up Basic Memory with OpenAI Codex for persistent development knowledge and enhanced coding sessions
---
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step, CodeGroup, CodeTab } from '@/components'
-
OpenAI Codex provides native support for Basic Memory through the Model Context Protocol (MCP), enabling persistent context across development sessions and building comprehensive coding knowledge.
## Setup
@@ -16,12 +12,12 @@ Watch this quick guide to get started with Basic Memory and OpenAI Codex:
-
\ No newline at end of file
diff --git a/src/layouts/Layout.astro b/src/layouts/Layout.astro
deleted file mode 100644
index 5666e2e..0000000
--- a/src/layouts/Layout.astro
+++ /dev/null
@@ -1,247 +0,0 @@
----
-import '@/styles/global.css'
-
-export interface Props {
- title: string
- description?: string
-}
-
-const { title = 'Basic Memory', description = 'Basic Memory - Persistent memory for Claude AI' } = Astro.props
----
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- {!title || title === 'Basic Memory' ? 'Basic Memory' : `${title} - Basic Memory`}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/src/lib/utils.ts b/src/lib/utils.ts
deleted file mode 100644
index 1a860ee..0000000
--- a/src/lib/utils.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-import { type ClassValue, clsx } from "clsx"
-import { twMerge } from "tailwind-merge"
-
-export function cn(...inputs: ClassValue[]) {
- return twMerge(clsx(inputs))
-}
\ No newline at end of file
diff --git a/src/pages/getting-started.mdx b/src/pages/getting-started.mdx
deleted file mode 100644
index afd5b06..0000000
--- a/src/pages/getting-started.mdx
+++ /dev/null
@@ -1,481 +0,0 @@
----
-layout: '@/layouts/DocsLayout.astro'
-title: 'Getting Started'
-description: 'Install Basic Memory, configure it with your AI assistant, and create your first knowledge notes.'
----
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step } from '@/components'
-
-Basic Memory works through the Model Context Protocol (MCP) to connect with AI assistants like Claude Desktop, Claude Code, and Gemini CLI.
-
-**New to Basic Memory?** Start with [Cloud Setup](#cloud-setup) for the fastest experience.
-
-**Prefer local-only or offline access?** See [Local Installation](#local-installation) - the open-source version is free to install on your own machine.
-
-import InstallationTabs from '../components/InstallationTabs'
-
-## Cloud Setup
-
-Basic Memory Cloud provides hosted MCP access with no local installation required.
-
-
-**Why use Basic Memory Cloud?**
-- Access from any device
-- Easily import your data
-- 2-minute setup
-- Local sync
-- OAuth authentication
-
-
-
-
- Create your account at [app.basicmemory.com](https://app.basicmemory.com)
-
-
-
- In Claude Desktop, go to **Settings → Claude → Connectors**
-
- Click "Add connector" and enter:
- - **Name**: Basic Memory
- - **Remote MCP server URL**: `https://cloud.basicmemory.com/mcp`
-
- 
-
-
-
- Click "Connect" and follow the OAuth flow to grant permissions
-
- 
-
-
-
- In Claude, click the tools icon (🔨) to see Basic Memory tools
-
- 
-
- Try Prompting: `List my projects`
-
-
-
-
-
-See the [Cloud Setup Guide](/guides/cloud) for detailed instructions, web editor usage, and troubleshooting.
-
-
----
-
-## Local Installation
-
-
-Basic Memory is **open source** and free to install on your own machine using the stdio MCP transport. If you decide to use the cloud product later, you can easily upload or sync all of your notes and projects. See the [Cloud Guide](/guides/cloud#migrating-to-cloud) for migration options.
-
-
-### Single-Step Installation (Recommended)
-
-The fastest way to get started with Basic Memory:
-
-
-
-### Universal Installation (All Platforms)
-
-You can install Basic Memory using `uv`, an extremely fast Python package and project manager, written in Rust.
-
-**Requirements**: Python 3.13 or higher
-
-You can install `uv` from [astral's website ↗️](https://docs.astral.sh/uv/getting-started/installation/). After installing `uv` you can install Basic Memory with the command:
-
-```bash
-uv tool install basic-memory
-```
-
-- **`uv` must be installed and available in your system PATH**. Claude Desktop runs in its own isolated environment and needs `uv` to manage dependencies.
-- **Python 3.13+ required**. Check your version with `python --version`.
-
-
-### Homebrew Installation (macOS)
-
-The easiest way to install Basic Memory on macOS is with Homebrew:
-
-```bash
-brew tap basicmachines-co/basic-memory
-brew install basic-memory
-```
-
-
-If you use Homebrew, you do **not** need to install with `uv` or `pip` separately.
-
-
-
-### Configure Claude Desktop
-
-Edit your Claude Desktop config, located at:
-
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-
-
-```json
-{
- "mcpServers": {
- "basic-memory": {
- "command": "uvx",
- "args": [
- "basic-memory",
- "mcp"
- ]
- }
- }
-}
-```
-
-**Restart Claude Desktop**. You should see Basic Memory tools available in the "tools" menu in Claude Desktop (the little hammer icon in the bottom-right corner of the chat interface). Click it to view available tools.
-
-
-
-
-### Choosing Where Your Notes Are Saved
-
-By default, Basic Memory saves notes in a project called `main` in `~/basic-memory`. If you want notes saved somewhere else—like an existing note-taking folder—you can change this easily.
-
-#### Use Your Existing Notes Folder
-
-The easiest way is to ask Claude directly in your conversation. For example:
-
-```
-Create a new project called "my project" in the "/Users/yourname/Documents/Notes" directory
-```
-
-Then:
-
-```
-Set the default project to "my project"
-```
-
-Alternatively, you can use command line tools:
-
-```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"
-```
-
-
-If you change default projects from the command line new notes will be saved in your chosen folder after restarting your MCP Client (e.g. Claude Desktop).
-
-
-**Want to use Obsidian?** Just open your folder location as a vault. See the [Obsidian Integration guide](/integrations/obsidian) for detailed setup with existing vaults.
-
-**Need multiple note collections?** You can create different projects for work, personal, etc. See [Multi-Project Setup](#multi-project-setup) below.
-
-
-**Advanced configuration**: Basic Memory stores its settings in `~/.basic-memory/config.json`. While you can use CLI commands for most configuration (recommended), you can also edit this file directly to manage projects and settings. Changes to the config file 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:**
-```
-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 Claude
-You: "Create a new project called 'work-notes' in ~/Documents/work"
-```
-
-**For users who primarily work in one project:**
-
-Enable Default Project Mode to automatically use your main project. Add this to `~/.basic-memory/config.json`:
-
-```json
-{
- "default_project": "main",
- "default_project_mode": true
-}
-```
-
-With this enabled, the AI uses your default project automatically when no project is specified. You can still override this by explicitly specifying a different project when needed.
-
-## Creating Your First Knowledge Note
-
-1. **Open Claude Desktop** and start a new conversation.
-
-2. **Have a natural conversation** about any topic:
- ```
- You: "Let's talk about coffee brewing methods I've been experimenting with."
- Claude: "I'd be happy to discuss coffee brewing methods..."
- You: "I've found that pour over gives more flavor clarity than French press..."
- ```
-
-3. **Ask Claude to create a note**:
- ```
- You: "Could you create a note summarizing what we've discussed about coffee brewing?"
- ```
-
-4. **Confirm note creation**:
- Claude will confirm when the note has been created and where it is stored.
-
-5. **View the created file** in your `~/basic-memory` directory using any text editor or Obsidian.
- The file structure will look similar to:
- ```markdown
- ---
- title: Coffee Brewing Methods
- permalink: coffee-brewing-methods
- tags: [coffee, brewing, equipment] # v0.14.0: Now searchable!
- ---
-
- # Coffee Brewing Methods
-
- ## Observations
- - [method] Pour over provides more clarity...
- - [technique] Water temperature at 205°F...
-
- ## Relations
- - relates_to [[Other Coffee Topics]]
- ```
-## Using Special Prompts
-
-Basic Memory includes special prompts that help you start conversations with context from your knowledge base:
-
-### Continue Conversation
-
-To resume a previous topic:
-
-```
-You: "Let's continue our conversation about coffee brewing."
-```
-
-This prompt triggers Claude to:
-
-1. Search your knowledge base for relevant content about coffee brewing
-2. Build context from these documents
-3. Resume the conversation with full awareness of previous discussions
-
-### Recent Activity
-
-To see what you've been working on:
-
-```
-You: "What have we been discussing recently?"
-```
-
-This prompt causes Claude to:
-
-1. Retrieve documents modified in the recent past
-2. Summarize the topics and main points
-3. Offer to continue any of those discussions
-
-### Search
-
-To find specific information:
-
-```
-You: "Find information about pour over coffee methods."
-```
-
-Claude will:
-
-1. Search your knowledge base for relevant documents
-2. Summarize the key findings
-3. Offer to explore specific documents in more detail
-
-See [User Guide - Using Special Prompts](/user-guide#using-special-prompts) for further information.
-
-## Using Your Knowledge Base
-
-### Referencing Knowledge
-
-In future conversations, reference your existing knowledge:
-
-```
-You: "What water temperature did we decide was optimal for coffee brewing?"
-```
-
-Or directly reference notes using memory:// URLs:
-
-```
-You: "Take a look at memory://coffee-brewing-methods and let's discuss how to improve my technique."
-```
-
-### Building On Previous Knowledge
-
-Basic Memory enables continuous knowledge building:
-
-1. **Reference previous discussions** in new conversations
-2. **Edit notes incrementally** without rewriting entire documents
-3. **Move and organize notes** as your knowledge base grows
-4. **Switch between projects** instantly during conversations
-5. **Search by tags** to find related content quickly
-6. **Create connections** between related topics
-7. **Follow relationships** to build comprehensive context
-
-### Workflow Examples
-
-**Incremental Editing:**
-```
-You: "Add a section about espresso to my coffee brewing notes"
-Claude: [Uses edit_note to append new section]
-```
-
-**File Organization:**
-```
-You: "Move my old meeting notes to an archive folder"
-Claude: [Uses move_note with database consistency]
-```
-
-## Importing Existing Conversations
-
-Import your existing AI conversations using the CLI commands:
-
-```bash
-# From Claude
-basic-memory import claude conversations
-
-# From ChatGPT
-basic-memory import chatgpt
-```
-
-After importing, changes sync automatically in real-time. You can see project statistics by running `basic-memory project info`.
-
-## Quick Tips
-
-### General Usage
-- Basic Memory syncs changes in real-time (no manual sync needed)
-- Use special prompts (Continue Conversation, Recent Activity, Search) to start contextual discussions
-- Build connections between notes for a richer knowledge graph
-- Use direct `memory://` URLs with permalinks for precise context
-- Review and edit AI-generated notes for accuracy
-
-## Next Steps
-
-After getting started, explore these areas:
-
-
-
- Comprehensive usage instructions
-
-
- Learn how knowledge is structured
-
-
- Visual knowledge navigation
-
-
- Map concepts visually
-
-
- Command line tools
-
-
-
-### Staying Updated
-
-To update Basic Memory when new versions are released:
-
-```bash
-# Update stable release
-uv tool upgrade basic-memory
-
-# Homebrew
-brew upgrade basic-memory
-```
-
-After updating, restart Claude Desktop for changes to take effect.
-
-
-
-
- Switch between projects during conversations
-
-
- Edit notes incrementally without rewriting
-
-
- Move and organize notes with database consistency
-
-
- Search with frontmatter tag support
-
-
-
-## Troubleshooting Installation
-
-### Fix Path to uv
-
-If you get an error that says `ENOENT` , this most likely means Claude Desktop could not find your `uv` installation. Make sure that you have `uv` installed per the instructions above, then:
-
-**Step 1: Find the absolute path to uvx**
-
-Open Terminal and run:
-
-```bash
-which uvx
-```
-
-This will show you the full path (e.g., `/Users/yourusername/.local/bin/uvx`).
-
-**Step 2: Edit Claude Desktop Configuration**
-
-Edit the Claude Desktop config:
-
-```json
-{
- "mcpServers": {
- "basic-memory": {
- "command": "/Users/yourusername/.local/bin/uvx",
- "args": [
- "basic-memory",
- "mcp"
- ]
- }
- }
-}
-```
-
-Replace `/Users/yourusername/.local/bin/uvx` with the actual path you found in Step 1.
-
-
-If you need to find your username you can type `whoami` in the terminal.
-
-
-**Step 3: Restart Claude Desktop**
-
-Close and reopen Claude Desktop for the changes to take effect.
-
-### Claude Says "No Basic Memory Tools Available"
-
-If Claude cannot find Basic Memory tools:
-
-1. **Check absolute paths**: Ensure you're using complete absolute paths to uvx in the Claude Desktop configuration
-2. **Verify installation**: Run `basic-memory --version` in Terminal to confirm Basic Memory is installed
-3. **Restart applications**: Restart both Terminal and Claude Desktop after making configuration changes
-4. **Check sync status**: You can view the sync status by running `basic-memory status`
-
-### Permission Issues
-
-If you encounter permission errors:
-
-1. Check that Basic Memory has access to create files in your home directory
-2. Ensure Claude Desktop has permission to execute the uvx command
diff --git a/src/pages/guides/cloud-sync.mdx b/src/pages/guides/cloud-sync.mdx
deleted file mode 100644
index 498fa47..0000000
--- a/src/pages/guides/cloud-sync.mdx
+++ /dev/null
@@ -1,777 +0,0 @@
----
-layout: '@/layouts/DocsLayout.astro'
-title: "Cloud Sync Guide"
-description: "Guide to syncing your local Basic Memory projects with Basic Memory Cloud"
----
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step } from '@/components'
-
-The Basic Memory Cloud CLI provides seamless integration between local and cloud knowledge bases using **project-scoped synchronization**. Each project can optionally sync with the cloud, giving you fine-grained control over what syncs and where.
-
-## Overview
-
-The cloud CLI enables you to:
-
-- **Toggle cloud mode** - All regular `bm` commands work with cloud when enabled
-- **Project-scoped sync** - Each project independently manages its sync configuration
-- **Explicit operations** - Sync only what you want, when you want
-- **Bidirectional sync** - Keep local and cloud in sync with rclone bisync
-- **Offline access** - Work locally, sync when ready
-
-## Prerequisites
-
-Before using Basic Memory Cloud sync, you need:
-
-- **Active Subscription**: An active Basic Memory Cloud subscription is required to access cloud features
-- **Subscribe**: Visit [https://basicmemory.com/subscribe](https://basicmemory.com/subscribe) to sign up
-- **Basic Memory CLI**: Cloud sync requires the CLI. See [Local Installation](/getting-started#local-installation) for installation steps.
-
-
-If you attempt to log in without an active subscription, you'll receive a "Subscription Required" error with a link to subscribe.
-
-
-### Why Use Sync?
-
-
-**When to use sync:**
-
-Sync is designed for **hybrid workflows** where you want to edit files locally (in tools like Obsidian or VS Code) while keeping cloud in sync.
-
-**Use sync when:**
-- You want to edit notes locally in your preferred editor
-- You need bidirectional sync (changes flow both ways automatically)
-- You're working with large knowledge bases
-- You want offline access with periodic syncing
-
-**Alternatives to sync:**
-
-If you don't need local editing, you can work directly in the cloud:
-- **Web Editor**: Upload and edit files in the [Basic Memory Cloud web interface](/guides/cloud#web-editor)
-- **MCP Tools Only**: Use AI assistants (Claude, ChatGPT) to manage notes entirely in cloud via MCP tools
-
-Sync is optional - choose the workflow that fits your needs.
-
-
-## Architecture: Project-Scoped Sync
-
-### How It Works
-
-Projects can exist in three states:
-
-1. **Cloud-only** - Project exists on cloud, no local copy
-2. **Cloud + Local (synced)** - Project has a local working directory that syncs
-3. **Local-only** - Project exists locally (when cloud mode is disabled)
-
-**Example:**
-
-```bash
-# You have 3 projects on cloud:
-# - research: wants local sync at ~/Documents/research
-# - work: wants local sync at ~/work-notes
-# - temp: cloud-only, no local sync needed
-
-bm project add research --local-path ~/Documents/research
-bm project add work --local-path ~/work-notes
-bm project add temp # No local sync
-
-# Now you can sync individually (after initial --resync):
-bm project bisync --name research
-bm project bisync --name work
-# temp stays cloud-only
-```
-
-**What happens under the covers:**
-- Config stores `cloud_projects` dict mapping project names to local paths
-- Each project gets its own bisync state in `~/.basic-memory/bisync-state/{project}/`
-- Rclone syncs using single remote: `basic-memory-cloud`
-- Projects can live anywhere on your filesystem, not forced into sync directory
-
-## Quick Start
-
-### 1. Enable Cloud Mode
-
-Authenticate and enable cloud mode:
-
-```bash
-bm cloud login
-```
-
-**What this does:**
-1. Opens browser to Basic Memory Cloud authentication page
-2. Stores authentication token in `~/.basic-memory/auth/token`
-3. **Enables cloud mode** - all CLI commands now work against cloud
-4. Validates your subscription status
-
-**Result:** All `bm project`, `bm tools` commands now work with cloud.
-
-### 2. Set Up Sync
-
-Install rclone and configure credentials:
-
-```bash
-bm cloud setup
-```
-
-**What this does:**
-1. Installs rclone automatically (if needed)
-2. Fetches your tenant information from cloud
-3. Generates scoped S3 credentials for sync
-4. Configures single rclone remote: `basic-memory-cloud`
-
-**Result:** You're ready to sync projects. No sync directories created yet - those come with project setup.
-
-### 3. Add Projects with Sync
-
-Create projects with optional local sync paths:
-
-```bash
-# Create cloud project without local sync
-bm project add research
-
-# Create cloud project WITH local sync
-bm project add research --local-path ~/Documents/research
-
-# Or configure sync for existing project
-bm project sync-setup research ~/Documents/research
-```
-
-**What happens under the covers:**
-
-When you add a project with `--local-path`:
-1. Project created on cloud at `/app/data/research`
-2. Local path stored in config: `cloud_projects.research.local_path = "~/Documents/research"`
-3. Local directory created if it doesn't exist
-4. Bisync state directory created at `~/.basic-memory/bisync-state/research/`
-
-**Result:** Project is ready to sync, but no files synced yet.
-
-### 4. Sync Your Project
-
-Establish the initial sync baseline. **Best practice:** Always preview with `--dry-run` first:
-
-```bash
-# Step 1: Preview the initial sync (recommended)
-bm project bisync --name research --resync --dry-run
-
-# Step 2: If all looks good, run the actual sync
-bm project bisync --name research --resync
-```
-
-**What happens under the covers:**
-1. Rclone reads from `~/Documents/research` (local)
-2. Connects to `basic-memory-cloud:bucket-name/app/data/research` (remote)
-3. Creates bisync state files in `~/.basic-memory/bisync-state/research/`
-4. Syncs files bidirectionally with settings:
- - `conflict_resolve=newer` (most recent wins)
- - `max_delete=25` (safety limit)
- - Respects `.bmignore` patterns
-
-**Result:** Local and cloud are in sync. Baseline established.
-
-
-**Why `--resync`?** This is an rclone requirement for the first bisync run. It establishes the initial state that future syncs will compare against. After the first sync, never use `--resync` unless you need to force a new baseline.
-
-See: [rclone bisync documentation](https://rclone.org/bisync/#resync)
-
-
-### 5. Subsequent Syncs
-
-After the first sync, just run bisync without `--resync`:
-
-```bash
-bm project bisync --name research
-```
-
-**What happens:**
-1. Rclone compares local and cloud states
-2. Syncs changes in both directions
-3. Auto-resolves conflicts (newer file wins)
-4. Basic Memory reindexes all changed files
-5. Updates `last_sync` timestamp in config
-
-**Result:** Changes flow both ways - edit locally or in cloud, both stay in sync.
-
-
-**Reindexing after sync**: Basic Memory automatically reindexes all synced changes to update the knowledge graph. For large changes (many files), this may take a few moments to complete.
-
-
-### 6. Verify Setup
-
-Check status:
-
-```bash
-bm cloud status
-```
-
-You should see:
-- `Mode: Cloud (enabled)`
-- `Cloud instance is healthy`
-- Instructions for project sync commands
-
-## Working with Projects
-
-### Understanding Project Commands
-
-
-**Key concept:** When cloud mode is enabled, use regular `bm project` commands (not `bm cloud project`).
-
-```bash
-# In cloud mode:
-bm project list # Lists cloud projects
-bm project add research # Creates cloud project
-
-# In local mode:
-bm project list # Lists local projects
-bm project add research ~/Documents/research # Creates local project
-```
-
-
-### Creating Projects
-
-**Use case 1: Cloud-only project (no local sync)**
-
-```bash
-bm project add temp-notes
-```
-
-**What this does:**
-- Creates project on cloud at `/app/data/temp-notes`
-- No local directory created
-- No sync configuration
-
-**Result:** Project exists on cloud, accessible via MCP tools, but no local copy.
-
-**Use case 2: Cloud project with local sync**
-
-```bash
-bm project add research --local-path ~/Documents/research
-```
-
-**What this does:**
-- Creates project on cloud at `/app/data/research`
-- Creates local directory `~/Documents/research`
-- Stores sync config in `~/.basic-memory/config.json`
-- Prepares for bisync (but doesn't sync yet)
-
-**Result:** Project ready to sync. Run `bm project bisync --name research --resync` to establish baseline.
-
-**Use case 3: Add sync to existing cloud project**
-
-```bash
-# Project already exists on cloud
-bm project sync-setup research ~/Documents/research
-```
-
-**What this does:**
-- Updates existing project's sync configuration
-- Creates local directory
-- Prepares for bisync
-
-**Result:** Existing cloud project now has local sync path. Run bisync to pull files down.
-
-### Listing Projects
-
-View all projects:
-
-```bash
-bm project list
-```
-
-**What you see:**
-- All projects in cloud (when cloud mode enabled)
-- Default project marked
-- Project paths shown
-
-## File Synchronization
-
-### Understanding the Sync Commands
-
-There are three sync-related commands:
-
-1. **`bm project sync`** - One-way: local → cloud (make cloud match local)
-2. **`bm project bisync`** - Two-way: local ↔ cloud (recommended)
-3. **`bm project check`** - Verify files match (no changes)
-
-### One-Way Sync: Local → Cloud
-
-**Use case:** You made changes locally and want to push to cloud (overwrite cloud).
-
-```bash
-bm project sync --name research
-```
-
-**What happens:**
-1. Reads files from `~/Documents/research` (local)
-2. Uses rclone sync to make cloud identical to local
-3. Respects `.bmignore` patterns
-4. Shows progress bar
-
-**Result:** Cloud now matches local exactly. Any cloud-only changes are overwritten.
-
-**When to use:**
-- You know local is the source of truth
-- You want to force cloud to match local
-- You don't care about cloud changes
-
-### Two-Way Sync: Local ↔ Cloud (Recommended)
-
-**Use case:** You edit files both locally and in cloud UI, want both to stay in sync.
-
-```bash
-# First time - establish baseline
-bm project bisync --name research --resync
-
-# Subsequent syncs
-bm project bisync --name research
-```
-
-**What happens:**
-1. Compares local and cloud states using bisync metadata
-2. Syncs changes in both directions
-3. Auto-resolves conflicts (newer file wins)
-4. Detects excessive deletes and fails safely (max 25 files)
-
-**Conflict resolution example:**
-
-```bash
-# Edit locally
-echo "Local change" > ~/Documents/research/notes.md
-
-# Edit same file in cloud UI
-# Cloud now has: "Cloud change"
-
-# Run bisync
-bm project bisync --name research
-
-# Result: Newer file wins (based on modification time)
-# If cloud was more recent, cloud version kept
-# If local was more recent, local version kept
-```
-
-**When to use:**
-- Default workflow for most users
-- You edit in multiple places
-- You want automatic conflict resolution
-
-### Verify Sync Integrity
-
-**Use case:** Check if local and cloud match without making changes.
-
-```bash
-bm project check --name research
-```
-
-**What happens:**
-1. Compares file checksums between local and cloud
-2. Reports differences
-3. No files transferred
-
-**Result:** Shows which files differ. Run bisync to sync them.
-
-```bash
-# One-way check (faster)
-bm project check --name research --one-way
-```
-
-### Preview Changes (Dry Run)
-
-**Use case:** See what would change without actually syncing.
-
-```bash
-bm project bisync --name research --dry-run
-```
-
-**What happens:**
-1. Runs bisync logic
-2. Shows what would be transferred/deleted
-3. No actual changes made
-
-**Result:** Safe preview of sync operations.
-
-### Advanced: List Remote Files
-
-**Use case:** See what files exist on cloud without syncing.
-
-```bash
-# List all files in project
-bm project ls --name research
-
-# List files in subdirectory
-bm project ls --name research --path subfolder
-```
-
-**What happens:**
-1. Connects to cloud via rclone
-2. Lists files in remote project path
-3. No files transferred
-
-**Result:** See cloud file listing.
-
-## Multiple Projects
-
-### Syncing Multiple Projects
-
-**Use case:** You have several projects with local sync, want to sync all at once.
-
-```bash
-# Setup multiple projects
-bm project add research --local-path ~/Documents/research
-bm project add work --local-path ~/work-notes
-bm project add personal --local-path ~/personal
-
-# Establish baselines
-bm project bisync --name research --resync
-bm project bisync --name work --resync
-bm project bisync --name personal --resync
-
-# Daily workflow: sync everything
-bm project bisync --name research
-bm project bisync --name work
-bm project bisync --name personal
-```
-
-### Mixed Usage
-
-**Use case:** Some projects sync, some stay cloud-only.
-
-```bash
-# Projects with sync
-bm project add research --local-path ~/Documents/research
-bm project add work --local-path ~/work
-
-# Cloud-only projects
-bm project add archive
-bm project add temp-notes
-
-# Sync only the configured ones
-bm project bisync --name research
-bm project bisync --name work
-
-# Archive and temp-notes stay cloud-only
-```
-
-**Result:** Fine-grained control over what syncs.
-
-## Disable Cloud Mode
-
-Return to local mode:
-
-```bash
-bm cloud logout
-```
-
-**What this does:**
-1. Disables cloud mode in config
-2. All commands now work locally
-3. Auth token remains (can re-enable with login)
-
-**Result:** All `bm` commands work with local projects again.
-
-## Filter Configuration
-
-### Understanding .bmignore
-
-**The problem:** You don't want to sync everything (e.g., `.git`, `node_modules`, database files).
-
-**The solution:** `.bmignore` file with gitignore-style patterns.
-
-
-Basic Memory already respects `.gitignore` files in your projects. See [Controlling What Gets Indexed](/user-guide#controlling-what-gets-indexed) for details. Use `.bmignore` when you need a **global ignore list** that applies across all your projects.
-
-
-**Location:** `~/.basic-memory/.bmignore`
-
-**Default patterns:**
-
-```gitignore
-# Version control
-.git/**
-
-# Python
-__pycache__/**
-*.pyc
-.venv/**
-venv/**
-
-# Node.js
-node_modules/**
-
-# Basic Memory internals
-memory.db/**
-memory.db-shm/**
-memory.db-wal/**
-config.json/**
-watch-status.json/**
-.bmignore.rclone/**
-
-# OS files
-.DS_Store/**
-Thumbs.db/**
-
-# Environment files
-.env/**
-.env.local/**
-```
-
-**How it works:**
-1. On first sync, `.bmignore` created with defaults
-2. Patterns converted to rclone filter format (`.bmignore.rclone`)
-3. Rclone uses filters during sync
-4. Same patterns used by all projects
-
-**Customizing:**
-
-```bash
-# Edit patterns
-code ~/.basic-memory/.bmignore
-
-# Add custom patterns
-echo "*.tmp/**" >> ~/.basic-memory/.bmignore
-
-# Next sync uses updated patterns
-bm project bisync --name research
-```
-
-## Troubleshooting
-
-### Authentication Issues
-
-
-
- **Solution:** Re-authenticate:
-
- ```bash
- bm cloud logout
- bm cloud login
- ```
-
-
-
-### Subscription Issues
-
-
-
- **Solution:**
- 1. Visit subscribe URL shown in error
- 2. Sign up for subscription
- 3. Run `bm cloud login` again
-
- **Note:** Access is immediate when subscription becomes active.
-
-
-
-### Bisync Initialization
-
-
-
- **Explanation:** Bisync needs a baseline state before it can sync changes.
-
- **Solution:**
-
- ```bash
- bm project bisync --name research --resync
- ```
-
- **What this does:**
- - Establishes initial sync state
- - Creates baseline in `~/.basic-memory/bisync-state/research/`
- - Syncs all files bidirectionally
-
- **Result:** Future syncs work without `--resync`.
-
-
-
-### Empty Directory Issues
-
-
-
- **Explanation:** Rclone bisync doesn't work well with completely empty directories. It needs at least one file to establish a baseline.
-
- **Solution:** Add at least one file before running `--resync`:
-
- ```bash
- # Create a placeholder file
- echo "# Research Notes" > ~/Documents/research/README.md
-
- # Now run bisync
- bm project bisync --name research --resync
- ```
-
- **Why this happens:** Bisync creates listing files that track the state of each side. When both directories are completely empty, these listing files are considered invalid by rclone.
-
- **Best practice:** Always have at least one file (like a README.md) in your project directory before setting up sync.
-
-
-
-### Bisync State Corruption
-
-
-
- **Explanation:** Sometimes bisync state can become inconsistent (e.g., after mixing dry-run and actual runs, or after manual file operations).
-
- **Solution:** Clear bisync state and re-establish baseline:
-
- ```bash
- # Clear bisync state
- bm project bisync-reset research
-
- # Re-establish baseline
- bm project bisync --name research --resync
- ```
-
- **What this does:**
- - Removes all bisync metadata from `~/.basic-memory/bisync-state/research/`
- - Forces fresh baseline on next `--resync`
- - Safe operation (doesn't touch your files)
-
- **Note:** This command also runs automatically when you remove a project to clean up state directories.
-
-
-
-### Too Many Deletes
-
-
-
- **Explanation:** Bisync detected you're about to delete more than 25 files. This is a safety check to prevent accidents.
-
- **Solution 1:** Review what you're deleting, then force resync:
-
- ```bash
- # Check what would be deleted
- bm project bisync --name research --dry-run
-
- # If correct, establish new baseline
- bm project bisync --name research --resync
- ```
-
- **Solution 2:** Use one-way sync if you know local is correct:
-
- ```bash
- bm project sync --name research
- ```
-
-
-
-### Project Not Configured for Sync
-
-
-
- **Explanation:** Project exists on cloud but has no local sync path.
-
- **Solution:**
-
- ```bash
- bm project sync-setup research ~/Documents/research
- bm project bisync --name research --resync
- ```
-
-
-
-### Connection Issues
-
-
-
- **Solution:** Check status:
-
- ```bash
- bm cloud status
- ```
-
- If instance is down, wait a few minutes and retry.
-
-
-
-## Security
-
-- **Authentication**: OAuth 2.1 with PKCE flow
-- **Tokens**: Stored securely in `~/.basic-memory/basic-memory-cloud.json`
-- **Transport**: All data encrypted in transit (HTTPS)
-- **Credentials**: Scoped S3 credentials (read-write to your tenant only)
-- **Isolation**: Your data isolated from other tenants
-- **Ignore patterns**: Sensitive files automatically excluded via `.bmignore`
-
-## Command Reference
-
-### Cloud Mode Management
-
-```bash
-bm cloud login # Authenticate and enable cloud mode
-bm cloud logout # Disable cloud mode
-bm cloud status # Check cloud mode and instance health
-```
-
-### Setup
-
-```bash
-bm cloud setup # Install rclone and configure credentials
-```
-
-### Project Management
-
-When cloud mode is enabled:
-
-```bash
-bm project list # List cloud projects
-bm project add # Create cloud project (no sync)
-bm project add --local-path # Create with local sync
-bm project sync-setup # Add sync to existing project
-bm project rm # Delete project
-```
-
-### File Synchronization
-
-```bash
-# One-way sync (local → cloud)
-bm project sync --name
-bm project sync --name --dry-run
-bm project sync --name --verbose
-
-# Two-way sync (local ↔ cloud) - Recommended
-bm project bisync --name # After first --resync
-bm project bisync --name --resync # First time / force baseline
-bm project bisync --name --dry-run
-bm project bisync --name --verbose
-
-# Integrity check
-bm project check --name
-bm project check --name --one-way
-
-# List remote files
-bm project ls --name
-bm project ls --name --path
-```
-
-## Summary
-
-**Basic Memory Cloud uses project-scoped sync:**
-
-1. **Enable cloud mode** - `bm cloud login`
-2. **Install rclone** - `bm cloud setup`
-3. **Add projects with sync** - `bm project add research --local-path ~/Documents/research`
-4. **Preview first sync** - `bm project bisync --name research --resync --dry-run`
-5. **Establish baseline** - `bm project bisync --name research --resync`
-6. **Daily workflow** - `bm project bisync --name research`
-
-**Key benefits:**
-- ✅ Each project independently syncs (or doesn't)
-- ✅ Projects can live anywhere on disk
-- ✅ Explicit sync operations (no magic)
-- ✅ Safe by design (max delete limits, conflict resolution)
-- ✅ Full offline access (work locally, sync when ready)
-
-## Next Steps
-
-
-
- Learn about Basic Memory Cloud features and setup
-
-
- Complete CLI command reference
-
-
- Use cloud sync with Obsidian
-
-
- Use cloud sync with VS Code
-
-
diff --git a/src/pages/guides/cloud.mdx b/src/pages/guides/cloud.mdx
deleted file mode 100644
index 79615a2..0000000
--- a/src/pages/guides/cloud.mdx
+++ /dev/null
@@ -1,536 +0,0 @@
----
-layout: '@/layouts/DocsLayout.astro'
-title: 'Basic Memory Cloud'
-description: 'Cloud remote MCP setup and command line tools for Basic Memory Cloud'
-icon: 'cloud'
----
-
-import {
- Card,
- CardGroup,
- Info,
- Warning,
- Note,
- Tip,
- Accordion,
- AccordionItem,
- Steps,
- Step,
- CodeGroup,
- CodeTab
-} from '@/components'
-
-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.
-
-
-**Why use Basic Memory Cloud?**
-- Access from any device
-- Easily import your data
-- 2-minute setup
-- Local sync optional
-- OAuth authentication
-
-
-## Setup with Claude
-
-Basic Memory Cloud uses Remote MCP to connect to AI assistants. The connection URL is:
-```
-https://cloud.basicmemory.com/mcp
-```
-
-
-
- In Claude Web or Desktop, go to **Settings → Claude → Connectors**
-
- 
-
-
-
- Click **Add custom connector**
-
- 
-
- Enter the following details:
- - **Name**: Basic Memory
- - **Remote MCP server URL**: `https://cloud.basicmemory.com/mcp`
-
- Click **Add**
-
-
-
- Click **Connect** to authenticate and grant permissions to Claude
-
- This will open an OAuth flow to authorize Claude to access your Basic Memory Cloud account.
-
-
-
- Click **Configure** to customize which tools are enabled
-
- 
-
- You can enable or disable specific tools and configure permissions.
-
- 
-
-
-
- Confirm Basic Memory is available in the "search and tools" menu for a chat
-
- 
-
- All your notes will be saved to your cloud instance.
-
-
-
-
-For detailed Claude setup instructions, see the [Claude Desktop Integration](/integrations/claude-desktop) guide.
-
-
-## Setup with ChatGPT
-
-
-ChatGPT requires a **Pro or Max subscription** to use Remote MCP servers.
-
-
-A complete setup walkthrough is shown in the following video:
-
-
-
-
-
-
-For detailed ChatGPT setup instructions, see the [ChatGPT Integration](/integrations/chatgpt) guide.
-
-
----
-
-## Web Editor
-
-Edit and manage your cloud notes directly in your browser at [app.basicmemory.com/notes](https://app.basicmemory.com/notes).
-
-### Features
-
-
-
- Browse and edit all your notes with a rich markdown editor
-
-
- Import your ChatGPT, Claude, or JSON data directly in the browser
-
-
- Create, switch between, and manage multiple projects
-
-
- Bulk upload markdown files and directories
-
-
- Export projects as zip files for backup
-
-
-
-### Using the Web Editor
-
-
-
- Navigate to [app.basicmemory.com/notes](https://app.basicmemory.com/notes)
-
- 
-
- View and edit your notes with full markdown support.
-
-
-
- Use the Project dropdown in the upper left corner to switch between projects
-
- 
-
-
-
- Click on "Manage Projects" to access project management features
-
- 
-
- Click the "more" button (...) on any project to:
- - Upload notes (files or folders)
- - Download project as zip
- - Delete project and its notes
-
-
-
-### Import Data
-
-Import conversations and data from Claude, ChatGPT, or Basic Memory JSON files directly via the web interface.
-
-
-
- In the web app, navigate to **Settings → Import Data**
-
-
- 
-
-
-
-
- Choose the type of data to import:
- - **Claude Conversations** (conversations.json)
- - **ChatGPT Conversations** (export JSON)
- - **Memory JSON** (entities & relations)
-
-
-
- Select which project to import into, or leave empty to use the default project
-
-
-
- Specify the folder within the project to store imported files (default: `imports`)
-
-
-
- Click to upload or drag and drop your JSON file, then click **Start Import**
-
-
-
-
-The import feature supports the same formats as the CLI import command. All imported conversations are converted to Basic Memory's markdown knowledge format.
-
-
----
-
-## Command Line Tools
-
-The CLI tools are **optional** but enable advanced features like project management, file upload, and bidirectional sync.
-
-**Requirements**: Basic Memory CLI v0.16.0 or later. See install and upgrade instructions on the [Getting Started](/getting-started) page.
-
-
-**Why use the CLI?**
-- Manage multiple projects from terminal
-- Upload entire folders to cloud
-- Set up bidirectional sync with local files
-- Automate workflows with scripts
-
-
-
-
- ```bash
- bm cloud login
- ```
- Opens browser for OAuth 2.1 authentication, then displays an authorization code.
-
-
-
-
-
- ```bash
- bm cloud status
- ```
- View your authentication status, subscription, and cloud project information.
-
-
-
- ```bash
- bm project list
- ```
- Shows all your cloud projects with their paths and default status.
-
-
-
-### Authentication
-
-Basic Memory uses JWT-based cloud authentication with OAuth 2.1 and automatic subscription validation.
-
-### Login to Cloud
-
-Authenticate with Basic Memory Cloud:
-
-```bash
-bm cloud login
-```
-
-**What happens:**
-1. Opens browser to OAuth authorization page
-2. Handles PKCE challenge/response automatically
-3. Validates active subscription status
-4. Stores JWT token in `~/.basic-memory/basic-memory-cloud.json`
-5. Token automatically refreshed when needed
-
-**Browser Confirmation Code**
-
-
-**Terminal**
-
-In the terminal, the same code will be displayed. Confirm the codes match and press the **Confirm** button
-on the web page.
-
-```
- bm cloud login
-Initiating authentication...
-
-🔐 Authentication Required
-
-To authenticate, please visit:
-https://eloquent-lotus-05.authkit.app/device
-
-And enter this code: XXX-XXX
-
-Or for one-click access, visit:
-https://eloquent-lotus-05.authkit.app/device?user_code=XXX-XXX
-
-Opening browser automatically...
-
-Waiting for you to complete authentication in your browser...
-```
-
-After you login and confirm via the web browser, your auth token will be saved locally.
-```
-✅ Successfully authenticated with Basic Memory Cloud!
-Verifying subscription access...
-✓ Cloud mode enabled
-All CLI commands now work against https://cloud.basicmemory.com
-✓ Tokens saved to ~/.basic-memory/basic-memory-cloud.json
-```
-
-
- **Important:** After `bm cloud login`, CLI tools access cloud endpoints instead of local MCP. Commands like `bm
- project list` show cloud projects, and `bm tool [name]` invokes tools in the cloud. Use the same CLI commands for
- both local and cloud projects.
-
-
-**If no subscription:**
-```
-Active subscription required
-Subscribe at: https://basicmemory.com/subscribe
-```
-
-### Check Authentication Status
-
-View current authentication and cloud status:
-
-```bash
-bm cloud status
-```
-
-**Output shows:**
-- Authentication status (logged in/out)
-- Subscription status (active/expired)
-- Last sync time
-- Cloud project count
-- Tenant information
-- Sync directory configuration
-
-### Logout
-
-Clear authentication session:
-
-```bash
-bm cloud logout
-```
-
-Removes `~/.basic-memory/basic-memory-cloud.json` and clears cached credentials. All cloud commands will require re-authentication.
-
-### Project Management
-
-Create and manage projects from the command line:
-
-```bash
-# Create a new cloud project
-bm project add my-new-project
-
-# Create and set as default
-bm project add my-new-project --default
-
-# List all cloud projects
-bm project list
-```
-
-Example output:
-
-```
- Basic Memory Projects
-┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
-┃ Name ┃ Path ┃ Default ┃
-┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
-│ main │ /app/data/basic-memory │ ✓ │
-└──────┴────────────────────────┴─────────┘
-```
-
-
-For more project management commands, see `bm project --help` or the [CLI Reference](/guides/cli-reference).
-
-
-## Upload files to Cloud Projects
-
-You can directly upload local files or directories to cloud projects using `bm cloud upload`. This is useful for:
-- Migrating existing local projects to the cloud
-- Quickly uploading specific files or directories
-- One-time bulk uploads without setting up sync
-
-**Basic Usage:**
-
-```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
-```
-
-**Create Project On-the-Fly:**
-
-If the target project doesn't exist yet, use `--create-project`:
-
-```bash
-# Upload and create project in one step
-bm cloud upload ~/local-project --project new-research --create-project
-```
-
-**Skip Automatic Sync:**
-
-By default, the command syncs the project after upload to index the files. To skip this:
-
-```bash
-# 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`)
-
-To customize what gets uploaded, edit `~/.basic-memory/.bmignore`.
-
-**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
-```
-
-**Example Output:**
-
-```
-bm cloud upload --project specs --create-project specs
-Creating cloud project 'specs'...
-✓ Created project 'specs'
-Uploading /Users/phernandez/dev/basicmachines/basic-memory/specs to project 'specs'...
-Found 21 file(s) to upload
-Uploading SPEC-8 TigrisFS Integration.md (1/21)
-Uploading SPEC-14 Cloud Git Versioning & GitHub Backup.md (2/21)
-Uploading SPEC-9 Signed Header Tenant Information.md (3/21)
-Uploading SPEC-12 OpenTelemetry Observability.md (4/21)
-Uploading SPEC-15 Configuration Persistence via Tigris for Cloud Tenants.md (5/21)
-Uploading SPEC-3 Agent Definitions.md (6/21)
-Uploading SPEC-9 Multi-Project Bidirectional Sync Architecture.md (7/21)
-Uploading SPEC-5 CLI Cloud Upload via WebDAV.md (8/21)
-Uploading SPEC-13 CLI Authentication with Subscription Validation.md (9/21)
-Uploading SPEC-17 Semantic Search with ChromaDB.md (10/21)
-Uploading SPEC-14- Cloud Git Versioning & GitHub Backup.md (11/21)
-Uploading SPEC-9-1 Follow-Ups- Conflict, Sync, and Observability.md (12/21)
-Uploading SPEC-10 Unified Deployment Workflow and Event Tracking.md (13/21)
-Uploading SPEC-4 Notes Web UI Component Architecture.md (14/21)
-Uploading SPEC-7 POC to spike Tigris Turso for local access to cloud data.md (15/21)
-Uploading SPEC-2 Slash Commands Reference.md (16/21)
-Uploading SPEC-18 AI Memory Management Tool.md (17/21)
-Uploading SPEC-1 Specification-Driven Development Process.md (18/21)
-Uploading SPEC-11 Basic Memory API Performance Optimization.md (19/21)
-Uploading SPEC-6 Explicit Project Parameter Architecture.md (20/21)
-Uploading SPEC-16 MCP Cloud Service Consolidation.md (21/21)
-✓ Upload complete: 21 file(s) (363.9 KB)
-✅ Successfully uploaded to 'specs'
-Syncing project 'specs'...
-✓ Filesystem sync initiated for project 'specs'
-```
-
-After sync completes, the notes are available in the [Notes Web Editor](https://app.basicmemory.com) and for AI conversations.
-
-
-
-
-For bidirectional sync (editing both locally and in cloud), see the [Cloud Sync Guide](/guides/cloud-sync).
-
-
----
-
-## Migrating to Cloud
-
-Already using Basic Memory locally? You have two options to move your notes to the cloud:
-
-### Option 1: One-Time Upload (Fastest)
-
-Upload your existing local project to cloud:
-
-```bash
-# Login first
-bm cloud login
-
-# Upload entire project
-bm cloud upload ~/basic-memory --project main --create-project
-```
-
-**Use when:**
-- You want to move to cloud-only
-- One-time migration is sufficient
-- Don't need ongoing local-cloud sync
-
-### Option 2: Bidirectional Sync (Hybrid Workflow)
-
-Set up sync to work both locally and in cloud:
-
-```bash
-# Login and setup sync
-bm cloud login
-bm cloud setup
-
-# Add existing project with sync enabled
-bm project add main --local-path ~/basic-memory
-
-# Initial sync (resync creates baseline)
-bm project bisync --name main --resync --dry-run # preview first
-bm project bisync --name main --resync # establish baseline
-
-# Ongoing sync (run after local or cloud changes)
-bm project bisync --name main
-```
-
-**Use when:**
-- You want to edit both locally (Obsidian, VS Code) and in cloud
-- Need offline access
-- Want automatic bidirectional sync
-
-
-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](/guides/cloud-sync) for detailed sync configuration.
-
-
-## Next Steps
-
-
-
- Set up bidirectional sync for local editing
-
-
- Complete CLI command reference
-
-
- Initial setup and configuration
-
-
- All available MCP tools and workflows
-
-
diff --git a/src/pages/guides/knowledge-format.mdx b/src/pages/guides/knowledge-format.mdx
deleted file mode 100644
index a7d0e20..0000000
--- a/src/pages/guides/knowledge-format.mdx
+++ /dev/null
@@ -1,222 +0,0 @@
----
-layout: '@/layouts/DocsLayout.astro'
-title: 'Knowledge Format'
-description: "Learn Basic Memory's knowledge format using standard Markdown with semantic patterns to create a knowledge graph"
----
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step, CodeGroup, CodeTab } from '@/components'
-
-Understanding how Basic Memory structures knowledge will help you create richer, more connected notes. Here's how the semantic patterns work.
-
-
-Using Basic Memory Cloud? The knowledge format works exactly the same - create notes through AI conversations or edit directly in the [Web Editor](/guides/cloud#web-editor).
-
-
-## File-First Architecture
-
-All knowledge in Basic Memory is stored in plain text Markdown files:
-
-
- - Files are the source of truth for all knowledge in Basic Memory
- - Changes to files automatically update the knowledge graph in the db
- - You maintain complete ownership and control
- - Files work with git and other version control systems
- - Knowledge persists independently of any AI conversation
-
-
-## Core Document Structure
-
-Every document uses this basic structure:
-
-```markdown
----
-title: Document Title
-type: note
-tags: [tag1, tag2]
-permalink: custom-path
----
-
-# Document Title
-Regular markdown content...
-
-## Observations
-- [category] Content with #tags (optional context)
-
-## Relations
-- relation_type [[Other Document]] (optional context)
-```
-
-### Frontmatter
-
-The YAML frontmatter at the top of each file defines essential metadata:
-
-```yaml
----
-title: Document Title # Used for linking and references
-type: note # Document type
-tags: [tag1, tag2] # For organization and searching
-permalink: custom-link # Optional custom URL path
----
-```
-
-
- The title is particularly important as it's used to create links between documents.
-
-
-### Observations
-
-Observations are facts or statements about a topic:
-
-```markdown
-- [tech] Uses SQLite for storage #database
-- [design] Follows plaint-text architecture #architecture
-- [decision] Selected bcrypt for passwords #security (Based on audit)
-```
-
- Observations are markdown list items beginning a `[category]` value. Basic Memory knows to not make Markdown lists:
- `[ ]` or `[x]`
- into observations.
-
-
-
-Each observation contains:
-- **Category** in [brackets] - classifies the information type
-- **Content text** - the main information
-- Optional **#tags** - additional categorization
-- Optional **(context)** - supporting details
-
-
-
- - `[tech]`: Technical details
- - `[design]`: Architecture decisions
- - `[feature]`: User capabilities
- - `[decision]`: Choices that were made
-
-
- - `[principle]`: Fundamental concepts
- - `[method]`: Approaches or techniques
- - `[preference]`: Personal opinions
-
-
-
-### Relations
-
-Relations connect documents to form the knowledge graph:
-
-```markdown
-- implements [[Search Design]]
-- depends_on [[Database Schema]]
-- relates_to [[User Interface]]
-```
-
-
- Relations are markdown list items beginning a descriptive word, followed by a `[[wiki link]]` value. The description
- will by used as the relationship type.
-
-
-You can also create inline references:
-```markdown
-This builds on [[Core Design]] and uses [[Utility Functions]].
-```
-
-Common relation types include:
-- `implements`: Implementation of a specification
-- `depends_on`: Required dependency
-- `relates_to`: General connection
-- `inspired_by`: Source of ideas
-- `extends`: Enhancement
-- `part_of`: Component relationship
-- `contains`: Hierarchical relationship
-- `pairs_with`: Complementary relationship
-
-## Knowledge Graph
-
-Basic Memory automatically builds a knowledge graph from your document connections:
-
-- Each document becomes a node in the graph
-- Relations create edges between nodes
-- Relation types add semantic meaning to connections
-- Forward references can link to documents that don't exist yet
-
-This graph enables rich context building and navigation across your knowledge base.
-
-## Permalinks and memory:// URLs
-
-Every document in Basic Memory has a unique **permalink** that serves as its stable identifier:
-
-### How Permalinks Work
-
-
- - **Automatically assigned**: The system generates a permalink for each document
- - **Based on title**: By default, derived from the document title
- - **Always unique**: If conflicts exist, the system adds a suffix to ensure uniqueness
- - **Stable reference**: Remains the same even if the file moves in the directory structure
- - **Used in memory:// URLs**: Forms the basis of the memory:// addressing scheme
-
-
-You can specify a custom permalink in the frontmatter:
-```yaml
----
-title: Authentication Approaches
-permalink: auth-approaches-2024
----
-```
-
-If not specified, one will be generated automatically from the title, if the note has has a frontmatter section.
-
-By default a notes' permalink value will not change if the file is moved. It's a **stable** identifier. But if you'd rather permalinks are always updated when a file moves, you can set the config setting in the global config.
-
-The config file for Basic Memory is in the home directory under `.basic-memory/config.json`.
-
-To change the behavior, set the following value:
-```json
-~/.basic-memory/config.json
-{
- "update_permalinks_on_move": true
-}
-```
-
-### Using memory:// URLs
-
-The memory:// URL scheme provides a reliable way to reference knowledge:
-
-```
-memory://auth-approaches-2024 # Direct access by permalink
-memory://Authentication Approaches # Access by title (automatically resolves)
-memory://project/auth-approaches # Access by path
-```
-
-Memory URLs support pattern matching for more powerful queries:
-
-```
-memory://auth* # All documents with permalinks starting with "auth"
-memory://*/approaches # All documents with permalinks ending with "approaches"
-memory://project/*/requirements # All requirements documents in the project folder
-memory://docs/search/implements/* # Follow all implements relations from search docs
-```
-
-This addressing scheme ensures content remains accessible even as your knowledge base evolves and files are reorganized.
-
-## File Organization
-
-Organize files in any structure that suits your needs:
-
-```
-docs/
- architecture/
- design.md
- patterns.md
- features/
- search.md
- auth.md
-```
-
-You can:
-- Group by topic in folders
-- Use a flat structure with descriptive filenames
-- Tag files for easier discovery
-- Add custom metadata in frontmatter
-
-
- The system will build the semantic knowledge graph regardless of how you organize your files.
-
diff --git a/src/pages/guides/mcp-tools-reference.mdx b/src/pages/guides/mcp-tools-reference.mdx
deleted file mode 100644
index 3999dd2..0000000
--- a/src/pages/guides/mcp-tools-reference.mdx
+++ /dev/null
@@ -1,513 +0,0 @@
----
-layout: '@/layouts/DocsLayout.astro'
-title: 'MCP Tools Reference'
-description: 'Complete reference of all Basic Memory MCP tools and prompts available to AI assistants'
----
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step, CodeGroup, CodeTab } from '@/components'
-
-Basic Memory provides a comprehensive suite of MCP (Model Context Protocol) tools and prompts that enable AI assistants to work directly with your knowledge base. This reference catalogs all available tools and where to find detailed examples.
-
-
-Using Basic Memory Cloud? All MCP tools work the same whether you're using cloud or local. Cloud users authenticate via OAuth and tools automatically work with your cloud projects. See the [Cloud Guide](/guides/cloud) for setup.
-
-
-
-**v0.15.0 Change**: Most MCP tools now require an explicit `project` parameter to specify which knowledge base to operate on. You can enable `default_project_mode` in your configuration for automatic project selection, or use the `--project` flag when starting the MCP server to constrain operations to a specific project. See [What's New](/whats-new#explicit-project-parameters) for migration details.
-
-
-## MCP Tools
-
-### Knowledge Management Tools
-
-
-
- **Create or update notes**
- - Parameters: title, content, folder, tags, project
- - Creates semantic observations and relations
- - [Detailed examples →](/how-to/note-taking#human-captures-ai-enhances)
-
-
- **Read existing notes with context**
- - Parameters: identifier, project, page, page_size
- - Loads note content and related knowledge
- - [Detailed examples →](/how-to/research-learning#knowledge-architecture-patterns)
-
-
- **Edit notes incrementally**
- - Parameters: identifier, operation, content, project
- - Operations: append, prepend, find_replace, replace_section
- - Preserves existing content structure
- - [Detailed examples →](/whats-new#advanced-note-editing)
-
-
- **Display notes as formatted artifacts**
- - Parameters: identifier, project
- - Shows notes with proper formatting in Claude Desktop
- - Enhanced readability and navigation
- - [Detailed examples →](/whats-new#view-notes-as-formatted-artifacts)
-
-
- **Remove notes from knowledge base**
- - Parameters: identifier, project
- - Removes from database and file system
- - Updates search index and relations
-
-
- **Move and rename notes**
- - Parameters: identifier, new_path, project
- - Maintains database consistency
- - Updates search index
- - [Detailed examples →](/whats-new#smart-file-management)
-
-
-
-### Search and Discovery Tools
-
-
-
- **Full-text search across knowledge**
- - Parameters: query, project, page, page_size, after_date
- - Searches content, titles, and frontmatter tags
- - [Detailed examples →](/how-to/research-learning#multi-source-synthesis)
-
-
- **Show recently modified content**
- - Parameters: project (optional), timeframe, type, depth
- - Discovery mode: omit project to see cross-project activity
- - Natural language timeframes ("2 days ago", "last week")
- - [Detailed examples →](/how-to/personal-knowledge#daily-and-weekly-reflection-systems)
-
-
- **Load context from memory:// URLs**
- - Parameters: uri, project, depth
- - Navigate knowledge graph relationships
- - Build conversation context from previous work
- - [Detailed examples →](/how-to/note-taking#context-aware-note-creation)
-
-
- **Browse knowledge base structure**
- - Parameters: dir_name, project, depth, file_name_glob
- - Explore folder organization
- - Filter by file patterns
-
-
-
-### Project Management Tools
-
-## Project Modes
-
-Basic Memory supports three different project modes to accommodate different workflows:
-
-### Multi-Project Mode (Default)
-
-The standard mode for users with multiple knowledge bases:
-
-- **How it works**: AI assistants discover projects using `list_memory_projects()` and `recent_activity()`
-- **Project selection**: Users specify which project to work with during conversations
-- **Benefits**: Full flexibility to work across multiple projects in one session
-- **Best for**: Users managing separate work, personal, and research knowledge bases
-
-**Example workflow:**
-```
-Assistant: I'll check what projects you have available.
-[Calls list_memory_projects()]
-
-Assistant: I see you have 'work', 'personal', and 'research' projects. Which would you like to use?
-
-User: Let's work with the research project
-
-Assistant: Perfect! I'll use the 'research' project for our work.
-[Uses project="research" in all subsequent tool calls]
-```
-
-### Default Project Mode
-
-**For single-project users who want automatic project selection:**
-
-Enable in `~/.basic-memory/config.json`:
-```json
-{
- "default_project_mode": true,
- "default_project": "main"
-}
-```
-
-**Behavior:**
-- Tools automatically use your default project when no `project` parameter is specified
-- You **can still override** by explicitly passing a different project to tools
-- Best for users who primarily work in one project but occasionally need others
-
-**Example:**
-```
-# With default_project_mode enabled and default_project="main"
-write_note("My Note", "Content", "folder") # Uses "main" project
-write_note("Work Note", "Content", "folder", project="work") # Uses "work" project
-```
-
-### Single Project Mode
-
-**For locked, single-project sessions:**
-
-Start MCP server with `--project` flag:
-```bash
-basic-memory mcp --project work
-```
-
-**Behavior:**
-- **Locks** the entire MCP session to one project
-- The `project` parameter in tool calls is **ignored** - cannot switch projects
-- Best for automation, focused sessions, or restricted access scenarios
-
-**Example:**
-```bash
-# Start locked to "work" project
-basic-memory mcp --project work
-
-# All operations use "work" regardless of parameters
-write_note("My Note", "Content", "folder") # Uses "work"
-write_note("Note", "Content", "folder", project="personal") # Still uses "work"!
-```
-
-### Project Resolution Hierarchy
-
-When multiple project specifications exist, Basic Memory uses this priority order:
-
-1. **Single Project Mode** (highest priority) - `--project` CLI parameter or `BASIC_MEMORY_MCP_PROJECT` env var
-2. **Explicit Parameter** (medium priority) - `project` parameter in tool call
-3. **Default Project Mode** (lowest priority) - Automatic default when `default_project_mode=true`
-
-**Quick Comparison:**
-
-| Mode | Can Switch Projects? | Use Case |
-|------|---------------------|----------|
-| Multi-Project (default) | Yes, via explicit parameters | Managing multiple knowledge bases |
-| Default Project Mode | Yes, can override default | Single project with occasional multi-project |
-| Single Project Mode | No, locked to one | Automation, security, focused sessions |
-
-
-
- **Show all available projects**
- - Displays project status and statistics
- - Provides session guidance for project selection
- - Use at conversation start when project is unknown
- - [Detailed examples →](/whats-new#multi-project-management)
-
-
- **Create new knowledge projects**
- - Parameters: project_name, project_path, set_default
- - Initialize new knowledge bases
- - Set up folder structures
-
-
- **Remove projects from configuration**
- - Parameters: project_name
- - Removes from Basic Memory configuration
- - Does not delete actual files
- - Clean up unused project references
-
-
- **Check file synchronization status**
- - No parameters required (shows all projects)
- - Show sync progress and background operations
- - Identify any sync issues or conflicts
- - [Detailed examples →](/whats-new#automatic-migration)
-
-
-
-
-**Deprecated in v0.15.0**: `switch_project()` and `get_current_project()` have been removed. Projects are now specified explicitly via the `project` parameter in each tool call, or automatically resolved using `default_project_mode`. See [What's New](/whats-new#explicit-project-parameters) for details.
-
-
-### Utility Tools
-
-
-
- **Read raw file content**
- - Parameters: file_path, project
- - Access files without knowledge graph processing
- - Support for text, images, and binary files
- - Direct file system access
-
-
- **Create Obsidian canvas visualizations**
- - Parameters: nodes, edges, title, folder, project
- - Generate knowledge graph visualizations
- - [Detailed examples →](/guides/canvas)
-
-
-
-### ChatGPT-Specific Tools
-
-
-Basic Memory provides ChatGPT-compatible tools (`search` and `fetch`) that use OpenAI's expected response format. These are automatically available when using Basic Memory with ChatGPT. For details, see the [ChatGPT Integration Guide](/integrations/chatgpt).
-
-
-## MCP Prompts
-
-Basic Memory includes specialized prompts that provide enhanced AI interactions with formatted responses and guided workflows.
-
-### Interactive Prompts
-
-
-
- **Comprehensive usage guide for AI assistants**
- - Best practices for using Basic Memory tools
- - Workflow recommendations and patterns
- - [View guide →](/guides/ai-assistant-guide)
-
-
- **Load context for conversation continuity**
- - Parameters: topic, timeframe
- - Intelligent context loading from knowledge base
- - Natural conversation resumption
-
-
- **Enhanced search with formatted results**
- - Parameters: query, after_date
- - Structured search results with context
- - Better than raw search tool for conversations
-
-
- **Formatted recent activity display**
- - Parameters: timeframe
- - Clean presentation of recent changes
- - Contextual information for follow-up
-
-
- **Detailed sync status information**
- - Comprehensive sync progress reporting
- - Background operation status
- - Troubleshooting guidance
-
-
-
-## Tool Usage Patterns
-
-### Common Workflows
-
-**Knowledge Creation Flow:**
-```
-write_note → edit_note (append/prepend) → move_note → view_note
-```
-*Start with basic note, enhance incrementally, organize, then review*
-
-
-Example conversation
-
-```
-You: "I want to document my thoughts on the new API design"
-Claude: I'll create a note for your API design thoughts.
-[Uses write_note to create initial note]
-
-You: "Add a section about authentication concerns"
-Claude: I'll append an authentication section to your API design note.
-[Uses edit_note with append operation]
-
-You: "This should go in my architecture folder"
-Claude: I'll move the API design note to your architecture folder.
-[Uses move_note to relocate the file]
-
-You: "Show me the final note"
-Claude: Here's your complete API design note formatted for easy reading.
-[Uses view_note to display formatted artifact]
-```
-
-
-**Research and Discovery Flow:**
-```
-search_notes → read_note → build_context → write_note
-```
-*Find existing knowledge, explore context, create new insights*
-
-
-Example conversation
-
-```
-You: "I'm working on database optimization, what have I learned before?"
-Claude: Let me search your knowledge base for database optimization content.
-[Uses search_notes to find relevant notes]
-
-You: "Tell me more about that PostgreSQL indexing note"
-Claude: I'll read the full PostgreSQL indexing note for you.
-[Uses read_note to load complete content and context]
-
-You: "Load the context from my database performance work"
-Claude: I'll gather related notes about database performance to build context.
-[Uses build_context with memory:// URLs to load related content]
-
-You: "Create a new note combining these insights for my current project"
-Claude: I'll create a comprehensive note that synthesizes your database optimization knowledge.
-[Uses write_note to capture new insights with full context]
-```
-
-
-**Project Discovery Flow:**
-```
-list_memory_projects → recent_activity (discovery mode) → project selection
-```
-*Discover projects, view cross-project activity, choose working project*
-
-
-Example conversation
-
-```
-You: "What projects do I have available?"
-Claude: Here are all your Basic Memory projects with their current status.
-[Uses list_memory_projects to show available projects]
-
-You: "Show me recent activity across all projects"
-Claude: Here's recent activity across all your projects to help you choose which to work with.
-[Uses recent_activity without project parameter for discovery mode]
-
-You: "I want to work with my research project"
-Claude: I'll use the 'research' project for our work. All subsequent operations will specify this project.
-[Remembers project choice for conversation context]
-
-You: "What have I been working on recently in this project?"
-Claude: Here's your recent activity in the research project.
-[Uses recent_activity with project="research" parameter]
-```
-
-
-**Content Organization Flow:**
-```
-list_directory → search_notes → move_note → list_directory
-```
-*Explore structure, find content, reorganize, verify changes*
-
-
-Example conversation
-
-```
-You: "Show me what's in my projects folder"
-Claude: Here's the structure of your projects folder.
-[Uses list_directory to explore folder contents]
-
-You: "Find all notes about the mobile app project"
-Claude: I found several notes related to your mobile app project.
-[Uses search_notes to locate relevant content]
-
-You: "Move the mobile app notes to a dedicated folder"
-Claude: I'll move all mobile app notes to a new 'mobile-app' folder.
-[Uses move_note to reorganize content]
-
-You: "Show me the updated folder structure"
-Claude: Here's your reorganized projects folder with the new mobile-app directory.
-[Uses list_directory to verify the changes]
-```
-
-
-### Integration Examples
-
-**In Claude Desktop:**
-```
-You: "What have I been working on lately?"
-Claude: [Uses recent_activity prompt for formatted response]
-
-You: "Create a note about today's meeting"
-Claude: [Uses write_note tool with semantic structure]
-
-You: "Show me my project documentation as a formatted view"
-Claude: [Uses view_note tool to display artifact]
-```
-
-**In Development Workflows:**
-```
-You: "Document today's architecture decisions in my work project"
-Claude: [Uses write_note with project="work" parameter and technical context]
-
-You: "Find all my API documentation in the work project and update the authentication section"
-Claude: [Uses search_notes with project="work", then edit_note with section replacement]
-```
-
-## Error Handling and Best Practices
-
-### Common Tool Parameters
-
-**Identifiers**: Most tools accept flexible identifiers:
-- Note titles: `"My Important Note"`
-- Permalinks: `"my-important-note"`
-- Memory URLs: `"memory://folder/note"`
-- File paths: `"folder/note.md"`
-
-**Timeframes**: Natural language supported:
-- `"2 days ago"`, `"last week"`, `"today"`
-- `"3 months ago"`, `"yesterday"`
-- Standard formats: `"7d"`, `"24h"`
-
-**Project Parameters**: Most content tools require project specification:
-- Specify which project to operate on: `project="work-docs"`
-- Optional if `default_project_mode: true` in configuration
-- Automatically resolved in constrained mode (`--project` flag)
-- `recent_activity()` supports discovery mode (no project = cross-project view)
-
-## Advanced Features
-
-### Memory URLs
-
-Use `memory://` URLs with `build_context` for intelligent navigation:
-
-```
-memory://project-planning # Load specific note
-memory://architecture/* # Load all architecture notes
-memory://decisions/database-choice # Load specific decision document
-```
-
-### Project Management vs Content Tools
-
-Basic Memory tools fall into two categories:
-
-**Project Management Tools** (work globally, no project parameter):
-- `list_memory_projects()` - Shows all projects
-- `create_memory_project(project_name, project_path)` - Creates new project
-- `delete_project(project_name)` - Removes project configuration
-- `sync_status()` - Shows status across all projects
-
-**Content Tools** (require project parameter):
-- `write_note(title, content, folder, project="...")` - Creates note in specified project
-- `search_notes(query, project="...")` - Searches specified project only
-- `edit_note(identifier, operation, content, project="...")` - Edits note in specified project
-- `read_note(identifier, project="...")` - Reads note from specified project
-- `recent_activity(project="...")` - Project-specific activity (or omit for discovery mode)
-
-**Example:**
-```python
-# Global operations (no project parameter)
-list_memory_projects() # Shows all projects
-create_memory_project("new-project", "~/Documents") # Creates new project
-
-# Project-specific operations (project parameter required)
-write_note("My Note", "Content", "folder", project="work")
-search_notes("api documentation", project="work")
-edit_note("My Note", "append", "More content", project="work")
-
-# Discovery mode (no project = cross-project view)
-recent_activity() # Shows activity across all projects
-```
-
-## Resources and Examples
-
-### Where to Find More
-
-- **Real workflows**: [How you can use Basic Memory](/how-to/project-documentation) section
-- **New features**: [What's New](/whats-new) with detailed examples
-- **Setup guides**: [Integrations](/integrations/claude-desktop) for platform-specific usage
-- **User perspective**: [User Guide](/user-guide) for comprehensive workflows
-- **AI perspective**: [AI Assistant Guide](/guides/ai-assistant-guide) for best practices
-
-### Quick Reference
-
-**Most Common Tools:**
-- `write_note` - Create knowledge
-- `search_notes` - Find information
-- `edit_note` - Update incrementally
-- `list_memory_projects` - Discover projects
-- `recent_activity` - Check progress
-
-**Most Useful Prompts:**
-- `continue_conversation` - Resume discussions
-- `ai_assistant_guide` - Get usage help
-- `search_notes` - Formatted search results
-
-This reference provides the complete catalog of Basic Memory's MCP capabilities. For detailed examples and real-world usage patterns, explore the guides and how-to sections linked throughout this page.
diff --git a/src/pages/index.mdx b/src/pages/index.mdx
deleted file mode 100644
index d846856..0000000
--- a/src/pages/index.mdx
+++ /dev/null
@@ -1,174 +0,0 @@
----
-layout: '@/layouts/DocsLayout.astro'
-title: 'Basic Memory'
-description: 'AI and humans working together to build knowledge that gets smarter over time'
----
-
-import { Card, CardGroup } from '@/components'
-
-Build a persistent knowledge base where both you and AI can read, write, and enhance each other's work. No more losing valuable insights in conversation history.
-
-
-
-## True AI Collaboration
-
-Unlike typical AI tools where you ask questions and get answers, Basic Memory creates **genuine collaboration**:
-
-- **You capture ideas quickly** → **AI structures and enhances them**
-- **AI creates comprehensive research** → **You add personal insights and connections**
-- **Both build on each other's work** → **Knowledge grows smarter over time**
-- **Access from anywhere** → **Cloud-first with optional local sync**
-
-Every note becomes part of a **semantic knowledge graph** that reveals connections you never would have seen otherwise.
-
-## Pick up conversations exactly where you left off
-
-No more "Can you remind me what we discussed?" or "Here's what I learned before..." - AI assistants access your **entire knowledge history** instantly.
-
-```
-You: "Continue our discussion about the database architecture"
-
-AI: [Loads relevant context from your knowledge base]
-"Based on our previous conversations and your notes about performance requirements,
-I see we were exploring PostgreSQL vs. MongoDB. Looking at your updated benchmarking
-results from last week..."
-```
-
-
-## Knowledge that compounds
-
-AI creates **comprehensive, detailed notes** that connect to everything you've learned before:
-
-### Beyond Chat Summaries
-
-- **2,000+ word research documents** instead of brief summaries
-- **Technical deep-dives** that build on previous architecture decisions
-- **Creative project notes** that track character development and plot evolution
-- **Personal reflections** that reveal life patterns and growth over time
-
-### Semantic Connections
-Every piece of knowledge is semantically tagged and related:
-
-```markdown
-## Neural Networks Research
-- [breakthrough] Transformer architecture revolutionized NLP #architecture
-- [application] Enables large language models like GPT and Claude #llm
-- [limitation] Computational requirements limit accessibility #resource-constraint
-
-## Relations
-- builds_on [[Artificial Intelligence History]]
-- enables [[Modern AI Applications]]
-- influences [[AI Ethics Considerations]]
-```
-
-The knowledge graph **automatically suggests connections** across domains - your AI research might connect to philosophy notes, which link to creative writing projects.
-
-## Always Yours
-
-
-
- Your ideas, your notes, your memory. Never trapped in a platform or model. Your knowledge belongs to you, always.
-
-
- Everything in human-readable Markdown. No black boxes, no proprietary formats. Open and portable.
-
-
- Cloud-first with web editor, or sync locally to your machine. Work online or offline, your choice.
-
-
- AI writes, you edit. You write, AI reads. True bidirectional collaboration on a shared knowledge base.
-
-
-
-## Versatile Knowledge Building
-
-Basic Memory adapts to how **you** think and work:
-
-
-
- Living documentation that evolves with your codebase
-
-
- Track characters, plots, and research for novels and screenplays
-
-
- Build comprehensive knowledge from papers, books, and courses
-
-
- Connect goals, relationships, and life experiences
-
-
-
-## Real-Time Knowledge Flow
-
-**Morning research session:**
-```
-You: "Research quantum computing applications in cryptography"
-AI: [Creates detailed 3,000-word analysis with technical details,
- current research, and connections to your existing crypto notes]
-```
-
-**Afternoon development work:**
-```
-You: "Document the authentication system we just built"
-AI: [Reads your code, connects to security best practices from your
- knowledge base, creates comprehensive API documentation]
-```
-
-**Evening reflection:**
-```
-You: "Add today's insights to my learning journal"
-AI: [Reviews day's knowledge creation, identifies patterns,
- connects to personal growth goals and career development]
-```
-
-Each interaction **builds on everything before it** - creating knowledge that gets more valuable over time.
-
-## Designed for Collaboration
-
-Basic Memory implements the **Model Context Protocol (MCP)**, enabling direct integration with AI assistants. Real-time collaborative access where both you and AI can read, write, search, and manage your knowledge base through natural conversation.
-
-### AI Integration
-- **Claude Desktop** - View, edit, and manage your notes directly through chat. Ask Claude to create notes, search your knowledge, or display notes as formatted artifacts
-- **Claude Code** - Persistent context across development sessions with full MCP tool access
-- **Cursor** - AI-powered coding with project memory and native MCP support
-- **VS Code** - Code editing with real-time sync to knowledge graph
-
-### Human-Friendly
-- **Plain Markdown files** you can edit in any text editor
-- **Folder organization** that matches how you think
-- **Git compatibility** for version control and team sharing
-- **Search and discovery** across your entire knowledge base
-
-## Get Started
-
-
-
- Install and configure with your favorite AI assistant
-
-
- Complete guide to building your knowledge system
-
-
- Set up with Claude Desktop, Cursor, VS Code, and more
-
-
- Learn the semantic patterns that make knowledge searchable
-
-
-
----
-
-**Basic Memory**: Where AI and human intelligence combine to create knowledge that's greater than the sum of its parts.
diff --git a/src/pages/integrations/claude-code.mdx b/src/pages/integrations/claude-code.mdx
deleted file mode 100644
index 50a1b0d..0000000
--- a/src/pages/integrations/claude-code.mdx
+++ /dev/null
@@ -1,208 +0,0 @@
----
-layout: '@/layouts/DocsLayout.astro'
-title: "Claude Code"
-description: "Set up Basic Memory with Claude Code for persistent development knowledge and enhanced coding sessions"
----
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step, CodeGroup, CodeTab } from '@/components'
-
-Claude Code provides native support for Basic Memory through the Model Context Protocol (MCP), enabling persistent context across development sessions and building comprehensive coding knowledge.
-
-## Cloud Setup
-
-Basic Memory Cloud provides hosted MCP access with no local installation required.
-
-
-
- Create your account at [app.basicmemory.com](https://app.basicmemory.com)
-
-
-
- In Claude Code, add the remote MCP server:
-
- ```bash
- claude mcp add -s user -t http basic-memory-cloud https://cloud.basicmemory.com/mcp
- ```
-
-
-
- Follow the OAuth flow in Claude Code to grant permissions
-
-
-
- In Claude Code, check available tools:
-
- ```
- You: "What tools do you have access to?"
- ```
-
- You should see Basic Memory tools listed
-
-
-
-
-See the [Cloud Setup Guide](/guides/cloud) for detailed instructions and troubleshooting.
-
-
----
-
-## Local Setup
-
-### Install Basic Memory cli
-
-```bash
-# Install Basic Memory
-uv tool install basic-memory
-
-# Or with pip
-pip install basic-memory
-```
-
-### Configure Claude Code
-
-Basic Memory works automatically with Claude Code through MCP. Install it with:
-
-```bash
-claude mcp add basic-memory basic-memory mcp
-```
-
-
-You can use the `/mcp` command in Claude Code to check MCP server status and available tools.
-
-
-### Verify Installation
-
-In Claude Code, check that Basic Memory tools are available:
-
-```
-You: "What tools do you have access to?"
-```
-
-You should see Basic Memory tools listed, including note creation, search, and project management.
-
-## Quick Start
-
-Once configured, you can immediately start using Basic Memory in your development workflow:
-
-```
-You: "Create a note about our authentication strategy for the API"
-Claude: I'll document the authentication strategy we discussed...
-[Creates structured note with technical details and rationale]
-
-You: "Switch to my personal coding project"
-Claude: [Changes context to personal project knowledge base]
-```
-
-## MCP Integration Benefits
-
-Claude Code's native MCP support provides:
-
-- **Automatic tool access** - No manual setup required
-- **Project-aware context** - Maintains separate knowledge bases per project
-- **Real-time sync** - Changes are immediately available
-- **Persistent memory** - Context survives between sessions
-- **Structured knowledge** - Uses Basic Memory's semantic format
-
-### Available Tools
-
-Through MCP, Claude Code can access all Basic Memory functionality:
-
-- **write_note** - Create and update documentation
-- **read_note** - Access existing knowledge and context
-- **search_notes** - Find relevant information across projects
-- **edit_note** - Update documentation incrementally
-- **recent_activity** - Check what you've been working on
-- **project management** - Switch between different knowledge bases
-- **build_context** - Load conversation context from memory:// URLs
-
-## Integration with Development
-
-### CLAUDE.md Enhancement
-
-Claude Code uses CLAUDE.md files for project instructions. Basic Memory complements this by:
-
-- **Storing detailed knowledge** outside the context window
-- **Enabling search** across your entire knowledge base
-- **Maintaining history** of decisions and learnings
-- **Linking related concepts** through relations
-
-### Project Context
-
-Basic Memory maintains separate knowledge bases for different projects:
-
-```
-You: "Switch to my work project"
-Claude: [Loads work project context and knowledge]
-
-You: "Based on our API design notes, what's the next step?"
-Claude: [References existing documentation to provide contextual guidance]
-```
-
-## Troubleshooting
-
-### Common Issues
-
-
-
- **Solutions:**
- - Verify Basic Memory is installed: `basic-memory --version`
- - Check MCP server status: `/mcp` in Claude Code
- - Reinstall if needed: `claude mcp remove basic-memory` then `claude mcp add basic-memory basic-memory mcp`
-
-
-
- **Solutions:**
- - Confirm files exist in current project
- - Check memory:// URL syntax (e.g., `memory://folder/note`)
- - Verify sync is working: `basic-memory status`
-
-
-
- **Solutions:**
- - Check file permissions in knowledge base directory
- - Check ~/.basic-memory for logs containing error messages
- - Report error messages to the Basic Memory team
-
-
-
-### Performance Tips
-
-- **Multiple projects**: Use separate Basic Memory projects for different codebases
-- **Organized structure**: Keep consistent folder organization across projects
-- **Regular cleanup**: Archive old projects to maintain performance
-
-## Alternative Usage
-
-If MCP isn't working, you can still use Basic Memory:
-
-
-
- Use Basic Memory CLI tools from Claude Code's terminal
-
-
- Edit Basic Memory notes directly and sync manually
-
-
- Copy content from Basic Memory into conversations
-
-
- Use Claude Desktop alongside Claude Code. With Basic Memory they can see the same notes and share context.
-
-
-
-## Next Steps
-
-
-
- Learn how to document your development projects
-
-
- Build knowledge from your coding sessions
-
-
- Master Basic Memory command line tools
-
-
- Structure effective development documentation
-
-
diff --git a/src/pages/integrations/claude-desktop.mdx b/src/pages/integrations/claude-desktop.mdx
deleted file mode 100644
index ba687db..0000000
--- a/src/pages/integrations/claude-desktop.mdx
+++ /dev/null
@@ -1,315 +0,0 @@
----
-layout: '@/layouts/DocsLayout.astro'
-title: "Claude Desktop"
-description: "Set up Basic Memory with Claude Desktop for persistent conversations and knowledge management"
----
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step, CodeGroup, CodeTab } from '@/components'
-
-Claude Desktop is the recommended way to use Basic Memory. Integration through the Model Context Protocol (MCP) gives Claude direct access to your knowledge base.
-
-## Cloud Setup
-
-Basic Memory Cloud provides hosted MCP access with no local installation required.
-
-
-
- Create your account at [app.basicmemory.com](https://app.basicmemory.com)
-
-
-
- In Claude Desktop, go to **Settings → Claude → Connectors**
-
- Click "Add connector" and enter:
- - **Name**: Basic Memory
- - **Remote MCP server URL**: `https://cloud.basicmemory.com/mcp`
-
- 
-
-
-
- Click "Connect" and follow the OAuth flow to grant permissions
-
- 
-
-
-
- In Claude, click the tools icon (🔨) to see Basic Memory tools
-
- 
-
- Try Prompting: `List my projects`
-
-
-
-
-See the [Cloud Setup Guide](/guides/cloud) for detailed instructions, web editor usage, and troubleshooting.
-
-
----
-
-## Local Installation
-
-### Prerequisites
-
-
-- `uv` **must be installed and available in your system PATH**. Claude Desktop runs in its own isolated environment and needs `uv` to manage dependencies.
-- **On macOS, install `uv` globally with Homebrew**: `brew install uv`. This ensures Claude Desktop can detect it.
-
-
-### Configure Claude Desktop
-
-Edit your Claude Desktop config, located at:
-
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-
-
-```json
-{
- "mcpServers": {
- "basic-memory": {
- "command": "uvx",
- "args": [
- "basic-memory",
- "mcp"
- ]
- }
- }
-}
-```
-
-### Install Basic Memory (Optional)
-
-```bash
-# Stable release (recommended)
-uv tool install basic-memory
-# or: pip install basic-memory
-
-# Beta releases (new features, testing)
-pip install basic-memory --pre
-
-# Development builds (latest changes)
-pip install basic-memory --pre --force-reinstall
-```
-
-### Restart Claude Desktop
-
-After saving the config, restart Claude Desktop. You should see Basic Memory tools available in the tools menu (hammer icon in bottom-right).
-
-
-
-## Features
-
-### Core Capabilities
-
-
-
- Create and update notes through natural conversation
-
-
- Find information across your entire knowledge base
-
-
- Load context from previous conversations using memory:// URLs
-
-
- Work with multiple knowledge projects in each conversation
-
-
- View notes as formatted artifacts for better readability
-
-
-
-### Real-time Sync
-
-Changes you make to files are immediately available in conversations:
-
-1. Edit a file in any text editor
-2. Save the changes
-3. Ask Claude to read the note - it will see your updates
-
-### Memory URLs
-
-Reference specific knowledge with `memory://` URLs:
-
-```
-You: "Take a look at memory://project-planning and let's continue our discussion"
-```
-
-Claude will load that specific note and any related context.
-
-## Common Workflows
-
-### Creating Knowledge
-
-**During a conversation:**
-```
-You: "Could you create a note summarizing our discussion about API design?"
-Claude: I'll create a note capturing our API design discussion...
-[Creates structured note with observations and relations]
-```
-
-**Building on existing knowledge:**
-```
-You: "Add a section about authentication to my API documentation"
-Claude: [Uses edit_note to append new content without rewriting]
-```
-
-### Searching and Discovery
-
-**Find information:**
-```
-You: "What did we decide about the database schema?"
-Claude: [Searches knowledge base and provides relevant information]
-```
-
-**View formatted notes:**
-```
-You: "Show me the project documentation as a formatted artifact"
-Claude: [Uses view_note to display the note as a readable artifact]
-```
-
-**Recent activity:**
-```
-You: "What have we been working on lately?"
-Claude: [Shows recently modified notes and offers to continue discussions]
-```
-
-### Project Management
-
-Projects are selected at the start of each conversation. Claude will suggest your most active project and ask which one to use.
-
-**Starting a conversation:**
-```
-You: "Let's organize my personal notes"
-
-Claude: I see you have 3 projects: main, work-notes, personal
-Your most active project is personal
-Should I use personal for this task?
-
-You: "Yes"
-```
-
-**For single-project users**, add this to `~/.basic-memory/config.json`:
-```json
-{
- "default_project": "main",
- "default_project_mode": true
-}
-```
-
-This skips project selection and uses your default project automatically.
-
-## Advanced Usage
-
-### Special Prompts
-
-Basic Memory includes prompts that trigger specific behaviors:
-
-- **"Continue our conversation about [topic]"** - Loads relevant context
-- **"What have we been discussing recently?"** - Shows recent activity
-- **"Find information about [topic]"** - Searches knowledge base
-
-### Incremental Editing
-
-Instead of rewriting entire notes, Claude can edit incrementally:
-
-- **Append**: Add new sections to existing notes
-- **Prepend**: Add content to the beginning
-- **Replace sections**: Update specific parts
-- **Find and replace**: Make targeted text changes
-
-### File Organization
-
-Claude can help organize your knowledge base:
-
-- Move notes to appropriate folders
-- Archive old content
-- Create directory structures
-- Maintain database consistency during moves
-
-## Troubleshooting
-
-### Common Issues
-
-
-
- **Solutions:**
- - Verify `uv` is installed: `which uvx`
- - Check config file syntax is valid JSON
- - Restart Claude Desktop after config changes
- - Try absolute path to uvx in config
-
-
-
- **Solutions:**
- - Check Basic Memory is installed: `basic-memory --version`
- - Verify sync is running: `basic-memory status`
- - Check file permissions in `~/basic-memory`
- - Look for error messages in Claude Desktop
-
-
-
- **Solutions:**
- - Confirm real-time sync is enabled (default)
- - Check `basic-memory status` for sync status
- - Restart sync: `basic-memory sync --watch`
- - Verify file is in the correct project directory
-
-
-
-### Getting Help
-
-```bash
-# Check installation
-basic-memory --version
-
-# View sync status
-basic-memory status
-
-# Get help with commands
-basic-memory --help
-```
-
-## Best Practices
-
-### Knowledge Creation
-
-1. **Use descriptive titles** - They become link targets
-2. **Add semantic observations** - Categorize information
-3. **Create relations** - Connect related concepts
-4. **Use tags** - Enable better search
-5. **Review AI-generated content** - Edit for accuracy
-
-### Conversation Management
-
-1. **Reference existing knowledge** - Use memory:// URLs
-2. **Build incrementally** - Add to existing notes
-3. **Use multiple projects** - Organize knowledge by context (work, personal, etc.)
-4. **Use special prompts** - Leverage built-in behaviors
-5. **Organize regularly** - Keep knowledge base clean
-
-### Performance
-
-1. **Archive old content** - Keep active knowledge focused
-2. **Use meaningful filenames** - Improve discoverability
-3. **Regular backups** - Use git for version control
-4. **Monitor project size** - Check with `basic-memory project info`
-
-## Next Steps
-
-
-
- Learn comprehensive usage patterns
-
-
- Understand the semantic markup
-
-
- Command line tools and options
-
-
- How AI assistants use Basic Memory
-
-
diff --git a/src/pages/integrations/cursor.mdx b/src/pages/integrations/cursor.mdx
deleted file mode 100644
index 52141fa..0000000
--- a/src/pages/integrations/cursor.mdx
+++ /dev/null
@@ -1,189 +0,0 @@
----
-layout: '@/layouts/DocsLayout.astro'
-title: "Cursor"
-description: "Set up Basic Memory with Cursor for AI-powered development with persistent memory"
----
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step, CodeGroup, CodeTab } from '@/components'
-
-Cursor's AI-powered development environment integrates natively with Basic Memory through the Model Context Protocol (MCP), enabling persistent context across coding sessions.
-
-## Cloud Setup
-
-Basic Memory Cloud provides hosted MCP access with no local installation required.
-
-
-
- Create your account at [app.basicmemory.com](https://app.basicmemory.com)
-
-
-
- In Cursor, go to **Settings → Developer → Edit Config**
-
- Select **MCP Tools** and click **Add Custom MCP**
-
- Add Basic Memory Cloud configuration:
- ```json
- {
- "mcpServers": {
- "basic-memory-cloud": {
- "url": "https://cloud.basicmemory.com/mcp"
- }
- }
- }
- ```
-
-
-
- Follow the OAuth flow to grant Cursor access to your Basic Memory account
-
-
-
- In Cursor, ask the AI:
-
- ```
- You: "What tools do you have access to?"
- ```
-
- You should see Basic Memory tools listed
-
-
-
-
-See the [Cloud Setup Guide](/guides/cloud) for detailed instructions and troubleshooting.
-
-
----
-
-## Local Setup
-
-### Configure MCP in Cursor
-
-Cursor supports MCP natively! Configure Basic Memory following the [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol).
-
-**Add to Cursor's MCP configuration:**
-
-```json
-{
- "mcpServers": {
- "basic-memory": {
- "command": "uvx",
- "args": ["basic-memory", "mcp"]
- }
- }
-}
-```
-
-### Install Basic Memory (optional)
-
-```bash
-# Install Basic Memory
-uv tool install basic-memory
-
-# Or with pip
-pip install basic-memory
-```
-
-### Verify Installation
-
-In Cursor, check that Basic Memory tools are available by asking the AI:
-
-```
-You: "What tools do you have access to?"
-```
-
-You should see Basic Memory tools listed, including note creation, search, and project management.
-
-## Quick Start
-
-Once configured, you can immediately start using Basic Memory in your Cursor conversations:
-
-```
-You: "Create a Basic Memory project for this codebase in the docs folder"
-Cursor: [Creates project configuration and folder structure]
-
-You: "Document our architecture decisions as we make them"
-Cursor: [Creates structured notes with observations and relations]
-```
-
-## MCP Integration Benefits
-
-
-Cursor's native MCP support enables Basic Memory integration with:
-- Direct tool access in AI conversations
-- Real-time knowledge base queries
-- Persistent context across coding sessions
-- No manual content transfer needed
-
-
-### Available Tools
-
-Through MCP, Cursor can access all Basic Memory tools:
-
-- **write_note** - Create structured documentation
-- **read_note** - Access existing knowledge
-- **search_notes** - Find relevant information
-- **edit_note** - Update documentation incrementally
-- **recent_activity** - Check what you've been working on
-- **project management** - Work with multiple knowledge bases
-
-## Troubleshooting
-
-### Common Issues
-
-
-
- **Solutions:**
- - Verify Basic Memory is installed: `basic-memory --version`
- - Check MCP configuration syntax in Cursor settings
- - Restart Cursor after configuration changes
- - Try absolute path to uvx if needed
-
-
-
- **Solutions:**
- - Check Basic Memory sync status: `basic-memory status`
- - Verify project directory permissions
- - Ensure uvx can find basic-memory: `which basic-memory`
-
-
-
- **Solutions:**
- - Large knowledge bases may slow responses
- - Consider splitting into multiple projects
- - Check available disk space
-
-
-
-## Alternative Integration
-
-If MCP setup doesn't work immediately, you can also:
-
-
-
- Edit Basic Memory notes directly in Cursor with full IDE features
-
-
- Use Basic Memory CLI tools from Cursor's integrated terminal
-
-
- Use Claude Desktop alongside Cursor for knowledge management
-
-
-
-## Next Steps
-
-
-
- Learn how to document your development projects
-
-
- Record and track technical decisions
-
-
- Master command line tools for development
-
-
- Structure your development documentation
-
-
diff --git a/src/pages/integrations/gemini.mdx b/src/pages/integrations/gemini.mdx
deleted file mode 100644
index 614f747..0000000
--- a/src/pages/integrations/gemini.mdx
+++ /dev/null
@@ -1,212 +0,0 @@
----
-layout: '@/layouts/DocsLayout.astro'
-title: "Google Gemini"
-description: "Set up Basic Memory with Google Gemini for persistent development knowledge and enhanced AI sessions"
----
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step, CodeGroup, CodeTab } from '@/components'
-
-Google Gemini provides native support for Basic Memory through the Model Context Protocol (MCP), enabling persistent context across AI sessions and building comprehensive knowledge bases.
-
-## Cloud Setup
-
-Basic Memory Cloud provides hosted MCP access with no local installation required.
-
-
-
- Create your account at [app.basicmemory.com](https://app.basicmemory.com)
-
-
-
- Add Basic Memory Cloud using HTTP transport:
-
- ```bash
- gemini mcp add -t http basic-memory-cloud https://cloud.basicmemory.com/mcp
- ```
-
-
-
- Follow the OAuth flow to grant Gemini access to your Basic Memory account
-
-
-
- Check that Basic Memory is configured:
-
- ```bash
- gemini mcp list
- ```
-
- You should see `basic-memory-cloud` with Connected status
-
-
-
-
-See the [Cloud Setup Guide](/guides/cloud) for detailed instructions and troubleshooting.
-
-
----
-
-## Local Setup
-
-### Video Tutorial
-
-Watch this quick guide to get started with Basic Memory and Google Gemini:
-
-
-
-
-
-### Configure Gemini
-
-Basic Memory works with Gemini through MCP. Install it with:
-
-```bash
-gemini mcp add basic-memory bash -c "uvx basic-memory mcp"
-```
-
-
-If you want to use a specific Basic Memory project, modify the command like so:
-```bash
-gemini mcp add basic-memory bash -c "uvx basic-memory mcp --project your-project-name"
-```
-
-You can also install it globally for your profile with:
-```bash
-gemini mcp add -s user basic-memory bash -c "uvx basic-memory mcp"
-```
-
-
-### Verify Installation
-
-Check that Basic Memory is configured correctly:
-
-```bash
-gemini mcp list
-```
-
-You should see `basic-memory` listed with the command `bash -c uvx basic-memory mcp` and a Connected status.
-
-## Quick Start
-
-Once configured, you can immediately start using Basic Memory in your workflow:
-
-```
-You: "Create a note about our authentication strategy for the API"
-Gemini: I'll document the authentication strategy we discussed...
-[Creates structured note with technical details and rationale]
-
-You: "Switch to my personal project"
-Gemini: [Changes context to personal project knowledge base]
-```
-
-## MCP Integration Benefits
-
-Gemini's native MCP support provides:
-
-- **Automatic tool access** - No manual setup required
-- **Project-aware context** - Maintains separate knowledge bases per project
-- **Real-time sync** - Changes are immediately available
-- **Persistent memory** - Context survives between sessions
-- **Structured knowledge** - Uses Basic Memory's semantic format
-
-### Available Tools
-
-Through MCP, Gemini can access all Basic Memory functionality:
-
-- **write_note** - Create and update documentation
-- **read_note** - Access existing knowledge and context
-- **search_notes** - Find relevant information across projects
-- **edit_note** - Update documentation incrementally
-- **recent_activity** - Check what you've been working on
-- **project management** - Switch between different knowledge bases
-- **build_context** - Load conversation context from memory:// URLs
-
-## Integration with Development
-
-### Project Context
-
-Basic Memory maintains separate knowledge bases for different projects:
-
-```
-You: "Switch to my work project"
-Gemini: [Loads work project context and knowledge]
-
-You: "Based on our API design notes, what's the next step?"
-Gemini: [References existing documentation to provide contextual guidance]
-```
-
-## Troubleshooting
-
-### Common Issues
-
-
-
- **Solutions:**
- - Verify Basic Memory is installed: `basic-memory --version`
- - Check MCP server configuration: `gemini mcp list`
- - Reinstall if needed: `gemini mcp remove basic-memory` then `gemini mcp add basic-memory bash -c "uvx basic-memory mcp"`
-
-
-
- **Solutions:**
- - Confirm files exist in current project
- - Check memory:// URL syntax (e.g., `memory://folder/note`)
- - Verify sync is working: `basic-memory status`
-
-
-
- **Solutions:**
- - Check file permissions in knowledge base directory
- - Check ~/.basic-memory for logs containing error messages
- - Report error messages to the Basic Memory team
-
-
-
-### Performance Tips
-
-- **Multiple projects**: Use separate Basic Memory projects for different use cases
-- **Organized structure**: Keep consistent folder organization across projects
-- **Regular cleanup**: Archive old projects to maintain performance
-
-## Alternative Usage
-
-If MCP isn't working, you can still use Basic Memory:
-
-
-
- Use Basic Memory CLI tools from your terminal
-
-
- Edit Basic Memory notes directly and sync manually
-
-
- Copy content from Basic Memory into conversations
-
-
- Use Claude Desktop or other MCP clients alongside Gemini. With Basic Memory they can see the same notes and share context.
-
-
-
-## Next Steps
-
-
-
- Learn how to document your projects
-
-
- Build knowledge from your sessions
-
-
- Master Basic Memory command line tools
-
-
- Structure effective documentation
-
-
diff --git a/src/pages/integrations/obsidian.mdx b/src/pages/integrations/obsidian.mdx
deleted file mode 100644
index b9ba66d..0000000
--- a/src/pages/integrations/obsidian.mdx
+++ /dev/null
@@ -1,403 +0,0 @@
----
-layout: '@/layouts/DocsLayout.astro'
-title: "Obsidian Integration"
-description: "Basic Memory works with Obsidian to visualize and navigate your knowledge graph.
-"
----
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step, CodeGroup, CodeTab } from '@/components'
-
-
-For more information about Obsidian, visit the Obsidian home page.
-
-
-## Using with Basic Memory Cloud
-
-Basic Memory Cloud enables a hybrid workflow: edit locally in Obsidian while your notes sync to the cloud.
-
-
-Sync requires the Basic Memory CLI. See [Local Installation](/getting-started#local-installation) for installation steps.
-
-
-
-
- Create your account at [app.basicmemory.com](https://app.basicmemory.com)
-
-
-
- Authenticate and enable cloud mode:
-
- ```bash
- bm cloud login
- ```
-
- This enables cloud mode and validates your subscription.
-
-
-
- Install rclone and configure credentials:
-
- ```bash
- bm cloud setup
- ```
-
- This installs rclone automatically and configures your cloud credentials.
-
-
-
-
- Point Basic Memory to your Obsidian vault:
-
- ```bash
- # If you have an existing vault
- bm project add my-vault --local-path ~/path/to/obsidian-vault
-
- # Or create a new project for a new vault
- bm project add notes --local-path ~/Documents/notes
- ```
-
- This creates the project on cloud and prepares local sync.
-
-
-
- Preview and run the initial sync:
-
- ```bash
- # Preview first (recommended)
- bm project bisync --name my-vault --resync --dry-run
-
- # If all looks good, establish baseline
- bm project bisync --name my-vault --resync
- ```
-
- This creates the initial sync state. Only use `--resync` for the first sync.
-
-
-
- Open your local directory as a vault in Obsidian. Continue editing locally with full graph view, plugins, and IDE features.
-
-
-
- After editing in Obsidian or making changes in cloud (via AI assistants), run bidirectional sync:
-
- ```bash
- bm project bisync --name my-vault
- ```
-
- This syncs changes in both directions - edit locally or in cloud, both stay in sync.
-
-
-
-
-**Bidirectional sync**: `bisync` keeps local and cloud in sync automatically. Changes flow both ways, with newer files winning conflicts. For one-way sync options and advanced configuration, see the [Cloud Sync Guide](/guides/cloud-sync).
-
-
----
-
-## Setup
-
-### Setting Up Obsidian with Basic Memory
-
-You can either create a new vault for Basic Memory or configure Basic Memory to use your existing vault.
-
-#### Option 1: Use an Existing Obsidian Vault
-
-If you have an existing Obsidian vault where you want Basic Memory to save notes:
-
-
-
-```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 Claude Desktop for the changes to take effect
-
-
-Ask Claude to create a note - it will now appear in your existing vault
-
-
-
-#### Option 2: Create a New Vault for Basic Memory
-
-
-
-Download and install [Obsidian](https://obsidian.md)
-
-
-Create a new vault in Obsidian pointing to your Basic Memory directory (~/basic-memory by default)
-
-
-Enable core plugins like Graph View, Backlinks, and Tags
-
-
-
-## Visualization Features
-
-### Graph View
-
-Obsidian's Graph View provides a visual representation of your knowledge network:
-
-
-
- Each document appears as a node
-
-
- Relations appear as connections between nodes
-
-
- Colors can be customized to distinguish types
-
-
- Filters let you focus on specific aspects
-
-
-
-
-Local graphs show connections for individual documents, providing focused views of specific areas in your knowledge base.
-
-
-### Backlinks
-
-Obsidian automatically tracks references between documents:
-
-- View all documents that reference the current one
-- See the exact context of each reference
-- Navigate easily through connections
-- Track how concepts relate to each other
-
-### Tag Explorer
-
-Use tags to organize and filter content:
-
-- View all tags in your knowledge base
-- See how many documents use each tag
-- Filter documents by tag combinations
-- Create hierarchical tag structures
-
-## Knowledge Elements
-
-Basic Memory's knowledge format works natively with Obsidian:
-
-### Wiki Links
-
-```markdown
-## Relations
-- implements [[Search Design]]
-- depends_on [[Database Schema]]
-```
-
-
-These display as clickable links in Obsidian and appear in the graph view.
-
-
-### Observations with Tags
-
-```markdown
-## Observations
-- [tech] Using SQLite #database
-- [design] Plain-text #architecture
-```
-
-Tags become searchable and filterable in Obsidian's tag pane.
-
-### Frontmatter
-
-```yaml
----
-title: Document Title
-type: note
-tags: [search, design]
----
-```
-
-Frontmatter provides metadata for Obsidian to use in search and filtering.
-
-## Canvas Integration
-
-Basic Memory can create [Obsidian Canvas](https://obsidian.md/canvas) files:
-
-
-
-```example
-You: "Create a canvas showing the structure of our project components."
-```
-
-
-The file is automatically created in your knowledge base
-
-
-View and edit the visual representation in Obsidian
-
-
-Canvas files keep live references to your documents
-
-
-
-## Recommended Plugins
-
-These Obsidian plugins work especially well with Basic Memory:
-
-
-
- Query your knowledge base programmatically
-
-
- Organize tasks from knowledge files
-
-
- View and navigate temporal knowledge
-
-
- Create consistent knowledge structures
-
-
-
-## Workflow Suggestions
-
-### Daily Notes
-
-```markdown
-# 2024-01-21
-
-## Progress
-- Updated [[Search Design]]
-- Fixed [[Bug Report 123]]
-
-## Notes
-- [idea] Better indexing #enhancement
-- [todo] Update docs #documentation
-
-## Links
-- relates_to [[Current Sprint]]
-- updates [[Project Status]]
-```
-
-### Project Tracking
-
-```markdown
-# Current Sprint
-
-## Tasks
-- [ ] Update [[Search]]
-- [ ] Fix [[Auth Bug]]
-
-## Tags
-#sprint #planning #current
-```
-
-## Advanced Obsidian Features
-
-### Graph Analysis
-
-#### Global Graph
-View your entire knowledge network to identify:
-- Central concepts (highly connected nodes)
-- Knowledge clusters
-- Isolated information
-- Missing connections
-
-#### Local Graph
-Focus on specific documents to see:
-- Direct connections
-- Related concepts
-- Knowledge pathways
-- Context around ideas
-
-### Search and Navigation
-
-
-
- Rapidly navigate between documents using Cmd/Ctrl + O
-
-
- Search across all content with advanced filtering options
-
-
- Browse by tags and see tag hierarchies
-
-
- See all references to the current document
-
-
-
-### Visual Customization
-
-You can customize how your knowledge appears in Obsidian:
-
-```css
-/* Custom CSS for Basic Memory observations */
-.observation-tech {
- color: #4A90E2;
- font-weight: bold;
-}
-
-.observation-design {
- color: #7ED321;
- font-style: italic;
-}
-
-.observation-decision {
- color: #F5A623;
- background: rgba(245, 166, 35, 0.1);
- padding: 2px 4px;
- border-radius: 3px;
-}
-```
-
-## Integration Benefits
-
-
-**Why use Obsidian with Basic Memory?**
-
-- **Visual Knowledge Mapping**: See the structure of your knowledge
-- **Powerful Navigation**: Move through connected concepts easily
-- **Rich Plugin Ecosystem**: Extend functionality with community plugins
-- **Mature Editor**: Professional markdown editing with live preview
-- **Local Files**: Everything stays on your machine, just like Basic Memory
-
-
-## Tips for Effective Use
-
-
-
- Use consistent tag patterns to enable better filtering and organization
-
-
- Create meaningful relation types that help you understand connections
-
-
- Regularly review your graph to identify knowledge gaps
-
-
- Use templates for consistent document structure
-
-
-
-## Troubleshooting
-
-### Common Issues
-
-
-
- - Ensure proper WikiLink syntax: `[[Document Title]]`
- - Check that referenced documents exist
- - Verify frontmatter title matches link text
-
-
-
- - Use proper tag syntax: `#tag` or in frontmatter
- - Check tag panel is enabled in Obsidian
- - Ensure tags don't contain spaces (use hyphens)
-
-
-
- - Update to latest Obsidian version
- - Enable Canvas core plugin
- - Check file permissions
-
-
diff --git a/src/pages/integrations/vscode.mdx b/src/pages/integrations/vscode.mdx
deleted file mode 100644
index 9a37b38..0000000
--- a/src/pages/integrations/vscode.mdx
+++ /dev/null
@@ -1,320 +0,0 @@
----
-layout: '@/layouts/DocsLayout.astro'
-title: "VS Code"
-description: "Set up Basic Memory with VS Code for file-based knowledge management and development documentation"
----
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step, CodeGroup, CodeTab } from '@/components'
-
-VS Code provides excellent support for Basic Memory through direct file editing, terminal integration, and rich markdown features, making it ideal for maintaining development documentation alongside your code.
-
-## Cloud Sync Workflow
-
-Basic Memory Cloud enables editing locally in VS Code while your notes sync to the cloud.
-
-
-
- Create your account at [app.basicmemory.com](https://app.basicmemory.com)
-
-
-
- Authenticate and enable cloud mode:
-
- ```bash
- bm cloud login
- ```
-
-
-
- Install rclone and configure credentials:
-
- ```bash
- bm cloud setup
- ```
-
- This installs rclone automatically and configures your cloud credentials.
-
-
- Sync requires the Basic Memory CLI. See [Local Installation](/getting-started#local-installation) for installation steps.
-
-
-
-
- Point Basic Memory to your local workspace:
-
- ```bash
- # For a project-specific docs folder
- bm project add my-project --local-path ~/workspace/my-project/docs
-
- # Or for a shared knowledge base
- bm project add knowledge --local-path ~/Documents/knowledge
- ```
-
-
-
- Preview and run the initial sync:
-
- ```bash
- # Preview first (recommended)
- bm project bisync --name my-project --resync --dry-run
-
- # Establish baseline
- bm project bisync --name my-project --resync
- ```
-
- Only use `--resync` for the first sync.
-
-
-
- Open your local directory in VS Code. Edit files with full IDE features, syntax highlighting, and markdown preview.
-
-
-
- After editing locally or making changes in cloud, run bidirectional sync:
-
- ```bash
- bm project bisync --name my-project
- ```
-
- This syncs changes in both directions - edit locally or in cloud, both stay in sync.
-
-
-
-
-**Bidirectional sync**: `bisync` keeps local and cloud in sync automatically. Changes flow both ways, with newer files winning conflicts. For one-way sync options and advanced configuration, see the [Cloud Sync Guide](/guides/cloud-sync).
-
-
----
-
-## Setup
-
-### Configure VS Code Settings
-
-Create or update `.vscode/settings.json` for enhanced markdown editing:
-
-```json
-{
- "files.associations": {
- "*.md": "markdown"
- },
- "markdown.preview.breaks": true,
- "markdown.preview.linkify": true,
- "editor.wordWrap": "on",
- "editor.quickSuggestions": {
- "other": true,
- "comments": true,
- "strings": true
- },
- "search.exclude": {
- "**/node_modules": true,
- "**/.git": true
- }
-}
-```
-
-### Install Basic Memory (optional)
-
-```bash
-# Install Basic Memory
-uv tool install basic-memory
-
-# Or with pip
-pip install basic-memory
-```
-
-### Install Recommended Extensions
-
-**Essential Extensions:**
-- **Markdown All in One** - Rich markdown editing with preview
-- **Markdown Preview Enhanced** - Advanced preview features
-- **Git Graph** - Visual git history for your knowledge base
-- **Terminal** - Built-in terminal for Basic Memory CLI
-
-## Integration Features
-
-### File-Based Editing
-
-
-
- Edit markdown files with syntax highlighting and preview
-
-
- Changes automatically sync to knowledge graph
-
-
- Use VS Code search across all documentation
-
-
- Version control your knowledge alongside code
-
-
-
-### Terminal Integration
-
-Set up CLI aliases for quick access:
-
-```bash
-# Add to your shell profile (.bashrc, .zshrc, etc.)
-alias note="basic-memory tools write-note"
-alias search="basic-memory tools search-notes --query"
-alias recent="basic-memory tools recent-activity"
-
-# Usage in VS Code terminal
-note --title "Authentication Flow" --folder "architecture"
-search "database patterns"
-recent --timeframe="2 days"
-```
-
-### Multi-Root Workspace
-
-Combine multiple projects in one workspace:
-
-```json
-{
- "folders": [
- {
- "name": "Project Code",
- "path": "./src"
- },
- {
- "name": "Documentation",
- "path": "./docs"
- },
- {
- "name": "Shared Knowledge",
- "path": "~/knowledge"
- }
- ],
- "settings": {
- "search.exclude": {
- "**/node_modules": true,
- "**/.git": true
- }
- }
-}
-```
-
-## Quick Start
-
-### Project Structure
-
-Organize your project with integrated knowledge:
-
-```
-my-project/
-├── src/
-├── tests/
-├── docs/ # Basic Memory project folder
-│ ├── architecture/
-│ ├── decisions/
-│ ├── patterns/
-│ └── api/
-├── .vscode/
-│ └── settings.json
-└── README.md
-```
-
-### Basic Usage
-
-1. **Edit documentation** in VS Code with full IDE features
-2. **Use split editor** - code on left, documentation on right
-3. **Terminal commands** for quick Basic Memory operations
-4. **File explorer** to navigate between code and docs
-5. **Git integration** to version control everything together
-
-## VS Code Snippets
-
-Create custom snippets for Basic Memory patterns. Add to `.vscode/markdown.json`:
-
-```json
-{
- "Basic Memory Note": {
- "prefix": "bmnote",
- "body": [
- "---",
- "title: ${1:Note Title}",
- "tags: [${2:tag1, tag2}]",
- "---",
- "",
- "# ${1:Note Title}",
- "",
- "## Observations",
- "- [${3:category}] ${4:observation} #${5:tag}",
- "",
- "## Relations",
- "- ${6:relation_type} [[${7:Related Note}]]",
- "",
- "$0"
- ],
- "description": "Create a Basic Memory note template"
- }
-}
-```
-
-## Troubleshooting
-
-### Common Issues
-
-
-
- **Solutions:**
- - Check file associations in settings
- - Install Markdown All in One extension
- - Verify markdown language mode is selected
-
-
-
- **Solutions:**
- - Check sync status: `basic-memory status`
- - Verify file permissions in project directory
-
-
-
- **Solutions:**
- - Check VS Code search settings
- - Verify files are not excluded in search.exclude
- - Use Basic Memory CLI search for knowledge graph queries
-
-
-
-### Performance Tips
-
-- **Exclude large files**: Configure search.exclude appropriately
-- **Use workspace**: Better performance than opening large folders
-- **Limit extensions**: Only install needed extensions
-- **Regular cleanup**: Archive old documentation periodically
-
-## Integration Benefits
-
-### Development Workflow
-
-- **Real-time documentation** - Edit docs as you code
-- **Unified search** - Search code and documentation together
-- **Git versioning** - Track changes to both code and knowledge
-- **Split editing** - View code and docs simultaneously
-- **Terminal access** - Quick Basic Memory commands
-
-### File Management
-
-- **Direct editing** - No need for external tools
-- **Rich preview** - See formatted markdown in real-time
-- **Folder organization** - Maintain clear structure
-- **Link navigation** - Follow wikilinks between notes
-- **Syntax highlighting** - Clear visual editing
-
-## Next Steps
-
-
-
- Learn effective project documentation strategies
-
-
- Master note-taking techniques for development
-
-
- Master Basic Memory command line tools
-
-
- Structure your development documentation
-
-
diff --git a/src/pages/latest-releases.mdx b/src/pages/latest-releases.mdx
deleted file mode 100644
index 561f13f..0000000
--- a/src/pages/latest-releases.mdx
+++ /dev/null
@@ -1,1155 +0,0 @@
----
-layout: '@/layouts/DocsLayout.astro'
-title: 'Latest Releases'
-description: 'Basic Memory is updated frequently, below are notable recent changes.'
----
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step } from '@/components'
-
----
-
-View the latest changes to Basic Memory on [GitHub](https://github.com/basicmachines-co/basic-memory/releases)
-
-## [v0.18.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.18.0) — 2026-01-28
-
-**Focus:** Context-aware wiki link resolution, directory operations, and cloud routing improvements
-
-
-**Highlights:**
-- Context-aware wiki link resolution with `source_path` support
-- Directory support for move and delete operations
-- Local MCP cloud mode routing for simultaneous local/cloud usage
-- MCP prompt rendering fixes
-
-
-### Features
-
-- **Context-aware wiki link resolution** ([#527](https://github.com/basicmachines-co/basic-memory/pull/527))
- - Add `source_path` parameter to `resolve_link()` for context-aware resolution
- - Relative path resolution: `[[nested/note]]` from `folder/file.md` → `folder/nested/note.md`
- - Proximity-based resolution for duplicate titles (prefers notes in same folder)
- - Strict mode to disable fuzzy search fallback for wiki links
-
-- **Directory support for move and delete** ([#518](https://github.com/basicmachines-co/basic-memory/pull/518))
- - Add `is_directory` parameter to `move_note` and `delete_note` MCP tools
- - New `POST /move-directory` and `POST /delete-directory` API endpoints
- - Rename `folder` → `directory` parameter across codebase for consistency
-
-- **Local MCP cloud mode routing** ([#522](https://github.com/basicmachines-co/basic-memory/pull/522))
- - Add `--local` and `--cloud` CLI routing flags
- - Local MCP server (`basic-memory mcp`) automatically uses local routing
- - Enables simultaneous use of local Claude Desktop and cloud-based clients
- - Environment variable `BASIC_MEMORY_FORCE_LOCAL=true` for global override
-
-### Bug Fixes
-
-- **Fix MCP prompt rendering errors** ([#524](https://github.com/basicmachines-co/basic-memory/pull/524))
- - Fix "Error rendering prompt recent_activity" error
- - Change `TimeFrame` to `str` in prompt type annotations for FastMCP compatibility
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.17.9...v0.18.0
-
----
-
-## [v0.17.8-v0.17.9](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.17.9) — 2026-01-24
-
-**Focus:** Cloud mode bug fixes and snapshot CLI commands
-
-### Features
-
-- **Cloud snapshot CLI commands** ([#476](https://github.com/basicmachines-co/basic-memory/pull/476))
- - New `basic-memory cloud snapshot` commands: `create`, `list`, `delete`, `show`, `browse`
- - Manage cloud backups directly from the command line
-
-### Bug Fixes
-
-- **Fix `get_default_project()` returning multiple results** ([#521](https://github.com/basicmachines-co/basic-memory/pull/521))
- - Query incorrectly matched any project with non-NULL `is_default` (both True and False)
- - Now correctly checks for `is_default=True` only
-
-- **Fix `remove_project()` checking stale config in cloud mode** ([#523](https://github.com/basicmachines-co/basic-memory/pull/523))
- - In cloud mode, only check database `is_default` field (source of truth)
- - Config file can become stale when users set default project via v2 API
-
-- **Read default project from database in cloud mode** ([#520](https://github.com/basicmachines-co/basic-memory/pull/520))
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.17.7...v0.17.9
-
----
-
-## [v0.17.7](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.17.7) — 2026-01-19
-
-**Focus:** MCP Registry publication and bug fixes
-
-
-**Highlights:**
-- Basic Memory is now published to the official MCP Registry
-- Fixed entity creation to properly set external_id
-- Removed OpenPanel telemetry
-
-
-### Features
-
-- **MCP Registry Publication** ([#515](https://github.com/basicmachines-co/basic-memory/pull/515))
- - Basic Memory is now listed on the official MCP Registry at [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io)
- - Added `server.json` for registry metadata
- - Automated version sync during releases
-
-### Bug Fixes
-
-- **Fix external_id not set on entity creation** ([#513](https://github.com/basicmachines-co/basic-memory/pull/513))
- - Ensures stable UUID identifiers are properly assigned when creating new entities
-
-### Internal
-
-- **Remove OpenPanel telemetry** ([#514](https://github.com/basicmachines-co/basic-memory/pull/514))
- - Telemetry collection has been removed from the codebase
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.17.6...v0.17.7
-
----
-
-## [v0.17.6](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.17.6) — 2026-01-17
-
-**Focus:** Docker container fix and internal cleanup
-
-### Bug Fixes
-
-- **Fix Docker container Python symlink broken at runtime** ([#510](https://github.com/basicmachines-co/basic-memory/pull/510))
- - Resolves issue where Python symlink was broken in Docker containers
- - Ensures reliable container startup
-
-### Internal
-
-- Remove logfire config and specs docs
-- Reduce lifespan and sync logging to debug level for cleaner output
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.17.5...v0.17.6
-
----
-
-## [v0.17.5](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.17.5) — 2026-01-11
-
-**Focus:** Python 3.14 compatibility and CLI stability
-
-
-**Highlights:**
-- Python 3.14 compatibility fixes
-- CLI commands no longer hang on exit
-- Updated pyright for better type checking
-
-
-### Bug Fixes
-
-- **Prevent CLI commands from hanging on exit** ([#505](https://github.com/basicmachines-co/basic-memory/pull/505))
- - Skip `nest_asyncio` on Python 3.14+ where it causes event loop issues
- - Simplify CLI test infrastructure for cross-version compatibility
- - Update pyright to 1.1.408 for Python 3.14 support
- - Fix SQLAlchemy rowcount typing for Python 3.14
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.17.4...v0.17.5
-
----
-
-## [v0.17.4](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.17.4) — 2026-01-05
-
-**Focus:** Critical search index fix and major architecture refactor
-
-
-**Important:** If you're upgrading from v0.16.3-v0.17.3, run `basic-memory reset` once after updating to rebuild your search index. A bug introduced in v0.16.3 caused the search index to be wiped on every server restart.
-
-
-
-**Highlights:**
-- Critical fix: Search index now persists across server restarts
-- Major internal architecture improvements with composition roots
-- New typed API clients for better code organization
-
-
-### Bug Fixes
-
-- **Preserve search index across server restarts** ([#503](https://github.com/basicmachines-co/basic-memory/pull/503))
- - Fixes critical bug where search index was wiped on every MCP server restart
- - Bug was introduced in v0.16.3, affecting v0.16.3-v0.17.3
- - **User action**: Run `basic-memory reset` once after updating to rebuild search index
-
-### Internal
-
-- **Major architecture refactor** ([#502](https://github.com/basicmachines-co/basic-memory/pull/502))
- - Add composition roots for API, MCP, and CLI entrypoints
- - Split deps.py into feature-scoped modules (config, db, projects, repositories, services, importers)
- - Add ProjectResolver for unified project selection
- - Add SyncCoordinator for centralized sync/watch lifecycle
- - Introduce typed API clients for MCP tools (KnowledgeClient, SearchClient, MemoryClient, etc.)
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.17.3...v0.17.4
-
----
-
-## [v0.17.3](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.17.3) — 2026-01-03
-
-**Focus:** Claude Code compatibility and cloud deployment stability
-
-
-**Highlights:**
-- MCP protocol version 2025-11-25 support for Claude Code compatibility
-- Stable UUID external_id for Projects and Entities
-- Cloud deployment fixes for route ordering and config handling
-
-
-### Features
-
-- **Stable external_id for Projects and Entities** ([#485](https://github.com/basicmachines-co/basic-memory/pull/485))
- - Added stable UUID `external_id` field to Project and Entity models
- - Enables reliable cross-system synchronization and identity tracking
- - Foundation for improved cloud sync and API integrations
-
-### Bug Fixes
-
-- **MCP protocol version 2025-11-25 support** ([#501](https://github.com/basicmachines-co/basic-memory/pull/501))
- - Updated mcp dependency to >=1.23.1 to support protocol version 2025-11-25
- - Fixes "Unsupported protocol version" errors when using Claude Code
- - Ensures compatibility with latest Claude Code releases
-
-- **Route ordering for cloud deployments** ([#499](https://github.com/basicmachines-co/basic-memory/pull/499))
- - Fixed API route ordering issues in cloud environments
- - Resolves request routing conflicts in multi-tenant deployments
-
-- **Skip config file update in cloud mode** ([#486](https://github.com/basicmachines-co/basic-memory/pull/486))
- - `set_default_project` no longer attempts to write config files in cloud mode
- - Prevents filesystem errors in containerized environments
-
-- **RelationResponse.from_id optional** ([#484](https://github.com/basicmachines-co/basic-memory/pull/484))
- - Made `from_id` optional to handle null permalinks gracefully
- - Fixes API errors when processing relations with missing data
-
-- **Parallel search indexing stability**
- - Use upsert operations to prevent IntegrityError during concurrent indexing
- - Improved reliability for large knowledge bases
-
-- **Relative file paths in importers**
- - Use relative paths for cloud storage compatibility
- - Fixes import operations in cloud environments
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.17.2...v0.17.3
-
----
-
-## [v0.17.2](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.17.2) — 2025-12-29
-
-**Focus:** Cloud mode improvements and build optimizations
-
-### Bug Fixes
-
-- **Allow recent_activity discovery mode in cloud mode**
- - Added `allow_discovery` parameter to `resolve_project_parameter()` that enables tools like `recent_activity` to work across all projects in cloud mode without requiring a project parameter
- - Fixes workflow where users want to see activity across all projects
-
-### Infrastructure
-
-- **Build optimizations** - Release builds now run lint and typecheck only, skipping full test suite for faster releases
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.17.1...v0.17.2
-
----
-
-## [v0.17.1](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.17.1) — 2025-12-29
-
-**Focus:** Critical fix for file watch service
-
-### Bug Fixes
-
-- **Fix watch service not starting** ([#482](https://github.com/basicmachines-co/basic-memory/pull/482))
- - Fixed issue where `BASIC_MEMORY_ENV='test'` was being set unconditionally at import time
- - This caused `config.is_test_env` to always return True, preventing the MCP server from starting the file watch service
- - File sync for external changes now works correctly in production
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.17.0...v0.17.1
-
----
-
-## [v0.17.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.17.0) — 2025-12-28
-
-**Focus:** API v2 migration, auto-formatting, and telemetry
-
-
-**Highlights:**
-- MCP tools now use API v2 endpoints for improved performance
-- Auto-format files on save with built-in Python formatter
-- Anonymous usage telemetry (Homebrew-style opt-out)
-- CLI commands no longer hang on exit
-
-
-### Features
-
-- **API v2 Migration - Phase 2 Complete** ([#447](https://github.com/basicmachines-co/basic-memory/pull/447))
- - All MCP tools now use v2 endpoints for improved performance
- - Foundation for future API enhancements
- - Backward compatible with existing integrations
-
-- **Auto-format files on save** ([#474](https://github.com/basicmachines-co/basic-memory/pull/474))
- - Built-in Python formatter automatically formats files when saved
- - Consistent formatting without external tools
- - Configurable behavior
-
-- **Anonymous usage telemetry** ([#478](https://github.com/basicmachines-co/basic-memory/pull/478))
- - Homebrew-style opt-out telemetry to help improve the product
- - Privacy-respecting with no personal data collected
- - Easy to disable via environment variable
-
-### Bug Fixes
-
-- **CLI commands no longer hang on exit** ([#471](https://github.com/basicmachines-co/basic-memory/pull/471))
- - Fixed issue where CLI commands would hang instead of cleanly exiting
- - Improved user experience with responsive command completion
-
-- **Rclone version detection** ([#473](https://github.com/basicmachines-co/basic-memory/pull/473))
- - Detects rclone version to check for `--create-empty-src-dirs` support
- - Better compatibility across different rclone versions
-
-- **Null titles in ChatGPT import** ([#475](https://github.com/basicmachines-co/basic-memory/pull/475))
- - Handles null titles gracefully during ChatGPT conversation import
- - Prevents crashes on malformed import data
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.16.3...v0.17.0
-
----
-
-## [v0.16.3](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.16.3) — 2025-12-20
-
-**Focus:** PostgreSQL database backend, API v2, and critical bug fixes
-
-
-**Highlights:**
-- Full PostgreSQL/Neon database support as alternative to SQLite
-- API v2 with ID-based endpoints for improved performance
-- Fixed FastMCP version to restore MCP tools visibility
-- Reduced CPU usage in watch service
-- Improved shutdown handling for background tasks
-
-
-### Features
-
-- **PostgreSQL database backend** ([#439](https://github.com/basicmachines-co/basic-memory/pull/439))
- - Full PostgreSQL/Neon database support as alternative to SQLite
- - Async connection pooling with asyncpg
- - Alembic migrations support for both backends
- - Configurable via `BASIC_MEMORY_DATABASE_BACKEND` environment variable
-
-- **API v2 with ID-based endpoints** ([#441](https://github.com/basicmachines-co/basic-memory/pull/441))
- - New ID-based API endpoints for improved performance
- - Foundation for future API enhancements
- - Backward compatible with existing endpoints
-
-- **Performance improvements**
- - Project-scoped queries with `project_id` on Relations and Observations
- - Bulk insert with ON CONFLICT handling for relations
- - Lightweight permalink resolution to avoid eager loading
-
-### Bug Fixes
-
-- **#464**: Pin FastMCP to 2.12.3 to fix MCP tools visibility
- - Fixes issue where MCP tools were not visible to Claude
- - Reverts to last known working FastMCP version
-
-- **#458**: Reduce watch service CPU usage
- - Increased reload interval to lower CPU utilization
- - More efficient resource usage during file watching
-
-- **#456**: Await background sync task cancellation in lifespan shutdown
- - Prevents hanging on shutdown
- - Clean async task cleanup
-
-- **#434**: Respect --project flag in background sync
- - Background sync now correctly uses specified project
- - Fixes multi-project sync issues
-
-- **#424**: Handle periods in kebab_filenames mode
- - Fixes filename handling for files with multiple periods
- - Improved kebab-case conversion
-
-### Testing
-
-- Replace py-pglite with testcontainers for Postgres testing
- - More reliable Postgres testing infrastructure
- - Uses Docker-based test containers
- - CI runs both SQLite and Postgres tests in parallel
-
-### New Contributors
-
-- [@divideby0](https://github.com/divideby0) made their first contribution
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.16.2...v0.16.3
-
----
-
-## [v0.16.2](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.16.2) — 2025-11-16
-
-**Focus:** Windows platform improvements and project management fixes
-
-### Bug Fixes
-
-- **#429**: Use platform-native path separators in config.json
- ([`6517e98`](https://github.com/basicmachines-co/basic-memory/commit/6517e98))
- - Fixes config.json path separator issues on Windows
- - Uses os.path.join for platform-native path construction
- - Ensures consistent path handling across platforms
-
-- **#427**: Add rclone installation checks for Windows bisync commands
- ([`1af0539`](https://github.com/basicmachines-co/basic-memory/commit/1af0539))
- - Validates rclone installation before running bisync commands
- - Provides clear error messages when rclone is not installed
- - Improves user experience on Windows
-
-- **#421**: Main project always recreated on project list command
- ([`cad7019`](https://github.com/basicmachines-co/basic-memory/commit/cad7019))
- - Fixes issue where main project was recreated unnecessarily
- - Improves project list command reliability
- - Reduces unnecessary file system operations
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.16.1...v0.16.2
-
----
-## [v0.16.1](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.16.1) — 2025-11-11
-
-**Focus:** Windows cloud sync stability
-
-### Bug Fixes
-
-- **#422**: Handle Windows line endings in rclone bisync
- ([`e9d0a94`](https://github.com/basicmachines-co/basic-memory/commit/e9d0a94))
- - Added `--compare=modtime` flag to rclone bisync to ignore size differences from line ending conversions
- - Fixes issue where LF→CRLF conversion on Windows was treated as file corruption
- - Resolves "corrupted on transfer: sizes differ" errors during cloud sync on Windows
- - Users will need to run `--resync` once after updating to establish new baseline
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.16.0...v0.16.1
-
----
-## [v0.16.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.16.0) — 2025-11-10
-
-**Focus:** Cloud sync improvements, Windows platform support, and reliability enhancements
-
-
-**Highlights:**
-- Simplified project-scoped cloud sync with rclone
-- Significantly improved Windows compatibility and Unicode handling
-- Circuit breaker pattern for sync resilience
-- Better memory management for large knowledge bases
-- Enhanced cloud upload controls with verbose logging
-
-
-### Cloud Sync Improvements
-
-- **Simplified project-scoped rclone sync** ([#405](https://github.com/basicmachines-co/basic-memory/pull/405))
- - More reliable cloud synchronization with project-level configuration
- - Better error handling and status reporting
- - Improved sync performance and consistency
-
-- **Background sync operations** ([#417](https://github.com/basicmachines-co/basic-memory/pull/417))
- - New `run_in_background` parameter for async sync operations
- - Better API flexibility for long-running sync tasks
- - Non-blocking sync workflows
-
-- **Circuit breaker for file sync failures** ([#364](https://github.com/basicmachines-co/basic-memory/pull/364))
- - Prevents cascading failures during sync operations
- - Automatic recovery from transient errors
- - Enhanced resilience in cloud sync scenarios
-
-- **Enhanced cloud upload controls** ([#362](https://github.com/basicmachines-co/basic-memory/pull/362))
- - `--verbose` flag for detailed upload logging
- - `--no-gitignore` option to bypass gitignore filtering
- - Better debugging and troubleshooting capabilities
-
-- **Preserve file timestamps on upload** ([#377](https://github.com/basicmachines-co/basic-memory/pull/377))
- - Maintains modification times during WebDAV upload
- - Better sync accuracy and detection
- - Prevents unnecessary re-syncing
-
-### Windows Platform Support
-
-- **Unicode encoding fixes** ([#411](https://github.com/basicmachines-co/basic-memory/pull/411), [#414](https://github.com/basicmachines-co/basic-memory/pull/414))
- - Resolves Unicode encoding issues on Windows terminals
- - ASCII arrows replace Unicode characters for compatibility
- - Better handling of international characters
-
-- **Rclone Windows compatibility** ([#410](https://github.com/basicmachines-co/basic-memory/pull/410))
- - Fixes cloud sync reliability on Windows
- - Better path handling for Windows filesystem
- - Improved rclone integration
-
-### Reliability & Performance
-
-- **Optimized memory usage for large projects** ([#380](https://github.com/basicmachines-co/basic-memory/pull/380))
- - Prevents out-of-memory errors on large knowledge bases
- - Better memory management during sync operations
- - Improved scalability
-
-- **Better YAML frontmatter handling** ([#418](https://github.com/basicmachines-co/basic-memory/pull/418), [#402](https://github.com/basicmachines-co/basic-memory/pull/402))
- - Quotes string values to handle special characters
- - Normalizes frontmatter types to prevent errors
- - More robust markdown parsing
-
-- **Improved sync accuracy** ([#369](https://github.com/basicmachines-co/basic-memory/pull/369))
- - Uses filesystem timestamps instead of database operation time
- - Better detection of external file modifications
- - More reliable sync behavior
-
-- **Streaming foundation** ([#384](https://github.com/basicmachines-co/basic-memory/pull/384))
- - Foundation for streaming support in future releases
- - Consolidated async I/O patterns
- - Improved performance and resource management
-
-### Bug Fixes
-
-- **Skip archive files during cloud upload** ([#420](https://github.com/basicmachines-co/basic-memory/pull/420))
- - Prevents uploading zip, tar, gz and other archives
- - Reduces storage usage and upload time
-
-- **Cleaner note editing** ([#396](https://github.com/basicmachines-co/basic-memory/pull/396))
- - Strips duplicate headers in edit_note replace_section
- - Better content consistency
-
-- **Improved error handling** ([#379](https://github.com/basicmachines-co/basic-memory/pull/379), [#368](https://github.com/basicmachines-co/basic-memory/pull/368), [#389](https://github.com/basicmachines-co/basic-memory/pull/389))
- - Graceful handling of YAML parsing errors
- - Better handling of missing or malformed frontmatter
- - More robust markdown processing
-
-- **Project lifecycle fixes** ([#370](https://github.com/basicmachines-co/basic-memory/pull/370), [#366](https://github.com/basicmachines-co/basic-memory/pull/366))
- - Prevents deleted projects from being recreated by background sync
- - Faster project deletion with immediate sync termination
-
-- **Database integrity** ([#367](https://github.com/basicmachines-co/basic-memory/pull/367))
- - Resolves UNIQUE constraint violations during sync
- - Better handling of duplicate observations
-
-### API Improvements
-
-- **Renamed write_note parameter** ([#419](https://github.com/basicmachines-co/basic-memory/pull/419))
- - Changed `entity_type` to `note_type` for clarity
- - Better API consistency and documentation
-
-- **Project deletion options** ([#391](https://github.com/basicmachines-co/basic-memory/pull/391))
- - `delete_notes` parameter for safer project cleanup
- - Prevents accidental data loss
-
-- **Idempotent project creation** ([#357](https://github.com/basicmachines-co/basic-memory/pull/357))
- - No errors when creating existing projects
- - Better API reliability
-
-- **Better type safety** ([#394](https://github.com/basicmachines-co/basic-memory/pull/394), [#395](https://github.com/basicmachines-co/basic-memory/pull/395))
- - Explicit type annotations in MCP tool parameters
- - Cleaner search_notes schema
- - Improved IDE support
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.15.2...v0.16.0
-
----
-## [v0.15.2](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.15.2) — 2025-10-14
-
-### Cloud Features
-
-- **WebDAV upload command for cloud projects** ([#356](https://github.com/basicmachines-co/basic-memory/pull/356))
- - New `basic-memory cloud upload` command for uploading files to cloud projects via WebDAV
- - Supports uploading individual files or entire directories
- - Automatic project syncing after upload completes
- - Simplifies workflow for adding local files to cloud projects
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.15.1...v0.15.2
-
----
-## [v0.15.1](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.15.1) — 2025-10-13
-
-**Focus:** Cloud mode stability, performance optimizations, and bug fixes
-
-
-**Highlights:**
-- 10-100x performance improvement for directory operations
-- 43% faster sync and indexing operations
-- Enhanced cloud mode security with path validation
-- Critical bug fixes for project deletion and Claude Desktop compatibility
-
-
-### Performance Improvements
-
-- **Optimize directory operations for 10-100x performance improvement** ([#350](https://github.com/basicmachines-co/basic-memory/pull/350))
- - Dramatically faster directory listing and traversal operations
- - Improved responsiveness for large knowledge bases
- - Optimized file system operations
-
-- **Optimize sync/indexing for 43% faster performance** ([#352](https://github.com/basicmachines-co/basic-memory/pull/352))
- - Significantly faster file synchronization
- - Reduced indexing time for large projects
- - Enhanced overall system responsiveness
-
-### Cloud Mode Enhancements
-
-- **Cloud mode path validation and sanitization** ([#332](https://github.com/basicmachines-co/basic-memory/pull/332))
- - Enhanced security with strict path validation in cloud mode
- - Prevents path traversal attacks and unauthorized file access
- - Improved data isolation for multi-tenant environments
-
-- **BASIC_MEMORY_PROJECT_ROOT for path constraints** ([#334](https://github.com/basicmachines-co/basic-memory/pull/334))
- - New environment variable for defining project root boundaries
- - Additional security layer for cloud deployments
- - Prevents access to files outside designated project directories
-
-- **Normalize paths to lowercase in cloud mode** ([#336](https://github.com/basicmachines-co/basic-memory/pull/336))
- - Prevents case-sensitivity collisions in cloud storage
- - Ensures consistent file handling across platforms
- - Improves cross-platform compatibility
-
-- **Configuration persistence via Tigris (SPEC-15)** ([#343](https://github.com/basicmachines-co/basic-memory/pull/343))
- - Cloud configuration storage implementation
- - Persistent settings across sessions
- - Foundation for enhanced cloud features
-
-- **Async client context manager pattern** ([#344](https://github.com/basicmachines-co/basic-memory/pull/344))
- - Improved cloud client architecture
- - Better resource management and connection handling
- - Enhanced reliability for cloud operations
-
-### Bug Fixes
-
-- **Prevent nested project paths** ([#338](https://github.com/basicmachines-co/basic-memory/pull/338))
- - Prevents data conflicts from nested project configurations
- - Improved project isolation and data integrity
- - Clear error messages for invalid project structures
-
-- **Project deletion with permalink normalization** ([#345](https://github.com/basicmachines-co/basic-memory/pull/345))
- - Fixed project deletion failures caused by permalink handling
- - Consistent permalink normalization across operations
- - Improved project management reliability
-
-- **Add permalink normalization to project lookups** ([#348](https://github.com/basicmachines-co/basic-memory/pull/348))
- - Ensures consistent project lookups across all operations
- - Fixes edge cases with project switching
- - Enhanced project management stability
-
-- **Correct ProjectItem.home property** ([#341](https://github.com/basicmachines-co/basic-memory/pull/341))
- - Fixed property to return path instead of name
- - Corrects API contract for project information
- - Improved integration reliability
-
-- **Update view_note and ChatGPT tools for Claude Desktop compatibility** ([#355](https://github.com/basicmachines-co/basic-memory/pull/355))
- - Fixed Claude Desktop integration issues
- - Enhanced MCP tool compatibility
- - Improved cross-platform tool support
-
-### Documentation
-
-- **v0.15.0 assistant guide** ([#335](https://github.com/basicmachines-co/basic-memory/pull/335))
- - Comprehensive guide for AI assistants working with Basic Memory
- - Enhanced integration documentation
- - Improved developer experience
-
-- **Tool documentation for write_note** ([#339](https://github.com/basicmachines-co/basic-memory/pull/339))
- - Clarified usage of empty string or "/" for root folder
- - Improved API documentation
- - Better tool usage examples
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.15.0...v0.15.1
-
----
-## [v0.15.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.15.0) — 2024-10-04
-
-**Major Release:** Cloud features, performance improvements, and enhanced project workflow
-
-
-**Highlights:**
-- Basic Memory Cloud (invite-only beta) - Cloud sync, authentication, and file mounting
-- API performance improvements with background relation resolution
-- Improved project selection - Choose your project at conversation start
-- Python 3.13 support and .gitignore integration
-- ChatGPT integration with specialized tools
-
-
-### Cloud Features
-
-- Sync to cloud projects
-- CLI commands support cloud projects
-- ChatGPT tools integration
-
-
-Basic Memory Cloud is currently in invite-only beta. Sign up for Early Access on [basicmemory.com](https://basicmemory.com).
-
-
-### Performance Improvements
-
-- API performance optimizations ([#315](https://github.com/basicmachines-co/basic-memory/pull/315))
- - Implements SPEC-11 performance improvements
- - Optimized database queries and response times
-
-- Lifecycle management optimization ([#320](https://github.com/basicmachines-co/basic-memory/pull/320))
- - Enhanced application lifecycle management
-
-- Background relation resolution ([#319](https://github.com/basicmachines-co/basic-memory/pull/319))
- - Non-blocking startup with background processing
- - Prevents cold start delays
-
-- Non-blocking sync operations ([#309](https://github.com/basicmachines-co/basic-memory/pull/309))
- - Thread pool for sync operations
- - Improved responsiveness
-
-### Security Enhancements
-
-- Remove .env file loading ([#330](https://github.com/basicmachines-co/basic-memory/pull/330))
- - Eliminates unintended environment variable loading
- - Improved configuration security
-
-- .gitignore integration ([#314](https://github.com/basicmachines-co/basic-memory/pull/314))
- - Respects .gitignore patterns during sync
- - Prevents syncing build artifacts and temporary files
-
-### Platform Support
-
-- Python 3.13 support
- - Full compatibility with Python 3.13
- - Updated dependencies and CI testing
-
-- ChatGPT tools integration ([#305](https://github.com/basicmachines-co/basic-memory/pull/305))
- - ChatGPT-specific search and fetch tools
-
-### Bug Fixes
-
-- Permalink collision prevention ([`2a050ed`](https://github.com/basicmachines-co/basic-memory/commit/2a050ed))
- - Prevents data loss from fuzzy search matching similar file paths
- - Strict link resolution during entity creation
-
-- Normalize underscores in memory:// URLs ([#329](https://github.com/basicmachines-co/basic-memory/pull/329))
- - Consistent URL handling for knowledge graph navigation
-
-- Simplify entity upsert ([#328](https://github.com/basicmachines-co/basic-memory/pull/328))
- - Database-level conflict resolution
- - Reduced application complexity
-
-- Minimum timeframe enforcement ([#318](https://github.com/basicmachines-co/basic-memory/pull/318))
- - Enforced minimum timeframe for operations
-
-- DateTime JSON schema format ([#312](https://github.com/basicmachines-co/basic-memory/pull/312))
- - Proper datetime format annotations for MCP validation
-
-- Remove obsolete project management code ([#310](https://github.com/basicmachines-co/basic-memory/pull/310))
- - Cleanup of deprecated functionality
-
-- Fix move_note without file extension ([#281](https://github.com/basicmachines-co/basic-memory/pull/281))
- - Allow moving notes by title alone
-
-### Architecture
-
-- Disable permalinks config flag ([#313](https://github.com/basicmachines-co/basic-memory/pull/313))
- - Optional permalink generation
-
-- Enhanced project workflow ([#298](https://github.com/basicmachines-co/basic-memory/pull/298))
- - Improved project selection at conversation start
-
-### Breaking Changes & Migration
-
-
-**Project workflow changes:**
-- AI assistants will ask which project to use at conversation start
-- You can still switch projects mid-conversation by saying "switch to project 'foo'"
-- The assistant remembers your current project throughout the conversation
-
-**Migration:** No action required - conversations will work naturally with the new workflow. Single-project users can enable `default_project_mode` in config to skip the selection prompt.
-
-
-**What's changed for users:**
-1. **Project selection** - AI asks which project to use when starting conversations
-2. **Flexible switching** - Tell the AI to switch projects anytime during the conversation
-3. **Single-project mode** - Enable `default_project_mode` in `~/.basic-memory/config.json` to automatically use your default project
-
-See [What's New](/whats-new#v0.15.0) for complete details and [Getting Started](/getting-started#multi-project-setup) for setup guidance.
-
----
-## [v0.14.4](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.14.4) — 2025-09-04
-
-### Critical Bug Fixes
-
-- **Critical search index bug - prevent note disappearing on edit** ([#257](https://github.com/basicmachines-co/basic-memory/pull/257))
- - Fixed critical issue where notes would disappear during editing operations
- - Improved search index stability and consistency
-
-### Database & Project Management
-
-- **Add missing foreign key constraints for project removal** ([#258](https://github.com/basicmachines-co/basic-memory/pull/258))
- - Enhanced database integrity with proper foreign key constraints
- - Improved project deletion handling and data consistency
-
-- **Add project isolation to ContextService.find_related() method** ([#262](https://github.com/basicmachines-co/basic-memory/pull/262))
- - Fixed cross-project data leakage in context search operations
- - Strengthened project boundary enforcement
-
-- **Complete project management special character support** ([#279](https://github.com/basicmachines-co/basic-memory/pull/279))
- - Enhanced support for special characters in project names and paths
- - Improved cross-platform compatibility for project management
-
-### Platform Compatibility
-
-- **Windows platform compatibility improvements** ([#252](https://github.com/basicmachines-co/basic-memory/pull/252))
- - Addressed multiple Windows-specific issues and compatibility problems
- - Enhanced cross-platform file handling and path resolution
-
-- **Fix Windows test failures and add Windows CI support** ([#273](https://github.com/basicmachines-co/basic-memory/pull/273))
- - Added Windows continuous integration support
- - Fixed platform-specific test failures
-
-### File Handling & Synchronization
-
-- **Handle vim atomic write DELETE events without ADD** ([#249](https://github.com/basicmachines-co/basic-memory/pull/249))
- - Improved handling of vim's atomic write operations
- - Better file synchronization with external editors
-
-- **Sanitize filenames and allow optional kebab case** ([#260](https://github.com/basicmachines-co/basic-memory/pull/260))
- - Enhanced filename sanitization for cross-platform compatibility
- - Added support for kebab-case filename formatting
-
-### MCP & API Improvements
-
-- **Enable string-to-integer conversion for build_context depth parameter** ([#259](https://github.com/basicmachines-co/basic-memory/pull/259))
- - Improved parameter handling in MCP build_context operations
- - Enhanced API flexibility and error handling
-
-- **Use discriminated unions for MCP schema validation in build_context** ([#266](https://github.com/basicmachines-co/basic-memory/pull/266))
- - Strengthened MCP schema validation with discriminated unions
- - Improved type safety and error detection
-
-- **Add ISO datetime serialization to MCP schema models** ([#270](https://github.com/basicmachines-co/basic-memory/pull/270))
- - Enhanced datetime handling in MCP operations
- - Improved API consistency and standard compliance
-
-### Logging & Configuration
-
-- **Respect BASIC_MEMORY_LOG_LEVEL and BASIC_MEMORY_CONSOLE_LOGGING environment variables** ([#264](https://github.com/basicmachines-co/basic-memory/pull/264))
- - Proper handling of logging configuration environment variables
- - Enhanced debugging and troubleshooting capabilities
-
-### Content Processing
-
-- **Ensure all datetime operations return timezone-aware objects** ([#268](https://github.com/basicmachines-co/basic-memory/pull/268))
- - Fixed timezone handling inconsistencies
- - Improved datetime processing reliability
-
-- **Fix observation parsing to exclude markdown and wiki links** ([#269](https://github.com/basicmachines-co/basic-memory/pull/269))
- - Enhanced content parsing to properly handle markdown and wiki link formats
- - Improved observation extraction accuracy
-
-- **Update YAML frontmatter tag formatting for Obsidian compatibility** ([#280](https://github.com/basicmachines-co/basic-memory/pull/280))
- - Enhanced Obsidian plugin compatibility with improved YAML frontmatter handling
- - Better integration with Obsidian's tagging system
-
-### Infrastructure
-
-- **Implement non-root Docker container to fix file ownership issues** ([#277](https://github.com/basicmachines-co/basic-memory/pull/277))
- - Enhanced Docker container security by running as non-root user
- - Fixed file ownership and permission issues in containerized environments
-
-### New Contributors
-
-- [@manuelbliemel](https://github.com/manuelbliemel) made their first contribution
-- [@bdmayes](https://github.com/bdmayes) made their first contribution
-
----
-## [v0.14.3](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.14.3) — 2025-08-02
-
-### Bug Fixes & Stability Improvements
-
-- **Enhanced character conflict detection and error handling for sync operations** ([`fb1350b`](https://github.com/basicmachines-co/basic-memory/commit/fb1350b))
- - Improved file path conflict detection for case-insensitive file systems
- - Better handling of character encoding differences and Unicode normalization
- - Enhanced error messages for sync conflicts
-
-- **Replace recursive _traverse_messages with iterative approach** ([`7585a29`](https://github.com/basicmachines-co/basic-memory/commit/7585a29))
- - Fixed stack overflow issues when handling deep conversation threads
- - Improved performance for ChatGPT import with large conversation histories
- - Better memory usage for processing complex conversation structures
-
-- **Handle missing 'name' key in memory JSON import** ([`a4a3b1b`](https://github.com/basicmachines-co/basic-memory/commit/a4a3b1b))
- - Fixed crashes when importing memory JSON files with incomplete data
- - Improved error handling and validation for legacy import formats
- - Better backward compatibility with older memory export formats
-
-- **Fix: basic memory home env var not respected when project path is changed** ([`6361574`](https://github.com/basicmachines-co/basic-memory/commit/6361574))
- - Fixed environment variable handling for custom project locations
- - Improved cross-platform path resolution
- - Better support for relative and absolute path configurations
-
-- **Fix: path traversal security vulnerability in mcp tools** ([`a0cf623`](https://github.com/basicmachines-co/basic-memory/commit/a0cf623))
- - Secured MCP tool file operations against path traversal attacks
- - Enhanced input validation for file paths and operations
- - Improved security posture for file system interactions
-
-### Testing & Quality
-
-- **Make case sensitivity test platform-aware** ([`7460a93`](https://github.com/basicmachines-co/basic-memory/commit/7460a93))
- - Fixed test failures on case-insensitive file systems (macOS, Windows)
- - Added platform detection for appropriate test behavior
- - Improved test reliability across different operating systems
-
----
-## [v0.14.2](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.14.2) — 2025-07-03
-
-- **#211**: Fix deprecation warnings in output
- ([`e738037`](https://github.com/basicmachines-co/basic-memory/pull/211))
- - Replace deprecated datetime.utcnow() with timezone-aware alternatives and suppress SQLAlchemy warnings
-
-- **#212**: MCP Error with MCP-Hub:
- ([`518d57c`](https://github.com/basicmachines-co/basic-memory/pull/212))
- - The MCP Tools spec calls for accepting empty parameter objects, which these two tools did not
- - Verified by testing the container locally
-
----
-## [v0.14.1](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.14.1) — 2025-07-02
-
-### Bug Fixes
-
-- **#203**: Pin FastMCP to prevent v2.10.0 breaking change
- ([`3a2e8c3`](https://github.com/basicmachines-co/basic-memory/pull/203))
- - FastMCP v2.10.0 introduced decorative ASCII box drawing characters in stdout output
- - This breaks JSON-based MCP protocol communication, preventing MCP servers from functioning
- - Constrained dependency to `fastmcp<2.10.0` until upstream issue is resolved
- - Critical fix: without this, Basic Memory MCP server fails to start with Claude Desktop and other MCP clients
-
-- **#190**: Fix MCP integration issues
- ([`bd4f551`](https://github.com/basicmachines-co/basic-memory/commit/bd4f551))
- - Fixed problems with Model Context Protocol integration that affected tool functionality
- - Ensures stable communication between Basic Memory and AI tools like MCP Hub
-
-- **#200**: Add Cursor IDE support
- ([`5360005`](https://github.com/basicmachines-co/basic-memory/commit/5360005))
- - Added an "Add to Cursor" button for easier integration with Cursor IDE
- - Provides developers with seamless setup for their preferred AI-powered development environment
-
-### Documentation
-
-- Updated README.md with clearer installation instructions and troubleshooting guides
- ([`39f811f`](https://github.com/basicmachines-co/basic-memory/commit/39f811f))
-
----
-## [v0.14.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.14.0) — 2025-06-26
-
-### Features
-
-- **Docker Container Registry Migration** - Switch from Docker Hub to GitHub Container Registry for better security and integration
- ([`616c1f0`](https://github.com/basicmachines-co/basic-memory/commit/616c1f0710da59c7098a5f4843d4f017877ff7b2))
- - Automated Docker image publishing via GitHub Actions CI/CD pipeline
- - Enhanced container security with GitHub's integrated vulnerability scanning
- - Streamlined container deployment workflow for production environments
-
-- **Enhanced Search Documentation** - Comprehensive search syntax examples for improved user experience
- ([`a589f8b`](https://github.com/basicmachines-co/basic-memory/commit/a589f8b894e78cce01eb25656856cfea8785fbbf))
- - Detailed examples for Boolean search operators (AND, OR, NOT)
- - Advanced search patterns including phrase matching and field-specific queries
- - User-friendly documentation for complex search scenarios
-
-- **Cross-Project File Management** - Intelligent move operations with project boundary detection
- ([`db5ef7d`](https://github.com/basicmachines-co/basic-memory/commit/db5ef7d35cc0894309c7a57b5741c9dd978526d4))
- - Automatic detection of cross-project move attempts with helpful guidance
- - Clear error messages when attempting unsupported cross-project operations
-
-### Bug Fixes
-
-- **#184**: Preserve permalinks when editing notes without frontmatter permalinks
- ([`c2f4b63`](https://github.com/basicmachines-co/basic-memory/commit/c2f4b632cf04921b1a3c2f0d43831b80c519cb31))
- - Fix permalink preservation during note editing operations
- - Ensure consistent permalink handling across different note formats
- - Maintain note identity and searchability during incremental edits
-
-- **#183**: Implement project-specific sync status checks for MCP tools
- ([`12b5152`](https://github.com/basicmachines-co/basic-memory/commit/12b51522bc953fca117fc5bc01fcb29c6ca7e13c))
- - Fix sync status reporting to correctly reflect current project state
- - Resolve inconsistencies where sync status showed global instead of project-specific information
- - Improve project isolation for sync operations and status reporting
-
-- **#180**: Handle Boolean search syntax with hyphenated terms
- ([`546e3cd`](https://github.com/basicmachines-co/basic-memory/commit/546e3cd8db98b74f746749d41887f8a213cd0b11))
- - Fix search parsing issues with hyphenated terms in Boolean queries
- - Improve search query tokenization for complex term structures
- - Enhanced search reliability for technical documentation and multi-word concepts
-
-- **#174**: Respect BASIC_MEMORY_HOME environment variable in Docker containers
- ([`9f1db23`](https://github.com/basicmachines-co/basic-memory/commit/9f1db23c78d4648e2c242ad1ee27eed85e3f3b5d))
- - Fix Docker container configuration to properly honor custom home directory settings
- - Improve containerized deployment flexibility with environment variable support
- - Ensure consistent behavior between local and containerized installations
-
-- **#168**: Scope entity queries by project_id in upsert_entity method
- ([`2a3adc1`](https://github.com/basicmachines-co/basic-memory/commit/2a3adc109a3e4d7ccd65cae4abf63d9bb2338326))
- - Fix entity isolation issues in multi-project setups
- - Prevent cross-project entity conflicts during database operations
- - Strengthen project boundary enforcement at the database level
-
-- **#166**: Handle None from_entity in Context API RelationSummary
- ([`8a065c3`](https://github.com/basicmachines-co/basic-memory/commit/8a065c32f4e41613207d29aafc952a56e3a52241))
- - Fix null pointer exceptions in relation processing
- - Improve error handling for incomplete relation data
- - Enhanced stability for knowledge graph traversal operations
-
-- **#164**: Remove log level configuration from mcp_server.run()
- ([`224e4bf`](https://github.com/basicmachines-co/basic-memory/commit/224e4bf9e4438c44a82ffc21bd1a282fe9087690))
- - Simplify MCP server startup by removing redundant log level settings
- - Fix potential logging configuration conflicts
- - Streamline server initialization process
-
-- **#162**: Ensure permalinks are generated for entities with null permalinks during move operations
- ([`f506507`](https://github.com/basicmachines-co/basic-memory/commit/f50650763dbd4322c132e4bdc959ce4bf074374b))
- - Fix move operations for entities without existing permalinks
- - Automatic permalink generation during file move operations
- - Maintain database consistency during file reorganization
-
-### Technical Improvements
-
-- **Comprehensive Test Coverage** - Extensive test suites for new features and edge cases
- - Enhanced test coverage for project-specific sync status functionality
- - Additional test scenarios for search syntax validation and edge cases
- - Integration tests for Docker CI workflow and container publishing
- - Comprehensive move operations testing with project boundary validation
-
-- **Docker CI/CD Pipeline** - Production-ready automated container publishing
- ([`74847cc`](https://github.com/basicmachines-co/basic-memory/commit/74847cc3807b0c6ed511e0d83e0d560e9f07ec44))
- - Automated Docker image building and publishing on release
- - Multi-architecture container support for AMD64 and ARM64 platforms
- - Integrated security scanning and vulnerability assessments
- - Streamlined deployment pipeline for production environments
-
-- **Release Process Improvements** - Enhanced automation and quality gates
- ([`a52ce1c`](https://github.com/basicmachines-co/basic-memory/commit/a52ce1c8605ec2cd450d1f909154172cbc30faa2))
- - Homebrew formula updates limited to stable releases only
- - Improved release automation with better quality control
- - Enhanced CI/CD pipeline reliability and error handling
-
-- **Code Quality Enhancements** - Improved error handling and validation
- - Better null safety in entity and relation processing
- - Enhanced project isolation validation throughout the codebase
- - Improved error messages and user guidance for edge cases
- - Strengthened database consistency guarantees across operations
-
-### Infrastructure
-
-- **GitHub Container Registry Integration** - Modern container infrastructure
- - Migration from Docker Hub to GitHub Container Registry (ghcr.io)
- - Improved security with integrated vulnerability scanning
- - Better integration with GitHub-based development workflow
- - Enhanced container versioning and artifact management
-
-- **Enhanced CI/CD Workflows** - Robust automated testing and deployment
- - Automated Docker image publishing on releases
- - Comprehensive test coverage validation before deployment
- - Multi-platform container building and publishing
- - Integration with GitHub's security and monitoring tools
-
-### Migration Guide
-
-This release includes several behind-the-scenes improvements and fixes. All changes are backward compatible:
-
-- **Docker Users**: Container images now served from `ghcr.io/basicmachines-co/basic-memory` instead of Docker Hub
-- **Search Users**: Enhanced search syntax handling - existing queries continue to work unchanged
-- **Multi-Project Users**: Improved project isolation - all existing projects remain fully functional
-- **All Users**: Enhanced stability and error handling - no breaking changes to existing workflows
-
-### Installation
-
-```bash
-# Latest stable release
-uv tool install basic-memory
-
-# Update existing installation
-uv tool upgrade basic-memory
-
-# Docker (new registry)
-docker pull ghcr.io/basicmachines-co/basic-memory:latest
-```
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.13.7...v0.14.0
-
-## [v0.13.7](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.13.7) — 2025-06-18
-
-
-## What's Changed
-* feat: Automatically update Homebrew by @groksrc in https://github.com/basicmachines-co/basic-memory/pull/147
-
-NOTE: This version is the same package as v0.13.6. The version bump is to test the CI and make sure the Homebrew auto-update process is completely working. Installation by Homebrew is now fully supported.
-
-**Full Changelog**: https://github.com/basicmachines-co/basic-memory/compare/v0.13.6...v0.13.7
-
-
-## [v0.13.6](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.13.6) — 2025-06-18
-
-**Bug Fixes**
-
-* fix: correct spelling error "Chose" to "Choose" in continue_conversation prompt by @groksrc in https://github.com/basicmachines-co/basic-memory/pull/141
-* fix: UNIQUE constraint failed: entity.permalink issue #139 by @groksrc in https://github.com/basicmachines-co/basic-memory/pull/140
-* fix: add entity_type parameter to write_note MCP tool by @phernandez in https://github.com/basicmachines-co/basic-memory/pull/145
-* fix: eliminate redundant database migration initialization by @phernandez in https://github.com/basicmachines-co/basic-memory/pull/146
-
-### New Contributors
-* [@groksrc](https://github.com/groksrc) made their first contribution in https://github.com/basicmachines-co/basic-memory/pull/141
-
-[Full Changelog](https://github.com/basicmachines-co/basic-memory/compare/v0.13.5...v0.13.6)
-
----
-
-## [v0.13.5](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.13.5) — 2025-06-12
-
-**Bug Fixes**
-- MCP Tools: Renamed `create_project` tool to `create_memory_project` for namespace isolation
-- Namespace: Continued namespace isolation effort to prevent conflicts with other MCP servers
-
-**Changes**
-- Tool functionality remains identical – only the name changed from `create_project` to `create_memory_project`
-- All integration tests updated to use the new tool name
-- Completes namespace isolation for project management tools alongside `list_memory_projects`
-
-[Full Changelog](https://github.com/basicmachines-co/basic-memory/compare/v0.13.4...v0.13.5)
-
----
-
-## [v0.13.4](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.13.4) — 2025-06-12
-
-**Bug Fixes**
-- MCP Tools: Renamed `list_projects` tool to `list_memory_projects` to avoid naming conflicts with other MCP servers
-- Namespace: Improved tool naming specificity for better MCP server integration and isolation
-
-**Changes**
-- Tool functionality remains identical – only the name changed from `list_projects` to `list_memory_projects`
-- All integration tests updated to use the new tool name
-- Better namespace isolation for Basic Memory MCP tools
-
-[Full Changelog](https://github.com/basicmachines-co/basic-memory/compare/v0.13.3...v0.13.4)
-
----
-
-## [v0.13.3](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.13.3) — 2025-06-12
-
-**Bug Fixes**
-- Projects: Fixed case-insensitive project switching where switching succeeded but subsequent operations failed due to session state inconsistency
-- Config: Enhanced config manager with case-insensitive project lookup using permalink-based matching
-- MCP Tools: Updated project management tools to store canonical project names from database instead of user input
-- API: Improved project service to handle both name and permalink lookups consistently
-
-[Full Changelog](https://github.com/basicmachines-co/basic-memory/compare/v0.13.2...v0.13.3)
-
----
-
-## [v0.13.2](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.13.2) — 2025-06-11
-
-**What's Changed**
-- fix: project cli commands and case sensitivity when switching projects by @phernandez
-
-[Full Changelog](https://github.com/basicmachines-co/basic-memory/compare/v0.13.1...v0.13.2)
-
----
-
-## [v0.13.1](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.13.1) — 2025-06-11
-
-**Bug Fixes**
-- CLI: Fixed `basic-memory project` project management commands that were not working in v0.13.0
-- Projects: Resolved case sensitivity issues when switching between projects that caused "Project not found" errors
-- API: Standardized CLI project command endpoints and improved error handling
-- Core: Implemented consistent project name handling using permalinks to avoid case-related conflicts
-
-**Changes**
-- Renamed `basic-memory project sync` command to `basic-memory project sync-config` for clarity
-- Improved project switching reliability across different case variations
-- Removed redundant server status messages from CLI error outputs
-
-[Full Changelog](https://github.com/basicmachines-co/basic-memory/compare/v0.13.0...v0.13.1)
diff --git a/src/pages/technical/technical-information.mdx b/src/pages/technical/technical-information.mdx
deleted file mode 100644
index 759da3d..0000000
--- a/src/pages/technical/technical-information.mdx
+++ /dev/null
@@ -1,377 +0,0 @@
----
-layout: '@/layouts/DocsLayout.astro'
-title: 'Technical Information'
-description: 'Technical details about Basic Memory implementation, architecture, licensing, and Model Context Protocol integration'
----
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step, CodeGroup, CodeTab } from '@/components'
-import SystemArchitectureTabs from '@/components/SystemArchitectureTabs'
-
-## Architecture
-
-Basic Memory consists of:
-
-
-
- Parses and indexes Markdown files
-
-
- Provides fast querying and search
-
-
- Implements the Model Context Protocol
-
-
- Command-line utilities for management
-
-
-
-
- Monitors file changes and updates the database
-
-
-
- The system follows a **file-first architecture** where all knowledge is represented in standard Markdown files and the database serves as a secondary index.
-
-
-## Model Context Protocol (MCP)
-
-Basic Memory implements the [Model Context Protocol](https://github.com/modelcontextprotocol/spec), an open standard for enabling AI models to access external tools:
-
-
-
- Common protocol for tool integration
-
-
- Basic Memory registers as a tool provider
-
-
- Enables efficient interaction with AI models
-
-
- 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):
-
-
-
- You can use, study, share, and modify the software
-
-
- Derivative works must be distributed under the same license
-
-
- Network users must be able to receive the source code
-
-
- Allowed, subject to license requirements
-
-
-
-
- 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:
-
-
-
- [https://github.com/basicmachines-co/basic-memory](https://github.com/basicmachines-co/basic-memory)
-
-
- Report bugs and request features on GitHub
-
-
- Pull requests are welcome following the contributing guidelines
-
-
- Source for this documentation is also available in the repository
-
-
-
-## Data Storage and Privacy
-
-Basic Memory is designed with privacy as a core principle:
-
-
- **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:
-
-
-
- Distinct concepts represented by Markdown documents
-
-
- Categorized facts and information about entities
-
-
- Connections between entities that form the knowledge graph
-
-
-
-This structure emerges from simple text patterns in standard Markdown:
-
-### 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]]
-```
-
-### Parsed JSON Structure
-
-
-
- ```json
- {
- "entities": [
- {
- "permalink": "coffee/coffee-brewing-methods",
- "title": "Coffee Brewing Methods",
- "file_path": "Coffee Notes/Coffee Brewing Methods.md",
- "entity_type": "note",
- "entity_metadata": {
- "title": "Coffee Brewing Methods",
- "type": "note",
- "permalink": "coffee/coffee-brewing-methods",
- "tags": "['#coffee', '#brewing', '#methods', '#demo']"
- },
- "checksum": "bfa32a0f23fa124b53f0694c344d2788b0ce50bd090b55b6d738401d2a349e4c",
- "content_type": "text/markdown",
- "observations": [
- {
- "category": "principle",
- "content": "Coffee extraction follows a predictable pattern: acids extract first, then sugars, then bitter compounds #extraction",
- "tags": [
- "extraction"
- ],
- "permalink": "coffee/coffee-brewing-methods/observations/principle/coffee-extraction-follows-a-predictable-pattern-acids-extract-first-then-sugars-then-bitter-compounds-extraction"
- },
- {
- "category": "method",
- "content": "Pour over methods generally produce cleaner, brighter cups with more distinct flavor notes #clarity",
- "tags": [
- "clarity"
- ],
- "permalink": "coffee/coffee-brewing-methods/observations/method/pour-over-methods-generally-produce-cleaner-brighter-cups-with-more-distinct-flavor-notes-clarity"
- }
- ],
- "relations": [
- {
- "from_id": "coffee/coffee-bean-origins",
- "to_id": "coffee/coffee-brewing-methods",
- "relation_type": "pairs_with",
- "permalink": "coffee/coffee-bean-origins/pairs-with/coffee/coffee-brewing-methods",
- "to_name": "Coffee Brewing Methods"
- },
- {
- "from_id": "coffee/flavor-extraction",
- "to_id": "coffee/coffee-brewing-methods",
- "relation_type": "affected_by",
- "permalink": "coffee/flavor-extraction/affected-by/coffee/coffee-brewing-methods",
- "to_name": "Coffee Brewing Methods"
- }
- ],
- "created_at": "2025-03-06T14:01:23.445071",
- "updated_at": "2025-03-06T13:34:48.563606"
- }
- ]
- }
- ```
-
-
-
-Basic Memory understands how to build context via its semantic graph.
-
-### Entity Model
-
-Basic Memory's core data model consists of:
-
-
-
- Documents in your knowledge base
-
-
- Facts or statements about entities
-
-
- Connections between entities
-
-
- Additional categorization for entities and observations
-
-
-
-The system parses Markdown files to extract this structured information while preserving the human-readable format.
-
-### Files as Source of Truth
-
-Plain Markdown files store all knowledge, making it accessible with any text editor and easy to version with git.
-
-```mermaid
-flowchart TD
- User((User)) <--> |Conversation| Claude["Claude or other LLM"]
- Claude <-->|API Calls| BMCP["Basic Memory MCP Server"]
-
- subgraph "Local Storage"
- KnowledgeFiles["Markdown Files - Source of Truth"]
- KnowledgeIndex[(Knowledge Graph SQLite Index)]
- end
-
- 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
-
-
- class Claude primary
- class BMCP secondary
- class KnowledgeFiles tertiary
- class KnowledgeIndex quaternary
- class User,Editors user
-```
-
-### SQLite Database
-
-A local SQLite database maintains the knowledge graph topology for fast queries and semantic traversal without cloud dependencies. It contains:
-
-
-
- Database tables for the knowledge graph structure
-
-
- Full text search index across the knowledge base
-
-
-
-### Sync Process
-
-The sync process:
-
-
-
- Detects changes to files in the knowledge directory
-
-
- Parses modified files to extract structured data
-
-
- Updates the SQLite database with changes
-
-
- Resolves forward references when new entities are created
-
-
- Updates the search index for fast querying
-
-
-
-### Search Engine
-
-The search functionality:
-
-
-
- Uses a combination of full-text search and semantic matching
-
-
- Indexes observations, relations, and content
-
-
- Supports wildcards and pattern matching in memory:// URLs
-
-
- Traverses the knowledge graph to follow relationships
-
-
-
-
- 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:
-
-
-
-### Performance Characteristics
-
-
-
- All operations are local with no network latency
-
-
- Handles knowledge bases with thousands of documents
-
-
- Minimal CPU and memory footprint
-
-
-
-## Development Philosophy
-
-Basic Memory embodies several key principles:
-
-
- **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
-
diff --git a/src/pages/user-guide.mdx b/src/pages/user-guide.mdx
deleted file mode 100644
index da29e82..0000000
--- a/src/pages/user-guide.mdx
+++ /dev/null
@@ -1,629 +0,0 @@
----
-layout: '@/layouts/DocsLayout.astro'
-title: 'User Guide'
-description: 'Learn how to effectively use Basic Memory in your daily workflow to build rich semantic knowledge'
----
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step } from '@/components'
-
-Once you have Basic Memory installed, here's how to make the most of it. This covers everything from creating your first notes to building a comprehensive knowledge graph.
-
-
-Using Basic Memory Cloud? Your notes are automatically synced and accessible from anywhere. See the [Cloud Guide](/guides/cloud) for setup and the [Web Editor](/guides/cloud#web-editor) for browser-based editing.
-
-
-## Basic Memory Workflow
-
-Using Basic Memory follows a natural cycle:
-
-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
-
-To create knowledge during conversations with Claude:
-
-```
-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.
-```
-
-This creates a Markdown file in your `~/basic-memory` directory with semantic markup.
-
-
-You can store your knowledge at any location you want. `~/basic-memory` is the default project location. See [Choosing Where Your Notes Are Saved](/getting-started#choosing-where-your-notes-are-saved) for more information.
-
-
-### Direct File Creation
-
-You can create files directly:
-
-1. Create a new Markdown file in your `~/basic-memory` directory
-2. Add frontmatter with title, type, and optional tags
-3. Structure content with observations and relations
-4. Save the file
-
-## Using Special Prompts
-
-Basic Memory includes several special prompts that help you leverage your knowledge base more effectively. In apps like
-Claude Desktop, these prompts trigger specific tools to search and analyze your knowledge base.
-
-### Continue Conversation
-
-Use this prompt to resume previous topics with full context:
-
-```
-"Let's continue our conversation about [topic]"
-```
-
-**What happens:**
-- Searches your knowledge base for relevant content
-- Builds context from related documents
-- Resumes with awareness of previous discussions
-
-### Recent Activity
-
-See what you've been working on recently:
-
-```
-"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 in your knowledge base:
-
-```
-"Find information about [topic]"
-```
-
-**What happens:**
-- Searches across all your documents
-- Summarizes key findings
-- Offers to explore specific documents
-
-## Working with Memory URLs
-
-Basic Memory uses special `memory://` URLs to reference knowledge:
-
-### URL Formats
-
-```
-memory://title # Reference by title
-memory://folder/title # Reference by folder and title
-memory://permalink # Reference by permalink
-memory://path/relation_type/* # Follow all relations of type
-memory://path/*/target # Find entities with relations to target
-```
-
-### Using Memory URLs
-
-Reference existing knowledge in conversations:
-
-```
-You: "Take a look at memory://coffee-brewing-methods and let's discuss improvements"
-```
-
-Claude will load that specific document and any related context.
-
-## Building Knowledge Connections
-
-### Creating Relations
-
-Use WikiLink syntax to connect knowledge:
-
-```markdown
-- implements [[Authentication System]]
-- requires [[Database Schema]]
-- relates_to [[Security Guidelines]]
-```
-
-### Common Relation Types
-
-- `implements` - One thing implements another
-- `requires` - Dependencies
-- `relates_to` - General connections
-- `part_of` - Hierarchy relationships
-- `extends` - Extensions or enhancements
-- `pairs_with` - Things that work together
-
-### Adding Observations
-
-Structure facts with semantic categories:
-
-```markdown
-- [decision] We chose JWT tokens for stateless auth
-- [requirement] Must support 2FA for sensitive operations
-- [technique] Use bcrypt for password hashing
-- [issue] Rate limiting needed for login attempts
-```
-
-## File Organization
-
-### Directory Structure
-
-```
-~/basic-memory/
-├── projects/ # Project-specific notes
-├── decisions/ # Decision records
-├── learning/ # Learning notes and research
-├── meetings/ # Meeting notes
-└── archive/ # Archived content
-```
-
-### Best Practices
-
-- Use descriptive filenames
-- Group related content in folders
-- Include dates in time-sensitive notes
-- Archive old content regularly
-
-### Controlling What Gets Indexed
-
-Basic Memory respects `.gitignore` patterns to automatically skip sensitive files and skip indexing files if needed.
-
-**How it works:**
-
-Basic Memory combines ignore patterns from two sources:
-
-1. **Global patterns**: `~/.basic-memory/.bmignore` (applied to all projects)
-2. **Project patterns**: `{project}/.gitignore` (applied to specific project)
-
-**Example `.gitignore`:**
-```gitignore
-# Sensitive files
-.env
-.env.*
-*.key
-credentials.json
-
-# Build artifacts
-node_modules/
-__pycache__/
-dist/
-build/
-
-# OS files
-.DS_Store
-Thumbs.db
-```
-
-**Benefits:**
-- **Security**: Prevents indexing sensitive files like `.env` or API keys
-- **Performance**: Skips unnecessary files like `node_modules/` or build outputs
-- **Cleaner knowledge base**: Ignores OS and editor files
-
-Files matching these patterns are automatically skipped during index sync and never indexed in your knowledge base.
-
-## Multi-Project Features
-
-### Project Management
-
-```bash
-# Create new project
-basic-memory project add work ~/work-notes
-
-# List all projects
-basic-memory project list
-```
-
-### Project Selection Workflow
-
-At the start of each conversation, the AI will:
-1. Check your available projects
-2. Suggest the most active project based on recent activity
-3. Ask which project to use for this conversation
-4. Remember your choice throughout the session
-
-**Example conversation:**
-```
-You: "Let's work on documentation"
-
-Claude: I see you have 3 projects: main, work-notes, personal
-Your most active project is work-notes
-Should I use work-notes for this task?
-
-You: "Yes, let's use work-notes"
-```
-
-**For single-project users:**
-
-If you only use one project, you can skip the selection prompt. Add this to `~/.basic-memory/config.json`:
-
-```json
-{
- "default_project": "main",
- "default_project_mode": true
-}
-```
-
-With this enabled, the AI uses your default project automatically without asking. You can still override this by explicitly specifying a different project in tool calls.
-
-### Single Project Mode
-
-For focused work sessions or automation, you can lock the MCP server to a specific project:
-
-```bash
-# Start MCP server constrained to specific project
-basic-memory mcp --project work-notes
-```
-
-This **locks** the entire MCP session to one project - the `project` parameter in tool calls will be ignored.
-
-**When to use:**
-- Automation workflows that should only access one project
-- Focused work sessions where you want to prevent accidental cross-project operations
-- Team environments with project-specific access
-
-**Key difference from Default Project Mode:**
-- **Single Project Mode**: Locks session to one project, cannot switch
-- **Default Project Mode**: Uses default automatically, but can still switch projects
-
-
-Moving notes from one project to another is not currently supported. The easiest
-thing to do is to either move the note yourself or write a new note, then delete
-the old note.
-
-
-### Enhanced Editing
-
-**Incremental editing** instead of rewriting:
-
-```
-You: "Add a troubleshooting section to my setup guide"
-Claude: [Uses edit_note to append new section]
-```
-
-**Smart file organization**:
-
-```
-You: "Move my old meeting notes to the archive folder"
-Claude: [Uses move_note with database consistency]
-```
-
-### Enhanced Search
-
-Search now includes frontmatter tags:
-
-```markdown
----
-title: Coffee Notes
-tags: [brewing, equipment, techniques]
----
-```
-
-Tags are searchable: `"Find my brewing notes"` will find this document.
-
-## Syncing and Updates
-
-### Real-time Sync (Default)
-
-Basic Memory automatically syncs file changes in real-time. No manual sync needed.
-
-### Checking Status
-
-```bash
-# View sync status
-basic-memory status
-
-# View project information
-basic-memory project info
-```
-
-## Integration Tips
-
-### With Obsidian
-
-1. Open your `~/basic-memory` directory in Obsidian
-2. Use graph view to see connections
-3. Edit files directly in Obsidian
-4. Changes are synced in real time. Ask the AI to read a note to see changes.
-
-### With Git
-
-```bash
-cd ~/basic-memory
-git init
-git add .
-git commit -m "Initial knowledge base"
-```
-
-Basic Memory files are git-friendly and work well with version control.
-
-### With Other Editors
-
-Basic Memory uses standard Markdown files that work with:
-
-- VS Code with Markdown extensions
-- Typora for rich text editing
-- Any text editor for quick edits
-- Web editors for remote access
-
-## Configuration
-
-Basic Memory can be configured through `~/.basic-memory/config.json` or environment variables. Environment variables take precedence over config file settings.
-
-### Configuration File Location
-
-**Config file:** `~/.basic-memory/config.json`
-
-**Example configuration:**
-```json
-{
- "default_project": "main",
- "default_project_mode": true,
- "log_level": "INFO",
- "sync_delay": 1000,
- "kebab_filenames": false,
- "disable_permalinks": false,
- "sync_changes": true
-}
-```
-
-### Project Settings
-
-**`projects`** - Mapping of project names to filesystem paths
-- Type: Dictionary
-- Default: `{"main": "~/basic-memory"}`
-- Example: `{"work": "~/work-notes", "personal": "~/personal-notes"}`
-
-**`default_project`** - Name of the default project
-- Type: String
-- Default: `"main"`
-- Used when no project is specified
-
-**`default_project_mode`** - Automatic project selection for single-project users
-- Type: Boolean
-- Default: `false`
-- When `true`, AI assistants automatically use default project without asking
-- Environment variable: `BASIC_MEMORY_DEFAULT_PROJECT_MODE`
-
-**`project_root`** - Constrain all projects under a root directory
-- Type: String (optional)
-- Default: `null` (projects can be created anywhere)
-- When set, all project paths must be within this directory
-- Environment variable: `BASIC_MEMORY_PROJECT_ROOT`
-
-### Sync Settings
-
-**`sync_changes`** - Enable/disable real-time synchronization
-- Type: Boolean
-- Default: `true`
-- When `false`, changes are not automatically synced
-- Environment variable: `BASIC_MEMORY_SYNC_CHANGES`
-
-**`sync_delay`** - Milliseconds to wait after changes before syncing
-- Type: Integer
-- Default: `1000` (1 second)
-- Prevents excessive sync operations during rapid edits
-- Environment variable: `BASIC_MEMORY_SYNC_DELAY`
-
-**`sync_thread_pool_size`** - Thread pool size for file I/O operations
-- Type: Integer
-- Default: `4`
-- Higher values may improve performance with many files
-- Environment variable: `BASIC_MEMORY_SYNC_THREAD_POOL_SIZE`
-
-**`skip_initialization_sync`** - Skip expensive initialization sync
-- Type: Boolean
-- Default: `false`
-- Useful for cloud/stateless deployments
-- Environment variable: `BASIC_MEMORY_SKIP_INITIALIZATION_SYNC`
-
-**`watch_project_reload_interval`** - Seconds between reloading project list
-- Type: Integer
-- Default: `30`
-- Used in watch service to detect new projects
-- Environment variable: `BASIC_MEMORY_WATCH_PROJECT_RELOAD_INTERVAL`
-
-### File Management
-
-**`kebab_filenames`** - Filename format for generated files
-- Type: Boolean
-- Default: `false`
-- `false`: Preserves spaces and special characters
-- `true`: Converts to kebab-case (consistent with permalinks)
-- Environment variable: `BASIC_MEMORY_KEBAB_FILENAMES`
-
-**`update_permalinks_on_move`** - Update permalinks when files are moved
-- Type: Boolean
-- Default: `false`
-- When `true`, permalinks are updated to reflect new file location
-- Environment variable: `BASIC_MEMORY_UPDATE_PERMALINKS_ON_MOVE`
-
-**`disable_permalinks`** - Disable automatic permalink generation
-- Type: Boolean
-- Default: `false`
-- When `true`, new notes won't have permalinks added
-- Existing permalinks still work for reading
-- Environment variable: `BASIC_MEMORY_DISABLE_PERMALINKS`
-
-### Logging
-
-**`log_level`** - Logging verbosity
-- Type: String
-- Default: `"INFO"`
-- Options: `"DEBUG"`, `"INFO"`, `"WARNING"`, `"ERROR"`
-- Environment variable: `BASIC_MEMORY_LOG_LEVEL`
-
-**Console logging** - Enable logging to console
-- Environment variable only: `BASIC_MEMORY_CONSOLE_LOGGING`
-- Values: `true`, `false`, `1`, `0`, `yes`, `no`
-- Default: `false` (logs to file only)
-
-**Log file location:** `~/.basic-memory/basic-memory-{process}.log`
-
-### Environment Variables
-
-All configuration can be overridden with environment variables using the `BASIC_MEMORY_` prefix:
-
-```bash
-# Set default project mode
-export BASIC_MEMORY_DEFAULT_PROJECT_MODE=true
-
-# Change log level
-export BASIC_MEMORY_LOG_LEVEL=DEBUG
-
-# Enable console logging
-export BASIC_MEMORY_CONSOLE_LOGGING=true
-
-# Set custom sync delay
-export BASIC_MEMORY_SYNC_DELAY=2000
-```
-
-**Special environment variables:**
-
-`BASIC_MEMORY_HOME` - Override default project location
-- Default: `~/basic-memory`
-- Used when creating the `main` project
-
-`BASIC_MEMORY_PROJECT_ROOT` - Constrain project paths
-- Optional
-- All projects must be created within this directory
-
-`BASIC_MEMORY_CLOUD_MODE` - Enable cloud mode
-- Values: `true`, `false`
-- See [Cloud Guide](/guides/cloud) for details
-
-
-### Configuration Priority
-
-Settings are applied in this order (highest to lowest priority):
-
-1. **Environment variables** (e.g., `BASIC_MEMORY_LOG_LEVEL`)
-2. **Config file** (`~/.basic-memory/config.json`)
-3. **Default values** (hardcoded in application)
-
-Example:
-```bash
-# Config file has: "log_level": "INFO"
-# Environment has: BASIC_MEMORY_LOG_LEVEL=DEBUG
-# Result: DEBUG is used (environment wins)
-```
-
-### Editing Configuration
-
-**Via config file:**
-```bash
-# Edit configuration
-vim ~/.basic-memory/config.json
-
-# Restart MCP server for changes to take effect
-# (Claude Desktop, VS Code, etc.)
-```
-
-**Via CLI:**
-```bash
-# Set default project
-basic-memory project default work
-
-# View all projects
-basic-memory project list
-
-# Check current configuration
-cat ~/.basic-memory/config.json
-```
-
-**Via environment:**
-```bash
-# Temporary (current session)
-export BASIC_MEMORY_LOG_LEVEL=DEBUG
-basic-memory status
-
-# Permanent (add to ~/.bashrc or ~/.zshrc)
-echo 'export BASIC_MEMORY_DEFAULT_PROJECT_MODE=true' >> ~/.bashrc
-```
-
-
-After changing configuration, restart your MCP client (Claude Desktop, VS Code, etc.) for changes to take effect.
-
-
-## Troubleshooting
-
-### Common Issues
-
-**Changes not syncing:**
-- Check `basic-memory status` for sync status
-- Verify file permissions
-- Reset the database with `basic-memory reset`
-
-**Claude can't find knowledge:**
-- Confirm files are in the correct project directory
-- Check frontmatter formatting
-- Try `memory://` URLs for direct references
-
-**Performance issues:**
-- Large knowledge bases may need optimization
-- Use `basic-memory project info` to check database size
-- Consider archiving old content
-
-### Getting Help
-Live help is available on our [Discord server](https://discord.gg/tyvKNccgqN) in
-the #help channel. You can also find past conversations of people who may have
-encountered a problem similar to yours.
-
-```bash
-# View all available commands
-basic-memory --help
-
-# Get help for specific commands
-basic-memory sync --help
-basic-memory project --help
-```
-
-
-## Best Practices
-
-### Knowledge Creation
-
-1. **Create Relations** - Link related concepts
-1. **Make Observations** - Structure facts with semantic categories
-1. **Create an AI Assistant Guide** - AI assistants can be guided through a reference note
-1. **Be descriptive** - Use clear titles and rich content
-1. **Add context** - Include background and reasoning
-1. **Use categories** - Structure observations semantically
-1. **Review and refine** - Edit AI-generated content for accuracy
-
-### Workflow
-
-1. **Use Special Prompts** - Start conversations contextually
-1. **Build incrementally** - Add to existing notes rather than creating duplicates
-1. **Organize regularly** - Move old content to appropriate folders
-1. **Cross-reference** - Link new content to existing knowledge
-1. **Switch projects** - Use different projects for different contexts and to create boundaries
-
-### Long-term Maintenance
-
-1. **Archive old content** - Keep active knowledge base focused
-2. **Refactor connections** - Update relations as knowledge evolves
-3. **Regular reviews** - Periodically review and update key documents
-4. **Backup regularly** - Use git or other backup solutions
-
-## Next Steps
-
-
-
- Learn the semantic patterns for structuring knowledge
-
-
- Reference for AI assistants using Basic Memory
-
-
- Complete command line reference
-
-
- Set up visual knowledge navigation
-
-
diff --git a/src/pages/whats-new.mdx b/src/pages/whats-new.mdx
deleted file mode 100644
index d180296..0000000
--- a/src/pages/whats-new.mdx
+++ /dev/null
@@ -1,918 +0,0 @@
----
-layout: '@/layouts/DocsLayout.astro'
-title: "What's New in Basic Memory"
-description: 'Latest features and improvements in Basic Memory - context-aware wiki links, directory operations, and cloud sync.'
----
-
-import { Card, CardGroup, Info, Warning, Note, Tip, Accordion, AccordionItem, Steps, Step } from '@/components'
-
-## Basic Memory Cloud
-
-
-[Basic Memory Cloud](/guides/cloud) is live! Now accessible from everywhere, in the Cloud. [Sign up ->](https://basicmemory.com/beta) with a 7 day free trial.
-
-
-Work with your knowledge base across multiple devices using cloud sync and storage.
-
-## v0.18.0
-
-Basic Memory v0.18.0 introduces context-aware wiki link resolution, directory operations, and improved cloud routing.
-
-
-**Key improvements:**
-- Context-aware wiki link resolution with `source_path` support
-- Directory support for `move_note` and `delete_note` tools
-- Local MCP cloud mode routing for simultaneous local/cloud usage
-- MCP prompt rendering fixes
-
-
-### Context-Aware Wiki Link Resolution
-
-Wiki links now resolve intelligently based on where they appear in your knowledge base.
-
-**Relative path resolution:**
-When you write `[[nested/note]]` in a file at `folder/file.md`, Basic Memory first looks for `folder/nested/note.md` before searching globally.
-
-**Proximity-based resolution:**
-If you have notes with the same title in different folders, links resolve to the note closest to your current location. A link to `[[Meeting Notes]]` from `projects/alpha/tasks.md` prefers `projects/alpha/Meeting Notes.md` over `projects/beta/Meeting Notes.md`.
-
-**Strict mode:**
-The resolve endpoint now supports strict mode to disable fuzzy search fallback, ensuring exact matches only.
-
-### Directory Operations
-
-Move and delete entire folders of notes with database consistency:
-
-```python
-# Move all notes in a directory
-move_note("old-folder", "new-folder", is_directory=True)
-
-# Delete all notes in a directory
-delete_note("archive/old-project", is_directory=True)
-```
-
-### Local/Cloud Routing
-
-Use local Claude Desktop and cloud-based clients simultaneously:
-
-```bash
-# Force local routing (when cloud mode is enabled)
-basic-memory status --local
-basic-memory project list --local
-
-# Force cloud routing
-basic-memory status --cloud
-```
-
-The local MCP server (`basic-memory mcp`) automatically uses local routing, so you can run both without conflicts.
-
-See the [complete v0.18.0 changelog](/latest-releases) for full details.
-
----
-
-## v0.17.0
-
-Basic Memory v0.17.0 completes the API v2 migration, adds auto-formatting, and improves CLI stability.
-
-
-**Key improvements:**
-- All MCP tools now use API v2 endpoints for improved performance
-- Auto-format files on save with built-in Python formatter
-- CLI commands no longer hang on exit
-- Anonymous usage telemetry (Homebrew-style opt-out)
-
-
-### API v2 Migration Complete
-
-Phase 2 of the API v2 migration is complete. All MCP tools now use the new v2 endpoints, providing:
-
-- **Improved performance** - Optimized endpoints for faster responses
-- **Better scalability** - Foundation for future API enhancements
-- **Backward compatibility** - Existing integrations continue to work
-
-### Auto-Format on Save
-
-Basic Memory now includes a built-in Python formatter that automatically formats files when saved:
-
-```bash
-# Files are automatically formatted on save
-# No external tools required
-```
-
-This ensures consistent formatting across your knowledge base without needing to configure external formatters.
-
-### CLI Stability Improvements
-
-Several improvements make the CLI more reliable:
-
-- **No more hanging** - Commands exit cleanly after completion
-- **Rclone version detection** - Automatically checks for `--create-empty-src-dirs` support
-- **Better ChatGPT import** - Handles null titles gracefully
-
-### Anonymous Telemetry
-
-Basic Memory now includes opt-out anonymous telemetry (similar to Homebrew) to help improve the product:
-
-- No personal data collected
-- Privacy-respecting design
-- Easy to disable via environment variable
-
-```bash
-# Disable telemetry
-export BASIC_MEMORY_NO_TELEMETRY=1
-```
-
-See the [complete v0.17.0 changelog](/latest-releases) for full details.
-
----
-
-## v0.16.0
-
-Basic Memory v0.16.0 focuses on cloud sync reliability, Windows platform support, and overall system robustness.
-
-
-**Key improvements:**
-- Simplified and more reliable cloud sync with project-scoped rclone configuration
-- Significantly improved Windows compatibility with Unicode fixes
-- Circuit breaker pattern prevents cascading sync failures
-- Better memory management for large knowledge bases
-- Enhanced cloud upload controls and debugging
-
-
-### Cloud Sync Enhancements
-
-**Simplified project-scoped sync:**
-The cloud sync architecture has been simplified with project-level rclone configuration, making sync operations more reliable and easier to troubleshoot.
-
-**What you'll experience:**
-- More consistent sync behavior across different environments
-- Better error messages when sync issues occur
-- Improved sync performance and reliability
-
-**Background sync operations:**
-Long-running sync operations can now run in the background, preventing API timeouts and improving overall system responsiveness.
-
-```bash
-# Sync runs in background, returns immediately
-bm project bisync --name main --background
-```
-
-**Circuit breaker for resilience:**
-Automatic failure recovery prevents cascading errors during sync operations. Transient network issues no longer cause complete sync failures.
-
-**Enhanced upload controls:**
-```bash
-# Verbose logging for troubleshooting
-bm cloud upload ~/notes --project main --verbose
-
-# Bypass gitignore when needed
-bm cloud upload ~/all-files --project archive --no-gitignore
-```
-
-### Windows Platform Support
-
-v0.16.0 includes major improvements for Windows users:
-
-**Unicode encoding fixes:**
-- Resolves terminal encoding issues on Windows
-- Better handling of international characters in filenames and content
-- ASCII characters replace Unicode symbols for better compatibility
-
-**Improved rclone integration:**
-- Better path handling for Windows filesystem conventions
-- More reliable cloud sync on Windows
-- Fixed edge cases with Windows-specific path separators
-
-### Reliability Improvements
-
-**Memory optimization for large projects:**
-Prevents out-of-memory errors when syncing large knowledge bases. The sync process now handles projects with thousands of files efficiently.
-
-**Better YAML frontmatter handling:**
-- Automatically quotes string values to handle special characters
-- Normalizes frontmatter types to prevent parsing errors
-- More robust handling of edge cases in markdown files
-
-**Improved sync accuracy:**
-Uses filesystem timestamps instead of database operation times for better detection of external file modifications. This makes sync more reliable when editing files in external editors like Obsidian or VS Code.
-
-### API & Tool Improvements
-
-**Clearer write_note parameter:**
-The `entity_type` parameter has been renamed to `note_type` for better clarity and consistency.
-
-```python
-# v0.16.0 (new)
-write_note("My Note", "Content", "folder", note_type="note")
-
-# v0.15.x (old, still supported)
-write_note("My Note", "Content", "folder", entity_type="note")
-```
-
-**Safer project deletion:**
-```bash
-# Delete project configuration only (preserves files)
-bm project remove work
-
-# Delete project AND all notes
-bm project remove work --delete-notes
-```
-
-**Better error handling:**
-- Graceful handling of malformed YAML frontmatter
-- Better recovery from missing or incomplete metadata
-- More informative error messages
-
-### Bug Fixes
-
-- Archive files (zip, tar, gz) automatically excluded from cloud uploads
-- Duplicate headers no longer created when replacing note sections
-- Deleted projects won't be recreated by background sync
-- Better handling of empty or null titles in frontmatter
-- Database constraint violations resolved during sync operations
-
-See the [complete v0.16.0 changelog](https://github.com/basicmachines-co/basic-memory/blob/main/CHANGELOG.md) for full details.
-
----
-
-## v0.15.0
-
-Basic Memory v0.15.0 introduces Cloud projects, multi-project conversation improvements, performance optimizations, and Python 3.13 support.
-
-#### Learn More
-
-See the [Basic Memory Cloud](/guides/cloud-cli) guide for complete documentation including:
-- Using cloud mode via the command line
-- Managing projects
-- Uploading notes
-- Viewing notes via the notes web ui
-
-### Multi-Project Conversations
-
-AI assistants now ask which project to use at the start of conversations.
-
-#### What You'll Experience
-
-When starting a new conversation, the AI will:
-
-1. Check for available projects
-2. Suggest the most active project based on recent activity
-3. Ask which project to use
-4. Remember your choice throughout the conversation
-
-**Example conversation:**
-```
-You: "Let's work on documentation"
-
-Claude: I see you have 3 projects: main, work-docs, creative-writing
-Your most active project is work-docs (15 recent updates)
-Should I use work-docs for this task?
-
-You: "Yes"
-
-Claude: I'll use work-docs for this session.
-[All subsequent operations use work-docs project]
-```
-
-#### Default Project Setup
-
-If you only use one project, enable automatic project selection:
-
-**Configuration** (`~/.basic-memory/config.json`):
-```json
-{
- "default_project": "main",
- "default_project_mode": true
-}
-```
-
-With this enabled:
-- AI uses your default project automatically when no project is specified
-- You can still override by explicitly passing a different project to tools
-- Suitable for users who primarily work in one project
-
-#### Single Project Mode
-
-Lock an MCP session to a specific project using the `--project` flag:
-
-```bash
-basic-memory mcp --project work-notes
-```
-
-**Key behavior:** All operations in this session use the specified project - the `project` parameter in tool calls is ignored. Useful for automation, security, and focused work sessions where you want to prevent accidental cross-project operations.
-
-#### What Changed from v0.14.x
-
-**Removed tools:**
-- `switch_project()` - no longer available
-- `get_current_project()` - no longer available
-
-**New behavior:**
-- AI asks which project to use at conversation start
-- Project selection remembered throughout session
-- `list_memory_projects()` shows available projects with activity suggestions
-- `recent_activity()` provides cross-project discovery
-
-All MCP tools now accept an explicit `project` parameter. See [Technical Information](/technical/technical-information) for architecture details.
-
-### Performance Improvements
-
-v0.15.0 includes significant performance optimizations across API operations, database queries, and startup processes.
-
-#### API Optimizations
-
-API response times improved 3-4x through query optimization and batch loading. The `read_note` endpoint now completes in 75ms instead of 250ms, while `build_context` operations with depth=2 run in 320ms instead of 1200ms.
-
-**What changed:**
-- Single optimized queries replace multiple separate database calls
-- Batch loading eliminates N+1 query problems
-- Eager loading strategies reduce round trips
-
-Database queries for typical MCP tool calls dropped from 15-20 queries to 3-5 queries (75% reduction).
-
-#### Startup Performance
-
-The MCP server now starts instantly (<1 second) regardless of knowledge base size.
-Previously, large knowledge bases with 1000+ entities could have slow startup times.
-
-**Background relation resolution:**
-- Entity relations resolve in background threads
-- Server accepts requests immediately on startup
-- Relations complete asynchronously without blocking operations
-
-#### Database Performance
-
-SQLite now uses Write-Ahead Logging (WAL) mode by default, enabling concurrent reads and writes. This feature is particularly relevant to Windows users.
-
-**Performance gains:**
-- 2-3x faster write operations
-- Readers don't block writers (and vice versa)
-- Bulk operations complete in seconds instead of minutes
-
-### Platform Support
-
-#### Python 3.13
-
-Basic Memory now supports Python 3.13. All dependencies have been verified compatible, and Python 3.13 is included in the CI test matrix.
-
-**Supported versions:** Python 3.10, 3.11, 3.12, 3.13
-
-#### .gitignore Support
-
-The sync process now respects `.gitignore` patterns, automatically skipping files during synchronization.
-
-**What you'll notice:**
-- Sensitive files (`.env`, credentials) excluded from sync
-- Build artifacts (`node_modules/`, `__pycache__/`) not indexed
-- OS and editor files (`.DS_Store`, `.vscode/`) ignored
-
-Create a `.gitignore` in your project root to control which files are synced.
-See [Controlling What gets synced](user-guide#controlling-what-gets-synced) in the user guide.
-
-### Bug Fixes
-
-**v0.15.0** resolves numerous bugs related to entity conflicts, URL handling, file operations, and platform compatibility.
-
-**Key fixes:**
-- Entity upsert conflicts resolved through database-level conflict handling
-- `memory://` URLs with underscores now properly normalized to hyphens
-- `move_note` automatically handles file extensions (works with or without `.md`)
-- `.env` file auto-loading removed for compatibility with code repos using env files
-- Minimum timeframe enforcement prevents timezone edge cases
-- DateTime fields include proper JSON schema format for MCP validation
-
-See the [complete changelog](https://github.com/basicmachines-co/basic-memory/blob/main/CHANGELOG.md) or the [full v0.15.0 release notes](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.15.0).
-
-## v0.14.0
-
-### Advanced Note Editing
-
-**Edit notes incrementally without rewriting entire documents:**
-
-#### Append Operations
-
-**Adding to existing meeting notes:**
-```
-You: "Add today's action items to our project meeting notes"
-
-Claude: [Uses edit_note with append operation]
-✓ Added to "Weekly Project Meeting Notes":
-
-## Action Items - January 15, 2025
-- [ ] Sarah: Update API documentation by Friday
-- [ ] Mike: Review security implementation
-- [ ] Team: Prepare demo for client meeting next week
-- [ ] Jenny: Coordinate user testing sessions
-
-[Content appended to existing note without affecting previous sections]
-```
-
-**Building research over time:**
-```
-You: "Add the new study findings to my climate research note"
-
-Claude: [Appends new research section]
-✓ Added to "Climate Change Solutions Research":
-
-## Recent Studies - January 2025
-- [study] MIT carbon capture efficiency improved 40% #breakthrough
-- [finding] Solar panel costs dropped 15% year-over-year #economics
-- [policy] EU carbon tax showing measurable emissions reduction #policy-impact
-
-Relations automatically updated to connect with existing energy and policy notes.
-```
-
-#### Prepend Operations
-
-**Adding timestamps to journals:**
-```
-You: "Add today's entry to my learning journal"
-
-Claude: [Uses prepend to add newest entry at top]
-✓ Added to beginning of "Daily Learning Journal":
-
-## January 15, 2025 - React Performance Insights
-- [discovery] useMemo doesn't help with props.children changes #react-gotcha
-- [technique] React.Children.count for shallow comparison #workaround
-- [pattern] Custom hooks for complex state logic #architecture
-
-[New entry added above previous entries, maintaining chronological order]
-```
-
-#### Section Replacement
-
-**Updating specific documentation sections:**
-```
-You: "Update the deployment section in our API docs with the new Docker setup"
-
-Claude: [Replaces specific section under ## Deployment header]
-✓ Updated "API Documentation" → ## Deployment section:
-
-
-## 🐳 Docker Support
-
-**Run Basic Memory in Docker Desktop or your own container runtime:**
-
-Update the docker-compose.yml to set the path to your knowledge folder and then:
-```
-$ docker-compose up
-```
-
-Basic Memory now supports SSE and can be used with [n8n ↗️](https://n8n.io) workflows.
-
-
-### Docker Setup (Updated)
-# Build the application
-docker build -t my-api:latest .
-
-# Run with environment variables
-docker run -d \
- -p 8000:8000 \
- -e DATABASE_URL=postgresql://... \
- -e REDIS_URL=redis://... \
- my-api:latest
-
-### Environment Variables
-- `DATABASE_URL`: PostgreSQL connection string
-- `REDIS_URL`: Redis cache connection
-- `JWT_SECRET`: Secret key for token signing
-
-[Only the deployment section was updated, rest of documentation unchanged]
-```
-
-#### Find and Replace
-
-**Version updates across documentation:**
-```
-You: "Update all references to v0.12.0 to v0.13.0 in the configuration guide"
-
-Claude: [Uses find_replace with validation]
-✓ Updated "Configuration Guide":
-Found and replaced 3 occurrences of "v0.12.0" with "v0.13.0"
-
-Changes made:
-- Line 23: Version requirement updated
-- Line 45: Docker image tag updated
-- Line 67: Example configuration updated
-```
-
-### Smart File Management
-
-**Move and organize notes with full database consistency:**
-
-#### Organizing Project Documentation
-
-**Moving notes to appropriate folders:**
-```
-You: "Move all my old meeting notes to an archive folder"
-
-Claude: [Moves files and updates database]
-✓ Moved 8 meeting notes to archive/:
-- meeting-2024-12-01.md → archive/meetings/meeting-2024-12-01.md
-- meeting-2024-12-08.md → archive/meetings/meeting-2024-12-08.md
-- weekly-standup-notes.md → archive/meetings/weekly-standup-notes.md
-
-Database updated: permalinks, search index, and relations preserved.
-All links to these notes remain functional.
-```
-
-**Reorganizing research by topic:**
-```
-You: "Move my AI research notes into a dedicated ai-research folder"
-
-Claude: [Creates folder structure and moves files]
-✓ Created folder: ai-research/
-✓ Moved 12 AI-related notes:
-- neural-networks.md → ai-research/neural-networks.md
-- transformer-architecture.md → ai-research/transformer-architecture.md
-- ai-ethics-considerations.md → ai-research/ethics/ai-ethics-considerations.md
-
-Search functionality maintained, all relations preserved.
-```
-
-#### Renaming and Restructuring
-
-**Renaming notes for clarity:**
-```
-You: "Rename 'temp-notes.md' to 'database-design-decisions.md'"
-
-Claude: [Renames file and updates all references]
-✓ Renamed: temp-notes.md → database-design-decisions.md
-✓ Updated permalink: /temp-notes → /database-design-decisions
-✓ Search index updated
-✓ All internal links automatically updated
-```
-
-### View Notes as Formatted Artifacts
-
-**Display notes as html formatted artifacts in Claude Desktop:**
-
-#### Technical Documentation
-
-```
-You: "Show me the API documentation as a formatted artifact"
-
-Claude: [Uses view_note tool to display formatted artifact]
-```
-
-*Claude displays a html formatted artifact with:*
-- Proper heading hierarchy
-- Syntax-highlighted code blocks
-- Organized sections and subsections
-- Typography and spacing
-- Clickable links and references
-
-#### Creative Writing Projects
-
-```
-You: "Display my character development notes as an artifact"
-
-Claude: [Creates formatted view of character notes]
-```
-
-*Result: Readable format showing:*
-- Character profiles with clear sections
-- Relationship maps and connections
-- Story arc progression
-- Research and background details
-
-#### Research Summaries
-
-```
-You: "View my climate research compilation as an artifact"
-
-Claude: [Formats research note]
-```
-
-*Displays: Research document with:*
-- Executive summary
-- Organized findings by category
-- Source citations and links
-- Visual hierarchy of information
-
-### Enhanced Search & Discovery
-
-**Find content more easily with frontmatter tag search:**
-
-#### Searchable Frontmatter Tags
-
-**Before v0.13.0** - Only content was searchable:
-```markdown
----
-title: Coffee Brewing Methods
-tags: [coffee, brewing, equipment, chemex]
----
-
-# Coffee Brewing Methods
-Pour-over techniques for better coffee...
-```
-*Search for "chemex" would find nothing*
-
-**v0.13.0** - Tags are now indexed and searchable:
-```
-You: "Search for all my chemex notes"
-
-Claude: [Finds notes with 'chemex' in tags or content]
-Found 4 notes mentioning 'chemex':
-• Coffee Brewing Methods (tag match)
-• Morning Routine - Coffee Setup (content match)
-• Kitchen Equipment Reviews (tag match)
-• Weekend Coffee Experiments (content match)
-```
-
-#### Better Content Discovery
-
-**Topic-based discovery:**
-```
-You: "Find all my notes about productivity"
-
-Claude: [Searches across titles, content, tags, and metadata]
-Found 12 productivity-related notes:
-
-By Tags:
-• Daily Habits Tracking [productivity, habits]
-• Time Management Systems [productivity, time-management]
-• Focus Techniques [productivity, deep-work]
-
-By Content:
-• Weekly Reviews (mentions productivity goals)
-• Book Notes: Deep Work (productivity principles)
-• Morning Routine (productivity habits)
-```
-
-**Project-scoped search:**
-```
-You: "Search for 'authentication' in my work project only"
-
-Claude: [Searches within current work project]
-Found 6 authentication-related notes in work-notes project:
-• API Authentication Strategy
-• OAuth Implementation Guide
-• Security Review - Auth System
-• User Session Management
-• Password Reset Flow
-• Two-Factor Authentication Setup
-```
-
-### Unified Database Architecture
-
-**Single app-level database for better performance and project management:**
-
-#### Automatic Migration
-
-**Seamless upgrade from v0.12.x:**
-
-After upgrading, Basic Memory will re-index all your project notes into a single project. Basic Memory uses your files
-as the source of truth, so there is no risk of data loss. You can see the status any time.
-
-```
-You: what is the sync status?
-
-Claude:
-
-**Current Status**: 🔄 Syncing 1 projects (231/331 files, 70%)
-**System Ready**: 🔄 Processing
-
-🔄 **File synchronization in progress**
-
-Basic Memory is automatically processing all configured projects and building knowledge graphs.
-This typically takes 1-3 minutes depending on the amount of content.
-
-**Currently Processing:**
-- **main**: Processing new files (231/331, 70%)
-
-**What's happening:**
-- Scanning and indexing markdown files
-- Building entity and relationship graphs
-- Setting up full-text search indexes
-- Processing file changes and updates
-
-**What you can do:**
-- Wait for automatic processing to complete - no action needed
-- Use this tool again to check progress
-- Simple operations may work already
-- All projects will be available once sync finishes
-
-**Note**: All configured projects will be automatically synced during startup.
-You don't need to manually switch projects - Basic Memory handles this for you.
-```
-
-#### Better Project Isolation
-
-**Secure project boundaries:**
-```
-You: "Switch to work-notes project"
-Claude: ✓ Switched to work-notes
-
-You: "Search for client information"
-Claude: [Searches only within work-notes project]
-Found 3 client-related notes in work-notes:
-• Client Requirements Document
-• Meeting Notes - Client Kickoff
-• Client Feedback Analysis
-
-[Personal project notes remain completely isolated]
-```
-
-### Complete MCP Tool Suite
-
-#### New Project Management Tools
-
-**Discover and manage projects:**
-```python
-# List all available projects
-list_projects()
-→ Shows: main (default, current), work-notes, personal-journal
-
-# Project discovery and management
-list_memory_projects()
-→ Shows all projects with guidance for session management
-
-# Project-specific operations (stateless architecture)
-write_note("My Note", "Content", "folder", project="work-notes")
-→ Creates note in specified project
-
-search_notes("query", project="work-notes")
-→ Searches within specified project only
-
-# Check sync status
-sync_status()
-→ Shows: file sync status, background operations, any issues
-```
-
-#### Enhanced Note Operations
-
-**Incremental editing tools:**
-```python
-# Append new content
-edit_note("meeting-notes", "append", "\n## New Action Items\n- Task 1\n- Task 2")
-
-# Prepend timestamp
-edit_note("journal", "prepend", "# January 15, 2025\nToday's insights...")
-
-# Replace specific section
-edit_note("api-docs", "replace_section", "New deployment steps...", section="## Deployment")
-
-# Find and replace with validation
-edit_note("config", "find_replace", "v0.13.0", find_text="v0.12.0", expected_replacements=3)
-```
-
-**File management tools:**
-```python
-# Move notes with database consistency
-move_note("old-location.md", "new-folder/better-name.md")
-
-# View formatted artifacts
-view_note("important-document")
-→ Displays note as formatted artifact in Claude Desktop
-```
-
-### Real-World Workflows
-
-#### Software Development Team
-
-**Morning standup routine:**
-```
-You: "Switch to our team project and show yesterday's progress"
-
-Claude: [Switches to team project]
-✓ Switched to team-project
-
-Recent activity (last 24 hours):
-• Updated API documentation with new authentication endpoints
-• Added deployment guide for Docker setup
-• Meeting notes from client feedback session
-• Bug tracking for payment processing issues
-
-You: "Add today's standup notes"
-
-Claude: [Creates structured standup note]
-✓ Created "Daily Standup - January 15, 2025"
-
-## Team Updates
-- Sarah: Completed user authentication module, starting on password reset
-- Mike: Fixed payment processing bug, investigating performance issues
-- Jenny: Client demo went well, gathering requirements for Phase 2
-
-## Blockers
-- Need DevOps review for production deployment
-- Waiting on client approval for UI changes
-
-[Automatically linked to previous standup notes and relevant project documentation]
-```
-
-#### Academic Researcher
-
-**Research session workflow:**
-```
-You: "Switch to my research project and add today's paper notes"
-
-Claude: [Switches to research context]
-✓ Switched to phd-research project
-
-You: "Create detailed notes on the transformer architecture paper"
-
-Claude: [Creates research note]
-✓ Created "Attention Is All You Need - Paper Analysis"
-
-## Key Contributions
-- [innovation] Self-attention mechanism replaces RNN/CNN architectures #breakthrough
-- [performance] Parallelizable training reduces computation time significantly #efficiency
-- [impact] Enables larger models and better sequence understanding #scaling
-
-## Technical Details
-- [architecture] Multi-head attention with scaled dot-product attention #technical
-- [training] Position encoding for sequence order without recurrence #implementation
-- [results] BLEU score improvements on translation tasks #evaluation
-
-## Relations
-- revolutionizes [[Natural Language Processing]]
-- enables [[Large Language Models]]
-- influences [[Computer Vision - Vision Transformers]]
-
-[Automatically connects to existing AI research and methodology notes]
-
-You: "Move this to my 'foundational-papers' folder"
-
-Claude: [Organizes research]
-✓ Moved to foundational-papers/attention-is-all-you-need.md
-✓ Updated research index and cross-references
-```
-
-#### Creative Writer
-
-**Novel planning session:**
-```
-You: "Switch to my novel project and update character development"
-
-Claude: [Switches to creative writing project]
-✓ Switched to sci-fi-novel project
-
-You: "Add new backstory details to Sarah Chen's character profile"
-
-Claude: [Uses append to add to existing character note]
-✓ Updated "Sarah Chen - Protagonist Character Profile"
-
-## New Backstory Details
-- [background] Lost younger brother in early neural implant experiment #trauma
-- [motivation] Brother's death drives her investigation into NeuroLink Corp #personal-stakes
-- [skill] Developed hacking abilities after brother's accident #character-development
-- [relationship] Estranged from father who worked for competing tech company #family-conflict
-
-## Character Arc Implications
-- [growth] Must overcome trust issues to work with allies #emotional-journey
-- [conflict] Personal vendetta vs. broader social justice #internal-struggle
-
-Relations updated:
-- drives [[Main Plot - Corporate Conspiracy]]
-- connects_to [[NeuroLink Corporation - Antagonist]]
-- influences [[Theme - Technology vs Humanity]]
-
-You: "View the character profile as a formatted artifact"
-
-Claude: [Displays character sheet]
-[Shows organized character profile with clear sections, relationship maps, and story connections]
-```
-
-#### Personal Knowledge Management
-
-**Weekly life review:**
-```
-You: "Switch to my personal project and create this week's reflection"
-
-Claude: [Switches to personal knowledge context]
-✓ Switched to personal-life project
-
-You: "Review this week's notes and create a summary of patterns and insights"
-
-Claude: [Analyzes recent personal notes]
-✓ Created "Weekly Reflection - January 15, 2025"
-
-## This Week's Patterns
-- [energy] Most productive mornings when I exercise first #health-performance-link
-- [social] Deep conversations with friends boost mood for 2+ days #relationship-impact
-- [work] Finished projects faster when I break tasks into 25-minute chunks #productivity-technique
-
-## Growth Areas Identified
-- [challenge] Procrastination increases when overwhelmed - need better task management #self-awareness
-- [opportunity] Reading before bed improves sleep quality #habit-optimization
-
-## Goal Progress
-- [fitness] Ran 3 times this week (goal: 3x) ✓ #achievement
-- [learning] Completed 2 Spanish lessons (goal: 3x) #partial-progress
-- [creativity] No creative writing this week #missed-goal
-
-## Relations
-- builds_on [[Monthly Goals - January 2025]]
-- informs [[Habit Tracking and Optimization]]
-- connects_to [[Work-Life Balance Strategies]]
-
-You: "Move my old reflections to an archive folder"
-
-Claude: [Organizes personal history]
-✓ Moved 12 reflection notes to archive/reflections/
-✓ Maintained chronological order and cross-references
-✓ Updated personal development timeline
-```
-
-[Get started with Basic Memory →](/getting-started)
diff --git a/src/styles/global.css b/src/styles/global.css
deleted file mode 100644
index fdf1369..0000000
--- a/src/styles/global.css
+++ /dev/null
@@ -1,355 +0,0 @@
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-
-@layer base {
- :root {
- --background: 0 0% 100%;
- --foreground: 222.2 84% 4.9%;
- --card: 0 0% 100%;
- --card-foreground: 222.2 84% 4.9%;
- --popover: 0 0% 100%;
- --popover-foreground: 222.2 84% 4.9%;
- --primary: 0 0% 0%;
- --primary-foreground: 0 0% 100%;
- --secondary: 210 40% 96.1%;
- --secondary-foreground: 222.2 47.4% 11.2%;
- --muted: 210 40% 96.1%;
- --muted-foreground: 215.4 16.3% 46.9%;
- --accent: 210 40% 96.1%;
- --accent-foreground: 222.2 47.4% 11.2%;
- --destructive: 0 84.2% 60.2%;
- --destructive-foreground: 210 40% 98%;
- --border: 214.3 31.8% 91.4%;
- --input: 214.3 31.8% 91.4%;
- --ring: 0 0% 0%;
- --radius: 0.5rem;
- }
-
- .dark {
- --background: 222.2 84% 4.9%;
- --foreground: 210 40% 98%;
- --card: 222.2 84% 4.9%;
- --card-foreground: 210 40% 98%;
- --popover: 222.2 84% 4.9%;
- --popover-foreground: 210 40% 98%;
- --primary: 0 0% 100%;
- --primary-foreground: 0 0% 0%;
- --secondary: 217.2 32.6% 17.5%;
- --secondary-foreground: 210 40% 98%;
- --muted: 217.2 32.6% 17.5%;
- --muted-foreground: 215 20.2% 65.1%;
- --accent: 217.2 32.6% 17.5%;
- --accent-foreground: 210 40% 98%;
- --destructive: 0 62.8% 30.6%;
- --destructive-foreground: 210 40% 98%;
- --border: 217.2 32.6% 17.5%;
- --input: 217.2 32.6% 17.5%;
- --ring: 0 0% 100%;
- }
-}
-
-@layer base {
- * {
- @apply border-border;
- }
- body {
- @apply bg-background text-foreground;
- font-family: 'Inter', sans-serif;
- font-feature-settings: "rlig" 1, "calt" 1;
- }
-
- /* Typography */
- h1 {
- @apply scroll-m-20 text-3xl font-semibold tracking-tight mb-6;
- }
-
- h2 {
- @apply scroll-m-20 text-3xl font-medium tracking-tight first:mt-0 mt-12 mb-4;
- }
-
- h3 {
- @apply scroll-m-20 text-2xl font-medium tracking-tight;
- }
-
- /* Article content h3 spacing - only applies to h3 in main content */
- article > h3:not([class*="text-lg"]) {
- @apply mt-8 mb-4;
- }
-
- h4 {
- @apply scroll-m-20 text-xl font-medium tracking-tight mt-6 mb-3;
- }
-
- p {
- @apply leading-7 [&:not(:first-child)]:mt-6 text-gray-700 dark:text-gray-300;
- font-size: 16px;
- }
-
- blockquote {
- @apply mt-6 border-l-2 pl-6 italic;
- }
-
- ul {
- @apply my-4 ml-6 list-disc [&>li]:mt-2;
- }
-
- ol {
- @apply my-6 ml-6 list-decimal [&>li]:mt-2;
- }
-
- li {
- @apply text-gray-700 dark:text-gray-300;
- }
-
- code {
- @apply relative rounded bg-muted px-[0.3rem] py-[0.2rem] font-mono text-sm;
- }
-
- pre {
- @apply mb-4 mt-6 overflow-x-auto rounded-lg bg-gray-100/50 dark:bg-gray-900 p-4 pr-12 border border-gray-200 dark:border-gray-800;
- }
-
- pre code {
- @apply bg-transparent p-0 text-gray-900 dark:text-gray-100 font-light;
- white-space: pre-wrap;
- word-wrap: break-word;
- }
-
- /* Code block wrapper */
- .code-block-wrapper {
- @apply relative;
- }
-
- .code-block-wrapper .copy-button {
- @apply absolute top-2 right-2 p-2 rounded-md bg-transparent text-gray-400 hover:text-gray-600 dark:text-gray-500 dark:hover:text-gray-300 transition-colors;
- }
-
- .code-block-wrapper .copy-button.copied {
- @apply text-green-600 dark:text-green-400;
- }
-
- /* Markdown syntax highlighting */
- pre code .line {
- display: inline-block;
- width: 100%;
- }
-
- /* Markdown headings in code blocks */
- pre code .token.title,
- pre code .token.heading {
- @apply text-blue-600 dark:text-blue-400 font-semibold;
- }
-
- pre code .token.punctuation.heading {
- @apply text-blue-600 dark:text-blue-400;
- }
-
- /* Markdown links */
- pre code .token.link,
- pre code .token.url {
- @apply text-purple-600 dark:text-purple-400;
- }
-
- /* Markdown bold/italic */
- pre code .token.bold {
- @apply font-semibold;
- }
-
- pre code .token.italic {
- font-style: italic;
- }
-
- /* Markdown lists */
- pre code .token.list {
- @apply text-gray-600 dark:text-gray-400;
- }
-
- /* Markdown code */
- pre code .token.code {
- @apply bg-gray-200 dark:bg-gray-800 px-1 rounded;
- }
-
- /* Override inline styles for Shiki code blocks in dark mode */
- .dark pre.astro-code {
- background-color: rgb(17 24 39) !important; /* dark:bg-gray-900 */
- }
-
- .dark pre.astro-code,
- .dark pre.astro-code span {
- color: rgb(243 244 246) !important; /* dark:text-gray-100 */
- }
-
- /* Preserve token colors in dark mode */
- .dark pre.astro-code .token.keyword {
- color: rgb(147 197 253) !important; /* blue-300 */
- }
-
- .dark pre.astro-code .token.string {
- color: rgb(134 239 172) !important; /* green-300 */
- }
-
- .dark pre.astro-code .token.comment {
- color: rgb(156 163 175) !important; /* gray-400 */
- }
-
- .dark pre.astro-code .token.function {
- color: rgb(252 211 77) !important; /* yellow-300 */
- }
-
- .dark pre.astro-code .token.number {
- color: rgb(251 146 60) !important; /* orange-400 */
- }
-
- .dark pre.astro-code .token.operator,
- .dark pre.astro-code .token.punctuation {
- color: rgb(209 213 219) !important; /* gray-300 */
- }
-
- /* Default link styles for content */
- a {
- @apply font-medium text-primary hover:text-primary/80;
- }
-
- /* Article content links with proper dark mode colors */
- article a,
- main p a,
- main li a {
- @apply font-medium text-gray-900 dark:text-gray-100 hover:text-gray-700 dark:hover:text-gray-300 underline underline-offset-2;
- }
-
- /* Remove underlines from specific areas */
- header a,
- nav a,
- aside a,
- footer a,
- .no-underline,
- a.group[href] {
- text-decoration: none !important;
- }
-
- table {
- @apply w-full;
- }
-
- table thead tr {
- @apply m-0 border-t p-0 even:bg-muted;
- }
-
- table thead th {
- @apply border px-4 py-2 text-left font-bold [&[align=center]]:text-center [&[align=right]]:text-right;
- }
-
- table tbody tr {
- @apply m-0 border-t p-0 even:bg-muted;
- }
-
- table tbody td {
- @apply border px-4 py-2 text-left [&[align=center]]:text-center [&[align=right]]:text-right;
- }
-
- hr {
- @apply my-16 border-gray-200;
- }
-
- img {
- @apply rounded-lg my-6 cursor-pointer transition-opacity hover:opacity-90;
- }
-
- /* Full screen image viewer */
- .image-viewer {
- @apply fixed inset-0 z-50 bg-black/90 flex items-center justify-center p-4 opacity-0 invisible transition-all duration-300;
- }
-
- .image-viewer.active {
- @apply opacity-100 visible;
- }
-
- .image-viewer img {
- @apply max-w-full max-h-full object-contain rounded-lg cursor-default;
- }
-
- .image-viewer-close {
- @apply absolute top-4 right-4 w-10 h-10 flex items-center justify-center rounded-full bg-white/10 text-white hover:bg-white/20 transition-colors cursor-pointer;
- }
-
- /* Steps component numbering */
- .steps-container {
- counter-reset: step-counter;
- }
-
- .step-item {
- counter-increment: step-counter;
- }
-
- .step-item .step-number::before {
- content: counter(step-counter);
- }
-
- /* Table of Contents styles */
- #toc-list {
- list-style: none;
- padding: 0;
- margin: 0;
- }
-
- #toc-list li {
- list-style: none;
- padding: 0;
- margin: 0;
- }
-
- /* Line clamp utility */
- .line-clamp-2 {
- display: -webkit-box;
- -webkit-line-clamp: 2;
- -webkit-box-orient: vertical;
- overflow: hidden;
- }
-
- /* Prevent Tailwind dark mode styles from affecting Mermaid diagrams */
- .mermaid p {
- color: inherit !important;
- }
-
- /* Mermaid line colors for light and dark modes */
- .mermaid .flowchart-link {
- stroke: #333333 !important;
- }
-
- .dark .mermaid .flowchart-link {
- stroke: #cccccc !important;
- }
-
- /* Mermaid arrow markers for light and dark modes */
- .mermaid marker path {
- fill: #333333 !important;
- stroke: #333333 !important;
- }
-
- .dark .mermaid marker path {
- fill: #cccccc !important;
- stroke: #cccccc !important;
- }
-
- /* Mobile menu blur effect - only blur specific content areas */
- .mobile-menu-open main {
- filter: blur(4px);
- transition: filter 300ms ease-in-out;
- }
-
- .mobile-menu-open header .flex-shrink-0 {
- filter: blur(4px);
- transition: filter 300ms ease-in-out;
- }
-
- .mobile-menu-open header .hidden.md\\:flex {
- filter: blur(4px);
- transition: filter 300ms ease-in-out;
- }
-
- .mobile-menu-open body {
- overflow: hidden;
- }
-
-}
diff --git a/tailwind.config.js b/tailwind.config.js
deleted file mode 100644
index 83119f6..0000000
--- a/tailwind.config.js
+++ /dev/null
@@ -1,39 +0,0 @@
-/** @type {import('tailwindcss').Config} */
-export default {
- content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
- darkMode: 'class',
- theme: {
- extend: {
- colors: {
- primary: '#000000',
- 'primary-foreground': '#ffffff',
- secondary: '#374151',
- 'secondary-foreground': '#ffffff',
- dark: '#111827',
- 'dark-foreground': '#ffffff',
- background: 'hsl(var(--background))',
- foreground: 'hsl(var(--foreground))',
- card: 'hsl(var(--card))',
- 'card-foreground': 'hsl(var(--card-foreground))',
- popover: 'hsl(var(--popover))',
- 'popover-foreground': 'hsl(var(--popover-foreground))',
- muted: 'hsl(var(--muted))',
- 'muted-foreground': 'hsl(var(--muted-foreground))',
- accent: 'hsl(var(--accent))',
- 'accent-foreground': 'hsl(var(--accent-foreground))',
- destructive: 'hsl(var(--destructive))',
- 'destructive-foreground': 'hsl(var(--destructive-foreground))',
- border: 'hsl(var(--border))',
- input: 'hsl(var(--input))',
- ring: 'hsl(var(--ring))',
- },
- borderRadius: {
- lg: 'var(--radius)',
- md: 'calc(var(--radius) - 2px)',
- sm: 'calc(var(--radius) - 4px)',
- },
- },
- },
- plugins: [],
-}
-
diff --git a/tsconfig.json b/tsconfig.json
index 96aeca0..4b34df1 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,18 +1,3 @@
{
- "extends": "astro/tsconfigs/strict",
- "include": [
- ".astro/types.d.ts",
- "**/*"
- ],
- "exclude": [
- "dist"
- ],
- "compilerOptions": {
- "jsx": "react-jsx",
- "jsxImportSource": "react",
- "baseUrl": ".",
- "paths": {
- "@/*": ["./src/*"]
- }
- }
-}
\ No newline at end of file
+ "extends": "./.nuxt/tsconfig.json"
+}