universal-memory-mcp 0.1.2

package/README.md

@@ -0,0 +1,133 @@
+# Universal Memory MCP Server
+
+MCP Server for persistent AI memory across sessions. Works with any MCP-compatible AI CLI.
+
+## Installation
+
+```bash
+npm install -g universal-memory-mcp
+```
+
+## Configuration
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "universal-memory": {
+      "command": "npx",
+      "args": ["-y", "universal-memory-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code CLI
+
+Edit `~/.config/claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "universal-memory": {
+      "command": "npx",
+      "args": ["-y", "universal-memory-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+### memory_search
+
+Search through conversation history and long-term memories.
+
+```json
+{
+  "query": "database decision",
+  "time_range": ["2026-01-01", "2026-01-31"],
+  "project": "my-project",
+  "limit": 10
+}
+```
+
+**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
+
+Record conversation for future reference.
+
+```json
+{
+  "user_message": "Help me design a REST API",
+  "ai_response": "Recommended RESTful patterns with resource-based URLs...",
+  "project": "my-project"
+}
+```
+
+**When to use:**
+- After every meaningful conversation exchange
+- To ensure continuity across sessions
+
+### memory_update_long_term
+
+Store important information for easy retrieval.
+
+```json
+{
+  "category": "preferences",
+  "content": "User prefers TypeScript over JavaScript"
+}
+```
+
+**Categories:**
+- `preferences` - User's working style and preferences
+- `decisions` - Important technical decisions
+- `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/`:
+
+```
+~/.ai_memory/
+├── daily/           # Daily conversation logs (YYYY-MM-DD.md)
+├── long_term/       # Important memories (MEMORY.md, preferences.md, etc.)
+├── projects/        # Project-specific state
+└── config.json      # Configuration
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+node dist/index.js
+```

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Universal Memory MCP Server
+ *
+ * Provides MCP tools for persistent memory across AI sessions:
+ * - memory_search: Search conversation history and long-term memories
+ * - memory_record: Record conversations
+ * - memory_update_long_term: Update long-term memory
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG"}

package/dist/index.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+/**
+ * Universal Memory MCP Server
+ *
+ * Provides MCP tools for persistent memory across AI sessions:
+ * - memory_search: Search conversation history and long-term memories
+ * - memory_record: Record conversations
+ * - memory_update_long_term: Update long-term memory
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { createMemoryManager } from 'universal-memory-core';
+// Create memory manager
+const memoryManager = createMemoryManager();
+// Create MCP Server
+const server = new Server({
+    name: 'universal-memory-mcp',
+    version: '0.1.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Define tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: 'memory_search',
+                description: `Search through conversation history and long-term memories.
+
+WHEN TO USE:
+- When user asks about past discussions, decisions, or preferences
+- When user references something "we talked about before"
+- When you need context from previous sessions
+- When user asks "what did we decide about X" or "remember when we..."
+- When you need to know user preferences (search "preferences" or specific topic)
+
+This searches across all recorded conversations and long-term memories.
+Use specific keywords for better results (e.g., "TypeScript preferences", "database decision").`,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        query: {
+                            type: 'string',
+                            description: 'Search keywords or question',
+                        },
+                        time_range: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Time range [start_date, end_date], format: YYYY-MM-DD',
+                        },
+                        project: {
+                            type: 'string',
+                            description: 'Filter by project name',
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Max results to return, default 10',
+                        },
+                    },
+                    required: ['query'],
+                },
+            },
+            {
+                name: 'memory_record',
+                description: `Record the current conversation exchange for future reference.
+
+WHEN TO USE:
+- After EVERY meaningful conversation exchange
+- When the conversation contains information worth remembering
+- To ensure continuity across sessions
+
+What to record:
+- user_message: The user's question or request
+- ai_response: Summary of your response (key points, not full text)
+
+This builds memory over time, allowing recall of past discussions in future sessions.`,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        user_message: {
+                            type: 'string',
+                            description: 'The user message/question',
+                        },
+                        ai_response: {
+                            type: 'string',
+                            description: 'Summary of your response (key points)',
+                        },
+                        project: {
+                            type: 'string',
+                            description: 'Project name if in a project context',
+                        },
+                        session_id: {
+                            type: 'string',
+                            description: 'Session ID for grouping related conversations',
+                        },
+                    },
+                    required: ['user_message', 'ai_response'],
+                },
+            },
+            {
+                name: 'memory_update_long_term',
+                description: `Store important information in long-term memory for easy retrieval.
+
+WHEN TO USE - Call this when you identify:
+- User preferences (coding style, tools, communication preferences)
+- Important decisions (architecture choices, technology selections)
+- Key facts about user or their projects
+- Contact information or team details
+
+Categories:
+- preferences: User's personal preferences and working style
+- decisions: Important technical or project decisions
+- facts: Key information about user, projects, or context
+- contacts: People, teams, or organizations mentioned
+
+Long-term memories are searchable via memory_search.`,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        category: {
+                            type: 'string',
+                            enum: ['decisions', 'preferences', 'contacts', 'facts'],
+                            description: 'Memory category',
+                        },
+                        content: {
+                            type: 'string',
+                            description: 'Content to remember',
+                        },
+                    },
+                    required: ['category', 'content'],
+                },
+            },
+        ],
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case 'memory_search': {
+                const { query, time_range, project, limit } = args;
+                const results = await memoryManager.search(query, {
+                    timeRange: time_range
+                        ? [new Date(time_range[0]), new Date(time_range[1])]
+                        : undefined,
+                    project,
+                    limit,
+                });
+                if (results.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `No memories found matching "${query}".`,
+                            },
+                        ],
+                    };
+                }
+                const formatted = results
+                    .map((r, i) => {
+                    const date = r.timestamp.toISOString().split('T')[0];
+                    const projectInfo = r.project ? ` [${r.project}]` : '';
+                    return `### Result ${i + 1}${projectInfo} (${date}, relevance: ${(r.score * 100).toFixed(0)}%)\n\n${r.content}`;
+                })
+                    .join('\n\n---\n\n');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Found ${results.length} relevant memories:\n\n${formatted}`,
+                        },
+                    ],
+                };
+            }
+            case 'memory_record': {
+                const { user_message, ai_response, project, session_id } = args;
+                const conversation = await memoryManager.recordConversation(user_message, ai_response, {
+                    project,
+                    sessionId: session_id,
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Conversation recorded (ID: ${conversation.id})`,
+                        },
+                    ],
+                };
+            }
+            case 'memory_update_long_term': {
+                const { category, content } = args;
+                await memoryManager.updateLongTermMemory(category, content);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Stored in long-term memory [${category}]:\n\n${content}`,
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start server
+async function main() {
+    // Initialize memory system
+    await memoryManager.initialize();
+    console.error('Universal Memory MCP Server starting...');
+    console.error(`Storage path: ${memoryManager.getStoragePath()}`);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Universal Memory MCP Server running');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "universal-memory-mcp",
+  "version": "0.1.2",
+  "description": "MCP Server for persistent AI memory across sessions",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "universal-memory-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "start": "node dist/index.js",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "universal-memory-core": "^0.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.2.0"
+  },
+  "keywords": [
+    "mcp",
+    "memory",
+    "ai",
+    "claude",
+    "context",
+    "model-context-protocol"
+  ],
+  "author": "slicenferqin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/slicenferqin/universal-memory-mcp.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://github.com/slicenferqin/universal-memory-mcp#readme",
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}