Complete installation instructions for Memory Journal MCP Server - Project context management for AI-assisted development.

• MCP Client: Cursor IDE, Claude Desktop, or any MCP-compatible client
• Node.js 24+ (for npm installation)
• Docker (for Docker installation)

If you're working on large projects with AI assistance, you're likely experiencing:

• Thread amnesia - Each AI conversation starts from scratch
• Lost decisions - Architecture choices scattered across disconnected threads
• Repeated work - AI suggests solutions you've already tried

Memory Journal solves this by providing persistent project memory that makes every AI conversation informed by your complete development history.

Add to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "npx",
      "args": ["-y", "memory-journal-mcp"]
    }
  }
}

Or with Docker:

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

The fastest way to get started. Installs directly from npm.

1. Install the Package

npm install -g memory-journal-mcp

2. Configure Your MCP Client

Add to your ~/.cursor/mcp.json (or equivalent for your MCP client):

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

3. Restart Your Client

Restart Cursor or your MCP client. The server should appear in your MCP servers list.

4. Verify Installation

Try the test tool:

test_simple({ message: "Hello Memory Journal!" });

Run without installing globally:

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "npx",
      "args": ["-y", "memory-journal-mcp"]
    }
  }
}

Single optimized Node.js Alpine-based image (~100MB) with all features included.

1. Pull the Image

docker pull writenotenow/memory-journal-mcp:latest

For supply chain security (SHA-pinned):

# Find SHA tags at: https://hub.docker.com/r/writenotenow/memory-journal-mcp/tags
docker pull writenotenow/memory-journal-mcp:sha256-<manifest-digest>

2. Create Data Directory

mkdir data

This directory will persist your SQLite database on your host machine.

3. Configure Your MCP Client

Add to your ~/.cursor/mcp.json:

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

4. Restart Your Client

Restart Cursor or your MCP client.

5. Verify Installation

The server should start in ~2-3 seconds and show 70 tools, 17 prompts, and 37 resources (24 static + 13 template).

Custom database path:

{
  "command": "docker",
  "args": [
    "run",
    "--rm",
    "-i",
    "-v",
    "/path/to/your/data:/app/data",
    "-e",
    "DB_PATH=/app/data/custom.db",
    "-e",
    "PROJECT_REGISTRY={\"my-repo\":{\"path\":\"/app/repo\",\"project_number\":1}}",
    "-e",
    "ALLOWED_IO_ROOTS=/app/repo",
    "writenotenow/memory-journal-mcp:latest"
  ]
}

Enable debug logging:

{
  "args": [
    "run",
    "--rm",
    "-i",
    "-v",
    "./data:/app/data",
    "-e",
    "DEBUG=true",
    "-e",
    "PROJECT_REGISTRY={\"my-repo\":{\"path\":\"/app/repo\",\"project_number\":1}}",
    "writenotenow/memory-journal-mcp:latest"
  ]
}

For development or customization.

1. Clone the Repository

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

2. Install Dependencies

npm install

3. Build

npm run build

4. Configure Your MCP Client

Add to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "node",
      "args": ["/full/path/to/memory-journal-mcp/dist/cli.js"]
    }
  }
}

5. Restart Your Client

For remote access, web-based clients, or HTTP-compatible MCP hosts.

npm (stateful - default):

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

npm (stateless - serverless):

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

From source:

node dist/cli.js --transport http --port 3000
node dist/cli.js --transport http --port 3000 --stateless

Docker (stateful):

docker run --rm -p 3000:3000 \
  -v ./data:/app/data \
  writenotenow/memory-journal-mcp:latest \
  --transport http --port 3000 --server-host 0.0.0.0

Docker (stateless):

docker run --rm -p 3000:3000 \
  -v ./data:/app/data \
  writenotenow/memory-journal-mcp:latest \
  --transport http --port 3000 --server-host 0.0.0.0 --stateless

Choose Stateful when:

• Running on persistent infrastructure (VMs, containers)
• Need progress notifications for long-running tools
• Need SSE streaming for real-time notifications

Choose Stateless when:

• Deploying to serverless (Lambda, Workers, Vercel)
• Horizontal scaling without sticky sessions
• Simple request-response patterns

In stateful mode, include the mcp-session-id header (returned from initialization) in subsequent requests.

In stateless mode, no session ID is required — each request is independent.

Stateful mode:

# Initialize session
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
# Returns mcp-session-id header

# List tools (with session)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Stateless mode:

# All requests are independent - no session ID needed
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"test_simple","arguments":{"message":"Hello"}}}'

After installation, verify the server is running:

1. Open your MCP client
2. Look for "memory-journal" in the MCP servers list
3. Status should show green/connected

Try creating a simple entry:

create_entry_minimal({
  content: "Testing Memory Journal installation",
});

