memory-journal-mcp 3.0.0

package/DOCKER_README.md

@@ -0,0 +1,377 @@
+# Memory Journal MCP Server
+
+Last Updated December 28, 2025 - v3.0.0
+
+[![GitHub](https://img.shields.io/badge/GitHub-neverinfamous/memory--journal--mcp-blue?logo=github)](https://github.com/neverinfamous/memory-journal-mcp)
+[![Docker Pulls](https://img.shields.io/docker/pulls/writenotenow/memory-journal-mcp)](https://hub.docker.com/r/writenotenow/memory-journal-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![Version](https://img.shields.io/badge/version-v3.0.0-green)
+![Status](https://img.shields.io/badge/status-Production%2FStable-brightgreen)
+[![npm](https://img.shields.io/npm/v/memory-journal-mcp)](https://www.npmjs.com/package/memory-journal-mcp)
+[![Security](https://img.shields.io/badge/Security-Enhanced-green.svg)](https://github.com/neverinfamous/memory-journal-mcp/blob/main/SECURITY.md)
+[![GitHub Stars](https://img.shields.io/github/stars/neverinfamous/memory-journal-mcp?style=social)](https://github.com/neverinfamous/memory-journal-mcp)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg)](https://github.com/neverinfamous/memory-journal-mcp)
+
+**Project context management for AI-assisted development - Maintain continuity across fragmented AI threads with persistent knowledge graphs and intelligent context recall**
+
+🎯 **Solve the AI Context Problem:** Bridge the gap between disconnected AI sessions. Memory Journal provides persistent project memory, enabling AI to access your complete development history, past decisions, and work patterns across any thread or timeframe.
+
+**[GitHub](https://github.com/neverinfamous/memory-journal-mcp)** • **[Wiki](https://github.com/neverinfamous/memory-journal-mcp/wiki)** • **[Changelog](https://github.com/neverinfamous/memory-journal-mcp/wiki/CHANGELOG)** • **[Release Article](https://adamic.tech/articles/memory-journal-mcp-server)**
+
+**🚀 Multiple Deployment Options:**
+- **[Docker Hub](https://hub.docker.com/r/writenotenow/memory-journal-mcp)** - Node.js Alpine-based multi-platform support
+- **[npm Package](https://www.npmjs.com/package/memory-journal-mcp)** - Simple `npm install -g` for local deployment
+- **[MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.neverinfamous/memory-journal-mcp)**
+
+---
+
+## 🎯 What This Does
+
+**Solve the AI Context Problem:** When working with AI across multiple threads, context is lost. Memory Journal provides persistent project memory - every AI conversation can access your complete development history, past decisions, and work patterns.
+
+### Key Benefits
+- 📝 **Auto-capture Git/GitHub context** (commits, branches, issues, PRs, projects)
+- 🔗 **Build knowledge graphs** linking specs → implementations → tests → PRs  
+- 🔍 **Triple search** (full-text, semantic, date range)
+- 📊 **Generate reports** (standups, retrospectives, PR summaries, status)
+- 🗄️ **Backup & restore** your journal data with one command
+
+---
+
+## ✨ v3.0.0 Highlights (December 28, 2025)
+
+### **🚀 Complete TypeScript Rewrite**
+- **Pure JS Stack** - No native compilation required (`sql.js` + `vectra` + `@xenova/transformers`)
+- **Cross-Platform** - Works on AMD64 and ARM64 without architecture-specific builds
+- **Strict Type Safety** - 100% TypeScript strict mode compliance
+- **MCP 2025-11-25 Compliance** - Full spec with behavioral annotations
+
+### **🗄️ New: Backup & Restore Tools**
+- `backup_journal` - Create timestamped database backups
+- `list_backups` - List all available backup files
+- `restore_backup` - Restore from any backup (with auto-backup before restore)
+
+### **📊 New: Server Health Resource**
+- `memory://health` - Database stats, backup info, vector index status, tool filter config
+
+### **27 MCP Tools • 14 Workflow Prompts • 14 Resources**
+- **8 tool groups** - `core`, `search`, `analytics`, `relationships`, `export`, `admin`, `github`, `backup`
+- **Knowledge graphs** - 5 relationship types, Mermaid diagram visualization
+- **Semantic search** - AI-powered conceptual search via `@xenova/transformers`
+
+---
+
+## 🚀 Quick Start (2 Minutes)
+
+### 1. Pull the Image
+
+```bash
+docker pull writenotenow/memory-journal-mcp:latest
+```
+
+### 2. Create Data Directory
+
+```bash
+mkdir data
+```
+
+### 3. Add to MCP Config
+
+Add this to your `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "memory-journal-mcp": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-v", "./data:/app/data",
+        "writenotenow/memory-journal-mcp:latest"
+      ]
+    }
+  }
+}
+```
+
+### 4. Restart & Journal!
+
+Restart Cursor or your MCP client and start journaling!
+
+### GitHub Integration (Optional)
+
+To enable GitHub tools (`get_github_issues`, `get_github_prs`, etc.), add environment variables:
+
+```json
+{
+  "mcpServers": {
+    "memory-journal-mcp": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-v", "./data:/app/data",
+        "-e", "GITHUB_TOKEN",
+        "-e", "GITHUB_REPO_PATH=/app/repo",
+        "-v", "/path/to/your/repo:/app/repo:ro",
+        "writenotenow/memory-journal-mcp:latest"
+      ],
+      "env": {
+        "GITHUB_TOKEN": "ghp_your_token_here"
+      }
+    }
+  }
+}
+```
+
+| Environment Variable | Description |
+|---------------------|-------------|
+| `GITHUB_TOKEN` | GitHub personal access token for API access |
+| `GITHUB_REPO_PATH` | Path to git repo inside container (mount your repo) |
+
+**Without `GITHUB_REPO_PATH`**: Explicitly provide `owner` and `repo` when calling GitHub tools.
+
+### Cursor Known Issues
+
+**Listing MCP Resources**: If the agent has trouble listing resources, instruct it to call `list_mcp_resources()` without specifying a server parameter. Using `server="memory-journal-mcp"` may return nothing (Cursor bug).
+
+---
+
+## ⚡ **Install to Cursor IDE**
+
+### **One-Click Installation**
+
+Click the button below to install directly into Cursor:
+
+[![Install to Cursor](https://img.shields.io/badge/Install%20to%20Cursor-Click%20Here-blue?style=for-the-badge)](cursor://anysphere.cursor-deeplink/mcp/install?name=Memory%20Journal%20MCP&config=eyJtZW1vcnktam91cm5hbC1tY3AiOnsiYXJncyI6WyJydW4iLCItLXJtIiwiLWkiLCItdiIsIi4vZGF0YTovYXBwL2RhdGEiLCJ3cml0ZW5vdGVub3cvbWVtb3J5LWpvdXJuYWwtbWNwOmxhdGVzdCJdLCJjb21tYW5kIjoiZG9ja2VyIn19)
+
+Or copy this deep link:
+```
+cursor://anysphere.cursor-deeplink/mcp/install?name=Memory%20Journal%20MCP&config=eyJtZW1vcnktam91cm5hbC1tY3AiOnsiYXJncyI6WyJydW4iLCItLXJtIiwiLWkiLCItdiIsIi4vZGF0YTovYXBwL2RhdGEiLCJ3cml0ZW5vdGVub3cvbWVtb3J5LWpvdXJuYWwtbWNwOmxhdGVzdCJdLCJjb21tYW5kIjoiZG9ja2VyIn19
+```
+
+### **Prerequisites**
+- ✅ Docker installed and running
+- ✅ ~300MB disk space available
+
+**📖 [See Full Installation Guide →](https://github.com/neverinfamous/memory-journal-mcp/wiki/Installation)**
+
+---
+
+## 🛡️ Supply Chain Security
+
+For enhanced security and reproducible builds, use SHA-pinned images:
+
+**Find SHA tags:** https://hub.docker.com/r/writenotenow/memory-journal-mcp/tags
+
+**Option 1: Multi-arch manifest (recommended)**
+```bash
+docker pull writenotenow/memory-journal-mcp:sha256-<manifest-digest>
+```
+
+**Option 2: Direct digest (maximum security)**
+```bash
+docker pull writenotenow/memory-journal-mcp@sha256:<manifest-digest>
+```
+
+**Security Features:**
+- ✅ **Build Provenance** - Cryptographic proof of build process
+- ✅ **SBOM Available** - Complete software bill of materials
+- ✅ **Supply Chain Attestations** - Verifiable build integrity
+- ✅ **Non-root Execution** - Minimal attack surface
+- ✅ **No Native Dependencies** - Pure JS stack reduces attack surface
+
+---
+
+## ⚡ Core Features
+
+### 🛠️ 27 MCP Tools (8 Groups)
+| Group | Tools | Description |
+|-------|-------|-------------|
+| `core` | 6 | Entry CRUD, tags, test |
+| `search` | 4 | Text search, date range, semantic, vector stats |
+| `analytics` | 2 | Statistics, cross-project insights |
+| `relationships` | 2 | Link entries, visualize graphs |
+| `export` | 1 | JSON/Markdown export |
+| `admin` | 4 | Update, delete, vector index management |
+| `github` | 5 | Issues, PRs, context integration |
+| `backup` | 3 | **NEW** Backup, list, restore |
+
+**[Complete tools documentation →](https://github.com/neverinfamous/memory-journal-mcp/wiki/Tools)**
+
+### 🎯 14 Workflow Prompts
+Standups • Retrospectives • Weekly digests • PR summaries • Code review prep • Goal tracking  
+**[Complete prompts guide →](https://github.com/neverinfamous/memory-journal-mcp/wiki/Prompts)**
+
+### 📡 14 Resources
+Including new `memory://health` for server diagnostics  
+**[Resources documentation →](https://github.com/neverinfamous/memory-journal-mcp/wiki/Resources)**
+
+---
+
+## 📖 Quick Examples
+
+```javascript
+// Create entry with auto-context
+create_entry({
+  content: "Implemented lazy ML loading",
+  tags: ["performance"]
+})
+
+// Create a backup before major changes
+backup_journal({ name: "pre_refactor" })
+
+// Check server health
+// Fetch memory://health resource
+
+// Search entries
+search_entries({ query: "performance" })
+
+// Access MCP resources
+memory://recent                  // Recent entries
+memory://health                  // Server diagnostics
+memory://projects/1/timeline     // Project timeline
+```
+
+**Ask Cursor AI naturally:**
+- "Show me my recent journal entries"
+- "Create a backup of my journal"
+- "Check the server health status"
+- "Find entries related to performance"
+
+**[See complete examples & prompts →](https://github.com/neverinfamous/memory-journal-mcp/wiki/Examples)**
+
+---
+
+## 🔧 Configuration
+
+### Optional Environment Variables
+
+```bash
+# GitHub integration (optional - enables Projects/Issues/PRs)
+-e GITHUB_TOKEN=your_token
+-e GITHUB_ORG_TOKEN=your_org_token  # For org projects
+-e DEFAULT_ORG=your-org-name
+
+# Tool filtering (optional - control which tools are exposed)
+-e MEMORY_JOURNAL_MCP_TOOL_FILTER="-github"
+
+# Database location
+-e DB_PATH=/app/data/custom.db
+```
+
+**Token Scopes:** `repo`, `project`, `read:org` (org projects only)  
+**[Full configuration guide →](https://github.com/neverinfamous/memory-journal-mcp/wiki/Installation#configuration)**
+
+### Tool Filtering
+
+Control which tools are exposed using `MEMORY_JOURNAL_MCP_TOOL_FILTER`:
+
+```bash
+docker run -i --rm \
+  -e MEMORY_JOURNAL_MCP_TOOL_FILTER="-github,-analytics" \
+  -v ./data:/app/data \
+  writenotenow/memory-journal-mcp:latest
+```
+
+**Common configurations:**
+
+```bash
+# Starter mode (core + search only)
+-e MEMORY_JOURNAL_MCP_TOOL_FILTER="starter"
+
+# Read-only mode (disable modifications)
+-e MEMORY_JOURNAL_MCP_TOOL_FILTER="readonly"
+
+# Full mode (all tools, default)
+-e MEMORY_JOURNAL_MCP_TOOL_FILTER="full"
+```
+
+**Available tool groups:** `core`, `search`, `analytics`, `relationships`, `export`, `admin`, `github`, `backup`
+
+**[Complete tool filtering guide →](https://github.com/neverinfamous/memory-journal-mcp/wiki/Tool-Filtering)**
+
+---
+
+## 📦 Image Details
+
+| Platform | Features | 
+|----------|----------|
+| **AMD64** (x86_64) | Complete: all tools, semantic search, Git context |
+| **ARM64** (Apple Silicon) | Complete: all tools, semantic search, Git context |
+
+**TypeScript v3.0 Image Benefits:**
+- **Node.js 22 on Alpine Linux** - Minimal footprint (~150MB compressed)
+- **Pure JS Stack** - No native compilation, identical features on all platforms
+- **sql.js** - SQLite in pure JavaScript
+- **vectra** - Vector similarity search without native dependencies
+- **@xenova/transformers** - ML embeddings in JavaScript
+- **Instant Startup** - Lazy loading of ML models
+- **Production/Stable** - Comprehensive error handling and automatic migrations
+
+**Automated Deployment:**
+- ⚡ **Always Fresh** - Images built within minutes of commits
+- 🔒 **Security Scanned** - Automatic vulnerability scanning
+- 🌍 **Multi-Platform** - Intel (amd64) and Apple Silicon (arm64)
+- ✅ **Quality Tested** - Automated testing before deployment
+- 📋 **SBOM Available** - Complete software bill of materials
+
+**Available Tags:**
+- `3.0.0` - Specific version (recommended for production)
+- `3.0` - Latest patch in 3.0.x series
+- `3` - Latest minor in 3.x series
+- `latest` - Always the newest version
+- `sha256-<digest>` - SHA-pinned for maximum security
+
+---
+
+## 🏗️ Build from Source
+
+**Step 1: Clone the repository**
+
+```bash
+git clone https://github.com/neverinfamous/memory-journal-mcp.git
+cd memory-journal-mcp
+```
+
+**Step 2: Build the Docker image**
+
+```bash
+docker build -f Dockerfile -t memory-journal-mcp-local .
+```
+
+**Step 3: Add to MCP config**
+
+Update your `~/.cursor/mcp.json` to use the local build:
+
+```json
+{
+  "mcpServers": {
+    "memory-journal-mcp": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "-v", "./data:/app/data",
+        "memory-journal-mcp-local"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## 📚 Documentation & Resources
+
+- **[GitHub Wiki](https://github.com/neverinfamous/memory-journal-mcp/wiki)** - Complete documentation
+- **[npm Package](https://www.npmjs.com/package/memory-journal-mcp)** - Node.js distribution
+- **[Issues](https://github.com/neverinfamous/memory-journal-mcp/issues)** - Bug reports & feature requests
+
+---
+
+## 📄 License
+
+MIT License - See [LICENSE](https://github.com/neverinfamous/memory-journal-mcp/blob/main/LICENSE)
+
+---
+
+*Migrating from v2.x?* Your existing database is fully compatible. The TypeScript version uses the same schema and data format.

package/Dockerfile

@@ -0,0 +1,64 @@
+# Memory Journal MCP Server - TypeScript Version
+# Multi-stage build for optimized production image
+FROM node:22-alpine AS builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apk add --no-cache python3 make g++
+
+# Copy package files first for better layer caching
+COPY package*.json ./
+
+# Install all dependencies (including devDependencies for build)
+RUN npm ci
+
+# Copy source code
+COPY tsconfig.json ./
+COPY src/ ./src/
+
+# Build TypeScript
+RUN npm run build
+
+# Production stage
+FROM node:22-alpine
+
+WORKDIR /app
+
+# Install runtime dependencies
+RUN apk add --no-cache git ca-certificates && apk upgrade --no-cache
+
+# Copy built artifacts and production dependencies
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY package*.json ./
+COPY LICENSE ./
+
+# Create data directory for SQLite database with proper permissions
+RUN mkdir -p /app/data && chmod 700 /app/data
+
+# Create non-root user for security
+RUN addgroup -g 1001 -S appgroup && \
+    adduser -u 1001 -S appuser -G appgroup && \
+    chown -R appuser:appgroup /app
+
+# Set environment variables
+ENV NODE_ENV=production
+ENV DB_PATH=/app/data/memory_journal.db
+
+# Switch to non-root user
+USER appuser
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD node -e "console.log('Server healthy')" || exit 1
+
+# Run the MCP server
+CMD ["node", "dist/cli.js"]
+
+# Labels for Docker Hub
+LABEL maintainer="Adamic.tech"
+LABEL description="Memory Journal MCP Server - Project context management for AI-assisted development"
+LABEL version="3.0.0"
+LABEL org.opencontainers.image.source="https://github.com/neverinfamous/memory-journal-mcp"
+LABEL io.modelcontextprotocol.server.name="io.github.neverinfamous/memory-journal-mcp"

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Adamic.tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.