# Memory Journal MCP Server
Last Updated October 26, 2025 - Production/Stable v1.2.2
<!-- mcp-name: io.github.neverinfamous/memory-journal-mcp -->
[](https://github.com/neverinfamous/memory-journal-mcp)
[](https://hub.docker.com/r/writenotenow/memory-journal-mcp)
[](https://opensource.org/licenses/MIT)
[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.neverinfamous/memory-journal-mcp)
[](https://pypi.org/project/memory-journal-mcp/)
[](SECURITY.md)
[](https://github.com/neverinfamous/memory-journal-mcp/security/code-scanning)
[](https://github.com/neverinfamous/memory-journal-mcp)
*A production-ready developer journal with knowledge graphs, visual relationship mapping, and intelligent search*
**🎉 Now Production/Stable!** Memory Journal has graduated from beta with powerful relationship mapping, 10x faster startup, and comprehensive documentation.
**🚀 Quick Deploy:**
- **[PyPI Package](https://pypi.org/project/memory-journal-mcp/)** - `pip install memory-journal-mcp`
- **[Docker Hub](https://hub.docker.com/r/writenotenow/memory-journal-mcp)** - Alpine-based (225MB) with full semantic search
- **[MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.neverinfamous/memory-journal-mcp)** - Discoverable by MCP clients
**📚 Full Documentation:** [GitHub Wiki](https://github.com/neverinfamous/memory-journal-mcp/wiki)
**📰 [Read the v1.1.2 Release Article](https://adamic.tech/articles/2025-10-04-memory-journal-mcp-v1-1-2)** - Learn about knowledge graphs, performance optimizations, and relationship mapping
---
## ✨ What's New in v1.2.2 (Security Patch - October 26, 2025)
### 🔒 **Security Fix: URL Parsing Vulnerability (CodeQL #110, #111)**
Fixed incomplete URL substring sanitization in GitHub remote URL parsing:
- **Proper URL validation** - Implemented `urllib.parse.urlparse()` with exact hostname matching
- **Prevented URL spoofing** - Blocks malicious URLs like `http://evil.com/github.com/fake/repo`
- **Enhanced security** - SSH URLs use explicit prefix validation, HTTPS URLs use proper parsing
- **No breaking changes** - Drop-in replacement maintaining full compatibility
### Technical Details
- **Vulnerability**: CWE-20 (Improper Input Validation)
- **Severity**: Medium (limited to Git remote URL parsing in local repositories)
- **Fix**: Replaced substring checks (`'github.com' in url`) with proper `urlparse()` validation
- **Reference**: [CodeQL Rule py/incomplete-url-substring-sanitization](https://codeql.github.com/codeql-query-help/python/py-incomplete-url-substring-sanitization/)
This security patch maintains full compatibility with v1.2.x - simply upgrade to receive the fix.
---
## ✨ What's New in v1.2.1 (Patch Release - October 26, 2025)
### 🐛 **Critical Bug Fix: Semantic Search Initialization**
Fixed a critical async/lazy loading race condition that could cause semantic search to hang on first use:
- **First semantic_search now completes in <1 second** (was: could timeout after 30+ seconds)
- **Eliminated async lock deadlocks** during ML model loading
- **Enhanced thread pool** from 2 to 4 workers for better concurrent operations
- **No more need to cancel and retry** - reliable semantic search on every server restart
This patch release maintains full compatibility with v1.2.0 - simply upgrade and restart your MCP client.
---
## ✨ What's New in v1.2.0 (Organization Support)
### 🏢 **Organization-Level GitHub Projects** - Team Collaboration Ready
Full support for organization-level projects alongside user projects:
- **Automatic Owner Detection** - Detects whether repo belongs to user or organization
- **Dual Project Lookup** - Shows both user and org projects in context
- **Org Project Analytics** - All features work seamlessly with org projects
- **Separate Token Support** - Optional `GITHUB_ORG_TOKEN` for org-specific permissions
- **Zero Breaking Changes** - Fully backward compatible
### 🔧 **Enhanced Features for Organizations**
All advanced project analytics now support org projects:
- **Cross-Project Insights** - Analyze patterns across user AND org projects
- **Status Summaries** - Comprehensive reports for org project teams
- **Milestone Tracking** - Track org-level milestones and team velocity
- **Project Timelines** - Combined journal + GitHub activity for org projects
- **Smart Caching** - 80%+ API reduction for both user and org projects (24hr owner type cache, 1hr project cache)
### 📊 **Advanced Project Analytics** - Deep Insights Across Projects
- **Cross-Project Insights** - Analyze patterns across all tracked projects
- **Project Breakdown** - Time distribution and activity analysis per project
- **Velocity Tracking** - Measure productivity with entries per week
- **Smart Caching** - 80%+ reduction in API calls with intelligent caching (1hr TTL)
- **Inactive Project Detection** - Automatically identify projects needing attention
### 📈 **Project Status & Milestone Tracking**
- **Status Summary Prompt** - Comprehensive project reports with GitHub data integration
- **Milestone Tracker** - Progress visualization with velocity charts
- **Project Timeline Resource** - Live activity feed combining journal + GitHub events
- **Item Status Monitoring** - Track completion rates and project item states
### 🔗 **GitHub Projects Integration** - Enhanced Context Awareness
Seamlessly connect your journal entries with GitHub Projects:
- **Automatic Project Detection** - Detects GitHub Projects associated with current repository (user & org)
- **Active Work Items** - Shows what you're actively working on from projects
- **Entry-Project Linking** - Associate journal entries with specific projects and items
- **Project Filtering** - Search and filter entries by project number
- **Graceful Degradation** - Works perfectly without GitHub token (features degrade gracefully)
### 🎉 **v1.2.0 - Capabilities**
Building on the stable v1.1.3 foundation:
- **16 MCP tools** (up from 15) - Added `get_cross_project_insights`
- **10 workflow prompts** (up from 8) - Added `project-status-summary` and `project-milestone-tracker`
- **4 MCP resources** (up from 3) - Added `memory://projects/{number}/timeline`
- **Smart caching system** - GitHub API response caching with configurable TTLs
- **Enhanced analytics** - Project breakdown support in `get_statistics`
- **Backward compatible** - Seamless upgrade from v1.1.x with automatic schema migration
### 🔗 **Entry Relationships & Knowledge Graphs**
Build connections between your entries with typed relationships:
- `references` - General connections between work
- `implements` - Link implementations to specs/designs
- `clarifies` - Add explanations and elaborations
- `evolves_from` - Track how ideas develop over time
- `response_to` - Thread conversations and replies
### 📊 **Visual Relationship Mapping**
Generate beautiful Mermaid diagrams showing how your work connects:
```mermaid
graph TD
E55["#55: Implementing visualization feature<br/>development_note"]
E56["#56: Testing the new tool<br/>technical_note"]
E57["#57: Documentation improvements<br/>enhancement"]
E56 ==>|implements| E55
E57 -.->|clarifies| E55
style E55 fill:#FFF3E0
style E56 fill:#FFF3E0
style E57 fill:#FFF3E0
```
### ⚡ **Performance Revolution**
- **10x faster startup** - Lazy loading reduces init time from 14s → 2-3s
- **Thread-safe operations** - Zero race conditions in concurrent tag creation
- **Database lock prevention** - Single-connection transactions eliminate conflicts
- **Optimized queries** - Strategic indexes for relationship traversal
### 🛠️ **New Tools** (15 Total, +2 from v1.0)
- `visualize_relationships` - Generate Mermaid diagrams with depth control
- `link_entries` - Create typed relationships between entries
- Plus comprehensive CRUD, triple search, analytics, and export
### 🎯 **Enhanced Workflow Prompts** (8 Total, +2 from v1.0)
- `find-related` - Discover connected entries via semantic similarity
- `prepare-standup` - Daily standup summaries
- `prepare-retro` - Sprint retrospectives
- `weekly-digest` - Day-by-day weekly summaries
- `analyze-period` - Deep period analysis with insights
- `goal-tracker` - Milestone and achievement tracking
- `get-context-bundle` - Project context with Git/GitHub
- `get-recent-entries` - Formatted recent entries
### 📡 **New Resources** (3 Total, +1 from v1.0)
- `memory://graph/recent` - **NEW** Live Mermaid diagram of recent relationships
- `memory://recent` - 10 most recent entries
- `memory://significant` - Significant milestones and breakthroughs
### 🗄️ **Database Improvements**
- Automatic schema migrations (seamless v1.0 → v1.1 upgrades)
- Soft delete support with `deleted_at` column
- New `relationships` table with cascading deletes
- Enhanced indexes for optimal query performance
---
## 🚀 Quick Start
### Option 1: PyPI (Fastest - 30 seconds)
**Step 1: Install the package**
```bash
pip install memory-journal-mcp
```
**Step 2: Add to ~/.cursor/mcp.json**
```json
{
"mcpServers": {
"memory-journal": {
"command": "memory-journal-mcp"
}
}
}
```
**Step 3: Restart Cursor**
Restart Cursor or your MCP client, then start journaling!
### Option 2: Docker (Full Features - 2 minutes)
**Step 1: Pull the Docker image**
```bash
docker pull writenotenow/memory-journal-mcp:latest
```
**Step 2: Create data directory**
```bash
mkdir data
```
**Step 3: Add to ~/.cursor/mcp.json**
```json
{
"mcpServers": {
"memory-journal": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-v", "./data:/app/data",
"writenotenow/memory-journal-mcp:latest",
"python", "src/server.py"
]
}
}
}
```
**Step 4: Restart Cursor**
Restart Cursor or your MCP client, then start journaling!
---
## ⚡ **Install to Cursor IDE**
### **One-Click Installation**
Click the button below to install directly into Cursor:
[](cursor://anysphere.cursor-deeplink/mcp/install?name=Memory%20Journal%20MCP&config=eyJtZW1vcnktam91cm5hbCI6eyJhcmdzIjpbInJ1biIsIi0tcm0iLCItaSIsIi12IiwiLi9kYXRhOi9hcHAvZGF0YSIsIndyaXRlbm90ZW5vdy9tZW1vcnktam91cm5hbC1tY3A6bGF0ZXN0IiwicHl0aG9uIiwic3JjL3NlcnZlci5weSJdLCJjb21tYW5kIjoiZG9ja2VyIn19)
Or copy this deep link:
```
cursor://anysphere.cursor-deeplink/mcp/install?name=Memory%20Journal%20MCP&config=eyJtZW1vcnktam91cm5hbCI6eyJhcmdzIjpbInJ1biIsIi0tcm0iLCItaSIsIi12IiwiLi9kYXRhOi9hcHAvZGF0YSIsIndyaXRlbm90ZW5vdy9tZW1vcnktam91cm5hbC1tY3A6bGF0ZXN0IiwicHl0aG9uIiwic3JjL3NlcnZlci5weSJdLCJjb21tYW5kIjoiZG9ja2VyIn19
```
### **Prerequisites**
- ✅ Docker installed and running
- ✅ ~500MB disk space for data directory
### **Configuration**
After installation, Cursor will use this Docker-based configuration. If you prefer manual setup, add this to your `~/.cursor/mcp.json`:
```json
{
"memory-journal": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-v", "./data:/app/data",
"writenotenow/memory-journal-mcp:latest",
"python", "src/server.py"
]
}
}
```
**📖 [See Full Installation Guide →](https://github.com/neverinfamous/memory-journal-mcp/wiki/Installation)**
---
## 📋 Core Capabilities
### 🛠️ **16 MCP Tools** - Complete Development Workflow
**Entry Management:**
- `create_entry` / `create_entry_minimal` - Create entries with auto-context and GitHub Projects linking
- `update_entry` - Edit existing entries (thread-safe)
- `delete_entry` - Soft or permanent deletion
- `get_entry_by_id` - Retrieve with full relationship details and project info
**Search & Discovery:**
- `search_entries` - FTS5 full-text search with highlighting and project filtering
- `search_by_date_range` - Time-based filtering with tags and projects
- `semantic_search` - ML-powered similarity (optional)
- `get_recent_entries` - Quick access to recent work
**Relationships & Visualization:**
- `link_entries` - Create typed relationships
- `visualize_relationships` - Generate Mermaid diagrams
**Organization & Analytics:**
- `list_tags` - Tag usage statistics
- `get_statistics` - Comprehensive analytics by time period with project breakdown
- `get_cross_project_insights` - **NEW** - Cross-project pattern analysis
- `export_entries` - JSON/Markdown export
- `test_simple` - Connectivity testing
### 🎯 **10 Workflow Prompts** - Automated Productivity
- **`prepare-standup`** - Daily standup summaries from recent entries
- **`prepare-retro`** - Sprint retrospectives with achievements and learnings
- **`weekly-digest`** - Day-by-day weekly summaries
- **`analyze-period`** - Deep analysis with pattern insights
- **`goal-tracker`** - Milestone and achievement tracking
- **`find-related`** - Discover connected entries via semantic similarity
- **`get-context-bundle`** - Complete project context (Git + GitHub)
- **`get-recent-entries`** - Formatted display of recent work
- **`project-status-summary`** - **NEW** - Comprehensive GitHub Project status reports
- **`project-milestone-tracker`** - **NEW** - Milestone progress with velocity tracking
### 🔍 **Triple Search System** - Find Anything, Any Way
1. **Full-text search** - SQLite FTS5 with result highlighting and rank ordering
2. **Date range search** - Time-based filtering with tag and type filters
3. **Semantic search** - FAISS vector similarity for concept-based discovery (optional)
### 🔗 **Entry Relationships** - Build Your Knowledge Graph
- **5 relationship types** - references, implements, clarifies, evolves_from, response_to
- **Bidirectional linking** - See both incoming and outgoing relationships
- **Graph visualization** - Generate Mermaid diagrams with depth control
- **Smart discovery** - Find related entries via semantic similarity and shared tags
### 📊 **Comprehensive Analytics** - Track Your Progress
- Entry counts by type (achievements, notes, milestones, etc.)
- Top tags with usage statistics
- Activity patterns by day/week/month
- Significant milestone tracking
- Export-ready statistics for reports
### 🎨 **Visual Relationship Graphs** - See How Work Connects
- **3 visualization modes** - Entry-centric, tag-based, recent activity
- **Customizable depth** - Control relationship traversal (1-3 hops)
- **Tag filtering** - Focus on specific projects or topics
- **Color-coded nodes** - Personal (blue) vs Project (orange) entries
- **Typed arrows** - Different styles for different relationship types
### 🔄 **Git & GitHub Integration** - Automatic Context Capture
- Repository name and path
- Current branch
- Latest commit (hash + message)
- Recent GitHub issues (via `gh` CLI)
- **GitHub Projects** - Automatic project detection and tracking (user & org)
- **Organization Support** - Full support for org-level projects alongside user projects
- **Project Analytics** - Cross-project insights, status summaries, milestone tracking (user & org)
- **Smart API Caching** - 80%+ API call reduction (24hr owner type, 1hr projects, 15min items)
- **Timeline Resources** - Combined journal + GitHub activity feeds for user & org projects
- **Auto Owner Detection** - Automatically determines if repo belongs to user or organization
- Working directory
- Timestamp for all context
### 📦 **Data Export** - Own Your Data
- **JSON format** - Machine-readable with full metadata
- **Markdown format** - Human-readable with beautiful formatting
- **Flexible filtering** - By date range, tags, entry types, projects
- **Portable** - Take your journal anywhere
### 🔧 **Configuration & Setup**
**GitHub Projects Integration (Optional):**
To enable GitHub Projects features, set the `GITHUB_TOKEN` environment variable:
```bash
# Linux/macOS
export GITHUB_TOKEN="your_github_personal_access_token"
# Windows PowerShell
$env:GITHUB_TOKEN="your_github_personal_access_token"
```
**Organization Projects:**
For organization-level projects, you can optionally use a separate token:
```bash
# Linux/macOS
export GITHUB_ORG_TOKEN="your_org_access_token"
export DEFAULT_ORG="your-org-name" # Optional: default org for ambiguous contexts
# Windows PowerShell
$env:GITHUB_ORG_TOKEN="your_org_access_token"
$env:DEFAULT_ORG="your-org-name"
```
**Required Scopes:**
- User projects: `repo`, `project`
- Org projects: `repo`, `project`, `read:org` (minimum)
- Full org features: Add `admin:org` for team info
**Fallback Options:**
- Uses GitHub CLI (`gh`) if `GITHUB_TOKEN` is not available
- Uses `GITHUB_TOKEN` if `GITHUB_ORG_TOKEN` not set
- Works without GitHub token (project features gracefully disabled)
- Auto-detects whether owner is user or organization
---
## 📖 Usage Examples
### Create an Entry with GitHub Projects
```javascript
// Create an entry linked to a GitHub Project
create_entry({
content: "Completed Phase 1 of GitHub Projects integration - all core features implemented!",
entry_type: "technical_achievement",
tags: ["github-projects", "integration", "milestone"],
project_number: 1, // Links to GitHub Project #1
significance_type: "technical_breakthrough"
})
// Context automatically includes GitHub Projects info
// Search entries by project
search_entries({
project_number: 1,
limit: 10
})
// Filter by project and date range
search_by_date_range({
start_date: "2025-10-01",
end_date: "2025-10-31",
project_number: 1
})
```
### Create an Entry with Relationships
```javascript
// Create a technical achievement
create_entry({
content: "Implemented lazy loading for ML dependencies - 10x faster startup!",
entry_type: "technical_achievement",
tags: ["performance", "optimization", "ml"],
significance_type: "technical_breakthrough"
})
// Returns: Entry #55
// Link related work
link_entries({
from_entry_id: 56, // Testing entry
to_entry_id: 55, // Implementation
relationship_type: "implements"
})
// Visualize the connections
visualize_relationships({
entry_id: 55,
depth: 2
})
```
### Search and Analyze
```javascript
// Full-text search with highlighting
search_entries({ query: "performance optimization", limit: 5 })
// Semantic search for concepts
semantic_search({ query: "startup time improvements", limit: 3 })
// Date range with tags
search_by_date_range({
start_date: "2025-10-01",
end_date: "2025-10-31",
tags: ["performance"]
})
// Get analytics
get_statistics({ group_by: "week" })
```
### Generate Visual Maps
```javascript
// Visualize entry relationships
visualize_relationships({
entry_id: 55, // Root entry
depth: 2 // 2 hops out
})
// Filter by tags
visualize_relationships({
tags: ["visualization", "relationships"],
limit: 20
})
// Access live graph resource
memory://graph/recent // Most recent 20 entries with relationships
```
### Advanced Project Features
```javascript
// Cross-project insights
get_cross_project_insights({
start_date: "2025-10-01",
end_date: "2025-10-31",
min_entries: 3
})
// Returns: Active projects ranked by activity, time distribution, productivity patterns, inactive projects
// Project statistics with breakdown
get_statistics({
start_date: "2025-10-01",
end_date: "2025-10-31",
group_by: "week",
project_breakdown: true
})
// Returns: Standard stats PLUS entries per project, active days per project
// Project status summary (prompt)
project-status-summary({
project_number: 1,
time_period: "sprint", // week, sprint, month
include_items: true
})
// Returns: Project overview, journal activity, GitHub items status, key insights
// Milestone tracking (prompt)
project-milestone-tracker({
project_number: 1,
milestone_name: "v1.2.0" // optional filter
})
// Returns: Milestone progress, velocity chart, journal activity summary
// Access project timeline resource
memory://projects/1/timeline
// Returns: Chronological feed of last 30 days (journal + GitHub events)
```
### Organization Project Support
```javascript
// Create entry with explicit org project
create_entry({
content: "Sprint planning meeting - discussed Q4 roadmap",
entry_type: "technical_note",
tags: ["sprint-planning", "Q4"],
project_number: 5,
project_owner: "my-company",
project_owner_type: "org"
})
// Auto-detect works for org repos too! (detects owner type automatically)
create_entry({
content: "Fixed critical bug in auth service",
project_number: 5 // Owner and type auto-detected from repo context
})
// Org project status summary
project-status-summary({
project_number: 5,
owner: "my-company",
owner_type: "org",
time_period: "sprint",
include_items: true
})
// Returns: Org project overview, team activity, GitHub items, insights
// Org milestone tracking
project-milestone-tracker({
project_number: 5,
owner: "my-company",
owner_type: "org"
})
// Returns: Org milestone progress, team velocity, activity summary
// Access org project timeline (explicit format)
memory://projects/my-company/org/5/timeline
// Returns: Org project timeline with journal + GitHub events
// Access org project timeline (auto-detect format)
memory://projects/5/timeline
// Returns: Auto-detects if project belongs to org and fetches accordingly
// Cross-project insights automatically includes org projects
get_cross_project_insights({
start_date: "2025-10-01",
end_date: "2025-10-31"
})
// Returns: Insights across BOTH user and org projects
```
---
## 🏗️ Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ MCP Server Layer (Async/Await) │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
│ │ Entry Creation │ │ Triple Search │ │ Relationship│ │
│ │ with Context │ │ FTS5/Date/ML │ │ Mapping │ │
│ └─────────────────┘ └─────────────────┘ └─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Thread Pool Execution Layer │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
│ │ Git Operations │ │ Database Ops │ │ Lazy ML │ │
│ │ (2s timeout) │ │ Single Conn │ │ Loading │ │
│ └─────────────────┘ └─────────────────┘ └─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ SQLite Database with FTS5 + Relationships │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ entries + tags + relationships + embeddings + FTS ││
│ └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
```
---
## 🔧 Technical Highlights
### Performance & Security
- **Python 3.14** - Latest Python with free-threaded support (PEP 779), deferred annotations (PEP 649), and performance optimizations
- **10x faster startup** - Lazy loading of ML dependencies (2-3s vs 14s)
- **Thread-safe operations** - Zero race conditions in tag creation
- **WAL mode** - Better concurrency and crash recovery
- **Database lock prevention** - Single-connection transactions
- **Aggressive timeouts** - Git operations fail-fast (2s per command)
- **Input validation** - Length limits, parameterized queries, SQL injection prevention
### Semantic Search (Optional)
- **Model**: `all-MiniLM-L6-v2` (384-dimensional embeddings)
- **Storage**: FAISS index for fast similarity search
- **Graceful degradation**: Works perfectly without ML dependencies
### Data & Privacy
- **Local-first**: Single SQLite file, you own your data
- **Portable**: Move your `.db` file anywhere
- **Secure**: No external API calls, non-root Docker containers
---
## 📚 Documentation
**Full documentation available on the [GitHub Wiki](https://github.com/neverinfamous/memory-journal-mcp/wiki):**
- [Installation Guide](https://github.com/neverinfamous/memory-journal-mcp/wiki/Installation)
- [Tools Reference](https://github.com/neverinfamous/memory-journal-mcp/wiki/Tools)
- [Prompts Guide](https://github.com/neverinfamous/memory-journal-mcp/wiki/Prompts)
- [Relationship Visualization](https://github.com/neverinfamous/memory-journal-mcp/wiki/Visualization)
- [Examples & Tutorials](https://github.com/neverinfamous/memory-journal-mcp/wiki/Examples)
- [Architecture Deep Dive](https://github.com/neverinfamous/memory-journal-mcp/wiki/Architecture)
### GitHub Gists: Practical Examples & Use Cases
**[→ View All Memory Journal Gists](https://gist.github.com/neverinfamous/ffedec3bdb5da08376a381733b80c1a7)**
Explore 5 curated gists with real-world examples and implementation patterns:
1. **[Complete Feature Showcase](https://gist.github.com/neverinfamous/ffedec3bdb5da08376a381733b80c1a7)** - All 15 tools, 8 prompts, and 3 resources
2. **[Relationship Mapping & Knowledge Graphs](https://gist.github.com/neverinfamous/e5f3638dc76b2536df04a02af9647abd)** - Build knowledge graphs with typed relationships
3. **[Triple Search System Guide](https://gist.github.com/neverinfamous/a484535fea7014e8822887abbd8abb38)** - Master FTS5, date range, and semantic search
4. **[Workflow Automation & Prompts](https://gist.github.com/neverinfamous/5d77fb0bf37179effcdc64ecce4f4de2)** - Standup, retrospectives, and weekly digests
5. **[Git Integration & Context Capture](https://gist.github.com/neverinfamous/bf31ca9f0949993275d9d947a2284598)** - Automatic project context from Git and GitHub
---
## 🔗 Resources
- **[GitHub Wiki](https://github.com/neverinfamous/memory-journal-mcp/wiki)** - Complete documentation
- **[GitHub Gists](https://gist.github.com/neverinfamous/ffedec3bdb5da08376a381733b80c1a7)** - 5 practical examples and use cases
- **[Docker Hub](https://hub.docker.com/r/writenotenow/memory-journal-mcp)** - Container images
- **[PyPI Package](https://pypi.org/project/memory-journal-mcp/)** - Python package
- **[MCP Registry](https://registry.modelcontextprotocol.io/)** - Official MCP listing
- **[GitHub Issues](https://github.com/neverinfamous/memory-journal-mcp/issues)** - Bug reports & feature requests
- **[Adamic Support](https://adamic.tech/)** - Project announcements
---
## 📄 License
MIT License - See [LICENSE](LICENSE) file for details.
## 🤝 Contributing
Built by developers, for developers. PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
Raw data
{
"_id": null,
"home_page": null,
"name": "memory-journal-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10.12",
"maintainer_email": null,
"keywords": "context, developer-tools, git, journaling, mcp, model-context-protocol, relationships, visualization",
"author": null,
"author_email": "Chris LeRoux <writenotenow@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f1/0d/362db90e640b1e45091a9ae581c1af9fefe0c3ccfb4663f32072d34e9eea/memory_journal_mcp-1.2.2.tar.gz",
"platform": null,
"description": "# Memory Journal MCP Server\n\nLast Updated October 26, 2025 - Production/Stable v1.2.2\n\n<!-- mcp-name: io.github.neverinfamous/memory-journal-mcp -->\n\n[](https://github.com/neverinfamous/memory-journal-mcp)\n[](https://hub.docker.com/r/writenotenow/memory-journal-mcp)\n[](https://opensource.org/licenses/MIT)\n\n\n[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.neverinfamous/memory-journal-mcp)\n[](https://pypi.org/project/memory-journal-mcp/)\n[](SECURITY.md)\n[](https://github.com/neverinfamous/memory-journal-mcp/security/code-scanning)\n[](https://github.com/neverinfamous/memory-journal-mcp)\n\n*A production-ready developer journal with knowledge graphs, visual relationship mapping, and intelligent search*\n\n**\ud83c\udf89 Now Production/Stable!** Memory Journal has graduated from beta with powerful relationship mapping, 10x faster startup, and comprehensive documentation.\n\n**\ud83d\ude80 Quick Deploy:**\n- **[PyPI Package](https://pypi.org/project/memory-journal-mcp/)** - `pip install memory-journal-mcp`\n- **[Docker Hub](https://hub.docker.com/r/writenotenow/memory-journal-mcp)** - Alpine-based (225MB) with full semantic search\n- **[MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.neverinfamous/memory-journal-mcp)** - Discoverable by MCP clients\n\n**\ud83d\udcda Full Documentation:** [GitHub Wiki](https://github.com/neverinfamous/memory-journal-mcp/wiki)\n\n**\ud83d\udcf0 [Read the v1.1.2 Release Article](https://adamic.tech/articles/2025-10-04-memory-journal-mcp-v1-1-2)** - Learn about knowledge graphs, performance optimizations, and relationship mapping\n\n---\n\n## \u2728 What's New in v1.2.2 (Security Patch - October 26, 2025)\n\n### \ud83d\udd12 **Security Fix: URL Parsing Vulnerability (CodeQL #110, #111)**\nFixed incomplete URL substring sanitization in GitHub remote URL parsing:\n- **Proper URL validation** - Implemented `urllib.parse.urlparse()` with exact hostname matching\n- **Prevented URL spoofing** - Blocks malicious URLs like `http://evil.com/github.com/fake/repo`\n- **Enhanced security** - SSH URLs use explicit prefix validation, HTTPS URLs use proper parsing\n- **No breaking changes** - Drop-in replacement maintaining full compatibility\n\n### Technical Details\n- **Vulnerability**: CWE-20 (Improper Input Validation)\n- **Severity**: Medium (limited to Git remote URL parsing in local repositories)\n- **Fix**: Replaced substring checks (`'github.com' in url`) with proper `urlparse()` validation\n- **Reference**: [CodeQL Rule py/incomplete-url-substring-sanitization](https://codeql.github.com/codeql-query-help/python/py-incomplete-url-substring-sanitization/)\n\nThis security patch maintains full compatibility with v1.2.x - simply upgrade to receive the fix.\n\n---\n\n## \u2728 What's New in v1.2.1 (Patch Release - October 26, 2025)\n\n### \ud83d\udc1b **Critical Bug Fix: Semantic Search Initialization**\nFixed a critical async/lazy loading race condition that could cause semantic search to hang on first use:\n- **First semantic_search now completes in <1 second** (was: could timeout after 30+ seconds)\n- **Eliminated async lock deadlocks** during ML model loading\n- **Enhanced thread pool** from 2 to 4 workers for better concurrent operations\n- **No more need to cancel and retry** - reliable semantic search on every server restart\n\nThis patch release maintains full compatibility with v1.2.0 - simply upgrade and restart your MCP client.\n\n---\n\n## \u2728 What's New in v1.2.0 (Organization Support)\n\n### \ud83c\udfe2 **Organization-Level GitHub Projects** - Team Collaboration Ready\nFull support for organization-level projects alongside user projects:\n- **Automatic Owner Detection** - Detects whether repo belongs to user or organization\n- **Dual Project Lookup** - Shows both user and org projects in context\n- **Org Project Analytics** - All features work seamlessly with org projects\n- **Separate Token Support** - Optional `GITHUB_ORG_TOKEN` for org-specific permissions\n- **Zero Breaking Changes** - Fully backward compatible\n\n### \ud83d\udd27 **Enhanced Features for Organizations**\nAll advanced project analytics now support org projects:\n- **Cross-Project Insights** - Analyze patterns across user AND org projects\n- **Status Summaries** - Comprehensive reports for org project teams\n- **Milestone Tracking** - Track org-level milestones and team velocity\n- **Project Timelines** - Combined journal + GitHub activity for org projects\n- **Smart Caching** - 80%+ API reduction for both user and org projects (24hr owner type cache, 1hr project cache)\n\n### \ud83d\udcca **Advanced Project Analytics** - Deep Insights Across Projects\n- **Cross-Project Insights** - Analyze patterns across all tracked projects\n- **Project Breakdown** - Time distribution and activity analysis per project\n- **Velocity Tracking** - Measure productivity with entries per week\n- **Smart Caching** - 80%+ reduction in API calls with intelligent caching (1hr TTL)\n- **Inactive Project Detection** - Automatically identify projects needing attention\n\n### \ud83d\udcc8 **Project Status & Milestone Tracking**\n- **Status Summary Prompt** - Comprehensive project reports with GitHub data integration\n- **Milestone Tracker** - Progress visualization with velocity charts\n- **Project Timeline Resource** - Live activity feed combining journal + GitHub events\n- **Item Status Monitoring** - Track completion rates and project item states\n\n### \ud83d\udd17 **GitHub Projects Integration** - Enhanced Context Awareness\nSeamlessly connect your journal entries with GitHub Projects:\n- **Automatic Project Detection** - Detects GitHub Projects associated with current repository (user & org)\n- **Active Work Items** - Shows what you're actively working on from projects\n- **Entry-Project Linking** - Associate journal entries with specific projects and items\n- **Project Filtering** - Search and filter entries by project number\n- **Graceful Degradation** - Works perfectly without GitHub token (features degrade gracefully)\n\n### \ud83c\udf89 **v1.2.0 - Capabilities**\nBuilding on the stable v1.1.3 foundation:\n- **16 MCP tools** (up from 15) - Added `get_cross_project_insights`\n- **10 workflow prompts** (up from 8) - Added `project-status-summary` and `project-milestone-tracker`\n- **4 MCP resources** (up from 3) - Added `memory://projects/{number}/timeline`\n- **Smart caching system** - GitHub API response caching with configurable TTLs\n- **Enhanced analytics** - Project breakdown support in `get_statistics`\n- **Backward compatible** - Seamless upgrade from v1.1.x with automatic schema migration\n\n### \ud83d\udd17 **Entry Relationships & Knowledge Graphs**\nBuild connections between your entries with typed relationships:\n- `references` - General connections between work\n- `implements` - Link implementations to specs/designs\n- `clarifies` - Add explanations and elaborations\n- `evolves_from` - Track how ideas develop over time\n- `response_to` - Thread conversations and replies\n\n### \ud83d\udcca **Visual Relationship Mapping**\nGenerate beautiful Mermaid diagrams showing how your work connects:\n\n```mermaid\ngraph TD\n E55[\"#55: Implementing visualization feature<br/>development_note\"]\n E56[\"#56: Testing the new tool<br/>technical_note\"]\n E57[\"#57: Documentation improvements<br/>enhancement\"]\n \n E56 ==>|implements| E55\n E57 -.->|clarifies| E55\n \n style E55 fill:#FFF3E0\n style E56 fill:#FFF3E0\n style E57 fill:#FFF3E0\n```\n\n### \u26a1 **Performance Revolution**\n- **10x faster startup** - Lazy loading reduces init time from 14s \u2192 2-3s\n- **Thread-safe operations** - Zero race conditions in concurrent tag creation\n- **Database lock prevention** - Single-connection transactions eliminate conflicts\n- **Optimized queries** - Strategic indexes for relationship traversal\n\n### \ud83d\udee0\ufe0f **New Tools** (15 Total, +2 from v1.0)\n- `visualize_relationships` - Generate Mermaid diagrams with depth control\n- `link_entries` - Create typed relationships between entries\n- Plus comprehensive CRUD, triple search, analytics, and export\n\n### \ud83c\udfaf **Enhanced Workflow Prompts** (8 Total, +2 from v1.0)\n- `find-related` - Discover connected entries via semantic similarity\n- `prepare-standup` - Daily standup summaries\n- `prepare-retro` - Sprint retrospectives\n- `weekly-digest` - Day-by-day weekly summaries\n- `analyze-period` - Deep period analysis with insights\n- `goal-tracker` - Milestone and achievement tracking\n- `get-context-bundle` - Project context with Git/GitHub\n- `get-recent-entries` - Formatted recent entries\n\n### \ud83d\udce1 **New Resources** (3 Total, +1 from v1.0)\n- `memory://graph/recent` - **NEW** Live Mermaid diagram of recent relationships\n- `memory://recent` - 10 most recent entries\n- `memory://significant` - Significant milestones and breakthroughs\n\n### \ud83d\uddc4\ufe0f **Database Improvements**\n- Automatic schema migrations (seamless v1.0 \u2192 v1.1 upgrades)\n- Soft delete support with `deleted_at` column\n- New `relationships` table with cascading deletes\n- Enhanced indexes for optimal query performance\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### Option 1: PyPI (Fastest - 30 seconds)\n\n**Step 1: Install the package**\n\n```bash\npip install memory-journal-mcp\n```\n\n**Step 2: Add to ~/.cursor/mcp.json**\n\n```json\n{\n \"mcpServers\": {\n \"memory-journal\": {\n \"command\": \"memory-journal-mcp\"\n }\n }\n}\n```\n\n**Step 3: Restart Cursor**\n\nRestart Cursor or your MCP client, then start journaling!\n\n### Option 2: Docker (Full Features - 2 minutes)\n\n**Step 1: Pull the Docker image**\n\n```bash\ndocker pull writenotenow/memory-journal-mcp:latest\n```\n\n**Step 2: Create data directory**\n\n```bash\nmkdir data\n```\n\n**Step 3: Add to ~/.cursor/mcp.json**\n\n```json\n{\n \"mcpServers\": {\n \"memory-journal\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"--rm\", \"-i\", \n \"-v\", \"./data:/app/data\",\n \"writenotenow/memory-journal-mcp:latest\",\n \"python\", \"src/server.py\"\n ]\n }\n }\n}\n```\n\n**Step 4: Restart Cursor**\n\nRestart Cursor or your MCP client, then start journaling!\n\n---\n\n## \u26a1 **Install to Cursor IDE**\n\n### **One-Click Installation**\n\nClick the button below to install directly into Cursor:\n\n[](cursor://anysphere.cursor-deeplink/mcp/install?name=Memory%20Journal%20MCP&config=eyJtZW1vcnktam91cm5hbCI6eyJhcmdzIjpbInJ1biIsIi0tcm0iLCItaSIsIi12IiwiLi9kYXRhOi9hcHAvZGF0YSIsIndyaXRlbm90ZW5vdy9tZW1vcnktam91cm5hbC1tY3A6bGF0ZXN0IiwicHl0aG9uIiwic3JjL3NlcnZlci5weSJdLCJjb21tYW5kIjoiZG9ja2VyIn19)\n\nOr copy this deep link:\n```\ncursor://anysphere.cursor-deeplink/mcp/install?name=Memory%20Journal%20MCP&config=eyJtZW1vcnktam91cm5hbCI6eyJhcmdzIjpbInJ1biIsIi0tcm0iLCItaSIsIi12IiwiLi9kYXRhOi9hcHAvZGF0YSIsIndyaXRlbm90ZW5vdy9tZW1vcnktam91cm5hbC1tY3A6bGF0ZXN0IiwicHl0aG9uIiwic3JjL3NlcnZlci5weSJdLCJjb21tYW5kIjoiZG9ja2VyIn19\n```\n\n### **Prerequisites**\n- \u2705 Docker installed and running\n- \u2705 ~500MB disk space for data directory\n\n### **Configuration**\n\nAfter installation, Cursor will use this Docker-based configuration. If you prefer manual setup, add this to your `~/.cursor/mcp.json`:\n\n```json\n{\n \"memory-journal\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"--rm\", \"-i\",\n \"-v\", \"./data:/app/data\",\n \"writenotenow/memory-journal-mcp:latest\",\n \"python\", \"src/server.py\"\n ]\n }\n}\n```\n\n**\ud83d\udcd6 [See Full Installation Guide \u2192](https://github.com/neverinfamous/memory-journal-mcp/wiki/Installation)**\n\n---\n\n## \ud83d\udccb Core Capabilities\n\n### \ud83d\udee0\ufe0f **16 MCP Tools** - Complete Development Workflow\n**Entry Management:**\n- `create_entry` / `create_entry_minimal` - Create entries with auto-context and GitHub Projects linking\n- `update_entry` - Edit existing entries (thread-safe)\n- `delete_entry` - Soft or permanent deletion\n- `get_entry_by_id` - Retrieve with full relationship details and project info\n\n**Search & Discovery:**\n- `search_entries` - FTS5 full-text search with highlighting and project filtering\n- `search_by_date_range` - Time-based filtering with tags and projects\n- `semantic_search` - ML-powered similarity (optional)\n- `get_recent_entries` - Quick access to recent work\n\n**Relationships & Visualization:**\n- `link_entries` - Create typed relationships\n- `visualize_relationships` - Generate Mermaid diagrams\n\n**Organization & Analytics:**\n- `list_tags` - Tag usage statistics\n- `get_statistics` - Comprehensive analytics by time period with project breakdown\n- `get_cross_project_insights` - **NEW** - Cross-project pattern analysis\n- `export_entries` - JSON/Markdown export\n- `test_simple` - Connectivity testing\n\n### \ud83c\udfaf **10 Workflow Prompts** - Automated Productivity\n- **`prepare-standup`** - Daily standup summaries from recent entries\n- **`prepare-retro`** - Sprint retrospectives with achievements and learnings\n- **`weekly-digest`** - Day-by-day weekly summaries\n- **`analyze-period`** - Deep analysis with pattern insights\n- **`goal-tracker`** - Milestone and achievement tracking\n- **`find-related`** - Discover connected entries via semantic similarity\n- **`get-context-bundle`** - Complete project context (Git + GitHub)\n- **`get-recent-entries`** - Formatted display of recent work\n- **`project-status-summary`** - **NEW** - Comprehensive GitHub Project status reports\n- **`project-milestone-tracker`** - **NEW** - Milestone progress with velocity tracking\n\n### \ud83d\udd0d **Triple Search System** - Find Anything, Any Way\n1. **Full-text search** - SQLite FTS5 with result highlighting and rank ordering\n2. **Date range search** - Time-based filtering with tag and type filters\n3. **Semantic search** - FAISS vector similarity for concept-based discovery (optional)\n\n### \ud83d\udd17 **Entry Relationships** - Build Your Knowledge Graph\n- **5 relationship types** - references, implements, clarifies, evolves_from, response_to\n- **Bidirectional linking** - See both incoming and outgoing relationships\n- **Graph visualization** - Generate Mermaid diagrams with depth control\n- **Smart discovery** - Find related entries via semantic similarity and shared tags\n\n### \ud83d\udcca **Comprehensive Analytics** - Track Your Progress\n- Entry counts by type (achievements, notes, milestones, etc.)\n- Top tags with usage statistics\n- Activity patterns by day/week/month\n- Significant milestone tracking\n- Export-ready statistics for reports\n\n### \ud83c\udfa8 **Visual Relationship Graphs** - See How Work Connects\n- **3 visualization modes** - Entry-centric, tag-based, recent activity\n- **Customizable depth** - Control relationship traversal (1-3 hops)\n- **Tag filtering** - Focus on specific projects or topics\n- **Color-coded nodes** - Personal (blue) vs Project (orange) entries\n- **Typed arrows** - Different styles for different relationship types\n\n### \ud83d\udd04 **Git & GitHub Integration** - Automatic Context Capture\n- Repository name and path\n- Current branch\n- Latest commit (hash + message)\n- Recent GitHub issues (via `gh` CLI)\n- **GitHub Projects** - Automatic project detection and tracking (user & org)\n- **Organization Support** - Full support for org-level projects alongside user projects\n- **Project Analytics** - Cross-project insights, status summaries, milestone tracking (user & org)\n- **Smart API Caching** - 80%+ API call reduction (24hr owner type, 1hr projects, 15min items)\n- **Timeline Resources** - Combined journal + GitHub activity feeds for user & org projects\n- **Auto Owner Detection** - Automatically determines if repo belongs to user or organization\n- Working directory\n- Timestamp for all context\n\n### \ud83d\udce6 **Data Export** - Own Your Data\n- **JSON format** - Machine-readable with full metadata\n- **Markdown format** - Human-readable with beautiful formatting\n- **Flexible filtering** - By date range, tags, entry types, projects\n- **Portable** - Take your journal anywhere\n\n### \ud83d\udd27 **Configuration & Setup**\n\n**GitHub Projects Integration (Optional):**\n\nTo enable GitHub Projects features, set the `GITHUB_TOKEN` environment variable:\n\n```bash\n# Linux/macOS\nexport GITHUB_TOKEN=\"your_github_personal_access_token\"\n\n# Windows PowerShell\n$env:GITHUB_TOKEN=\"your_github_personal_access_token\"\n```\n\n**Organization Projects:**\n\nFor organization-level projects, you can optionally use a separate token:\n\n```bash\n# Linux/macOS\nexport GITHUB_ORG_TOKEN=\"your_org_access_token\"\nexport DEFAULT_ORG=\"your-org-name\" # Optional: default org for ambiguous contexts\n\n# Windows PowerShell\n$env:GITHUB_ORG_TOKEN=\"your_org_access_token\"\n$env:DEFAULT_ORG=\"your-org-name\"\n```\n\n**Required Scopes:**\n- User projects: `repo`, `project`\n- Org projects: `repo`, `project`, `read:org` (minimum)\n- Full org features: Add `admin:org` for team info\n\n**Fallback Options:**\n- Uses GitHub CLI (`gh`) if `GITHUB_TOKEN` is not available\n- Uses `GITHUB_TOKEN` if `GITHUB_ORG_TOKEN` not set\n- Works without GitHub token (project features gracefully disabled)\n- Auto-detects whether owner is user or organization\n\n---\n\n## \ud83d\udcd6 Usage Examples\n\n### Create an Entry with GitHub Projects\n\n```javascript\n// Create an entry linked to a GitHub Project\ncreate_entry({\n content: \"Completed Phase 1 of GitHub Projects integration - all core features implemented!\",\n entry_type: \"technical_achievement\",\n tags: [\"github-projects\", \"integration\", \"milestone\"],\n project_number: 1, // Links to GitHub Project #1\n significance_type: \"technical_breakthrough\"\n})\n// Context automatically includes GitHub Projects info\n\n// Search entries by project\nsearch_entries({\n project_number: 1,\n limit: 10\n})\n\n// Filter by project and date range\nsearch_by_date_range({\n start_date: \"2025-10-01\",\n end_date: \"2025-10-31\",\n project_number: 1\n})\n```\n\n### Create an Entry with Relationships\n\n```javascript\n// Create a technical achievement\ncreate_entry({\n content: \"Implemented lazy loading for ML dependencies - 10x faster startup!\",\n entry_type: \"technical_achievement\",\n tags: [\"performance\", \"optimization\", \"ml\"],\n significance_type: \"technical_breakthrough\"\n})\n// Returns: Entry #55\n\n// Link related work\nlink_entries({\n from_entry_id: 56, // Testing entry\n to_entry_id: 55, // Implementation\n relationship_type: \"implements\"\n})\n\n// Visualize the connections\nvisualize_relationships({\n entry_id: 55,\n depth: 2\n})\n```\n\n### Search and Analyze\n\n```javascript\n// Full-text search with highlighting\nsearch_entries({ query: \"performance optimization\", limit: 5 })\n\n// Semantic search for concepts\nsemantic_search({ query: \"startup time improvements\", limit: 3 })\n\n// Date range with tags\nsearch_by_date_range({\n start_date: \"2025-10-01\",\n end_date: \"2025-10-31\",\n tags: [\"performance\"]\n})\n\n// Get analytics\nget_statistics({ group_by: \"week\" })\n```\n\n### Generate Visual Maps\n\n```javascript\n// Visualize entry relationships\nvisualize_relationships({\n entry_id: 55, // Root entry\n depth: 2 // 2 hops out\n})\n\n// Filter by tags\nvisualize_relationships({\n tags: [\"visualization\", \"relationships\"],\n limit: 20\n})\n\n// Access live graph resource\nmemory://graph/recent // Most recent 20 entries with relationships\n```\n\n### Advanced Project Features\n\n```javascript\n// Cross-project insights\nget_cross_project_insights({\n start_date: \"2025-10-01\",\n end_date: \"2025-10-31\",\n min_entries: 3\n})\n// Returns: Active projects ranked by activity, time distribution, productivity patterns, inactive projects\n\n// Project statistics with breakdown\nget_statistics({\n start_date: \"2025-10-01\",\n end_date: \"2025-10-31\",\n group_by: \"week\",\n project_breakdown: true\n})\n// Returns: Standard stats PLUS entries per project, active days per project\n\n// Project status summary (prompt)\nproject-status-summary({\n project_number: 1,\n time_period: \"sprint\", // week, sprint, month\n include_items: true\n})\n// Returns: Project overview, journal activity, GitHub items status, key insights\n\n// Milestone tracking (prompt)\nproject-milestone-tracker({\n project_number: 1,\n milestone_name: \"v1.2.0\" // optional filter\n})\n// Returns: Milestone progress, velocity chart, journal activity summary\n\n// Access project timeline resource\nmemory://projects/1/timeline\n// Returns: Chronological feed of last 30 days (journal + GitHub events)\n```\n\n### Organization Project Support\n\n```javascript\n// Create entry with explicit org project\ncreate_entry({\n content: \"Sprint planning meeting - discussed Q4 roadmap\",\n entry_type: \"technical_note\",\n tags: [\"sprint-planning\", \"Q4\"],\n project_number: 5,\n project_owner: \"my-company\",\n project_owner_type: \"org\"\n})\n\n// Auto-detect works for org repos too! (detects owner type automatically)\ncreate_entry({\n content: \"Fixed critical bug in auth service\",\n project_number: 5 // Owner and type auto-detected from repo context\n})\n\n// Org project status summary\nproject-status-summary({\n project_number: 5,\n owner: \"my-company\",\n owner_type: \"org\",\n time_period: \"sprint\",\n include_items: true\n})\n// Returns: Org project overview, team activity, GitHub items, insights\n\n// Org milestone tracking\nproject-milestone-tracker({\n project_number: 5,\n owner: \"my-company\",\n owner_type: \"org\"\n})\n// Returns: Org milestone progress, team velocity, activity summary\n\n// Access org project timeline (explicit format)\nmemory://projects/my-company/org/5/timeline\n// Returns: Org project timeline with journal + GitHub events\n\n// Access org project timeline (auto-detect format)\nmemory://projects/5/timeline\n// Returns: Auto-detects if project belongs to org and fetches accordingly\n\n// Cross-project insights automatically includes org projects\nget_cross_project_insights({\n start_date: \"2025-10-01\",\n end_date: \"2025-10-31\"\n})\n// Returns: Insights across BOTH user and org projects\n```\n\n---\n\n## \ud83c\udfd7\ufe0f Architecture\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 MCP Server Layer (Async/Await) \u2502\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 Entry Creation \u2502 \u2502 Triple Search \u2502 \u2502 Relationship\u2502 \u2502\n\u2502 \u2502 with Context \u2502 \u2502 FTS5/Date/ML \u2502 \u2502 Mapping \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 Thread Pool Execution Layer \u2502\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 Git Operations \u2502 \u2502 Database Ops \u2502 \u2502 Lazy ML \u2502 \u2502\n\u2502 \u2502 (2s timeout) \u2502 \u2502 Single Conn \u2502 \u2502 Loading \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 SQLite Database with FTS5 + Relationships \u2502\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u2502\n\u2502 \u2502 entries + tags + relationships + embeddings + FTS \u2502\u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n---\n\n## \ud83d\udd27 Technical Highlights\n\n### Performance & Security\n- **Python 3.14** - Latest Python with free-threaded support (PEP 779), deferred annotations (PEP 649), and performance optimizations\n- **10x faster startup** - Lazy loading of ML dependencies (2-3s vs 14s)\n- **Thread-safe operations** - Zero race conditions in tag creation\n- **WAL mode** - Better concurrency and crash recovery\n- **Database lock prevention** - Single-connection transactions\n- **Aggressive timeouts** - Git operations fail-fast (2s per command)\n- **Input validation** - Length limits, parameterized queries, SQL injection prevention\n\n### Semantic Search (Optional)\n- **Model**: `all-MiniLM-L6-v2` (384-dimensional embeddings)\n- **Storage**: FAISS index for fast similarity search\n- **Graceful degradation**: Works perfectly without ML dependencies\n\n### Data & Privacy\n- **Local-first**: Single SQLite file, you own your data\n- **Portable**: Move your `.db` file anywhere\n- **Secure**: No external API calls, non-root Docker containers\n\n---\n\n## \ud83d\udcda Documentation\n\n**Full documentation available on the [GitHub Wiki](https://github.com/neverinfamous/memory-journal-mcp/wiki):**\n\n- [Installation Guide](https://github.com/neverinfamous/memory-journal-mcp/wiki/Installation)\n- [Tools Reference](https://github.com/neverinfamous/memory-journal-mcp/wiki/Tools)\n- [Prompts Guide](https://github.com/neverinfamous/memory-journal-mcp/wiki/Prompts)\n- [Relationship Visualization](https://github.com/neverinfamous/memory-journal-mcp/wiki/Visualization)\n- [Examples & Tutorials](https://github.com/neverinfamous/memory-journal-mcp/wiki/Examples)\n- [Architecture Deep Dive](https://github.com/neverinfamous/memory-journal-mcp/wiki/Architecture)\n\n### GitHub Gists: Practical Examples & Use Cases\n\n**[\u2192 View All Memory Journal Gists](https://gist.github.com/neverinfamous/ffedec3bdb5da08376a381733b80c1a7)**\n\nExplore 5 curated gists with real-world examples and implementation patterns:\n\n1. **[Complete Feature Showcase](https://gist.github.com/neverinfamous/ffedec3bdb5da08376a381733b80c1a7)** - All 15 tools, 8 prompts, and 3 resources\n2. **[Relationship Mapping & Knowledge Graphs](https://gist.github.com/neverinfamous/e5f3638dc76b2536df04a02af9647abd)** - Build knowledge graphs with typed relationships\n3. **[Triple Search System Guide](https://gist.github.com/neverinfamous/a484535fea7014e8822887abbd8abb38)** - Master FTS5, date range, and semantic search\n4. **[Workflow Automation & Prompts](https://gist.github.com/neverinfamous/5d77fb0bf37179effcdc64ecce4f4de2)** - Standup, retrospectives, and weekly digests\n5. **[Git Integration & Context Capture](https://gist.github.com/neverinfamous/bf31ca9f0949993275d9d947a2284598)** - Automatic project context from Git and GitHub\n\n---\n\n## \ud83d\udd17 Resources\n\n- **[GitHub Wiki](https://github.com/neverinfamous/memory-journal-mcp/wiki)** - Complete documentation\n- **[GitHub Gists](https://gist.github.com/neverinfamous/ffedec3bdb5da08376a381733b80c1a7)** - 5 practical examples and use cases\n- **[Docker Hub](https://hub.docker.com/r/writenotenow/memory-journal-mcp)** - Container images\n- **[PyPI Package](https://pypi.org/project/memory-journal-mcp/)** - Python package\n- **[MCP Registry](https://registry.modelcontextprotocol.io/)** - Official MCP listing\n- **[GitHub Issues](https://github.com/neverinfamous/memory-journal-mcp/issues)** - Bug reports & feature requests\n- **[Adamic Support](https://adamic.tech/)** - Project announcements\n\n---\n\n## \ud83d\udcc4 License\n\nMIT License - See [LICENSE](LICENSE) file for details.\n\n## \ud83e\udd1d Contributing\n\nBuilt by developers, for developers. PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Model Context Protocol server for personal journaling with context awareness, relationships, and visualization",
"version": "1.2.2",
"project_urls": {
"Documentation": "https://github.com/neverinfamous/memory-journal-mcp/wiki",
"Homepage": "https://github.com/neverinfamous/memory-journal-mcp",
"Issues": "https://github.com/neverinfamous/memory-journal-mcp/issues",
"Repository": "https://github.com/neverinfamous/memory-journal-mcp"
},
"split_keywords": [
"context",
" developer-tools",
" git",
" journaling",
" mcp",
" model-context-protocol",
" relationships",
" visualization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "879219dc3705a42a1386de5f6364c1377de6263cd6551774ab993d555bfa085c",
"md5": "0c467351d8baf6588b8551e2c3f011bd",
"sha256": "ea513e6a456304aee36838664da9b0434535ae605cdad998b7a97f3d130d8d56"
},
"downloads": -1,
"filename": "memory_journal_mcp-1.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0c467351d8baf6588b8551e2c3f011bd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10.12",
"size": 46764,
"upload_time": "2025-10-26T15:32:13",
"upload_time_iso_8601": "2025-10-26T15:32:13.342239Z",
"url": "https://files.pythonhosted.org/packages/87/92/19dc3705a42a1386de5f6364c1377de6263cd6551774ab993d555bfa085c/memory_journal_mcp-1.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f10d362db90e640b1e45091a9ae581c1af9fefe0c3ccfb4663f32072d34e9eea",
"md5": "91305572b99989df6265b4729bbe08d7",
"sha256": "74b11b057d6739dfce008feaad96eb90c6e04fc68b5304b4cada84b4f9eac0a0"
},
"downloads": -1,
"filename": "memory_journal_mcp-1.2.2.tar.gz",
"has_sig": false,
"md5_digest": "91305572b99989df6265b4729bbe08d7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10.12",
"size": 88056,
"upload_time": "2025-10-26T15:32:14",
"upload_time_iso_8601": "2025-10-26T15:32:14.588447Z",
"url": "https://files.pythonhosted.org/packages/f1/0d/362db90e640b1e45091a9ae581c1af9fefe0c3ccfb4663f32072d34e9eea/memory_journal_mcp-1.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 15:32:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "neverinfamous",
"github_project": "memory-journal-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "mcp",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "sentence-transformers",
"specs": [
[
">=",
"2.2.2"
]
]
},
{
"name": "faiss-cpu",
"specs": [
[
">=",
"1.7.4"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.21.0"
]
]
}
],
"lcname": "memory-journal-mcp"
}
JSON
