Overview Basic Memory supports multiple projects, allowing you to organize knowledge into separate, independent knowledge bases. Each project has:
Its own directory of Markdown files
Separate SQLite database for indexing
Independent configuration and settings
Isolated knowledge graph
Why Use Multiple Projects?
Work vs Personal Keep professional and personal knowledge separate
Team Collaboration Share project-specific knowledge with teammates
Client Work Maintain separate knowledge bases for different clients
Research Topics Organize different research areas independently
Project Management List Projects View all available projects:
basic-memory project list
Output:
Available projects: * work ~/work-notes (default) research ~/research-notes personal ~/personal-notes
Create Project Create a new project:
basic-memory project add "project-name" ~/path/to/directory
Examples:
Work Project
Research Project
Client Project
basic-memory project add "work" ~/Documents/work-notes
Set Default Project Set which project is used by default:
basic-memory project default "project-name"
Example:
basic-memory project default "work"
Remove Project Remove a project from configuration (files remain on disk):
basic-memory project remove "project-name"
This removes the project from Basic Memory’s configuration and deletes the database, but leaves files on disk unchanged. You can re-add the project later.
Project Info View detailed information about a project:
basic-memory project info "project-name"
Output:
Project: work Path: /Users/alice/work-notes Status: Active Entities: 142 Observations: 1,234 Relations: 387 Last synced: 2024-01-15 14:32:00
Using Projects with MCP Claude Desktop Configuration Configure Claude Desktop to use a specific project:
Single Project
Multiple Projects
Default Project
Configure for one project: { "mcpServers" : { "basic-memory" : { "command" : "uvx" , "args" : [ "basic-memory" , "mcp" , "--project" , "work" ] } } }
Set up multiple MCP servers for different projects: { "mcpServers" : { "basic-memory-work" : { "command" : "uvx" , "args" : [ "basic-memory" , "mcp" , "--project" , "work" ] }, "basic-memory-research" : { "command" : "uvx" , "args" : [ "basic-memory" , "mcp" , "--project" , "research" ] } } }
Each server appears separately in Claude Desktop. Use the default project: { "mcpServers" : { "basic-memory" : { "command" : "uvx" , "args" : [ "basic-memory" , "mcp" ] } } }
Uses whichever project is set as default. VS Code Configuration Configure VS Code for project-specific setups:
Create Workspace Settings
In your repository, create .vscode/mcp.json: { "servers" : { "basic-memory" : { "command" : "uvx" , "args" : [ "basic-memory" , "mcp" , "--project" , "my-project" ] } } }
Commit Configuration
Share the configuration with your team: git add .vscode/mcp.json git commit -m "Add Basic Memory configuration"
Team Setup
Team members need to:
Install Basic Memory
Create the same project:
basic-memory project add "my-project" ~/path/to/shared/docs
Sync the project:
basic-memory sync --project my-project
Project Synchronization Manual Sync Sync a specific project:
basic-memory sync --project "project-name"
Watch Mode Real-time sync for active development:
basic-memory sync --watch --project "project-name"
Sync Status Check sync status for a project:
basic-memory status --project "project-name"
Cloud Projects Cloud features require an active Basic Memory Cloud subscription.
Cloud Authentication Authenticate with Basic Memory Cloud:
Set Project to Cloud Mode Route a project through the cloud:
basic-memory project set-cloud "project-name"
This enables:
Cross-device access
Team collaboration
Cloud backup
Web and mobile access
Set Project to Local Mode Revert a project to local-only:
basic-memory project set-local "project-name"
Bidirectional Sync Sync between local and cloud:
# One-way sync (local → cloud) basic-memory project sync "project-name" # Two-way sync basic-memory project bisync "project-name"
Project Integrity Check Verify project consistency:
basic-memory project check "project-name"
Project Organization Strategies By Domain Organize by knowledge domain:
basic-memory project add "work" ~/knowledge/work basic-memory project add "personal" ~/knowledge/personal basic-memory project add "learning" ~/knowledge/learning
By Client Separate client work:
basic-memory project add "client-acme" ~/clients/acme/knowledge basic-memory project add "client-beta" ~/clients/beta/knowledge basic-memory project add "internal" ~/knowledge/internal
By Time Period Archive by time:
basic-memory project add "current" ~/knowledge/current basic-memory project add "archive-2023" ~/knowledge/archive/2023 basic-memory project add "archive-2024" ~/knowledge/archive/2024
By Team Team-based organization:
basic-memory project add "engineering" ~/teams/engineering basic-memory project add "product" ~/teams/product basic-memory project add "design" ~/teams/design
Cross-Project References Memory URLs with Projects Reference notes in other projects using memory:// URLs:
memory://project-name/note-path
Examples:
memory://work/authentication-system memory://research/semantic-search-paper memory://personal/coffee-brewing
Building Context Across Projects When using build_context, specify the project:
build_context( "memory://work/authentication-system" , project = "work" )
Searching Multiple Projects Search within specific projects:
# Search in work project search_notes( "authentication" , project = "work" ) # Search in research project search_notes( "embeddings" , project = "research" )
Each MCP server instance is tied to one project. To search across projects, you need multiple MCP server configurations.
Project Migration Moving Projects Move a project to a new location:
Move Files
mv ~/old-location ~/new-location
Update Configuration
basic-memory project move "project-name" ~/new-location
Verify
basic-memory project info "project-name"
Exporting Projects Back up or export a project:
# Create archive tar -czf project-backup.tar.gz ~/path/to/project # Copy to backup location cp project-backup.tar.gz ~/backups/
Importing Projects Restore from backup:
Extract Archive
tar -xzf project-backup.tar.gz -C ~/restored-project
Add Project
basic-memory project add "restored" ~/restored-project
Sync
basic-memory sync --project "restored"
Best Practices
Each project should have a clear scope: Good:
work - All work-related knowledgeresearch-ml - Machine learning researchpersonal-health - Health and fitness notes Avoid:
misc - Mixed unrelated contenteverything - Single project for all knowledge
Choose a naming convention: # Domain-based work, personal, research # Team-based team-eng, team-product, team-design # Client-based client-acme, client-beta, client-gamma
Back up important projects: # Automated backup script #!/bin/bash DATE = $( date +%Y%m%d ) tar -czf ~/backups/work- $DATE .tar.gz ~/work-notes
Always sync before switching projects: basic-memory sync --project current basic-memory project default new-project basic-memory sync --project new-project
Create a README in each project: # Work Knowledge Base This project contains all work-related documentation including: - Architecture decisions - Meeting notes - Technical documentation - Project planning
Troubleshooting
Check available projects: basic-memory project list
Add the project if missing: basic-memory project add "project-name" ~/path
Diagnose sync problems: # Check status basic-memory status --project "project-name" # Run doctor basic-memory doctor --project "project-name" # Force sync basic-memory sync --project "project-name"
If multiple projects use the same path: # List projects to find conflict basic-memory project list # Update path for one project basic-memory project move "project-name" ~/new-path
Rebuild database if corrupted: # Backup current database cp ~/.basic-memory/projects/project-name.db ~/backup.db # Remove and re-add project basic-memory project remove "project-name" basic-memory project add "project-name" ~/path # Re-sync basic-memory sync --project "project-name"
Next Steps
Writing Notes Learn how to structure notes effectively
Searching Master search across projects
Cloud Sync Enable cloud features for projects
CLI Reference Complete CLI documentation