universal-memory-mcp 0.1.2 → 0.2.0

package/README.md

@@ -2,17 +2,36 @@
 
 MCP Server for persistent AI memory across sessions. Works with any MCP-compatible AI CLI.
 
-## Installation
+## Features
+
+- **Automatic Setup**: Installs MCP server and memory-assistant skill automatically
+- **Persistent Memory**: Remember conversations across sessions
+- **Smart Recall**: AI automatically searches past discussions when relevant
+- **Long-term Storage**: Store preferences, decisions, and important facts
+
+## Quick Start
 
 ```bash
 npm install -g universal-memory-mcp
 ```
 
-## Configuration
+That's it! The installer will:
+1. Configure MCP server in `~/.claude/settings.json`
+2. Install memory-assistant skill to `~/.claude/skills/`
+3. Prompt you to restart Claude Code
 
-### Claude Desktop
+**After restart**, Claude will automatically:
+- Search past conversations when you reference them
+- Record important conversations for future recall
+- Remember your preferences and decisions
 
-Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+## Manual Configuration
+
+If automatic setup doesn't work, configure manually:
+
+### Claude Code CLI
+
+Edit `~/.claude/settings.json`:
 
 ```json
 {
@@ -25,9 +44,9 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-### Claude Code CLI
+### Claude Desktop
 
-Edit `~/.config/claude/settings.json`:
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ```json
 {
@@ -40,9 +59,21 @@ Edit `~/.config/claude/settings.json`:
 }
 ```
 
-## Tools
+## How It Works
+
+### Memory Assistant Skill
+
+The installed skill guides Claude to use memory tools automatically:
+
+| Trigger | Action |
+|---------|--------|
+| User mentions "之前", "上次", "remember", "we talked about" | Search past memories |
+| End of meaningful conversation | Record the exchange |
+| User expresses preference or makes decision | Store in long-term memory |
 
-### memory_search
+### MCP Tools
+
+#### memory_search
 
 Search through conversation history and long-term memories.
 
@@ -55,13 +86,7 @@ Search through conversation history and long-term memories.
 }
 ```
 
-**When to use:**
-- User asks about past discussions
-- User references "we talked about before"
-- Need to know user preferences (search "preferences")
-- Need context from previous sessions
-
-### memory_record
+#### memory_record
 
 Record conversation for future reference.
 
@@ -73,11 +98,7 @@ Record conversation for future reference.
 }
 ```
 
-**When to use:**
-- After every meaningful conversation exchange
-- To ensure continuity across sessions
-
-### memory_update_long_term
+#### memory_update_long_term
 
 Store important information for easy retrieval.
 
@@ -94,24 +115,6 @@ Store important information for easy retrieval.
 - `facts` - Key information about user/projects
 - `contacts` - People and teams
 
-## How It Works
-
-```
-User asks about past discussion
-        │
-        ▼
-AI calls memory_search("topic")
-        │
-        ▼
-Returns relevant memories
-        │
-        ▼
-AI responds with context
-        │
-        ▼
-AI calls memory_record() to save this exchange
-```
-
 ## Storage
 
 All data stored locally in `~/.ai_memory/`:
@@ -124,10 +127,29 @@ All data stored locally in `~/.ai_memory/`:
 └── config.json      # Configuration
 ```
 
+## Troubleshooting
+
+### MCP tools not available
+
+1. Ensure you've restarted Claude Code after installation
+2. Check `~/.claude/settings.json` contains the MCP configuration
+3. Try running `npx universal-memory-mcp` directly to test
+
+### Skill not triggering
+
+1. Check `~/.claude/skills/memory-assistant/SKILL.md` exists
+2. Restart Claude Code to reload skills
+3. Try explicitly asking Claude to "search my memories for X"
+
 ## Development
 
 ```bash
+git clone https://github.com/slicenferqin/universal-memory-mcp.git
+cd universal-memory-mcp
 pnpm install
 pnpm build
-node dist/index.js
 ```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-memory-mcp",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "MCP Server for persistent AI memory across sessions",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,7 +19,8 @@
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
     "start": "node dist/index.js",
-    "test": "vitest"
+    "test": "vitest",
+    "postinstall": "node scripts/postinstall.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
@@ -48,6 +49,7 @@
   "homepage": "https://github.com/slicenferqin/universal-memory-mcp#readme",
   "files": [
     "dist",
+    "scripts",
     "README.md"
   ]
 }

