basicmachines-co-basic-memory/docs/Docker.md

Docker Setup Guide

Basic Memory can be run in Docker containers to provide a consistent, isolated environment for your knowledge management system. This is particularly useful for integrating with existing Dockerized MCP servers or for deployment scenarios.

Quick Start

Option 1: Using Docker Compose (Recommended)

1. Clone the repository:

   git clone https://github.com/basicmachines-co/basic-memory.git
   cd basic-memory
   

2. Update the docker-compose.yml: Edit the volume mount to point to your Obsidian vault:

   volumes:
     # Change './obsidian-vault' to your actual directory path
     - /path/to/your/obsidian-vault:/data/knowledge:rw
   

3. Start the container:

   docker-compose up -d
   

Option 2: Using Docker CLI

# Build the image
docker build -t basic-memory .

# Run with volume mounting
docker run -d \
  --name basic-memory-server \
  -v /path/to/your/obsidian-vault:/data/knowledge:rw \
  -v basic-memory-config:/root/.basic-memory:rw \
  -e BASIC_MEMORY_DEFAULT_PROJECT=main \
  basic-memory

Configuration

Volume Mounts

Basic Memory requires several volume mounts for proper operation:

1. Knowledge Directory (Required):

   - /path/to/your/obsidian-vault:/data/knowledge:rw
   

   Mount your Obsidian vault or knowledge base directory.

2. Configuration and Database (Recommended):

   - basic-memory-config:/root/.basic-memory:rw
   

   Persistent storage for configuration and SQLite database.

You can edit the basic-memory config.json file located in the /root/.basic-memory/config.json after Basic Memory starts.

3. Multiple Projects (Optional):

   - /path/to/project1:/data/projects/project1:rw
   - /path/to/project2:/data/projects/project2:rw
   

You can edit the basic-memory config.json file located in the /root/.basic-memory/config.json

CLI Commands via Docker

You can run Basic Memory CLI commands inside the container using docker exec:

Basic Commands

# Check status
docker exec basic-memory-server basic-memory status

# Sync files
docker exec basic-memory-server basic-memory sync

# Show help
docker exec basic-memory-server basic-memory --help

Managing Projects with Volume Mounts

When using Docker volumes, you'll need to configure projects to point to your mounted directories:

1. Check current configuration:

   docker exec basic-memory-server cat /root/.basic-memory/config.json
   

2. Add a project for your mounted volume:

   # If you mounted /path/to/your/vault to /data/knowledge
   docker exec basic-memory-server basic-memory project create my-vault /data/knowledge
   
   # Set it as default
   docker exec basic-memory-server basic-memory project set-default my-vault
   

3. Sync the new project:

   docker exec basic-memory-server basic-memory sync
   

Example: Setting up an Obsidian Vault

If you mounted your Obsidian vault like this in docker-compose.yml:

volumes:
  - /Users/yourname/Documents/ObsidianVault:/data/obsidian:rw

Then configure it:

# Create project pointing to mounted vault
docker exec basic-memory-server basic-memory project create obsidian /data/obsidian

# Set as default
docker exec basic-memory-server basic-memory project set-default obsidian

# Sync to index all files
docker exec basic-memory-server basic-memory sync

Environment Variables

Configure Basic Memory using environment variables:

environment:

  # Default project
  - BASIC_MEMORY_DEFAULT_PROJECT=main

  # Enable real-time sync
  - BASIC_MEMORY_SYNC_CHANGES=true

  # Logging level
  - BASIC_MEMORY_LOG_LEVEL=INFO

  # Sync delay in milliseconds
  - BASIC_MEMORY_SYNC_DELAY=1000

File Permissions

Linux/macOS

Ensure your knowledge directories have proper permissions:

# Make directories readable/writable
chmod -R 755 /path/to/your/obsidian-vault

# If using specific user/group
chown -R $USER:$USER /path/to/your/obsidian-vault

Windows

When using Docker Desktop on Windows, ensure the directories are shared:

1. Open Docker Desktop
2. Go to Settings → Resources → File Sharing
3. Add your knowledge directory path
4. Apply & Restart

Troubleshooting

Common Issues

1. File Watching Not Working:

   • Ensure volume mounts are read-write (:rw)
   • Check directory permissions
   • On Linux, may need to increase inotify limits:

     echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
     sudo sysctl -p
     

2. Configuration Not Persisting:

   • Use named volumes for /root/.basic-memory
   • Check volume mount permissions

3. Network Connectivity:

   • For HTTP transport, ensure port 8000 is exposed
   • Check firewall settings

Debug Mode

Run with debug logging:

environment:
  - BASIC_MEMORY_LOG_LEVEL=DEBUG

View logs:

docker-compose logs -f basic-memory

Security Considerations

1. Use Non-Root User: The default Dockerfile runs as root. Consider creating a custom Dockerfile with a non-root user for production.

2. Volume Permissions: Ensure mounted directories have appropriate permissions and don't expose sensitive data.

3. Network Security: If using HTTP transport, consider using reverse proxy with SSL/TLS and authentication if the endpoint is available on a network.

4. IMPORTANT: the https have no auhorization. They should not be exposed on a public network.

Integration Examples

Claude Desktop with Docker

The recommended way to connect Claude Desktop to the containerized Basic Memory is using mcp-proxy, which converts the HTTP transport to STDIO that Claude Desktop expects:

1. Start the Docker container:

   docker-compose up -d
   

2. Configure Claude Desktop to use mcp-proxy:

   {
     "mcpServers": {
       "basic-memory": {
         "command": "uvx",
         "args": [
           "mcp-proxy",
           "http://localhost:8000/mcp"
         ]
       }
     }
   }
   

Support

For Docker-specific issues:

1. Check the troubleshooting section above
2. Review container logs: docker-compose logs basic-memory
3. Verify volume mounts: docker inspect basic-memory-server
4. Test file permissions: docker exec basic-memory-server ls -la /root

For general Basic Memory support, see the main README and documentation.