basicmachines-co-basic-memory/v15-docs/basic-memory-home.md

BASIC_MEMORY_HOME Environment Variable

Status: Existing (clarified in v0.15.0) Related: project-root-env-var.md

What It Is

BASIC_MEMORY_HOME specifies the location of your default "main" project. This is the primary directory where Basic Memory stores knowledge files when no other project is specified.

Quick Reference

# Default (if not set)
~/basic-memory

# Custom location
export BASIC_MEMORY_HOME=/Users/you/Documents/knowledge-base

How It Works

Default Project Location

When Basic Memory initializes, it creates a "main" project:

# Without BASIC_MEMORY_HOME
projects = {
    "main": "~/basic-memory"  # Default
}

# With BASIC_MEMORY_HOME set
export BASIC_MEMORY_HOME=/Users/you/custom-location
projects = {
    "main": "/Users/you/custom-location"  # Uses env var
}

Only Affects "main" Project

Important: BASIC_MEMORY_HOME ONLY sets the path for the "main" project. Other projects are unaffected.

export BASIC_MEMORY_HOME=/Users/you/my-knowledge

# config.json will have:
{
  "projects": {
    "main": "/Users/you/my-knowledge",    # ← From BASIC_MEMORY_HOME
    "work": "/Users/you/work-notes",       # ← Independently configured
    "personal": "/Users/you/personal-kb"   # ← Independently configured
  }
}

Relationship with BASIC_MEMORY_PROJECT_ROOT

These are separate environment variables with different purposes:

Variable	Purpose	Scope	Default
BASIC_MEMORY_HOME	Where "main" project lives	Single project	~/basic-memory
BASIC_MEMORY_PROJECT_ROOT	Security boundary for ALL projects	All projects	None (unrestricted)

Using Together

# Common containerized setup
export BASIC_MEMORY_HOME=/app/data/basic-memory          # Main project location
export BASIC_MEMORY_PROJECT_ROOT=/app/data               # All projects must be under here

Result:

• Main project created at /app/data/basic-memory
• All other projects must be under /app/data/
• Provides both convenience and security

Comparison Table

Scenario	BASIC_MEMORY_HOME	BASIC_MEMORY_PROJECT_ROOT	Result
Default	Not set	Not set	Main at ~/basic-memory, projects anywhere
Custom main	/Users/you/kb	Not set	Main at /Users/you/kb, projects anywhere
Containerized	/app/data/main	/app/data	Main at /app/data/main, all projects under /app/data/
Secure SaaS	/app/tenant-123/main	/app/tenant-123	Main at /app/tenant-123/main, tenant isolated

Use Cases

Personal Setup (Default)

# Use default location
# BASIC_MEMORY_HOME not set

# Main project created at:
~/basic-memory/

Custom Location

# Store in Documents folder
export BASIC_MEMORY_HOME=~/Documents/BasicMemory

# Main project created at:
~/Documents/BasicMemory/

Synchronized Cloud Folder

# Store in Dropbox/iCloud
export BASIC_MEMORY_HOME=~/Dropbox/BasicMemory

# Main project syncs via Dropbox:
~/Dropbox/BasicMemory/

Docker Deployment

# Mount volume for persistence
docker run \
  -e BASIC_MEMORY_HOME=/app/data/basic-memory \
  -v $(pwd)/data:/app/data \
  basic-memory:latest

# Main project persists at:
./data/basic-memory/  # (host)
/app/data/basic-memory/  # (container)

Multi-User System

# Per-user isolation
export BASIC_MEMORY_HOME=/home/$USER/basic-memory

# Alice's main project:
/home/alice/basic-memory/

# Bob's main project:
/home/bob/basic-memory/

Configuration Examples

Basic Setup

# .bashrc or .zshrc
export BASIC_MEMORY_HOME=~/Documents/knowledge

Docker Compose

services:
  basic-memory:
    environment:
      BASIC_MEMORY_HOME: /app/data/basic-memory
    volumes:
      - ./data:/app/data

