Skip to content

Configuration

Jump to bottom
Temp edited this page Jan 17, 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)
--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

Transport Examples

stdio (default - for MCP clients):

memory-journal-mcp

HTTP stateful (for web clients):

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

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:

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

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.

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 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
  • 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)

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

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": "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