Skip to content

Configuration

Jump to bottom
Chris & Mike edited this page Mar 11, 2026 · 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:

npm 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"
      ]
    }
  }
}

From Source:

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "node",
      "args": ["/full/path/to/memory-journal-mcp/dist/cli.js"],
      "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.

CLI Options

When running from source or npm, the following command-line options are available:

memory-journal-mcp [options]
Option Default Description
--transport <type> stdio Transport type: stdio or http
--port <number> 3000 HTTP port (for http transport)
--server-host <host> localhost HTTP bind address (e.g., 0.0.0.0 for containers)
--stateless false Use stateless HTTP mode (no session management)
--db <path> ./memory_journal.db Database path
--tool-filter <filter> (none) Tool filter string (e.g., "starter", "core,search")
--default-project <number> (none) Default GitHub Project number
--auto-rebuild-index false Rebuild vector index on server startup
--log-level <level> info Log level: debug, info, warning, error
--cors-origin <origins> * CORS allowed origins (comma-separated, wildcard subdomains)
--team-db <path> (none) Path to team database file (enables team tools)

Transport Examples

stdio (default - for MCP clients):

memory-journal-mcp

HTTP stateful (for web clients):

memory-journal-mcp --transport http --port 3000

HTTP stateful (bind to all interfaces — required for Docker):

memory-journal-mcp --transport http --port 3000 --server-host 0.0.0.0

HTTP stateless (for serverless):

memory-journal-mcp --transport http --port 3000 --stateless

Database Configuration

Database Location

npm (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"
  ]
}

Database Backup

Simple backup:

# npm installation
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:

-- sql.js uses an in-memory WASM database
-- Disk-based PRAGMAs (journal_mode, synchronous, mmap_size) do not apply
PRAGMA foreign_keys = ON;
PRAGMA busy_timeout = 30000;         -- 30s wait for locks

These settings provide:

  • In-memory WASM - All data in memory for fast access
  • Automatic persistence - Database saved to disk on changes
  • Performance - Large caches and memory-mapped I/O

Startup Performance

v3.0.0 optimization:

  • Lazy loading of ML dependencies
  • Startup time: 2-3 seconds
  • First semantic search: ~5s (loads model)

Note: Semantic search is included by default in v3.0.0.

Automated Scheduler (HTTP Only)

Added in v4.5.0

Long-running HTTP/SSE server processes can run periodic maintenance jobs automatically. All intervals default to 0 (disabled). Stdio transport ignores these options.

CLI Flag Default Description
--backup-interval <minutes> 0 Automated backup interval (0=off)
--keep-backups <count> 5 Max backups retained during cleanup
--vacuum-interval <minutes> 0 PRAGMA optimize + flush to disk
--rebuild-index-interval <minutes> 0 Full vector index rebuild

Example:

memory-journal-mcp --transport http --port 3000 \
  --backup-interval 60 --keep-backups 10 \
  --vacuum-interval 360 \
  --rebuild-index-interval 720

Jobs:

  • Backup — Exports database to a timestamped file, then prunes old backups (keeping --keep-backups most recent)
  • Vacuum — Runs PRAGMA optimize and flushes the in-memory database to disk
  • Rebuild Index — Full vector search index rebuild from all entries (requires semantic search)

Scheduler status is reported in the memory://health resource under the scheduler field. Each job is error-isolated: failures are logged but don't affect other scheduled jobs.

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

Included by default in v3.0.0!

Uses @xenova/transformers (pure JS) instead of Python ML stack.

Features:

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

Requirements:

  • First search: ~5s (loads model)
  • Subsequent: <1s
  • Models cached locally

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 84%):

{
  "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)
  • MCP_HOST - HTTP transport bind address (default: localhost). Set to 0.0.0.0 for containers. Also reads HOST as fallback.
  • MEMORY_JOURNAL_MCP_TOOL_FILTER - Comma-separated tool filter rules (see Tool Filtering)
  • GITHUB_TOKEN - GitHub Personal Access Token for Projects/Issues/PRs
  • DEFAULT_PROJECT_NUMBER - Default GitHub Project number for auto-assignment when creating issues
  • AUTO_REBUILD_INDEX - Set to true to rebuild vector index on server startup (useful when index gets out of sync)
  • MCP_CORS_ORIGIN - CORS allowed origin for HTTP transport (default: *). Set to a specific origin in production (e.g., http://localhost:3000).
  • TEAM_DB_PATH - Path to team database file (enables team collaboration with dedicated tools and resources)
  • TEAM_AUTHOR - Override author name for team entries (default: git config user.name)

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"
    ]
  }
}

Instance 2 (personal):

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

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"
  ]
}

Troubleshooting Configuration

Server Won't Start

Check MCP config syntax:

# Validate JSON (Windows PowerShell)
Get-Content ~/.cursor/mcp.json | ConvertFrom-Json | ConvertTo-Json

# or (cross-platform with Node.js)
node -e "console.log(JSON.parse(require('fs').readFileSync(process.env.HOME + '/.cursor/mcp.json')))"

Check paths:

# npm - verify package
npm list -g memory-journal-mcp

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

# Source - verify path
ls /full/path/to/memory-journal-mcp/dist/cli.js

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 v3.0.0+ (TypeScript version with all 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 (Default)

{
  "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"
      ]
    }
  }
}

Lightweight (Core Only - 84% 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": "node",
      "args": ["/path/to/memory-journal-mcp/dist/cli.js"],
      "cwd": "/path/to/memory-journal-mcp",
      "env": {
        "DEBUG": "true",
        "DB_PATH": "/path/to/test.db",
        "GITHUB_TOKEN": "your_token_here",
        "DEFAULT_PROJECT_NUMBER": "1",
        "AUTO_REBUILD_INDEX": "true"
      }
    }
  }
}

Next: Learn about Tools or check Installation.

🏠 Home

Getting Started

Core Features

Knowledge Graph

GitHub Integration

Workflows

Deployment

Architecture

Clone this wiki locally