package/scripts/postinstall.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+
+/**
+ * Universal Memory MCP - Postinstall Script
+ *
+ * Automatically configures:
+ * 1. MCP server in Claude Code settings
+ * 2. Memory assistant skill
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const CLAUDE_SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
+const CLAUDE_SKILLS_PATH = path.join(os.homedir(), '.claude', 'skills');
+
+// MCP server configuration
+const MCP_CONFIG = {
+  'universal-memory': {
+    command: 'npx',
+    args: ['-y', 'universal-memory-mcp'],
+  },
+};
+
+// Skill content
+const SKILL_CONTENT = `---
+name: memory-assistant
+description: |
+  Automatic conversation memory management using universal-memory MCP.
+
+  ALWAYS activate this skill to:
+  1. SEARCH memories when user mentions: "之前", "上次", "我们讨论过", "remember", "we talked about", "what did we decide"
+  2. RECORD conversations at the END of EVERY meaningful response
+  3. STORE long-term info when discovering: user preferences, important decisions, key facts
+
+  This skill ensures AI maintains persistent memory across all sessions.
+---
+
+# Memory Assistant
+
+You have access to persistent memory through the universal-memory MCP tools. Use them proactively.
+
+## Core Rules
+
+### 1. Always Search Before Answering (When Relevant)
+
+When user references past conversations or asks about previous decisions:
+
+\`\`\`
+Call memory_search with relevant keywords
+\`\`\`
+
+Trigger phrases:
+- "之前", "上次", "我们讨论过", "记得吗"
+- "remember", "we talked about", "what did we decide", "last time"
+- Any reference to past discussions or decisions
+
+### 2. Always Record After Responding
+
+At the END of EVERY meaningful conversation exchange, call:
+
+\`\`\`
+memory_record({
+  user_message: "<summarize user's question/request>",
+  ai_response: "<key points of your response>",
+  project: "<current project name if applicable>"
+})
+\`\`\`
+
+What counts as "meaningful":
+- Technical discussions or decisions
+- Problem-solving conversations
+- User preferences expressed
+- Any information worth remembering
+
+What to skip:
+- Simple greetings ("hi", "thanks")
+- Trivial clarifications
+
+### 3. Store Important Long-term Information
+
+When you identify important information, immediately call:
+
+\`\`\`
+memory_update_long_term({
+  category: "preferences" | "decisions" | "facts" | "contacts",
+  content: "<the information>"
+})
+\`\`\`
+
+Categories:
+- **preferences**: User's coding style, tool preferences, communication style
+- **decisions**: Architecture choices, technology selections, design decisions
+- **facts**: Key information about user, projects, team structure
+- **contacts**: People, teams, organizations mentioned
+
+## Examples
+
+### Example 1: User References Past Discussion
+
+**User**: "我们之前讨论的认证方案是什么来着？"
+
+**Action**:
+1. Call \`memory_search({ query: "认证方案 authentication" })\`
+2. Use search results to answer
+3. Call \`memory_record\` to log this exchange
+
+### Example 2: User Expresses Preference
+
+**User**: "我喜欢用 TypeScript，不要给我 JavaScript 代码"
+
+**Action**:
+1. Acknowledge the preference
+2. Call \`memory_update_long_term({ category: "preferences", content: "用户偏好 TypeScript，不使用 JavaScript" })\`
+3. Call \`memory_record\` to log this exchange
+
+### Example 3: Technical Decision Made
+
+**User**: "好，我们就用 PostgreSQL 作为主数据库"
+
+**Action**:
+1. Confirm the decision
+2. Call \`memory_update_long_term({ category: "decisions", content: "选择 PostgreSQL 作为主数据库" })\`
+3. Call \`memory_record\` to log this exchange
+
+## Important Notes
+
+- Memory tools are provided by the universal-memory MCP server
+- If tools are not available, inform user to restart Claude Code
+- Always summarize, don't record full conversation text
+- Use project name when in a project context for better organization
+`;
+
+/**
+ * Read JSON file safely
+ */
+function readJsonFile(filePath) {
+  try {
+    if (fs.existsSync(filePath)) {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      return JSON.parse(content);
+    }
+  } catch (error) {
+    console.error(`Warning: Could not read ${filePath}:`, error.message);
+  }
+  return null;
+}
+
+/**
+ * Write JSON file with backup
+ */
+function writeJsonFile(filePath, data) {
+  const dir = path.dirname(filePath);
+
+  // Create directory if not exists
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Backup existing file
+  if (fs.existsSync(filePath)) {
+    const backupPath = `${filePath}.backup.${Date.now()}`;
+    fs.copyFileSync(filePath, backupPath);
+    console.log(`  Backed up existing config to: ${backupPath}`);
+  }
+
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+}
+
+/**
+ * Configure MCP server in Claude settings
+ */
+function configureMcpServer() {
+  console.log('\n📦 Configuring MCP server...');
+
+  let settings = readJsonFile(CLAUDE_SETTINGS_PATH) || {};
+
+  // Initialize mcpServers if not exists
+  if (!settings.mcpServers) {
+    settings.mcpServers = {};
+  }
+
+  // Check if already configured
+  if (settings.mcpServers['universal-memory']) {
+    console.log('  MCP server already configured');
+    return false;
+  }
+
+  // Add MCP configuration
+  settings.mcpServers = {
+    ...settings.mcpServers,
+    ...MCP_CONFIG,
+  };
+
+  writeJsonFile(CLAUDE_SETTINGS_PATH, settings);
+  console.log('  MCP server configured successfully');
+  return true;
+}
+
+/**
+ * Install memory assistant skill
+ */
+function installSkill() {
+  console.log('\n🎯 Installing memory-assistant skill...');
+
+  const skillDir = path.join(CLAUDE_SKILLS_PATH, 'memory-assistant');
+  const skillFile = path.join(skillDir, 'SKILL.md');
+
+  // Create skills directory if not exists
+  if (!fs.existsSync(skillDir)) {
+    fs.mkdirSync(skillDir, { recursive: true });
+  }
+
+  // Check if skill already exists
+  if (fs.existsSync(skillFile)) {
+    const existingContent = fs.readFileSync(skillFile, 'utf-8');
+    if (existingContent === SKILL_CONTENT) {
+      console.log('  Skill already installed (same version)');
+      return false;
+    }
+    // Backup existing skill
+    const backupPath = `${skillFile}.backup.${Date.now()}`;
+    fs.copyFileSync(skillFile, backupPath);
+    console.log(`  Backed up existing skill to: ${backupPath}`);
+  }
+
+  fs.writeFileSync(skillFile, SKILL_CONTENT);
+  console.log('  Skill installed successfully');
+  return true;
+}
+
+/**
+ * Main installation
+ */
+function main() {
+  console.log('╔════════════════════════════════════════════════════════════╗');
+  console.log('║         Universal Memory MCP - Setup                       ║');
+  console.log('╚════════════════════════════════════════════════════════════╝');
+
+  let needsRestart = false;
+
+  try {
+    // Configure MCP server
+    const mcpConfigured = configureMcpServer();
+    if (mcpConfigured) needsRestart = true;
+
+    // Install skill
+    const skillInstalled = installSkill();
+    if (skillInstalled) needsRestart = true;
+
+    // Summary
+    console.log('\n' + '═'.repeat(60));
+
+    if (needsRestart) {
+      console.log('\n✅ Setup complete!\n');
+      console.log('⚠️  IMPORTANT: Please restart Claude Code to enable the MCP server.\n');
+      console.log('After restart, Claude will automatically:');
+      console.log('  • Search past conversations when you reference them');
+      console.log('  • Record important conversations for future recall');
+      console.log('  • Remember your preferences and decisions\n');
+    } else {
+      console.log('\n✅ Already configured! No changes needed.\n');
+    }
+
+    console.log('📁 Configuration locations:');
+    console.log(`   MCP config: ${CLAUDE_SETTINGS_PATH}`);
+    console.log(`   Skill: ${path.join(CLAUDE_SKILLS_PATH, 'memory-assistant', 'SKILL.md')}`);
+    console.log(`   Memory storage: ${path.join(os.homedir(), '.ai_memory')}\n`);
+
+  } catch (error) {
+    console.error('\n❌ Setup failed:', error.message);
+    console.error('\nPlease configure manually. See README for instructions.');
+    process.exit(1);
+  }
+}
+
+main();