@whenmoon-afk/memory-mcp 2.0.0 → 2.1.0

package/README.md

@@ -1,12 +1,18 @@
 # claude-memory-mcp
 
-**Local, Persistent Memory for Any MCP-Compatible AI**  
+[![npm version](https://badge.fury.io/js/@whenmoon-afk%2Fmemory-mcp.svg)](https://www.npmjs.com/package/@whenmoon-afk/memory-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
+
+**Local, Persistent Memory for Any MCP-Compatible AI**
 A lightweight, **zero-cloud**, **token-efficient** Model Context Protocol (MCP) server that gives your AI **durable, searchable, and context-aware memory** - entirely under your control.
 
-Built with **TypeScript**, **SQLite + FTS5**, and **no external dependencies**, it runs locally and stores everything in a single, portable `.db` file.
+Built with **TypeScript**, **SQLite + FTS5**, and **minimal runtime dependencies** (MCP SDK + better-sqlite3), it runs locally and stores everything in a single, portable `.db` file.
 
 Works with **Claude Desktop**, **Cursor**, **Windsurf**, or any MCP client.
 
+📦 **Now available on npm**: Install with `npx @whenmoon-afk/memory-mcp`
+
 ---
 
 ## Why Local Memory?
@@ -40,20 +46,32 @@ Works with **Claude Desktop**, **Cursor**, **Windsurf**, or any MCP client.
 
 ### Prerequisites
 - Node.js ≥ 18
-- An **MCP-compatible client**
+- An **MCP-compatible client** (Claude Desktop, Cursor, Windsurf, etc.)
+
+### Option 1: NPM Package with Auto-Setup (Recommended)
 
-### Quick Install (NPM)
+**Automatic installation** (configures Claude Desktop for you):
 ```bash
 npx @whenmoon-afk/memory-mcp
 ```
 
-Or install globally:
+This will automatically:
+- Detect your operating system (macOS/Windows/Linux)
+- Add the memory server to your Claude Desktop configuration
+- Create a backup of your existing config
+- Configure the correct command format for your platform
+
+After installation, **restart Claude Desktop completely** (quit and reopen).
+
+**Or install globally**:
 ```bash
 npm install -g @whenmoon-afk/memory-mcp
 memory-mcp
 ```
 
-### From Source
+### Option 2: From Source
+
+For development or customization:
 ```bash
 git clone https://github.com/WhenMoon-afk/claude-memory-mcp.git
 cd claude-memory-mcp
@@ -67,15 +85,42 @@ npm run build
 
 ## Integrate with Your MCP Client
 
-Add to your client's MCP config:
+Add to your client's MCP config file:
+
+**Claude Desktop**:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+**Cursor/Windsurf**: Check your editor's MCP settings
 
-### Using NPM Package (Recommended)
+> **💡 Recommended**: Use the automatic installer (`npx @whenmoon-afk/memory-mcp`) which handles platform differences automatically.
+
+### Manual Configuration (macOS/Linux)
 ```json
 {
   "mcpServers": {
     "memory": {
       "command": "npx",
-      "args": ["@whenmoon-afk/memory-mcp"],
+      "args": ["-y", "@whenmoon-afk/memory-mcp"],
+      "env": {
+        "MEMORY_DB_PATH": "./memory.db"
+      }
+    }
+  }
+}
+```
+
+### Manual Configuration (Windows)
+
+**Windows requires the `cmd /c` wrapper** to execute npx properly:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@whenmoon-afk/memory-mcp"],
       "env": {
         "MEMORY_DB_PATH": "./memory.db"
       }
@@ -234,6 +279,23 @@ Your AI **knows what it knows** — and can ask for more.
 
 ---
 
+## Dependencies
+
+This project uses minimal runtime dependencies to keep the package lightweight:
+
+| Dependency | Version | Purpose |
+|-----------|---------|---------|
+| `@modelcontextprotocol/sdk` | ^1.0.4 | Official MCP protocol implementation |
+| `better-sqlite3` | ^11.0.0 | Fast, native SQLite3 bindings with FTS5 support |
+
+**Why these dependencies?**
+- **MCP SDK**: Required for implementing the Model Context Protocol standard
+- **better-sqlite3**: Native performance for full-text search and database operations, essential for memory recall speed
+
+All other dependencies are dev-only (TypeScript, testing, linting).
+
+---
+
 ## Environment Variables
 
 | Var | Default | Description |
@@ -259,5 +321,32 @@ For sensitive data, use OS-level encryption (FileVault, BitLocker).
 4. **Reference provenance**: Track source and context for audit trails.
 5. **Backup `memory.db`** regularly — it's just a file!
 
+---
+
+## Quick Links
 
+- 📦 **NPM Package**: https://www.npmjs.com/package/@whenmoon-afk/memory-mcp
+- 🐙 **GitHub Repository**: https://github.com/WhenMoon-afk/claude-memory-mcp
+- 🐛 **Report Issues**: https://github.com/WhenMoon-afk/claude-memory-mcp/issues
+- 📖 **MCP Documentation**: https://modelcontextprotocol.io
+
+---
+
+## Contributing
+
+Contributions are welcome! Feel free to:
+- Report bugs or request features via [GitHub Issues](https://github.com/WhenMoon-afk/claude-memory-mcp/issues)
+- Submit pull requests for improvements
+- Share your use cases and feedback
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+**Copyright (c) 2025 WhenMoon-afk**
+
+---
 
+**Built with ❤️ for the MCP community**

package/dist/index.js

@@ -22,7 +22,7 @@ const config = {
  */
 const server = new Server({
     name: '@whenmoon-afk/memory-mcp',
-    version: '2.0.0',
+    version: '2.1.0',
 }, {
     capabilities: {
         tools: {},

package/install.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+/**
+ * Memory MCP Server - Automatic Installation Script
+ * Configures Claude Desktop to use the memory server
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { homedir, platform } from 'os';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Get Claude Desktop config path based on platform
+ */
+function getClaudeConfigPath() {
+  const plat = platform();
+
+  switch (plat) {
+    case 'darwin': // macOS
+      return join(homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+
+    case 'win32': // Windows
+      return join(process.env.APPDATA || join(homedir(), 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json');
+
+    default: // Linux and others
+      const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+      return join(configHome, 'Claude', 'claude_desktop_config.json');
+  }
+}
+
+/**
+ * Get platform-specific MCP server configuration
+ */
+function getMcpServerConfig() {
+  const plat = platform();
+
+  if (plat === 'win32') {
+    // Windows requires cmd /c wrapper for npx
+    return {
+      command: 'cmd',
+      args: ['/c', 'npx', '-y', '@whenmoon-afk/memory-mcp']
+    };
+  } else {
+    // macOS and Linux can use npx directly
+    return {
+      command: 'npx',
+      args: ['-y', '@whenmoon-afk/memory-mcp']
+    };
+  }
+}
+
+/**
+ * Install the memory server configuration
+ */
+function install() {
+  console.log('🧠 Memory MCP Server - Automatic Installation\n');
+
+  const configPath = getClaudeConfigPath();
+  const configDir = dirname(configPath);
+
+  // Ensure config directory exists
+  if (!existsSync(configDir)) {
+    console.log(`📁 Creating config directory: ${configDir}`);
+    try {
+      mkdirSync(configDir, { recursive: true });
+    } catch (error) {
+      console.error(`❌ Failed to create config directory: ${error.message}`);
+      console.log('\n⚠️  Please create the directory manually and run this installer again.');
+      process.exit(1);
+    }
+  }
+
+  // Read existing config or create new one
+  let config = { mcpServers: {} };
+  let isNewConfig = true;
+
+  if (existsSync(configPath)) {
+    isNewConfig = false;
+    console.log(`📖 Reading existing config: ${configPath}`);
+
+    try {
+      const configContent = readFileSync(configPath, 'utf-8');
+      config = JSON.parse(configContent);
+
+      // Ensure mcpServers object exists
+      if (!config.mcpServers) {
+        config.mcpServers = {};
+      }
+
+      // Create backup
+      const backupPath = `${configPath}.backup`;
+      writeFileSync(backupPath, configContent, 'utf-8');
+      console.log(`💾 Backup created: ${backupPath}`);
+
+    } catch (error) {
+      console.error(`❌ Failed to read/parse config file: ${error.message}`);
+      console.log('\n⚠️  Your config file may be corrupted. Please fix it manually or delete it to create a new one.');
+      process.exit(1);
+    }
+  } else {
+    console.log(`📝 Creating new config file: ${configPath}`);
+  }
+
+  // Add or update memory server configuration
+  const serverConfig = getMcpServerConfig();
+  const serverExists = config.mcpServers.memory !== undefined;
+
+  config.mcpServers.memory = serverConfig;
+
+  // Write updated config
+  try {
+    writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+
+    if (serverExists) {
+      console.log('✅ Memory server configuration updated!');
+    } else {
+      console.log('✅ Memory server configuration added!');
+    }
+
+  } catch (error) {
+    console.error(`❌ Failed to write config file: ${error.message}`);
+    console.log('\n⚠️  Please check file permissions and try again.');
+    process.exit(1);
+  }
+
+  // Display next steps
+  console.log('\n📋 Next Steps:');
+  console.log('1. Restart Claude Desktop completely (quit and reopen)');
+  console.log('2. The memory server will be available automatically');
+  console.log('3. Try asking Claude to "store a memory" or "recall memories about..."');
+
+  console.log('\n📍 Configuration Location:');
+  console.log(`   ${configPath}`);
+
+  if (platform() === 'win32') {
+    console.log('\n💡 Windows Note:');
+    console.log('   This installer configured the server with the cmd /c wrapper required for Windows.');
+  }
+
+  console.log('\n✨ Installation complete! Enjoy your persistent AI memory!\n');
+}
+
+// Run installer
+try {
+  install();
+} catch (error) {
+  console.error('❌ Installation failed:', error.message);
+  console.error('\n📖 For manual installation instructions, see:');
+  console.error('   https://github.com/WhenMoon-afk/claude-memory-mcp#readme');
+  process.exit(1);
+}

package/package.json

@@ -1,20 +1,22 @@
 {
   "name": "@whenmoon-afk/memory-mcp",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Brain-inspired memory for AI agents - MCP server",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {
-    "memory-mcp": "./dist/index.js"
+    "memory-mcp": "install.js"
   },
   "files": [
     "dist/",
+    "install.js",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "dev": "tsx watch src/index.ts",
     "build": "tsc",
+    "prepare": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -40,7 +42,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/whenmoon-afk/claude-memory-mcp.git"
+    "url": "git+https://github.com/whenmoon-afk/claude-memory-mcp.git"
   },
   "bugs": {
     "url": "https://github.com/whenmoon-afk/claude-memory-mcp/issues"