memory-journal-mcp 3.0.0

package/releases/v3.0.0.md

@@ -0,0 +1,236 @@
+# Memory Journal MCP v3.0.0 Release Notes
+
+**Release Date:** December 28, 2025
+
+---
+
+## 🎉 Overview
+
+Memory Journal v3.0.0 is a **complete ground-up rewrite in TypeScript**, delivering a pure JavaScript stack with zero native dependencies. This release deprecates and archives the Python codebase in favor of a modern, portable, strictly-typed implementation.
+
+---
+
+## 🚀 Highlights
+
+### Complete TypeScript Rewrite
+
+- **Strict Type Safety** - 100% TypeScript strict mode with zero lint errors
+- **Pure JS Stack** - No native compilation required:
+  - `sql.js` - SQLite in pure JavaScript
+  - `vectra` - Vector similarity search without native deps
+  - `@xenova/transformers` - ML embeddings in JavaScript
+- **Cross-Platform** - Works on Windows, macOS, Linux without binary dependencies
+- **Faster Startup** - Lazy ML model loading for instant cold starts
+- **MCP 2025-11-25 Compliance** - Full protocol spec compliance
+
+### Dynamic Structured Logging
+
+Enterprise-grade logging with RFC 5424 severity levels:
+
+- **Centralized Logger** - All output to stderr (stdout reserved for MCP protocol)
+- **Structured Format** - `[timestamp] [LEVEL] [MODULE] [CODE] message {context}`
+- **Module Prefixes** - Operation-specific codes like `DB_CONNECT`, `VECTOR_SEARCH`
+- **Debug Mode** - Enable with `DEBUG=true` environment variable
+
+### Tool Annotations (MCP 2025-11-25)
+
+All 27 tools now include behavioral hints:
+
+| Hint | Purpose |
+|------|---------|
+| `readOnlyHint` | Indicates read-only operations |
+| `destructiveHint` | Warns of data modification |
+| `idempotentHint` | Safe to retry |
+| `openWorldHint` | External service calls (GitHub) |
+
+---
+
+## ✨ New Features
+
+### Backup & Restore Tools
+
+Never lose your journal data again with the new `backup` tool group:
+
+| Tool | Description |
+|------|-------------|
+| `backup_journal` | Create timestamped database backups |
+| `list_backups` | List all available backup files |
+| `restore_backup` | Restore from any backup (with auto-backup before restore) |
+
+```javascript
+// Create a named backup
+backup_journal({ name: "before_migration" })
+// → { success: true, filename: "before_migration.db", sizeBytes: 524288 }
+
+// List available backups  
+list_backups()
+// → { backups: [...], total: 3, backupsDirectory: "~/.memory-journal/backups" }
+
+// Restore with safety (auto-creates backup before restore)
+restore_backup({ filename: "before_migration.db", confirm: true })
+// → { success: true, previousEntryCount: 50, newEntryCount: 42 }
+```
+
+### Server Health Resource
+
+New `memory://health` resource provides comprehensive diagnostics:
+
+```json
+{
+  "database": {
+    "path": "~/.memory-journal/memory_journal.db",
+    "sizeBytes": 524288,
+    "entryCount": 150,
+    "deletedEntryCount": 5,
+    "relationshipCount": 42,
+    "tagCount": 28
+  },
+  "backups": {
+    "directory": "~/.memory-journal/backups",
+    "count": 3,
+    "lastBackup": { "filename": "...", "createdAt": "...", "sizeBytes": 524288 }
+  },
+  "vectorIndex": {
+    "available": true,
+    "indexedEntries": 150,
+    "modelName": "all-MiniLM-L6-v2"
+  },
+  "toolFilter": {
+    "active": false,
+    "enabledCount": 27,
+    "totalCount": 27
+  },
+  "timestamp": "2025-12-28T05:47:00Z"
+}
+```
+
+---
+
+## 📊 Capabilities Summary
+
+| Category | Count | Details |
+|----------|-------|---------|
+| **MCP Tools** | 27 | +3 backup tools from v2.x |
+| **Tool Groups** | 8 | core, search, analytics, relationships, export, admin, github, **backup** |
+| **Workflow Prompts** | 14 | Standups, retros, PR workflows, CI/CD analysis |
+| **Resources** | 14 | +1 health resource from v2.x |
+| **Relationship Types** | 5 | relates_to, blocks, follows_up, parent_of, references |
+
+---
+
+## 🔧 Technical Improvements
+
+### Architecture
+
+- **Modular File Structure** - Clean separation of concerns
+- **Handler Pattern** - Dedicated handlers for tools, prompts, resources
+- **Type-Safe Database Layer** - Full TypeScript types for SQLite operations
+- **Centralized Constants** - Server instructions and configuration
+
+### CI/CD Modernization
+
+- **Native ARM64 Builds** - No more slow QEMU emulation
+- **NPM Publishing** - Replaces PyPI distribution
+- **CodeQL Analysis** - Static security analysis
+- **Docker Scout** - Container vulnerability scanning
+- **Dependabot Auto-Merge** - Automatic patch/minor updates
+
+### Security
+
+- **Input Validation** - Zod schemas for all tool parameters
+- **Path Traversal Protection** - Backup filename validation
+- **SQL Injection Prevention** - Parameterized queries throughout
+- **Content Size Limits** - Configurable per field
+
+---
+
+## ⬆️ Migration from v2.x
+
+### Breaking Changes
+
+- **Python Deprecated** - The Python codebase is archived at `archive/python-v2`
+- **Installation Changed** - Now via npm instead of pip:
+  ```bash
+  # Old (Python)
+  pip install memory-journal-mcp
+  
+  # New (TypeScript)
+  npm install -g memory-journal-mcp
+  ```
+
+### Database Compatibility
+
+✅ **Your existing database is fully compatible!**
+
+The TypeScript version uses the same SQLite schema and data format. No migration needed.
+
+### Configuration Changes
+
+Update your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "memory-journal-mcp": {
+      "command": "memory-journal-mcp"
+    }
+  }
+}
+```
+
+Or use npx (no installation):
+
+```json
+{
+  "mcpServers": {
+    "memory-journal-mcp": {
+      "command": "npx",
+      "args": ["-y", "memory-journal-mcp"]
+    }
+  }
+}
+```
+
+---
+
+## 📦 Installation
+
+### npm (Recommended)
+
+```bash
+npm install -g memory-journal-mcp
+```
+
+### Docker
+
+```bash
+docker pull writenotenow/memory-journal-mcp:v3.0.0
+```
+
+### From Source
+
+```bash
+git clone https://github.com/neverinfamous/memory-journal-mcp.git
+cd memory-journal-mcp
+npm install
+npm run build
+```
+
+---
+
+## 📚 Resources
+
+- **[GitHub Repository](https://github.com/neverinfamous/memory-journal-mcp)**
+- **[npm Package](https://www.npmjs.com/package/memory-journal-mcp)**
+- **[Docker Hub](https://hub.docker.com/r/writenotenow/memory-journal-mcp)**
+- **[Documentation Wiki](https://github.com/neverinfamous/memory-journal-mcp/wiki)**
+
+---
+
+## 🙏 Acknowledgments
+
+Thank you to all users who provided feedback during the Python era. This TypeScript rewrite addresses the core requests for better portability, faster startup, and stricter type safety.
+
+---
+
+**Full Changelog:** [v2.2.5...v3.0.0](https://github.com/neverinfamous/memory-journal-mcp/compare/v2.2.5...v3.0.0)

package/server.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
+  "name": "io.github.neverinfamous/memory-journal-mcp",
+  "title": "Memory Journal MCP",
+  "description": "MCP server– Project memory system with GitHub-aware context, knowledge graphs, and CI/PR timelines",
+  "version": "3.0.0",
+  "packages": [
+    {
+      "registryType": "oci",
+      "identifier": "docker.io/writenotenow/memory-journal-mcp:v3.0.0",
+      "version": "3.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "context-management",
+    "project-management",
+    "ai-assistant",
+    "knowledge-graph",
+    "developer-tools",
+    "git",
+    "github-projects",
+    "persistent-memory",
+    "thread-continuity",
+    "semantic-search"
+  ],
+  "author": {
+    "name": "Chris LeRoux",
+    "email": "writenotenow@gmail.com"
+  },
+  "homepage": "https://github.com/neverinfamous/memory-journal-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverinfamous/memory-journal-mcp.git",
+    "source": "github"
+  },
+  "license": "MIT"
+}

package/src/cli.ts

@@ -0,0 +1,52 @@
+/**
+ * Memory Journal MCP Server - CLI Entry Point
+ */
+
+import { Command } from 'commander';
+import { createServer } from './server/McpServer.js';
+import { logger } from './utils/logger.js';
+
+const program = new Command();
+
+program
+    .name('memory-journal-mcp')
+    .description('Project context management for AI-assisted development')
+    .version('3.0.0-alpha.1')
+    .option('--transport <type>', 'Transport type: stdio or http', 'stdio')
+    .option('--port <number>', 'HTTP port (for http transport)', '3000')
+    .option('--db <path>', 'Database path', './memory_journal.db')
+    .option('--tool-filter <filter>', 'Tool filter string (e.g., "starter", "core,search")')
+    .option('--log-level <level>', 'Log level: debug, info, warning, error', 'info')
+    .action(async (options: {
+        transport: string;
+        port: string;
+        db: string;
+        toolFilter?: string;
+        logLevel: string;
+    }) => {
+        // Set log level
+        logger.setLevel(options.logLevel as 'debug' | 'info' | 'warning' | 'error');
+
+        logger.info('Starting Memory Journal MCP Server', {
+            module: 'CLI',
+            transport: options.transport,
+            db: options.db,
+        });
+
+        try {
+            await createServer({
+                transport: options.transport as 'stdio' | 'http',
+                port: parseInt(options.port, 10),
+                dbPath: options.db,
+                toolFilter: options.toolFilter,
+            });
+        } catch (error) {
+            logger.error('Failed to start server', {
+                module: 'CLI',
+                error: error instanceof Error ? error.message : String(error),
+            });
+            process.exit(1);
+        }
+    });
+
+program.parse();

package/src/constants/ServerInstructions.ts

@@ -0,0 +1,25 @@
+/**
+ * Server instructions for Memory Journal MCP.
+ *
+ * These instructions are automatically sent to MCP clients during initialization,
+ * providing guidance for AI agents on tool usage.
+ */
+export const SERVER_INSTRUCTIONS = `# memory-journal-mcp
+
+Memory Journal MCP Server - Persistent project context management for AI-assisted development.
+
+## GitHub Tools
+
+GitHub tools auto-detect repository from the configured GITHUB_REPO_PATH.
+- If owner/repo are detected, they appear in \`detectedOwner\`/\`detectedRepo\` in responses
+- If not detected (null), specify \`owner\` and \`repo\` parameters explicitly
+
+## Tool Groups
+
+| Group | Tools |
+|-------|-------|
+| journal | create_entry, create_entry_minimal, update_entry, delete_entry |
+| search | search_entries, semantic_search, search_by_date_range |
+| github | get_github_issues, get_github_prs, get_github_issue, get_github_pr, get_github_context |
+| admin | backup_journal, list_backups, restore_backup, rebuild_vector_index |
+`;