You should see: ✅ Minimal entry created #1

The server should provide:

• 70 Tools: create_entry, search_entries, semantic_search, link_entries, backup_journal, get_kanban_board, move_kanban_item, create_github_issue_with_entry, close_github_issue_with_entry, get_github_milestones, create_github_milestone, get_repo_insights, get_copilot_reviews, team_create_entry, team_get_recent, team_search, team_get_entry_by_id, team_list_tags, team_search_by_date_range, team_update_entry, team_delete_entry, team_merge_tags, team_get_statistics, team_link_entries, team_visualize_relationships, team_export_entries, team_backup, team_list_backups, team_semantic_search, team_get_vector_index_stats, team_rebuild_vector_index, team_add_to_vector_index, team_get_cross_project_insights, team_get_collaboration_matrix, pass_team_flag, resolve_team_flag, etc.
• 17 Prompts: get-context-bundle, prepare-standup, project-status-summary, pr-summary, code-review-prep, pr-retrospective, actions-failure-digest, confirm-briefing, session-summary, etc.
• 37 Resources (24 static + 13 template):
  • Static (24): memory://briefing, memory://instructions, memory://recent, memory://significant, memory://tags, memory://statistics, memory://rules, memory://workflows, memory://skills, memory://graph/recent, memory://graph/actions, memory://github/status, memory://github/insights, memory://github/milestones, memory://actions/recent, memory://health, memory://help, memory://help/gotchas, memory://team/recent, memory://team/statistics, memory://insights/digest, memory://insights/team-collaboration, memory://flags, memory://flags/vocabulary
  • Template (13, require parameters): memory://briefing/{repo}, memory://help/{group}, memory://projects/{number}/timeline, memory://issues/{issue_number}/entries, memory://prs/{pr_number}/entries, memory://prs/{pr_number}/timeline, memory://kanban/{project_number}, memory://kanban/{project_number}/diagram, memory://github/status/{repo}, memory://github/insights/{repo}, memory://github/milestones/{repo}, memory://milestones/{repo}/{number}, memory://milestones/{number}

Listing Resources: To discover available resources, call ListMcpResources() with NO parameters or with server: "user-memory-journal-mcp" (Cursor prefixes server names with user-). Note: Only 22 static resources appear in the listing; 13 template resources require parameters and are accessed directly by URI.

npm Installation:

• Check Node.js version: node --version (need 24+)
• Reinstall: npm uninstall -g memory-journal-mcp && npm install -g memory-journal-mcp
• Check logs in your MCP client

Docker Installation:

• Verify Docker is running: docker ps
• Check image exists: docker images | grep memory-journal
• Test manually: docker run --rm writenotenow/memory-journal-mcp:latest
• Check data directory permissions

This shouldn't happen in v3.0.0! ML models are lazy-loaded. If it does:

• Check you're on latest version (v3.0.0+)
• Check system resources (CPU/memory)

In v3.0.0, semantic search is included by default using @huggingface/transformers. If issues occur:

• Check server logs for "Vector search capabilities available"
• First search may be slower (model loading)

• Check data directory exists and is writable
• For Docker: Verify volume mount -v ./data:/app/data
• Database auto-creates on first run
• Backup existing database before troubleshooting

• Restart the client after configuration changes
• Check JSON syntax in mcp.json
• Look for error messages in client logs
• Try the test_simple tool to verify connectivity

Cursor IDE:

• Listing Resources: Call ListMcpResources() without specifying a server parameter, or with server: "user-memory-journal-mcp" (Cursor prefixes server names with user-).

Google AntiGravity IDE:

• Server instructions: Auto-injected via MCP protocol. The memory://instructions resource is available for manual reference if needed.
• Session start: Add to user rules: "At session start, infer repo_name from your workspace and read memory://briefing/{repo_name}. If no target can be inferred, fallback natively to memory://briefing."
• Prompts: All 17 workflow prompts are accessible via MCP prompts support.

• Quick Start Guide - Learn basic usage
• Tool Filtering - Reduce token usage by up to 84%
• Configuration - Customize your setup
• Tools Reference - Explore all 70 tools
• Examples - See real-world usage patterns

• Node.js: 24+
• Memory: 512MB RAM
• Disk: 100MB (ML models loaded on demand)
• OS: Windows, macOS, Linux

• Node.js: 24+
• Memory: 2GB RAM (for semantic search)
• Disk: 500MB (for models + data)
• Docker: 20.10+ (for Docker installation)

• Installs to global npm directory
• Database stored in ~/.memory-journal/ or custom path
• No network access required after installation

• Non-root container execution
• Minimal Node.js Alpine base
• Volume-mounted data directory
• No privileged access required
• Supply chain security with SHA-pinned images

Need Help? Open an issue on GitHub.