diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml new file mode 100644 index 0000000..f303f72 --- /dev/null +++ b/.github/workflows/docs-check.yml @@ -0,0 +1,18 @@ +name: Docs checks + +on: + pull_request: + push: + branches: [main] + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + cache: npm + - run: npm ci + - run: npm run check diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..565b8cf --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,22 @@ +# Contributing to the Basic Memory docs + +Keep documentation task-oriented, current, and explicit about whether a workflow uses Basic Memory Cloud or the open-source local project. + +## Before opening a pull request + +- Verify CLI commands and MCP parameters against the current `basic-memory` source or generated help. +- Verify Cloud settings, permissions, roles, billing behavior, and screenshots against the current application. +- Verify third-party integrations against the provider's official documentation. +- Avoid current-page claims tied to a release number. Put historical behavior in What's New, Changelog, or a migration page. +- Use screenshots only when they clarify a UI step that text cannot describe reliably. +- Add maintained screenshots to `docs/screenshots.json`. +- Preserve a redirect when deleting or renaming a published page. +- Run `npm run check`. + +## Writing style + +- Lead with the task or decision the reader is trying to complete. +- Keep Quickstarts short; link to deeper reference pages. +- Describe shipped behavior only. Label historical material as historical. +- Prefer durable names and concepts over exact button positions when third-party interfaces change frequently. +- Do not frame Basic Memory only as expanded model memory. It is a shared knowledge base for documents, workflows, projects, research, creative work, humans, AI tools, agents, and teams. diff --git a/app/app.config.ts b/app/app.config.ts index 2a0cedb..e3bcdf8 100644 --- a/app/app.config.ts +++ b/app/app.config.ts @@ -16,13 +16,22 @@ export default defineAppConfig({ }, contentNavigation: { slots: { + link: 'items-start', linkLeadingIcon: 'size-4 mr-1', + linkTitle: 'min-w-0 flex-1 overflow-visible text-clip whitespace-normal break-words leading-5', linkTrailing: 'hidden', }, defaultVariants: { variant: 'link', }, }, + contentToc: { + slots: { + link: 'items-start py-1.5', + linkText: 'overflow-visible text-clip whitespace-normal break-words leading-5', + indicator: 'hidden', + }, + }, pageLinks: { slots: { linkLeadingIcon: 'size-4', diff --git a/app/assets/css/main.css b/app/assets/css/main.css new file mode 100644 index 0000000..f64c73c --- /dev/null +++ b/app/assets/css/main.css @@ -0,0 +1,446 @@ +@import "tailwindcss"; +@import "@nuxt/ui"; + +:root { + --bm-paper: #fbf8f2; + --bm-paper-deep: #f4eee4; + --bm-ink: #24211d; + --bm-accent: #c96f2d; + --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; +} + +html { + background: var(--bm-paper); +} + +body { + color: var(--bm-ink); + font-family: var(--font-sans); + background: var(--bm-paper); +} + +.dark { + --bm-paper: #171512; + --bm-paper-deep: #211e1a; + --bm-ink: #f5efe5; +} + +header { + background-color: color-mix(in srgb, var(--bm-paper) 92%, transparent) !important; +} + +.bm-docs-switch { + align-items: center; + gap: 0.6rem; +} + +.bm-docs-switch-label { + color: color-mix(in srgb, var(--bm-ink) 58%, transparent); + font-size: 0.75rem; + font-weight: 650; + letter-spacing: 0.025em; + text-transform: uppercase; +} + +.bm-docs-switch-options { + display: flex; + align-items: center; + padding: 0.2rem; + border: 1px solid color-mix(in srgb, var(--bm-ink) 16%, transparent); + border-radius: 0.55rem; + background: color-mix(in srgb, var(--bm-paper-deep) 72%, transparent); +} + +.bm-docs-switch-link { + display: flex; + align-items: center; + gap: 0.4rem; + min-height: 2rem; + padding: 0.35rem 0.7rem; + border-radius: 0.38rem; + color: color-mix(in srgb, var(--bm-ink) 68%, transparent); + font-size: 0.875rem; + font-weight: 600; + line-height: 1; + text-decoration: none; + transition: + color 120ms ease, + background-color 120ms ease, + box-shadow 120ms ease; +} + +.bm-docs-switch-link:hover { + color: var(--bm-ink); +} + +.bm-docs-switch-link.is-active { + color: var(--bm-paper); + background: var(--bm-ink); + box-shadow: + 0 1px 2px rgb(36 33 29 / 10%), + inset 0 0 0 1px color-mix(in srgb, var(--bm-ink) 18%, transparent); +} + +.bm-docs-switch-link.is-active svg { + color: #f29a57; +} + +main { + min-height: calc(100vh - var(--ui-header-height)); +} + +.bm-home { + width: min(100% - 2rem, 68rem); + margin-inline: auto; + padding-block: 3rem 5rem; +} + +.bm-docs-intro { + max-width: 48rem; + margin-bottom: 2.75rem; +} + +.bm-docs-intro h1 { + margin: 0 0 0.75rem; + font-size: clamp(2.25rem, 4vw, 3.5rem); + line-height: 1.08; + letter-spacing: -0.035em; +} + +.bm-docs-intro p { + max-width: 44rem; + margin: 0; + color: color-mix(in srgb, var(--bm-ink) 72%, transparent); + font-size: 1.125rem; + line-height: 1.55; +} + +.bm-docs-search { + width: min(100%, 42rem); + min-height: 3.25rem; + margin-top: 1.75rem; + border-color: color-mix(in srgb, var(--bm-ink) 18%, transparent); + background: color-mix(in srgb, var(--bm-paper) 70%, white); + box-shadow: 0 1px 2px rgb(36 33 29 / 5%); + font-size: 1rem; +} + +.bm-docs-search:hover { + border-color: color-mix(in srgb, var(--bm-accent) 55%, transparent); + background: color-mix(in srgb, var(--bm-paper) 45%, white); +} + +.bm-docs-section { + margin-bottom: 3rem; +} + +.bm-start-grid { + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + gap: 1rem; +} + +.bm-start-card { + min-width: 0; + padding: 1.15rem 1.25rem; + border: 1px solid color-mix(in srgb, var(--bm-ink) 14%, transparent); + border-radius: 0.85rem; + background: color-mix(in srgb, var(--bm-paper) 78%, white); + box-shadow: 0 1px 2px rgb(36 33 29 / 4%); +} + +.bm-start-card-primary { + border-color: color-mix(in srgb, var(--bm-accent) 36%, transparent); + background: color-mix(in srgb, var(--bm-paper) 68%, #fff1e4); +} + +.bm-start-title { + display: inline-block; + margin: 0.75rem 0 0.45rem; + color: var(--bm-ink); + font-size: 1.25rem; + font-weight: 750; + line-height: 1.25; + letter-spacing: -0.025em; + text-decoration: none; +} + +.bm-start-title:hover { + color: var(--bm-accent); +} + +.bm-start-card > p { + margin: 0 0 1rem; + color: color-mix(in srgb, var(--bm-ink) 68%, transparent); + font-size: 0.95rem; + line-height: 1.55; +} + +.bm-start-card > p a { + display: inline-block; + color: var(--bm-ink); + font-weight: 700; + text-decoration: none; +} + +.bm-start-card > p a:hover { + color: var(--bm-accent); +} + +.bm-ai-docs-link { + margin: 1rem auto 0; + color: color-mix(in srgb, var(--bm-ink) 62%, transparent); + font-size: 0.95rem; + line-height: 1.5; + text-align: center; +} + +.bm-ai-docs-link a { + color: var(--bm-accent); + font-weight: 700; + text-decoration: none; +} + +.bm-ai-docs-link a:hover { + text-decoration: underline; +} + +.bm-docs-section h2, +.bm-docs-column h2 { + margin: 0 0 1rem; + font-size: 1.25rem; + line-height: 1.3; + letter-spacing: -0.02em; +} + +.bm-task-grid { + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + border-top: 1px solid color-mix(in srgb, var(--bm-ink) 13%, transparent); +} + +.bm-task-link { + min-width: 0; + padding: 1rem 2rem 1rem 0; + border-bottom: 1px solid color-mix(in srgb, var(--bm-ink) 13%, transparent); +} + +.bm-task-link:nth-child(even) { + padding-right: 0; + padding-left: 2rem; + border-left: 1px solid color-mix(in srgb, var(--bm-ink) 13%, transparent); +} + +.bm-task-link p { + margin: 0; + color: color-mix(in srgb, var(--bm-ink) 64%, transparent); + font-size: 0.925rem; + line-height: 1.45; +} + +.bm-task-link p:first-child { + margin-bottom: 0.25rem; +} + +.bm-task-link a { + position: relative; + display: block; + padding-right: 1.5rem; + color: var(--bm-ink); + font-size: 1rem; + font-weight: 650; + line-height: 1.35; + text-decoration: none; +} + +.bm-task-link a::after { + position: absolute; + top: 0; + right: 0; + color: var(--bm-accent); + content: "→"; + font-weight: 400; + transition: transform 120ms ease; +} + +.bm-task-link:hover a { + color: var(--bm-accent); +} + +.bm-task-link:hover a::after { + transform: translateX(0.2rem); +} + +.bm-browse-grid { + display: grid; + grid-template-columns: repeat(4, minmax(0, 1fr)); + gap: 2rem; + padding-top: 1rem; + border-top: 1px solid color-mix(in srgb, var(--bm-ink) 14%, transparent); +} + +.bm-browse-group { + min-width: 0; +} + +.bm-browse-group h3 { + margin: 0 0 0.5rem; + color: var(--bm-ink); + font-size: 1rem; + line-height: 1.35; + letter-spacing: -0.015em; +} + +.bm-browse-group ul { + display: grid; + gap: 0.35rem; + margin: 0; + padding: 0; + list-style: none; +} + +.bm-browse-group li { + margin: 0; +} + +.bm-browse-group a { + color: color-mix(in srgb, var(--bm-ink) 66%, transparent); + font-size: 0.9rem; + line-height: 1.4; + text-decoration: none; +} + +.bm-browse-group a:hover { + color: var(--bm-accent); +} + +.bm-docs-columns { + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + gap: 4rem; + padding-top: 2.5rem; + border-top: 1px solid color-mix(in srgb, var(--bm-ink) 16%, transparent); +} + +.bm-docs-column { + min-width: 0; +} + +.bm-docs-column > p { + margin: -0.5rem 0 1rem; + color: color-mix(in srgb, var(--bm-ink) 66%, transparent); + font-size: 0.925rem; +} + +.bm-docs-column ul { + display: grid; + gap: 0; + margin: 0; + padding: 0; + list-style: none; +} + +.bm-docs-column li { + margin: 0; + border-top: 1px solid color-mix(in srgb, var(--bm-ink) 12%, transparent); +} + +.bm-docs-column a { + position: relative; + display: block; + padding: 0.65rem 1.5rem 0.65rem 0; + color: var(--bm-ink); + font-weight: 500; + text-decoration: none; +} + +.bm-docs-column a::after { + position: absolute; + right: 0.15rem; + color: color-mix(in srgb, var(--bm-ink) 40%, transparent); + content: "→"; +} + +.bm-docs-column a:hover { + color: var(--bm-accent); +} + +.bm-docs-column a:hover::after { + color: var(--bm-accent); +} + +@media (max-width: 767px) { + .bm-home { + padding-block: 2rem 3.5rem; + } + + .bm-docs-intro { + margin-bottom: 2.25rem; + } + + .bm-docs-intro h1 { + font-size: 2.25rem; + } + + .bm-docs-intro p { + font-size: 1rem; + } + + .bm-docs-search { + margin-top: 1.25rem; + } + + .bm-docs-section { + margin-bottom: 2.5rem; + } + + .bm-start-grid { + grid-template-columns: 1fr; + } + + .bm-task-grid { + grid-template-columns: 1fr; + } + + .bm-task-link, + .bm-task-link:nth-child(even) { + padding: 0.9rem 0; + border-left: 0; + } + + .bm-browse-grid { + grid-template-columns: 1fr; + gap: 1.35rem; + } + + .bm-docs-columns { + grid-template-columns: 1fr; + gap: 2.5rem; + padding-top: 2rem; + } + + .bm-docs-column h2 { + margin-bottom: 1rem; + } +} + +.prose h1, +.prose h2, +.prose h3 { + letter-spacing: -0.025em; +} + +.prose { + --tw-prose-body: color-mix(in srgb, var(--bm-ink) 82%, transparent); + --tw-prose-headings: var(--bm-ink); +} +div[data-slot='root'][role='separator']:has( + a[href$='/content/1.start-here/1.what-is-basic-memory.md'] +) { + display: none; +} + +body:has(a[href$='/content/1.start-here/4.getting-started.md']) + a[href='/start-here/quickstart-local'] { + display: none; +} diff --git a/app/components/app/AppHeaderBody.vue b/app/components/app/AppHeaderBody.vue new file mode 100644 index 0000000..1f52724 --- /dev/null +++ b/app/components/app/AppHeaderBody.vue @@ -0,0 +1,28 @@ + + + diff --git a/app/components/app/AppHeaderCTA.vue b/app/components/app/AppHeaderCTA.vue new file mode 100644 index 0000000..40c9f19 --- /dev/null +++ b/app/components/app/AppHeaderCTA.vue @@ -0,0 +1,25 @@ + diff --git a/app/components/app/AppHeaderCenter.vue b/app/components/app/AppHeaderCenter.vue new file mode 100644 index 0000000..58651c9 --- /dev/null +++ b/app/components/app/AppHeaderCenter.vue @@ -0,0 +1,36 @@ + + + diff --git a/app/components/app/AppHeaderLogo.vue b/app/components/app/AppHeaderLogo.vue new file mode 100644 index 0000000..de14f52 --- /dev/null +++ b/app/components/app/AppHeaderLogo.vue @@ -0,0 +1,13 @@ + diff --git a/app/components/content/DocsHomeSearch.vue b/app/components/content/DocsHomeSearch.vue new file mode 100644 index 0000000..44ecc26 --- /dev/null +++ b/app/components/content/DocsHomeSearch.vue @@ -0,0 +1,16 @@ + diff --git a/app/components/docs/DocsAsideLeftBody.vue b/app/components/docs/DocsAsideLeftBody.vue new file mode 100644 index 0000000..5c065f9 --- /dev/null +++ b/app/components/docs/DocsAsideLeftBody.vue @@ -0,0 +1,12 @@ + + + diff --git a/app/composables/useDocsNavigation.ts b/app/composables/useDocsNavigation.ts new file mode 100644 index 0000000..bf16119 --- /dev/null +++ b/app/composables/useDocsNavigation.ts @@ -0,0 +1,212 @@ +import type { ContentNavigationItem } from '@nuxt/content' + +type DocsArea = 'cloud' | 'open-source' | 'utility' + +function copySection( + section: ContentNavigationItem | undefined, + title?: string, + children?: ContentNavigationItem[], +): ContentNavigationItem | undefined { + if (!section) return + + return { + ...section, + title: title || section.title, + children: children || section.children, + } +} + +function selectChildren( + section: ContentNavigationItem | undefined, + paths: string[], + deployment?: 'local', +) { + const children = section?.children || [] + + return paths + .map(path => children.find(item => item.path === path)) + .filter((item): item is ContentNavigationItem => Boolean(item)) + .map(item => deployment + ? { ...item, to: `${item.path}?deployment=local` } + : item) +} + +export function useDocsNavigation() { + const route = useRoute() + const navigation = inject>('navigation') + + const area = computed(() => { + if (route.path === '/changelog' || route.path.startsWith('/whats-new')) { + return 'utility' + } + if (route.query.deployment === 'local') { + return 'open-source' + } + if (route.path.startsWith('/local') || route.path === '/start-here/quickstart-local') { + return 'open-source' + } + if (route.path.startsWith('/integrations')) { + return 'cloud' + } + if (route.path.startsWith('/reference')) { + return [ + '/reference/cli-reference', + '/reference/configuration', + '/reference/docker', + '/reference/v0-19-migration', + ].includes(route.path) + ? 'open-source' + : 'cloud' + } + return 'cloud' + }) + + const headerLinks = computed(() => [ + { + label: 'Cloud', + icon: 'i-lucide-cloud', + to: '/start-here/quickstart-cloud', + active: area.value === 'cloud', + }, + { + label: 'Open Source', + icon: 'i-lucide-terminal', + to: '/local/local-install', + active: area.value === 'open-source', + }, + ]) + + const sidebarNavigation = computed(() => { + const items = navigation?.value || [] + const section = (path: string) => items.find(item => item.path === path) + const startHere = section('/start-here') + const startChildren = startHere?.children || [] + const integrations = section('/integrations') + const reference = section('/reference') + const concepts = section('/concepts') + const structuredKnowledge = copySection( + concepts, + 'Structure & schemas', + selectChildren(concepts, [ + '/concepts/knowledge-format', + '/concepts/observations-and-relations', + '/concepts/schema-system', + '/concepts/metadata-search', + ]), + ) + const remainingConcepts = copySection( + concepts, + 'Concepts', + (concepts?.children || []).filter(item => ![ + '/concepts/knowledge-format', + '/concepts/observations-and-relations', + '/concepts/schema-system', + '/concepts/metadata-search', + ].includes(item.path)), + ) + + if (area.value === 'open-source') { + return [ + copySection( + startHere, + 'Get Started', + startChildren.filter(item => [ + '/start-here/what-is-basic-memory', + '/start-here/quickstart-local', + ].includes(item.path)), + ), + copySection(section('/local'), 'Open Source'), + copySection( + integrations, + 'AI tools & extensions', + selectChildren(integrations, [ + '/integrations', + '/integrations/claude-desktop', + '/integrations/claude-code', + '/integrations/gemini', + '/integrations/codex', + '/integrations/cursor', + '/integrations/vscode', + '/integrations/obsidian', + '/integrations/skills', + '/integrations/openclaw', + '/integrations/hermes', + ], 'local'), + ), + structuredKnowledge, + remainingConcepts, + copySection( + reference, + 'Reference', + selectChildren(reference, [ + '/reference/cli-reference', + '/reference/mcp-tools-reference', + '/reference/ai-assistant-guide', + '/reference/technical-information', + '/reference/troubleshooting', + '/reference/contact-support', + '/reference/configuration', + '/reference/docker', + '/reference/llms-txt', + '/reference/v0-19-migration', + ], 'local'), + ), + ].filter(Boolean) as ContentNavigationItem[] + } + + if (area.value === 'utility') { + return [ + copySection(section('/whats-new')), + ].filter(Boolean) as ContentNavigationItem[] + } + + return [ + copySection( + startHere, + 'Get Started', + startChildren.filter(item => item.path !== '/start-here/quickstart-local'), + ), + copySection(section('/cloud'), 'Basic Memory Cloud'), + copySection(section('/teams'), 'Collaboration'), + copySection( + integrations, + 'AI tools & extensions', + selectChildren(integrations, [ + '/integrations', + '/integrations/claude-desktop', + '/integrations/claude-code', + '/integrations/chatgpt', + '/integrations/gemini', + '/integrations/codex', + '/integrations/cursor', + '/integrations/vscode', + '/integrations/obsidian', + '/integrations/skills', + '/integrations/openclaw', + '/integrations/hermes', + ]), + ), + structuredKnowledge, + copySection(section('/how-to'), 'Guides'), + remainingConcepts, + copySection( + reference, + 'Reference', + selectChildren(reference, [ + '/reference/llms-txt', + '/reference/mcp-tools-reference', + '/reference/ai-assistant-guide', + '/reference/technical-information', + '/reference/troubleshooting', + '/reference/contact-support', + ]), + ), + ].filter(Boolean) as ContentNavigationItem[] + }) + + return { + area, + headerLinks, + sidebarNavigation, + } +} diff --git a/content/1.start-here/1.what-is-basic-memory.md b/content/1.start-here/1.what-is-basic-memory.md index 7486d74..d05636a 100644 --- a/content/1.start-here/1.what-is-basic-memory.md +++ b/content/1.start-here/1.what-is-basic-memory.md @@ -1,434 +1,158 @@ --- -title: What is Basic Memory -description: An overview of what Basic Memory is and how it works. +title: What is Basic Memory? +description: A shared knowledge base for humans, agents, and their teams. --- -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. +Basic Memory is a shared knowledge base for humans, LLMs, agents, and their teams. -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. +It gives people and AI tools a durable place to share and organize knowledge. That knowledge can be anything you or your AI might need: a collection of large documents, instructions for complex, repeatable workflows, software projects, years of research, or a novel. --- -:video{autoplay controls loop muted src="https://basicmemory.com/videos/explainer-video.mp4"} -## Why Basic Memory? +## What can you use it for? -**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. +Basic Memory does not prescribe one kind of knowledge or one way to organize it. -**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. +### Project knowledge -**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 +Keep requirements, architecture decisions, meeting notes, plans, risks, and next steps in one place. People and agents can work from the same current context instead of reconstructing it in every conversation. ---- +### Repeatable workflows -## What it does +Document procedures, checklists, playbooks, and operating practices. An agent can find the relevant workflow, follow its steps, record the result, and improve the documentation as the process changes. -:::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. -:: +### Document collections -::card ---- -title: Connects ideas with links -icon: i-lucide-link ---- -Relations and tags turn notes into a knowledge graph that grows over time. -:: +Import and organize large collections of Markdown files, exported conversations, technical documents, research, and reference material. Search can surface a relevant passage from deep inside the collection without requiring you to remember the exact wording. -::card ---- -title: Lets assistants search and write -icon: i-lucide-search ---- -MCP tools let your assistant read, write, search, and organize notes. -:: +### Research and learning -::card ---- -title: Cloud or Local -icon: i-lucide-cloud ---- -Use the hosted cloud service or run everything locally - your choice. -:: -::: +Build a connected body of sources, findings, questions, and conclusions. Relations and semantic search help reveal how ideas connect across documents and over time. ---- - -## How it works +### Team knowledge -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 ---- -:: +Create shared workspaces where people and agents can contribute to the same projects. Decisions and context remain available when work changes hands or moves between tools. -### The workflow +### Persistent context -1. **Capture a note** - You write or ask your assistant to write a note during a conversation. +Keep useful knowledge available across AI conversations. This is an important use case, but it is one part of the larger system rather than the product's limit. -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 +## Humans and agents use the same knowledge -```bash -You: "What did we decide about the authentication approach?" +Most AI memory systems keep small, hidden facts for one assistant. Basic Memory takes a different approach: the knowledge itself is visible and editable. -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'." +- **Humans can** write and edit notes, organize projects, import documents, review changes, and correct mistakes. +- **Agents can** create notes, search across projects, edit existing material, follow relations, and assemble relevant context. +- **Teams can** share workspaces, manage access, and build on a common body of knowledge. -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." -``` +Knowledge created in one tool is not trapped there. A note written with Codex can be used from Claude, reviewed in the Basic Memory web app, edited locally, and found later by another MCP-compatible tool. --- -## What a note looks like +## The knowledge stays readable -Notes are standard Markdown with optional semantic structure: +Basic Memory stores knowledge as Markdown with optional metadata and semantic structure. -```bash +```markdown --- -title: API Authentication Decision -tags: [security, api, auth] +title: Release Process +type: workflow +status: active --- -# API Authentication Decision +# Release Process -## Context -We needed to choose an authentication approach for the new API. +1. Run the full test suite. +2. Review database migrations. +3. Publish the release notes. ## Observations -- [decision] Use JWT tokens for API auth #security -- [requirement] Tokens expire after 24 hours -- [risk] Rate limiting needed on login endpoint #auth +- [decision] Production releases require two reviewers. +- [requirement] Database migrations must be reversible. ## Relations -- implements [[API Security Spec]] -- depends_on [[User Service]] -- relates_to [[Token Refresh]] +- follows [[Deployment Checklist]] +- produces [[Release Notes]] ``` -**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. -:: +This is still an ordinary text document. You can read it, edit it, export it, track it with Git, or open it in another Markdown tool. ---- - -## 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`) +Basic Memory adds useful structure without requiring every document to use it: -### Building context +- **Metadata** describes fields such as status, owner, type, or due date. +- **Observations** identify important facts, decisions, requirements, and findings. +- **Relations** connect one document to another. +- **Schemas** can define consistent structures for recurring document types. -When you ask a question, the AI doesn't just return one note. It traverses the graph to build rich context: +Start with plain notes. Add structure when it helps. -::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 +## How it works -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 +Basic Memory Cloud gives people and AI tools access to the same workspace. -**Both use the same Markdown format**, so you can start with one and switch to the other later. +People work through the web app. AI tools connect through MCP. Both can read, create, and update the same notes, projects, metadata, observations, and relations. ---- +When a document is created or changed, Basic Memory indexes its text and structure. You and your agents can then: -## MCP Integration +- Search by exact text or meaning +- Find individual facts inside long documents +- Filter by metadata +- Follow relations between notes +- Build context from connected material +- Create and update documents through MCP tools -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. +The result is not a static archive. It is a working knowledge base that stays useful as humans and agents change it. -**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 +Basic Memory Cloud includes: -**Compatible assistants:** -- Claude Desktop -- Claude Code -- ChatGPT (Pro/Max) -- Google Gemini -- Cursor -- VS Code (with MCP extension) -- Codex +- A web app for browsing and editing +- Hosted MCP access +- Shared workspaces and team management +- Imports, local sync, file history, and snapshots +- Access from multiple tools and devices --- -## Getting started - -Ready to try Basic Memory? +## Next steps -:::card-group -::card +::::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. -:: +Create a hosted workspace and connect an AI tool. ::: +:::card --- - -## Next steps - -:::card-group -::card ---- -title: Getting Started -icon: i-lucide-rocket -to: /start-here/getting-started +title: Web App Guide +icon: i-lucide-layout-panel-left +to: /cloud/web-app --- -Full installation guide with configuration options. -:: +Browse, edit, search, import, and manage your knowledge. +::: -::card +:::card --- title: Knowledge Format icon: i-lucide-file-text to: /concepts/knowledge-format --- -Learn the note structure with observations and relations. -:: +See how Markdown, metadata, observations, and relations work. +::: -::card +:::card --- -title: MCP Tools Reference -icon: i-lucide-wrench -to: /reference/mcp-tools-reference +title: Basic Memory and built-in memory +icon: i-lucide-layers +to: /concepts/vs-built-in-memory --- -All available tools for AI assistants. -:: +Compare Basic Memory with built-in memory and other knowledge tools. ::: +:::: diff --git a/content/1.start-here/2.quickstart-cloud.md b/content/1.start-here/2.quickstart-cloud.md index 37e9e47..d30e488 100644 --- a/content/1.start-here/2.quickstart-cloud.md +++ b/content/1.start-here/2.quickstart-cloud.md @@ -1,199 +1,135 @@ --- title: "Quickstart: Cloud" -description: Connect Basic Memory Cloud and create your first note in 2 minutes. +description: Create a Basic Memory Cloud workspace, connect an AI tool, and make your first note. --- -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. +Basic Memory Cloud gives you a hosted workspace, a web app, and a remote MCP endpoint your AI tools can use from anywhere. You can start with Claude, Codex, ChatGPT, or another MCP-compatible client. -::mermaid ---- -code: | - flowchart LR - A[Sign Up] --> B[Connect AI] - B --> C[Create Note] - C --> D[View in App] ---- -:: - ---- +This guide follows the same path as the in-app onboarding. It uses Claude as the example client because that is the default walkthrough in the product, but the same endpoint works with Codex and other MCP tools. -## 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. - -![Cloud signup page](/screenshots/cloud/signup.png) - ---- - -## 2. Connect your AI assistant - -Use the remote MCP endpoint URL: - -```bash +```text https://cloud.basicmemory.com/mcp ``` -### For Claude Desktop +## 1. Create your account -::steps -### Open Settings -In Claude Desktop or Claude.ai, go to **Settings → Claude → Connectors** +Go to [app.basicmemory.com](https://app.basicmemory.com) and create an account. -![Claude Settings - Connectors](/screenshots/claude/settings-connectors.png) +You can sign up with email or a supported identity provider such as Google, Microsoft, or GitHub. -### Add Custom Connector -Click **Add custom connector** and enter: -- **Name**: Basic Memory -- **Remote MCP server URL**: `https://cloud.basicmemory.com/mcp` +After email verification, new workspace owners choose a plan, name their workspace, and complete checkout. Invited users follow the invitation flow for the workspace they were invited to. -![Claude - Add connector dialog](/screenshots/claude/add-connector.png) +--- -### Authenticate -Click **Connect** to start the OAuth flow. You'll be redirected to Basic Memory to authorize access. +## 2. Choose an AI tool -![OAuth authorization](/screenshots/claude/oauth-connect.png) +After checkout or invite acceptance, Basic Memory opens the **Getting Started** onboarding screen. -![OAuth authorization](/screenshots/claude/oauth-authorize.png) +The first step asks which AI tool you want to connect: -### Configure Tools (Optional) -Click **Configure** to customize which tools are enabled. +- Claude +- Codex +- ChatGPT +- Other MCP tools -![Claude - Configure tools](/screenshots/claude/configure-tools.png) +Pick the assistant you use most. You can connect more tools later. -### Verify Setup -Confirm Basic Memory appears in the tools menu (+ icon in chat). +::tip +Need client-specific details? Use the integration guides: -![Claude - Tools menu](/attachments/claude-tools-menu.png) +- [Claude](/integrations/claude-desktop) +- [Codex](/integrations/codex) +- [ChatGPT](/integrations/chatgpt) :: -### 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 +## 3. Copy your MCP endpoint -### Add Endpoint -Add the Basic Memory endpoint URL: `https://cloud.basicmemory.com/mcp` +The onboarding screen shows your remote MCP endpoint: -### Authenticate -Complete the OAuth flow when prompted -:: +```text +https://cloud.basicmemory.com/mcp +``` -::tip -Watch the [ChatGPT setup video](https://youtube.com/watch?v=NvU0Jo38P_k) for a complete walkthrough. -:: +Paste that URL wherever your AI tool asks for a remote MCP server, connector, or custom MCP server. -### For other assistants +Use the setup guide for your client: -See the [Integrations](/integrations/claude-desktop) section for setup guides for: -- [Google Gemini](/integrations/gemini) -- [Cursor](/integrations/cursor) -- [VS Code](/integrations/vscode) +- [Claude](/integrations/claude-desktop) - [Claude Code](/integrations/claude-code) +- [ChatGPT](/integrations/chatgpt) +- [Gemini CLI](/integrations/gemini) +- [Codex](/integrations/codex) +- [Cursor](/integrations/cursor) + +These guides cover where to enter the endpoint, how to authorize Basic Memory, and how to verify the connection. + +::tip +The setup guide remains available later from **Settings -> MCP** in the Basic Memory web app. +:: --- -## 3. Verify the connection +## 4. Create your first memory -Ask your assistant: +Once your AI tool is connected, send the prompt from the onboarding screen: -```bash -List my basic memory projects +```text +Help me get started with Basic Memory. First, explain in a few bullets how you can use Basic Memory with me to remember project context, decisions, and next steps. Then create a note titled "Getting Started with Basic Memory" that includes: +- What Basic Memory is for +- How I should use it with you +- One simple thing I should try next ``` -**Expected response:** -```bash -You have 1 project: -- main (default) - /app/data/basic-memory - 0 notes -``` +This confirms that your AI tool can write to your Basic Memory workspace. -![Claude - Project list response](/screenshots/claude/project-list-response.png) +If the prompt succeeds, your assistant creates a note in your cloud workspace. You can open it in the web app and continue editing it there. -::warning -If you get an error, check the [Troubleshooting](/reference/troubleshooting) guide. +::tip +Want your assistant to use Basic Memory more consistently? After you finish the quickstart, add the recommended [Basic Memory instructions](/start-here/getting-started#teach-your-ai-when-to-use-basic-memory) to your AI tool. :: --- -## 4. Create your first note +## 5. Invite your team -Try this prompt: +Standalone workspaces include a final onboarding step for collaboration. -```bash -Create a note called "Getting Started" with a summary of what Basic Memory does. -``` +You can invite teammates immediately from **Team Settings**, or skip this and invite people later from **Settings -> Teams**. -Your assistant will use the `write_note` tool to create a Markdown file in your cloud storage. +::note +Invited users may not see this step. If you joined an existing workspace, your onboarding focuses on connecting an AI tool and creating your first memory. +:: -**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. +## 6. Open the Getting Started project -[Uses write_note tool] +After onboarding, Basic Memory opens the **Getting Started** project. It includes eight tutorial notes that explain: -I've created "Getting Started" in your knowledge base. The note covers: - What Basic Memory is -- How the knowledge format works -- Key features like semantic search and relations -``` - -![Claude - Creating first note](/screenshots/claude/create-first-note.png) - ---- - -## 5. View your notes - -Open [app.basicmemory.com/notes](https://app.basicmemory.com/notes) to see your new note. +- The toolset your AI assistant can use +- How Basic Memory structures knowledge +- Markdown, imports, sync, and next steps -![Web app - First note](/screenshots/cloud-app/first-note.png) +Your workspace also includes a **Main** project for your own notes. -**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 +![The Basic Memory web app open to the Getting Started project, with eight tutorial notes and the welcome note selected.](/screenshots/cloud-app/getting-started-project.png) --- -## What you can do now +## What to try next -Try these prompts with your assistant: +Use these prompts with your connected 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] -``` +| `Create a note about what we just discussed.` | Writes a new note to your workspace. | +| `Find my notes about [topic].` | Searches your knowledge base. | +| `What decisions have we made about [project]?` | Uses your notes as context. | +| `Add this to my notes about [topic].` | Updates existing knowledge. | +| `Show me recent notes.` | Lists recent workspace activity. | --- @@ -202,29 +138,29 @@ Claude: [Uses edit_note to append new content] :::card-group ::card --- -title: Cloud Guide -icon: i-lucide-cloud -to: /cloud/cloud-guide +title: Web App Guide +icon: i-lucide-layout-panel-left +to: /cloud/web-app --- -Full cloud features including CLI tools, snapshots, and migration. +Browse, edit, search, import, and manage notes in the browser. :: ::card --- -title: Web App Guide -icon: i-lucide-layout-panel-left -to: /cloud/web-app +title: Teams +icon: i-lucide-users +to: /teams/about --- -Learn the web interface for browsing and editing notes. +Invite people, manage roles, and collaborate in shared workspaces. :: ::card --- -title: Cloud Sync -icon: i-lucide-refresh-cw -to: /cloud/cloud-sync +title: Cloud Overview +icon: i-lucide-cloud +to: /cloud/cloud-guide --- -Set up bidirectional sync with local files. +Cloud features, web app workflows, collaboration, recovery, and advanced options. :: ::card @@ -233,6 +169,15 @@ title: Knowledge Format icon: i-lucide-file-text to: /concepts/knowledge-format --- -Learn the note structure with observations and relations. +Learn how notes, observations, relations, and tags work. +:: + +::card +--- +title: Using Basic Memory +icon: i-lucide-compass +to: /start-here/getting-started +--- +Set up useful habits, organize knowledge, and teach your AI when to use Basic Memory. :: ::: diff --git a/content/1.start-here/3.quickstart-local.md b/content/1.start-here/3.quickstart-local.md index 5780185..df87f91 100644 --- a/content/1.start-here/3.quickstart-local.md +++ b/content/1.start-here/3.quickstart-local.md @@ -1,69 +1,34 @@ --- -title: "Quickstart: Local" -description: Install Basic Memory locally and connect it to your AI assistant. +title: "Quickstart: Open Source" +description: Install Basic Memory locally, connect an MCP client, and create your first note. --- -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] ---- -:: - ---- +The open-source version runs on your computer. Your source of truth is a folder of Markdown files you control. ## 1. Install Basic Memory -Choose your installation method. All installs include semantic search for hybrid (keyword + meaning-based) search. +We recommend installing with `uv`: -### macOS (Homebrew) - Recommended +::code-group +```bash [uv] +uv tool install basic-memory +``` -```bash +```bash [Homebrew] 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 -``` +Confirm that the CLI is available: -**Expected output:** ```bash -basic-memory, version 0.19.x +bm --version ``` ---- - -## 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` | +## 2. Connect an MCP client -Add this configuration: +Configure your AI tool to launch the local MCP server: ```json { @@ -76,264 +41,81 @@ Add this configuration: } ``` -::warning -**ENOENT error?** Use the full path to uvx. Find it with `which uvx` and replace `"uvx"` with the full path (e.g., `"/Users/yourname/.local/bin/uvx"`). -:: - -**Restart Claude Desktop** after editing the config. - ---- - -## 3. Verify the connection - -In Claude Desktop, click the **tools icon** (hammer) in the bottom-right of the chat interface. You should see Basic Memory tools listed. - -![Claude - Tools menu with Basic Memory](/screenshots/claude/tools-menu-local.png) - -Ask Claude: - -```bash -List my projects -``` - -**Expected response:** -```bash -You have 1 project: -- main (default) - ~/basic-memory - 0 notes -``` - -![Claude - Project list](/screenshots/claude/project-list-response.png) - ---- - -## 4. Create your first note - -Try this prompt: - -```bash -Create a note called "Getting Started" with a summary of what Basic Memory does. -``` - -Claude will create a Markdown file at `~/basic-memory/Getting Started.md`. - -**Example conversation:** -```bash -You: Create a note called "Getting Started" with a summary of what Basic Memory does. - -Claude: I'll create a note for you. - -[Uses write_note tool] - -Done! I've created "Getting Started.md" in your basic-memory folder. -It includes an overview of Basic Memory's key features: -- Knowledge storage in Markdown -- Semantic observations and relations -- Search across your knowledge base -``` - -![Claude - Creating first note](/screenshots/claude/create-first-note.png) - ---- - -## 5. View your notes - -Your notes are stored at `~/basic-memory` by default. You can: - -### Open in any text editor - -```bash -# View in terminal -cat ~/basic-memory/Getting\ Started.md - -# Open folder -open ~/basic-memory # macOS -explorer ~/basic-memory # Windows -``` - -### Use Obsidian for visual navigation - -1. Open Obsidian -2. **Create new vault** → select `~/basic-memory` -3. Use the **graph view** to see connections between notes - -### Example note structure - -After creating a few notes, your folder might look like: - -```bash -~/basic-memory/ -├── Getting Started.md -├── projects/ -│ └── API Design.md -├── research/ -│ └── Database Optimization.md -└── meetings/ - └── Team Standup 2024-01-15.md -``` - ---- - -## What you can do now - -Try these prompts with Claude: - -| Prompt | What it does | -|--------|--------------| -| `Create a note about [topic]` | Creates a new Markdown file | -| `What have we discussed recently?` | Shows recently modified notes | -| `Find notes about [topic]` | Searches your knowledge base | -| `Continue our conversation about [topic]` | Loads context from previous notes | -| `Add to my [topic] notes` | Edits an existing note | -| `Move my [note] to the archive folder` | Reorganizes files | - -### Example workflow - -```bash -You: "Let's document our API design decisions" - -Claude: I'll create a note for the API design decisions. -[Creates ~/basic-memory/API Design Decisions.md] +Restart the AI tool after changing its configuration. ---- Later --- +::note +The install command uses `uv tool install` so you can run `bm` in your terminal. The MCP snippet uses `uvx` so your AI client can launch Basic Memory directly. If the client cannot find `uvx`, run `which uvx` and use the returned absolute path as `command`. +:: -You: "What did we decide about authentication?" +Client-specific instructions are available under [Connect AI tools](/integrations?deployment=local). -Claude: [Searches knowledge base] -"Based on your 'API Design Decisions' note, you decided to use JWT tokens..." +## 3. Create your first note -You: "Add a section about rate limiting" +Ask your connected AI tool: -Claude: [Uses edit_note to append] -"I've added a rate limiting section to your API design notes." +```text +Create a Basic Memory note called "Getting Started" that explains what I want +to keep in this knowledge base. ``` ---- - -## Customize your setup +Then ask: -### 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" +```text +Read my "Getting Started" note. ``` -Restart Claude Desktop for changes to take effect. - -### Skip project selection prompts +This verifies both write and read access. -If you only use one project, add to `~/.basic-memory/config.json`: +## 4. Find the Markdown files -```json -{ - "default_project": "main" -} -``` +The default `main` project lives at `~/basic-memory`. Open that folder in any Markdown editor, file browser, Obsidian vault, or Git repository. ---- - -## Useful CLI commands +To use another folder: ```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 +bm project add research ~/Documents/research +bm project default research ``` ---- - -## Troubleshooting - -### ENOENT error +Basic Memory indexes Markdown from that folder without taking ownership of the files. -Claude Desktop can't find `uvx`. Use the full path: +## 5. Try the CLI ```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"] - } - } -} +bm project list +bm status +bm tool search-notes --query "getting started" ``` -### 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. - ---- +The CLI and MCP server use the same projects and index. ## Next steps :::card-group ::card --- -title: CLI Basics -icon: i-lucide-terminal -to: /local/cli-basics +title: Local install +icon: i-lucide-download +to: /local/local-install --- -Learn the command line tools for managing your knowledge. +Installation details and project locations. :: ::card --- -title: Configuration -icon: i-lucide-settings -to: /reference/configuration +title: CLI basics +icon: i-lucide-terminal +to: /local/cli-basics --- -All configuration options and environment variables. +Common project, search, and note commands. :: ::card --- -title: Knowledge Format +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 +to: /concepts/knowledge-format?deployment=local --- -Visual knowledge navigation with graph view. +How Markdown, observations, and relations fit together. :: ::: diff --git a/content/1.start-here/4.getting-started.md b/content/1.start-here/4.getting-started.md index 407cb90..c37f5f4 100644 --- a/content/1.start-here/4.getting-started.md +++ b/content/1.start-here/4.getting-started.md @@ -1,146 +1,186 @@ --- -title: Getting Started -description: Configure where notes are saved and manage multiple projects. +title: Using Basic Memory +description: Build useful habits, organize your knowledge, and teach your AI tools when to use Basic Memory. --- -Ready to set up Basic Memory? Start with the quickstart guides: +Once you have created your workspace, Basic Memory Cloud is ready to use in the browser and with any connected AI tools. -:::card-group -::card ---- -title: "Quickstart: Cloud" -icon: i-lucide-cloud -to: /start-here/quickstart-cloud ---- -Connect in 2 minutes. No installation required. -:: +If you have not created an account or connected an AI tool yet, begin with the [Cloud quickstart](/start-here/quickstart-cloud). -::card ---- -title: "Quickstart: Local" -icon: i-lucide-hard-drive -to: /start-here/quickstart-local --- -Install locally and run everything on your machine. -:: -::: + +## Start with your workspace + +Your workspace is the shared home for your projects, notes, people, and AI connections. + +When you first open Basic Memory, you will see: + +- A **Getting Started** project with a short guided introduction +- A **Main** project for your own knowledge +- Search, graph, and activity views +- Settings for AI connections, projects, members, and your account + +You can write and edit notes directly in the web app or ask a connected AI tool to do it for you. --- -## Choosing Where Notes Are Saved +## Add some knowledge + +You do not need to design the perfect structure before you begin. Start with something useful: -By default, Basic Memory saves notes in a project called `main` in `~/basic-memory`. To save notes elsewhere: +- Create a note in the web app +- Ask an AI assistant to save the context from a conversation +- Import existing Markdown notes or an archive +- Add project documentation, research, instructions, or a repeatable workflow -### Use Your Existing Notes Folder +Basic Memory can hold anything you and your AI tools need to work with together, from a single decision to a large collection of documents. -Ask your AI assistant directly: +::tip +Try asking a connected assistant: -```bash -Create a new project called "my project" in the "/Users/yourname/Documents/Notes" directory +```text +Create a note that summarizes this project, including its goals, +current decisions, open questions, and next steps. ``` +:: -Then: +--- -```bash -Set the default project to "my project" -``` +## Organize with projects -Or use the command line: +Projects keep different bodies of knowledge separate inside your workspace. You might create projects for: -```bash -# Point Basic Memory to your existing notes folder -basic-memory project add "my project" +- A product or software repository +- A research topic +- Company operations +- A client +- A book or other long-running creative project -# Make it your default location -basic-memory project default "my project" -``` +Start with one or two projects and add more when the distinction becomes useful. Notes can also be organized into folders within a project. + +[Learn about projects and folders →](/concepts/projects-and-folders) + +--- + +## Connect your AI tools -::warning -If you change default projects from the command line, new notes will be saved in your chosen folder after restarting Claude Desktop. +Basic Memory Cloud provides a hosted MCP connection that works with supported AI tools. You can connect more than one tool to the same workspace, allowing them to use the same knowledge. + +:::card-group +::card +--- +title: Claude +icon: i-simple-icons-anthropic +to: /integrations/claude-desktop +--- +Use Basic Memory in your conversations with Claude. :: -**Want to use Obsidian?** Just open your folder location as a vault. See the [Obsidian Integration](/integrations/obsidian) guide. +::card +--- +title: Claude Code +icon: i-simple-icons-anthropic +to: /integrations/claude-code +--- +Give Claude Code access to shared project knowledge. +:: -::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. +::card +--- +title: ChatGPT +icon: i-simple-icons-openai +to: /integrations/chatgpt +--- +Connect ChatGPT to your shared knowledge. :: +::card --- +title: Gemini CLI +icon: i-simple-icons-googlegemini +to: /integrations/gemini +--- +Connect Google's command-line AI agent through MCP. +:: -## Multi-Project Setup +::card +--- +title: Codex +icon: i-lucide-code +to: /integrations/codex +--- +Use Basic Memory while working with Codex. +:: -Basic Memory supports multiple projects for organizing different knowledge bases (work, personal, research, etc.). +::card +--- +title: Cursor +icon: i-lucide-mouse-pointer-2 +to: /integrations/cursor +--- +Use your Basic Memory knowledge while coding in Cursor. +:: +::: -**How it works:** +Other clients can connect if they support authenticated remote MCP servers. -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" +## Teach your AI when to use Basic Memory -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? +Connecting the MCP server gives an AI tool access to Basic Memory. Persistent instructions help it know **when** you want that access used. -You: "Yes, let's use work-notes" -``` +Add the following to your tool's custom instructions, project instructions, or equivalent: -**Creating projects:** -```bash -# Command line -basic-memory project add "work-notes" ~/Documents/work +```text +Use Basic Memory as our shared knowledge base. -# Or ask your AI assistant -You: "Create a new project called 'work-notes' in ~/Documents/work" +- Search Basic Memory when earlier decisions, project context, research, + instructions, or prior work may help. +- Save durable knowledge when we make an important decision, establish a + reusable workflow, complete research, or create context worth using later. +- Update an existing note when appropriate instead of creating duplicates. +- Ask before saving sensitive or personal information. ``` -**For users who primarily work in one project:** +You can adapt this to your work. For example, a software project might explicitly ask the AI to save architecture decisions and debugging discoveries, while a research project might emphasize sources, findings, and open questions. -Set a default fallback project in `~/.basic-memory/config.json`: +Different AI tools store these instructions in different places. Look for settings named **custom instructions**, **project instructions**, rules, or skills. Coding agents may use files such as `CLAUDE.md` or `AGENTS.md`. -```json -{ - "default_project": "main" -} -``` +The important part is the division of labor: the MCP connection gives the AI access to Basic Memory, and the instructions tell it when you want that access used. -With this set, the AI uses your default project when no project is specified. +For agents that support skills, the [Basic Memory Agent Skills](/integrations/skills) provide more detailed workflows than a short instruction block. MCP gives the assistant access to Basic Memory tools; skills teach the assistant how to use those tools well. --- -## Staying Updated +## Use Cloud from the terminal -To update Basic Memory when new versions are released: +You do not need the CLI to use Basic Memory Cloud. The web app and hosted MCP connection are enough for most workflows. -```bash -# Update with uv -uv tool upgrade basic-memory +Install the Basic Memory CLI when you want Cloud to participate in local workflows: syncing Markdown folders, publishing project notes, checking project status, managing API keys, recovering content, or automating repeatable knowledge tasks from scripts. -# Or Homebrew -brew upgrade basic-memory -``` +Start with [Cloud CLI](/cloud/cloud-cli) for the short command-line overview. Use [Edit Locally and in the App](/cloud/edit-locally-and-in-the-app) for a local Markdown workflow, or see [Cloud Sync](/cloud/cloud-sync) for the full sync reference. -::note -After updating, restart Claude Desktop for changes to take effect. -:: +--- + +## Work with other people + +Invite members when you are ready to share the workspace. Everyone can work with the same projects and knowledge while workspace roles control what each person can manage. + +[Learn about collaboration →](/teams/about) --- -## Next Steps +## Choose your next step :::card-group ::card --- -title: User Guide -icon: i-lucide-book-open -to: /local/user-guide +title: Web App Guide +icon: i-lucide-layout-panel-left +to: /cloud/web-app --- -Comprehensive usage instructions for daily workflows. +Browse, edit, search, import, and manage knowledge in the browser. :: ::card @@ -149,42 +189,24 @@ title: Knowledge Format icon: i-lucide-file-text to: /concepts/knowledge-format --- -Learn how knowledge is structured with semantic patterns. +Understand notes, observations, relations, tags, and Markdown. :: ::card --- -title: CLI Reference -icon: i-lucide-terminal -to: /reference/cli-reference +title: Import Knowledge +icon: i-lucide-file-up +to: /cloud/web-app --- -Complete command line tools reference. +Bring existing notes and document collections into your workspace. :: ::card --- -title: Troubleshooting +title: MCP Tools icon: i-lucide-wrench -to: /reference/troubleshooting ---- -Common issues and solutions. -:: - -::card ---- -title: Schema System -icon: i-lucide-shield-check -to: /concepts/schema-system ---- -Define and validate note structure with schemas. -:: - -::card ---- -title: Semantic Search -icon: i-lucide-search -to: /concepts/semantic-search +to: /reference/mcp-tools-reference --- -Search by meaning with vector and hybrid modes. +See the tools connected AI assistants can use. :: ::: diff --git a/content/1.start-here/5.why-basic-memory.md b/content/1.start-here/5.why-basic-memory.md deleted file mode 100644 index cc81da2..0000000 --- a/content/1.start-here/5.why-basic-memory.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Why Basic Memory -description: Your AI already has memory features. Here's why you still want a knowledge base you own — and how Basic Memory is different from the alternatives. ---- - -Every AI tool is adding memory. Claude has CLAUDE.md and auto memory. ChatGPT remembers facts about you. Obsidian users have been doing this with markdown for years. And a new wave of startups is building memory-as-a-service on top of databases. - -So why Basic Memory? - -Because none of these solve the whole problem. They each handle a piece of it, but they leave gaps that matter more as your knowledge grows. - ---- - -## The three alternatives - -### 1. Built-in AI memory - -Claude, ChatGPT, Cursor, and others now ship with some form of memory. Claude Code has CLAUDE.md files and auto memory. ChatGPT has saved memories and reference chat history. These are useful for quick preferences — "I use TypeScript," "I'm vegetarian," "use 2-space indentation." - -**Where it falls short:** - -- **Short-form only.** ChatGPT memories are single sentences. Claude Code's auto memory index caps at 200 lines. You can't store a detailed architecture decision, a meeting summary, or a research synthesis. -- **Siloed.** Claude's memory only works in Claude. ChatGPT's only works in ChatGPT. If you use more than one AI tool, your knowledge is fragmented. A decision captured in Claude Code isn't available when you switch to Cursor or ChatGPT. -- **Not searchable.** There's no semantic search, no knowledge graph, no way to ask "find everything related to our authentication approach" and get structured results. -- **Not yours to keep.** If the platform changes its terms, shuts down, or you switch tools, your memories don't come with you. - -Basic Memory works alongside built-in memory — it doesn't replace it. Use built-in memory for preferences. Use Basic Memory for everything deeper. See [Basic Memory vs Built-in AI Memory](/concepts/vs-built-in-memory) for the detailed comparison. - ---- - -### 2. Obsidian - -Obsidian is excellent — and it's the approach closest to Basic Memory's philosophy. Plain markdown files, wiki links, graph view, local-first. With the recent addition of headless mode and CLI commands, Obsidian can even be integrated with AI tools through skills and automation. - -If you're already an Obsidian user, you're halfway to Basic Memory's worldview. The question is what you get by adding Basic Memory on top. - -**What Basic Memory adds to the Obsidian experience:** - -- **Semantic search.** Obsidian's search finds exact text matches. Basic Memory finds notes about "error handling" when you wrote "exception management" — it searches by meaning, not just keywords. Hybrid search combines vector similarity with text matching for the best of both. -- **A semantic knowledge graph.** Basic Memory parses observations and relations from your notes to build a typed knowledge graph. You can ask "what depends on this decision?" and traverse connections across your entire knowledge base — not just follow backlinks, but navigate structured relationships. -- **Schemas.** Define what a meeting note or decision record should contain. The AI validates notes against schemas automatically, keeping your knowledge base consistent as it grows. -- **Cloud access.** Your knowledge is available from any device, with any AI tool. Basic Memory Cloud means your notes aren't stuck on one machine — use them from Claude Desktop at work, ChatGPT on your phone, or Cursor on your laptop. -- **Cross-tool portability.** Notes created in Claude Code are searchable in ChatGPT, editable in Cursor, and visible in Obsidian. One knowledge base, every AI tool you use. - -The best part: you don't have to choose. [Obsidian is a great companion](/integrations/obsidian) for Basic Memory. Point both at the same folder and you get Obsidian's graph view and rich editing, plus AI-powered semantic search, schemas, and cloud access on top. - ---- - -### 3. Database-only memory services - -A growing number of startups offer AI memory as a service — Mem0, Letta, Supermemory, and others. They store memories in databases behind APIs, often with vector search and cloud infrastructure. - -**Where it falls short:** - -- **You can't read what the AI knows.** Your knowledge lives in a database you access through an API. You can't open a file, read what's there, fix a mistake, or reorganize your notes. The AI's understanding of you is opaque. -- **You can't edit it naturally.** Want to refine a decision the AI captured? You need to go through the API or a dashboard. You can't just open a markdown file in your editor and fix it. -- **Vendor lock-in.** Your knowledge is in a proprietary format in someone else's database. If the service shuts down, changes pricing, or pivots, migrating is painful — if it's possible at all. -- **Not built for humans.** These tools treat memory as something the AI manages *about* you. Basic Memory treats knowledge as something you and your AI build *together*. You're a participant, not a subject. - -Plain text files from 1975 are still readable today. Can you say that about any proprietary database format? - ---- - -## What makes Basic Memory different - -Basic Memory takes a different position from all three alternatives: - -**Your memory is a file you can read.** Not a database entry you can't see. Not a single sentence in a settings page. A full markdown note with observations, relations, and tags — readable in any editor, trackable with git, portable forever. - -**Your AI is a collaborator, not a recorder.** Both you and your AI read and write the same files. You capture rough notes, the AI structures them. The AI writes a summary, you refine it. Knowledge flows in both directions. - -**It works across every AI tool.** Notes created in Claude Code are available in ChatGPT, Cursor, Gemini, or any MCP-compatible tool. One knowledge base, many interfaces. - -**Search finds meaning, not just keywords.** Semantic search finds notes about "login security" even when you wrote "authentication hardening." Combined with text search, metadata filtering, and knowledge graph traversal, you can find anything in your knowledge base. - -**Structure grows with you.** Start with simple notes. Add observations and relations when they're useful. Define schemas when you want consistency. The system meets you where you are. - ---- - -## The best of all worlds - -You don't have to choose one approach. The strongest setup combines them: - -- **Built-in memory** for quick preferences your AI tool handles automatically -- **Basic Memory** for structured knowledge, decisions, research, and context -- **Obsidian** for visual graph exploration and rich editing alongside Basic Memory -- **Git** for version history on your knowledge base - -Basic Memory is the connective layer that makes your knowledge available everywhere, searchable by meaning, and yours to keep. - ---- - -## Get started - -:::card-group -::card ---- -title: "Quickstart: Cloud" -icon: i-lucide-cloud -to: /start-here/quickstart-cloud ---- -Connect in 2 minutes, no install needed. -:: - -::card ---- -title: "Quickstart: Local" -icon: i-lucide-hard-drive -to: /start-here/quickstart-local ---- -Run everything on your machine. -:: - -::card ---- -title: Basic Memory vs Built-in AI Memory -icon: i-lucide-layers -to: /concepts/vs-built-in-memory ---- -Detailed comparison with Claude, ChatGPT, and Cursor memory. -:: - -::card ---- -title: What is Basic Memory -icon: i-lucide-book-open -to: /start-here/what-is-basic-memory ---- -How it works under the hood. -:: -::: diff --git a/content/2.whats-new/0.teams.md b/content/2.whats-new/0.teams.md index d9079d5..b4b8786 100644 --- a/content/2.whats-new/0.teams.md +++ b/content/2.whats-new/0.teams.md @@ -1,14 +1,14 @@ --- -title: Basic Memory Teams -description: Share a cloud workspace with your team — invite members, assign roles, and build one knowledge base together. +title: Collaboration in Basic Memory Cloud +description: Invite members, assign roles, and build one shared knowledge base with humans and agents. --- -**Basic Memory Teams** brings your whole team into one shared knowledge base. Invite teammates into a shared cloud workspace, work from the same projects, and your AI assistant reaches those shared projects automatically. +Basic Memory Cloud now supports shared workspaces. Invite teammates, friends, or collaborators, work from the same projects, and let everyone's AI assistants use the same knowledge base. -Teams adds a **team workspace alongside your personal one** — your own notes and projects stay where they are, and you switch between workspaces in the app whenever you want. +Collaboration is a feature of every Cloud subscription, not a separate Teams product. A solo account starts with one seat. Add seats when you want to bring more people into a shared workspace. ::note{icon="i-lucide-users"} -Teams is a cloud feature and requires a subscription with one or more seats. Billing is per seat. Your personal cloud workspace (and any local projects) keep working alongside it. +Cloud subscriptions are billed per seat. Your private cloud projects and any local projects keep working alongside the workspaces you share with other people. :: ## What you get @@ -28,7 +28,7 @@ Owners invite members from **Settings → Teams**. Each member signs in with the :::card-group ::card --- -title: Teams Guide +title: Collaboration Guide icon: i-lucide-users to: /teams/about --- diff --git a/content/2.whats-new/1.v0.21.0.md b/content/2.whats-new/1.v0.21.0.md index 96d50f8..84f1ef2 100644 --- a/content/2.whats-new/1.v0.21.0.md +++ b/content/2.whats-new/1.v0.21.0.md @@ -1,9 +1,9 @@ --- title: v0.21.0 -description: Basic Memory Teams support — shared cloud workspaces that work consistently across MCP and CLI, plus faster search and sync and smarter Markdown parsing in v0.21. +description: Shared cloud workspaces that work consistently across MCP and CLI, plus faster search and sync and smarter Markdown parsing in v0.21. --- -v0.21.0 brings **Basic Memory Teams** support: shared cloud workspaces now work consistently across every MCP tool and CLI command, so your AI assistant reaches the right projects whether you're working solo or with a team. Search and sync are also noticeably faster, with smarter, more predictable Markdown parsing. +v0.21.0 brings shared-workspace support across every MCP tool and CLI command, so your AI assistant reaches the right projects whether you're working alone or with other people. Search and sync are also noticeably faster, with smarter, more predictable Markdown parsing. ::note **Heads up: relation parsing fix.** Unquoted multi-word text before a wikilink used to be misread as a custom relation type. That's fixed — but if you intentionally relied on multi-word relation types, **quote them before upgrading** so they survive the next re-sync. See [Upgrading](#upgrading) below. @@ -11,9 +11,9 @@ v0.21.0 brings **Basic Memory Teams** support: shared cloud workspaces now work --- -## Basic Memory Teams Support +## Shared Workspace Support -This is our first release to include support for Basic Memory Teams (subscription required). When you work with Teams, your projects live in a shared cloud workspace that everyone on the team can read and write. If you have a local workspace or personal Basic Memory subscription you can continue to use both at the same time. +This is our first core release with consistent support for shared Basic Memory Cloud workspaces. Collaboration is a Cloud feature rather than a separate Teams product. Projects in a shared workspace are available to its members according to their roles, while your private cloud and local projects remain available alongside them. What you'll notice: @@ -107,4 +107,4 @@ workspace-qualified permalinks, and SQLite vector reindexing handles - Updated: [Knowledge Format](/concepts/knowledge-format) — relation-type quoting rules - New: [Teams](/teams/about) — shared cloud workspaces, roles, and invitations -For commit-level release history, see [Changelog](/whats-new/changelog). +For commit-level release history, see [Changelog](/changelog). diff --git a/content/2.whats-new/2.hermes-plugin.md b/content/2.whats-new/2.hermes-plugin.md index 775f939..f017f6f 100644 Binary files a/content/2.whats-new/2.hermes-plugin.md and b/content/2.whats-new/2.hermes-plugin.md differ diff --git a/content/2.whats-new/3.cloud.md b/content/2.whats-new/3.cloud.md index f22e77d..bf5ed68 100644 --- a/content/2.whats-new/3.cloud.md +++ b/content/2.whats-new/3.cloud.md @@ -60,7 +60,7 @@ Share a workspace and collaborate with your team. ::card --- -title: Cloud Guide +title: Cloud Overview icon: i-lucide-cloud to: /cloud/cloud-guide --- diff --git a/content/2.whats-new/4.changelog.md b/content/2.whats-new/4.changelog.md index 25182ba..1ee6717 100644 --- a/content/2.whats-new/4.changelog.md +++ b/content/2.whats-new/4.changelog.md @@ -1,13 +1,7 @@ --- -title: Basic Memory -description: Release notes for Basic Memory. +title: Changelog moved +description: The Basic Memory changelog now has a permanent top-level home. +navigation: false --- -All notable changes to [Basic Memory](https://github.com/basicmachines-co/basic-memory). - -::github-releases ---- -repo: basicmachines-co/basic-memory -limit: 30 ---- -:: +The changelog now lives at [Changelog](/changelog). diff --git a/content/3.cloud/01.cloud-guide.md b/content/3.cloud/01.cloud-guide.md index 0438ed9..197f6f6 100644 --- a/content/3.cloud/01.cloud-guide.md +++ b/content/3.cloud/01.cloud-guide.md @@ -1,380 +1,167 @@ --- -title: Basic Memory Cloud -description: Cloud remote MCP setup, web editor, CLI tools, and snapshots for Basic Memory Cloud. +title: Overview +description: What Basic Memory Cloud includes and where to go next. --- -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. +Basic Memory Cloud is the hosted version of Basic Memory. It gives people and AI tools one shared place to create, organize, search, and maintain knowledge without running a local server. -::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 +Cloud includes: -Basic Memory Cloud uses Remote MCP to connect to AI assistants. The connection URL is: +- A web app for writing, browsing, searching, and organizing knowledge +- A hosted MCP endpoint that works across supported AI tools +- Projects and folders for anything from a small workflow to a large document collection +- Imports for existing Markdown, Basic Memory data, and exported AI conversations +- Shared workspaces, invitations, roles, and collaboration +- Public, read-only links for sharing individual notes +- File history and snapshots for recovering earlier work +- Optional CLI workflows, API keys, local editing, and Cloud sync for advanced workflows -``` +```text https://cloud.basicmemory.com/mcp ``` -::steps -### Open Claude Settings - -In Claude Web or Desktop, go to **Settings → Claude → Connectors** - -### Add Custom Connector - -Click **Add custom connector** and enter: -- **Name**: Basic Memory -- **Remote MCP server URL**: `https://cloud.basicmemory.com/mcp` - -Click **Add** - -### Authenticate - -Click **Connect** to authenticate and grant permissions to Claude. - -This opens an OAuth flow to authorize Claude to access your Basic Memory Cloud account. - -### Configure Tools (Optional) - -Click **Configure** to customize which tools are enabled. You can enable or disable specific tools and configure permissions. - -### Verify Setup - -Confirm Basic Memory is available in the "search and tools" menu for a chat. All your notes will be saved to your cloud instance. -:: - ::tip -For detailed Claude setup instructions, see the [Claude Desktop Integration](/integrations/claude-desktop) guide. +New to Cloud? Start with the [Cloud quickstart](/start-here/quickstart-cloud). It walks through account setup, connecting an AI tool, and creating your first note. :: --- -## 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. +## What to set up first +:::card-group +::card --- - -## Web App - -Browse, edit, and collaborate on your cloud notes directly in your browser at [app.basicmemory.com](https://app.basicmemory.com). - -**Key features:** -- **Edit notes** - A rich editor, plain Markdown source mode, and a read-only preview with clickable wiki links -- **Collaborate with AI** - Connect an agent and watch it write alongside you in the same note -- **Import conversations** - Import ChatGPT, Claude, or JSON data -- **Manage projects** - Create, switch between, and manage projects -- **Upload files** - Bulk upload markdown files and directories -- **Download archives** - Export projects as zip files for backup - -::tip -For the complete web app guide including editing modes, drafts, AI collaboration, importing, and project management, see the [Web App Guide](/cloud/web-app). -:: - +title: Connect an AI Tool +icon: i-lucide-plug +to: /integrations --- - -## 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 +Connect Claude, Claude Code, ChatGPT, Gemini CLI, Codex, Cursor, or another supported tool. :: -### 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 -CLI commands use cloud routing unless a project is explicitly set to local mode -✓ Tokens saved to ~/.basic-memory/basic-memory-cloud.json -``` - -### Per-project Cloud Routing - -You can route specific projects through cloud while keeping others local: - -```bash -# Save or create an API key -bm cloud api-key save bmc_... -bm cloud api-key create "my-laptop" - -# Route one project through cloud -bm project set-cloud research - -# Revert to local for that project -bm project set-local research -``` - -::tip -For the full routing model — including priority levels, hybrid setups, and common configurations — see [Local & Cloud Routing](/cloud/routing). +::card +--- +title: Web App +icon: i-lucide-layout-panel-left +to: /cloud/web-app +--- +Browse, edit, search, import, and manage knowledge in the browser. :: -**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). +::card +--- +title: Collaboration +icon: i-lucide-users +to: /teams/about +--- +Invite members, choose roles, and share projects with your team. :: +::card --- - -## Upload Files to Cloud - -Upload local files or directories to cloud projects using `bm cloud upload`: - -```bash -# Upload a directory to existing project -bm cloud upload ~/my-notes --project research - -# Upload a single file -bm cloud upload important-doc.md --project research - -# Upload and create project in one step -bm cloud upload ~/local-project --project new-research --create-project - -# Upload without triggering sync -bm cloud upload ~/bulk-data --project archives --no-sync -``` - -**File Filtering:** The upload command respects `.bmignore` and `.gitignore` patterns, automatically excluding: -- Hidden files (`.git`, `.DS_Store`) -- Build artifacts (`node_modules`, `__pycache__`) -- Database files (`*.db`, `*.db-wal`) -- Environment files (`.env`) - -**Complete Example:** -```bash -# 1. Login to cloud -bm cloud login - -# 2. Upload local project (creates project if needed) -bm cloud upload ~/specs --project specs --create-project - -# 3. Verify upload -bm project list -``` - -After sync completes, the notes are available in the [web app](https://app.basicmemory.com) and for AI conversations. - -::tip -For bidirectional sync (editing both locally and in cloud), see the [Cloud Sync Guide](/cloud/cloud-sync). +title: Projects +icon: i-lucide-folder +to: /concepts/projects-and-folders +--- +Organize workflows, documents, research, and other knowledge. :: +::: --- -## Cloud Snapshots +## Everyday Cloud workflows -Basic Memory Cloud includes point-in-time snapshots for backup and recovery. Create manual snapshots before major changes, or rely on automatic daily backups. +### Work in the web app -**Key features:** -- Create unlimited manual snapshots -- Automatic daily snapshots -- Browse historical versions -- Restore individual files or folders +Use [app.basicmemory.com](https://app.basicmemory.com) to write and organize notes, search your knowledge, import existing material, manage projects, and change workspace settings. -```bash -# Create a snapshot before major changes -bm cloud snapshot create "Before reorganization" +See the [Web App guide](/cloud/web-app). -# List all snapshots -bm cloud snapshot list +### Bring existing knowledge with you -# Browse and restore files -bm cloud snapshot browse snap_abc123 -``` +You do not have to start with an empty workspace. Import exported Claude or ChatGPT conversations, Basic Memory data, or existing Markdown files. You can also upload and download complete projects. -::tip -For complete snapshot management including restore procedures and best practices, see the [Cloud Snapshots Guide](/cloud/cloud-snapshots). -:: - ---- +See [Import data](/cloud/web-app#import-data) and [Manage projects](/cloud/web-app#manage-projects) in the Web App guide. -## Migrating to Cloud +### Use Basic Memory from AI tools -Already using Basic Memory locally? You have two options: +Connect the hosted MCP endpoint to your AI tools so they can search, read, write, and update the same workspace. You can connect more than one tool without creating separate copies of your knowledge. -### Option 1: One-Time Upload (Fastest) +Use [Connect AI tools](/integrations) to choose a client, or jump to a specific guide: -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 -``` +- [Claude](/integrations/claude-desktop) +- [Claude Code](/integrations/claude-code) +- [ChatGPT](/integrations/chatgpt) +- [Gemini CLI](/integrations/gemini) +- [Codex](/integrations/codex) +- [Cursor](/integrations/cursor) +- [Agent Skills](/integrations/skills) +- [OpenClaw](/integrations/openclaw) +- [Hermes](/integrations/hermes) -**Use when:** -- You want to move to cloud-only -- One-time migration is sufficient -- Don't need ongoing local-cloud sync +### Collaborate with other people -### Option 2: Bidirectional Sync (Hybrid Workflow) +Cloud workspaces support team members, roles, shared projects, invitations, and billing seats. -Set up sync to work both locally and in cloud: +See [Collaboration](/teams/about). -```bash -# Login and setup sync -bm cloud login -bm cloud setup +### Share individual notes -# Add existing project with sync enabled -bm project add main --local-path ~/basic-memory +Publish a saved note as a public, read-only page when someone needs the result but not access to your workspace. You can disable or revoke the link later. -# Initial sync (resync creates baseline) -bm cloud bisync --name main --resync --dry-run # preview first -bm cloud bisync --name main --resync # establish baseline +See [Shared Notes](/cloud/shared-notes). -# Ongoing sync (run after local or cloud changes) -bm cloud bisync --name main -``` +### Recover changed or deleted content -**Use when:** -- You want to edit both locally (Obsidian, VS Code) and in cloud -- Need offline access -- Want automatic bidirectional sync +Use file history for changes to a single note. Use snapshots when you need to recover deleted content or restore a larger part of a project from an earlier point in time. -::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. -:: +- [File History](/cloud/file-history) +- [Cloud Snapshots](/cloud/cloud-snapshots) +- [Recover Notes](/cloud/restore-lost-content) -### Moving between cloud workspaces +### Get help -If your notes already live in one cloud workspace (say, your personal one) and you want to bring them into a [team workspace](/teams/about) — or vice versa — see [Copy Content Between Workspaces](/teams/copy-between-workspaces) for the project ZIP, single-note, MCP, and local-sync recipes. +If you are stuck on account access, billing, invitations, private Cloud data, or a workspace issue, see [Contact Support](/reference/contact-support). Use public Discord or GitHub only for issues that do not require private context. --- -## Next Steps +## Advanced options + +Cloud works entirely through the web app and hosted MCP endpoint. The options below are available when you need automation, local Markdown files, or a hybrid local-and-Cloud setup. Most people do not need them on day one. :::card-group ::card --- -title: Local & Cloud Routing -icon: i-lucide-route -to: /cloud/routing +title: Cloud CLI +icon: i-lucide-terminal +to: /cloud/cloud-cli --- -Run some projects locally and others in the cloud. +Use Cloud from the terminal for status, keys, sync, routing, and recovery. :: ::card --- -title: Cloud Sync Guide -icon: i-lucide-refresh-cw -to: /cloud/cloud-sync +title: API Keys +icon: i-lucide-key +to: /cloud/api-keys --- -Set up bidirectional sync for local editing. +Create bearer tokens for automation and clients that do not use OAuth. :: ::card --- -title: CLI Reference -icon: i-lucide-terminal -to: /reference/cli-reference +title: Local & Cloud Routing +icon: i-lucide-route +to: /cloud/routing --- -Complete CLI command reference. +Choose which local projects route through Cloud. :: ::card --- -title: MCP Tools Reference -icon: i-lucide-wrench -to: /reference/mcp-tools-reference +title: Cloud Sync +icon: i-lucide-refresh-cw +to: /cloud/cloud-sync --- -All available MCP tools for AI assistants. +Synchronize local files with Cloud for hybrid setups. :: ::: diff --git a/content/3.cloud/02.web-app.md b/content/3.cloud/02.web-app.md index f3e07e3..4f1f18b 100644 --- a/content/3.cloud/02.web-app.md +++ b/content/3.cloud/02.web-app.md @@ -1,9 +1,9 @@ --- title: Web App -description: Complete guide to the Basic Memory Cloud web app - browse, edit, search, and collaborate on your notes in the browser. +description: Browse, edit, search, import, share, and manage your Basic Memory Cloud workspace. --- -The Basic Memory web app at [app.basicmemory.com](https://app.basicmemory.com) is a full-featured interface for working with your knowledge base. Notes open ready to edit, your AI assistant can join you live, and everything is saved as plain Markdown. Anything your AI assistant can do, you can do here too. +The Basic Memory web app at [app.basicmemory.com](https://app.basicmemory.com) is the browser interface for your Cloud workspaces. Use it to write and organize notes, search across your knowledge, inspect the graph, import existing material, share notes, and manage projects and members. Notes remain portable Markdown. ::theme-image{light="/screenshots/cloud-app/v2-overview-light.png" dark="/screenshots/cloud-app/v2-overview-dark.png" alt="Web App Overview"} :: @@ -16,14 +16,22 @@ The app is organized into three panes: | Pane | Contents | |------|----------| -| **Sidebar** | Project and folder tree, search, your account avatar | +| **Sidebar** | Workspace selector, projects and folders, search, Graph, Activity, and your account menu | | **Note list** | Notes in the current folder or project, grouped by date | -| **Note detail** | The selected note, opened ready to edit | +| **Note detail** | The selected note and its editing, history, sharing, and file actions | Click a folder in the sidebar to filter the note list. Select a note to open it in the detail pane. --- +## Workspaces and projects + +Use the workspace selector near the top of the sidebar to move between personal and shared workspaces. Each workspace has its own projects, members, settings, and billing. + +Projects appear beneath the workspace name. Select a project to see its folders and notes, or use **Add project** to create one. Go to **Settings → Projects** for project visibility, uploads, downloads, and deletion. + +--- + ## Navigating notes ### Browse by folder @@ -41,7 +49,9 @@ Switch between views above the note list: ### Search notes -Use the search field in the sidebar to filter by title or content. Search is instant and scoped to the current project. +Open **Search** or press **Cmd/Ctrl + K** to find notes and navigate the app. Search can span all accessible workspaces and projects, or be narrowed with the workspace, project, and filter controls in the search dialog. + +The same dialog also opens Settings, Graph, Projects, Activity, and common actions such as creating a note or changing the current view. ::theme-image{light="/screenshots/cloud-app/v2-search-light.png" dark="/screenshots/cloud-app/v2-search-dark.png" alt="Search notes"} :: @@ -109,21 +119,23 @@ Saved notes are written automatically as you edit. Status dots tell you the stat --- -## Working with your AI assistant +## Working with AI tools -The web app treats your AI assistant as a real collaborator — you can watch it write, and steer it, in the same note you're editing. +AI tools connect to the same workspace through Basic Memory's hosted MCP endpoint. Notes created or changed by an AI tool appear in the web app, and changes you make in the app are available to connected tools. -### Connect an agent +Go to **Settings → MCP** to copy the endpoint, follow the common setup path, open client-specific guides, and copy a test prompt. -Click **Connect Agent** in the editor to start or resume an agent session for the workspace. When an agent is connected, the button shows its live status (for example, "Claude live"). +See [Connect AI tools](/integrations) for setup instructions. -### Improve a selection +--- + +## Collaboration -Select text in the editor and choose **Improve** to ask the agent to rewrite, summarize, or extend it. The agent's changes stream into the note as it works — connecting automatically if no agent is attached yet. +Cloud workspaces can include other people as owners, editors, or viewers. Use **Settings → Teams** to invite members, manage roles and invitations, transfer ownership, and edit the team name. Use **Settings → Billing** to manage seats and the workspace subscription. -### The agent pane +Project access is managed separately under **Settings → Projects**, where owners can choose who can find and work with each project. -The agent pane shows the session: what the agent is working on, its progress, and a place to steer it ("Ask for a rewrite, summary, or next step…"). Updates flow into the note in real time, so you can follow along while it writes. +See [Share Basic Memory With Your Team](/teams/about) for invitations, roles, seats, project visibility, and shared-workspace workflows. --- @@ -178,11 +190,10 @@ Use the project selector in the sidebar to switch between projects. Go to **Settings → Projects** to create new projects, upload files, download a project as a ZIP, or delete a project. -::theme-image{light="/screenshots/cloud-app/v2-manage-projects-light.png" dark="/screenshots/cloud-app/v2-manage-projects-dark.png" alt="Manage projects"} -:: +![Manage projects and project access in workspace settings](/screenshots/cloud-app/v2-manage-projects-current.png) ::tip -Upload entire folders and folder trees via the [command line tools](/cloud/cloud-guide#command-line-tools) — directory structure is preserved. +Upload entire folders and folder trees via [Cloud Sync](/cloud/cloud-sync) — directory structure is preserved. :: --- @@ -193,18 +204,18 @@ Import your existing AI conversations from **Settings → Import**. | Format | File | |--------|------| +| **Project ZIP** | A ZIP containing Markdown files and folders | | **Claude** | `conversations.json` from a Claude export | | **ChatGPT** | Export ZIP or JSON from ChatGPT settings | | **Basic Memory JSON** | Memory exports with entities & relations | 1. Go to **Settings → Import** -2. Select the import type -3. Choose a target project (or use the default) -4. Set a destination folder (default: `imports`) +2. Choose the workspace and target project +3. Select the import type +4. Optionally set a destination folder; leave it blank to import at the project root 5. Upload your file and start the import -::theme-image{light="/screenshots/cloud-app/v2-import-light.png" dark="/screenshots/cloud-app/v2-import-dark.png" alt="Import data"} -:: +![Import data into a workspace and project](/screenshots/cloud-app/v2-import-current.png) ::note Imported conversations are converted to Basic Memory's knowledge format automatically. @@ -212,6 +223,35 @@ Imported conversations are converted to Basic Memory's knowledge format automati --- +## Knowledge Graph + +Select **Graph** in the sidebar to inspect the structure Basic Memory has indexed from the current project. + +The Graph workspace includes: + +- **Project** — an overview of notes, observations, relations, connection health, and unresolved links +- **Structured** — browse indexed entities, observations, and relations as structured data +- **Explore** — navigate the full relationship graph visually +- **Review queues** — find unlinked notes, missing backlinks, and strong connector notes + +Use the project selector in the Graph workspace to inspect another project. + +--- + +## Activity and notifications + +Select **Activity** in the sidebar to see recent note changes, imports, indexing, and other workspace operations. + +Under **Settings → Notifications**, choose how live updates appear for each workspace: + +- **Toasts + Activity** +- **Activity only** +- **Off** + +Realtime note, project, and graph updates continue in every mode; this setting controls how they are presented. + +--- + ## Snapshots Create point-in-time backups of your cloud data from **Settings → Snapshots**. Use them before major changes like bulk imports or reorganizations. @@ -228,7 +268,7 @@ The web app is designed for keyboard-first navigation. Press **Cmd/Ctrl + /** to ### Command palette -Press **Cmd/Ctrl + K** to open the command palette and search for any action — navigate to notes, settings, the graph, or projects; create a new note; switch view modes; change theme; or run note and editor actions. +Press **Cmd/Ctrl + K** to search notes across accessible workspaces and projects, navigate to Settings, Graph, or Projects, create a note, switch list and gallery views, change theme, or run editor actions. ::theme-image{light="/screenshots/cloud-app/v2-command-light.png" dark="/screenshots/cloud-app/v2-command-dark.png" alt="Command palette"} :: @@ -280,43 +320,57 @@ Press **Cmd/Ctrl + K** to open the command palette and search for any action — Access settings from the user menu (top of the sidebar) or the command palette. +The table below is the useful level of detail for this guide. Settings with a substantial workflow have their own linked guide; small preferences are best understood directly in the app rather than repeated here. + ::theme-image{light="/screenshots/cloud-app/v2-settings-light.png" dark="/screenshots/cloud-app/v2-settings-dark.png" alt="Settings"} :: | Section | What it does | |---------|--------------| -| **General** | Account and profile settings | -| **Projects** | Create, upload to, download, and delete projects | -| **Import** | Import Claude, ChatGPT, or JSON exports | -| **MCP** | Connect AI assistants via MCP | +| **General** | Profile, workspaces, and editor preferences | +| **Themes** | Choose color mode, theme preset, and editor appearance | +| **Projects** | Create and manage workspace, private, and shared projects | +| **Import** | Import project ZIPs, Claude or ChatGPT exports, and Basic Memory JSON | +| **MCP** | Copy the hosted endpoint, open tool guides, and test a connection | +| **Notifications** | Choose how live workspace updates appear | | **Teams** | Manage [team members, roles, and invitations](/teams/about) | -| **Billing** | Manage payment and subscription | +| **Billing** | Manage plans, seats, renewal, and cancellation | | **API Keys** | Create and manage [API keys](/cloud/api-keys) for programmatic access | +| **Support** | Find help for account, billing, workspace, and private Cloud issues | | **Snapshots** | Manage [point-in-time backups](/cloud/cloud-snapshots) | +| **Audit Logs** | Filter and review workspace activity history | | **Shared Notes** | Manage public [share links](/cloud/shared-notes) for your notes | +| **Version** | View the deployed web app build | ::note The **Teams**, **Billing**, and **Audit Logs** sections appear based on your workspace and role. See [Teams](/teams/about) for collaboration features. :: -You can also customize appearance — see [Themes](/cloud/themes). +--- + +## Themes + +Themes live in **Settings → General → Look & Feel**. Use them to change the app's appearance in your current browser. Theme choices do not change your notes or what other workspace members see. + +![The General settings screen with Look & Feel controls for system, light, dark, and color theme presets.](/screenshots/cloud-app/themes-settings.png) + +You can: + +- Choose **System**, **Light**, or **Dark** mode. +- Pick a color preset for the interface. +- Set editor preferences like default note mode, content width, and preview behavior. + +::note +Theme and editor appearance preferences are stored per browser. If you switch browsers, devices, or browser profiles, set them again. +:: --- ## Tips for Effective Use -### Organize with folders +### Start with projects, then add 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 projects for distinct bodies of knowledge or access boundaries. Add folders inside a project only when they make browsing easier; you do not need to design the entire structure in advance. ### Use pinned notes @@ -329,7 +383,7 @@ Before reorganizing folders, bulk importing, or deleting lots of notes, create a ### Collaborate with your assistant The web app and your AI assistant work together: -1. **AI creates** detailed notes during conversations — or writes alongside you with Connect Agent +1. **AI creates or updates** notes through MCP 2. **You browse and refine** in the web app 3. **AI references** your refined notes in future conversations @@ -356,6 +410,15 @@ to: /cloud/cloud-sync Set up bidirectional sync to edit locally and in cloud. :: +::card +--- +title: Cloud CLI +icon: i-lucide-terminal +to: /cloud/cloud-cli +--- +Use Cloud from terminal workflows. +:: + ::card --- title: CLI Reference diff --git a/content/3.cloud/03.cloud-sync.md b/content/3.cloud/03.cloud-sync.md index a1e0840..166ebdf 100644 --- a/content/3.cloud/03.cloud-sync.md +++ b/content/3.cloud/03.cloud-sync.md @@ -1,476 +1,250 @@ --- -title: Cloud Sync Guide -description: Guide to syncing your local Basic Memory projects with Basic Memory Cloud. +title: Cloud Sync +description: Keep a local Markdown folder synchronized with a Basic Memory Cloud project. --- -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. +Cloud Sync is an optional workflow for people who want to edit Cloud projects as local Markdown files in tools such as Obsidian, VS Code, or another text editor. ---- - -## Overview - -The cloud CLI enables you to: +You do not need Cloud Sync to use Basic Memory Cloud. The web app and hosted MCP endpoint work without a local copy. -- **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 +::note +This is an advanced hybrid workflow. For the shortest command-line overview, see [Cloud CLI](/cloud/cloud-cli). For the shortest practical sync setup, see [Edit Locally and in the App](/cloud/edit-locally-and-in-the-app). +:: --- -## Prerequisites +## Choose the right workflow -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 +| What you want | Recommended approach | +|---|---| +| Work entirely in the browser and AI tools | Use the [web app](/cloud/web-app) and hosted MCP endpoint | +| Import a folder once | Upload a Project ZIP from **Settings → Import** | +| Keep a personal Cloud project and local folder synchronized | Use two-way `bisync` | +| Publish a local folder to a team workspace | Use one-way `sync` | +| Keep sensitive projects only on your computer | Use the [open-source local installation](/local/local-install) | ::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 +Two-way `bisync` is supported only for **personal workspaces**. For a project in a shared team workspace, use one-way `bm cloud sync` to publish local changes to Cloud. :: --- -## Architecture: Project-Scoped Sync +## Before you start -### How It Works +You need: -Projects can exist in three states: +- A Basic Memory Cloud account +- The current Basic Memory CLI +- A Cloud project +- A local directory for its Markdown files -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:** +Check your installed version: ```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 --version +``` -bm project add research --local-path ~/Documents/research -bm project add work --local-path ~/work-notes -bm project add temp # No local sync +Update an older installation before following this guide: -# Now you can sync individually (after initial --resync): -bm cloud bisync --name research -bm cloud bisync --name work -# temp stays cloud-only +```bash +bm update ``` -**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 +## Set up a personal project for two-way sync -Authenticate and enable cloud mode: +### 1. Sign in ```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 +This authenticates the CLI with Basic Memory Cloud. It does not move or sync any files. -### 2. Set Up Sync - -Install rclone and configure credentials: +### 2. Configure file synchronization ```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` +Basic Memory installs or configures `rclone`, which performs the file transfer. -### 3. Add Projects with Sync +### 3. Attach a local directory -Create projects with optional local sync paths: +For a new Cloud project: ```bash -# Create cloud project without local sync -bm project add research +bm project add research --cloud --local-path ~/Documents/research +``` -# Create cloud project WITH local sync -bm project add research --local-path ~/Documents/research +For an existing Cloud project: -# Or configure sync for existing project +```bash bm cloud sync-setup research ~/Documents/research ``` -### 4. Sync Your Project +The local directory can live anywhere on your computer. -Establish the initial sync baseline. **Always preview with `--dry-run` first:** +### 4. Preview the initial sync + +The first two-way sync needs a baseline. Preview it before changing files: ```bash -# Step 1: Preview the initial sync bm cloud bisync --name research --resync --dry-run - -# Step 2: If all looks good, run the actual sync -bm cloud bisync --name research --resync ``` -::note{icon="i-lucide-info"} -**Why `--resync`?** This is an rclone requirement for the first bisync run. It establishes the initial state that future syncs will compare against. After the first sync, don't use `--resync` unless you need to force a new baseline. -:: - -### 5. Subsequent Syncs +Review the proposed uploads, downloads, and deletions carefully. -After the first sync, just run bisync without `--resync`: +### 5. Establish the baseline ```bash -bm cloud bisync --name research +bm cloud bisync --name research --resync ``` -**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. -:: +After the baseline exists, do not routinely use `--resync`. -### 6. Verify Setup +### 6. Sync later changes ```bash -bm cloud status +bm cloud bisync --name research ``` -You should see: -- `Mode: Cloud (enabled)` -- `Cloud instance is healthy` +Changes made locally or through the web app are copied to the other side. When the same file changed in both places, the newer version wins. --- -## File Synchronization - -### Understanding the Sync Commands - -| Command | Direction | Use Case | -|---------|-----------|----------| -| `bm cloud bisync` | Local ↔ Cloud | Two-way sync (recommended) | -| `bm cloud sync` | Local → Cloud | One-way, make cloud match local | -| `bm cloud check` | Verify | Check if files match | +## Publish a local project to a team workspace -### Two-Way Sync (Recommended) +Two-way bisync is intentionally unavailable for organization workspaces. To make Cloud match a local folder, configure the project and run one-way sync: ```bash -# First time - establish baseline -bm cloud bisync --name research --resync - -# Subsequent syncs -bm cloud bisync --name research +bm cloud sync-setup team-wiki ~/Documents/team-wiki +bm cloud sync --name team-wiki --dry-run +bm cloud sync --name team-wiki ``` -**Conflict resolution:** When the same file is edited both locally and in cloud, the newer file wins (based on modification time). +::warning +One-way sync treats the local folder as the source of truth. Cloud-only file changes can be replaced or removed. Always run `--dry-run` first. +:: -### One-Way Sync +For normal collaborative editing, use the web app and MCP tools instead. See [Collaboration](/teams/about). -```bash -bm cloud sync --name research -``` +--- -Makes cloud identical to local. Use when local is the source of truth. +## Check sync status -### Preview Changes (Dry Run) +Check authentication, Cloud health, and configured project sync: ```bash -bm cloud bisync --name research --dry-run +bm cloud status ``` -Shows what would change without actually syncing. - -### Verify Integrity +Verify that the local and Cloud files match without transferring data: ```bash bm cloud check --name research ``` -Compares file checksums without making changes. - ---- - -## Multiple Projects - -### Syncing Multiple Projects +Use a faster one-direction check when you only need to detect files missing from the destination: ```bash -# Setup multiple projects -bm project add research --local-path ~/Documents/research -bm project add work --local-path ~/work-notes -bm project add personal --local-path ~/personal - -# Establish baselines -bm cloud bisync --name research --resync -bm cloud bisync --name work --resync -bm cloud bisync --name personal --resync - -# Daily workflow: sync everything -bm cloud bisync --name research -bm cloud bisync --name work -bm cloud bisync --name personal -``` - -### Mixed Usage - -```bash -# Projects with sync -bm project add research --local-path ~/Documents/research -bm project add work --local-path ~/work - -# Cloud-only projects -bm project add archive -bm project add temp-notes - -# Sync only the configured ones -bm cloud bisync --name research -bm cloud bisync --name work -# archive and temp-notes stay cloud-only +bm cloud check --name research --one-way ``` --- -## 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/** +## Work safely -# Basic Memory internals -memory.db/** -memory.db-shm/** -memory.db-wal/** +- Run `--dry-run` before the first sync or any operation that may move or delete many files. +- Allow one sync operation to finish before starting another. +- Create a [Cloud Snapshot](/cloud/cloud-snapshots) before a major reorganization. +- Do not edit the same file locally and in the web app at the same time. +- Keep at least one Markdown file in a new sync directory before establishing its first baseline. -# 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. -:: +Basic Memory respects `.bmignore` and project `.gitignore` patterns during file synchronization. Use them to exclude generated files, dependency folders, credentials, and editor metadata. --- ## Troubleshooting -### Authentication Issues +### Authentication failed -**Problem:** Authentication failed or Invalid token - -**Solution:** ```bash bm cloud logout bm cloud login ``` -### First Bisync Requires --resync +### Project has no local sync path -**Problem:** Bisync fails on first run +Attach a local directory, then establish a baseline: -**Solution:** ```bash +bm cloud sync-setup research ~/Documents/research bm cloud bisync --name research --resync ``` -This establishes the initial baseline state. - -### Empty Directory Issues - -**Problem:** "Empty prior Path1 listing. Cannot sync to an empty directory" - -**Solution:** Add at least one file before running `--resync`: -```bash -echo "# Research Notes" > ~/Documents/research/README.md -bm cloud bisync --name research --resync -``` - -### Bisync State Corruption +### Bisync state is inconsistent -**Problem:** Bisync fails with errors about corrupted state +Clear only the synchronization metadata, preview a new baseline, and then apply it: -**Solution:** ```bash bm cloud bisync-reset research +bm cloud bisync --name research --resync --dry-run bm cloud bisync --name research --resync ``` -### Too Many Deletes +`bisync-reset` does not delete your project files. -**Problem:** "max delete limit (25) exceeded" +### Too many deletions + +Bisync stops when a change exceeds its deletion safety limit. Inspect the proposed operation: -**Solution:** Review what's being deleted, then force resync if correct: ```bash bm cloud bisync --name research --dry-run -bm cloud bisync --name research --resync ``` -### Project Not Configured for Sync +Do not force a new baseline until you understand why the files would be removed. -**Problem:** "Project has no local_sync_path configured" +### First sync reports an empty directory + +Add a starter Markdown file, then retry: -**Solution:** ```bash -bm cloud sync-setup research ~/Documents/research +printf '# Research\n' > ~/Documents/research/README.md bm cloud bisync --name research --resync ``` --- -## Disable Cloud Mode - -Return to local mode: - -```bash -bm cloud logout -``` - -All `bm` commands now work with local projects. +## Related guides +:::card-group +::card --- - -## 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` - +title: Cloud CLI +icon: i-lucide-terminal +to: /cloud/cloud-cli --- +Short overview of Cloud commands and when to use them. +:: -## Command Reference - -### Cloud Mode Management - -```bash -bm cloud login # Authenticate and enable cloud mode -bm cloud logout # Disable cloud mode -bm cloud status # Check cloud mode and instance health -``` - -### Setup - -```bash -bm cloud setup # Install rclone and configure credentials -``` - -### Project Management - -```bash -bm project list # List cloud projects -bm project add # Create cloud project (no sync) -bm project add --local-path # Create with local sync -bm cloud sync-setup # Add sync to existing project -bm project rm # Delete project -``` - -### File Synchronization - -```bash -# Two-way sync (recommended) -bm cloud bisync --name # After first --resync -bm cloud bisync --name --resync # First time / force baseline -bm cloud bisync --name --dry-run -bm cloud bisync --name --verbose - -# One-way sync (local → cloud) -bm cloud sync --name -bm cloud sync --name --dry-run - -# Integrity check -bm cloud check --name - -# List remote files -bm project ls --name -``` - +::card --- - -## Summary - -**Basic Memory Cloud uses project-scoped sync:** - -1. **Enable cloud mode** - `bm cloud login` -2. **Install rclone** - `bm cloud setup` -3. **Add projects with sync** - `bm project add research --local-path ~/Documents/research` -4. **Preview first sync** - `bm cloud bisync --name research --resync --dry-run` -5. **Establish baseline** - `bm cloud bisync --name research --resync` -6. **Daily workflow** - `bm cloud bisync --name research` - -**Key benefits:** -- Each project independently syncs (or doesn't) -- Projects can live anywhere on disk -- Explicit sync operations (no magic) -- Safe by design (max delete limits, conflict resolution) -- Full offline access (work locally, sync when ready) - +title: Edit Locally and in the App +icon: i-lucide-file-pen-line +to: /cloud/edit-locally-and-in-the-app --- +The concise day-to-day hybrid workflow. +:: -## Next Steps - -:::card-group ::card --- -title: Cloud Guide -icon: i-lucide-cloud -to: /cloud/cloud-guide +title: Local & Cloud Routing +icon: i-lucide-route +to: /cloud/routing --- -Cloud features and setup options. +Choose whether individual projects use local or Cloud MCP operations. :: ::card @@ -479,24 +253,15 @@ 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. +Complete command and option reference. :: ::card --- -title: VS Code Integration -icon: i-lucide-code -to: /integrations/vscode +title: Recover Notes +icon: i-lucide-history +to: /cloud/restore-lost-content --- -Use cloud sync with VS Code. +Recover files with history, snapshots, or a local copy. :: ::: diff --git a/content/3.cloud/04.cloud-cli.md b/content/3.cloud/04.cloud-cli.md new file mode 100644 index 0000000..21058de --- /dev/null +++ b/content/3.cloud/04.cloud-cli.md @@ -0,0 +1,198 @@ +--- +title: Cloud CLI +description: Use Basic Memory Cloud from the terminal for status checks, API keys, sync, routing, recovery, and automation. +--- + +You do **not** need the CLI to use Basic Memory Cloud. The web app and hosted MCP endpoint are enough for most people. + +Install the CLI when you want Cloud to participate in terminal workflows: + +- Check Cloud connection and project status. +- Manage API keys for scripts or MCP clients. +- Sync a Cloud project with a local Markdown folder. +- Route selected local projects through Cloud. +- Create and restore Cloud snapshots. +- Automate repeatable knowledge tasks from shell scripts or CI jobs. + +::note{icon="i-lucide-cloud"} +Cloud CLI commands use the same Cloud account, workspaces, projects, and permissions as the web app and hosted MCP endpoint. +:: + +--- + +## Install and check the CLI + +If you have not installed Basic Memory locally yet, use `uv`: + +```bash +uv tool install basic-memory +``` + +Confirm the command is available: + +```bash +bm --version +``` + +Update an older install: + +```bash +bm update +``` + +See [Install Basic Memory locally](/local/local-install) for Homebrew and local MCP setup. + +--- + +## Sign in to Cloud + +Use browser-based login for an interactive terminal: + +```bash +bm cloud login +bm cloud status +``` + +`bm cloud login` authenticates the CLI. It does not automatically move local projects into Cloud or start syncing files. + +For automation, scripts, shared terminals, or clients that need bearer-token authentication, use an API key: + +```bash +# Save an existing key from Settings -> API Keys +bm cloud api-key save bmc_your_key_here + +# Or create and save a new key from the CLI +# Requires an active `bm cloud login` session +bm cloud api-key create "work-laptop" +``` + +See [API Keys](/cloud/api-keys) for the full key workflow and security guidance. + +--- + +## Inspect workspaces and projects + +List the Cloud workspaces available to your account: + +```bash +bm cloud workspace list +``` + +Set the default workspace used by Cloud commands when one is not specified: + +```bash +bm cloud workspace set-default acme +``` + +List projects across local and Cloud workspaces: + +```bash +bm project list +``` + +`bm project list` is the fastest sanity check when a terminal command or local MCP server is not using the project you expected. + +--- + +## Route selected local projects through Cloud + +Routing is for hybrid setups where you have the CLI or a local MCP server installed, but want specific projects to use Cloud. + +```bash +# Route one project through Cloud +bm project set-cloud research + +# Route a project through a specific workspace +bm project set-cloud research --workspace acme + +# Return the project to local routing +bm project set-local research --local-path ~/Documents/research +``` + +Routing is separate from file sync. A Cloud-routed project can be used by CLI and local MCP commands without keeping a local Markdown mirror. + +See [Local & Cloud Routing](/cloud/routing) for the routing model, precedence, and troubleshooting. + +--- + +## Sync Cloud with local files + +Use Cloud Sync when you want a local Markdown folder and a Cloud project to stay aligned. + +For a personal workspace project: + +```bash +bm cloud setup +bm cloud sync-setup research ~/Documents/research +bm cloud bisync --name research --resync --dry-run +bm cloud bisync --name research --resync +``` + +For team workspaces, use one-way publishing from local files to Cloud: + +```bash +bm cloud sync-setup team-wiki ~/Documents/team-wiki +bm cloud sync --name team-wiki --dry-run +bm cloud sync --name team-wiki +``` + +See [Edit Locally and in the App](/cloud/edit-locally-and-in-the-app) for the short workflow, or [Cloud Sync](/cloud/cloud-sync) for the full reference. + +--- + +## Recover content from the terminal + +Cloud snapshots are available from the CLI: + +```bash +bm cloud snapshot list +bm cloud snapshot create "Before reorganization" +bm cloud snapshot browse SNAPSHOT_ID --prefix research/ +bm cloud restore research/important-note.md --snapshot SNAPSHOT_ID +``` + +The CLI asks for confirmation before restore operations. Use `--force` only when you intentionally want to skip confirmation. + +See [Cloud Snapshots](/cloud/cloud-snapshots) and [Recover Notes](/cloud/restore-lost-content). + +--- + +## Related reference + +:::card-group +::card +--- +title: CLI Reference +icon: i-lucide-terminal +to: /reference/cli-reference +--- +Complete command and option reference. +:: + +::card +--- +title: API Keys +icon: i-lucide-key +to: /cloud/api-keys +--- +Create keys for automation and bearer-token MCP clients. +:: + +::card +--- +title: Local & Cloud Routing +icon: i-lucide-route +to: /cloud/routing +--- +Choose which projects use local or Cloud operations. +:: + +::card +--- +title: Cloud Sync +icon: i-lucide-refresh-cw +to: /cloud/cloud-sync +--- +Keep local Markdown folders aligned with Cloud projects. +:: +::: diff --git a/content/3.cloud/04.user-guide.md b/content/3.cloud/04.user-guide.md deleted file mode 100644 index 9594514..0000000 --- a/content/3.cloud/04.user-guide.md +++ /dev/null @@ -1,480 +0,0 @@ ---- -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 cloud 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 cloud 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/05.cloud-snapshots.md b/content/3.cloud/05.cloud-snapshots.md index aaf6344..28d48ba 100644 --- a/content/3.cloud/05.cloud-snapshots.md +++ b/content/3.cloud/05.cloud-snapshots.md @@ -1,225 +1,153 @@ --- title: Cloud Snapshots -description: Point-in-time backups for your Basic Memory Cloud knowledge base. +description: Create, download, browse, and restore point-in-time backups of a Basic Memory Cloud workspace. --- -Basic Memory Cloud includes point-in-time snapshots for backup and recovery. Create manual snapshots before major changes, or rely on automatic daily backups. +Snapshots preserve the state of an entire Basic Memory Cloud workspace at a particular moment. Use them before a large import, reorganization, restore, or other change you may want to undo. -::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. -:: +Basic Memory creates automatic snapshots daily. You can also create a manual snapshot whenever you need a specific rollback point. ::tip -**Need to recover something now?** Go to [Restore Lost Content](/cloud/restore-lost-content) for a step-by-step recovery guide. For a single note's recent edits, [File History](/cloud/file-history) is usually faster than restoring from a snapshot. +Trying to recover something now? See [Recover Notes](/cloud/restore-lost-content). For changes to one existing note, [File History](/cloud/file-history) is usually faster. :: --- -## What Snapshots Do +## What snapshots contain + +A snapshot covers the projects and files in the selected workspace. From a snapshot, you can: -- **Rollback** to a previous state after accidental changes -- **Browse** historical versions of your notes -- **Restore** individual files or entire folders -- **Protect** against accidental deletion +- Browse files as they existed at that time +- Download the snapshot as a ZIP archive +- Restore selected files or folders +- Recover a deleted project's files + +A restore writes the selected historical files back to their original paths. It does not roll the entire workspace backward or remove unrelated newer files. --- -## Using the Web App +## Manage snapshots in the web app + +Open **Settings → Snapshots**. The page shows the selected workspace, snapshot totals, and whether each snapshot is automatic or manual. -Manage snapshots directly in your browser at [app.basicmemory.com](https://app.basicmemory.com). +Snapshots require an active Cloud subscription. In a team workspace, the workspace owner manages snapshots. -### View Snapshots +Each snapshot has three actions: -Go to **Settings → Snapshots** to see all snapshots with creation time and description. +- **Restore** — browse and restore selected files or folders +- **Download** — download the snapshot as a ZIP archive +- **Delete** — remove the snapshot from the list -![Snapshots list](/screenshots/cloud-app/snapshots-list.png) +![The current Snapshots settings page, showing workspace totals and Restore, Download, and Delete actions.](/screenshots/cloud-app/snapshots-list.png) -### Create a Snapshot +### Create a manual snapshot -1. Click **Create Snapshot** -2. Add an optional description (e.g., "Before reorganizing projects") -3. Confirm +1. Select **Create Snapshot**. +2. Enter an optional description, such as `Before importing research archive`. +3. Select **Create**. -![Create snapshot](/screenshots/cloud-app/create-snapshot.png) +If you leave the description blank, Basic Memory uses the current timestamp. -### Restore from a Snapshot +![The Create Snapshot dialog with an optional description field.](/screenshots/cloud-app/create-snapshot.png) -1. Click on a snapshot → **Restore Files** -2. Filter by project or search for specific files -3. Select files or folders to restore -4. Click **Restore** to copy them back +### Restore files or folders -![Restore from snapshot](/screenshots/cloud-app/restore-files.png) +1. Select **Restore** beside the snapshot you want to use. +2. Choose a project under **Scope**, or browse all projects. +3. Search or browse for the files and folders you need. +4. Select one or more paths. +5. Select **Restore**. -::note -Restored files overwrite existing files with the same path. Consider creating a new snapshot before restoring if you want to preserve current state. +![The current snapshot restore screen with project scope, search, and selectable files and folders.](/screenshots/cloud-app/restore-files.png) + +::warning +Restoring overwrites current files at the selected paths. Create a new snapshot first if you may need to return to the current versions. :: --- -## Using the CLI - -Manage snapshots from the command line with `bm cloud snapshot` commands. +## Use snapshots from the CLI -### Create a Snapshot +The CLI uses the same Cloud snapshots. Sign in first: ```bash -bm cloud snapshot create "Before reorganization" -``` - -**Output:** -``` -Created snapshot: snap_abc123 (2026-01-27T10:30:00) +bm cloud login ``` -### List Snapshots +### Create and list snapshots ```bash +bm cloud snapshot create "Before reorganization" bm cloud snapshot list +bm cloud snapshot list --limit 20 ``` -**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 -``` +### Inspect a snapshot -### View Snapshot Details +Show its metadata: ```bash -bm cloud snapshot show snap_abc123 +bm cloud snapshot show ``` -### Browse Snapshot Contents - -View files in a snapshot without restoring: +Browse all files or filter by a path prefix: ```bash -bm cloud snapshot browse snap_abc123 +bm cloud snapshot browse +bm cloud snapshot browse --prefix research/ ``` -**Output:** -``` -notes/project.md -notes/ideas.md -research/analysis.md -meetings/2026-01-15.md -``` +### Restore a file or folder -Filter by path: +Restore uses `bm cloud restore`, not the `snapshot` command group: ```bash -bm cloud snapshot browse snap_abc123 --path notes/ +bm cloud restore research/important.md --snapshot +bm cloud restore research/ --snapshot ``` -### Restore Files +The CLI previews the affected files and asks for confirmation. Add `--force` only when you intentionally want to skip that prompt. -Restore a specific file: +### Delete a snapshot ```bash -bm cloud snapshot restore snap_abc123 --file notes/important.md +bm cloud snapshot delete ``` -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. -:: +The CLI asks for confirmation unless you add `--force`. --- -## 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 - ---- +## When to create a manual snapshot -## Automatic Snapshots +Create one before: -Basic Memory Cloud creates automatic daily snapshots: +- Importing a large collection +- Moving or renaming many files +- Reorganizing projects or folders +- Running a bulk edit or automation +- Restoring files from an older snapshot +- Deleting substantial content -- **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. +Use a description that explains the change you are about to make. The automatic daily snapshots remain useful for general recovery, while a named manual snapshot gives you a precise rollback point. --- -## Best Practices +## Snapshots and file history -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 +| Use | Best option | +|-----|-------------| +| Undo or compare edits to one existing note | [File History](/cloud/file-history) | +| Recover a deleted note | Snapshot | +| Recover a folder or deleted project | Snapshot | +| Preserve the workspace before a risky bulk change | Manual snapshot | +| Keep an offline copy of a point in time | Download snapshot | --- -## 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 - ---- +## Related guides -## 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. -:: -::: +- [Recover Notes](/cloud/restore-lost-content) +- [File History](/cloud/file-history) +- [Cloud Sync](/cloud/cloud-sync) +- [CLI Reference](/reference/cli-reference) diff --git a/content/3.cloud/06.themes.md b/content/3.cloud/06.themes.md deleted file mode 100644 index 4057315..0000000 --- a/content/3.cloud/06.themes.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -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. - -![Themes](/screenshots/cloud-app/themes.gif) ---- - -## Color Mode - -Switch between light, dark, or system-based color modes: - -1. Open **Settings** in the web app -2. Find the **Theme** section -3. Click **Light**, **Dark**, or **System** - -System mode automatically matches your operating system preference. - ---- - -## Preset Themes - -Choose from 40+ curated themes, each with coordinated colors for both light and dark modes. - -### Selecting a Theme - -1. Open **Settings** in the web app -2. Find the **Theme** section -3. Click the theme dropdown -4. Preview themes by hovering - see the color palette -5. Click to apply - -### Available Themes - -**Popular presets include:** -- **Default** - Clean white/dark gray base -- **Modern Minimal** - Blue-focused minimal design -- **Violet Bloom** - Purple-focused theme -- **T3 Chat** - Inspired by T3 Chat interface -- And 35+ more options - -Each theme defines: -- Background and foreground colors -- Primary and accent colors -- Sidebar colors -- Card and border styles -- Typography (optional) - ---- - -## Custom Themes - -Create your own theme with custom CSS variables. - -### Adding a Custom Theme - -1. Open **Settings** in the web app -2. Find the **Theme** section -3. Click **Custom Theme** -4. Paste your CSS or drag-and-drop a `.css` file -5. Click **Save** - -### CSS Format - -Custom themes use CSS variables in TweakCN format: - -```css -:root { - --background: oklch(1 0 0); - --foreground: oklch(0.145 0 0); - --card: oklch(1 0 0); - --card-foreground: oklch(0.145 0 0); - --popover: oklch(1 0 0); - --popover-foreground: oklch(0.145 0 0); - --primary: oklch(0.205 0 0); - --primary-foreground: oklch(0.985 0 0); - --secondary: oklch(0.97 0 0); - --secondary-foreground: oklch(0.205 0 0); - --muted: oklch(0.97 0 0); - --muted-foreground: oklch(0.556 0 0); - --accent: oklch(0.97 0 0); - --accent-foreground: oklch(0.205 0 0); - --destructive: oklch(0.577 0.245 27.325); - --border: oklch(0.922 0 0); - --input: oklch(0.922 0 0); - --ring: oklch(0.708 0 0); - --radius: 0.625rem; -} - -.dark { - --background: oklch(0.145 0 0); - --foreground: oklch(0.985 0 0); - /* ... dark mode overrides */ -} -``` - -### Required Variables - -Your custom theme must define these variables for both light (`:root`) and dark (`.dark`) modes: - -| Variable | Purpose | -|----------|---------| -| `--background` | Page background | -| `--foreground` | Primary text | -| `--card` | Card backgrounds | -| `--card-foreground` | Card text | -| `--popover` | Dropdown/menu backgrounds | -| `--popover-foreground` | Dropdown/menu text | -| `--primary` | Primary buttons, links | -| `--primary-foreground` | Text on primary elements | -| `--secondary` | Secondary elements | -| `--secondary-foreground` | Text on secondary elements | -| `--muted` | Muted backgrounds | -| `--muted-foreground` | Muted text | -| `--accent` | Accent highlights | -| `--accent-foreground` | Text on accents | -| `--destructive` | Delete/danger actions | -| `--border` | Borders | -| `--input` | Input field borders | -| `--ring` | Focus rings | - -### Optional Variables - -Customize typography and layout: - -```css -:root { - /* Typography */ - --font-sans: 'Inter', sans-serif; - --font-serif: 'Georgia', serif; - --font-mono: 'JetBrains Mono', monospace; - --letter-spacing: -0.01em; - - /* Layout */ - --radius: 0.5rem; - --spacing: 1rem; -} -``` - -### Sidebar Variables - -Customize the sidebar separately: - -```css -:root { - --sidebar: oklch(0.985 0 0); - --sidebar-foreground: oklch(0.145 0 0); - --sidebar-primary: oklch(0.205 0 0); - --sidebar-primary-foreground: oklch(0.985 0 0); - --sidebar-accent: oklch(0.97 0 0); - --sidebar-accent-foreground: oklch(0.205 0 0); - --sidebar-border: oklch(0.922 0 0); - --sidebar-ring: oklch(0.708 0 0); -} -``` - ---- - -## Using TweakCN - -[TweakCN](https://tweakcn.com) 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/07.api-keys.md b/content/3.cloud/07.api-keys.md index 668b349..2b075c0 100644 --- a/content/3.cloud/07.api-keys.md +++ b/content/3.cloud/07.api-keys.md @@ -3,7 +3,7 @@ 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. +API keys provide an alternative to OAuth for authenticating with Basic Memory Cloud. Use them for CLI tools, automation scripts, hybrid local/Cloud setups, or MCP clients that support bearer token authentication. --- @@ -13,6 +13,7 @@ API keys provide an alternative to OAuth for authenticating with Basic Memory Cl - **Automation friendly** - Use in scripts and CI/CD - **Multiple keys** - Create separate keys for different tools - **Revocable** - Disable a key without affecting others +- **CLI friendly** - Saved keys are used by Cloud-routed local projects --- @@ -50,76 +51,42 @@ Store your API key securely. Anyone with the key can access your Basic Memory ac ## 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 +### With MCP Clients -Add to `~/.codex/config.toml`: +Basic Memory Cloud's hosted MCP endpoint is: -```toml -[[mcp_servers]] -name = "basic-memory" -url = "https://cloud.basicmemory.com/mcp" -bearer_token_env_var = "BASIC_MEMORY_API_KEY" +```text +https://cloud.basicmemory.com/mcp ``` -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: +MCP clients that support custom bearer tokens or HTTP headers can use API keys with: ``` 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 -``` +For client-specific instructions, start with [Claude Desktop](/integrations/claude-desktop), [ChatGPT](/integrations/chatgpt), [Codex](/integrations/codex), or the individual integration pages. Prefer OAuth when a client supports Basic Memory Cloud's browser authorization flow. ### With Basic Memory CLI (per-project routing) -Save a key and route only selected projects through cloud: +Save a key and route selected local projects through Cloud: ```bash # Save an existing key from the web app bm cloud api-key save bmc_your_key_here -# Or create and save a new key (requires active OAuth session — run bm cloud login first) +# Or create and save a new key from the CLI +# Requires an active OAuth session from `bm cloud login` bm cloud api-key create "work-laptop" # Route one project through cloud bm project set-cloud research # Revert that project to local routing -bm project set-local research +bm project set-local research --local-path ~/Documents/research ``` -This lets you keep a hybrid setup where some projects stay local and others use cloud. See [Local & Cloud Routing](/cloud/routing) for the full routing model, priority levels, and common configurations. +Saved API keys take priority over OAuth tokens for local Cloud routing. This lets you keep a hybrid setup where some projects stay local and others use Cloud. See [Cloud CLI](/cloud/cloud-cli) for the short terminal workflow, or [Local & Cloud Routing](/cloud/routing) for the full routing model. --- @@ -179,8 +146,8 @@ bmc_ ``` - Prefix `bmc_` identifies it as a Basic Memory Cloud key -- 32 bytes of cryptographically random data -- URL-safe base64 encoding +- The remaining characters are a secret token generated by Basic Memory Cloud +- The CLI rejects saved keys that do not start with `bmc_` Example: `bmc_K7xR2pQmNvLwYhT9sU3fAeBcDgHiJkMnOpQrStUv` @@ -194,17 +161,18 @@ Example: `bmc_K7xR2pQmNvLwYhT9sU3fAeBcDgHiJkMnOpQrStUv` | 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 +- Local projects routed through Cloud Use **OAuth** for: -- Web applications -- First-time setup in Claude/ChatGPT +- Web app sign-in +- First-time interactive CLI setup +- AI clients that support Basic Memory's browser authorization flow - When you want automatic token refresh --- @@ -218,12 +186,26 @@ Use **OAuth** for: 3. Check the key hasn't expired 4. Ensure the Authorization header format is correct: `Bearer bmc_...` -### "Unauthorized" Error +### Unauthorized Error 1. Confirm your subscription is active 2. Verify the key belongs to your account 3. Try creating a new key +### Project Still Routes Locally + +Saving a key authenticates the CLI, but it does not move every project to Cloud. Route a project explicitly: + +```bash +bm project set-cloud research +``` + +If the project belongs to a specific workspace, include it: + +```bash +bm project set-cloud research --workspace team-name +``` + ### Key Not Showing in List Keys are only shown once at creation. If you lost the key: @@ -238,7 +220,16 @@ Keys are only shown once at creation. If you lost the key: :::card-group ::card --- -title: Cloud Guide +title: Cloud CLI +icon: i-lucide-terminal +to: /cloud/cloud-cli +--- +Use keys from terminal workflows and automation. +:: + +::card +--- +title: Cloud Overview icon: i-lucide-cloud to: /cloud/cloud-guide --- diff --git a/content/3.cloud/08.routing.md b/content/3.cloud/08.routing.md index b0edbc2..9d8dd23 100644 --- a/content/3.cloud/08.routing.md +++ b/content/3.cloud/08.routing.md @@ -1,161 +1,195 @@ --- title: Local & Cloud Routing -description: Choose where each project lives — on your computer, in the cloud, or a mix of both. +description: Route selected CLI and local MCP projects through Basic Memory Cloud. --- -Basic Memory is a knowledge base that you and your AI share. By default, your notes live on your computer. With Basic Memory Cloud, you can also store notes in the cloud — accessible from any device. Routing lets you choose where each project lives. +Basic Memory can run locally, in Basic Memory Cloud, or in a hybrid setup. Routing is the local CLI/MCP feature that decides whether a project is handled on your computer or forwarded to Basic Memory Cloud. ::note{icon="i-lucide-info"} -**When does routing apply?** This page is for people who have Basic Memory installed on their computer and want to connect some projects to the cloud. If you use Basic Memory Cloud directly (through the web app or by adding `cloud.basicmemory.com` to your AI tool), your notes are already in the cloud — no routing setup needed. +You do not need routing to use the Basic Memory web app or the hosted MCP endpoint at `https://cloud.basicmemory.com/mcp`. This page is for people who also use the Basic Memory CLI or a local MCP server and want selected projects to use Cloud. + +For the shorter command-line overview, start with [Cloud CLI](/cloud/cloud-cli). :: --- ## How Routing Works -When Basic Memory runs on your computer, it decides where to handle each request based on your settings: +When Basic Memory runs on your computer, project-scoped requests follow this order: -- **Local mode** — Files and database stay on your machine. No network requests. This is the default. -- **Cloud mode** — Requests are forwarded to your Basic Memory Cloud instance. Notes are stored in the cloud and accessible from any device. +1. **Explicit command flag** — Commands that support `--local` or `--cloud` use that flag for the current command. +2. **Project mode** — Projects marked with `bm project set-cloud` route through Cloud. Projects marked with `bm project set-local` stay local. +3. **Local default** — If no Cloud route is configured, Basic Memory uses the local project on your machine. -You use the same commands and your AI uses the same tools either way — the only difference is where your notes are stored. +Cloud-routed projects use your saved API key first. If no API key is saved, Basic Memory can use your browser login token from `bm cloud login`. --- -## Routing Levels - -Routing decisions follow a priority order — the most specific level wins: +## When To Use Routing -| Priority | Level | How to set | What it does | -|----------|-------|-----------|--------------| -| Highest | **Per-command** | `--local` / `--cloud` flags | Override for a single command | -| Medium | **Per-project** | `bm project set-cloud` / `set-local` | Persistent setting for a specific project | -| Lowest | **Global** | `bm cloud login` / `logout` | Default for all projects | +Use routing when you want one of these setups: -**Examples:** +- Work in local tools while keeping a project in Basic Memory Cloud. +- Keep private projects local and route shared projects through Cloud. +- Use Cloud workspaces from scripts or terminal workflows. +- Move a project to Cloud without changing every project on your machine. -- Global cloud mode is active, but `bm project set-local research` keeps the `research` project on your machine. -- You're in local-only mode, but `bm project set-cloud shared-notes` routes just that project through cloud. -- You need a quick cloud check: `bm search_notes --cloud "meeting notes"` overrides everything for that one call. +If you only use the web app and hosted MCP connection, skip this page. --- -## Setting Up Cloud Routing +## Authenticate The CLI -### Save an API Key - -API keys are the simplest way to enable cloud routing for specific projects. +Cloud-routed projects need Cloud credentials. You can use either method. ```bash -# Save a key you created in the web app -bm cloud api-key save bmc_your_key_here +# Interactive browser login +bm cloud login -# Or create a new key from the CLI (requires being logged in via `bm cloud login`) -bm cloud api-key create "my-laptop" +# Or save an API key from the web app +bm cloud api-key save bmc_your_key_here ``` -See [API Keys](/cloud/api-keys) for details on creating and managing keys. +API keys are usually best for automation, shared terminals, and repeatable setup. See [API Keys](/cloud/api-keys) for creating and managing keys. -### Route a Project to Cloud +--- + +## Route A Project Through Cloud + +Mark an existing local project as Cloud-routed: ```bash -# Route a specific project through cloud bm project set-cloud research ``` -After this, all MCP tool calls for the `research` project go through your cloud instance. +After this, MCP tools and CLI commands for `research` route through Basic Memory Cloud. + +If you have more than one Cloud workspace, attach the project to a specific workspace: + +```bash +bm project set-cloud research --workspace team-name +``` + +You can pass a workspace name, slug, type, or workspace ID. To set a default workspace for future Cloud commands: + +```bash +bm cloud workspace list +bm cloud workspace set-default team-name +``` -### Check Routing Status +::warning +`bm project set-cloud` changes routing; it does not delete your files. Basic Memory removes the local index entry and preserves the files on disk. If you want local files and Cloud content to stay in sync, see [Cloud Sync](/cloud/cloud-sync). +:: + +--- + +## Check Project Routing ```bash -# See which projects are cloud-routed +bm project list bm cloud status ``` -### Revert to Local +`bm project list` shows each project's local path, cloud path, workspace, CLI route, and MCP transport. `bm cloud status` checks your Cloud connection and reports configured Cloud projects. + +--- + +## Force One Command + +Some CLI commands support `--local` and `--cloud` flags. Use them when you need a one-time override without changing the saved project mode. + +The exact command depends on the operation. If a command supports routing flags, it will show them in its help output: + +```bash +bm project info --help +``` + +--- + +## Return A Project To Local + +To route a Cloud project back through your local files, give Basic Memory the local path: + +```bash +bm project set-local research --local-path ~/Documents/research +``` + +If the project still has a previous local path recorded, you can omit `--local-path`: ```bash -# Switch a project back to local bm project set-local research ``` -The project returns to local mode immediately. Your cloud data remains in the cloud — this only changes where new requests are handled. +Your Cloud data remains in Cloud. This only changes where local CLI and MCP requests go next. --- ## Common Setups -### All Local (Default) +### Local Only -No configuration needed. Every project runs on your machine. This is how Basic Memory works out of the box. +No setup required. Projects you add locally stay local unless you explicitly route them through Cloud. -### All Cloud +### Cloud From Local Tools -Log in and everything routes through cloud: +Use Cloud as the source of truth for a selected project: ```bash -bm cloud login +bm cloud api-key save bmc_your_key_here +bm project set-cloud research ``` -All projects use your cloud instance. Use `bm cloud logout` to return to local-only. - -### Hybrid (Local + Cloud) +### Hybrid -This is the most popular setup — keep private notes on your computer while sharing specific projects across devices. +Keep personal projects local and route shared projects through Cloud: ```bash -# Save your API key for per-project routing bm cloud api-key save bmc_your_key_here -# Route shared projects to cloud bm project set-cloud shared-notes -bm project set-cloud team-wiki - -# Personal projects stay local (no action needed — local is the default) +bm project set-cloud team-wiki --workspace acme ``` -This is useful when you want to: -- Keep sensitive or personal projects on your machine -- Share specific projects across devices -- Collaborate on cloud projects while working locally on others +Local projects require no extra configuration. ### Gradual Migration -Start local and move projects to cloud one at a time: +Upload or copy content into Cloud, then route the project through Cloud: ```bash -# 1. Start with everything local (default) - -# 2. Upload a project to cloud bm cloud upload ~/my-notes --project my-notes --create-project - -# 3. Route that project to cloud bm cloud api-key save bmc_your_key_here bm project set-cloud my-notes - -# 4. Repeat for other projects as needed ``` +Repeat for each project you want Cloud to own. + --- -## Authentication +## Routing And Sync Are Different + +Routing decides where Basic Memory handles a project. + +Sync copies files between a local folder and Cloud storage. -Cloud-routed projects need credentials. Basic Memory supports two methods: +You can route a project through Cloud without maintaining a local copy. You can also keep a local working folder synchronized with Cloud when that workflow is useful. + +Start with [Edit Locally and in the App](/cloud/edit-locally-and-in-the-app) for the short version, or use [Cloud Sync](/cloud/cloud-sync) for the full reference. + +--- -| Method | Best for | How to set up | -|--------|----------|---------------| -| **API keys** | CLI, hybrid setups, automation | `bm cloud api-key save bmc_...` | -| **Browser login** | Interactive use, global cloud mode | `bm cloud login` | +## Credentials And Logout -Both methods work for any cloud-routed project. API keys are preferred for hybrid setups because they don't require opening a browser. +`bm cloud login` signs the CLI into Basic Memory Cloud. It does not automatically move every local project into Cloud mode. -See [API Keys](/cloud/api-keys) for detailed setup instructions. +`bm cloud logout` removes the saved OAuth session and default workspace, but it does not remove a saved API key. If you saved an API key, Cloud-routed projects can still use it until you remove or replace it. --- ## How It Works Under the Hood -- **Local mode** — Requests are handled directly on your machine with no network involved. -- **Cloud mode** — Requests are forwarded to `cloud.basicmemory.com` using your credentials (API key or login token). The cloud instance processes the request and returns the result. +- **Local mode** uses the in-process Basic Memory service and your local project files. +- **Cloud mode** forwards project requests to Basic Memory Cloud using your API key or OAuth token. +- **Workspace routing** uses a per-project workspace when configured, then the default workspace, then an unambiguous single workspace when Basic Memory can resolve one. -In both cases, the same tools and commands work identically. The only difference is where the work happens. +The goal is simple: the same Basic Memory tools can work with local projects, Cloud projects, or a deliberate mix of both. diff --git a/content/3.cloud/09.shared-notes.md b/content/3.cloud/09.shared-notes.md index da640b5..085071f 100644 --- a/content/3.cloud/09.shared-notes.md +++ b/content/3.cloud/09.shared-notes.md @@ -5,6 +5,8 @@ description: Create a public, read-only link to a note so anyone can view it — Shared Notes let you publish a single note as a public, read-only web page. Anyone with the link can read it without signing in — handy for sharing a document, a spec, or a writeup with people outside your workspace. +Use Shared Notes for material you are comfortable making link-accessible. For private team material, invite people to the workspace or grant project access instead of creating a public link. + ::theme-image{light="/screenshots/cloud-app/v2-shared-note-public-note-light.png" dark="/screenshots/cloud-app/v2-shared-note-public-note-dark.png" alt="A shared note"} :: @@ -47,8 +49,8 @@ The shared link opens a clean, full-page rendered view of the note. Visitors: - **Don't need an account** and **can't edit** — it's read-only. - Can follow `[[wiki links]]` in the note (they render as preview links). -- Can view the note's frontmatter and copy the link. -- Can grab the raw Markdown by adding `/raw` to the URL — useful for feeding a note to a tool or LLM. +- Can view the note's frontmatter when the shared page includes it. +- Can copy the public link from the page. If a link is invalid, disabled, or revoked, the page simply returns a generic "not found" — your workspace and share details are never exposed. @@ -75,7 +77,7 @@ Moving or renaming a note **doesn't break** its share link — the link follows ## Who can share -In a [team workspace](/teams/about), **owners and editors** can create, disable, and revoke share links. **Viewers** can't manage shares. In a personal workspace, you manage your own. +In a [team workspace](/teams/about), share management follows workspace permissions: **owners and editors** can create, disable, and revoke share links for notes they can edit. **Viewers** can't manage shares. In a personal workspace, you manage your own. --- @@ -84,6 +86,7 @@ In a [team workspace](/teams/about), **owners and editors** can create, disable, - Each note has **one** public link in the app. - Links have **no password** — anyone who has the link can read the note, so only share notes you're comfortable making public. - Revoke or disable a link from **Settings → Shared Notes** the moment you no longer want it reachable. +- If you accidentally shared private material, disable or stop sharing the link first, then [contact support](/reference/contact-support) if you need help reviewing the exposure. --- diff --git a/content/3.cloud/10.edit-locally-and-in-the-app.md b/content/3.cloud/10.edit-locally-and-in-the-app.md index e28af9b..712cf4b 100644 --- a/content/3.cloud/10.edit-locally-and-in-the-app.md +++ b/content/3.cloud/10.edit-locally-and-in-the-app.md @@ -1,12 +1,12 @@ --- title: Edit Locally and in the App -description: Happy-path setup for hybrid editing — work on the same project in Obsidian or VS Code locally and in the cloud app, with bidirectional sync keeping both sides in step. +description: Set up a personal Cloud project for editing in both the web app and a local Markdown editor. --- -You want the best of both worlds: edit the same project in your local editor (Obsidian, VS Code, Cursor…) **and** in the [cloud app](/cloud/web-app), with both sides staying in sync. This page is the happy path — get a project sync'd in five steps, then the day-to-day routine. +Use this guide when you want to edit a personal Cloud project in both the [web app](/cloud/web-app) and a local Markdown editor such as Obsidian or VS Code. ::note{icon="i-lucide-info"} -This is a stitched-together how-to. For the deep reference on bidirectional sync — architecture, filters, conflict handling — see [Cloud Sync](/cloud/cloud-sync). +This is the shortest sync setup path. For a broader terminal overview, see [Cloud CLI](/cloud/cloud-cli). For team-workspace publishing, conflict handling, integrity checks, and recovery, see [Cloud Sync](/cloud/cloud-sync). :: --- @@ -17,6 +17,8 @@ This is a stitched-together how-to. For the deep reference on bidirectional sync - Edits in either place propagate to the other with `bm cloud bisync`. - Your AI assistant (via MCP) sees the same notes whether you're working locally or remotely. +Two-way `bisync` is for personal workspaces. Shared team workspaces use one-way publishing; see [Cloud Sync](/cloud/cloud-sync#publish-a-local-project-to-a-team-workspace). + --- ## One-time setup @@ -28,7 +30,7 @@ This is a stitched-together how-to. For the deep reference on bidirectional sync bm cloud login ``` -A browser tab walks you through OAuth. After confirming the displayed code, you're authenticated and CLI commands route through cloud by default. +A browser tab walks you through authentication. ### Install sync tooling @@ -111,9 +113,9 @@ That's it. The rest is editing wherever you like. --- -## What if I want some projects local-only and others in cloud? +## Keep other projects local -That's the [routing](/cloud/routing) model. You can keep personal projects entirely local while syncing only a couple of projects to cloud. The hybrid setup on this page is one routing configuration; routing covers the others (all-local, all-cloud, mixed, per-command overrides). +Syncing this project does not require moving every local project to Cloud. See [Local & Cloud Routing](/cloud/routing) when you want the installed CLI or local MCP server to route selected projects through Cloud. --- diff --git a/content/3.cloud/11.restore-lost-content.md b/content/3.cloud/11.restore-lost-content.md index 978c2b8..161ea5d 100644 --- a/content/3.cloud/11.restore-lost-content.md +++ b/content/3.cloud/11.restore-lost-content.md @@ -1,9 +1,9 @@ --- -title: Restore Lost Content +title: Recover Notes description: Recover a single note from File history, or roll back a bigger change from a Snapshot — pick the right tier and follow the exact steps. --- -You deleted a note you needed. A bulk reorganize went sideways. A teammate cleared out the wrong folder. Basic Memory Cloud has two recovery tiers — pick the one that matches what you lost. +You deleted a note you needed. A bulk reorganize went sideways. A teammate cleared out the wrong folder. Basic Memory Cloud has two recovery paths — pick the one that matches what you need to recover. | Lost what? | Use | |------------|-----| @@ -78,7 +78,7 @@ Before restoring, peek at what the snapshot actually contains — it saves a ste bm cloud snapshot browse snap_abc123 # List a specific folder -bm cloud snapshot browse snap_abc123 --path notes/ +bm cloud snapshot browse snap_abc123 --prefix notes/ # Show snapshot metadata bm cloud snapshot show snap_abc123 @@ -95,7 +95,7 @@ Restore is targeted — you pick the file, folder, or project you want back, not #### A single note ```bash -bm cloud snapshot restore snap_abc123 --file notes/important.md +bm cloud restore notes/important.md --snapshot snap_abc123 ``` Or in the web app: browse the snapshot, find the file, choose **Restore**. @@ -103,7 +103,7 @@ Or in the web app: browse the snapshot, find the file, choose **Restore**. #### A folder ```bash -bm cloud snapshot restore snap_abc123 --path research/ +bm cloud restore research/ --snapshot snap_abc123 ``` Restores everything under that path as it existed in the snapshot. @@ -113,7 +113,7 @@ Restores everything under that path as it existed in the snapshot. If you lost most of a project — or deleted it — restore the project root: ```bash -bm cloud snapshot restore snap_abc123 --path / +bm cloud restore / --snapshot snap_abc123 ``` ::note @@ -138,8 +138,8 @@ You can recover a deleted project the same way: find a snapshot from before the ```bash bm cloud snapshot list -bm cloud snapshot browse snap_abc123 --path my-project/ -bm cloud snapshot restore snap_abc123 --path my-project/ +bm cloud snapshot browse snap_abc123 --prefix my-project/ +bm cloud restore my-project/ --snapshot snap_abc123 ``` You may need to re-create the project entry in the workspace before the restored files appear as a live project — open the app, go to **Settings → Projects**, and verify. @@ -153,7 +153,7 @@ Snapshots cover the recent history of your cloud workspace. If the content you w - **Local sync mirror.** If you had [hybrid editing](/cloud/edit-locally-and-in-the-app) set up, your local folder is an independent copy. Check there. - **A project ZIP download.** If you'd previously downloaded the project as a ZIP (Manage Projects → Download), unpack it locally and re-upload to the project. -For ongoing safety: take a manual snapshot before any change you might want to roll back. They're free and instant. +For ongoing safety, take a manual snapshot before any change you might want to roll back. ```bash bm cloud snapshot create "Before reorganizing research/" diff --git a/content/3.cloud/12.file-history.md b/content/3.cloud/12.file-history.md index 70bc1ab..a173d70 100644 --- a/content/3.cloud/12.file-history.md +++ b/content/3.cloud/12.file-history.md @@ -1,12 +1,12 @@ --- title: File History -description: Per-note version history in the cloud — open File history on any note to see every saved version and restore or merge in old content. +description: Review stored versions of a Cloud note and apply earlier content when you need it. --- -Every saved version of a note is preserved automatically in Basic Memory Cloud. Open **File history** on any note to see its full timeline, compare an earlier version side-by-side with the current one, and apply changes back into the live note. It's the fast, per-note answer to "I want to undo something" — distinct from [Snapshots](/cloud/cloud-snapshots), which are project-wide point-in-time backups. +Basic Memory Cloud records versions of saved notes automatically. Open **File history** to compare a stored version with the current note and apply earlier content. Use [Snapshots](/cloud/cloud-snapshots) for deleted files, folders, or larger recovery jobs. ::note{icon="i-lucide-history"} -File history is a cloud feature. Versions are created automatically on every save — no setup, nothing to turn on. +File history is a Cloud feature and requires no setup. :: --- @@ -42,7 +42,7 @@ You have two ways to bring old content forward: When the draft looks right, click **Apply**. That saves the merged content as a **new** version — it doesn't overwrite or rewind history. Your existing versions stay intact, with the freshly applied content sitting on top as the new Current. ::note -**Apply creates a new version, not a rollback.** If you change your mind, just open File history again and merge back from any earlier version. Nothing's ever lost. +**Apply creates a new version, not an in-place rollback.** Check the result after applying, especially when other people are editing the note. :: ### When Apply is disabled @@ -69,26 +69,18 @@ In a [team workspace](/teams/about), this follows the project's normal access ru | | File history | [Snapshots](/cloud/cloud-snapshots) | |---|---|---| | **Scope** | One note at a time | The whole project / workspace | -| **Created** | Automatically on every save | Automatically daily + manually on demand | +| **Created** | Automatically as notes are saved | Automatically daily + manually on demand | | **Use it for** | "I want to undo the last few changes to this note" | "I want to roll back a bulk reorganization" or "I deleted a folder by accident" | | **Restore creates** | A new version of the note | Files written back into the live project | | **Best for** | Granular per-note recovery | Project-scale recovery | -Both work alongside each other — start with File history for a single note, fall back to a Snapshot when you need a bigger rollback. See [Restore Lost Content](/cloud/restore-lost-content) for a recovery decision guide. - ---- - -## Under the hood - -File history is built on **object versioning** in our underlying storage (Tigris). Each save writes a new object version, so every meaningful state of every note is preserved — without any extra storage choreography on your part. - -For more on the architecture, see the Tigris case study: [Own Your AI Context with Basic Memory](https://www.tigrisdata.com/blog/case-study-basic-memory/). +Both work alongside each other — start with File history for a single note, fall back to a Snapshot when you need a bigger rollback. See [Recover Notes](/cloud/restore-lost-content) for a recovery decision guide. --- ## Related -- [Restore Lost Content](/cloud/restore-lost-content) — when to use File history vs. Snapshots +- [Recover Notes](/cloud/restore-lost-content) — when to use File history vs. Snapshots - [Cloud Snapshots](/cloud/cloud-snapshots) — project-wide point-in-time backups - [Web App](/cloud/web-app) — the editor and surrounding UI - [Teams](/teams/about) — permissions in a shared workspace diff --git a/content/4.teams/1.about.md b/content/4.teams/1.about.md index 71631d6..8e40e10 100644 --- a/content/4.teams/1.about.md +++ b/content/4.teams/1.about.md @@ -1,12 +1,12 @@ --- -title: Basic Memory Teams -description: Share a cloud workspace with your team — invite members, assign roles, and collaborate on the same projects. +title: Share Basic Memory With Your Team +description: Invite people to your cloud workspace, assign roles, and collaborate on the same knowledge base. --- -Basic Memory Teams gives your team a single, shared cloud workspace. Knowledge isn't confined to one person — anything a teammate writes is immediately available to everyone else and to their AI assistants. Edit a note together in real time, hand work off between humans and agents, and build one connected knowledge base instead of scattered copies. +Collaboration is built into Basic Memory Cloud. Invite other people into a shared workspace, work from the same projects, and give each member's connected AI tools access to the same knowledge base. The result is one shared body of notes, documents, decisions, and project context instead of scattered copies. ::note{icon="i-lucide-users"} -**Teams requires a subscription with one or more seats.** Billing is per seat. Joining or starting a team doesn't change anything about your existing setup — your personal cloud subscription (if you have one) and any local projects keep working exactly as before. Teams adds an organization workspace alongside them. +**Teams is a feature, not a separate product or plan.** Every Basic Memory Cloud subscription is seat-based and includes collaboration. Your first seat is for you; add seats when you want to invite more people. Local projects continue to work alongside your cloud workspaces. :: --- @@ -18,7 +18,7 @@ Your account can have more than one workspace. Each keeps its own projects, note | Workspace | Who can access it | Notes | |-----------|-------------------|-------| | **Local** | Just you, on your machine | No team features; runs entirely on your computer | -| **Personal Cloud** | Just you | Your personal cloud subscription and notes | +| **Personal Cloud** | Just you | Your private cloud projects and notes | | **Organization** | Your team | Shared projects, members, roles, and seats | Switch between workspaces using the workspace selector in the app. Projects and notes are scoped to the workspace you're in. @@ -32,7 +32,7 @@ Every member of an organization workspace has a role that determines what they c | Role | Can do | |------|--------| | **Owner** | Everything an editor can, plus manage members and invitations, manage billing, and transfer ownership | -| **Editor** | Read and write notes, and manage invitations | +| **Editor** | Read and write notes in projects they can access | | **Viewer** | Read-only access to shared projects | Members also have a **status**: @@ -46,35 +46,33 @@ Members also have a **status**: --- -## Working together in real time +## Working together When two people open the same note, they see each other's edits as they happen. The editor is built on CRDTs (Yjs), so every keystroke syncs instantly across collaborators with no merge conflicts to resolve. A presence avatar appears in the note header for each active collaborator — each one gets a distinct color so you can tell at a glance who's typing where. -### AI agents as collaborators +### AI tools and shared knowledge -::note{icon="i-lucide-sparkles"} -**Coming soon.** AI agents will join as first-class collaborators alongside your team. -:: +Each member can connect a supported AI tool through Basic Memory's hosted MCP server. After the member accepts the invitation, the tool can discover the Cloud projects that member is allowed to access. The same permissions that apply in the app also determine which shared knowledge the member and their tools can read or change. -Once available, you'll connect an agent to a note and it shows up in the same presence list as your teammates with a live status indicator — _working_, _just updated_, or _waiting for input_. Agents read the shared knowledge graph for context and write structured observations and relations back into it, so the more your team uses Basic Memory, the better your AI gets at answering from your team's actual knowledge. +Basic Memory does not require a separate agent seat. Seats represent people who belong to the workspace. ### Activity feed -The **Activity** view in the app keeps you aware of what's happening across the workspace. It shows operations in progress (imports, indexing, large edits) and recent completed changes — from every team member and agent — with direct links to the affected notes. +The **Activity** view in the app keeps you aware of what's happening across the workspace. It shows operations in progress, such as imports and indexing, plus recent completed changes with links to affected notes. --- ## File history — undo on the file level -Every save creates a new version of a note, automatically. If a teammate overwrites something or an agent edits go sideways, open **File history** on the note to step back through the timeline, compare any version against the current one, and merge content back in. Restored content saves as a _new_ version, so nothing is ever lost. +Cloud records versions of saved notes automatically. If a teammate or connected tool changes something you need, open **File history** to compare an earlier stored version with the current note and apply the content you want. Applying historical content creates another saved version instead of rewriting the existing history. -See [File History](/cloud/file-history) for the full reference, or [Restore Lost Content](/cloud/restore-lost-content) for the broader recovery decision guide (File history for a single note, Snapshots for bigger rollbacks). +See [File History](/cloud/file-history) for the full reference, or [Recover Notes](/cloud/restore-lost-content) for the broader recovery decision guide (File history for a single note, Snapshots for bigger rollbacks). --- ## Inviting members -Owners invite people by email from **Settings → Teams**. +Workspace owners invite people by email from **Settings → Teams**. ::theme-image{light="/screenshots/cloud-app/v2-team-invite-light.png" dark="/screenshots/cloud-app/v2-team-invite-dark.png" alt="Invite a member"} :: @@ -113,7 +111,7 @@ On first sign-in, their authenticated account is linked to the pending membershi :: ::note{icon="i-lucide-credit-card"} -**Seats are assigned when an invitation is claimed, not when it's sent.** Inviting someone doesn't consume a seat until they accept — so a pending invitation won't be billed until the person joins. +**Pending invitations do not occupy a seat.** The workspace needs an available seat when the invitation is accepted. :: ::tip @@ -133,15 +131,16 @@ From **Settings → Teams**, an owner can: --- -## Seats and billing +## Seats -Teams billing is **per seat**. The number of seats on your subscription sets how many active members the workspace can have. +Basic Memory Cloud is billed **per seat**. The number of seats on your subscription sets how many active people can belong to the workspace. - Each active member occupies one seat. - Deactivating a member frees their seat for someone else. - Reactivating a member requires an available seat. - Pending invitations don't consume a seat until they're accepted. -- If your team grows past your current seat allocation, there's a **14-day grace period** before any restrictions kick in — so a new hire never gets locked out while you're adding seats. +- Add a seat before a pending invitation can be accepted when all current seats are assigned. +- If a seat reduction leaves the workspace over its allocation, a 14-day grace period gives the owner time to resolve the overage. Manage seats and payment from **Settings → Billing**. @@ -157,7 +156,7 @@ Track current seat usage from the same screen: ## Projects -Team projects come in three visibilities. The right one depends on who needs to see the work: +Projects in a shared workspace come in three visibilities. The right one depends on who needs to see the work: | Visibility | Who can see it | When to use | |------------|----------------|-------------| @@ -184,7 +183,7 @@ See the [CLI Reference](/reference/cli-reference) for full `bm project add` opti ## Bringing existing notes into a team workspace -When you join (or start) a team, you'll often want to promote work from your personal workspace into the shared one. Cross-workspace transfers are a **copy** workflow — export from the source, import into the target, verify, then optionally delete the original. +When you join or create a shared workspace, you may want to promote work from your personal workspace into it. Cross-workspace transfers are a **copy** workflow — export from the source, import into the target, verify, then optionally delete the original. See [Copy Content Between Workspaces](/teams/copy-between-workspaces) for the project ZIP, single-note, MCP, and local-sync workflows, along with caveats around wikilinks, permissions, and share links. @@ -195,7 +194,7 @@ See [Copy Content Between Workspaces](/teams/copy-between-workspaces) for the pr Once you're part of a team workspace, team projects show up everywhere you work: - **In the app** — switch to the organization workspace and your shared projects appear in the sidebar. -- **In your AI assistant (MCP)** — your assistant's project list spans every cloud workspace you can access, so it reaches team projects without extra setup. See [v0.21.0](/whats-new/v0.21.0) for details on cross-workspace discovery. +- **In your AI assistant (MCP)** — your assistant's project list spans every Cloud workspace you can access, so it reaches team projects without a separate endpoint. - **In the CLI** — `bm project list` shows projects across all your workspaces. ### Workspace commands @@ -214,7 +213,9 @@ You can also target a specific workspace when creating a project, either from th ## Security and isolation -Each organization gets its **own** isolated database and file storage in the cloud — there is no shared tenancy at the data layer. Your team's knowledge is physically separated from every other team's. Authentication runs through [WorkOS AuthKit](https://workos.com/authkit) for enterprise-grade identity management. +Workspace access is enforced by authenticated membership, role, and project permissions. Do not use public share links for private team material; use workspace membership and project access instead. + +If an invitation, seat, billing, or private workspace access issue blocks your team, see [Contact Support](/reference/contact-support). --- @@ -248,12 +249,4 @@ to: /reference/cli-reference Full `bm project` and `bm cloud workspace` commands. :: -::card ---- -title: What's New in v0.21.0 -icon: i-lucide-megaphone -to: /whats-new/v0.21.0 ---- -Cross-workspace discovery across MCP and CLI. -:: ::: diff --git a/content/4.teams/2.join-a-team.md b/content/4.teams/2.join-a-team.md index a73f28e..43d43db 100644 --- a/content/4.teams/2.join-a-team.md +++ b/content/4.teams/2.join-a-team.md @@ -1,9 +1,9 @@ --- -title: Joining a Team Workspace -description: First-time setup for new team members — accept the invite, sign in, switch workspaces, and connect your AI assistant to the shared knowledge base. +title: Join a Shared Workspace +description: Accept an invitation, sign in, switch workspaces, and connect your AI assistant to the shared knowledge base. --- -You got an invite to a Basic Memory [team workspace](/teams/about). This page walks through what to do on day one — accept the invite, get into the workspace, find the shared projects, and point your AI assistant at the same knowledge base. +You received an invitation to a shared Basic Memory Cloud workspace. This page walks through what to do on day one — accept the invite, enter the workspace, find its projects, and point your AI assistant at the same knowledge base. ::note **You'll need a Basic Memory account on the email address the invite was sent to.** If you don't have one yet, the accept flow walks you through creating it. @@ -41,7 +41,7 @@ Your **role** determines what you can do: | Role | You can | |------|---------| | **Viewer** | Read shared projects | -| **Editor** | Read and write shared projects; create new notes; manage invitations | +| **Editor** | Read and write projects they can access; create and edit notes | | **Owner** | Everything an editor can, plus manage members, billing, and project visibility | Not sure of your role? Open **Settings → Teams** to see it next to your name. If you need a different role, ask an owner. @@ -54,12 +54,10 @@ Your assistant works with the team workspace through the same MCP endpoint as yo - **Claude Desktop / Claude Code** — see [Claude Desktop](/integrations/claude-desktop) or [Claude Code](/integrations/claude-code). Use the OAuth flow; your assistant will see team projects automatically once you've accepted the invite. - **ChatGPT** — see [ChatGPT](/integrations/chatgpt). -- **Codex / Cursor / VS Code / Obsidian** — see the [integrations index](/integrations/claude-desktop). +- **Codex / Cursor / VS Code / Obsidian** — see [Connect AI tools](/integrations). - **CLI** — `bm cloud login` once, then `bm project list` shows projects across every workspace you can access (personal and team). -::tip -With v0.21, your assistant's project list spans **every** workspace you can reach, so team projects show up without extra configuration. See [v0.21.0](/whats-new/v0.21.0) for the cross-workspace discovery story. -:: +Once the invitation is accepted, connected tools discover the Cloud projects your account can access. You do not need a second MCP endpoint for the team workspace. ### Targeting the team workspace explicitly @@ -99,4 +97,4 @@ Already have personal notes you want to share with the team? Cross-workspace tra - [Teams](/teams/about) — workspaces, roles, invitations, billing - [Web App](/cloud/web-app) — the three-pane editor and shortcuts - [Copy Content Between Workspaces](/teams/copy-between-workspaces) — bring personal notes into the team workspace -- [Integrations](/integrations/claude-desktop) — connect your AI assistant +- [Connect AI tools](/integrations) — connect your AI assistant diff --git a/content/5.local/1.local-install.md b/content/5.local/1.local-install.md index a5d1717..3c9743c 100644 --- a/content/5.local/1.local-install.md +++ b/content/5.local/1.local-install.md @@ -1,12 +1,22 @@ --- -title: Local install -description: Install Basic Memory locally and choose where notes live. +title: Install locally +description: Install the open-source Basic Memory CLI and choose where notes live. --- -Local mode runs the MCP server on your machine and stores notes in local folders you control. +Local mode runs Basic Memory on your machine. Notes are plain Markdown files in folders you control; the local database indexes those files for search, relations, and MCP tools. + +## Before you start + +You need: + +- A Mac, Linux, or Windows machine with a terminal. +- [`uv`](https://docs.astral.sh/uv/) for the recommended install path. +- An MCP-capable AI tool, such as Claude Desktop, Claude Code, Codex, Cursor, VS Code, ChatGPT, or Obsidian. ## Install the CLI +Use `uv` unless you already manage Basic Memory with Homebrew. + ::code-group ```bash [uv] uv tool install basic-memory @@ -18,7 +28,29 @@ brew install basic-memory ``` :: -## Start the MCP server +Verify the install: + +```bash +bm --version +bm status +``` + +`basic-memory` and `bm` are the same command. The docs use `bm` because it is shorter. + +## Choose where notes live + +By default, Basic Memory creates a `main` project at `~/basic-memory`. + +Create another local project when you want Basic Memory to index a different folder: + +```bash +bm project add research ~/Documents/research +bm project default research +``` + +Basic Memory reads and writes Markdown in that folder. It does not move the folder into an app-specific database. + +## Connect an MCP client Configure your MCP client to run the server: @@ -35,15 +67,46 @@ Configure your MCP client to run the server: Restart your MCP client after editing the config. -## Choose where notes live +Use `uvx` in client configs when you want the client to launch Basic Memory directly. If you prefer using the installed CLI, this also works in clients that can find shell commands: -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. +```json +{ + "mcpServers": { + "basic-memory": { + "command": "bm", + "args": ["mcp"] + } + } +} +``` + +The `uvx` form is usually more portable across GUI apps because it does not depend on the app inheriting your shell `PATH`. + +## Update Basic Memory + +Basic Memory checks for updates automatically for supported `uv tool`, `uvx`, and Homebrew installs. You can also check manually: ```bash -bm project add "work" ~/Documents/work-notes -bm project default "work" +bm update +bm update --check ``` +## Remove Basic Memory + +Uninstall the package with the same tool you used to install it: + +::code-group +```bash [uv] +uv tool uninstall basic-memory +``` + +```bash [Homebrew] +brew uninstall basic-memory +``` +:: + +Your Markdown project folders are not deleted by uninstalling the CLI. + ## Next steps :::card-group @@ -58,7 +121,16 @@ Learn common commands for projects, notes, and search. ::card --- -title: Projects and Folders +title: Local MCP tools +icon: i-lucide-wrench +to: /local/mcp-tools-local +--- +Use Basic Memory from MCP clients. +:: + +::card +--- +title: Projects and folders icon: i-lucide-folder to: /concepts/projects-and-folders --- diff --git a/content/5.local/2.cli-basics.md b/content/5.local/2.cli-basics.md index 357bbb3..f86c579 100644 --- a/content/5.local/2.cli-basics.md +++ b/content/5.local/2.cli-basics.md @@ -1,49 +1,76 @@ --- title: CLI basics -description: Common commands for projects, notes, and search. +description: Common commands for local projects, notes, search, and schemas. --- -The CLI is the fastest way to manage projects and run MCP tools directly from the terminal. +The CLI is the fastest way to manage local projects and run the same tools your AI client uses. ## Use the short alias `bm` is a short alias for `basic-memory`. -## List and create projects +```bash +bm --help +basic-memory --help +``` + +## Check local status + +Use `status` when you want to confirm that files and the local index agree: ```bash -bm project list -bm project add "research" ~/Documents/research +bm status +bm status --verbose +bm status --project research ``` -## Set the default project +Use `doctor` when something feels off: ```bash -bm project default "research" +bm doctor ``` -## Search notes +## Manage projects ```bash -bm tool search-notes --query "authentication" +bm project list +bm project add research ~/Documents/research +bm project default research +bm project info research ``` -Semantic modes: +The default project is used when a command or MCP tool does not name a project explicitly. + +## Search notes ```bash +bm tool search-notes --query "authentication" bm tool search-notes --query "authentication architecture" --search-type hybrid bm tool search-notes --query "login flow" --search-type vector ``` +`hybrid` combines keyword and semantic search. `vector` searches by meaning only. + ## Read and write notes ```bash bm tool read-note "docs/api-auth.md" +bm tool read-note "API Auth" --include-frontmatter +``` -echo "New note content" | bm tool write-note --title "Notes" --folder "drafts" +```bash +bm tool write-note --title "Meeting notes" --folder "meetings" --content "We decided to..." +echo "New note content" | bm tool write-note --title "Draft" --folder "drafts" ``` -## Schema workflows +Use `edit-note` for smaller changes: + +```bash +bm tool edit-note "Draft" --operation append --content "More context." +bm tool edit-note "Draft" --operation find_replace --find-text "old" --content "new" +``` + +## Work with schemas ```bash bm schema infer person @@ -51,6 +78,12 @@ bm schema validate person bm schema diff person ``` +Use `--json` for machine-readable schema reports: + +```bash +bm schema validate person --json +``` + ## Format files ```bash @@ -59,6 +92,19 @@ bm format --project research bm format notes/meeting.md ``` +Formatting uses the formatter configured in Basic Memory settings. + +## Run the MCP server yourself + +Most AI clients launch the MCP server for you. You can also start it manually: + +```bash +bm mcp +bm mcp --project research +``` + +The default transport is `stdio`, which is what local desktop and coding clients usually expect. + ## Next steps :::card-group diff --git a/content/5.local/3.mcp-tools-local.md b/content/5.local/3.mcp-tools-local.md index 6cc3a15..ae0b2ea 100644 --- a/content/5.local/3.mcp-tools-local.md +++ b/content/5.local/3.mcp-tools-local.md @@ -1,13 +1,33 @@ --- -title: MCP tools (local) -description: Use MCP tools against local projects. +title: Local MCP tools +description: Use MCP tools against local Markdown projects. --- -MCP tools are the same in Cloud and Local. In local mode, they operate on folders on your machine. +Basic Memory exposes the same core MCP tools in Cloud and Open Source. In local mode, those tools read and write Markdown files in local project folders. -## Use tools in local mode +## How local MCP works -When you run the local MCP server, tools read and write local project folders by default. +Your AI client launches: + +```bash +uvx basic-memory mcp +``` + +or: + +```bash +bm mcp +``` + +The MCP server starts, syncs your project files into the local index, responds to tool calls, and writes changes back to Markdown. + +Use the `--project` flag when you want a client connection to stay locked to one project: + +```bash +bm mcp --project research +``` + +Otherwise, tools use Basic Memory's normal project resolution: explicit tool parameter first, then the configured default project. ## Common tools @@ -18,17 +38,32 @@ When you run the local MCP server, tools read and write local project folders by - `schema_validate`, `schema_infer`, `schema_diff` for schema workflows - `build_context` for memory URL graph traversal -`search_notes` and `read_note` also support terminal-friendly formats: -- `output_format=\"default\"` (structured) -- `output_format=\"ascii\"` (plain table/preview) -- `output_format=\"ansi\"` (colorized table/preview) +See the [MCP tools reference](/reference/mcp-tools-reference?deployment=local) for full parameters. -## Example +## Example tool call ```python search_notes(query="architecture", project="main") ``` +The assistant receives matching notes and can then call `read_note`, `build_context`, or `edit_note` as needed. + +## Local versus Cloud MCP + +Use local MCP when: + +- The project should stay on your machine. +- You want an AI tool to work directly with a local folder. +- You are using Basic Memory without a Cloud subscription. + +Use Cloud MCP when: + +- You want the same knowledge available across devices. +- You want shared workspaces and project access. +- You want hosted auth instead of local stdio configuration. + +You can use both. For example, a sensitive local project can stay local while a team workspace routes through Cloud. + ## Next steps :::card-group diff --git a/content/5.local/4.user-guide.md b/content/5.local/4.user-guide.md deleted file mode 100644 index 5ed9463..0000000 --- a/content/5.local/4.user-guide.md +++ /dev/null @@ -1,642 +0,0 @@ ---- -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" -} -``` - -This sets your fallback project when no explicit project is passed. You can still override by specifying a different project. - -### Single Project Mode (Locked) - -For focused sessions or automation, lock the MCP server to one project: - -```bash -basic-memory mcp --project work-notes -``` - -This **locks** the entire MCP session - the `project` parameter in tool calls will be ignored. - -**When to use:** -- Automation workflows that should only access one project -- Focused sessions where you want to prevent cross-project operations -- Team environments with project-specific access - -::note -**Key difference:** -- **Default project fallback**: Uses `default_project` when no project is specified, but can still switch -- **Single Project Mode**: Locked to one project, cannot switch -:: - -### Moving Notes Between Projects - -::warning -Moving notes from one project to another is not currently supported directly. The easiest approach is to: -1. Copy the file manually between project directories -2. Or create a new note in the destination project, then delete the original -:: - ---- - -## File Organization - -### Directory Structure - -Organize files in any structure that suits you: - -```bash -~/basic-memory/ -├── projects/ # Active project notes -│ ├── api-redesign/ -│ └── mobile-app/ -├── decisions/ # Decision records -├── learning/ # Research and learning notes -├── meetings/ # Meeting notes -└── archive/ # Completed/old content -``` - -### Best Practices - -- Use descriptive filenames -- Group related content in folders -- Include dates in time-sensitive notes (e.g., `2024-01-15 Team Standup.md`) -- Archive old content regularly - -### Controlling What Gets Indexed - -Basic Memory respects `.gitignore` patterns to skip sensitive files. - -**Pattern sources:** -- **Global patterns**: `~/.basic-memory/.bmignore` (all projects) -- **Project patterns**: `{project}/.gitignore` (specific project) - -**Example `.gitignore`:** -```gitignore -# Sensitive files -.env -*.key -credentials.json - -# Build artifacts -node_modules/ -__pycache__/ -dist/ - -# OS files -.DS_Store -Thumbs.db -``` - -Files matching these patterns are automatically skipped during indexing. - ---- - -## Enhanced Editing - -### Incremental Editing - -Edit notes without rewriting entire documents: - -```bash -You: "Add a troubleshooting section to my setup guide" -Claude: [Uses edit_note with append operation] -"I've added a troubleshooting section to the end of your setup guide." -``` - -**Available operations:** -- `append` - Add content to end -- `prepend` - Add content to beginning -- `find_replace` - Replace specific text -- `replace_section` - Replace entire section by heading - -### Smart File Organization - -Move and rename notes with database consistency: - -```bash -You: "Move my old meeting notes to the archive folder" -Claude: [Uses move_note] -"Done! I've moved 12 meeting notes to the archive folder." -``` - -### Directory Operations - -Move or delete entire folders: - -```bash -You: "Move the old-projects folder to archive" -Claude: [Uses move_note with is_directory=true] -"Moved old-projects/ → archive/old-projects/ (15 files)" - -You: "Delete the empty temp folder" -Claude: [Uses delete_note with is_directory=true] -"Deleted temp/ and all 3 contained files" -``` - -### Enhanced Search - -Tags and frontmatter fields are searchable. Use `tag:` shorthand or metadata filters to narrow results: - -```bash -You: "Find all my notes tagged with security" -Claude: [Uses search_notes with query="tag:security"] - -You: "Show me in-progress specs" -Claude: [Uses search_notes with note_types=["spec"], metadata_filters={"status": "in-progress"}] - -You: "Find high priority items from this year" -Claude: [Uses search_notes with metadata_filters={"priority": {"$in": ["high", "critical"]}}, - after_date="2026-01-01"] -``` - -You can also search purely by metadata — no text query needed: - -```bash -You: "What notes have status draft?" -Claude: [Uses search_notes with status="draft"] -``` - ---- - -## Schema Workflows - -As your knowledge base grows, you may want consistent structure for certain note types. Schemas let you define what a "good" note of a particular type should contain, then validate notes against that definition. - -**Conversational example:** -```bash -You: "I've been writing a lot of person notes. Can you help me standardize them?" - -Claude: Let me analyze your existing person notes to find common patterns. - -[Uses schema_infer with note_type="person"] - -Based on your notes, here's what most of them include: -- name (in 95% of notes) -- role (in 80%) -- works_at relation (in 60%) - -I can create a schema note that formalizes this pattern. -Would you like me to save it? - -You: "Yes, and validate my existing notes against it" - -Claude: [Creates schema note, then validates] -3 of your 15 person notes are missing the [name] observation. -Here are the ones that need updating... -``` - -See the [Schema System](/concepts/schema-system) guide for full details on picoschema syntax, validation modes, and the infer-validate-diff lifecycle. - ---- - -## Semantic Search - -Semantic search lets you find notes by meaning rather than exact keywords. This is helpful when you remember the concept but not the exact words used in the note. - -**Conversational example:** -```bash -You: "Find my notes about making the app faster" - -Claude: [Uses search_notes with search_type="hybrid"] - -I found several relevant notes: -1. "React Performance Optimization" — contains observations about bundle size and lazy loading -2. "Database Query Tuning" — discusses index strategies and query plans -3. "Caching Architecture" — your design decisions for the Redis cache layer - -Would you like me to build context from any of these? -``` - -Semantic search is included by default. Embeddings are generated automatically on first startup. See the [Semantic Search](/concepts/semantic-search) guide for configuration details. - ---- - -## Syncing and Updates - -### Real-time Sync - -Basic Memory automatically syncs file changes in real-time. When you edit a file in your editor: -1. The change is detected within ~1 second -2. The file is re-parsed for observations and relations -3. The database is updated -4. Search index is refreshed - -No manual sync needed for normal workflows. - -### Checking Status - -```bash -# View sync status -basic-memory status - -# View project information -basic-memory project info -``` - -### Force Re-sync - -If something seems out of sync: - -```bash -# Re-sync all files -basic-memory sync - -# Reset and rebuild database (use if issues persist) -basic-memory reset -``` - -::warning -`basic-memory reset` rebuilds the entire database from your files. This is safe (files are never deleted) but may take time for large knowledge bases. -:: - ---- - -## Integration Tips - -### With Obsidian - -1. Open your `~/basic-memory` directory as an Obsidian vault -2. Use **Graph View** to visualize connections -3. Edit files directly in Obsidian -4. Changes sync automatically - ask the AI to read a note to see updates - -![Obsidian graph view](/attachments/obsidian-coffee.png) - -::tip -Obsidian's graph view is excellent for discovering unexpected connections in your knowledge base. -:: - -### With Git - -Basic Memory files are git-friendly: - -```bash -cd ~/basic-memory -git init -git add . -git commit -m "Initial knowledge base" -``` - -Benefits: -- Version history for all changes -- Backup to GitHub/GitLab -- Collaborate with others -- Track what changed over time - -### With Other Editors - -Basic Memory uses standard Markdown that works with: -- **VS Code** with Markdown extensions -- **Typora** for rich text editing -- **Any text editor** for quick edits -- **Web editors** for remote access - -The database syncs regardless of how you edit files. - ---- - -## Best Practices - -### Knowledge Creation - -1. **Create relations** - Link related concepts with `[[WikiLinks]]` -2. **Make observations** - Structure facts with `[category]` syntax -3. **Be descriptive** - Use clear titles and rich content -4. **Add context** - Include background and reasoning -5. **Review and refine** - Edit AI-generated content for accuracy - -### Workflow - -1. **Use special prompts** - "Continue conversation", "Recent activity", "Search" -2. **Build incrementally** - Add to existing notes rather than creating duplicates -3. **Organize regularly** - Move old content to archive -4. **Cross-reference** - Link new content to existing knowledge -5. **Use projects** - Separate work, personal, research - -### Long-term Maintenance - -1. **Archive old content** - Keep active knowledge base focused -2. **Refactor connections** - Update relations as knowledge evolves -3. **Regular reviews** - Periodically update key documents -4. **Backup regularly** - Use git, cloud sync, or snapshots - ---- - -## Troubleshooting - -### Changes Not Syncing - -1. Check sync status: `basic-memory status` -2. Verify file permissions -3. Check if file matches ignore patterns -4. Reset database: `basic-memory reset` - -### Claude Can't Find Knowledge - -1. Confirm files are in correct project directory -2. Check frontmatter formatting (valid YAML) -3. Use `memory://` URLs for direct references -4. Trigger re-sync: `basic-memory sync` - -### Performance Issues - -1. Check database size: `basic-memory project info` -2. Archive old content -3. Adjust sync delay in config (default: 1000ms) - -### Getting Help - -- **Discord**: [discord.gg/tyvKNccgqN](https://discord.gg/tyvKNccgqN) - #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/6.concepts/0.vs-built-in-memory.md b/content/6.concepts/0.vs-built-in-memory.md index cfa642e..b002bb5 100644 --- a/content/6.concepts/0.vs-built-in-memory.md +++ b/content/6.concepts/0.vs-built-in-memory.md @@ -5,7 +5,7 @@ description: How to use Basic Memory alongside the memory features in Claude, Ch Your AI tools already have built-in memory features. Basic Memory doesn't replace them — it works alongside them. This page explains what each system is good at and how to use them together effectively. -For a broader comparison of Basic Memory with all the alternatives — including Obsidian, database-only memory services, and more — see [Why Basic Memory](/start-here/why-basic-memory). +For the product overview, see [What is Basic Memory?](/start-here/what-is-basic-memory). --- @@ -118,9 +118,9 @@ How notes, observations, and relations work. ::card --- -title: Integrations +title: Connect AI tools icon: i-lucide-plug -to: /integrations/claude-desktop +to: /integrations --- Connect Basic Memory to your AI tool. :: diff --git a/content/6.concepts/1.knowledge-format.md b/content/6.concepts/1.knowledge-format.md index e3de28e..d856d97 100644 --- a/content/6.concepts/1.knowledge-format.md +++ b/content/6.concepts/1.knowledge-format.md @@ -8,7 +8,7 @@ Basic Memory is a knowledge base that you and your AI share. Everything is store This page explains how those files are structured and how that structure turns a folder of notes into a connected knowledge graph. ::tip -Using Basic Memory Cloud? The knowledge format is the same — create notes through AI conversations or edit them directly in the [Web Editor](/cloud/cloud-guide#web-editor). +Using Basic Memory Cloud? The knowledge format is the same — create notes through AI conversations or edit them directly in the [web app](/cloud/web-app). :: --- diff --git a/content/6.concepts/2.projects-and-folders.md b/content/6.concepts/2.projects-and-folders.md index ff751e7..5cc1497 100644 --- a/content/6.concepts/2.projects-and-folders.md +++ b/content/6.concepts/2.projects-and-folders.md @@ -78,7 +78,7 @@ This is a perfectly good layout. So is a flat folder with everything at the top ## Mixing local and cloud projects -Starting in v0.19, you can keep some projects local and route others to Basic Memory Cloud. Your personal notes stay on your machine. Your work projects sync to the cloud and are accessible from any device. Both are available in the same conversation. +You can keep some projects local and route others to Basic Memory Cloud. Personal notes can stay on your machine while work projects live in Cloud. Both can remain available to a connected AI tool. This is configured through per-project cloud routing. Each project independently decides whether it talks to a local database or a cloud instance. diff --git a/content/6.concepts/3.observations-and-relations.md b/content/6.concepts/3.observations-and-relations.md index 1e85152..6783466 100644 --- a/content/6.concepts/3.observations-and-relations.md +++ b/content/6.concepts/3.observations-and-relations.md @@ -1,159 +1,223 @@ --- -title: Observations and relations -description: How Basic Memory turns your notes into searchable facts and a connected knowledge graph — and why you rarely need to write the syntax yourself. +title: Observations and Relations +description: Use observations and relations to turn Markdown notes into a searchable, connected knowledge graph. --- -Basic Memory notes aren't just text. Each note can contain **observations** (individual facts) and **relations** (links to other notes). Together, they turn a folder of Markdown files into a searchable, navigable knowledge graph. +Observations and relations are the light semantic layer in Basic Memory. They let humans and AI tools write ordinary Markdown while still giving Basic Memory enough structure to search facts, follow connections, and build context across projects. -The important thing to know up front: **you don't need to write these by hand.** When you ask your AI assistant to write a note, it creates observations and relations automatically. You should understand what they are so you can read your notes and give feedback, but you never need to memorize the syntax. +You do not need to mark up every sentence. Use these patterns where structure helps. ## Observations -An observation is a single fact, captured as a list item with a category in brackets: +An observation is a single fact, decision, instruction, question, risk, preference, or other useful detail. ```markdown -- [decision] Use Postgres for primary storage #database -- [risk] Latency spikes under heavy load #performance -- [preference] Dark mode for all internal tools #ux +## Observations +- [decision] Use PostgreSQL for the customer portal #architecture +- [constraint] Export jobs must finish within 10 minutes +- [instruction] Always run the accessibility checklist before release +- [question] Should onboarding create a sample project by default? ``` -The category (the word in brackets) classifies the kind of fact. The rest of the line is the content. There is no fixed list of categories — use whatever makes sense for what you're capturing: +The pattern is: ```markdown -- [tool] Basic Memory uses SQLite for local indexing -- [recipe] Bloom the espresso for 30 seconds before extraction -- [symptom] App crashes on launch after upgrading to iOS 18 -- [quote] "Simplicity is the ultimate sophistication" — Leonardo da Vinci -- [milestone] v1.0 shipped on March 15 +- [category] content #optional-tags ``` -Categories help your AI assistant understand what kind of information it's looking at. When it builds context from your knowledge base, it can distinguish a decision from a risk, a preference from a requirement. That distinction matters when it's helping you reason through a problem. +Categories are flexible. Basic Memory does not require a fixed vocabulary. Pick labels that match the work: + +| Category | Good for | +|---|---| +| `[decision]` | Choices you made and want to preserve | +| `[fact]` | Stable information, research findings, source notes | +| `[instruction]` | Repeatable workflow steps or preferences | +| `[constraint]` | Limits, requirements, policies, deadlines | +| `[risk]` | Things to watch or mitigate | +| `[question]` | Open questions to return to | +| `[todo]` | Action items and next steps | +| `[idea]` | Possibilities that are not committed yet | + +Use any category that helps your team or agent understand the note. + +## Why observations help -### Tags within observations +Observations are indexed individually. That means search can return the exact decision, fact, or instruction instead of only returning the whole note that contains it. -The `#hashtags` at the end of an observation line add extra searchability: +For example, a large research note might contain: ```markdown -- [decision] Switch to async job processing #architecture #backend -- [feedback] Users want faster search results #ux #search +- [finding] Most customers use Basic Memory to preserve reusable project context, not only chat history ``` -Tags are indexed and searchable with the `tag:` prefix in search queries. They cut across categories — you might tag observations from many different notes with `#database` and then find all of them in one search. - -Tags are optional. Many observations work fine without them. Add them when you want a cross-cutting way to find information later. +Later, a search for "why do customers use Basic Memory" can surface that observation directly. ## Relations -A relation is a link from one note to another, with a label that describes how they're connected: +A relation links one note to another. ```markdown ## Relations -- depends_on [[Caching Layer]] -- relates_to [[Latency Budget]] -- owned_by [[Platform Team]] +- implements [[Cloud Sync]] +- depends_on [[API Keys]] +- inspired_by [[Cody Call Notes]] +- part_of [[Docs Overhaul]] ``` -The label before the `[[link]]` is the relation type. Like categories, there is no fixed list — use whatever describes the connection: +The pattern is: ```markdown -- implements [[RFC-042 Async Processing]] -- contrasts_with [[Monolith Architecture]] -- learned_from [[Q3 Retrospective]] -- inspired_by [[Obsidian Plugin System]] -- blocked_by [[Auth Migration]] +- relation_type [[Linked Note]] ``` -Relations are directional. `System Design - depends_on -> Caching Layer` creates a link in the knowledge graph from one note to the other. Your AI assistant can follow these links to build context — starting from one note and pulling in the connected notes to understand the bigger picture. +The text before the wikilink becomes the relation type. Use a single token like `depends_on`, `part_of`, or `implements` when you can. If you need spaces, quote the relation type: -::note -**Quote multi-word relation types.** A relation type is a single token (`depends_on`, `relates_to`). If you want a multi-word type, **quote it** — `"depends on" [[Caching Layer]]`. Unquoted prose before a wikilink is no longer treated as a relation type: a bare or prose list item like `- [[Caching Layer]]` or `- see also [[Caching Layer]]` is indexed as a generic `links_to` connection. (Changed in [v0.21.0](/whats-new/v0.21.0).) -:: +```markdown +- "depends on" [[Billing Settings]] +``` -### Inline references +A bare wikilink still creates a connection, but it is treated as a generic link: -You can also link to other notes anywhere in a note's body text using `[[wiki links]]`: +```markdown +- [[Billing Settings]] +``` + +## Inline links + +You can also link notes from ordinary paragraphs: ```markdown -We decided to follow the approach from [[API Design Principles]] -because it aligns with our [[Team Standards]]. +The invite flow is described in [[Join a Shared Workspace]], and the owner-side controls are in [[Share Basic Memory With Your Team]]. ``` -These inline references also create connections in the knowledge graph. The difference is that relations in a dedicated `## Relations` section have explicit types (depends_on, relates_to), while inline references create a general "references" connection. Both are useful. +Inline links are useful when the relation is obvious from the surrounding text. Use a `## Relations` section when the type of connection matters. -## Why this matters +## Relation types to try -Observations and relations aren't just formatting — they're what makes Basic Memory's search and navigation powerful. +Relation types are not limited to a built-in list. A few durable patterns: -### Precise search +| Type | Use for | +|---|---| +| `part_of` | A section, task, or note belongs to a larger project | +| `depends_on` | One thing needs another to exist first | +| `implements` | A decision or artifact implements a requirement | +| `informed_by` | A conclusion came from research, notes, or a call | +| `replaces` | One note supersedes another | +| `blocked_by` | Progress is waiting on something | +| `relates_to` | General connection when no specific type matters | -Every observation is indexed individually. When you search your knowledge base, Basic Memory doesn't just match against whole documents — it can surface a specific fact from deep inside a long note. +Use fewer relation types at first. It is easier to grow a vocabulary than to clean up a sprawling one. -If you have a 2000-word architecture document with dozens of observations, a search for "database migration strategy" can find the one relevant observation without forcing you to read the entire note. Semantic search matches the meaning of your query against each observation, so even different wording will find the right fact. +## Examples -### Knowledge graph navigation +### Workflow notes -Relations create a graph you can traverse. The `build_context` tool follows links between notes to assemble relevant information from across your knowledge base. When you ask your AI assistant about a topic, it doesn't just find one note — it follows relations to pull in connected context. +```markdown +## Observations +- [instruction] Before publishing docs, run npm run check:docs +- [instruction] Capture screenshots in light and dark mode when UI state matters +- [risk] Version numbers drift quickly unless they are checked against source -For example, if you ask about a system design decision, the assistant might start with the design note, follow a `depends_on` link to the caching strategy, then follow a `relates_to` link to the performance requirements. That chain of connections gives it a much richer understanding than any single note would. +## Relations +- part_of [[Docs Maintenance]] +- depends_on [[Screenshot Manifest]] +``` -### AI context building +### Research collections -Categories, tags, and relation types give your AI assistant structured metadata to work with. It can filter observations by category, search by tag, and navigate by relation type. This structure means the assistant can be selective about what context it pulls in, rather than dumping entire documents into the conversation. +```markdown +## Observations +- [finding] Users describe Basic Memory as a shared knowledge base more often than an extended memory layer +- [source] Interview notes came from the Cody call +- [question] Which examples best show non-chat use cases? -## Enforcing structure with schemas +## Relations +- informed_by [[Cody Call]] +- informs [[Messaging Guidelines]] +``` -If you want to ensure consistency across similar notes, Basic Memory's schema system (introduced in v0.19) can validate that notes of a certain type contain the observations and relations you expect. +### Software projects -For example, you could define a schema that requires every "person" note to have a `name` observation and a `works_at` relation. The schema validates notes when they're written and flags anything that's missing. +```markdown +## Observations +- [decision] Keep Cloud and Open Source setup paths separate in docs navigation +- [constraint] Cloud onboarding should not include unexplained local setup +- [todo] Add redirects for deleted legacy pages -::note -See [Schema System](/concepts/schema-system) for details on defining and applying schemas. -:: +## Relations +- implements [[Docs Homepage Navigation Plan]] +- relates_to [[Cloud or Open Source]] +``` -## Teaching your AI with skills +### Creative projects -The `memory-notes` skill teaches your AI assistant best practices for writing observations and relations — what categories to use, how to structure relations, and when to add tags. Skills are a way to encode your preferences so the AI writes notes the way you want without being reminded every time. +```markdown +## Observations +- [character] Mara hides uncertainty by over-explaining technical details +- [theme] The archive is useful because it is incomplete +- [question] What does the city remember that the characters do not? -::note -See [Agent Skills](/whats-new/agent-skills) for details on how skills work. -:: +## Relations +- part_of [[Novel Draft]] +- contrasts_with [[Elias]] +``` + +## Best practices + +- Make one observation per bullet. +- Keep the category short and predictable. +- Put durable information in observations; leave ordinary narrative as normal Markdown. +- Use relations for meaningful connections, not every possible link. +- Prefer `[[WikiLinks]]` to raw URLs for notes inside Basic Memory. +- Let AI tools help, but review important facts and decisions like any other documentation. + +## What not to overdo + +Do not turn notes into database rows unless you need that structure. Basic Memory works best when Markdown stays readable. + +Good: + +```markdown +- [decision] Use Cloud as the default docs path because it is fastest for new users +``` + +Too much: + +```markdown +- [decision_id] DEC-2026-06-09-001 +- [decision_subject] default_docs_path +- [decision_value] cloud +``` + +If you need stricter structure, use [schemas](/concepts/schema-system). If you just need a readable note with a few important facts, observations and relations are enough. ## Next steps :::card-group ::card --- -title: Semantic Search -icon: i-lucide-search -to: /concepts/semantic-search +title: Knowledge Format +icon: i-lucide-file-text +to: /concepts/knowledge-format --- -Learn how observations power precise semantic search across your knowledge base. +See how frontmatter, observations, relations, and permalinks fit together. :: ::card --- -title: Schema System +title: Schemas icon: i-lucide-shield-check to: /concepts/schema-system --- -Validate and enforce structure on your notes with schemas. +Define and validate structure for repeated note types. :: ::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 +title: Semantic Search +icon: i-lucide-search +to: /concepts/semantic-search --- -Learn the base note format that observations and relations build on. +Learn how structured facts improve search and retrieval. :: ::: diff --git a/content/6.concepts/5.canvas.md b/content/6.concepts/5.canvas.md deleted file mode 100644 index 590d51d..0000000 --- a/content/6.concepts/5.canvas.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Canvas Visualizations -description: Create visual knowledge maps using Obsidian's Canvas feature to understand relationships between concepts ---- -# Canvas Visualizations - -Basic Memory can create visual knowledge maps using Obsidian's Canvas feature. These visualizations help you understand relationships between concepts, map out processes, and visualize your knowledge structure. - -## Creating Canvas Visualizations - -Ask Claude to create a visualization by describing what you want to map: - -- **Example Requests** — - "Create a canvas visualization of my project components and their relationships." - "Make a concept map showing the main themes from our discussion about climate change." - "Can you make a canvas diagram of the perfect pour over method?" - -Canvas Visualization Example - -## Types of Visualizations - -Basic Memory can create several types of visual maps: - -- **Document Maps** — Visualize connections between your notes and documents -- **Concept Maps** — Create visual representations of ideas and their relationships -- **Process Diagrams** — Map workflows, sequences, and procedures -- **Thematic Analysis** — Organize ideas around central themes - -### Relationship Networks - -Show how different entities relate to each other in your knowledge base. - -## Visualization Sources - -Claude can create visualizations based on: - -### Documents in Your Knowledge Base - -```example -You: "Create a canvas showing the connections between my project planning documents" -``` - -### Conversation Content - -```example -You: "Make a canvas visualization of the main points we just discussed" -``` - -### Search Results - -```example -You: "Find all my notes about psychology and create a visual map of the concepts" -``` - -### Themes and Relationships - -```example -You: "Create a visual map showing how different philosophical schools relate to each other" -``` - -## Visualization Workflow - -::steps -### Request a visualization -Describe what you want to see by asking Claude to create a canvas - -### Claude creates the canvas file -The canvas file is automatically created in your Basic Memory directory - -### Open the file in Obsidian -View the visualization in Obsidian's Canvas feature - -### Refine the visualization -Ask Claude for adjustments: -- "Could you reorganize the canvas to group related components together?" -- "Please add more detail about the connection between these two concepts." - -:: - -## Technical Details - -Behind the scenes, the AI: - -::note -1. Creates a `.canvas` file in JSON format -2. Adds nodes for each concept or document -3. Creates edges to represent relationships -4. Sets positions for visual clarity -5. Includes any relevant metadata -:: - -The resulting file is fully compatible with Obsidian's Canvas feature and can be edited directly in Obsidian. - -## Tips for Effective Visualizations - -- **Be Specific** — Clearly describe what you want to visualize -- **Specify Detail Level** — Mention how much detail you need -- **Mention Type** — Specify the visualization type (concept map, process flow, etc.) -- **Start Simple** — Begin with basic visualizations and ask for refinements - -::note -**Provide context** about what documents or concepts to include for the best results. -:: diff --git a/content/6.concepts/6.schema-system.md b/content/6.concepts/6.schema-system.md index 0de665b..7e5491f 100644 --- a/content/6.concepts/6.schema-system.md +++ b/content/6.concepts/6.schema-system.md @@ -1,5 +1,5 @@ --- -title: Schema System +title: Schemas description: Define, validate, and evolve note structure in Basic Memory with schemas. --- diff --git a/content/7.integrations/0.index.md b/content/7.integrations/0.index.md new file mode 100644 index 0000000..d1c8eb5 --- /dev/null +++ b/content/7.integrations/0.index.md @@ -0,0 +1,149 @@ +--- +title: Connect AI tools +description: Choose an AI client or extension and connect it to Basic Memory. +--- + +Basic Memory is most useful when the AI tools you already use can read and write the same shared knowledge base. Start with the tool you use most, then connect others to the same workspace as needed. + +::tip +For Basic Memory Cloud, use the hosted MCP endpoint: + +```text +https://cloud.basicmemory.com/mcp +``` + +For local/open-source Basic Memory, use the local MCP server from your computer. See [Local MCP tools](/local/mcp-tools-local). +:: + +--- + +## Recommended Cloud Connections + +These are the best starting points for most Basic Memory Cloud users. + +:::card-group +::card +--- +title: Claude +icon: i-simple-icons-anthropic +to: /integrations/claude-desktop +--- +Connect Claude on the web, Claude Desktop, and Claude mobile apps through a custom remote MCP connector. +:: + +::card +--- +title: Claude Code +icon: i-simple-icons-anthropic +to: /integrations/claude-code +--- +Give Claude Code access to shared project knowledge while you work in a repository. +:: + +::card +--- +title: Codex +icon: i-lucide-code +to: /integrations/codex +--- +Use Basic Memory from the Codex app, CLI, and IDE extension. +:: + +::card +--- +title: ChatGPT +icon: i-simple-icons-openai +to: /integrations/chatgpt +--- +Connect ChatGPT as a custom MCP app, with notes about the extra per-chat step. +:: +::: + +--- + +## Coding And Local Editors + +Use these when you work from a code editor, terminal agent, or synced Markdown folder. + +:::card-group +::card +--- +title: Gemini CLI +icon: i-simple-icons-googlegemini +to: /integrations/gemini +--- +Connect Google's command-line AI agent through MCP. +:: + +::card +--- +title: Cursor +icon: i-lucide-mouse-pointer-2 +to: /integrations/cursor +--- +Use Basic Memory knowledge while coding in Cursor. +:: + +::card +--- +title: VS Code +icon: i-lucide-code-2 +to: /integrations/vscode +--- +Work with Basic Memory from VS Code and local Markdown files. +:: + +::card +--- +title: Obsidian +icon: i-lucide-notebook +to: /integrations/obsidian +--- +Use Obsidian as a local editor for Basic Memory Markdown projects. +:: +::: + +--- + +## Extensions And Agent Workflows + +These integrations add richer workflows on top of the core MCP connection. + +:::card-group +::card +--- +title: Agent Skills +icon: i-lucide-sparkles +to: /integrations/skills +--- +Optional instruction packs that teach agents when and how to use Basic Memory well. +:: + +::card +--- +title: OpenClaw +icon: i-lucide-bot +to: /integrations/openclaw +--- +Use the OpenClaw plugin for bundled Basic Memory tools and skills. +:: + +::card +--- +title: Hermes +icon: i-lucide-send +to: /integrations/hermes +--- +Use Hermes for Basic Memory-aware agent workflows. +:: +::: + +--- + +## Choosing Cloud Or Local + +- **Use Cloud** when you want the web app, remote MCP, collaboration, and the same knowledge available from multiple tools or devices. +- **Run locally** when you want files and indexing to stay on your machine, or when your AI client expects a local stdio MCP server. +- **Use both** when you want Cloud for shared projects and local files for editor-first workflows. + +Not sure? Start with [Quickstart: Cloud](/start-here/quickstart-cloud). diff --git a/content/7.integrations/1.claude-desktop.md b/content/7.integrations/1.claude-desktop.md index 70e4e15..a3aae45 100644 --- a/content/7.integrations/1.claude-desktop.md +++ b/content/7.integrations/1.claude-desktop.md @@ -1,146 +1,76 @@ --- -title: Claude Desktop -description: Give Claude a persistent memory that grows with every conversation. +title: Claude +description: Connect Claude to Basic Memory Cloud with a custom MCP connector. --- -Claude Desktop is the flagship way to use Basic Memory. Connect once, and Claude gains full access to your knowledge base — reading, writing, searching, and building on past conversations automatically. +Claude can use Basic Memory Cloud from Claude on the web, Claude Desktop, Cowork, and the Claude mobile apps. The connection is managed through your Claude account, so you only need to add it once. -Basic Memory describes its tools to Claude through the Model Context Protocol, so Claude already knows how to use them. You just ask in plain language. +::note +**The setup is the same across Claude clients.** Add and authorize Basic Memory from claude.ai or Claude Desktop, and the connector becomes available anywhere you use the same Claude account. Mobile apps can use an existing connector, but cannot add a new custom connector. +:: -## Cloud Setup +## Connect Basic Memory ::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** +### Open connectors -Click "Add connector" and enter: -- **Name**: Basic Memory -- **Remote MCP server URL**: `https://cloud.basicmemory.com/mcp` +In Claude on the web or Claude Desktop, open **Customize -> Connectors**. -![Add connector](/claude-settings-add-connector.png) +On Team and Enterprise plans, an owner may need to add Basic Memory first from **Organization settings -> Connectors**. -### Authenticate -Click "Connect" and follow the OAuth flow to grant permissions +### Add a custom connector -![Configure connector](/claude-settings-configure.png) +Choose **Add custom connector** and enter: -### Verify Setup -In Claude, click the tools icon to see Basic Memory tools +- **Name:** Basic Memory +- **Remote MCP server URL:** `https://cloud.basicmemory.com/mcp` -![Tools menu](/claude-settings-tools.png) +### Authorize access -Try prompting: `List my projects` +Add the connector, choose **Connect**, and complete the Basic Memory sign-in and authorization flow. -:: +### Enable it in a conversation -::tip -See the [Cloud Guide](/cloud/cloud-guide) for web editor usage and troubleshooting. +Open the **+** menu beside the message box, choose **Connectors**, and enable Basic Memory for the conversation. :: ---- - -## Local Setup - -For local installation, follow the [Quickstart: Local](/start-here/quickstart-local) guide. It walks you through installing Basic Memory and configuring Claude Desktop in a few minutes. - ---- - -## Try It +## Verify the connection -Once connected, try these prompts to see Basic Memory in action: +Ask Claude: -**Save something from a conversation:** -``` -Create a note summarizing what we just discussed about API rate limiting. +```text +List my Basic Memory projects. ``` -Claude will write a structured note with observations, tags, and relations to other topics in your knowledge base. +Claude should use a Basic Memory tool and return the projects in your workspace. -**Search with meaning, not just keywords:** -``` -Find my notes about login security. -``` +## Try it -Even if your notes use terms like "authentication hardening" or "credential rotation," semantic search surfaces them based on meaning. See [Semantic Search](/concepts/semantic-search) for details. - -**Pick up where you left off:** -``` -What have we been working on this week? +```text +Create a note summarizing what we just discussed, including decisions, +open questions, and next steps. ``` -Claude checks recent activity and offers to continue any thread. Changes sync in real time — edits you make in any text editor appear instantly in your next conversation. - -You can also reference specific notes with `memory://` URLs. Learn more in [Memory URLs](/concepts/memory-urls). - ---- +```text +Find my notes about authentication and summarize the latest decisions. +``` ## Troubleshooting -### Tools not appearing -- **Cloud**: Re-open Claude Desktop after adding the connector. Check that the connector URL is exactly `https://cloud.basicmemory.com/mcp`. -- **Local**: Verify `uv` is installed (`which uvx`), check config JSON syntax, and restart Claude Desktop. -- **Advanced research is on**: Research mode runs in a separate environment that can't reach any MCP connectors. See [Claude Research Mode](/integrations/claude-research-mode). +**Basic Memory is not listed:** Confirm the connector was added to the correct Claude account or organization. -### Tools appear but return errors -- Check Basic Memory is installed: `basic-memory --version` -- Verify sync status: `basic-memory status` -- Check file permissions in your `~/basic-memory` directory +**Claude does not use it:** Enable Basic Memory from the conversation's Connectors menu. -### Changes not showing up -- Real-time sync is on by default. Run `basic-memory status` to confirm. -- Make sure the file is in the correct project directory. -- If needed, run the watcher manually: `basic-memory watch` +**Authorization failed:** Remove the connector, add it again, and repeat the Basic Memory sign-in flow. -### Project selection -Projects are selected at the start of each conversation. For single-project setups, set a default in `~/.basic-memory/config.json`: +**A workspace member cannot add it:** On managed Claude plans, an owner may need to add and approve the connector for the organization. -```json -{ - "default_project": "main" -} -``` - ---- - -## Next Steps - -:::card-group -::card ---- -title: User Guide -icon: i-lucide-book-open -to: /local/user-guide ---- -Daily workflows and usage patterns for getting the most out of Basic Memory. +::note +Claude's labels and settings layout may change. The durable setup is always the same: add Basic Memory as a custom remote connector, use `https://cloud.basicmemory.com/mcp`, then authorize with Basic Memory. :: -::card ---- -title: Knowledge Format -icon: i-lucide-file-text -to: /concepts/knowledge-format ---- -How observations, relations, and tags create a semantic knowledge graph. -:: - -::card ---- -title: AI Assistant Guide -icon: i-lucide-bot -to: /reference/ai-assistant-guide ---- -How Claude uses Basic Memory tools under the hood. -:: +## Next steps -::card ---- -title: Agent Skills -icon: i-lucide-sparkles -to: /integrations/skills ---- -Pre-built skills that teach Claude best practices for Basic Memory. -:: -::: +- [MCP tools reference](/reference/mcp-tools-reference) +- [Knowledge format](/concepts/knowledge-format) +- [Claude Code](/integrations/claude-code) diff --git a/content/7.integrations/11.hermes.md b/content/7.integrations/11.hermes.md index 73325f0..047f13d 100644 --- a/content/7.integrations/11.hermes.md +++ b/content/7.integrations/11.hermes.md @@ -7,7 +7,7 @@ The [hermes-basic-memory](https://github.com/basicmachines-co/hermes-basic-memor The plugin is open source — browse the source on [GitHub](https://github.com/basicmachines-co/hermes-basic-memory). ::warning -**Slash commands need a Hermes Agent-side patch on current releases.** The plugin's agent tools (`bm_*`) and auto-capture work as documented once installed. The native `/bm-*` **slash commands**, however, do not appear in gateway sessions on Hermes Agent releases through `v0.14.0` / `v2026.5.16` (verified 2026-05-16). This is a Hermes Agent plugin-loading gap — exclusive memory-provider plugins aren't loaded during gateway slash-command discovery — not a plugin bug. The plugin ships a best-effort workaround, but it isn't sufficient for gateway startup discovery in affected builds. Until the upstream Hermes fix lands, apply the Hermes Agent-side patch documented in [MONKEYPATCH.md](https://github.com/basicmachines-co/hermes-basic-memory/blob/main/MONKEYPATCH.md). This affects only the slash-command surface; nothing else in this page depends on it. +**Some Hermes Agent releases require an Agent-side patch for slash commands.** The plugin's `bm_*` tools and automatic capture work independently. If `/bm-*` commands do not appear in a gateway session, follow the current compatibility instructions in [MONKEYPATCH.md](https://github.com/basicmachines-co/hermes-basic-memory/blob/main/MONKEYPATCH.md). :: ::tip @@ -135,7 +135,7 @@ Every read/write tool also accepts `project` / `project_id` for per-call routing ## Slash Commands ::note -On Hermes Agent releases through `v0.14.0` / `v2026.5.16`, these commands require the Hermes Agent-side patch in [MONKEYPATCH.md](https://github.com/basicmachines-co/hermes-basic-memory/blob/main/MONKEYPATCH.md) — see the warning at the top of this page. The agent tools above are unaffected. +If these commands do not appear, follow the Hermes Agent compatibility instructions in [MONKEYPATCH.md](https://github.com/basicmachines-co/hermes-basic-memory/blob/main/MONKEYPATCH.md). The agent tools above are unaffected. :: For direct, in-session use without going through the agent: diff --git a/content/7.integrations/12.claude-research-mode.md b/content/7.integrations/12.claude-research-mode.md deleted file mode 100644 index 3186898..0000000 --- a/content/7.integrations/12.claude-research-mode.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Claude Research Mode -description: Why your MCP connectors (including Basic Memory) aren't available during a Claude advanced-research run — and the recommended flow for combining research with your knowledge base. ---- - -When you turn on **advanced research**, Claude hands your request to a dedicated research agent that works across the web and Google Drive. That agent runs in its own environment and **does not have access to your connected MCP servers** — including Basic Memory, Gmail, Google Calendar, and any other connectors. This is a limitation of research mode itself, not of any individual connector: every MCP connector is unavailable during a research run, in the same way. - -What this means in practice: - -- **During a research run,** Claude can't read from or write to Basic Memory (or call any other connector's tools). It will research using web and Drive sources only. -- **After a research run finishes,** control returns to the normal conversation — which _does_ have your connectors. At that point Claude can save the results to Basic Memory, draft an email, add a calendar event, and so on. - -So research and your connectors aren't combined in a single step, but they chain cleanly: **research first, then act on the results with your connectors second.** - ---- - -## Recommended flow: research → save to Basic Memory - -::steps -### Turn advanced research on - -Toggle **advanced research** in the message composer, then run your query — for example, _"survey how other agent-memory tools expose graph APIs."_ - -### Wait for the report - -Let the research run complete. The report comes back inline in the conversation. - -### Turn advanced research off - -Use the same toggle to drop back into normal conversation. This is the important step — leaving research on keeps connectors out of reach. - -### Ask Claude to save it - -Now you're back in the normal tool path. Ask Claude to write up the results — _"Save that as a note in my `research` project"_ — and it can call Basic Memory's [`write_note`](/reference/mcp-tools-reference#write_note) directly. -:: - -The same pattern works in reverse for context you already have: if you need Claude to _use_ your Basic Memory notes as input, keep research off and ask normally — Claude can read your notes and reason over them directly. Use research only when you specifically want fresh web/Drive sources. - -::tip -**Which mode do I need?** If the question is "go find out what's out there on the web," use research. If it's "do something with my notes/data," keep research off. -:: - ---- - -## Why this happens - -Research mode runs a separate agent with its own toolset (web search, Google Drive). MCP connectors live on the main Claude conversation, not inside the research agent's environment. The research agent doesn't know your connectors exist, so it can't call them — and there's no way to "pass through" a connector during a research run. - -This is the same for **every** MCP connector, not specific to Basic Memory. If you have a workflow that wants both web research _and_ your private knowledge base in a single step, today the answer is to run them sequentially: research first, then a follow-up turn that uses your connectors on the results. - ---- - -## Related - -:::card-group -::card ---- -title: Claude Desktop -icon: i-lucide-monitor -to: /integrations/claude-desktop ---- -Connect Basic Memory to Claude Desktop or Claude on the web. -:: - -::card ---- -title: MCP Tools Reference -icon: i-lucide-wrench -to: /reference/mcp-tools-reference ---- -Every tool Claude can call when research mode is off. -:: - -::card ---- -title: Web App -icon: i-lucide-layout-dashboard -to: /cloud/web-app ---- -Save and organize research results in the cloud app. -:: -::: diff --git a/content/7.integrations/2.claude-code.md b/content/7.integrations/2.claude-code.md index 954cb31..e4b850f 100644 --- a/content/7.integrations/2.claude-code.md +++ b/content/7.integrations/2.claude-code.md @@ -1,145 +1,73 @@ --- -title: "Claude Code" -description: "Give Claude Code persistent memory with Basic Memory. Decisions, architecture, and project context carry over across every coding session." +title: Claude Code +description: Connect Claude Code to Basic Memory Cloud through remote MCP. --- -Claude Code is powerful, but every session starts from zero. Basic Memory gives it a persistent knowledge base -- so your AI remembers project decisions, code patterns, and context across every session. +Connect Claude Code to Basic Memory Cloud to use shared project knowledge, decisions, research, and workflows while you code. -## Cloud Setup +## Connect Basic Memory -::steps -### Sign Up -Create your account at [app.basicmemory.com](https://app.basicmemory.com). - -### Add Remote MCP Server -In your terminal, add the remote MCP server: +Run: ```bash -claude mcp add -s user -t http basic-memory-cloud https://cloud.basicmemory.com/mcp +claude mcp add --transport http --scope user basic-memory https://cloud.basicmemory.com/mcp ``` -### Authenticate -Follow the OAuth flow in Claude Code to grant permissions. +The `user` scope makes the connection available across your projects. -### Verify -Run `/mcp` in Claude Code and confirm Basic Memory tools are listed. -:: +Then open Claude Code and run: -::tip -See the [Cloud Guide](/cloud/cloud-guide) for detailed instructions and troubleshooting. -:: +```text +/mcp +``` ---- +Select Basic Memory and complete the browser authorization flow. -## Local Setup +## Verify the connection -Install Basic Memory locally ([Quickstart: Local](/start-here/quickstart-local)), then add it to Claude Code: +Run `/mcp` again and confirm that Basic Memory is connected. Then ask: -```bash -claude mcp add basic-memory basic-memory mcp +```text +List my Basic Memory projects. ``` -Run `/mcp` in Claude Code to confirm the tools are available. - ---- - -## Try It - -Once connected, try these prompts in Claude Code: +## Try it ```text -"Create a note about our authentication strategy -- we're using JWT with -refresh tokens, and here's why..." +Create a note documenting the architecture decisions in this repository. ``` ```text -"Search my notes for anything related to database migration patterns" +Search my notes for previous decisions about database migrations. ``` ```text -"What do my notes say about the API rate limiting decision we made last week?" +Update the project note with the changes we made today. ``` -Basic Memory supports [semantic search](/concepts/semantic-search), so your queries don't need to match exact keywords -- it finds notes by meaning. +## Claude Code instructions and Basic Memory -For the full list of tools Claude Code can use, see the [MCP Tools Reference](/reference/mcp-tools-reference). - ---- - -## CLAUDE.md and Basic Memory - -Claude Code uses `CLAUDE.md` files for project-level instructions. Basic Memory complements this nicely: `CLAUDE.md` tells Claude Code *how* to work in a project, while Basic Memory stores the *knowledge* -- decisions, architecture notes, research, context -- that doesn't belong in a static instruction file. - ---- - -## Agent Skills - -Install [agent skills](/integrations/skills) to teach Claude Code best practices for writing well-structured notes. Skills give your AI reusable patterns so notes are consistent and useful from the start. - ---- +Use `CLAUDE.md` for durable instructions about how Claude should work in a repository. Use Basic Memory for knowledge that grows and changes: decisions, research, meeting notes, project history, and reusable workflows. ## Troubleshooting -**Tools not showing up in `/mcp`?** -- For local: verify Basic Memory is installed (`basic-memory --version`) and re-add the server: `claude mcp remove basic-memory && claude mcp add basic-memory basic-memory mcp` -- For cloud: re-run the `claude mcp add` command and complete the OAuth flow again +**The server is missing from `/mcp`:** -**Notes not syncing?** -- Check sync status: `basic-memory status` -- Look for errors in `~/.basic-memory/logs/` - ---- - -## FAQ - -### Claude Code already has CLAUDE.md and auto memory. Why add Basic Memory? -Claude Code's built-in memory is great for project instructions and short learnings. Basic Memory adds a full knowledge base on top — searchable notes with semantic connections, observations, and relations that span across projects and AI tools. Think of CLAUDE.md as "how to work here" and Basic Memory as "everything we know." See [Using Basic Memory with Built-in AI Memory](/concepts/vs-built-in-memory) for a deeper comparison. - -### How does Basic Memory work alongside CLAUDE.md? -They complement each other. `CLAUDE.md` holds project instructions and coding standards. Basic Memory holds evolving knowledge — decisions, architecture notes, research, meeting notes, and context that grows over time. Claude Code's auto memory captures small preferences; Basic Memory captures structured knowledge you can search, link, and reuse across any AI tool. - ---- - -::note -**Basic Memory also works with:** [Cursor](/integrations/cursor) · [OpenAI Codex](/integrations/codex) · [Claude Desktop](/integrations/claude-desktop) · [VS Code](/integrations/vscode) · [Obsidian](/integrations/obsidian) -:: +```bash +claude mcp list +``` -## Next Steps +If necessary, remove it and add it again: -:::card-group -::card ---- -title: Project Documentation -icon: i-lucide-folder-kanban -to: /how-to/project-documentation ---- -Learn how to document your development projects. -:: +```bash +claude mcp remove basic-memory +claude mcp add --transport http --scope user basic-memory https://cloud.basicmemory.com/mcp +``` -::card ---- -title: MCP Tools Reference -icon: i-lucide-wrench -to: /reference/mcp-tools-reference ---- -Full reference for all 17 Basic Memory tools. -:: +**Authorization needs to be repeated:** Open `/mcp`, select Basic Memory, and use the authentication controls to clear or restart authorization. -::card ---- -title: Agent Skills -icon: i-lucide-sparkles -to: /integrations/skills ---- -Pre-built skills that teach Claude Code best practices for Basic Memory. -:: +## Next steps -::card ---- -title: Knowledge Format -icon: i-lucide-file-text -to: /concepts/knowledge-format ---- -Structure effective development documentation. -:: -::: +- [Project documentation](/how-to/project-documentation) +- [MCP tools reference](/reference/mcp-tools-reference) +- [Agent skills](/integrations/skills) diff --git a/content/7.integrations/3.chatgpt.md b/content/7.integrations/3.chatgpt.md index 126d829..a737550 100644 --- a/content/7.integrations/3.chatgpt.md +++ b/content/7.integrations/3.chatgpt.md @@ -1,100 +1,86 @@ --- title: ChatGPT -description: Use ChatGPT with Basic Memory Cloud for MCP-powered knowledge access +description: Connect ChatGPT to Basic Memory Cloud as a custom MCP app. --- -ChatGPT supports remote MCP servers, giving it access to your Basic Memory knowledge base. Since ChatGPT only connects to remote servers, **Basic Memory Cloud is required**. +ChatGPT connects to Basic Memory as a custom app backed by its remote MCP server. -## Cloud Setup +::tip +**For the smoothest experience with a ChatGPT account, we recommend [Codex](/integrations/codex).** Codex treats MCP servers as part of its persistent tool configuration, making Basic Memory readily available across new threads. Standard ChatGPT requires you to add Basic Memory to each chat where you want to use it. +:: + +::note +**Configure Basic Memory on the web.** Developer mode and custom app creation are managed at [chatgpt.com](https://chatgpt.com). Once connected, Basic Memory can be used in ChatGPT on the web and in the ChatGPT desktop app. Custom MCP apps are not currently available on mobile. +:: + +::note +OpenAI is still rolling out full MCP support. Full read and write access is currently intended for ChatGPT Business, Enterprise, and Edu workspaces. Pro users can use custom apps with more limited read and fetch access. Workspace administrators control availability on managed plans. +:: + +## Connect Basic Memory ::steps -### Sign Up +### Open ChatGPT on the web -Create your account at [app.basicmemory.com](https://app.basicmemory.com). +Go to [chatgpt.com](https://chatgpt.com). Custom MCP apps are created and managed from the web interface, even if you plan to use Basic Memory in the desktop app. -### Get Your MCP Endpoint +### Enable developer mode -Your remote MCP URL: `https://cloud.basicmemory.com/mcp` +In ChatGPT on the web, open **Settings -> Apps -> Advanced settings** and enable developer mode. -### Configure ChatGPT +On managed workspaces, an administrator may first need to allow custom MCP apps under workspace permissions. -In ChatGPT, go to **Settings > Developer > Custom MCP Servers** and add: +### Create the app -- **Name**: Basic Memory -- **Server URL**: `https://cloud.basicmemory.com/mcp` +Open **Settings -> Apps -> Create** and enter: -### Authenticate +- **Name:** Basic Memory +- **MCP server URL:** `https://cloud.basicmemory.com/mcp` +- **Authentication:** OAuth -Follow the OAuth flow to grant ChatGPT access to your Basic Memory account. +### Authorize access -### Enable in Conversations +Complete the Basic Memory sign-in flow and allow ChatGPT to discover the available tools. -When chatting, enable Basic Memory from the MCP server selector to start using your knowledge base. -:: +### Add Basic Memory to a chat -::tip -See the [Cloud Setup Guide](/cloud/cloud-guide) for detailed instructions. +Start a chat, open the **+** menu, choose **More**, and select Basic Memory. ChatGPT only gives the current chat access to apps you add to it. :: -## Try It +![The ChatGPT message composer with the plus menu open. Choose More to add Basic Memory to the current chat.](/screenshots/integrations/chatgpt-add-app-to-chat.png) -Once connected, ask ChatGPT to work with your knowledge base: +You need to add Basic Memory again when you start another chat. This extra per-chat step is the main reason we recommend Codex for people who want Basic Memory available throughout an ongoing AI-assisted workflow. -- **Search**: "Find my notes about authentication design" -- **Retrieve**: "Show me the full contents of my API documentation" -- **Semantic search**: "Find notes conceptually related to microservice architecture" (requires full MCP access) +## Verify the connection -ChatGPT will call the appropriate tools behind the scenes, searching and fetching documents as needed. +Ask: -## Important Notes +```text +List my Basic Memory projects. +``` -::warning -**ChatGPT Plus or Pro subscription required.** MCP integration is not available on ChatGPT's free tier. -:: +When the connection is working, ChatGPT shows that it called a tool and answers using your Basic Memory knowledge. -::note -**Default vs full MCP access** +![ChatGPT confirms that it called a tool and can see notes through the connected Basic Memory Cloud app.](/screenshots/integrations/chatgpt-tool-confirmation.png) -By default, ChatGPT exposes two tools: `search` for finding content and `fetch` for retrieving documents. To unlock all 17+ MCP tools — including `write_note`, `edit_note`, semantic search with text/vector/hybrid modes, and project management — explicitly enable the Basic Memory MCP server in ChatGPT's developer settings. +For a workspace with full MCP access, also test: -See the [MCP Tools Reference](/reference/mcp-tools-reference) for full tool documentation and the [Semantic Search](/concepts/semantic-search) guide for search mode details. -:: +```text +Create a note titled "ChatGPT connection test." +``` ## Troubleshooting -**"MCP server not available"** — Confirm you have a ChatGPT Plus or Pro subscription. MCP is not available on the free tier. - -**Authentication errors** — Re-add the MCP server in ChatGPT settings and complete the OAuth flow again. +**Developer mode is unavailable:** Your ChatGPT plan, workspace role, or administrator policy may not permit custom apps. -**No results returned** — Make sure your Basic Memory Cloud account has synced content. Check your project at [app.basicmemory.com](https://app.basicmemory.com). +**Basic Memory can search but cannot write:** Your current ChatGPT plan or workspace configuration may expose only read and fetch actions. -## Next Steps +**The tool list is outdated:** Managed ChatGPT workspaces may use an approved snapshot of an app's tools. An administrator may need to refresh and republish the app. -:::card-group -::card ---- -title: Cloud Setup Guide -icon: i-lucide-cloud -to: /cloud/cloud-guide ---- -Detailed cloud configuration and sync options. -:: +**Authorization failed:** Remove the app, create it again, and repeat the Basic Memory OAuth flow. -::card ---- -title: MCP Tools Reference -icon: i-lucide-wrench -to: /reference/mcp-tools-reference ---- -Complete documentation for all 17+ MCP tools. -:: +## Next steps -::card ---- -title: Claude Desktop -icon: i-lucide-message-square -to: /integrations/claude-desktop ---- -Full local and remote MCP integration. -:: -::: +- [MCP tools reference](/reference/mcp-tools-reference) +- [Knowledge format](/concepts/knowledge-format) +- [Cloud Overview](/cloud/cloud-guide) diff --git a/content/7.integrations/4.gemini.md b/content/7.integrations/4.gemini.md index e1e5f5a..f90a817 100644 --- a/content/7.integrations/4.gemini.md +++ b/content/7.integrations/4.gemini.md @@ -1,165 +1,57 @@ --- -title: Google Gemini -description: Connect Basic Memory to Google Gemini CLI for persistent knowledge across AI sessions +title: Gemini CLI +description: Connect Gemini CLI to Basic Memory Cloud through remote MCP. --- -Google Gemini has native MCP support, so connecting it to Basic Memory takes a single command. +Gemini CLI supports remote HTTP MCP servers, so it can connect directly to Basic Memory Cloud. -## Cloud Setup +## Connect Basic Memory -No local install needed -- Basic Memory Cloud gives you hosted MCP access. - -::steps -### Sign Up -Create your account at [app.basicmemory.com](https://app.basicmemory.com). - -### Add the Remote MCP Server +Run: ```bash -gemini mcp add -t http basic-memory-cloud https://cloud.basicmemory.com/mcp +gemini mcp add basic-memory https://cloud.basicmemory.com/mcp --transport http --scope user ``` -### Authenticate -Follow the OAuth flow to grant Gemini access to your Basic Memory account. +Complete the authorization flow when Gemini prompts you to sign in. -### Verify +## Verify the connection ```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 +Basic Memory should appear as a connected HTTP server. Then start Gemini and ask: -Watch this quick guide to get started with Basic Memory and Google Gemini: - -
- -
- -### Configure Gemini - -::steps -### Install - -```bash -gemini mcp add basic-memory bash -c "uvx basic-memory mcp" +```text +List my Basic Memory projects. ``` -### Verify +## Try it -```bash -gemini mcp list -``` - -You should see `basic-memory` listed with Connected status. -:: - -::tip -To target a specific project: -```bash -gemini mcp add basic-memory bash -c "uvx basic-memory mcp --project your-project-name" +```text +Create a note explaining the decisions we made in this session. ``` -To install globally for your user profile, add the `-s user` flag: -```bash -gemini mcp add -s user basic-memory bash -c "uvx basic-memory mcp" +```text +Search my notes for research related to this project. ``` -:: - ---- - -## Try It - -Once Gemini is connected, give these a spin: - -**Save a decision** -``` -"Create a note about our decision to use JWT-based auth for the API, -including the trade-offs we discussed." -``` - -**Pick up where you left off** -``` -"What have I been working on this week? Check recent activity." -``` - -**Semantic search** -``` -"Search my notes for anything related to database migration strategies." -``` - -For the full list of available tools, see the [MCP Tools Reference](/reference/mcp-tools-reference). - ---- ## Troubleshooting -**Gemini can't find Basic Memory** -- Verify it's installed (`basic-memory --version`), then check `gemini mcp list`. If the entry looks wrong, remove and re-add it: +**Basic Memory is not connected:** + ```bash gemini mcp remove basic-memory -gemini mcp add basic-memory bash -c "uvx basic-memory mcp" +gemini mcp add basic-memory https://cloud.basicmemory.com/mcp --transport http --scope user ``` -**memory:// URLs not resolving** -- Make sure the note exists in your current project and that sync is running (`basic-memory status`). - -**Notes not updating** -- Check file permissions in your knowledge base directory and look for errors in `~/.basic-memory/logs`. +**The connection changed but Gemini still shows the old state:** Restart Gemini or use `/mcp reload` in an active session. ---- - -## 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. -:: +**Authorization failed:** Remove the server, add it again, and repeat the browser sign-in flow. -::card ---- -title: MCP Tools Reference -icon: i-lucide-wrench -to: /reference/mcp-tools-reference ---- -See every tool Basic Memory exposes. -:: +## Next steps -::card ---- -title: Knowledge Format -icon: i-lucide-file-text -to: /concepts/knowledge-format ---- -Structure effective documentation. -:: -::: +- [MCP tools reference](/reference/mcp-tools-reference) +- [Research and learning](/how-to/research-learning) +- [Knowledge format](/concepts/knowledge-format) diff --git a/content/7.integrations/5.codex.md b/content/7.integrations/5.codex.md index 0feb535..6065fa2 100644 --- a/content/7.integrations/5.codex.md +++ b/content/7.integrations/5.codex.md @@ -1,249 +1,120 @@ --- -title: "OpenAI Codex" -description: "Give OpenAI Codex persistent memory with Basic Memory and MCP. Architecture decisions, API designs, and project context follow you across every session — in the Codex app and the Codex CLI." +title: Codex +description: Connect the Codex app and CLI to Basic Memory Cloud through MCP. --- -OpenAI Codex is a powerful coding agent, but it starts fresh every time. Basic Memory gives it persistent context through MCP — architecture decisions, API designs, and project knowledge carry over between sessions. Notes created in Codex are immediately available in Claude Code, Cursor, Claude Desktop, or any other MCP client. +Codex can use Basic Memory while planning, coding, reviewing, and working across applications. The Codex desktop app, CLI, and IDE extension share MCP configuration on your computer. -Codex comes in two forms, and both connect to Basic Memory: - -- **Codex app** — the agent inside ChatGPT (or the Codex desktop app) -- **Codex CLI** — the terminal-based coding agent - -Each one can connect to either a **local** Basic Memory (running on your machine) or **Basic Memory Cloud** (remote MCP). Pick the combination that fits your workflow. - -::tip -**Cloud is the easiest path for the Codex app.** App clients only speak HTTP/SSE, so connecting to Basic Memory Cloud takes one URL and a sign-in — no local servers to keep running. -:: - ---- - -## Codex app - -The Codex app talks to MCP servers over HTTP, so you give it a URL. - -### Connect to Basic Memory Cloud (remote MCP) +## Codex desktop ::steps -### Get your MCP endpoint +### Open MCP settings -Your Basic Memory Cloud URL is: +In the Codex app, open **Settings -> Integrations & MCP**. -``` -https://cloud.basicmemory.com/mcp -``` +### Add Basic Memory -### Add it in Codex +Choose the option to add a custom MCP server and enter: -In the Codex app, open **Settings → Connectors → Custom MCP** (the exact label may be "MCP Servers" or "Developer → MCP" depending on your version) and add: +- **Name:** Basic Memory +- **URL:** `https://cloud.basicmemory.com/mcp` -- **Name**: Basic Memory -- **Server URL**: `https://cloud.basicmemory.com/mcp` +### Authorize access -### Authenticate +Save the server. Codex opens the Basic Memory authorization flow when the connection requires OAuth. -Sign in to authorize Codex. Basic Memory Cloud uses OAuth — when prompted, complete the sign-in flow in your browser. +### Start a new thread -### Enable in conversations +Open a new Codex thread after the connection is authorized, then ask: -Turn on the Basic Memory connector for the conversation, and Codex can read, write, and search your notes. -:: - -### Connect to a local Basic Memory (local MCP) - -To point the app at a Basic Memory running on your own machine, start a local HTTP MCP server, then add its URL to Codex: - -::steps -### Start a local server - -```bash -basic-memory mcp --transport streamable-http --port 8000 +```text +List my Basic Memory projects. ``` - -This exposes Basic Memory at `http://localhost:8000/mcp`. - -### Add it in Codex - -In Codex's MCP/connector settings, add: - -- **Name**: Basic Memory (local) -- **Server URL**: `http://localhost:8000/mcp` :: -::note -Local MCP for an app means keeping that `basic-memory mcp` process running while you use Codex. For most app users, the Cloud setup is simpler. -:: - ---- +The app stores this connection in `~/.codex/config.toml`, so it is also available to the Codex CLI and IDE extension. ## Codex CLI -The [Codex CLI](https://github.com/openai/codex) can spawn local MCP servers as subprocesses **or** connect to a remote MCP endpoint via its config file. - -### Local MCP - -::steps -### Add Basic Memory as a local MCP server +You can configure the same connection from a terminal: ```bash -codex mcp add basic-memory bash -c "uvx basic-memory mcp" +codex mcp add basic-memory --url https://cloud.basicmemory.com/mcp ``` -::tip -To lock it to a specific project, add the `--project` flag: +Authorize the connection: ```bash -codex mcp add basic-memory bash -c "uvx basic-memory mcp --project your-project-name" +codex mcp login basic-memory ``` -:: -### Verify +Complete the Basic Memory sign-in flow in your browser. + +Verify the connection: ```bash codex mcp list ``` -You should see `basic-memory` listed with the command `bash -c uvx basic-memory mcp`. -:: - -#### Video walkthrough - -
- -
- -### Remote MCP (Basic Memory Cloud) - -::steps -### Get an API key - -Create one in the [web app](https://app.basicmemory.com) under **Settings → API Keys**. See the [API Keys guide](/cloud/api-keys) for details. - -### Export it +Then open a new Codex session and ask: -Add the key to your shell profile (`~/.zshrc` or `~/.bashrc`): - -```bash -export BASIC_MEMORY_API_KEY= +```text +List my Basic Memory projects. ``` -Reload your shell: +## Manual configuration -```bash -source ~/.zshrc -``` - -### Configure `~/.codex/config.toml` +Both setup methods create this entry in `~/.codex/config.toml`: ```toml [mcp_servers.basic-memory] url = "https://cloud.basicmemory.com/mcp" -bearer_token_env_var = "BASIC_MEMORY_API_KEY" ``` -The Codex CLI will now connect to Basic Memory Cloud using your API key for authentication. -:: - ---- +You only need to configure Basic Memory once. Changes made in the app, CLI, or IDE extension apply to the other Codex clients on the same computer. ## Try it -Once configured, try these prompts to see Basic Memory in action: - ```text -"Create a note about our authentication strategy for the API" +Create a note documenting the architecture decisions in this repository. ``` -Codex creates a structured note with technical details and rationale, saved to your knowledge base. - ```text -"Search my notes for everything related to database migrations" +Search Basic Memory for earlier work related to this feature. ``` -Codex uses semantic search to find relevant notes across your projects — even when they don't contain the exact words. - ```text -"What decisions have we made about the API design? Check my notes." +Save this workflow so our team can repeat it later. ``` -Codex loads context from your knowledge base and gives answers grounded in your actual project history. +## Troubleshooting -For the full list of tools Codex can use, see the [MCP Tools Reference](/reference/mcp-tools-reference). +**Basic Memory is not listed in the desktop app:** Open **Settings -> Integrations & MCP** and confirm that the server is enabled. ---- +**Basic Memory is not listed in the CLI:** -## Troubleshooting +```bash +codex mcp list +``` -**Codex CLI can't find Basic Memory** — Verify it's installed (`basic-memory --version`), check MCP config (`codex mcp list`), and reinstall if needed: +If necessary: ```bash codex mcp remove basic-memory -codex mcp add basic-memory bash -c "uvx basic-memory mcp" +codex mcp add basic-memory --url https://cloud.basicmemory.com/mcp ``` -**Codex app can't reach a local server** — Confirm `basic-memory mcp --transport streamable-http` is still running and the port matches the URL you gave Codex. Apps can't spawn subprocesses, so the server has to be live. - -**Cloud authentication errors** — For the CLI, make sure `BASIC_MEMORY_API_KEY` is exported in the shell Codex was launched from. For the app, remove and re-add the connector to redo the OAuth flow. - -**Context not loading from memory:// URLs** — Confirm the note exists in your current project, check the URL syntax (`memory://folder/note`), and verify sync status with `basic-memory status`. - ---- - -## FAQ - -### Does Codex have persistent memory? -Not by default. Basic Memory adds persistent, searchable context through MCP, so Codex can access your full project knowledge every session. - -### Can I share notes between Codex and other AI tools? -Yes. Basic Memory uses plain Markdown files as the source of truth. Notes created in Codex are immediately available in Claude Code, Cursor, Claude Desktop, or any MCP client. - -### App or CLI — which should I use? -They're complementary. Many people use the **CLI** with local MCP while coding, and the **app** with cloud MCP for planning or review on another device. Both read the same knowledge base. - -### Local or remote MCP? -- **Local** keeps everything on your machine — best for personal projects and when you don't want anything in the cloud. -- **Remote** (Basic Memory Cloud) means your notes are reachable from any device and any client, with no local processes to manage. Required for the app unless you're willing to run a local HTTP server. +**Authorization failed:** ---- - -::note -**Basic Memory also works with:** [Claude Code](/integrations/claude-code) · [Cursor](/integrations/cursor) · [Claude Desktop](/integrations/claude-desktop) · [VS Code](/integrations/vscode) · [Obsidian](/integrations/obsidian) -:: - -## Next Steps +```bash +codex mcp logout basic-memory +codex mcp login basic-memory +``` -:::card-group -::card ---- -title: Project Documentation -icon: i-lucide-folder-kanban -to: /how-to/project-documentation ---- -Learn how to document your development projects. -:: +**An existing thread cannot see the tools:** Start a new Codex thread after adding or changing the MCP server. -::card ---- -title: MCP Tools Reference -icon: i-lucide-wrench -to: /reference/mcp-tools-reference ---- -See every tool available to Codex through MCP. -:: +## Next steps -::card ---- -title: Knowledge Format -icon: i-lucide-file-text -to: /concepts/knowledge-format ---- -Structure effective development documentation. -:: -::: +- [Project documentation](/how-to/project-documentation) +- [MCP tools reference](/reference/mcp-tools-reference) +- [Agent skills](/integrations/skills) diff --git a/content/7.integrations/6.cursor.md b/content/7.integrations/6.cursor.md index 87f82d1..28c7f10 100644 --- a/content/7.integrations/6.cursor.md +++ b/content/7.integrations/6.cursor.md @@ -1,157 +1,64 @@ --- -title: "Cursor" -description: "Give Cursor persistent memory with Basic Memory. Full notes, semantic search, and rich context that outlasts built-in memories." +title: Cursor +description: Connect Cursor to Basic Memory Cloud through remote MCP. --- -Cursor's built-in memories store short preference strings. Basic Memory gives it a full knowledge base — searchable notes with semantic connections that persist across every session and grow with your project. +Cursor supports remote Streamable HTTP MCP servers and OAuth, so it can connect directly to Basic Memory Cloud. -## Cloud Setup +## Connect Basic Memory -::steps -### Sign Up -Create your account at [app.basicmemory.com](https://app.basicmemory.com) +Open Cursor's MCP settings and add a custom server. Cursor stores MCP configuration in `mcp.json`. -### Configure Remote MCP in Cursor -Go to **Settings > Developer > Edit Config**, select **MCP Tools**, click **Add Custom MCP**, and add: +Add: ```json { "mcpServers": { - "basic-memory-cloud": { + "basic-memory": { "url": "https://cloud.basicmemory.com/mcp" } } } ``` -### Authenticate -Follow the OAuth flow to grant Cursor access to your Basic Memory account. +Use the authorization control shown for Basic Memory and complete the browser sign-in flow. -### Verify -Ask the AI: `"What Basic Memory tools do you have?"` +::note +Use Cursor's user-level MCP configuration to make Basic Memory available in every project. Use a project-level `.cursor/mcp.json` only when the connection should be defined by that repository. :: -::tip -See the [Cloud Setup Guide](/cloud/cloud-guide) for detailed instructions and troubleshooting. -:: +## Verify the connection ---- +Open Cursor's MCP settings and confirm that Basic Memory is enabled and its tools are available. Then ask: -## Local Setup - -::steps -### Configure MCP -Cursor supports MCP natively. Add Basic Memory following the [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol): - -```json -{ - "mcpServers": { - "basic-memory": { - "command": "uvx", - "args": ["basic-memory", "mcp"] - } - } -} +```text +List my Basic Memory projects. ``` -### Install Basic Memory (optional) - -```bash -# With uv -uv tool install basic-memory +## Try it -# Or with pip -pip install basic-memory +```text +Create a note documenting this repository's authentication architecture. ``` -### Verify -Ask the AI: `"What Basic Memory tools do you have?"` - -You should see tools for note creation, search, and project management. -:: - ---- - -## Try It - -Once configured, try these prompts in Cursor: - -``` -"Create a note documenting our API authentication approach and link it to the user-auth module." -``` - -``` -"Search my notes for anything related to database migration strategy." +```text +Search my notes for previous database migration decisions. ``` +```text +Update our project note with the changes made in this session. ``` -"What have I been working on this week? Check recent activity." -``` - -For the full list of available tools, see the [MCP Tools Reference](/reference/mcp-tools-reference). - ---- ## Troubleshooting -**MCP tools not appearing** — Verify Basic Memory is installed (`basic-memory --version`), check your JSON config syntax, and restart Cursor. Try an absolute path to `uvx` if needed. - -**Tools appear but don't work** — Run `basic-memory status` to check sync. Verify project directory permissions and that `which basic-memory` resolves. - -**Cloud connection issues** — See the [Cloud Setup Guide](/cloud/cloud-guide) for OAuth troubleshooting. - ---- - -## Frequently Asked Questions +**The server does not appear:** Check that `mcp.json` contains valid JSON and that the URL is exactly `https://cloud.basicmemory.com/mcp`. -### Does Cursor have memory? -Cursor has a built-in "Memories" feature for storing short preferences, but it is limited to simple rules. Basic Memory provides full knowledge management — searchable notes, semantic connections, and rich context that grows with your project. +**Tools are missing:** Enable Basic Memory in Cursor's MCP settings, then restart Cursor if the configuration was just added. -### Can I use Basic Memory and Cursor's built-in memories together? -Yes. Cursor's built-in memories handle quick preferences and rules. Basic Memory handles everything deeper — architecture decisions, project history, detailed technical context, and cross-session knowledge. +**Authorization failed:** Disconnect or remove the server, add it again, and repeat the OAuth flow. ---- - -::note -**Basic Memory also works with:** [Claude Code](/integrations/claude-code) · [OpenAI Codex](/integrations/codex) · [Claude Desktop](/integrations/claude-desktop) · [VS Code](/integrations/vscode) · [Obsidian](/integrations/obsidian) -:: +## Next steps -## 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: Note Taking -icon: i-lucide-edit -to: /how-to/note-taking ---- -Master note-taking techniques for development. -:: - -::card ---- -title: MCP Tools Reference -icon: i-lucide-wrench -to: /reference/mcp-tools-reference ---- -See every tool Basic Memory exposes to your AI. -:: - -::card ---- -title: Knowledge Format -icon: i-lucide-file-text -to: /concepts/knowledge-format ---- -Structure your development documentation. -:: -::: +- [Project documentation](/how-to/project-documentation) +- [MCP tools reference](/reference/mcp-tools-reference) +- [Knowledge format](/concepts/knowledge-format) diff --git a/content/7.integrations/7.vscode.md b/content/7.integrations/7.vscode.md index f2ebb46..ed9f4fb 100644 --- a/content/7.integrations/7.vscode.md +++ b/content/7.integrations/7.vscode.md @@ -1,185 +1,58 @@ --- title: VS Code -description: Edit your Basic Memory knowledge base directly in VS Code with full IDE features and terminal CLI access +description: Use Basic Memory from VS Code through MCP or edit its Markdown files directly. --- -Edit your knowledge base directly in VS Code -- full syntax highlighting, markdown preview, and the Basic Memory CLI right in your terminal. +VS Code supports two complementary Basic Memory workflows: -## Cloud Sync Workflow +- Connect an MCP-capable chat client in VS Code to Basic Memory. +- Open a local Basic Memory project as an ordinary Markdown folder. -Basic Memory Cloud lets you edit locally in VS Code while keeping notes synced to the cloud. +## Connect through MCP -::steps -### Sign Up for Basic Memory Cloud -Create your account at [app.basicmemory.com](https://app.basicmemory.com) +VS Code's MCP support changes independently of Basic Memory. Follow the current [VS Code MCP server documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) and add one of these servers: -### Enable Cloud Mode -Authenticate and enable cloud mode: +### Basic Memory Cloud -```bash -bm cloud login -``` - -### Set Up Sync -Install rclone and configure credentials: - -```bash -bm cloud setup -``` - -This installs rclone automatically and configures your cloud credentials. - -::note -Sync requires the Basic Memory CLI. See [Local Installation](/local/local-install) for setup. -:: - -### Create Project with Local Sync -Point Basic Memory to your local workspace: - -```bash -# For a project-specific docs folder -bm project add my-project --local-path ~/workspace/my-project/docs - -# Or for a shared knowledge base -bm project add knowledge --local-path ~/Documents/knowledge -``` - -### Establish Sync Baseline -Preview and run the initial sync: - -```bash -# Preview first (recommended) -bm cloud bisync --name my-project --resync --dry-run - -# Establish baseline -bm cloud bisync --name my-project --resync -``` - -Only use `--resync` for the first sync. +- Transport: remote HTTP +- URL: `https://cloud.basicmemory.com/mcp` +- Authentication: OAuth -### Edit in VS Code -Open your local directory in VS Code. Edit files with full IDE features -- syntax highlighting, markdown preview, split editors, and search all work out of the box. +### Open-source local server -### Sync Changes -After editing locally or making changes in cloud, run bidirectional sync: - -```bash -bm cloud bisync --name my-project +```json +{ + "servers": { + "basic-memory": { + "command": "uvx", + "args": ["basic-memory", "mcp"] + } + } +} ``` -Changes flow both directions. Edit locally or in the cloud, both stay in sync. +Restart or reload VS Code after changing MCP configuration, then ask the chat client to list your Basic Memory projects. -:: +## Edit Markdown directly -::note -**Bidirectional sync**: `bisync` keeps local and cloud in sync automatically. Newer files win conflicts. For one-way sync and advanced configuration, see the [Cloud Sync Guide](/cloud/cloud-sync). -:: - ---- - -## Local Setup - -If you're running Basic Memory locally (no cloud), setup is simple: +For a local project, open its configured folder in VS Code: ```bash -# Install Basic Memory -uv tool install basic-memory - -# Add a project pointing to a folder -bm project add my-project --local-path ~/workspace/my-project/docs +bm project add project-docs ~/workspace/project/docs +code ~/workspace/project/docs ``` -Then open that folder in VS Code. That's it -- your markdown files are the knowledge base. Every edit you make is automatically synced to the knowledge graph. - ---- - -## Try It - -### Edit Files Directly +Basic Memory watches local project files and updates its index as Markdown changes. -VS Code is a first-class way to work with Basic Memory notes. Open any markdown file, edit it, save. Basic Memory watches for changes and updates the knowledge graph automatically. +For a personal Cloud project, first follow [Edit Locally and in the App](/cloud/edit-locally-and-in-the-app), then open the synchronized folder in VS Code. Run `bm cloud bisync --name ` before and after switching between local and web editing. -Use split editors to view code on one side and documentation on the other. Use VS Code's built-in search to find content across your knowledge base. - -### Terminal CLI - -Open VS Code's integrated terminal for quick operations: +## Useful terminal commands ```bash -# Search your knowledge base (including semantic search) +bm project list +bm status bm tool search-notes --query "authentication flow" -bm tool search-notes --query "how to handle errors" --search-type hybrid - -# Check recent activity bm tool recent-activity --timeframe "2 days" - -# Write a quick note -bm tool write-note --title "API Design Decision" --folder "decisions" -``` - -Set up aliases in your shell profile (`.bashrc`, `.zshrc`, etc.) for faster access: - -```bash -alias note="bm tool write-note" -alias search="bm tool search-notes --query" -alias recent="bm tool recent-activity" ``` -### Copilot Chat with MCP - -VS Code's Copilot Chat now supports MCP servers. You can add Basic Memory as an MCP server in your VS Code settings and use it directly through Copilot -- search your knowledge base, write notes, and build context without leaving the chat panel. See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for setup details. - ---- - -## Troubleshooting - -**Sync not picking up changes?** -Check sync status with `bm status` and verify file permissions in your project directory. - -**Search missing results?** -VS Code's built-in search works for text matches. For knowledge graph queries and semantic search, use the CLI: `bm tool search-notes --query "your query"`. - -**Cloud sync conflicts?** -Run `bm cloud bisync --name my-project --dry-run` to preview before syncing. See the [Cloud Sync Guide](/cloud/cloud-sync) for conflict resolution. - ---- - -## Next Steps - -:::card-group -::card ---- -title: Project Documentation -icon: i-lucide-folder-kanban -to: /how-to/project-documentation ---- -Learn effective project documentation strategies. -:: - -::card ---- -title: Note Taking -icon: i-lucide-edit -to: /how-to/note-taking ---- -Master note-taking techniques for development. -:: - -::card ---- -title: CLI Reference -icon: i-lucide-terminal -to: /reference/cli-reference ---- -Full Basic Memory command line reference. -:: - -::card ---- -title: Knowledge Format -icon: i-lucide-file-text -to: /concepts/knowledge-format ---- -Learn the semantic markdown format. -:: -::: +See [CLI basics](/local/cli-basics) and [Cloud Sync](/cloud/cloud-sync) for the underlying workflows. diff --git a/content/7.integrations/8.obsidian.md b/content/7.integrations/8.obsidian.md index 8cb2185..8e48203 100644 --- a/content/7.integrations/8.obsidian.md +++ b/content/7.integrations/8.obsidian.md @@ -1,155 +1,53 @@ --- title: Obsidian -description: Visualize your knowledge graph and edit notes directly in Obsidian. +description: Open a Basic Memory project as an Obsidian vault for direct Markdown editing and graph navigation. --- -Obsidian gives you a visual window into your Basic Memory knowledge base. Point it at your Basic Memory folder and you get graph view, backlinks, rich editing, and more — while your AI keeps working through MCP tools on the same files. +Basic Memory and Obsidian can work on the same Markdown folder. Basic Memory provides MCP tools, indexing, search, observations, relations, and schemas; Obsidian provides a local editor, backlinks, graph views, and its plugin ecosystem. -::note -For more information about Obsidian, visit the Obsidian home page. -:: +## Use an existing vault -## Cloud Sync Workflow - -Basic Memory Cloud enables a hybrid workflow: edit locally in Obsidian while your notes sync to the cloud. - -::note -Sync requires the Basic Memory CLI. See [Local Installation](/local/local-install) for installation steps. -:: - -::steps -### Sign Up for Basic Memory Cloud -Create your account at [app.basicmemory.com](https://app.basicmemory.com) - -### Enable Cloud Mode -Authenticate and enable cloud mode: +Point a local Basic Memory project at the vault: ```bash -bm cloud login +bm project add vault ~/Documents/MyVault +bm project default vault ``` -### Set Up Sync -Install rclone and configure credentials: +Ask a connected AI tool to create a note, then confirm that the Markdown file appears in Obsidian. -```bash -bm cloud setup -``` +## Create a new vault -This installs rclone automatically and configures your cloud credentials. +The default local Basic Memory project is stored at `~/basic-memory`. -### Create Project with Local Sync -Point Basic Memory to your Obsidian vault: +1. Install [Obsidian](https://obsidian.md). +2. Choose **Open folder as vault**. +3. Select `~/basic-memory`, or another configured project folder. -```bash -# If you have an existing vault -bm project add my-vault --local-path ~/path/to/obsidian-vault +## Use Obsidian with Cloud -# Or create a new project -bm project add notes --local-path ~/Documents/notes -``` +To edit a personal Cloud project in Obsidian, follow [Edit Locally and in the App](/cloud/edit-locally-and-in-the-app), then open the synchronized local folder as a vault. -### Establish Sync Baseline -Preview and run the initial sync: +Run: ```bash -# Preview first (recommended) -bm cloud bisync --name my-vault --resync --dry-run - -# If all looks good, establish baseline -bm cloud bisync --name my-vault --resync +bm cloud bisync --name ``` -Only use `--resync` for the first sync. +before and after switching between Obsidian and the web app. Two-way `bisync` is for personal workspaces; see [Cloud Sync](/cloud/cloud-sync) for team-workspace publishing. -### Open Your Vault in Obsidian -Open your local directory as a vault in Obsidian. You get full graph view, plugins, and editing. +## What maps cleanly -### Sync Changes -After editing in Obsidian or making changes via AI assistants in the cloud, sync both directions: +- `[[Wiki links]]` become Obsidian links and backlinks. +- Markdown headings, lists, code blocks, and frontmatter remain ordinary Markdown. +- Basic Memory observations and relations remain readable text. +- `.canvas` files created by Basic Memory can open in Obsidian Canvas. +- [Schemas](/concepts/schema-system) can keep notes consistent regardless of which editor created them. -```bash -bm cloud bisync --name my-vault -``` - -:: - -::note -**Bidirectional sync**: `bisync` keeps local and cloud in sync. Changes flow both ways, with newer files winning conflicts. For one-way sync and advanced options, see the [Cloud Sync Guide](/cloud/cloud-sync). -:: - ---- - -## Local Setup - -You can either use an existing Obsidian vault or create a new one for Basic Memory. - -### Option 1: Use an Existing Vault - -::steps -### Configure Basic Memory project -```bash -# Point Basic Memory to your existing vault -basic-memory project add main ~/path/to/your/obsidian-vault - -# Set it as default -basic-memory project default main -``` - -### Restart your AI client -Restart Claude Desktop (or your MCP client) for the changes to take effect. - -### Test the integration -Ask your AI to create a note — it will appear in your vault immediately. -:: - -### Option 2: Create a New Vault - -::steps -### Download Obsidian -Download and install [Obsidian](https://obsidian.md). - -### Create a new vault -Create a new vault pointing to your Basic Memory directory (`~/basic-memory` by default). - -### Enable core plugins -Enable Graph View, Backlinks, and Tags in Obsidian's settings. -:: - -## What You Get - -Because Basic Memory uses standard markdown with wiki links, Obsidian understands your knowledge base natively. - -- **Graph View** — See your entire knowledge network as an interactive graph. Each note is a node, and relations become connecting lines. Local graphs let you focus on one note's neighborhood. -- **Backlinks** — Every `[[wiki link]]` your AI creates is a clickable backlink in Obsidian. See all documents that reference the current note and navigate connections easily. -- **Tag Explorer** — Tags from observations and frontmatter show up in Obsidian's tag pane. Filter, browse, and combine tags to find what you need. -- **Live Updates** — Notes created by your AI (in Claude Desktop, Claude Code, or any MCP client) automatically appear in Obsidian since they share the same markdown files. No import or export needed. -- **Canvas** — Basic Memory's `canvas` tool generates Obsidian Canvas files. Ask your AI to visualize project structure or concept maps, then open the `.canvas` file in Obsidian to view and edit it. - -Use [schemas](/concepts/schema-system) to keep your notes consistent whether you're writing in Obsidian or through your AI. +Obsidian tags and graph views are useful views of the files, but Basic Memory's semantic index and relation model are separate from Obsidian's internal index. ## Troubleshooting -**Links not appearing in graph**: Make sure you're using wiki link syntax (`[[Note Title]]`) and that referenced documents exist in the vault. - -**Tags not showing up**: Use `#tag` syntax (no spaces — use hyphens instead). Ensure the tag panel is enabled in Obsidian settings. - -**Canvas files not opening**: Update to the latest Obsidian version and enable the Canvas core plugin. - -**Notes not syncing to cloud**: Run `bm cloud bisync --name ` after editing. See the [Cloud Sync Guide](/cloud/cloud-sync) for details. - -## Next Steps - -::card-group - ::card{title="Knowledge Format" to="/concepts/knowledge-format"} - Learn about observations, relations, and frontmatter. - :: - ::card{title="Schema System" to="/concepts/schema-system"} - Define consistent structures for your notes. - :: - ::card{title="Cloud Sync" to="/cloud/cloud-sync"} - Set up bidirectional sync between local and cloud. - :: - ::card{title="Claude Desktop" to="/integrations/claude-desktop"} - Connect your AI assistant to the same knowledge base. - :: -:: +- If a note is missing locally, run `bm status` and confirm the vault is the configured project path. +- If a Cloud edit is missing, run `bm cloud bisync --name `. +- If links do not resolve, confirm that the target Markdown note exists in the same vault. diff --git a/content/7.integrations/9.skills.md b/content/7.integrations/9.skills.md index 5e349db..dfc2122 100644 --- a/content/7.integrations/9.skills.md +++ b/content/7.integrations/9.skills.md @@ -3,7 +3,7 @@ title: Agent Skills description: Pre-built skills that teach AI agents how to use Basic Memory effectively. --- -Agent skills are markdown instruction files (`SKILL.md`) that teach AI coding agents best practices for using Basic Memory's MCP tools. Your agent already has access to the tools — skills teach it *when* and *how* to use them effectively, with examples and patterns for specific workflows. +Agent skills are markdown instruction files (`SKILL.md`) that teach AI coding agents best practices for using Basic Memory's MCP tools. Your agent already has access to the tools after you connect Basic Memory through MCP — skills teach it *when* and *how* to use them effectively, with examples and patterns for specific workflows. The skills are open source — browse the full collection on [GitHub](https://github.com/basicmachines-co/basic-memory-skills). ::tip @@ -22,6 +22,12 @@ Install all skills at once: npx skills add basicmachines-co/basic-memory-skills ``` +List available skills without installing: + +```bash +npx skills add basicmachines-co/basic-memory-skills --list +``` + Or install a single skill: ```bash @@ -66,6 +72,7 @@ For project-scoped skills, copy to `.claude/skills/` in your project root instea | **memory-metadata-search** | Query notes by custom frontmatter fields (equality, range, array filters) | | **memory-ingest** | Process transcripts, emails, and documents into structured notes | | **memory-research** | Web research synthesized into knowledge entities | +| **memory-literary-analysis** | Analyze a literary work into a graph of characters, themes, chapters, locations, symbols, and devices | ::note Start with **memory-notes** — it covers foundational note-writing patterns that all other skills build on. @@ -95,6 +102,8 @@ Start with **memory-notes** — it covers foundational note-writing patterns tha **memory-research** — Performs web research and synthesizes findings into Basic Memory entities. Use for researching companies, people, technologies, or any topic you want to capture in your knowledge base. +**memory-literary-analysis** — Analyzes a complete literary work into structured notes for characters, themes, chapters, locations, symbols, and literary devices. Use for book clubs, teaching resources, research projects, or long-form creative analysis. + --- ## Recommended Combinations @@ -111,7 +120,7 @@ Capture web research and process external documents into structured knowledge. :br Keep your knowledge base organized with regular reflection, defragmentation, and lifecycle management. -**Everything** — Install all 9 skills for comprehensive memory management across ingestion, organization, reflection, and lifecycle. +**Everything** — Install all 10 skills for comprehensive memory management across ingestion, organization, reflection, lifecycle, research, and literary analysis. ```bash npx skills add basicmachines-co/basic-memory-skills diff --git a/content/8.how-to/3.research-learning.md b/content/8.how-to/3.research-learning.md index 60d6b46..26a0894 100644 --- a/content/8.how-to/3.research-learning.md +++ b/content/8.how-to/3.research-learning.md @@ -58,7 +58,7 @@ The AI reads across your existing notes, identifies patterns, and produces a new ## Finding and Exploring Your Research -This is where Basic Memory v0.19 really shines. Once you've built up a collection of research notes, you need to find things -- and not just by exact title. +Once you've built up a collection of research notes, you need to find things by meaning as well as exact title. ### Semantic Search diff --git a/content/8.how-to/5.personal-knowledge.md b/content/8.how-to/5.personal-knowledge.md index 7573e08..66505c1 100644 --- a/content/8.how-to/5.personal-knowledge.md +++ b/content/8.how-to/5.personal-knowledge.md @@ -63,7 +63,7 @@ This kind of cross-domain insight is only possible because the AI has access to ### Semantic Search -Basic Memory v0.19 introduces semantic vector search, which means you can search by *meaning* rather than exact words. This is especially powerful for personal knowledge: +Semantic search lets you search by *meaning* rather than exact words. This is especially powerful for personal knowledge: > "What patterns do I notice about what energizes me?" @@ -87,7 +87,7 @@ Combining semantic and metadata search gives you powerful ways to review and ana ## Keeping Things Organized with Schemas -Schemas are a v0.19 feature that let you define consistent structure for different kinds of notes. For personal knowledge management, this means your goals always have the same fields, your reflections follow the same format, and your weekly reviews are easy to compare. +Schemas let you define consistent structure for different kinds of notes. For personal knowledge management, this means your goals can use the same fields, your reflections can follow the same format, and your weekly reviews are easier to compare. > "Create a schema for goal tracking with fields for status, target date, progress notes, and related life domain." @@ -147,7 +147,7 @@ Personal knowledge is, well, personal. Basic Memory is designed with this in min **Local-first by default** — Your notes live as markdown files on your machine. Nothing leaves your computer unless you choose to sync it. -**Per-project routing** — With v0.19's per-project routing, you can keep personal notes in a local-only project while routing work projects to the cloud. Your journal entries and health notes stay on your laptop; your team documentation syncs to Basic Memory Cloud. Different projects, different rules. +**Per-project routing** — You can keep personal notes in a local-only project while routing work projects to Cloud. Your journal entries and health notes stay on your laptop; your team documentation can live in Basic Memory Cloud. Different projects, different rules. ```bash # Personal notes stay local diff --git a/content/9.reference/1.cli-reference.md b/content/9.reference/1.cli-reference.md index a926b1b..78a50d2 100644 --- a/content/9.reference/1.cli-reference.md +++ b/content/9.reference/1.cli-reference.md @@ -18,6 +18,7 @@ bm status bm status --verbose bm status --json bm status --project research +bm status --wait --timeout 60 ``` | Flag | Description | @@ -25,6 +26,8 @@ bm status --project research | `--project` | Target a specific project | | `--verbose`, `-v` | Show detailed file information | | `--json` | Machine-readable JSON output | +| `--wait` | Block until indexing is complete | +| `--timeout` | Maximum seconds to wait with `--wait` (default `30`) | | `--local` | Force local routing (ignore cloud mode) | | `--cloud` | Force cloud routing | @@ -79,6 +82,9 @@ Rebuild search indexes and/or vector embeddings without dropping the database. # Rebuild everything (search + embeddings) bm reindex +# Force a full filesystem scan and file reindex +bm reindex --full + # Rebuild only full-text search index bm reindex --search bm reindex -s @@ -95,9 +101,10 @@ bm reindex -p main |------|-------------| | `--search`, `-s` | Rebuild only the full-text search index | | `--embeddings`, `-e` | Rebuild only vector embeddings | +| `--full` | Force a full filesystem scan and file reindex instead of the default incremental scan | | `--project`, `-p` | Target a specific project (default: all projects) | -When neither `--search` nor `--embeddings` is specified, both are rebuilt. +When neither `--search` nor `--embeddings` is specified, both are rebuilt. By default, reindexing uses the incremental scan path; add `--full` when you need to bypass the scan watermark. ### `bm reset` @@ -318,32 +325,69 @@ bm cloud api-key create "my-laptop" `bm cloud api-key create` requires an active OAuth session. Run `bm cloud login` first. :: -### Setup and upload +### Upload files ```bash -bm cloud setup bm cloud upload ~/my-notes --project research --create-project +bm cloud upload ./notes --project work --dry-run +bm cloud upload ~/docs --project work --no-sync ``` -### Sync +| Flag | Description | +|------|-------------| +| `--project`, `-p` | Cloud project name | +| `--create-project`, `-c` | Create the cloud project if it does not exist | +| `--sync` / `--no-sync` | Reindex after upload (default `--sync`) | +| `--verbose`, `-v` | Show detailed upload output | +| `--no-gitignore` | Ignore `.gitignore` patterns (still respects `.bmignore`) | +| `--dry-run` | Preview files without uploading | + +### Sync and local copies ```bash -# One-way sync: local → cloud -bm cloud sync +# Set up rclone credentials for the default workspace +bm cloud setup -# Two-way sync: local ↔ cloud -bm cloud bisync +# Set up rclone credentials for a specific workspace +bm cloud setup --workspace acme -# Verify file integrity between local and cloud -bm cloud check +# Configure a local folder for an existing cloud project +bm cloud sync-setup research ~/Documents/research -# Clear bisync state -bm cloud bisync-reset +# Fetch cloud changes into the local folder (Team-safe) +bm cloud pull --name research +bm cloud pull --name research --dry-run +bm cloud pull --name research --workspace acme -# Configure local sync for an existing cloud project -bm cloud sync-setup research ~/Documents/research +# Upload local changes to cloud (Team-safe) +bm cloud push --name research +bm cloud push --name research --dry-run +bm cloud push --name research --on-conflict keep-local + +# Personal workspace mirror commands +bm cloud sync --name research +bm cloud bisync --name research --resync +bm cloud bisync --name research + +# Verify file integrity between local and cloud +bm cloud check --name research + +# Clear bisync state for a project +bm cloud bisync-reset research ``` +Use `pull` and `push` for shared team workspaces. They are additive, detect conflicts first, and do not propagate deletions. `sync` and `bisync` are mirror-style personal workspace commands. + +Common flags: + +| Command | Flags | +|---|---| +| `bm cloud pull` | `--name` / `--project`, `--workspace`, `--on-conflict`, `--dry-run`, `--verbose` | +| `bm cloud push` | `--name` / `--project`, `--workspace`, `--on-conflict`, `--dry-run`, `--verbose` | +| `bm cloud sync` | `--name` / `--project`, `--dry-run`, `--verbose` | +| `bm cloud bisync` | `--name` / `--project`, `--dry-run`, `--resync`, `--verbose` | +| `bm cloud check` | `--name` / `--project`, `--one-way` | + ### Snapshots ```bash @@ -512,6 +556,20 @@ bm tool read-note my-note --page 2 --page-size 5 | `--local` | Force local routing | | `--cloud` | Force cloud routing | +### `bm tool delete-note` + +```bash +bm tool delete-note "notes/old-note" +bm tool delete-note "archive/old-folder" --is-directory +``` + +| Flag | Description | +|------|-------------| +| `--is-directory` | Delete a directory instead of a single note | +| `--project` | Target project | +| `--local` | Force local routing | +| `--cloud` | Force cloud routing | + ### `bm tool edit-note` ```bash @@ -647,6 +705,6 @@ bm import memory-json /path/to/export.json - [Configuration](/reference/configuration) - [MCP Tools Reference](/reference/mcp-tools-reference) -- [Cloud Guide](/cloud/cloud-guide) +- [Cloud Overview](/cloud/cloud-guide) - [Schema System](/concepts/schema-system) - [Semantic Search](/concepts/semantic-search) diff --git a/content/9.reference/10.contact-support.md b/content/9.reference/10.contact-support.md new file mode 100644 index 0000000..9532a9a --- /dev/null +++ b/content/9.reference/10.contact-support.md @@ -0,0 +1,97 @@ +--- +title: Contact Support +description: Get help with Basic Memory Cloud accounts, billing, workspaces, private data, invitations, and product issues. +--- + +For private account, billing, or Cloud workspace help, email: + +```text +hello@basicmemory.com +``` + +Use email when the issue involves information that should not be posted publicly. + +--- + +## Email support for private issues + +Contact support when you need help with: + +- Account access or sign-in problems. +- Billing, subscriptions, seats, or checkout. +- Cloud workspace access, invitations, or team membership. +- Private projects, notes, or shared-note links. +- API keys, OAuth sessions, or suspected credential exposure. +- Product bugs that require private workspace context. + +::warning +Never post API keys, OAuth tokens, billing information, private notes, or invitation links in public support channels. +:: + +--- + +## What to include + +To help diagnose the problem, include: + +- The email address you use for Basic Memory Cloud. +- The workspace name, if relevant. +- What you expected to happen. +- What happened instead. +- The page, command, or AI client where the issue occurred. +- Screenshots or error text with secrets removed. + +For CLI issues, these commands are usually safe to include after checking for private paths or tokens: + +```bash +bm --version +bm status +bm project list +bm cloud status +``` + +Do not include full API keys, OAuth tokens, raw private notes, or billing details unless support specifically asks for them through a trusted channel. + +--- + +## Public help + +Use public channels for general questions, local open-source issues, and reproducible bugs that do not require private context: + +- [Basic Memory Discord](https://discord.gg/tyvKNccgqN) +- [GitHub issues](https://github.com/basicmachines-co/basic-memory/issues) + +Public channels are best for installation issues, local MCP configuration, feature requests, documentation problems, and open-source bug reports. + +--- + +## Related guides + +:::card-group +::card +--- +title: Troubleshooting +icon: i-lucide-life-buoy +to: /reference/troubleshooting +--- +Diagnose common Cloud, MCP, sync, local install, and search issues. +:: + +::card +--- +title: Teams +icon: i-lucide-users +to: /teams/about +--- +Understand workspaces, members, roles, seats, and invitations. +:: + +::card +--- +title: API Keys +icon: i-lucide-key +to: /cloud/api-keys +--- +Create and revoke Cloud API keys safely. +:: +::: diff --git a/content/9.reference/2.mcp-tools-reference.md b/content/9.reference/2.mcp-tools-reference.md index edd080b..2bfd34b 100644 --- a/content/9.reference/2.mcp-tools-reference.md +++ b/content/9.reference/2.mcp-tools-reference.md @@ -19,9 +19,11 @@ Most tools accept these optional parameters. They are **not** repeated in every | Parameter | Type | Default | Notes | |---|---|---|---| -| `project` | string | resolved via fallback | Constrained project env → explicit parameter → `default_project` config | -| `workspace` | string | — | Cloud workspace name or tenant ID | -| `output_format` | `"text"` or `"json"` | `"text"` | Machine-readable JSON output. `build_context` defaults to `"json"`; all other tools default to `"text"` | +| `project` | string | resolved via fallback | Project name. Constrained project env → explicit parameter → `default_project` config | +| `project_id` | string | — | Project external UUID from `list_memory_projects`. Prefer this when the same project name exists in more than one workspace | +| `output_format` | `"text"` or `"json"` | `"text"` | Machine-readable JSON output. `build_context` defaults to `"json"`; most other tools default to `"text"` | + +`workspace` is not a universal parameter. It appears on tools that create or delete cloud projects/workspaces. For ordinary note, search, and schema calls, use `project` or `project_id`. --- @@ -38,11 +40,13 @@ Create or update a markdown note. | `directory` | string | Yes | Relative folder path | | `tags` | list[string] or string | No | Comma-separated string accepted | | `note_type` | string | No | Default `note`. Sets the `type` frontmatter field (e.g., `person`, `meeting`, `decision`) | -| `metadata` | object | No | Extra frontmatter fields merged into the note's YAML header | -| `overwrite` | boolean | No | Default `false`. Must be `true` to replace an existing note. Without this, writing to an existing path returns an error. Set `write_note_overwrite_default: true` in config to change the default | +| `metadata` | object or JSON string | No | Extra frontmatter fields merged into the note's YAML header | +| `overwrite` | boolean | No | Default follows `write_note_overwrite_default` config. Pass `true` to replace an existing note | The `note_type` parameter controls the `type` field in frontmatter, which is used for schema resolution and filtering. The `metadata` parameter accepts any key-value pairs that get written directly into the note's frontmatter — useful for custom fields like `status`, `priority`, or `due_date`. +Aliases accepted for `directory`: `folder`, `dir`, and `path`. + ### `read_note` Read note content by title/permalink/memory URL. @@ -93,7 +97,7 @@ Read raw file content by path or permalink. Returns the file's raw bytes — use | Parameter | Type | Required | Notes | |---|---|---|---| -| `path` | string | Yes | File path, permalink, or `memory://...` URL | +| `path` | string | Yes | File path, permalink, or `memory://...` URL. Aliases: `file_path`, `filepath`, `file` | ### `view_note` @@ -102,8 +106,6 @@ Render a note as a formatted artifact for display in MCP clients. Returns the no | Parameter | Type | Required | Notes | |---|---|---|---| | `identifier` | string | Yes | Note title, permalink, or `memory://...` URL | -| `page` | integer | No | Pagination page number | -| `page_size` | integer | No | Results per page | --- @@ -119,10 +121,11 @@ Main search tool with text, vector, and hybrid modes plus structured filters. | `page` | integer | No | Default `1` | | `page_size` | integer | No | Default `10` | | `search_type` | string | No | Default `None` — resolves to `hybrid` when semantic search is enabled, `text` otherwise. Options: `text`, `title`, `permalink`, `vector`, `semantic`, `hybrid` | -| `note_types` | list[string] | No | Frontmatter type filter (e.g., `["person", "meeting"]`) | -| `entity_types` | list[string] | No | Result type filter: `entity`, `observation`, `relation` | +| `note_types` | list[string] or string | No | Case-insensitive frontmatter `type` filter (e.g., `["person", "meeting"]`). Aliases: `note_type`, `types` | +| `entity_types` | list[string] or string | No | Knowledge graph result filter: `entity`, `observation`, `relation`. Alias: `entity_type` | +| `categories` | list[string] or string | No | Observation category filter. Pair with `entity_types=["observation"]` | | `after_date` | string | No | Date/time filter (ISO format) | -| `metadata_filters` | object | No | Structured metadata filters | +| `metadata_filters` | object or JSON string | No | Structured metadata filters | | `tags` | list[string] | No | Tag filter shorthand | | `status` | string | No | Status shorthand | | `min_similarity` | float | No | Overrides global `semantic_min_similarity` threshold per query | @@ -131,7 +134,7 @@ Main search tool with text, vector, and hybrid modes plus structured filters. The `search_type` parameter controls the search strategy. `hybrid` is the default — it combines keyword and semantic search. `text` is keyword-only. `vector` and `semantic` are equivalent — pure meaning-based similarity. See [Semantic Search](/concepts/semantic-search) for details on each mode. ::note -**Parameter aliases.** `search_notes` accepts `q`, `search`, or `text` as aliases for `query`, so assistants can use the parameter name they reach for naturally. Search responses also include a result total for pagination. +**Parameter aliases.** `search_notes` accepts `q`, `search`, or `text` as aliases for `query`; `all_projects` for `search_all_projects`; `page_number` for `page`; and `limit` / `per_page` for `page_size`. Search responses also include a result total for pagination. :: ### `build_context` @@ -176,11 +179,11 @@ Recent activity in one project or cross-project discovery mode. When called with ### `list_memory_projects` -List projects and project stats. Returns name, path, default status, note count, and last sync time for each project. In cloud mode, this discovers projects across **every** accessible workspace, not just the current one — so a team's projects show up without switching workspaces first. +List projects and project stats. Returns name, path, default status, note count, external project ID, and sync/workspace metadata for each project. In cloud mode, this discovers projects across **every** accessible workspace, not just the current one — so a team's projects show up without switching workspaces first. | Parameter | Type | Required | Notes | |---|---|---|---| -| `workspace` | string | No | Limit results to a specific cloud workspace (name or tenant ID) | +| `output_format` | `"text"` or `"json"` | No | Use `"json"` when an agent needs exact `project_id` values for later tool calls | ### `create_memory_project` @@ -200,6 +203,7 @@ Remove a project from Basic Memory config. | Parameter | Type | Required | Notes | |---|---|---|---| | `project_name` | string | Yes | Name of the project to remove | +| `workspace` | string | No | Cloud workspace selector when deleting from a specific workspace | ### `list_directory` @@ -228,6 +232,37 @@ List available cloud workspaces. Returns workspace names and tenant IDs for the --- +## UI tools + +Some MCP clients can render embedded UI resources. Basic Memory exposes UI variants separately from the plain text/json tools so clients that do not support embedded UI can keep using the normal tools. + +### `search_notes_ui` + +Search notes and return an embedded search-results UI resource. + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `query` | string | Yes | Search query | +| `page` | integer | No | Default `1` | +| `page_size` | integer | No | Default `10` | +| `search_type` | string | No | Same search modes as `search_notes` | +| `note_types` | list[string] | No | Frontmatter type filter | +| `entity_types` | list[string] | No | Knowledge graph result filter | +| `after_date` | string | No | Date/time filter | +| `metadata_filters` | object | No | Structured metadata filters | +| `tags` | list[string] | No | Tag filter | +| `status` | string | No | Status filter | + +### `read_note_ui` + +Read a note and return an embedded note-preview UI resource. + +| Parameter | Type | Required | Notes | +|---|---|---|---| +| `identifier` | string | Yes | Note title, permalink, path, or `memory://...` URL | + +--- + ## Schema tools Tools for defining, validating, and evolving note structure. See [Schema System](/concepts/schema-system) for concepts and workflow. @@ -240,6 +275,7 @@ Validate notes against their schema. Pass `note_type` to validate all notes of a |---|---|---|---| | `note_type` | string | Conditional | Note type to validate (e.g., `person`). One of `note_type` or `identifier` required | | `identifier` | string | Conditional | Specific note path or permalink to validate | +| `output_format` | `"text"` or `"json"` | No | Machine-readable validation report | ### `schema_infer` @@ -249,6 +285,7 @@ Analyze existing notes of a type and suggest a schema based on common patterns. |---|---|---|---| | `note_type` | string | Yes | Note type to analyze (e.g., `person`) | | `threshold` | float | No | Minimum field frequency for inclusion (default `0.25`) | +| `output_format` | `"text"` or `"json"` | No | Machine-readable inference report | ### `schema_diff` @@ -257,6 +294,7 @@ Compare a schema definition against actual note usage to detect drift. | Parameter | Type | Required | Notes | |---|---|---|---| | `note_type` | string | Yes | Note type to compare (e.g., `person`) | +| `output_format` | `"text"` or `"json"` | No | Machine-readable drift report | --- diff --git a/content/9.reference/3.ai-assistant-guide.md b/content/9.reference/3.ai-assistant-guide.md index 6851187..122c163 100644 --- a/content/9.reference/3.ai-assistant-guide.md +++ b/content/9.reference/3.ai-assistant-guide.md @@ -1,974 +1,41 @@ --- title: AI Assistant Guide -description: Guide for AI assistants using Basic Memory through the Model Context Protocol (MCP). +description: Durable instructions for AI tools working with Basic Memory through MCP. --- -::note -This is a technical guide for developers and AI integrations. For an overview of how Basic Memory works, see [What is Basic Memory](/start-here/what-is-basic-memory). +Basic Memory exposes its current tools, schemas, and a condensed assistant guide through MCP. Prefer those live resources over copying a long tool manual into a system prompt. -This guide is for AI assistants using Basic Memory tools through MCP. For setup instructions, see [Getting Started](/start-here/getting-started). +## Recommended instructions -Download the [AI Assistant Guide](https://github.com/basicmachines-co/basic-memory/blob/main/docs/ai-assistant-guide-extended.md) and customize it to your own workflow. A [condensed version](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/resources/ai_assistant_guide.md) is available as an MCP Resource in Basic Memory. -:: +Add this short instruction to an AI tool that supports persistent project or system guidance: -::tip -**AI agents:** This documentation is available as clean markdown. Fetch `https://docs.basicmemory.com/llms.txt` for an index or `https://docs.basicmemory.com/llms-full.txt` for the complete docs. See [AI-Friendly Documentation](/reference/llms-txt) for details. -:: +```text +Use Basic Memory as our shared knowledge base. -This guide explains how to use Basic Memory tools effectively when working with users through the Model Context Protocol. - ---- - -## Overview - -Basic Memory creates a semantic knowledge graph from markdown files stored locally on the user's computer. Knowledge persists across sessions, enabling continuity in conversations and collaborative development. - -**Architecture:** -- **Plain-Text**: Markdown files as source of truth -- **SQLite Index**: Fast search and navigation -- **MCP Integration**: Tools for AI interaction -- **Semantic Graph**: Observations and relations create connections - -**Your role:** Help users build structured knowledge that outlasts any particular AI model or session. Focus on creating observations and relations that provide lasting value. - ---- - -## Project Management - -All tools require explicit project specification. No implicit project context is maintained between calls. - -### Discovery and Selection - -Start conversations by discovering available projects: - -```python -# List all projects -projects = await list_memory_projects() - -# Response includes: -# - name -# - path -# - is_default -# - note_count -# - last_synced -``` - -**Recommended workflow:** - -1. Call `list_memory_projects()` at conversation start -2. Identify active project from metadata -3. Ask user which project to use -4. Store choice for the session -5. Pass project parameter to all tool calls - -### Cross-Project Operations - -Some tools work across all projects when project parameter is omitted: - -```python -# Recent activity across all projects -activity = await recent_activity(timeframe="7d") - -# Recent activity for specific project -activity = await recent_activity(timeframe="7d", project="main") -``` - -Tools supporting cross-project mode: -- `recent_activity()` -- `list_memory_projects()` - ---- - -## Knowledge Graph Structure - -The knowledge graph consists of three core elements: entities, observations, and relations. - -### Entities - -Each markdown file represents an entity with: - -- **Title**: Unique identifier -- **Permalink**: Auto-generated from title -- **Frontmatter**: YAML metadata (tags, type, dates) -- **Observations**: Categorized facts -- **Relations**: Links to other entities - -**Note types** (set via the `type` frontmatter field): -- `note` - General knowledge (default) -- `person` - People and contacts -- `project` - Projects and initiatives -- `meeting` - Meeting notes -- `decision` - Documented decisions -- `spec` - Technical specifications - -### Observations - -Observations are categorized facts with optional tags. - -**Syntax:** `- [category] content #tag1 #tag2` - -**Common categories:** -- `[fact]` - Objective information -- `[idea]` - Thoughts and concepts -- `[decision]` - Choices made -- `[technique]` - Methods and approaches -- `[requirement]` - Needs and constraints -- `[problem]` - Issues identified -- `[solution]` - Resolutions -- `[insight]` - Key realizations - -**Examples:** - -```bash -## Observations -- [decision] Use JWT tokens for authentication #security -- [technique] Hash passwords with bcrypt before storage #best-practice -- [requirement] Support OAuth 2.0 providers #auth -- [fact] Session timeout set to 24 hours #configuration -``` - -### Relations - -Relations are directional links between entities. - -**Syntax:** `- relation_type [[Target Entity]]` - -**Common relation types:** -- `relates_to` - General connection -- `implements` - Implementation relationship -- `requires` - Dependency -- `extends` - Enhancement -- `part_of` - Hierarchical membership -- `contrasts_with` - Alternative approach -- `leads_to` - Sequential relationship -- `caused_by` - Causal relationship - -**Examples:** - -```bash -## Relations -- implements [[Authentication Spec v2]] -- requires [[User Database Schema]] -- extends [[Base Security Model]] -- part_of [[API Backend Services]] -- contrasts_with [[API Key Authentication]] -``` - -### Forward References - -Reference entities that don't exist yet - relations resolve automatically when targets are created: - -```python -# Create note with forward reference -await write_note( - title="API Implementation", - content="## Relations\n- implements [[API Specification]]", - directory="api", - project="main" -) -# Forward reference created - -# Later, create referenced entity -await write_note( - title="API Specification", - content="# API Specification\n...", - directory="specs", - project="main" -) -# Forward reference automatically resolved -``` - ---- - -## Core Tools - -### Writing Knowledge - -Create new notes: - -```python -await write_note( - title="Topic", - content="# Topic\n## Observations\n- [category] fact\n## Relations\n- relates_to [[Other]]", - directory="notes", - project="main" -) -``` - -**Parameters:** -- `title` (required) - Note title -- `content` (required) - Markdown content -- `directory` (required) - Destination folder -- `tags` (optional) - List of tags -- `note_type` (optional) - Note type (default: `note`) -- `metadata` (optional) - Extra frontmatter fields -- `overwrite` (optional) - Default `false`. Must be `true` to replace an existing note -- `project` (optional) - Uses `default_project` fallback when configured - -::warning -**`write_note` is non-destructive by default.** If a note already exists at the target path, the call returns an error instead of silently overwriting. This prevents accidental data loss. - -- To update an existing note incrementally, use `edit_note` -- To fully replace an existing note, pass `overwrite=True` -- Always search before writing to check whether the note already exists -:: - -### Reading Knowledge - -Read notes with knowledge graph context: - -```python -# By title -note = await read_note("Topic", project="main") - -# By folder and title -note = await read_note("specs/Authentication System", project="main") - -# By memory:// URL -note = await read_note("memory://specs/auth", project="main") -``` - -**Response includes:** -- Content -- Observations (categorized) -- Relations (typed, with targets) -- Metadata (dates, tags, type) - -### Searching - -Find notes across the knowledge base: - -```python -results = await search_notes( - query="authentication", - project="main", - page_size=10 -) -``` - -**Filter by note type:** - -```python -# Find all specs about authentication -specs = await search_notes( - query="authentication", - note_types=["spec"], - project="main" -) - -# Find all meeting notes and decisions -results = await search_notes( - note_types=["meeting", "decision"], - project="main" -) -``` - -**Filter by date:** - -```python -recent = await search_notes( - query="api", - after_date="2025-01-01", - project="main" -) -``` - -**Search by tags:** - -```python -# tag: shorthand in the query string -results = await search_notes(query="tag:security", project="main") -results = await search_notes(query="tag:coffee AND tag:brewing", project="main") - -# tags parameter shorthand -results = await search_notes(tags=["security"], project="main") -results = await search_notes(tags=["security", "oauth"], project="main") -``` - -**Search by frontmatter metadata:** - -The `query` parameter is optional — you can search purely by frontmatter fields. Use `metadata_filters` for structured queries against any frontmatter field, or convenience shorthands for common fields. - -```python -# Find all notes with a specific status -results = await search_notes( - metadata_filters={"status": "in-progress"}, - project="main" -) - -# Find high-priority items -results = await search_notes( - metadata_filters={"priority": {"$in": ["high", "critical"]}}, - project="main" -) - -# Filter by team -results = await search_notes( - metadata_filters={"team": "backend"}, - project="main" -) - -# Combine text search with metadata filters -results = await search_notes( - query="authentication", - metadata_filters={"status": "draft"}, - project="main" -) - -# Convenience shorthands for common fields -results = await search_notes(status="draft", project="main") -results = await search_notes(tags=["security"], project="main") -``` - -**Supported filter operators:** - -| Operator | Example | Meaning | -|----------|---------|---------| -| exact match | `{"status": "draft"}` | Field equals value | -| `$in` | `{"priority": {"$in": ["high", "critical"]}}` | Field is one of the values | -| `$contains` | `{"tags": {"$contains": "security"}}` | Array field contains value | - -**Semantic search:** - -Semantic search is enabled by default. `hybrid` mode (combining keyword and meaning-based retrieval) is the default search type — no opt-in needed. You can also use pure semantic search: - -```python -# Pure semantic similarity — finds related concepts even with different wording -results = await search_notes( - query="how to speed up the application", - search_type="vector", - project="main" -) - -# Hybrid — combines keyword precision with semantic recall (recommended for most queries) -results = await search_notes( - query="authentication security", - search_type="hybrid", - project="main" -) - -# Adjust similarity threshold for tighter or looser results -results = await search_notes( - query="error handling patterns", - search_type="hybrid", - min_similarity=0.7, - project="main" -) -``` - -**When to use which search mode:** -- `hybrid` (default) — General-purpose. Start here for most queries. -- `text` — You know the exact terms. Best for names, identifiers, boolean queries. -- `vector` — Conceptual discovery. The note may not contain your exact words. - -### Building Context - -Navigate the knowledge graph. `build_context` defaults to JSON output (unlike other tools which default to text). - -```python -context = await build_context( - url="memory://specs/auth", - project="main", - depth=2, - timeframe="1 week" -) -``` - -**Parameters:** -- `url` (required) - memory:// URL -- `depth` (optional) - Traversal depth (default: 1) -- `timeframe` (optional) - Time window (e.g., "7d", "1 week") -- `output_format` (optional) - Default `"json"`. Pass `"text"` for human-readable output -- `project` (optional) - Uses `default_project` fallback when configured - -**Depth control:** -- `depth=1` - Immediate connections only -- `depth=2` - Two levels of relations -- `depth=3+` - Comprehensive (may be slow) - -### Editing Notes - -Edit existing notes incrementally: - -```python -# Append content -await edit_note( - identifier="Topic", - operation="append", - content="\n## New Section\nContent here", - project="main" -) - -# Prepend content -await edit_note( - identifier="Topic", - operation="prepend", - content="## Update\nImportant note\n\n", - project="main" -) - -# Find and replace -await edit_note( - identifier="Topic", - operation="find_replace", - find_text="old text", - content="new text", - expected_replacements=1, - project="main" -) - -# Replace section -await edit_note( - identifier="Topic", - operation="replace_section", - section="## Status", - content="## Status\nUpdated status here", - project="main" -) -``` - -**Operations:** -- `append` - Add to end -- `prepend` - Add to beginning -- `find_replace` - Replace specific text -- `replace_section` - Replace markdown section - -### Moving Notes - -Organize notes by moving them between folders: - -```python -await move_note( - identifier="Note Title", - destination_path="archive/note-title.md", - project="main" -) -``` - -**Behavior:** -- Folders created automatically -- Database updated automatically -- Relations preserved -- Both `.md` extension and without work - ---- - -## memory:// URL Format - -Basic Memory uses special URLs to reference entities. Generated permalinks include the project slug by default, so most URLs you encounter will be project-prefixed. - -**By title:** -``` -memory://title -``` - -**By folder and title:** -``` -memory://folder/title -``` - -**Project-prefixed (default format):** -``` -memory://project-slug/folder/title -``` - -**By permalink:** -``` -memory://permalink -``` - -**All in folder:** -``` -memory://folder/* -``` - -Underscores converted to hyphens automatically - `memory://my_note` finds entity with permalink `my-note`. - ---- - -## Recording Conversations - -Capture conversations to enable long-term context and knowledge accumulation. - -### Permission and Transparency - -**Always ask before recording:** - -``` -AI: "Would you like me to save our discussion about API authentication - to Basic Memory? This helps us continue this conversation later." - -User: "Yes, please" - -AI: [Saves to Basic Memory] - "I've saved our discussion as 'API Authentication Discussion'." -``` - -**Principles:** -- Ask permission before saving -- Confirm after saving -- Explain what was saved -- Describe how it helps future conversations - -### What to Record - -**Good candidates:** - -1. **Decisions and Rationales** -2. **Important Discoveries** -3. **Action Items and Plans** -4. **Connected Topics** - -### Recording Patterns - -**Conversation summary:** - -```python -await write_note( - title=f"Conversation: {topic} - {date}", - content=f"""# Conversation: {topic} - -## Summary -{brief_summary} - -## Key Points -{key_points} - -## Observations -{categorized_observations} - -## Relations -{relevant_relations} -""", - directory="conversations", - tags=["conversation"], - project="main" -) -``` - -**Decision record:** - -```python -await write_note( - title=f"Decision: {decision_title}", - content=f"""# Decision: {decision_title} - -## Context -{why_decision_needed} - -## Decision -{what_was_decided} - -## Rationale -{reasoning} - -## Relations -{related_entities} -""", - directory="decisions", - note_type="decision", - project="main" -) -``` - ---- - -## Schemas - -Schemas define what a "good" note of a particular type should contain. They formalize observation categories and relation types so you can validate notes against a consistent structure. Schemas are optional — you can use Basic Memory without ever defining one — but they help maintain consistency as a knowledge base grows and give you a guide for creating well-structured notes. - -A schema is just a regular note with `type: schema` in frontmatter: - -```yaml ---- -title: Person -type: schema -entity: person -version: 1 -schema: - name: string, full legal name - role?: string, current job title - works_at?: Organization, primary employer - expertise?(array, areas of knowledge): string -settings: - validation: warn ---- -``` - -Fields without `?` are required. Fields with `?` are optional. Capitalized types like `Organization` indicate entity references (wiki-link relations). Array fields expect multiple observations of the same category. - -### Schema tools - -Three tools are available for working with schemas: - -- **`schema_infer`** — Analyze existing notes of a type and suggest a schema based on common patterns. Use this when the user wants to create a schema from their existing notes. -- **`schema_validate`** — Check notes against their schema. Pass `note_type` to validate all notes of a type, or `identifier` to validate a single note. -- **`schema_diff`** — Compare a schema against actual note usage to detect drift. Shows which fields are defined but unused, and which undeclared fields appear in practice. - -### Creating notes with schemas - -When a schema exists for a note type, use it as a creation guide: - -1. **Look up the schema** before creating a note of a known type: - -```python -# Check what fields a "person" note should have -schema = await schema_infer(note_type="person") -``` - -2. **Create the note** following the schema's field definitions: - -```python -await write_note( - title="Grace Hopper", - content="""# Grace Hopper - -## Observations -- [name] Grace Hopper -- [role] Computer Scientist and Navy Admiral -- [expertise] Compiler design -- [expertise] Programming languages - -## Relations -- works_at [[US Navy]] -- works_at [[Harvard University]] -""", - directory="people", - note_type="person", - metadata={"status": "historical"}, - project="main" -) -``` - -3. **Validate** after creation to confirm conformance: - -```python -result = await schema_validate(identifier="people/grace-hopper", project="main") -``` - -### Discovering and evolving schemas - -Users may ask you to help create or refine schemas. The typical workflow: - -```python -# 1. Infer a schema from existing notes -schema = await schema_infer(note_type="meeting", project="main") - -# 2. Review the suggested schema with the user, then write it -await write_note( - title="Meeting", - content="...", # schema frontmatter + description - directory="schemas", - note_type="schema", - project="main" -) - -# 3. Validate existing notes against the new schema -results = await schema_validate(note_type="meeting", project="main") - -# 4. Later, check for drift as note patterns evolve -drift = await schema_diff(note_type="meeting", project="main") -``` - -### Using `note_type` and `metadata` - -The `note_type` parameter sets the `type` frontmatter field, which controls schema resolution and search filtering. Use it whenever creating notes of a specific type: - -```python -await write_note( - title="Sprint Planning 2026-02-15", - content="...", - directory="meetings", - note_type="meeting", - metadata={"sprint": 12, "team": "backend"}, - project="main" -) -``` - -The `metadata` parameter accepts any key-value pairs that get merged into the note's frontmatter. Use it for custom fields like `status`, `priority`, `due_date`, or `team` — these become searchable via `metadata_filters` in `search_notes`. - -See the full [Schema System](/concepts/schema-system) guide for syntax details and validation modes. - ---- - -## Best Practices - -### 1. Project Discovery - -Always start with discovery: - -```python -# First action in conversation -projects = await list_memory_projects() - -# Ask user which to use -# Store for session -# Use consistently -``` - -### 2. Rich Knowledge Graphs - -**Every note should have:** -- Clear, descriptive title -- 3-5 observations minimum -- 2-3 relations minimum -- Appropriate categories and tags - -**Good structure:** - -```bash ---- -title: Clear Descriptive Title -tags: [relevant, tags] -type: note ---- - -# Title - -## Context -Brief background - -## Observations -- [category] Specific fact #tag1 #tag2 -- [category] Another fact #tag3 -- [category] Third fact #tag4 - -## Relations -- relation_type [[Related Entity 1]] -- relation_type [[Related Entity 2]] -``` - -### 3. Search Before Creating - -Always search first to avoid duplicates. `write_note` returns an error if a note already exists at the target path, so searching first prevents failed writes and lets you choose the right tool: - -```python -# Before writing new note -existing = await search_notes( - query="topic name", - project="main" -) - -if existing["total"] > 0: - # Update existing with edit_note - await edit_note( - identifier=existing["results"][0]["permalink"], - operation="append", - content=new_information, - project="main" - ) -else: - # Create new - await write_note(...) -``` - -### 4. Exact Entity Titles in Relations - -Use exact titles when creating relations: - -```python -# Search for exact title -results = await search_notes(query="Authentication System", project="main") -exact_title = results["results"][0]["title"] - -# Use in relation -content = f"## Relations\n- relates_to [[{exact_title}]]" -``` - -### 5. Meaningful Categories and Relations - -**Use semantic categories:** -- `[decision]` for choices made -- `[fact]` for objective information -- `[technique]` for methods -- `[requirement]` for needs -- `[insight]` for realizations - -**Use specific relation types:** -- `implements` for implementation -- `requires` for dependencies -- `part_of` for hierarchy -- `extends` for enhancement -- `contrasts_with` for alternatives - -**Avoid generic:** Don't overuse `relates_to` - be specific about relationships. - -### 6. Progressive Elaboration - -Build knowledge over time: - -```python -# Session 1: Create foundation -await write_note( - title="Topic", - content="Basic structure with initial observations", - directory="notes", - project="main" -) - -# Session 2: Add details -await edit_note( - identifier="Topic", - operation="append", - content="Additional observations", - project="main" -) - -# Session 3: Add relations -await edit_note( - identifier="Topic", - operation="append", - content="Relations to related topics", - project="main" -) +Search before answering when prior decisions, research, documents, workflows, or +project context may matter. Read the relevant notes before changing them. Save +durable knowledge when it will be useful beyond this conversation, and preserve +the user's existing organization and wording. Confirm the project or workspace +when the destination is ambiguous. ``` -### 7. Consistent Organization +Adapt the wording to your workflow. Avoid instructing the tool to save every message; Basic Memory is most useful for durable knowledge, not undifferentiated transcripts. -**Folder structure:** -- `specs/` - Specifications -- `decisions/` - Decision records -- `meetings/` - Meeting notes -- `conversations/` - AI conversations -- `implementations/` - Code/implementations -- `docs/` - Documentation +## Tool-use pattern -### 8. Confirm Destructive Actions - -Always ask before calling `delete_note` or `move_note` on folders. - -::note -When in doubt, create a snapshot (Cloud) or suggest a backup (Local). -:: - ---- +1. Discover available projects when the active project is unclear. +2. Search for related notes before creating duplicates. +3. Read the relevant note before editing it. +4. Prefer targeted edits over replacing an entire note. +5. Verify important writes by reading the result. +6. Ask before deleting, moving many files, or changing project boundaries. -## Error Handling +## Current technical guidance -### Note Already Exists +- [MCP tools reference](/reference/mcp-tools-reference) +- [Knowledge format](/concepts/knowledge-format) +- [Schemas](/concepts/schema-system) +- [AI-friendly documentation](/reference/llms-txt) +- [Extended assistant guide on GitHub](https://github.com/basicmachines-co/basic-memory/blob/main/docs/ai-assistant-guide-extended.md) -The most common error. `write_note` returns an error when a note already exists at the target path. This is intentional — it prevents accidental overwrites. - -**Solution:** -```python -# Option 1: Update the existing note incrementally -await edit_note( - identifier="existing-note-path", - operation="append", - content="New content to add", - project="main" -) - -# Option 2: Explicitly replace the note -await write_note( - title="Topic", - content="Completely new content", - directory="notes", - overwrite=True, - project="main" -) -``` - -### Missing Project Parameter - -**Solution:** -```python -try: - results = await search_notes(query="test") -except: - projects = await list_memory_projects() - # Ask user which to use - results = await search_notes(query="test", project="main") -``` - -### Entity Not Found - -**Solution:** -```python -try: - note = await read_note("Nonexistent Note", project="main") -except: - results = await search_notes(query="Note", project="main") - # Suggest alternatives to user -``` - -### Forward References - -**Not an error:** Forward references resolve automatically when targets are created. No action needed. - ---- - -## Tool Reference - -### Content Management - -| Tool | Purpose | -|------|---------| -| `write_note` | Create new markdown notes (errors on existing path unless `overwrite=True`) | -| `read_note` | Read notes with knowledge graph context | -| `edit_note` | Edit notes incrementally | -| `move_note` | Move notes to new locations | -| `delete_note` | Delete notes from knowledge base | -| `view_note` | View notes as formatted artifacts | -| `read_content` | Read raw file content | - -### Knowledge Graph Navigation - -| Tool | Purpose | -|------|---------| -| `build_context` | Navigate knowledge graph | -| `recent_activity` | Get recent changes | -| `list_directory` | Browse directory contents | - -### Search & Discovery - -| Tool | Purpose | -|------|---------| -| `search_notes` | Search across knowledge base (text, vector, hybrid modes) | - -### Schema Tools - -| Tool | Purpose | -|------|---------| -| `schema_validate` | Validate notes against schema definitions | -| `schema_infer` | Analyze notes and suggest schema patterns | -| `schema_diff` | Detect drift between schema and actual usage | - -### Project Management - -| Tool | Purpose | -|------|---------| -| `list_memory_projects` | List all available projects | -| `create_memory_project` | Create new project | -| `delete_project` | Delete project from configuration | -| `list_workspaces` | List available cloud workspaces | - -### Visualization - -| Tool | Purpose | -|------|---------| -| `canvas` | Create Obsidian canvas | - ---- - -## Next Steps - -:::card-group -::card ---- -title: MCP Tools Reference -icon: i-lucide-wrench -to: /reference/mcp-tools-reference ---- -Complete tool documentation with parameters and examples. -:: - -::card ---- -title: Knowledge Format -icon: i-lucide-file-text -to: /concepts/knowledge-format ---- -Understanding the note structure and semantic patterns. -:: -::: +The GitHub guide follows the open-source implementation. The hosted MCP server may expose additional Cloud behavior governed by the authenticated user's workspace permissions. diff --git a/content/9.reference/4.technical-information.md b/content/9.reference/4.technical-information.md index ce9aab9..b7181ce 100644 --- a/content/9.reference/4.technical-information.md +++ b/content/9.reference/4.technical-information.md @@ -1,327 +1,47 @@ --- title: Technical Information -description: Technical details about Basic Memory implementation, architecture, licensing, and Model Context Protocol integration +description: Architecture, storage model, protocol, licensing, and source links for Basic Memory. --- -::note -This page describes the architecture of the open-source [Basic Memory](https://github.com/basicmachines-co/basic-memory) project. [Basic Memory Cloud](/cloud/cloud-guide) builds on this foundation with hosted infrastructure and additional features. -:: +## Open-source architecture -## Architecture +The open-source Basic Memory project is file-first: -Basic Memory consists of: +1. Markdown files are the durable source of truth. +2. A local database indexes files for search and graph traversal. +3. A file watcher updates the index as files change. +4. The CLI and MCP server operate on the same projects and index. -- **Core Knowledge Engine** — Parses and indexes Markdown files -- **Database** — Provides fast querying and search -- **MCP Server** — Implements the Model Context Protocol -- **CLI Tools** — Command-line utilities for management -- **File Watcher** — Monitors file changes and indexes the database +Deleting the index does not delete the Markdown source files. Rebuilding an index can still be expensive for a large project, so keep normal backups of the files. -::note - The system follows a **file-first architecture** where all knowledge is represented in standard Markdown files and the database serves as a secondary index. -:: +## Cloud architecture -## Model Context Protocol (MCP) +Basic Memory Cloud provides a hosted web app, remote MCP server, authentication, workspaces, collaboration, managed indexing, sharing, file history, and snapshots. Cloud projects are governed by workspace and project permissions. -Basic Memory implements the [Model Context Protocol](https://github.com/modelcontextprotocol/spec), an open standard for enabling AI models to access external tools: +See [Basic Memory Cloud](/cloud/cloud-guide) for user-facing behavior. -- **Standardized Interface** — Common protocol for tool integration -- **Tool Registration** — Basic Memory registers as a tool provider -- **Asynchronous Communication** — Enables efficient interaction with AI models -- **Standardized Schema** — Structured data exchange format +## Model Context Protocol -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. +Basic Memory exposes tools and resources through the [Model Context Protocol](https://modelcontextprotocol.io). Supported clients can search, read, write, edit, organize, and build context from Basic Memory without a client-specific API. -## Licensing +See the [MCP tools reference](/reference/mcp-tools-reference) for the current tool surface. -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): +## Data model -- **Free Software** — You can use, study, share, and modify the software -- **Copyleft** — Derivative works must be distributed under the same license -- **Network Use** — Network users must be able to receive the source code -- **Commercial Use** — Allowed, subject to license requirements +- **Projects** define knowledge boundaries and storage locations. +- **Notes** are Markdown documents. +- **Observations** are categorized statements extracted from note content. +- **Relations** connect notes and concepts. +- **Schemas** define reusable structure and validation rules. +- **Indexes** make text, metadata, semantic, and graph queries fast. -::note - The AGPL license ensures Basic Memory remains open source while protecting against proprietary forks. -:: +## License and source -## Source Code +The open-source project is licensed under [AGPL-3.0](https://github.com/basicmachines-co/basic-memory/blob/main/LICENSE). -Basic Memory is developed as an open-source project: +- [Source repository](https://github.com/basicmachines-co/basic-memory) +- [Issue tracker](https://github.com/basicmachines-co/basic-memory/issues) +- [Contributing guide](https://github.com/basicmachines-co/basic-memory/blob/main/CONTRIBUTING.md) +- [Documentation source](https://github.com/basicmachines-co/docs.basicmemory.com) -- **GitHub Repository** — [https://github.com/basicmachines-co/basic-memory](https://github.com/basicmachines-co/basic-memory) -- **Issue Tracker** — Report bugs and request features on GitHub -- **Contributions** — Pull requests are welcome following the contributing guidelines -- **Documentation** — Source for this documentation is also available in the repository - -## Data Storage and Privacy - -Basic Memory is designed with privacy as a core principle: - -::note - **Privacy-First Design:** - - **Local-First**: All data remains on your machine - - **No Cloud Dependency**: No remote servers or accounts required - - **Telemetry**: Optional and disabled by default - - **Standard Formats**: All data is stored in standard file formats you control -:: - -## Implementation Details - -Knowledge in Basic Memory is organized as a semantic graph: - -::steps -### Entities -Distinct concepts represented by Markdown documents - -### Observations -Categorized facts and information about entities - -### Relations -Connections between entities that form the knowledge graph - -:: - -This structure emerges from simple text patterns in standard Markdown: - -### Example Markdown Input - -```bash ---- -title: Coffee Brewing Methods -type: note -permalink: coffee/coffee-brewing-methods -tags: -- '#coffee' -- '#brewing' -- '#methods' -- '#demo' ---- - -# Coffee Brewing Methods - -An exploration of different coffee brewing techniques, their characteristics, and how they affect flavor extraction. - -## Overview - -Coffee brewing is both an art and a science. Different brewing methods extract different compounds from coffee beans, -resulting in unique flavor profiles, body, and mouthfeel. The key variables in any brewing method are: - -- Grind size -- Water temperature -- Brew time -- Coffee-to-water ratio -- Agitation/turbulence - -## Observations - -- [principle] Coffee extraction follows a predictable pattern: acids extract first, then sugars, then bitter compounds -#extraction -- [method] Pour over methods generally produce cleaner, brighter cups with more distinct flavor notes #clarity - -## Relations - -- requires [[Proper Grinding Technique]] -- affects [[Flavor Extraction]] -``` - -### Parsed JSON Structure - -### Resulting JSON Entity Structure -```json -{ - "entities": [ - { - "permalink": "coffee/coffee-brewing-methods", - "title": "Coffee Brewing Methods", - "file_path": "Coffee Notes/Coffee Brewing Methods.md", - "entity_type": "note", - "entity_metadata": { - "title": "Coffee Brewing Methods", - "type": "note", - "permalink": "coffee/coffee-brewing-methods", - "tags": "['#coffee', '#brewing', '#methods', '#demo']" - }, - "checksum": "bfa32a0f23fa124b53f0694c344d2788b0ce50bd090b55b6d738401d2a349e4c", - "content_type": "text/markdown", - "observations": [ - { - "category": "principle", - "content": "Coffee extraction follows a predictable pattern: acids extract first, then sugars, then bitter compounds #extraction", - "tags": [ - "extraction" - ], - "permalink": "coffee/coffee-brewing-methods/observations/principle/coffee-extraction-follows-a-predictable-pattern-acids-extract-first-then-sugars-then-bitter-compounds-extraction" - }, - { - "category": "method", - "content": "Pour over methods generally produce cleaner, brighter cups with more distinct flavor notes #clarity", - "tags": [ - "clarity" - ], - "permalink": "coffee/coffee-brewing-methods/observations/method/pour-over-methods-generally-produce-cleaner-brighter-cups-with-more-distinct-flavor-notes-clarity" - } - ], - "relations": [ - { - "from_id": "coffee/coffee-bean-origins", - "to_id": "coffee/coffee-brewing-methods", - "relation_type": "pairs_with", - "permalink": "coffee/coffee-bean-origins/pairs-with/coffee/coffee-brewing-methods", - "to_name": "Coffee Brewing Methods" - }, - { - "from_id": "coffee/flavor-extraction", - "to_id": "coffee/coffee-brewing-methods", - "relation_type": "affected_by", - "permalink": "coffee/flavor-extraction/affected-by/coffee/coffee-brewing-methods", - "to_name": "Coffee Brewing Methods" - } - ], - "created_at": "2025-03-06T14:01:23.445071", - "updated_at": "2025-03-06T13:34:48.563606" - } - ] -} -``` - -Basic Memory understands how to build context via its semantic graph. - -### Entity Model - -Basic Memory's core data model consists of: - -- **Entities** — Documents in your knowledge base -- **Observations** — Facts or statements about entities -- **Relations** — Connections between entities -- **Tags** — Additional categorization for entities and observations - -The system parses Markdown files to extract this structured information while preserving the human-readable format. - -### Files as Source of Truth - -Plain Markdown files store all knowledge, making it accessible with any text editor and easy to version with git. - -::mermaid ---- -code: | - flowchart TD - User((User)) <--> |Conversation| Claude["Claude or other LLM"] - Claude <-->|API Calls| BMCP["Basic Memory MCP Server"] - - KnowledgeFiles["Markdown Files - Source of Truth"] - KnowledgeIndex[(Knowledge Graph Index)] - - BMCP <-->|"write_note() read_note()"| KnowledgeFiles - BMCP <-->|"search_notes() build_context()"| KnowledgeIndex - KnowledgeFiles <-.->|Sync Process| KnowledgeIndex - KnowledgeFiles <-->|Direct Editing| Editors((Text Editors & Git)) - - User -.->|"Complete control, Privacy preserved"| KnowledgeFiles ---- -:: - -### Database - -The database maintains the knowledge graph topology for fast queries and semantic traversal. It contains: - -- **Knowledge Graph Schema** — Database tables for the knowledge graph structure -- **Search Index** — Full text search index across the knowledge base - -### Sync Process - -The sync process: - -::steps -### Detect Changes -Detects changes to files in the knowledge directory - -### Parse Files -Parses modified files to extract structured data - -### Update Database -Updates the database with changes - -### Resolve References -Resolves forward references when new entities are created - -### Update Search Index -Updates the search index for fast querying - -:: - -### Search Engine - -The search functionality: - -- **Hybrid Search** — Uses a combination of full-text search and semantic matching -- **Comprehensive Indexing** — Indexes observations, relations, and content -- **Pattern Matching** — Supports wildcards and pattern matching in memory:// URLs -- **Graph Traversal** — Traverses the knowledge graph to follow relationships - -::note - Results are ranked by relevance to the query using advanced scoring algorithms. -:: - -## System Architecture - -### Component Interaction - -The Basic Memory system is built with a modular architecture: - -::tabs - ::div{label="File Layer"} - **Markdown Files** — The foundation of your knowledge base - - - **Human-Readable** — Edit with any text editor - - **Version Control Friendly** — Works seamlessly with Git - - **Standard Format** — Plain Markdown with YAML frontmatter - - **Complete Ownership** — Your files, your control - :: - - ::div{label="Processing Layer"} - **Sync Service** — Keeps everything in sync - - - **File Monitoring** — Watches for changes in real-time - - **Markdown Parsing** — Extracts structure from content - - **Entity Extraction** — Identifies entities, observations, relations - - **Database Updates** — Maintains the knowledge graph index - :: - - ::div{label="Storage Layer"} - **Database** — Fast indexing - - - **Fast Querying** — Optimized for knowledge graph queries - - **Full-Text Search** — Search across all content - - **Relationship Mapping** — Tracks entity connections - - **Metadata Storage** — Stores parsed entity information - :: - - ::div{label="Interface Layer"} - **MCP Server** — AI integration layer - - - **Standardized Tools** — 17 MCP tools for AI access - - **Real-Time Access** — Live knowledge base queries - - **Secure Auth** — JWT-based authentication for cloud - - **Cross-Platform** — Works with Claude, VS Code, Cursor - :: -:: - -### Performance Characteristics - -- **Local Performance** — All operations are local with no network latency -- **Scalability** — Handles knowledge bases with thousands of documents -- **Resource Efficiency** — Minimal CPU and memory footprint - -## Development Philosophy - -Basic Memory embodies several key principles: - -::note - **Core Principles:** - - **Local-First**: Your data stays on your machine - - **Open Standards**: Uses standard formats and protocols - - **Human-Readable**: Everything is accessible without special tools - - **AI-Native**: Designed specifically for AI collaboration - - **Privacy-Preserving**: No data collection or tracking -:: +Review the license itself for legal requirements; this page is not legal advice. diff --git a/content/9.reference/5.troubleshooting.md b/content/9.reference/5.troubleshooting.md index 1c25a55..e099674 100644 --- a/content/9.reference/5.troubleshooting.md +++ b/content/9.reference/5.troubleshooting.md @@ -1,481 +1,517 @@ --- title: Troubleshooting -description: Common issues and solutions for Basic Memory. +description: Diagnose Basic Memory Cloud, local installs, MCP connections, sync, search, and project issues. --- -This guide covers common issues and their solutions. For live help, visit our [Discord server](https://discord.gg/tyvKNccgqN). +Start with the surface you are using: + +| If you are using... | Start here | +|---|---| +| Basic Memory Cloud in an AI tool | [Cloud MCP connection](#cloud-mcp-connection) | +| Basic Memory Cloud in the web app | [Cloud app issues](#cloud-app-issues) | +| Local open-source Basic Memory | [Local install and MCP](#local-install-and-mcp) | +| Cloud Sync or local/cloud routing | [Sync and routing](#sync-and-routing) | +| Search, notes, or project lookup | [Search and content](#search-and-content) | + +For private account, billing, workspace, invitation, or Cloud data issues, email support from [Contact Support](/reference/contact-support). For public help, visit the [Basic Memory Discord](https://discord.gg/tyvKNccgqN) or open a [GitHub issue](https://github.com/basicmachines-co/basic-memory/issues). --- -## MCP Connection Issues +## Quick checks -### Claude Says "No Basic Memory Tools Available" +Run these before digging deeper: -**Problem:** Claude Desktop can't find Basic Memory tools. +```bash +bm --version +bm status +bm project list +``` -**Solutions:** +If something feels inconsistent in a local project, run: -1. **Check absolute paths** - Use complete paths in Claude Desktop config: - ```json - { - "mcpServers": { - "basic-memory": { - "command": "/Users/yourusername/.local/bin/uvx", - "args": ["basic-memory", "mcp"] - } - } - } - ``` - Find your path with: `which uvx` +```bash +bm doctor +``` -2. **Verify installation**: - ```bash - basic-memory --version - ``` +If you are using Cloud from the CLI: -3. **Restart applications** - Close and reopen both Terminal and Claude Desktop +```bash +bm cloud status +``` -4. **Check sync status**: - ```bash - basic-memory status - ``` +## Cloud MCP connection -### ENOENT Error +Cloud MCP uses the hosted endpoint: -**Problem:** Claude Desktop cannot find the `uv` installation. +```text +https://cloud.basicmemory.com/mcp +``` -**Solution:** -1. Find the absolute path: `which uvx` -2. Update Claude Desktop config with the full path -3. Restart Claude Desktop +Use this URL when a client asks for a remote MCP server, custom connector, custom app, or MCP endpoint. -### MCP Endpoint Connection Fails (Cloud) +### The AI tool cannot connect -**Problem:** Remote MCP connection not working. +Check: -**Solutions:** +1. The endpoint is exactly `https://cloud.basicmemory.com/mcp`. +2. You completed the Basic Memory authorization flow. +3. You are signed in to the same Basic Memory account that owns or has access to the workspace. +4. Your client supports remote MCP or custom MCP connectors. +5. The connector/app is enabled in the current chat or project, if the client requires per-chat enablement. -1. **Verify endpoint URL**: `https://cloud.basicmemory.com/mcp` +Then remove and re-add the connector from the AI client. -2. **Re-authenticate**: - ```bash - bm cloud logout - bm cloud login - ``` +### The tool connects but cannot see projects -3. **Check subscription status**: - ```bash - bm cloud status - ``` +Ask the assistant: -4. **Restart your MCP client** (Claude Desktop, VS Code, etc.) +```text +List my Basic Memory projects. +``` ---- +If it returns no projects: -## Cloud Issues +- Open [app.basicmemory.com](https://app.basicmemory.com) and confirm you can see the workspace and projects there. +- If you were invited to a team workspace, confirm you accepted the invitation with the invited email address. +- Switch to the correct workspace in the Basic Memory web app. +- Re-authorize the MCP connector so the client refreshes access. -### Cloud Mode Not Working +### Claude does not use Basic Memory -**Problem:** CLI commands not working in cloud mode. +Claude custom connectors may need to be enabled in each conversation. -**Solution:** -```bash -bm cloud logout -bm cloud login -``` +Open the **+** menu beside the message box, choose **Connectors**, and enable Basic Memory. On managed Claude plans, an organization owner may need to approve the connector first. -### Subscription Required Error +See [Claude](/integrations/claude-desktop). -**Problem:** "Active subscription required" message. +### ChatGPT does not use Basic Memory -**Solution:** -1. Visit [basicmemory.com/subscribe](https://basicmemory.com/subscribe) -2. Complete subscription -3. Run `bm cloud login` again +ChatGPT custom apps may need to be invited into a chat from the message composer or tools menu. If developer mode or custom apps are unavailable, your ChatGPT plan, workspace role, or administrator policy may not allow them. -Access is immediate when subscription becomes active. +See [ChatGPT](/integrations/chatgpt). -### Authentication Failed or Invalid Token +### Codex, Cursor, VS Code, or Gemini cannot connect -**Problem:** Token expired or invalid. +Check the integration page for your client: -**Solution:** -```bash -bm cloud logout -bm cloud login -``` +- [Codex](/integrations/codex) +- [Cursor](/integrations/cursor) +- [VS Code](/integrations/vscode) +- [Gemini CLI](/integrations/gemini) + +The durable rule: use the Cloud endpoint for remote MCP, and use `uvx basic-memory mcp` only for local MCP. --- -## Sync Issues +## Cloud app issues + +### You are in the wrong workspace + +Use the workspace switcher in the Basic Memory web app. Personal, organization, and invited workspaces are separate. Projects and permissions are scoped to the selected workspace. + +If you expected a team project: -### Changes Not Syncing +- Confirm the invite was accepted. +- Confirm you are signed in with the invited email. +- Ask an owner to check your role and project access in **Settings → Teams**. -**Problem:** File changes not appearing in knowledge base. +### Subscription or seat problem -**Solutions:** +Workspace access depends on the subscription and seat allocation. -1. **Check sync status**: - ```bash - basic-memory status - ``` +- Owners manage seats and billing in **Settings → Billing**. +- Pending invitations do not use a seat until accepted. +- Active members use seats. +- Deactivated members lose access and free a seat. -2. **Verify file permissions** - Ensure Basic Memory can read/write to the project directory +See [Share Basic Memory With Your Team](/teams/about). -3. **Check .gitignore patterns** - Files matching ignore patterns are skipped +### API key authentication failed -4. **Reset the database**: - ```bash - basic-memory reset - ``` - ::warning - This re-indexes all files. May take time for large knowledge bases. - :: +API keys are useful for CLI, automation, and MCP clients that support bearer tokens. -### Sync In Progress +If a key stops working: -**Problem:** Operations failing with "sync in progress" message. +1. Check whether it was revoked in **Settings → API Keys**. +2. Create a new key if needed. +3. Update the environment variable, CLI config, or client header that uses the key. + +For CLI routing: -**Solution:** Wait for sync to complete, then retry. Check progress with: ```bash -basic-memory status +bm cloud api-key save bmc_your_key_here +bm cloud status ``` -### Cloud Sync Issues +See [API Keys](/cloud/api-keys). -**Problem:** Bisync not working. +--- -**Solutions:** +## Local install and MCP -1. **Re-run setup**: - ```bash - bm cloud setup - ``` +Local mode uses the open-source CLI and a local MCP server. Your source of truth is a Markdown folder on your computer. -2. **First bisync requires --resync**: - ```bash - bm cloud bisync --name research --resync - ``` +### `bm` is not found -3. **Empty directory error** - Add at least one file: - ```bash - echo "# Notes" > ~/Documents/research/README.md - bm cloud bisync --name research --resync - ``` +Install or reinstall Basic Memory: -4. **Bisync state corruption** - Reset state: - ```bash - bm cloud bisync-reset research - bm cloud bisync --name research --resync - ``` +::code-group +```bash [uv] +uv tool install basic-memory +``` -5. **Too many deletes error** - Review changes, then force: - ```bash - bm cloud bisync --name research --dry-run - bm cloud bisync --name research --resync - ``` +```bash [Homebrew] +brew tap basicmachines-co/basic-memory +brew install basic-memory +``` +:: ---- +Then open a new terminal and run: -## Search and Content Issues +```bash +bm --version +``` -### Claude Can't Find Knowledge +See [Install locally](/local/local-install). -**Problem:** AI assistant not finding your notes. +### `uvx` is not found by an MCP client -**Solutions:** +GUI apps often do not inherit your shell `PATH`. -1. **Confirm files are in correct directory**: - ```bash - basic-memory project list - ls ~/basic-memory - ``` +Find the absolute path: -2. **Check frontmatter formatting** - Ensure YAML is valid: - ```yaml - --- - title: My Note - tags: [tag1, tag2] - --- - ``` +```bash +which uvx +``` -3. **Use memory:// URLs for direct access**: - ``` - memory://my-note-title - ``` +Then use that full path as the MCP `command`: + +```json +{ + "mcpServers": { + "basic-memory": { + "command": "/Users/you/.local/bin/uvx", + "args": ["basic-memory", "mcp"] + } + } +} +``` -4. **Trigger a re-sync**: - ```bash - basic-memory sync - ``` +Restart the MCP client after changing the config. -### Entity Not Found +### Local MCP tools are missing -**Problem:** Note doesn't exist at specified path. +Check: -**Solutions:** +1. The client config uses `uvx basic-memory mcp` or `bm mcp`. +2. The JSON/TOML syntax is valid. +3. You restarted the client after editing the config. +4. `bm --version` works in a terminal. +5. `bm project list` shows at least one project. -1. **Search for the note**: - ``` - Find notes about [topic] - ``` +You can start the MCP server manually for a quick sanity check: -2. **Check exact title/permalink** - Titles are case-sensitive +```bash +bm mcp +``` -3. **List directory contents**: - ``` - List files in [folder] - ``` +Stop it with `Ctrl+C` after confirming it starts. ---- +### Local notes are in the wrong place -## Performance Issues +List projects: -### Slow Operations +```bash +bm project list +``` -**Problem:** Commands or syncing taking too long. +The default local project is usually `~/basic-memory`. Add or switch projects when needed: -**Solutions:** +```bash +bm project add research ~/Documents/research +bm project default research +``` -1. **Check database size**: - ```bash - basic-memory project info - ``` +### File changes are not appearing -2. **Archive old content** - Move inactive notes to archive folder +Check: -3. **Adjust sync delay** - Add to `~/.basic-memory/config.json`: - ```json - { - "sync_delay": 2000 - } - ``` +```bash +bm status --verbose +bm doctor +``` -4. **Increase thread pool** for large knowledge bases: - ```json - { - "sync_thread_pool_size": 8 - } - ``` +Then verify: -### High Memory Usage +- The file is inside a configured project folder. +- The file is Markdown if you expect it to become a note. +- The file is not excluded by `.gitignore` or `.bmignore`. +- Basic Memory can read and write the folder. -**Problem:** Basic Memory using too much memory. +If the local index is inconsistent, rebuild it: -**Solutions:** +```bash +bm reset --reindex +``` -1. **Limit context depth** in MCP calls (use `depth=1` or `depth=2`) +::warning +`bm reset --reindex` rebuilds the local database from files. It does not delete Markdown files, but it can take time for large projects. +:: -2. **Reduce search page size** +--- -3. **Archive old content** +## Sync and routing ---- +Cloud Sync and local/cloud routing are advanced workflows. You do not need them to use Basic Memory Cloud in the web app or through hosted MCP. -## Installation Issues +### Cloud-routed CLI commands fail -### Python Version Error +Re-authenticate: + +```bash +bm cloud logout +bm cloud login +bm cloud status +``` -**Problem:** "Python 3.13+ required" error. +For automation or hybrid setups, use an API key: -**Solution:** Install Python 3.13 or higher: ```bash -# macOS with Homebrew -brew install python@3.13 +bm cloud api-key save bmc_your_key_here +bm cloud status +``` + +### A project should be local but routes to Cloud -# Or use pyenv -pyenv install 3.13.0 -pyenv global 3.13.0 +Switch it back: + +```bash +bm project set-local research +bm cloud status ``` -### uv Not Found +### A project should route to Cloud but stays local -**Problem:** `uv` command not found. +Save Cloud credentials and route the project: -**Solution:** Install uv: ```bash -# macOS/Linux -curl -LsSf https://astral.sh/uv/install.sh | sh +bm cloud api-key save bmc_your_key_here +bm project set-cloud research +bm cloud status +``` -# Then add to PATH (restart terminal or run) -source ~/.bashrc # or ~/.zshrc +See [Local & Cloud Routing](/cloud/routing). + +### Cloud Sync says the project has no local sync path + +Attach a local directory: + +```bash +bm cloud sync-setup research ~/Documents/research ``` -### Permission Errors +Then establish or check sync according to the workflow: -**Problem:** Can't create files or access directories. +```bash +bm cloud bisync --name research --resync --dry-run +bm cloud bisync --name research --resync +``` -**Solutions:** +See [Cloud Sync](/cloud/cloud-sync). -1. **Check directory permissions**: - ```bash - ls -la ~/basic-memory - ``` +### First bisync reports an empty directory -2. **Fix permissions**: - ```bash - chmod -R u+rw ~/basic-memory - ``` +Add a starter Markdown file before establishing the first baseline: -3. **Ensure Claude Desktop can execute uvx** +```bash +printf '# Research\n' > ~/Documents/research/README.md +bm cloud bisync --name research --resync +``` ---- +### Bisync reports too many deletes -## Project Issues +Stop and inspect the dry run: -### Project Not Found +```bash +bm cloud bisync --name research --dry-run +``` -**Problem:** Project doesn't exist in configuration. +Do not run a new `--resync` baseline until you understand why files would be removed. If this is a large reorganization, create a [Cloud Snapshot](/cloud/cloud-snapshots) first. -**Solutions:** +--- -1. **List available projects**: - ```bash - basic-memory project list - ``` +## Search and content -2. **Add the project**: - ```bash - basic-memory project add my-project ~/path/to/project - ``` +### The assistant cannot find a note -### Project Not Configured for Sync (Cloud) +Try a direct search: -**Problem:** "Project has no local_sync_path configured" +```bash +bm tool search-notes --query "the topic you expect" +``` + +Then try reading by title, path, or permalink: -**Solution:** ```bash -bm cloud sync-setup research ~/Documents/research -bm cloud bisync --name research --resync +bm tool read-note "My Note" +bm tool read-note "folder/my-note.md" ``` -### Moving Notes Between Projects +If you are using an AI tool, ask it to list projects first. Many "missing note" problems are project-selection problems. -**Problem:** Can't move notes from one project to another. +### Search results are too broad -**Current solution:** Copy the file manually or create a new note in the destination project, then delete the original. +Use a more specific search type or filters: ---- +```bash +bm tool search-notes --query "authentication architecture" --search-type hybrid +bm tool search-notes --query "login flow" --search-type vector +bm tool search-notes --query "tag:security" +``` -## Configuration Issues +Use [metadata search](/concepts/metadata-search) when frontmatter fields matter. -### Config Changes Not Taking Effect +### A note exists but relations or observations do not appear -**Problem:** Updated config.json but nothing changed. +Check the Markdown format: -**Solution:** Restart your MCP client (Claude Desktop, VS Code, etc.) after changing configuration. +```markdown +## Observations +- [decision] Use Cloud as the default setup path -### Invalid JSON in Config +## Relations +- part_of [[Docs Overhaul]] +``` -**Problem:** Configuration file has syntax errors. +Then run: -**Solution:** Validate your JSON: ```bash -cat ~/.basic-memory/config.json | python -m json.tool +bm status +bm doctor ``` -Common issues: -- Missing commas between properties -- Trailing commas after last property -- Unquoted strings +See [Observations and Relations](/concepts/observations-and-relations). ---- +### Memory URLs do not resolve + +Check the title, path, or permalink: -## Database Issues +```text +memory://my-note +memory://folder/my-note +``` + +If a note was renamed or moved, search for it by title first, then use the current permalink. See [Memory URLs](/concepts/memory-urls). + +--- -### Database Locked +## Performance -**Problem:** "database is locked" error. +### Commands are slow -**Solutions:** +Check project size and status: -1. **Close other applications** accessing the database +```bash +bm project info main +bm status +``` -2. **Restart Basic Memory**: - ```bash - # Find and kill processes - pkill -f "basic-memory" - ``` +For large local projects: -3. **Remove lock files** (if they exist): - ```bash - rm ~/.basic-memory/memory.db-shm - rm ~/.basic-memory/memory.db-wal - ``` +- Archive generated or inactive files outside the project folder. +- Exclude dependency/build folders with `.gitignore` or `.bmignore`. +- Keep huge binary files outside the project unless you need them available through `read_content`. +- Use smaller `page_size` values in MCP/search calls. -### Corrupted Database +### Semantic search takes time after adding many notes -**Problem:** Database errors or inconsistent state. +Embedding and indexing work can take time for large imports. Let indexing finish, then check: -**Solution:** Reset and re-index: ```bash -basic-memory reset +bm status +bm doctor ``` -::warning -This rebuilds the database from your markdown files. All files are preserved. -:: - --- -## Getting Help +## Configuration -### Check Logs +### Config changes are not taking effect -```bash -# View log files -cat ~/.basic-memory/basic-memory-*.log +Restart the MCP client after editing config files. For long-running local servers, stop and restart `bm mcp`. -# Or for Cloud mode -cat ~/.basic-memory/basic-memory-cloud.json -``` +### Config file has invalid JSON -### Command Help +Validate it: ```bash -# View all commands -basic-memory --help +python -m json.tool ~/.basic-memory/config.json +``` -# Get help for specific commands -basic-memory sync --help -basic-memory project --help +Common issues: + +- Missing commas between properties +- Trailing commas after the final property +- Unquoted strings + +See [Configuration](/reference/configuration). + +--- + +## Logs and help + +### Command help + +```bash +bm --help +bm project --help +bm tool --help +bm schema --help bm cloud --help ``` -### Community Support +### Logs + +Basic Memory writes local logs under `~/.basic-memory/`. If you ask for help, include: -- **Discord**: [discord.gg/tyvKNccgqN](https://discord.gg/tyvKNccgqN) - #help channel -- **GitHub Issues**: [github.com/basicmachines-co/basic-memory/issues](https://github.com/basicmachines-co/basic-memory/issues) +- What you expected to happen +- What happened instead +- The command or client you used +- The relevant error message +- Your operating system +- Whether the project is Cloud, local, or hybrid + +Do not paste API keys, OAuth tokens, private notes, invitation links, or billing information into public support channels. Use [Contact Support](/reference/contact-support) for private issues. --- -## Next Steps +## Next steps :::card-group ::card --- -title: Getting Started -icon: i-lucide-rocket -to: /start-here/getting-started +title: Install locally +icon: i-lucide-download +to: /local/local-install --- -Installation guide and initial setup. +Reinstall or verify the local CLI and MCP server. :: ::card --- -title: CLI Reference -icon: i-lucide-terminal -to: /reference/cli-reference +title: Cloud Sync +icon: i-lucide-refresh-cw +to: /cloud/cloud-sync --- -Complete command documentation. +Diagnose local/Cloud file synchronization. :: ::card --- -title: Cloud Sync Guide -icon: i-lucide-refresh-cw -to: /cloud/cloud-sync +title: MCP Tools Reference +icon: i-lucide-wrench +to: /reference/mcp-tools-reference --- -Cloud sync configuration and troubleshooting. +Check tool names, parameters, and project behavior. :: ::: diff --git a/content/9.reference/6.configuration.md b/content/9.reference/6.configuration.md index eca9731..6e01861 100644 --- a/content/9.reference/6.configuration.md +++ b/content/9.reference/6.configuration.md @@ -31,7 +31,7 @@ When set, Basic Memory stores config and default app DB in that directory. --- -## Example config (v0.19+) +## Example config ```json { @@ -192,7 +192,7 @@ Add frontmatter to files during sync if they don't already have it. ### `write_note_overwrite_default` -Default value for the `overwrite` parameter on `write_note`. When `false` (default), writing to an existing note path returns an error unless `overwrite=True` is passed explicitly. Set to `true` to restore the pre-v0.19 upsert behavior. +Default value for the `overwrite` parameter on `write_note`. When `false` (default), writing to an existing note path returns an error unless `overwrite=True` is passed explicitly. Set to `true` only when you deliberately want upsert behavior. - Type: boolean - Default: `false` diff --git a/content/9.reference/7.docker.md b/content/9.reference/7.docker.md index 1401e79..eb8238a 100644 --- a/content/9.reference/7.docker.md +++ b/content/9.reference/7.docker.md @@ -1,238 +1,197 @@ --- title: Docker -description: Run Basic Memory in Docker containers for server deployments and SSE transport +description: Run Basic Memory in a container for server deployments, CI, and controlled self-hosted MCP experiments. --- + ::warning -The Docker image runs Basic Memory as an **SSE server** on port 8000. This is designed for server deployments where clients connect over HTTP, not for local MCP stdio connections with Claude Desktop. +Docker is an advanced deployment path. For most local desktop and coding tools, install Basic Memory with `uv tool install basic-memory` or Homebrew and let the tool launch `uvx basic-memory mcp`. :: -## Overview +## What Docker is for -Basic Memory provides official Docker images published to GitHub Container Registry. The container runs the MCP server with SSE (Server-Sent Events) transport, suitable for: +The official Docker image runs the Basic Memory MCP server in a container. It is useful when you want: -- Server deployments where multiple clients connect remotely -- Kubernetes or Docker Compose orchestration -- CI/CD environments -- Development and testing +- A repeatable server deployment +- Docker Compose or Kubernetes orchestration +- A shared test environment +- CI jobs that need Basic Memory available over HTTP +- A controlled self-hosted MCP experiment -For local use with Claude Desktop or other MCP clients that use stdio transport, we recommend installing via [Homebrew](/local/local-install) or [pip](/local/local-install). +It is **not** the recommended path for day-one local use. Local MCP clients usually expect a stdio process they can launch themselves. See [Local Install](/local/local-install) for that setup. -## Quick Start +## Image -### Pull the Image +The image is published to GitHub Container Registry: ```bash docker pull ghcr.io/basicmachines-co/basic-memory:latest ``` -### Run the Container +The image is built from the [Basic Memory repository](https://github.com/basicmachines-co/basic-memory) and runs as a non-root user. + +## Run a container + +Mount a local knowledge folder and expose the MCP server: ```bash docker run -d \ ---name basic-container \ --p 8000:8000 \ --v ~/basic-memory-data:/app/data \ -ghcr.io/basicmachines-co/basic-memory:latest + --name basic-memory-server \ + -p 8000:8000 \ + -v "$PWD/knowledge:/app/data" \ + -v basic-memory-config:/home/appuser/.basic-memory \ + ghcr.io/basicmachines-co/basic-memory:latest ``` -The server will be available at `http://localhost:8000/mcp`. +The server listens on port `8000`. -::note -The `-v` flag mounts a local directory for persistent storage. Without it, your data will be lost when the container stops. +::caution +The container's SSE and HTTP endpoints are not secured by Basic Memory. Do not expose them directly to the public internet. Put authentication, TLS, and network access controls in front of any remote deployment. :: -## Image Details +## Docker Compose -### Registry +Use Compose when you want persistent configuration and a repeatable project mount: -Images are published to GitHub Container Registry (GHCR): +```yaml +services: + basic-memory: + image: ghcr.io/basicmachines-co/basic-memory:latest + container_name: basic-memory-server + ports: + - "8000:8000" + volumes: + - basic-memory-config:/home/appuser/.basic-memory:rw + - ./knowledge:/app/data:rw + environment: + - BASIC_MEMORY_DEFAULT_PROJECT=main + - BASIC_MEMORY_SYNC_CHANGES=true + - BASIC_MEMORY_LOG_LEVEL=INFO + - BASIC_MEMORY_SYNC_DELAY=1000 + command: ["basic-memory", "mcp", "--transport", "sse", "--host", "0.0.0.0", "--port", "8000"] + restart: unless-stopped + healthcheck: + test: ["CMD", "basic-memory", "--version"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 30s +volumes: + basic-memory-config: ``` -ghcr.io/basicmachines-co/basic-memory -``` - -### Available Tags - -| Tag | Description | -|-----|-------------| -| `latest` | Latest stable release | -| `0.19.0` | Specific version | -| `0.19` | Latest patch for minor version | - -### Architectures - -Multi-platform images are available for: -- `linux/amd64` (Intel/AMD) -- `linux/arm64` (Apple Silicon, ARM servers) - -Docker automatically pulls the correct architecture for your platform. -## Configuration - -### Environment Variables - -| Variable | Default | Description | -|----------|---------|-------------| -| `BASIC_MEMORY_HOME` | `/app/data/basic-memory` | Path to Basic Memory data | -| `BASIC_MEMORY_PROJECT_ROOT` | `/app/data` | Root directory for projects | - -### Volume Mounts - -Mount a local directory to persist data: +Start it: ```bash -docker run -d \ --v /path/to/local/data:/app/data \ --p 8000:8000 \ -ghcr.io/basicmachines-co/basic-memory:latest +docker compose up -d ``` -### Port Configuration - -The container exposes port 8000 by default. Map to a different host port if needed: +Check logs: ```bash -docker run -d \ --p 3000:8000 \ -ghcr.io/basicmachines-co/basic-memory:latest +docker logs basic-memory-server ``` -## Docker Compose +## Configuration -For more complex setups, use Docker Compose: +The image sets these defaults: -```yaml -version: '3.8' +| Variable | Default | Purpose | +|---|---|---| +| `BASIC_MEMORY_HOME` | `/app/data/basic-memory` | Basic Memory home inside the container | +| `BASIC_MEMORY_PROJECT_ROOT` | `/app/data` | Root directory for mounted projects | +| `BASIC_MEMORY_DEFAULT_PROJECT` | `main` in the Compose example | Default project name | +| `BASIC_MEMORY_SYNC_CHANGES` | `true` in the Compose example | Enable file-change sync behavior | +| `BASIC_MEMORY_LOG_LEVEL` | `INFO` in the Compose example | Log verbosity | +| `BASIC_MEMORY_SYNC_DELAY` | `1000` in the Compose example | File sync delay in milliseconds | -services: -basic-container: -image: ghcr.io/basicmachines-co/basic-memory:latest -container_name: basic-container -ports: -- "8000:8000" -volumes: -- ./data:/app/data -environment: -- BASIC_MEMORY_HOME=/app/data/basic-memory -restart: unless-stopped -healthcheck: -test: ["CMD", "basic-memory", "--version"] -interval: 30s -timeout: 10s -retries: 3 -``` +Mount two kinds of storage: -Run with: +- **Knowledge files:** mount your Markdown/project directory at `/app/data`. +- **Configuration and local index:** mount `/home/appuser/.basic-memory` to a named volume so configuration and database state survive container restarts. -```bash -docker compose up -d -``` +## Connect a client -## Connecting to the Server +The Docker image starts Basic Memory with SSE transport by default: -### MCP SSE Configuration +```bash +basic-memory mcp --transport sse --host 0.0.0.0 --port 8000 +``` -Configure your MCP client to connect via SSE transport: +Use Docker only with clients or gateways that can reach an HTTP/SSE MCP server. If your client expects local stdio config, use the local install path instead: ```json { "mcpServers": { "basic-memory": { - "transport": { - "type": "sse", - "url": "http://localhost:8000/mcp" - } + "command": "uvx", + "args": ["basic-memory", "mcp"] } } } ``` -### Health Check +## Run CLI commands inside the container -Verify the server is running: +You can inspect the container with normal Basic Memory commands: ```bash -curl http://localhost:8000/health +docker exec basic-memory-server basic-memory --version +docker exec basic-memory-server bm status +docker exec basic-memory-server bm project list ``` -Or check container health: +Use `docker exec` for diagnostics and scripted maintenance. For everyday local work, use the installed CLI on your host machine. -```bash -docker inspect --format='{{.State.Health.Status}}' basic-container -``` - -## Running CLI Commands +## PostgreSQL for development -You can run Basic Memory CLI commands inside the container. Note that the first argument is the container name (`basic-container`) and the second is the CLI command (`basic-memory`): +The Basic Memory source repository includes a separate `docker-compose-postgres.yml` for local development and testing with PostgreSQL plus `pgvector`. -```bash -# Check version -docker exec basic-container basic-memory --version - -# Check status -docker exec basic-container basic-memory status +Use it when you are developing or testing the database backend. It is not required for the standard Docker MCP server above, which can run with its normal local storage. -# List projects -docker exec basic-container basic-memory project list -``` - -## Security - -The container runs as a non-root user (`appuser`) for security. Key security features: - -- Non-root execution (UID/GID 1000 by default) -- No unnecessary packages installed -- Health checks enabled -- Slim base image (Python 3.12 slim-bookworm) +## Troubleshooting -### Custom UID/GID +### Port 8000 is already in use -Build with custom user IDs for permission compatibility: +Map a different host port: ```bash -docker build --build-arg UID=1001 --build-arg GID=1001 -t basic-memory:custom . +docker run -d \ + -p 3000:8000 \ + -v "$PWD/knowledge:/app/data" \ + -v basic-memory-config:/home/appuser/.basic-memory \ + ghcr.io/basicmachines-co/basic-memory:latest ``` -## Troubleshooting +The container still listens on `8000`; the host listens on `3000`. -### Permission Denied Errors +### Permission denied on mounted files -If you see permission errors with mounted volumes: +The container runs as a non-root user. If it cannot read or write your mounted directory, fix ownership or run with a matching user: ```bash -# Fix ownership on host -sudo chown -R 1000:1000 /path/to/local/data - -# Or run with matching UID -docker run --user $(id -u):$(id -g) ... +sudo chown -R 1000:1000 ./knowledge ``` -### Container Exits Immediately - -Check the logs: +or: ```bash -docker logs basic-container +docker run --user "$(id -u):$(id -g)" ... ``` -Common causes: -- Port 8000 already in use -- Volume mount path doesn't exist -- Insufficient permissions +### The client cannot connect -### SSE vs Stdio Transport +Check three things: -::warning -The Docker image is configured for SSE transport only. It cannot be used as a stdio MCP server for Claude Desktop directly. -:: +1. The container is running: `docker ps` +2. The server logs are clean: `docker logs basic-memory-server` +3. Your client supports the transport you configured -For Claude Desktop integration, either: -1. Install Basic Memory locally via Homebrew or pip -2. Use the SSE transport configuration (if your Claude Desktop version supports it) +If the client only supports local stdio MCP, Docker is the wrong connection path. Use [Local MCP tools](/local/mcp-tools-local) instead. -## Building from Source +## Build from source -Clone the repository and build locally: +Clone the Basic Memory source repository and build the image locally: ```bash git clone https://github.com/basicmachines-co/basic-memory.git @@ -240,8 +199,42 @@ cd basic-memory docker build -t basic-memory:local . ``` -## See Also +You can pass custom UID/GID build arguments if your deployment needs specific file ownership: -- [Getting Started](/start-here/getting-started) - Local installation options -- [CLI Reference](/reference/cli-reference) - Command line interface -- [MCP Tools Reference](/reference/mcp-tools-reference) - Available MCP tools +```bash +docker build \ + --build-arg UID=1001 \ + --build-arg GID=1001 \ + -t basic-memory:custom . +``` + +## See also + +::card-group + ::card + --- + title: Local Install + icon: i-lucide-terminal + to: /local/local-install + --- + Install Basic Memory for local desktop and coding tools. + :: + + ::card + --- + title: CLI Reference + icon: i-lucide-square-terminal + to: /reference/cli-reference + --- + Look up Basic Memory commands and flags. + :: + + ::card + --- + title: Troubleshooting + icon: i-lucide-life-buoy + to: /reference/troubleshooting + --- + Diagnose install, MCP, sync, and routing problems. + :: +:: diff --git a/content/9.reference/9.v0.19-migration.md b/content/9.reference/9.v0.19-migration.md index 28ce8d4..261a838 100644 --- a/content/9.reference/9.v0.19-migration.md +++ b/content/9.reference/9.v0.19-migration.md @@ -3,7 +3,7 @@ title: v0.19.0 Migration Guide description: Configuration and behavior changes when upgrading from v0.18 to v0.19. --- -This guide covers configuration and behavior changes when upgrading from v0.18 to v0.19. For a user-friendly overview of new features, see [What's New in v0.19.0](/whats-new/v0.19.0). +This historical guide covers configuration and behavior changes when upgrading from v0.18 to v0.19. For current releases, see the [Changelog](/changelog). --- diff --git a/content/changelog.md b/content/changelog.md new file mode 100644 index 0000000..33678a8 --- /dev/null +++ b/content/changelog.md @@ -0,0 +1,13 @@ +--- +title: Changelog +description: Release notes and shipped changes across 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/index.md b/content/index.md index 4821b8f..9560ee4 100644 --- a/content/index.md +++ b/content/index.md @@ -1,163 +1,140 @@ --- +path: / seo: - title: Basic Memory - description: AI and humans working together to build knowledge that gets smarter over time + title: Basic Memory Documentation + description: Documentation for Basic Memory Cloud and the open-source project. --- -::u-page-hero ---- -orientation: horizontal -class: py-0 ---- +::div{class="bm-home"} + :::div{class="bm-docs-intro"} + # Basic Memory documentation -#title -AI memory that grows with you. - -#description -Build persistent knowledge that both you and AI can read, write, and enhance together. -Learn how it works. -See why your AI needs Basic Memory. - -#links - :::u-button - --- - color: neutral - size: xl - to: start-here/what-is-basic-memory - trailing-icon: i-lucide-arrow-right - --- - Get started - ::: + Build and maintain a shared knowledge base for humans, agents, and their teams. Find guides for Basic Memory Cloud and the open-source project. - :::u-button - --- - color: neutral - icon: simple-icons-github - size: xl - to: https://github.com/basicmachines-co/basic-memory - variant: outline - --- - Star on GitHub + ::docs-home-search ::: -#headline - :::u-button - --- - size: sm - to: /whats-new/v0.21.0 - variant: outline - --- - v0.21 → - ::: + :::div{class="bm-docs-section bm-start-here"} + ## Start here -#default -![Basic Memory](/computer.png) -:: + ::::div{class="bm-start-grid"} + :::::div{class="bm-start-card bm-start-card-primary"} + :badge[Recommended]{color="primary" variant="soft"} -::u-page-section ---- -class: pt-0 ---- - :::u-page-grid - ::::u-page-card - --- - title: See into the black box - description: Every piece of AI context is a file you can read and edit. No mystery, no lock-in—just plain Markdown you own forever. - class: lg:col-span-1 - spotlight: true - --- - :::: + Start with Cloud - ::::u-page-card - --- - title: Knowledge that compounds - description: Unlike chat history that disappears, Basic Memory creates a semantic knowledge graph. Every note connects to related ideas, revealing patterns and insights that grow smarter over time. - class: lg:col-span-2 - spotlight: true - --- - :::: + Create a workspace, connect your AI tools, and use Basic Memory from the web app. - ::::u-page-card - --- - title: Works with your AI assistant - description: Connect to Claude, ChatGPT, Gemini, Cursor, VS Code, and more via the Model Context Protocol. Your AI assistant reads your entire knowledge history instantly. - class: lg:col-span-2 - spotlight: true - --- - ![MCP Integration with Claude](/screenshots/claude/create-first-note.png) - :::: + [Quickstart: Cloud →](/start-here/quickstart-cloud) - ::::u-page-card - --- - title: Your web editor for knowledge - description: Write and organize notes from any browser. Search your knowledge, make connections, and watch your ideas grow—no installation required. - class: lg:col-span-1 - spotlight: true - --- - :::theme-image{light="/screenshots/cloud-app/v2-edit-mode-light.png" dark="/screenshots/cloud-app/v2-edit-mode-dark.png" alt="Web editor"} - ::: - :::: + ::::: - ::::u-page-card - --- - title: Cloud or local - description: Start with Basic Memory Cloud for instant access from any browser, or run locally on your machine. Sync between them, or keep everything offline—your choice. - class: lg:col-span-1 - icon: i-lucide-cloud - to: /start-here/quickstart-cloud - --- - :::: + :::::div{class="bm-start-card"} + :badge[Open Source]{color="neutral" variant="soft"} - ::::u-page-card - --- - title: Plain Markdown - description: Human-readable files, not proprietary formats. Your knowledge works in Obsidian, VS Code, or any text editor. Export, backup, or migrate anytime. - class: lg:col-span-2 - icon: i-lucide-file-text - --- - ```markdown - --- - title: Project Ideas - tags: [ideas, projects] - --- - - ## Observations - - [insight] AI collaboration improves over time #growth - - ## Relations - - relates_to [[AI Tools]] - - builds_on [[Past Research]] - ``` + Run locally + + Install the CLI, keep notes on your machine, and connect a local MCP server. + + [Quickstart: Open Source →](/start-here/quickstart-local) + + ::::: :::: - ::::u-page-card - --- - title: Open source - description: Basic Memory is fully open source. Run locally, self-host, contribute, or just explore the code. Your knowledge, your rules. - class: lg:col-span-1 - icon: i-simple-icons-github - to: https://github.com/basicmachines-co/basic-memory - --- + ::::p{class="bm-ai-docs-link"} + [AI-friendly docs](/reference/llms-txt) for agents that need clean Markdown, `/llms.txt`, or the full docs corpus. :::: + ::: - ::::u-page-card - --- - title: AI-friendly docs - description: This documentation is optimized for AI consumption with llms.txt support and content negotiation. AI assistants can read these docs directly. - class: lg:col-span-1 - icon: i-lucide-bot - to: /reference/llms-txt - --- + :::div{class="bm-docs-section bm-common-tasks"} + ## Common tasks + + ::::div{class="bm-task-grid"} + :::::div{class="bm-task-link"} + [Connect an AI tool](/integrations) + + Claude, ChatGPT, Codex, Cursor, and other MCP clients. + ::::: + + :::::div{class="bm-task-link"} + [Import existing knowledge](/cloud/web-app#import-data) + + Bring in Markdown, Claude conversations, or ChatGPT history. + ::::: + + :::::div{class="bm-task-link"} + [Collaborate with your team](/teams/about) + + Invite members, assign roles, and share projects. + ::::: + + :::::div{class="bm-task-link"} + [Understand the knowledge format](/concepts/knowledge-format) + + Learn how notes, observations, relations, and projects work. + ::::: + + :::::div{class="bm-task-link"} + [Look up an MCP tool](/reference/mcp-tools-reference) + + Find tool names, parameters, behavior, and examples. + ::::: + + :::::div{class="bm-task-link"} + [Use Cloud from the terminal](/cloud/cloud-cli) + + Check status, manage keys, sync files, route projects, and automate workflows. + ::::: + + :::::div{class="bm-task-link"} + [Troubleshoot a problem](/reference/troubleshooting) + + Diagnose installation, connection, sync, and indexing issues. + ::::: :::: + ::: - ::::u-page-card - --- - title: Ready to start? - description: Create your first note in under 2 minutes. Build AI memory that actually remembers. - class: lg:col-span-1 - spotlight: true - to: /start-here/quickstart-cloud - --- + :::div{class="bm-docs-section bm-browse-docs"} + ## Browse the docs + + ::::div{class="bm-browse-grid"} + :::::div{class="bm-browse-group"} + ### Cloud + + - [Cloud overview](/cloud/cloud-guide) + - [Web app](/cloud/web-app) + - [Cloud CLI](/cloud/cloud-cli) + - [Cloud sync](/cloud/cloud-sync) + ::::: + + :::::div{class="bm-browse-group"} + ### Open Source + + - [Install Basic Memory](/local/local-install) + - [CLI basics](/local/cli-basics) + - [Local MCP tools](/local/mcp-tools-local) + - [Configuration](/reference/configuration) + ::::: + + :::::div{class="bm-browse-group"} + ### Integrations + + - [Connect AI tools](/integrations) + - [Claude](/integrations/claude-desktop) + - [ChatGPT](/integrations/chatgpt) + - [Codex](/integrations/codex) + - [Cursor and VS Code](/integrations/cursor) + ::::: + + :::::div{class="bm-browse-group"} + ### Concepts & Reference + + - [Knowledge format](/concepts/knowledge-format) + - [Schemas](/concepts/schema-system) + - [MCP tools reference](/reference/mcp-tools-reference) + - [Troubleshooting](/reference/troubleshooting) + - [Contact support](/reference/contact-support) + ::::: :::: ::: :: diff --git a/docs/docs-audit.md b/docs/docs-audit.md new file mode 100644 index 0000000..b90b8ba --- /dev/null +++ b/docs/docs-audit.md @@ -0,0 +1,146 @@ +# Basic Memory Docs Audit + +Last updated: 2026-06-09 + +## Purpose + +This file tracks the docs overhaul as a product audit. A page is not "done" because it reads well; it is done when current product behavior, source code, screenshots, and positioning agree. + +## Source Of Truth + +| Area | Primary source | Verification notes | +|---|---|---| +| Messaging | basicmemory.com, product notes, Drew/Paul decisions | Current public website uses "One knowledge base for you, your AI tools, and your team" and emphasizes plain Markdown, MCP, Cloud, open source, and teams. Avoid "just expanding memory" framing. | +| Cloud app | Live app at app.basicmemory.com | Verify settings, onboarding, workspace switcher, import, sharing, snapshots, file history, themes, and billing in the browser. | +| Collaboration | Live app invite/member flows, product notes | Verify owner and recipient flows, roles, seats, billing behavior, project access, and shared AI access. | +| CLI | basic-memory source and command help | Verify commands, flags, defaults, routing, update behavior, imports, schema commands, and local paths. | +| MCP tools | basic-memory source/tool schemas | Verify tool names, parameters, aliases, output behavior, Cloud/local parity, and ChatGPT compatibility tools. | +| Integrations | Official client docs plus live Basic Memory behavior | Verify remote MCP/OAuth versus local stdio setup for each client. Remove unsupported clients/workarounds. | +| Screenshots | Live app/browser captures plus `docs/screenshots.json` | Every screenshot should record source screen, capture date, theme, and owning docs page. | +| Pricing/limits | Live app checkout, Polar/product config, public website | Treat as high-stale-risk. Do not hard-code pricing or limits without verification. | + +## Status Key + +| Status | Meaning | +|---|---| +| Verified | Checked against current source of truth in this overhaul. | +| Needs audit | Plausible, but not yet verified deeply enough. | +| Needs rewrite | Known stale, incomplete, misleading, or too thin. | +| Needs screenshots | Text may be fine, but UI proof/capture is missing or stale. | +| Archive candidate | Historical or release-specific; should not sit in current docs nav unless intentionally preserved. | + +## Priority Queue + +1. **Integrations batch** — verify client-by-client against official current behavior and Basic Memory source. +2. **Screenshots** — resolve unreferenced screenshot warnings and snapshot-list image transform warning. +3. **How-to guides** — shorten or rewrite as durable workflows, not old marketing/tutorial sprawl. +4. **Historical release pages** — keep release material under What's New/changelog/archive, not current reference unless still useful. + +## Coverage Checklist + +| User job | Current home | Status | Notes | +|---|---|---|---| +| Understand what Basic Memory is | `/start-here/what-is-basic-memory` | Needs audit | Messaging mostly aligned; verify examples cover documents, workflows, research, software, and creative projects. | +| Start with Cloud | `/start-here/quickstart-cloud` | Needs audit | Check live onboarding, pricing/seat language, screenshot, and team invite mention. | +| Start locally | `/start-here/quickstart-local` | Verified | First pass checked against README/source. | +| Decide Cloud vs Open Source | Missing dedicated page | Needs rewrite | Add "Cloud or Open Source?" or equivalent; link from homepage and both quickstarts. | +| Use docs with an AI agent | `/reference/llms-txt`, `/llms.txt`, `/llms-full.txt` | Verified | Endpoints return real content locally. Homepage links to explanation page. | +| Connect an AI tool | `/integrations/*` | Needs audit | Must distinguish Cloud remote MCP/OAuth from local `uvx basic-memory mcp`. | +| Invite/collaborate with a team | `/teams/about`, `/teams/join-a-team` | Needs screenshots | Text rewritten, but live invite/recipient flow still needs final verification. | +| Import existing knowledge | `/cloud/web-app#import-data` | Needs audit | Verify current import UI and supported sources. | +| Sync local files with Cloud | `/cloud/cloud-sync`, `/cloud/edit-locally-and-in-the-app` | Needs audit | Verify current CLI behavior and local/cloud routing. | +| Use Cloud from the terminal | `/cloud/cloud-cli` | Verified | Added short command-line guide backed by current CLI source and cross-linked from Cloud onboarding/reference pages. | +| Recover notes | `/cloud/restore-lost-content`, `/cloud/cloud-snapshots`, `/cloud/file-history` | Needs screenshots | Build logs one Cloud Snapshot image transform warning. | +| Contact support | `/reference/contact-support` | Verified | Uses public `hello@basicmemory.com` contact path and separates private support from Discord/GitHub. | +| Use schemas | `/concepts/schema-system`, `/concepts/metadata-search` | Needs audit | Schema page appears substantial; verify examples against current schema commands/tools. | +| Understand observations/relations | `/concepts/observations-and-relations` | Verified | Rewritten in this audit pass; verify against parser/source during MCP reference audit. | +| Troubleshoot MCP/install/sync | `/reference/troubleshooting` | Verified | Rewritten around Cloud MCP, Cloud app, local MCP, sync/routing, search/content, config, logs. | + +## Page Register + +| Area | Page | Status | Action | +|---|---|---|---| +| Home | `/` | Verified | New task-first homepage. Add Cloud/Open Source decision page link when created. | +| Get Started | `/start-here/what-is-basic-memory` | Needs audit | Check examples and remove any narrow "AI memory only" framing. | +| Get Started | `/start-here/quickstart-cloud` | Needs audit | Verify onboarding, current pricing language, MCP endpoint, and screenshot. | +| Get Started | `/start-here/quickstart-local` | Verified | Keep concise; revisit after CLI reference audit. | +| Get Started | `/start-here/getting-started` | Verified | Cloud terminal guidance now points to Cloud CLI; skills framing distinguishes MCP tool access from optional usage patterns. | +| What's New | `/whats-new/teams` | Needs audit | Verify role/seat copy; keep release-specific framing out of evergreen Teams docs. | +| What's New | `/whats-new/v0.21.0` | Archive candidate | Confirm patch-release notes belong here, not current nav/reference. | +| What's New | `/whats-new/hermes-plugin` | Needs audit | Verify install command and feature list. | +| What's New | `/whats-new/cloud` | Archive candidate | Keep as release/news if still accurate. | +| What's New | `/whats-new/changelog` | Verified | Simple redirect/explanation. | +| What's New | `/whats-new/agent-skills` | Needs audit | Verify whether release/news page should mirror current 10-skill list or stay historical. | +| What's New | `/whats-new/openclaw-plugin` | Needs audit | Verify install command and feature list. | +| What's New | `/whats-new/ai-friendly-docs` | Verified | Mirrors AI-friendly reference. | +| Cloud | `/cloud/cloud-guide` | Verified | Cloud CLI and Contact Support are now surfaced; still keep feature claims tied to current Cloud pages. | +| Cloud | `/cloud/web-app` | Needs screenshots | Verify all settings sections and screenshots. | +| Cloud | `/cloud/cloud-sync` | Needs audit | Verify commands, routing, and sync statuses. | +| Cloud | `/cloud/cloud-cli` | Verified | New short guide for terminal workflows; snapshot commands corrected against source. | +| Cloud | `/cloud/cloud-snapshots` | Needs screenshots | Verify UI/CLI, retention claims, and image warning. | +| Cloud | `/cloud/web-app#themes` | Verified | Themes folded into Web App settings with current screenshot; `/cloud/themes` redirects here. | +| Cloud | `/cloud/api-keys` | Verified | Source-backed pass against current CLI API-key behavior; reduced client-specific config, clarified `bmc_` format, bearer usage, OAuth/API-key tradeoffs, and explicit per-project routing. | +| Cloud | `/cloud/routing` | Verified | Source-backed pass against current `get_client`, routing flags, project mode, workspace default, `set-cloud`, and `set-local` behavior; removed stale global Cloud mode claims. | +| Cloud | `/cloud/shared-notes` | Verified | Current screenshots present; tightened public-link safety language, removed unverified `/raw` claim, and linked support for accidental private sharing. | +| Cloud | `/cloud/edit-locally-and-in-the-app` | Needs audit | Verify CLI/sync setup and cross-link with Cloud Sync. | +| Cloud | `/cloud/restore-lost-content` | Needs audit | Verify recovery decision tree and current UI labels. Visible title is "Recover Notes." | +| Cloud | `/cloud/file-history` | Needs screenshots | Verify UI, permissions, and retention behavior. | +| Collaboration | `/teams/about` | Needs screenshots | Verify live owner flow, roles, seats, project visibility. | +| Collaboration | `/teams/join-a-team` | Needs screenshots | Verify recipient invite flow. | +| Collaboration | `/teams/copy-between-workspaces` | Needs audit | Verify copy/export/import options and avoid overpromising. | +| Open Source | `/local/local-install` | Verified | First pass checked. Revisit after CLI reference audit. | +| Open Source | `/local/cli-basics` | Verified | First pass checked. Revisit after CLI reference audit. | +| Open Source | `/local/mcp-tools-local` | Verified | First pass checked. Revisit after MCP reference audit. | +| Concepts | `/concepts/vs-built-in-memory` | Needs audit | Verify current built-in memory claims for Claude/ChatGPT/Cursor. | +| Concepts | `/concepts/knowledge-format` | Needs audit | Check duplication and align with schema/obs-rel pages. | +| Concepts | `/concepts/projects-and-folders` | Needs audit | Verify local/cloud project examples and project-prefixed permalinks. | +| Concepts | `/concepts/observations-and-relations` | Verified | Rewritten from current Knowledge Format/MCP reference behavior. | +| Concepts | `/concepts/memory-urls` | Needs audit | Verify current URL resolution behavior. | +| Concepts | `/concepts/schema-system` | Needs audit | Verify picoschema examples and command names. | +| Concepts | `/concepts/semantic-search` | Needs audit | Verify default embedding provider, config, and OpenAI provider guidance. | +| Concepts | `/concepts/metadata-search` | Needs audit | Verify filters against current tool schema. | +| Integrations | `/integrations/claude-desktop` | Needs audit | Verify official Claude connector flow and local deployment variant. | +| Integrations | `/integrations/claude-code` | Needs audit | Verify CLI commands and Cloud/local variants. | +| Integrations | `/integrations/chatgpt` | Needs audit | Verify current ChatGPT developer-mode/custom app flow. | +| Integrations | `/integrations/gemini` | Needs audit | Verify official Gemini CLI MCP config. | +| Integrations | `/integrations/codex` | Needs audit | Verify Codex app and CLI config, including desktop behavior. | +| Integrations | `/integrations/cursor` | Needs audit | Verify Cursor MCP config and Cloud/local variants. | +| Integrations | `/integrations/vscode` | Needs audit | Verify VS Code MCP configuration and direct Markdown editing guidance. | +| Integrations | `/integrations/obsidian` | Needs audit | Verify Cloud/local wording; likely durable. | +| Integrations | `/integrations/skills` | Verified | Checked against `basicmachines-co/basic-memory-skills` README; updated to 10 skills including `memory-literary-analysis`. | +| Integrations | `/integrations/openclaw` | Needs audit | Verify package name and feature list. | +| Integrations | `/integrations/hermes` | Needs audit | Verify package name and feature list. | +| Guides | `/how-to/project-documentation` | Needs audit | Keep only if durable and useful; shorten if generic. | +| Guides | `/how-to/writing-organization` | Needs audit | Good broader-use signal; check for outdated examples. | +| Guides | `/how-to/research-learning` | Needs audit | Likely durable; tighten if needed. | +| Guides | `/how-to/note-taking` | Needs audit | Check for old terminology and stale tool behavior. | +| Guides | `/how-to/personal-knowledge` | Needs audit | Avoid over-indexing docs on personal memory use case. | +| Reference | `/reference/cli-reference` | Verified | Source-backed pass against current CLI command modules; added status wait/full reindex, Team-safe pull/push guidance, upload flags, and missing `bm tool delete-note`. | +| Reference | `/reference/mcp-tools-reference` | Verified | Source-backed pass against current MCP tool signatures; added `project_id`, current search aliases/categories, UI tools, and corrected workspace/list-project behavior. | +| Reference | `/reference/ai-assistant-guide` | Needs audit | Make durable system-prompt guidance; link from quickstarts/getting-started. | +| Reference | `/reference/technical-information` | Needs audit | Verify architecture, licensing, and source links. | +| Reference | `/reference/troubleshooting` | Verified | Rewritten in this audit pass; stale `basic-memory sync` and old install assumptions removed. | +| Reference | `/reference/contact-support` | Verified | New page for private account, billing, workspace, invitation, and Cloud data issues. | +| Reference | `/reference/configuration` | Needs audit | Verify config keys and environment variables. | +| Reference | `/reference/docker` | Verified | Rewritten against current Dockerfile, Compose files, default SSE transport, mounted knowledge/config volumes, and security caveats. | +| Reference | `/reference/llms-txt` | Verified | Endpoints checked locally. | +| Reference | `/reference/v0.19-migration` | Archive candidate | Keep historical; remove from current-reference prominence if distracting. | +| Changelog | `/changelog` | Needs audit | Verify release feed/source. | + +## Automated Checks To Add Or Extend + +- Fail on broken internal links and missing assets. +- Warn on orphaned screenshots with source metadata missing from `docs/screenshots.json`. +- Warn on stale version literals outside `whats-new`, changelog, and migration/archive pages. +- Warn on removed commands such as `basic-memory sync` unless in historical pages. +- Warn on unsupported clients/features such as Claude Research if reintroduced. +- Warn when content pages have no title or no body headings. + +## Working Rhythm + +1. Pick one batch from the priority queue. +2. Verify source of truth. +3. Rewrite or delete pages. +4. Run `npm run check:docs`. +5. Browser-review the affected routes. +6. Update this audit status before moving on. diff --git a/docs/handoff-2026-06-09-review.md b/docs/handoff-2026-06-09-review.md new file mode 100644 index 0000000..fe4cb99 --- /dev/null +++ b/docs/handoff-2026-06-09-review.md @@ -0,0 +1,85 @@ +# Handoff: docs review pass (2026-06-09) + +Claude (Opus) did a verification pass over the docs at Drew's request. Overall the +docs are in good shape — content is accurate, consistent, and well-structured. +This note records what was checked, what changed, and what's left for you to decide. + +## What was verified (no changes needed) + +- **Routes render**: home + quickstarts + integrations + cloud + reference + concepts + all return 200 against the local preview (127.0.0.1:4327). +- **Consistency is clean across all content**: + - Pricing: `$15/seat/month` + "per seat" language agree everywhere. + - Cloud MCP endpoint `https://cloud.basicmemory.com/mcp` is identical in all ~10 places. + - No `TODO`/`placeholder`/`coming soon` leftovers. +- **Anchor links resolve**: homepage `/cloud/web-app#import-data` and quickstart + `getting-started#teach-your-ai-when-to-use-basic-memory` both point to real headings. +- `npm run check:docs` passes (0 errors). + +## Changes made this session + +1. **`scripts/check-docs.mjs` — fixed a real regex bug.** The link pattern's text and + URL groups (`[^\]]*` / `[^)]+`) matched across newlines. A stray `[` in the + keyboard-shortcuts table in `content/3.cloud/02.web-app.md` (line ~293, + `**Cmd/Ctrl + [**`) opened a "markdown link" that didn't close until the real + `[Teams](/teams/about)` link ~42 lines later. `matchAll` is non-overlapping, so it + swallowed that whole span — producing **false** "unreferenced screenshot" warnings for + `v2-settings-*` and `v2-shortcuts-*` (which ARE used), AND silently skipping link/asset + validation for anything inside a swallowed span (a real blind spot). + - Fix: bounded both groups to a single line: + `\[[^\]\n]*]\(([^)\s]+)\)|\bto:\s*([^\s]+)|(?:light|dark)="([^"]+)"` + - NOTE: `check-docs.mjs` is still untracked (`??`). Commit it. + +2. **`content/3.cloud/02.web-app.md` — promoted Themes into the Settings table.** + Themes was the one setting that wasn't a table row (just a dangling trailing sentence). + Added a `**Themes**` row linking to `/cloud/themes`, removed the trailing sentence, and + dropped the now-redundant "appearance" from the General row. The `/cloud/themes` page is + intentionally kept — its TweakCN custom-theme workflow is durable content that doesn't + belong inlined in the settings table. (Drew agreed with keeping the page.) + +3. **Deleted stale/superseded screenshots:** + - `v2-import-{light,dark}.png`, `v2-manage-projects-{light,dark}.png` — superseded by + the `-current.png` versions web-app.md already uses. + - `themes.gif` — Drew confirmed it's based on the old app and is distracting. + +## Result: orphaned-screenshot warnings went 19 -> 10 + +After the fixes, `check:docs` passes with **10 warnings**, all now genuine orphans. + +## Open decision for you (Codex) — the 10 remaining orphans + +We dug into provenance and concluded these are **pre-v2 leftovers**, deliberately not +blessed during your v2 capture pass: + +- The current/blessed captures in `docs/screenshots.json` were taken **2026-06-07** and use + the `v2-` naming convention. +- All 10 orphans were captured **2026-06-06**, are **not** in the manifest, and the two + Basic-Memory-app ones (`cloud/signup.png`, `cloud-app/first-note.png`) lack the `v2-` + prefix. `first-note.png` (223 KB, Jun 6) is a lower-quality near-duplicate of the blessed + `getting-started-project.png` (562 KB, Jun 7). + +The 10 orphans: + +- `cloud-app/first-note.png` — pre-v2 dupe of `getting-started-project.png`. Safe to delete. +- `cloud/signup.png` — pre-v2 sign-up screen. Current screen may differ; verify before reuse. +- `claude/*` (8: add-connector, configure-tools, create-first-note, oauth-authorize, + oauth-connect, project-list-response, settings-connectors, tools-menu-local) — these are + **Claude's own UI**, not the BM app, captured Jun 6. They visually look current (Opus 4.5, + BETA connector) and match the written steps in + `content/7.integrations/1.claude-desktop.md` (which is currently text-only), but they were + not blessed and we couldn't verify them against today's Claude. + +**Recommendation:** either (a) delete all 10 to reach zero warnings and match what the v2 +pass already decided, or (b) if you want visuals on the (currently text-only) Claude +integration page, re-capture fresh shots against current app.basicmemory.com + current +Claude and add them to `docs/screenshots.json` — don't reuse the Jun-6 images on trust. + +We did NOT delete these 8 Claude shots or `signup.png`/`first-note.png` — left for your call. + +## Notes + +- `content/3.cloud/06.themes.md` shows as modified in git, but that was a pre-existing + change from before this session — Claude did not edit it. +- Audit doc (`docs/docs-audit.md`) still lists many pages as "Needs audit." Spot-checks of + several (integrations index, claude-desktop, both quickstarts, what-is-basic-memory) found + them in good shape — the status table may just be lagging the actual work. diff --git a/docs/screenshots.json b/docs/screenshots.json new file mode 100644 index 0000000..f441925 --- /dev/null +++ b/docs/screenshots.json @@ -0,0 +1,68 @@ +{ + "description": "Screenshots deliberately reviewed during the 2026 documentation overhaul. Add new UI captures here when they become part of the maintained documentation.", + "screenshots": [ + { + "path": "screenshots/cloud-app/getting-started-project.png", + "page": "/start-here/quickstart-cloud", + "source": "Basic Memory Cloud Getting Started workspace", + "captured": "2026-06-07", + "theme": "light" + }, + { + "path": "screenshots/cloud-app/v2-manage-projects-current.png", + "page": "/cloud/web-app", + "source": "Settings > Projects", + "captured": "2026-06-07", + "theme": "light" + }, + { + "path": "screenshots/cloud-app/v2-import-current.png", + "page": "/cloud/web-app", + "source": "Settings > Import", + "captured": "2026-06-07", + "theme": "light" + }, + { + "path": "screenshots/cloud-app/themes-settings.png", + "page": "/cloud/web-app#themes", + "source": "Settings > General > Look & Feel", + "captured": "2026-06-09", + "theme": "light" + }, + { + "path": "screenshots/cloud-app/snapshots-list.png", + "page": "/cloud/cloud-snapshots", + "source": "Settings > Snapshots", + "captured": "2026-06-07", + "theme": "light" + }, + { + "path": "screenshots/cloud-app/create-snapshot.png", + "page": "/cloud/cloud-snapshots", + "source": "Create Snapshot dialog", + "captured": "2026-06-07", + "theme": "light" + }, + { + "path": "screenshots/cloud-app/restore-files.png", + "page": "/cloud/cloud-snapshots", + "source": "Snapshot restore browser", + "captured": "2026-06-07", + "theme": "light" + }, + { + "path": "screenshots/integrations/chatgpt-add-app-to-chat.png", + "page": "/integrations/chatgpt", + "source": "ChatGPT app picker", + "captured": "2026-06-07", + "theme": "light" + }, + { + "path": "screenshots/integrations/chatgpt-tool-confirmation.png", + "page": "/integrations/chatgpt", + "source": "ChatGPT Basic Memory tool result", + "captured": "2026-06-07", + "theme": "light" + } + ] +} diff --git a/nuxt.config.ts b/nuxt.config.ts index 4d9eab6..72129f5 100644 --- a/nuxt.config.ts +++ b/nuxt.config.ts @@ -1,7 +1,14 @@ export default defineNuxtConfig({ extends: ['docus'], modules: ['@nuxtjs/sitemap'], + css: ['~/assets/css/main.css'], compatibilityDate: '2025-07-15', + routeRules: { + '/cloud/user-guide': { redirect: '/start-here/getting-started' }, + '/cloud/themes': { redirect: '/cloud/web-app#themes' }, + '/local/user-guide': { redirect: '/local/local-install' }, + '/start-here/why-basic-memory': { redirect: '/start-here/what-is-basic-memory' }, + }, app: { head: { meta: [ @@ -26,7 +33,7 @@ export default defineNuxtConfig({ llms: { domain: 'https://docs.basicmemory.com', title: 'Basic Memory Documentation', - description: 'Documentation for Basic Memory - a knowledge management system that gives AI assistants persistent memory through the Model Context Protocol (MCP). Supports both cloud and local deployments.', + description: 'Documentation for Basic Memory, a shared knowledge base for humans, AI tools, agents, and their teams. Covers Basic Memory Cloud and the open-source local project.', full: { title: 'Basic Memory Complete Documentation', description: 'Complete technical documentation for Basic Memory including setup guides, MCP tools reference, knowledge format specifications, and integration guides for Claude, ChatGPT, Gemini, and other AI assistants.', diff --git a/package-lock.json b/package-lock.json index 8d02d5b..8972144 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2569,6 +2569,17 @@ "consola": "^3.2.3" } }, + "node_modules/@nuxt/cli/node_modules/commander": { + "version": "13.1.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-13.1.0.tgz", + "integrity": "sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==", + "license": "MIT", + "optional": true, + "peer": true, + "engines": { + "node": ">=18" + } + }, "node_modules/@nuxt/content": { "version": "3.11.0", "resolved": "https://registry.npmjs.org/@nuxt/content/-/content-3.11.0.tgz", diff --git a/package.json b/package.json index a123901..6a8622e 100644 --- a/package.json +++ b/package.json @@ -7,6 +7,8 @@ "scripts": { "dev": "nuxt dev", "build": "nuxt build", + "check:docs": "node scripts/check-docs.mjs", + "check": "npm run check:docs && npm run build", "generate": "nuxt generate", "preview": "nuxt preview", "start": "node .output/server/index.mjs" diff --git a/public/screenshots/claude/add-connector.png b/public/screenshots/claude/add-connector.png deleted file mode 100644 index 7e9df40..0000000 Binary files a/public/screenshots/claude/add-connector.png and /dev/null differ diff --git a/public/screenshots/claude/configure-tools.png b/public/screenshots/claude/configure-tools.png deleted file mode 100644 index e5e9901..0000000 Binary files a/public/screenshots/claude/configure-tools.png and /dev/null differ diff --git a/public/screenshots/claude/create-first-note.png b/public/screenshots/claude/create-first-note.png deleted file mode 100644 index 891fcd8..0000000 Binary files a/public/screenshots/claude/create-first-note.png and /dev/null differ diff --git a/public/screenshots/claude/oauth-authorize.png b/public/screenshots/claude/oauth-authorize.png deleted file mode 100644 index 3c68790..0000000 Binary files a/public/screenshots/claude/oauth-authorize.png and /dev/null differ diff --git a/public/screenshots/claude/oauth-connect.png b/public/screenshots/claude/oauth-connect.png deleted file mode 100644 index 28881e0..0000000 Binary files a/public/screenshots/claude/oauth-connect.png and /dev/null differ diff --git a/public/screenshots/claude/project-list-response.png b/public/screenshots/claude/project-list-response.png deleted file mode 100644 index 8e146e1..0000000 Binary files a/public/screenshots/claude/project-list-response.png and /dev/null differ diff --git a/public/screenshots/claude/settings-connectors.png b/public/screenshots/claude/settings-connectors.png deleted file mode 100644 index f81daf5..0000000 Binary files a/public/screenshots/claude/settings-connectors.png and /dev/null differ diff --git a/public/screenshots/claude/tools-menu-local.png b/public/screenshots/claude/tools-menu-local.png deleted file mode 100644 index 8d706ae..0000000 Binary files a/public/screenshots/claude/tools-menu-local.png and /dev/null differ diff --git a/public/screenshots/cloud-app/create-snapshot.png b/public/screenshots/cloud-app/create-snapshot.png index 76eacf9..9591183 100644 Binary files a/public/screenshots/cloud-app/create-snapshot.png and b/public/screenshots/cloud-app/create-snapshot.png differ diff --git a/public/screenshots/cloud-app/first-note.png b/public/screenshots/cloud-app/first-note.png deleted file mode 100644 index 677c757..0000000 Binary files a/public/screenshots/cloud-app/first-note.png and /dev/null differ diff --git a/public/screenshots/cloud-app/getting-started-project.png b/public/screenshots/cloud-app/getting-started-project.png new file mode 100644 index 0000000..b5f8b75 Binary files /dev/null and b/public/screenshots/cloud-app/getting-started-project.png differ diff --git a/public/screenshots/cloud-app/restore-files.png b/public/screenshots/cloud-app/restore-files.png index b92e5b4..a483378 100644 Binary files a/public/screenshots/cloud-app/restore-files.png and b/public/screenshots/cloud-app/restore-files.png differ diff --git a/public/screenshots/cloud-app/snapshots-list.png b/public/screenshots/cloud-app/snapshots-list.png index 3fd4f07..6f7f303 100644 Binary files a/public/screenshots/cloud-app/snapshots-list.png and b/public/screenshots/cloud-app/snapshots-list.png differ diff --git a/public/screenshots/cloud-app/themes-settings.png b/public/screenshots/cloud-app/themes-settings.png new file mode 100644 index 0000000..353dd69 Binary files /dev/null and b/public/screenshots/cloud-app/themes-settings.png differ diff --git a/public/screenshots/cloud-app/themes.gif b/public/screenshots/cloud-app/themes.gif deleted file mode 100644 index de5c320..0000000 Binary files a/public/screenshots/cloud-app/themes.gif and /dev/null differ diff --git a/public/screenshots/cloud-app/v2-import-current.png b/public/screenshots/cloud-app/v2-import-current.png new file mode 100644 index 0000000..1c4c61e Binary files /dev/null and b/public/screenshots/cloud-app/v2-import-current.png differ diff --git a/public/screenshots/cloud-app/v2-import-dark.png b/public/screenshots/cloud-app/v2-import-dark.png deleted file mode 100644 index 9c7f208..0000000 Binary files a/public/screenshots/cloud-app/v2-import-dark.png and /dev/null differ diff --git a/public/screenshots/cloud-app/v2-import-light.png b/public/screenshots/cloud-app/v2-import-light.png deleted file mode 100644 index b129c51..0000000 Binary files a/public/screenshots/cloud-app/v2-import-light.png and /dev/null differ diff --git a/public/screenshots/cloud-app/v2-manage-projects-current.png b/public/screenshots/cloud-app/v2-manage-projects-current.png new file mode 100644 index 0000000..9d8e763 Binary files /dev/null and b/public/screenshots/cloud-app/v2-manage-projects-current.png differ diff --git a/public/screenshots/cloud-app/v2-manage-projects-dark.png b/public/screenshots/cloud-app/v2-manage-projects-dark.png deleted file mode 100644 index 51d47ae..0000000 Binary files a/public/screenshots/cloud-app/v2-manage-projects-dark.png and /dev/null differ diff --git a/public/screenshots/cloud-app/v2-manage-projects-light.png b/public/screenshots/cloud-app/v2-manage-projects-light.png deleted file mode 100644 index 48e5749..0000000 Binary files a/public/screenshots/cloud-app/v2-manage-projects-light.png and /dev/null differ diff --git a/public/screenshots/cloud/signup.png b/public/screenshots/cloud/signup.png deleted file mode 100644 index e9f3118..0000000 Binary files a/public/screenshots/cloud/signup.png and /dev/null differ diff --git a/public/screenshots/integrations/chatgpt-add-app-to-chat.png b/public/screenshots/integrations/chatgpt-add-app-to-chat.png new file mode 100644 index 0000000..7bf1298 Binary files /dev/null and b/public/screenshots/integrations/chatgpt-add-app-to-chat.png differ diff --git a/public/screenshots/integrations/chatgpt-tool-confirmation.png b/public/screenshots/integrations/chatgpt-tool-confirmation.png new file mode 100644 index 0000000..b8f0c0b Binary files /dev/null and b/public/screenshots/integrations/chatgpt-tool-confirmation.png differ diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs new file mode 100644 index 0000000..f0c5e09 --- /dev/null +++ b/scripts/check-docs.mjs @@ -0,0 +1,136 @@ +import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs' +import { extname, join, relative, resolve, sep } from 'node:path' + +const root = resolve(import.meta.dirname, '..') +const contentRoot = join(root, 'content') +const publicRoot = join(root, 'public') +const errors = [] +const warnings = [] +const retryableCodes = new Set(['ETIMEDOUT', 'EAGAIN', 'EBUSY']) + +function retry(operation) { + let lastError + for (let attempt = 0; attempt < 4; attempt += 1) { + try { + return operation() + } catch (error) { + lastError = error + if (!retryableCodes.has(error.code) || attempt === 3) throw error + Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 150 * (attempt + 1)) + } + } + throw lastError +} + +const readText = path => retry(() => readFileSync(path, 'utf8')) +const listDirectory = path => retry(() => readdirSync(path)) +const getStat = path => retry(() => statSync(path)) + +function walk(directory, extensions) { + const files = [] + for (const name of listDirectory(directory)) { + const path = join(directory, name) + const stat = getStat(path) + if (stat.isDirectory()) files.push(...walk(path, extensions)) + else if (!extensions || extensions.has(extname(path))) files.push(path) + } + return files +} + +function slug(value) { + return value + .replace(/^\d+\./, '') + .replace(/\.md$/, '') +} + +function routeFor(file) { + const parts = relative(contentRoot, file).split(sep).map(slug) + if (parts.at(-1) === 'index') parts.pop() + return `/${parts.join('/')}`.replace(/\/$/, '') || '/' +} + +const markdownFiles = walk(contentRoot, new Set(['.md'])) +const routes = new Set(markdownFiles.map(routeFor)) +routes.add('/') +routes.add('/changelog') + +const nuxtConfig = readText(join(root, 'nuxt.config.ts')) +for (const match of nuxtConfig.matchAll(/['"]([^'"]+)['"]\s*:\s*\{\s*redirect:/g)) { + routes.add(match[1]) +} + +const referencedScreenshots = new Set() +const linkPattern = /\[[^\]\n]*]\(([^)\s]+)\)|\bto:\s*([^\s]+)|(?:light|dark)="([^"]+)"/g + +for (const file of markdownFiles) { + const source = readText(file) + const display = relative(root, file) + + if (!display.includes(`${sep}2.whats-new${sep}`) + && !display.endsWith(`${sep}changelog.md`) + && !display.endsWith(`${sep}9.v0.19-migration.md`)) { + const versions = [...source.matchAll(/(?$/g, '').split('#')[0].split('?')[0] + if (!target.startsWith('/')) continue + + if (target.startsWith('/screenshots/')) referencedScreenshots.add(target) + + if (target.startsWith('/raw/') + || target === '/llms.txt' + || target === '/llms-full.txt') continue + + if (routes.has(target.replace(/\/$/, '') || '/')) continue + + if (extname(target)) { + if (!existsSync(join(publicRoot, target))) { + errors.push(`${display}: missing public asset ${target}`) + } + continue + } + + errors.push(`${display}: broken internal route ${target}`) + } +} + +const screenshotRoot = join(publicRoot, 'screenshots') +if (existsSync(screenshotRoot)) { + for (const file of walk(screenshotRoot)) { + const publicPath = `/${relative(publicRoot, file).split(sep).join('/')}` + if (!referencedScreenshots.has(publicPath)) { + warnings.push(`unreferenced screenshot: ${publicPath}`) + } + } +} + +const manifestPath = join(root, 'docs', 'screenshots.json') +if (!existsSync(manifestPath)) { + errors.push('docs/screenshots.json is missing') +} else { + const manifest = JSON.parse(readText(manifestPath)) + for (const item of manifest.screenshots || []) { + if (!existsSync(join(publicRoot, item.path))) { + errors.push(`screenshot manifest references missing file: ${item.path}`) + } + if (!item.captured || !item.page || !item.source) { + errors.push(`incomplete screenshot manifest entry: ${item.path}`) + } + } +} + +for (const warning of warnings) console.warn(`WARN ${warning}`) +for (const error of errors) console.error(`ERROR ${error}`) + +if (errors.length) { + console.error(`\nDocs checks failed with ${errors.length} error(s).`) + process.exit(1) +} + +console.log(`Docs checks passed. ${warnings.length} warning(s).`)