--- title: "Projects and folders" description: "Projects are separate knowledge bases in Basic Memory. Learn when to use multiple projects, how folders work inside them, and how cloud routing keeps your data where you want it." canonical_url: "https://docs.basicmemory.com/concepts/projects-and-folders" --- # Projects and folders > Projects are separate knowledge bases in Basic Memory. Learn when to use multiple projects, how folders work inside them, and how cloud routing keeps your data where you want it. Most people start Basic Memory with a single project and a single folder. That works fine for a while, but eventually you need boundaries. Maybe you want work notes separate from personal notes. Maybe you have three clients and their knowledge should never overlap. That is what projects are for. ## What is a project? A project is a separate knowledge base. Each project maps to a folder on disk (or a cloud instance), has its own set of notes, its own knowledge graph, and its own search index. Notes in one project do not appear in another. Relations in one project cannot link to notes in a different project. Think of projects the way you think of separate notebooks, not separate pages in the same notebook. AI tools such as `bm_write` target the project supplied through `project` or a project-qualified path. When several projects are addressable, note and search calls require that explicit scope, even if a default is configured. With only one addressable project, it can be selected implicitly. CLI commands that support a default still use it when their project argument is omitted. You can target a different project at any time, including mid-conversation. ## Creating and managing projects Add a project by pointing Basic Memory at a folder: ```bash bm project add "work" ~/Documents/work-notes bm project add "personal" ~/Documents/personal-notes ``` List your projects: ```bash bm project list ``` Set a default for CLI commands that support default-project selection: ```bash bm project default "work" ``` Switch to a different project in conversation using the MCP tool: ```text Switch to the "personal" project. ``` The AI will simply pass `project="personal"` on its next tool calls — there's no switch step; it discovers your projects with `bm_project(command="list")`. From the CLI, change the fallback for commands that don't specify a project: ```bash bm project default "personal" ``` ## When to use multiple projects The key question is: **do these notes need to be connected, or separate?** If notes should link to each other and show up in the same search results, keep them in the same project. If they should stay isolated, split them. Here are some common patterns: - **Work vs personal.** Keep company knowledge separate from your own notes. Different contexts, different purposes, no accidental leakage. - **Multiple clients.** Each client gets a project. Their notes, decisions, and context stay contained. You can switch between clients mid-conversation. - **A coding project's docs folder.** Point a project at the `docs/` folder inside a repo. The AI builds context about that specific codebase without pulling in unrelated notes. - **A writing project.** A book, a course, or a research paper. Give it a project so its outline, drafts, and references form their own knowledge graph. If you're unsure, start with one project. You can always create another later and move notes into it. ## Searching across projects Projects stay separate, but you can still search several of them at once when you need to. Ask your AI to search everywhere, or name the projects: ```text Search my work and research projects for notes about rate limiting. ``` Behind the scenes, `bm_search` takes `all_projects=True` or, as of [v0.24](https://docs.basicmemory.com/whats-new/v0-24), a `projects` list of names (or project ids) to search together. An unknown name is an error rather than a silent skip. Results from all the chosen projects come back as one ranked list, and each hit says which project it came from so the AI can read it from the right place. ## Folders within a project Inside a project, organize however you like. Create folders, nest them, rename them. The knowledge graph does not care about folder structure. It indexes notes by their content, observations, and relations, not by which directory they live in. Folders are for you. They help you browse and find things visually. But when the AI searches your knowledge base or follows a relation link, it works at the note level, not the folder level. ```text ~/Documents/work-notes/ meetings/ decisions/ architecture/ onboarding/ ``` This is a perfectly good layout. So is a flat folder with everything at the top level. The graph works the same either way. If you'd like folders to be browsable as pages, `bm wiki rebuild` generates an `index.md` for the project root and each folder, plus a `log.md` of recent changes. It never overwrites an `index.md` or `log.md` you wrote yourself. For sharing a project outside Basic Memory, `bm okf export` writes it as a static Open Knowledge Format bundle. See the [CLI Reference](https://docs.basicmemory.com/reference/cli-reference) for both. ## Mixing local and cloud projects You can keep some projects local and route others to Basic Memory Cloud. Your personal notes stay on your machine. Your work projects sync to the cloud and are accessible from any device. Both are available in the same conversation. This is configured through per-project cloud routing. Each project independently decides whether it talks to a local database or a cloud instance. For setup details, see the [Local and Cloud Routing](https://docs.basicmemory.com/cloud/routing) guide. ## Project-prefixed permalinks By default, Basic Memory prefixes newly generated permalinks with the project name, so notes with the same title in different projects stay distinct: ```text memory://work/architecture/auth-system memory://personal/reading-list ``` This means a note called "Auth System" in your work project and a note called "Auth System" in your personal project are distinct and addressable. The prefix is added when a permalink is generated — existing permalinks aren't rewritten. You don't need to manage it yourself. For more on how memory URLs work, see [Memory URLs](https://docs.basicmemory.com/concepts/memory-urls). ## Next steps Learn the note structure with observations and relations. Keep some projects local and route others to the cloud. How memory:// URLs address notes across projects. Use notes in the Cloud app. ## Sitemap See the full [sitemap](https://docs.basicmemory.com/sitemap.md) for all pages.