Kubernetes

apiVersion: v1
kind: ConfigMap
metadata:
  name: basic-memory-config
data:
  BASIC_MEMORY_HOME: "/app/data/basic-memory"
---
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: basic-memory
    envFrom:
    - configMapRef:
        name: basic-memory-config

systemd Service

[Service]
Environment="BASIC_MEMORY_HOME=/var/lib/basic-memory"
ExecStart=/usr/local/bin/basic-memory serve

Migration

Changing BASIC_MEMORY_HOME

If you need to change the location:

Option 1: Move files

# Stop services
bm sync --stop

# Move data
mv ~/basic-memory ~/Documents/knowledge

# Update environment
export BASIC_MEMORY_HOME=~/Documents/knowledge

# Restart
bm sync

Option 2: Copy and sync

# Copy to new location
cp -r ~/basic-memory ~/Documents/knowledge

# Update environment
export BASIC_MEMORY_HOME=~/Documents/knowledge

# Verify
bm status

# Remove old location once verified
rm -rf ~/basic-memory

From v0.14.x

No changes needed - BASIC_MEMORY_HOME works the same way:

# v0.14.x and v0.15.0+ both use:
export BASIC_MEMORY_HOME=~/my-knowledge

Common Patterns

Development vs Production

# Development (.bashrc)
export BASIC_MEMORY_HOME=~/dev/basic-memory-dev

# Production (systemd/docker)
export BASIC_MEMORY_HOME=/var/lib/basic-memory

Shared Team Setup

# Shared network drive
export BASIC_MEMORY_HOME=/mnt/shared/team-knowledge

# Note: Use with caution, consider file locking

Backup Strategy

# Primary location
export BASIC_MEMORY_HOME=~/basic-memory

# Automated backup script
rsync -av ~/basic-memory/ ~/Backups/basic-memory-$(date +%Y%m%d)/

Verification

Check Current Value

# View environment variable
echo $BASIC_MEMORY_HOME

# View resolved config
bm project list
# Shows actual path for "main" project

Verify Main Project Location

from basic_memory.config import ConfigManager

config = ConfigManager().config
print(config.projects["main"])
# Shows where "main" project is located

Troubleshooting

Main Project Not at Expected Location

Problem: Files not where you expect

Check:

# What's the environment variable?
echo $BASIC_MEMORY_HOME

# Where is main project actually?
bm project list | grep main

Solution: Set environment variable and restart

Permission Errors

Problem: Can't write to BASIC_MEMORY_HOME location

$ bm sync
Error: Permission denied: /var/lib/basic-memory

Solution:

# Fix permissions
sudo chown -R $USER:$USER /var/lib/basic-memory

# Or use accessible location
export BASIC_MEMORY_HOME=~/basic-memory

Conflicts with PROJECT_ROOT

Problem: BASIC_MEMORY_HOME outside PROJECT_ROOT

export BASIC_MEMORY_HOME=/Users/you/kb
export BASIC_MEMORY_PROJECT_ROOT=/app/data

# Error: /Users/you/kb not under /app/data

Solution: Align both variables

export BASIC_MEMORY_HOME=/app/data/basic-memory
export BASIC_MEMORY_PROJECT_ROOT=/app/data

Best Practices

1. Use absolute paths:

   export BASIC_MEMORY_HOME=/Users/you/knowledge  # ✓
   # not: export BASIC_MEMORY_HOME=~/knowledge    # ✗ (may not expand)
   

2. Document the location:

   • Add comment in shell config
   • Document for team if shared

3. Backup regularly:

   • Main project contains your primary knowledge
   • Automate backups of this directory

4. Consider PROJECT_ROOT for security:

   • Use both together in production/containers

5. Test changes:

   • Verify with bm project list after changing

See Also

• project-root-env-var.md - Security constraints for all projects
• env-var-overrides.md - Environment variable precedence
• Project management documentation