Projects and folders

Most people start Basic Memory with a single project and a single folder. That works fine for a while, but eventually you need boundaries. Maybe you want work notes separate from personal notes. Maybe you have three clients and their knowledge should never overlap. That is what projects are for.

What is a project?

A project is a separate knowledge base. Each project maps to a folder on disk (or a cloud instance), has its own set of notes, its own knowledge graph, and its own search index. Notes in one project do not appear in another. Relations in one project cannot link to notes in a different project.

Think of projects the way you think of separate notebooks, not separate pages in the same notebook.

When you run a command or an AI tool like write_note, it targets whichever project is currently active. You can switch projects at any time, and one project is always set as the default so you do not have to specify it every time.

Creating and managing projects

Add a project by pointing Basic Memory at a folder:

bm project add "work" ~/Documents/work-notes
bm project add "personal" ~/Documents/personal-notes

List your projects:

bm project list

Set a default so commands go there automatically:

bm project default "work"

Switch to a different project in conversation using the MCP tool:

Switch to the "personal" project.

The AI will call switch_project behind the scenes. You can also use the CLI:

bm project switch "personal"

When to use multiple projects

The key question is: do these notes need to be connected, or separate?

If notes should link to each other and show up in the same search results, keep them in the same project. If they should stay isolated, split them.

Here are some common patterns:

• Work vs personal. Keep company knowledge separate from your own notes. Different contexts, different purposes, no accidental leakage.
• Multiple clients. Each client gets a project. Their notes, decisions, and context stay contained. You can switch between clients mid-conversation.
• A coding project's docs folder. Point a project at the docs/ folder inside a repo. The AI builds context about that specific codebase without pulling in unrelated notes.
• A writing project. A book, a course, or a research paper. Give it a project so its outline, drafts, and references form their own knowledge graph. If you're unsure, start with one project. You can always create another later and move notes into it.

Folders within a project

Inside a project, organize however you like. Create folders, nest them, rename them. The knowledge graph does not care about folder structure. It indexes notes by their content, observations, and relations, not by which directory they live in.

Folders are for you. They help you browse and find things visually. But when the AI searches your knowledge base or follows a relation link, it works at the note level, not the folder level.

~/Documents/work-notes/
  meetings/
  decisions/
  architecture/
  onboarding/

This is a perfectly good layout. So is a flat folder with everything at the top level. The graph works the same either way.

Mixing local and cloud projects

Starting in v0.19, you can keep some projects local and route others to Basic Memory Cloud. Your personal notes stay on your machine. Your work projects sync to the cloud and are accessible from any device. Both are available in the same conversation.

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 guide.

Project-prefixed permalinks

When you have multiple projects, Basic Memory automatically prefixes note permalinks with the project name to prevent ambiguity:

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 automatically when notes are indexed. You do not need to manage it yourself.

For more on how memory URLs work, see Memory URLs.

Next steps