Skip to content

Configuration

Jump to bottom
Temp edited this page Dec 8, 2025 · 42 revisions

Configuration

Configure Memory Journal MCP Server for project context management in AI-assisted development workflows.

MCP Client Configuration

Cursor IDE

Edit ~/.cursor/mcp.json:

PyPI Installation:

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp"
    }
  }
}

Docker Installation:

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "./data:/app/data",
        "writenotenow/memory-journal-mcp:latest",
        "python", "src/server.py"
      ]
    }
  }
}

From Source:

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "python",
      "args": ["/full/path/to/memory-journal-mcp/src/server.py"],
      "cwd": "/full/path/to/memory-journal-mcp",
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

Note: The cwd parameter is required for proper Git context detection. The server will change to the project root directory on startup.

Database Configuration

Database Location

PyPI (default):

  • Database: ~/.memory-journal/memory_journal.db
  • Auto-creates on first run

Docker:

  • Container path: /app/data/memory_journal.db
  • Host path: ./data/memory_journal.db (mounted volume)

Custom Path (Docker):

{
  "args": [
    "run", "--rm", "-i",
    "-v", "/my/custom/path:/app/data",
    "-e", "DB_PATH=/app/data/my_journal.db",
    "writenotenow/memory-journal-mcp:latest",
    "python", "src/server.py"
  ]
}

Database Backup

Simple backup:

# PyPI
cp ~/.memory-journal/memory_journal.db ~/backups/journal-$(date +%Y%m%d).db

# Docker
cp ./data/memory_journal.db ./backups/journal-$(date +%Y%m%d).db

Automated backup:

#!/bin/bash
# daily-backup.sh
DATE=$(date +%Y%m%d)
cp ./data/memory_journal.db "./backups/journal-$DATE.db"
# Keep last 30 days
find ./backups -name "journal-*.db" -mtime +30 -delete

Performance Configuration

SQLite Settings

The server automatically configures SQLite for optimal performance:

PRAGMA journal_mode = WAL;          # Write-Ahead Logging
PRAGMA synchronous = NORMAL;         # Balance speed/safety
PRAGMA cache_size = -64000;          # 64MB cache
PRAGMA mmap_size = 268435456;        # 256MB memory-mapped I/O
PRAGMA temp_store = MEMORY;          # Temp tables in memory
PRAGMA busy_timeout = 30000;         # 30s timeout

These settings provide:

  • Better concurrency - Multiple readers, one writer
  • Crash recovery - WAL mode is crash-safe
  • Performance - Large caches and memory-mapped I/O

Startup Performance

v2.1.0 optimization:

  • Lazy loading of ML dependencies with initialization fix
  • Startup time: 2-3 seconds (vs 14s in v1.0)
  • First semantic search: <1 second

Disable semantic search (faster startup):

# Don't install optional dependencies
pip install memory-journal-mcp
# (skip: pip install sentence-transformers faiss-cpu)

Git Integration

Auto-Context Capture

By default, create_entry captures Git context automatically.

Disable for a single entry:

create_entry({
  content: "Entry without Git context",
  auto_context: false
})

What's captured:

  • Repository name and path
  • Current branch
  • Latest commit (hash + message)
  • Working directory
  • Timestamp

GitHub Issues

Enable GitHub issue capture:

  1. Install GitHub CLI:
# macOS
brew install gh

# Windows
winget install GitHub.cli

# Linux
sudo apt install gh
  1. Authenticate:
gh auth login
  1. Issues now appear in context bundles!

Disable issue capture:

  • Uninstall gh or ensure it's not in PATH
  • Context capture continues without issues

Optional Features

Semantic Search

Enable:

pip install sentence-transformers faiss-cpu

Features:

  • Vector similarity search
  • Concept-based finding
  • ML-powered relevance

Requirements:

  • ~500MB disk space (model + dependencies)
  • 2GB RAM recommended
  • First search: 15s (loads model)
  • Subsequent: <1s

Disable:

  • Don't install dependencies
  • Server works perfectly without semantic search

Environment Variables

Docker Environment Variables

DEBUG mode:

{
  "args": [
    "-e", "DEBUG=true",
    ...
  ]
}

Custom database path:

{
  "args": [
    "-e", "DB_PATH=/app/data/custom.db",
    ...
  ]
}

Tool filtering (reduce token usage by up to 69%):

{
  "args": [
    "-e", "MEMORY_JOURNAL_MCP_TOOL_FILTER=-test,-admin",
    ...
  ]
}

All environment variables:

  • DEBUG - Enable debug logging (default: false)
  • DB_PATH - Custom database path (default: /app/data/memory_journal.db)
  • MEMORY_JOURNAL_MCP_TOOL_FILTER - Comma-separated tool filter rules (see Tool Filtering)
  • GITHUB_TOKEN - GitHub Personal Access Token for Projects/Issues/PRs
  • GITHUB_ORG_TOKEN - Separate token for organization projects (optional)
  • DEFAULT_ORG - Default organization name for org project lookups

