Quick Start

Quick Start Guide

Get up and running with Memory Journal in 2 minutes!

5-Minute Tutorial

Step 1: Install (Choose One)

PyPI (30 seconds):

pip install memory-journal-mcp

Docker (1 minute):

docker pull writenotenow/memory-journal-mcp:latest
mkdir data

Step 2: Configure (30 seconds)

Add to ~/.cursor/mcp.json:

PyPI:

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

Docker:

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

Step 3: Restart Cursor (10 seconds)

The server should show green/connected with:

• 16 tools
• 14 prompts
• 13 resources (including GitHub Actions resources)

Step 4: Create Your First Entry (1 minute)

create_entry({
  content: "Set up Memory Journal for project context management. Now AI can access complete project history across all threads.",
  entry_type: "milestone",
  tags: ["setup", "context-management", "ai-assistant"],
  is_personal: false
})

Output:

✅ Created journal entry #1
Type: milestone
Personal: False
Tags: setup, journal, productivity

Step 5: Try Searching (30 seconds)

search_entries({
  query: "journal setup",
  limit: 5
})

Output:

Found 1 entries:

#1 (milestone) - 2025-10-04 16:30:22
Personal: False
Snippet: Just set up Memory **Journal**! Excited to track my development work...

---

Common First Tasks

Log a Technical Decision (Critical for AI Context)

create_entry({
  content: "Decided to use Redis for session caching instead of in-memory store. Rationale: Better scalability for multi-instance deployment. Considered memcached but Redis provides persistence we need for disaster recovery.",
  entry_type: "development_note",
  tags: ["architecture", "caching", "decision"],
  significance_type: "technical_decision"
})

Build Knowledge Graphs (Connect Related Work)

// Document the implementation
create_entry({
  content: "Implemented Redis session caching with 1-hour TTL and automatic refresh on activity.",
  entry_type: "technical_achievement",
  tags: ["caching", "redis", "implementation"]
})
// Returns: Entry #3

// Link implementation to original decision (builds context chain)
link_entries({
  from_entry_id: 3,  // Implementation
  to_entry_id: 2,    // Original decision
  relationship_type: "implements"
})
// Now AI can trace: Decision → Implementation → Results

Visualize Your Work

// Generate a relationship graph
visualize_relationships({
  entry_id: 2,
  depth: 2
})

Output: Mermaid diagram showing connected entries!

Prepare Your Daily Standup

Use the prompt palette (type / in Cursor):

/prepare-standup days_back:1

Output:

📋 Daily Standup - October 4, 2025

What I Did Yesterday:
- Fixed memory leak in caching layer
- Added connection pool monitoring

Blockers/Issues:
(None identified)

What's Next:
- Continue monitoring system performance

Get Recent Entries

get_recent_entries({
  limit: 5,
  is_personal: false
})

---

Essential Commands

Creating Entries

// Minimal entry
create_entry_minimal({
  content: "Quick note about the API refactor"
})

// Full entry with all options
create_entry({
  content: "Detailed technical description...",
  entry_type: "development_note",
  is_personal: false,
  tags: ["api", "refactor", "breaking-change"],
  significance_type: "major_milestone",
  auto_context: true  // Captures Git info
})

Searching

// Full-text search
search_entries({ query: "API refactor", limit: 10 })

// Semantic search (requires ML dependencies)
semantic_search({ query: "performance optimization challenges" })

// Date range
search_by_date_range({
  start_date: "2025-10-01",
  end_date: "2025-10-31",
  tags: ["bug-fix"]
})

Managing Entries

// Update an entry
update_entry({
  entry_id: 1,
  content: "Updated content...",
  tags: ["new-tag"]
})

// Soft delete (recoverable)
delete_entry({
  entry_id: 1,
  permanent: false
})

// Get specific entry with relationships
get_entry_by_id({
  entry_id: 1,
  include_relationships: true
})

Analytics

// Get statistics
get_statistics({
  group_by: "week"
})

// List all tags
list_tags()

// Export to Markdown
export_entries({
  format: "markdown",
  start_date: "2025-10-01",
  tags: ["milestone"]
})

---

Using Workflow Prompts

Access prompts through your MCP client's prompt palette (type / in Cursor):

Daily Standup

/prepare-standup days_back:1

Sprint Retrospective

/prepare-retro sprint_start:2025-10-01 sprint_end:2025-10-14

Weekly Digest

/weekly-digest week_offset:0

Period Analysis

/analyze-period start_date:2025-10-01 end_date:2025-10-31 focus_area:performance

Goal Tracking

/goal-tracker project_name:memory-journal

Find Related Entries

/find-related entry_id:1

---

Tips for Success

Entry Types for AI Context Management

• development_note - Technical decisions, architecture choices (MOST IMPORTANT for AI context)
• technical_achievement - Implementations, breakthroughs
• milestone - Project milestones, releases, version completions
• bug_fix - Bug resolutions with root cause analysis
• enhancement - Improvements, optimizations, refactorings
• technical_note - API documentation, integration notes
• personal_reflection - Learning insights, retrospectives (optional)

Tagging Strategy

Be consistent:

• Use lowercase
• Use hyphens for multi-word tags
• Create a core set of tags you use regularly

Good tags:

• performance, bug-fix, api-design
• learning, documentation, testing
• Project-specific: memory-journal, postgres-mcp

Relationship Types

• references - General connection between entries
• implements - Implementation of a spec/plan
• clarifies - Explanation or elaboration
• evolves_from - Iteration or improvement
• response_to - Reply or follow-up

Auto-Context Capture (Critical for AI Context)

Set auto_context: true (default) to automatically capture Git/GitHub state with every entry:

• Repository context - Repo name, path, working directory
• Branch information - Current branch (e.g., feature/redis-caching)
• Commit details - Latest commit hash and message
• GitHub integration - Open issues, PR status (if gh CLI installed)

Why this matters: AI can understand WHEN and WHERE work happened, making context reconstruction much more accurate across fragmented threads.

---

Next Steps

Learn More:

• Tools Reference - Complete guide to all 16 tools
• Tool Filtering - Reduce token usage by up to 69%
• Prompts Guide - All 14 workflow prompts
• Visualization - Relationship graphs
• Examples - Real-world usage patterns

Advanced Features:

• Relationships - Building knowledge graphs
• Semantic Search - ML-powered search
• Analytics - Statistics and insights

---

Questions? Check the Examples page or open an issue on GitHub.