# 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)