Security Configuration

Data Privacy

Local-first:

  • All data stored locally in SQLite
  • No external API calls
  • No telemetry or analytics
  • You own your data

Docker security:

  • Non-root user execution
  • Minimal Alpine base
  • No privileged access
  • Volume-mounted data only

Input Validation

Built-in security:

  • Max entry size: 50KB
  • Max tag length: 100 chars
  • Parameterized SQL queries
  • SQL injection prevention

Advanced Configuration

Multiple Databases

Run multiple instances with different databases:

Instance 1 (work):

{
  "memory-journal-work": {
    "command": "docker",
    "args": [
      "run", "--rm", "-i",
      "-v", "./work-data:/app/data",
      "writenotenow/memory-journal-mcp:latest",
      "python", "src/server.py"
    ]
  }
}

Instance 2 (personal):

{
  "memory-journal-personal": {
    "command": "docker",
    "args": [
      "run", "--rm", "-i",
      "-v", "./personal-data:/app/data",
      "writenotenow/memory-journal-mcp:latest",
      "python", "src/server.py"
    ]
  }
}

Custom Docker Image

Build with modifications:

# Clone repo
git clone https://github.com/neverinfamous/memory-journal-mcp.git
cd memory-journal-mcp

# Modify code
# ...

# Build custom image
docker build -t my-memory-journal .

# Use in config
{
  "command": "docker",
  "args": [
    "run", "--rm", "-i",
    "-v", "./data:/app/data",
    "my-memory-journal",
    "python", "src/server.py"
  ]
}

Troubleshooting Configuration

Server Won't Start

Check MCP config syntax:

# Validate JSON
python -m json.tool ~/.cursor/mcp.json

Check paths:

# PyPI - verify package
python -c "import memory_journal_mcp; print('OK')"

# Docker - verify image
docker images | grep memory-journal

# Source - verify path
ls /full/path/to/memory-journal-mcp/src/server.py

Database Issues

Permissions:

# Ensure writable
chmod 755 ./data
touch ./data/test.db && rm ./data/test.db

Corruption:

# Check integrity
sqlite3 ./data/memory_journal.db "PRAGMA integrity_check;"

# Restore from backup
cp ./backups/journal-20251004.db ./data/memory_journal.db

Performance Issues

Slow startup:

  • Check you're on v2.1.0 (includes all performance optimizations)
  • Verify ML dependencies aren't blocking
  • Check system resources

Slow queries:

  • Run ANALYZE: included in maintenance
  • Check database size: ls -lh ./data/memory_journal.db
  • Consider archiving old entries

Windows-Specific Issues

Git operations hang or timeout:

  • Cause: Git subprocess calls inherit stdin from MCP server's stdio channel
  • Fixed in: v2.0.1+ (all subprocess calls use stdin=DEVNULL)
  • Symptom: Context gathering times out, Git commands never complete
  • Solution: Upgrade to latest version

GitHub Projects return empty arrays:

  • Check token scope: Token must have read:project or project scope
  • Verify in Cursor MCP config: env.GITHUB_TOKEN is set correctly
  • Test token: Run gh api graphql -f query='{ viewer { login } }' to verify
  • Note: Old REST API endpoints return HTTP 410 (deprecated)

Working directory issues:

  • Symptom: Git context shows "Not a Git repository"
  • Cause: MCP server not starting in project directory
  • Solution: Add "cwd": "/path/to/project" to MCP configuration
  • Note: Server automatically changes to project root on startup (v2.0.1+)

Configuration Templates

Minimal (No semantic search)

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp"
    }
  }
}

Full Features (Docker)

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "./memory-journal-data:/app/data",
        "writenotenow/memory-journal-mcp:latest",
        "python", "src/server.py"
      ]
    }
  }
}

Lightweight (Core Only - 69% Token Savings)

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "env": {
        "MEMORY_JOURNAL_MCP_TOOL_FILTER": "-search,-analytics,-relationships,-export,-admin,-test"
      }
    }
  }
}

See Tool Filtering for all configurations and token savings.

Development (Source + Debug)

{
  "mcpServers": {
    "memory-journal-dev": {
      "command": "python",
      "args": ["/path/to/memory-journal-mcp/src/server.py"],
      "cwd": "/path/to/memory-journal-mcp",
      "env": {
        "DEBUG": "true",
        "DB_PATH": "/path/to/test.db",
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

Next: Learn about Tools or check Installation.

🏠 Home

Getting Started

Core Features

Knowledge Graph

GitHub Integration

Workflows

Deployment

Architecture

Clone this wiki locally