Configuration

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.

---

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

2. Authenticate:

gh auth login

3. 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.