From d6194295870a38f8034263d8a311d818adf712c4 Mon Sep 17 00:00:00 2001 From: nellins Date: Wed, 10 Jun 2026 17:15:07 -0500 Subject: [PATCH] Overhaul Basic Memory docs --- .github/workflows/docs-check.yml | 18 + CONTRIBUTING.md | 22 + app/app.config.ts | 9 + app/assets/css/main.css | 446 ++++++++ app/components/app/AppHeaderBody.vue | 28 + app/components/app/AppHeaderCTA.vue | 25 + app/components/app/AppHeaderCenter.vue | 36 + app/components/app/AppHeaderLogo.vue | 13 + app/components/content/DocsHomeSearch.vue | 16 + app/components/docs/DocsAsideLeftBody.vue | 12 + app/composables/useDocsNavigation.ts | 212 ++++ .../1.start-here/1.what-is-basic-memory.md | 440 ++------ content/1.start-here/2.quickstart-cloud.md | 245 ++--- content/1.start-here/3.quickstart-local.md | 316 +----- content/1.start-here/4.getting-started.md | 250 +++-- content/1.start-here/5.why-basic-memory.md | 131 --- content/2.whats-new/0.teams.md | 12 +- content/2.whats-new/1.v0.21.0.md | 10 +- content/2.whats-new/2.hermes-plugin.md | Bin 2468 -> 2468 bytes content/2.whats-new/3.cloud.md | 2 +- content/2.whats-new/4.changelog.md | 14 +- content/3.cloud/01.cloud-guide.md | 399 ++----- content/3.cloud/02.web-app.md | 143 ++- content/3.cloud/03.cloud-sync.md | 459 ++------ content/3.cloud/04.cloud-cli.md | 198 ++++ content/3.cloud/04.user-guide.md | 480 --------- content/3.cloud/05.cloud-snapshots.md | 232 ++--- content/3.cloud/06.themes.md | 241 ----- content/3.cloud/07.api-keys.md | 97 +- content/3.cloud/08.routing.md | 180 ++-- content/3.cloud/09.shared-notes.md | 9 +- .../3.cloud/10.edit-locally-and-in-the-app.md | 14 +- content/3.cloud/11.restore-lost-content.md | 18 +- content/3.cloud/12.file-history.md | 22 +- content/4.teams/1.about.md | 57 +- content/4.teams/2.join-a-team.md | 16 +- content/5.local/1.local-install.md | 90 +- content/5.local/2.cli-basics.md | 70 +- content/5.local/3.mcp-tools-local.md | 55 +- content/5.local/4.user-guide.md | 642 ------------ content/6.concepts/0.vs-built-in-memory.md | 6 +- content/6.concepts/1.knowledge-format.md | 2 +- content/6.concepts/2.projects-and-folders.md | 2 +- .../3.observations-and-relations.md | 226 ++-- content/6.concepts/5.canvas.md | 100 -- content/6.concepts/6.schema-system.md | 2 +- content/7.integrations/0.index.md | 149 +++ content/7.integrations/1.claude-desktop.md | 150 +-- content/7.integrations/11.hermes.md | 4 +- .../7.integrations/12.claude-research-mode.md | 82 -- content/7.integrations/2.claude-code.md | 144 +-- content/7.integrations/3.chatgpt.md | 114 +- content/7.integrations/4.gemini.md | 158 +-- content/7.integrations/5.codex.md | 231 +--- content/7.integrations/6.cursor.md | 149 +-- content/7.integrations/7.vscode.md | 189 +--- content/7.integrations/8.obsidian.md | 156 +-- content/7.integrations/9.skills.md | 13 +- content/8.how-to/3.research-learning.md | 2 +- content/8.how-to/5.personal-knowledge.md | 6 +- content/9.reference/1.cli-reference.md | 88 +- content/9.reference/10.contact-support.md | 97 ++ content/9.reference/2.mcp-tools-reference.md | 66 +- content/9.reference/3.ai-assistant-guide.md | 985 +----------------- .../9.reference/4.technical-information.md | 336 +----- content/9.reference/5.troubleshooting.md | 634 +++++------ content/9.reference/6.configuration.md | 4 +- content/9.reference/7.docker.md | 301 +++--- content/9.reference/9.v0.19-migration.md | 2 +- content/changelog.md | 13 + content/index.md | 255 +++-- docs/docs-audit.md | 146 +++ docs/handoff-2026-06-09-review.md | 85 ++ docs/screenshots.json | 68 ++ nuxt.config.ts | 9 +- package-lock.json | 11 + package.json | 2 + public/screenshots/claude/add-connector.png | Bin 70459 -> 0 bytes public/screenshots/claude/configure-tools.png | Bin 43455 -> 0 bytes .../screenshots/claude/create-first-note.png | Bin 100417 -> 0 bytes public/screenshots/claude/oauth-authorize.png | Bin 44916 -> 0 bytes public/screenshots/claude/oauth-connect.png | Bin 13373 -> 0 bytes .../claude/project-list-response.png | Bin 64052 -> 0 bytes .../claude/settings-connectors.png | Bin 12005 -> 0 bytes .../screenshots/claude/tools-menu-local.png | Bin 72366 -> 0 bytes .../screenshots/cloud-app/create-snapshot.png | Bin 42658 -> 77385 bytes public/screenshots/cloud-app/first-note.png | Bin 223151 -> 0 bytes .../cloud-app/getting-started-project.png | Bin 0 -> 562696 bytes .../screenshots/cloud-app/restore-files.png | Bin 84016 -> 216108 bytes .../screenshots/cloud-app/snapshots-list.png | Bin 57787 -> 53773 bytes .../screenshots/cloud-app/themes-settings.png | Bin 0 -> 127062 bytes public/screenshots/cloud-app/themes.gif | Bin 4287729 -> 0 bytes .../cloud-app/v2-import-current.png | Bin 0 -> 60980 bytes .../screenshots/cloud-app/v2-import-dark.png | Bin 251901 -> 0 bytes .../screenshots/cloud-app/v2-import-light.png | Bin 257436 -> 0 bytes .../cloud-app/v2-manage-projects-current.png | Bin 0 -> 46819 bytes .../cloud-app/v2-manage-projects-dark.png | Bin 142183 -> 0 bytes .../cloud-app/v2-manage-projects-light.png | Bin 143734 -> 0 bytes public/screenshots/cloud/signup.png | Bin 46812 -> 0 bytes .../integrations/chatgpt-add-app-to-chat.png | Bin 0 -> 213903 bytes .../chatgpt-tool-confirmation.png | Bin 0 -> 52716 bytes scripts/check-docs.mjs | 136 +++ 102 files changed, 4149 insertions(+), 6653 deletions(-) create mode 100644 .github/workflows/docs-check.yml create mode 100644 CONTRIBUTING.md create mode 100644 app/assets/css/main.css create mode 100644 app/components/app/AppHeaderBody.vue create mode 100644 app/components/app/AppHeaderCTA.vue create mode 100644 app/components/app/AppHeaderCenter.vue create mode 100644 app/components/app/AppHeaderLogo.vue create mode 100644 app/components/content/DocsHomeSearch.vue create mode 100644 app/components/docs/DocsAsideLeftBody.vue create mode 100644 app/composables/useDocsNavigation.ts delete mode 100644 content/1.start-here/5.why-basic-memory.md create mode 100644 content/3.cloud/04.cloud-cli.md delete mode 100644 content/3.cloud/04.user-guide.md delete mode 100644 content/3.cloud/06.themes.md delete mode 100644 content/5.local/4.user-guide.md delete mode 100644 content/6.concepts/5.canvas.md create mode 100644 content/7.integrations/0.index.md delete mode 100644 content/7.integrations/12.claude-research-mode.md create mode 100644 content/9.reference/10.contact-support.md create mode 100644 content/changelog.md create mode 100644 docs/docs-audit.md create mode 100644 docs/handoff-2026-06-09-review.md create mode 100644 docs/screenshots.json delete mode 100644 public/screenshots/claude/add-connector.png delete mode 100644 public/screenshots/claude/configure-tools.png delete mode 100644 public/screenshots/claude/create-first-note.png delete mode 100644 public/screenshots/claude/oauth-authorize.png delete mode 100644 public/screenshots/claude/oauth-connect.png delete mode 100644 public/screenshots/claude/project-list-response.png delete mode 100644 public/screenshots/claude/settings-connectors.png delete mode 100644 public/screenshots/claude/tools-menu-local.png delete mode 100644 public/screenshots/cloud-app/first-note.png create mode 100644 public/screenshots/cloud-app/getting-started-project.png create mode 100644 public/screenshots/cloud-app/themes-settings.png delete mode 100644 public/screenshots/cloud-app/themes.gif create mode 100644 public/screenshots/cloud-app/v2-import-current.png delete mode 100644 public/screenshots/cloud-app/v2-import-dark.png delete mode 100644 public/screenshots/cloud-app/v2-import-light.png create mode 100644 public/screenshots/cloud-app/v2-manage-projects-current.png delete mode 100644 public/screenshots/cloud-app/v2-manage-projects-dark.png delete mode 100644 public/screenshots/cloud-app/v2-manage-projects-light.png delete mode 100644 public/screenshots/cloud/signup.png create mode 100644 public/screenshots/integrations/chatgpt-add-app-to-chat.png create mode 100644 public/screenshots/integrations/chatgpt-tool-confirmation.png create mode 100644 scripts/check-docs.mjs 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 775f939fd07203bac942df6bbc2464284d55868e..f017f6f7e45383541fa641a8e09c87d964436ca1 100644 GIT binary patch delta 122 zcmZ1?yhM0ICOcbhVo7GQ!sIM=S=ZqF+*AdR)S}$fVg<+a)VvafqSTz!#9|;fFEuqq zAu$gktXrI!lB$rLpIZRbo0OT8SyHJ0WF}`Qq~#Y)p2#jPXsuA3nyOHe0aR65R0K3> M6UP!pb_NIl06P;XRsaA1 delta 122 zcmZ1?yhM0ICOf0<