updates

1 files changed, 381 insertions, 0 deletions

diff --git a/mcp-servers/memory-mcp-server/.claude/commands/setup.md b/mcp-servers/memory-mcp-server/.claude/commands/setup.md
new file mode 100644
index 0000000..5a9db1d
--- /dev/null
+++ b/mcp-servers/memory-mcp-server/.claude/commands/setup.md
@@ -0,0 +1,381 @@
+---
+description: Initialize Memory MCP Server project from scratch
+argument-hint: "[quick, full, or database]"
+allowed-tools: Write, MultiEdit, Bash, Task, TodoWrite
+---
+
+# Memory MCP Server Setup
+
+Initialize and configure the Memory MCP Server project based on $ARGUMENTS:
+
+## Quick Setup
+
+Initialize minimal working MCP server with memory capabilities:
+
+```bash
+# Initialize project
+npm init -y
+npm install @modelcontextprotocol/sdk zod dotenv
+npm install -D typescript @types/node tsx nodemon
+npm install @neondatabase/serverless drizzle-orm@^0.44.4
+npm install openai pgvector
+
+# Create TypeScript config
+npx tsc --init
+```
+
+## Full Setup
+
+Complete project initialization with all features:
+
+### 1. Project Structure
+
+```text
+memory-mcp-server/
+├── src/
+│   ├── index.ts              # MCP server entry point
+│   ├── server.ts              # Server initialization
+│   ├── tools/                # MCP tool implementations
+│   │   ├── createMemory.ts
+│   │   ├── searchMemories.ts
+│   │   ├── getMemory.ts
+│   │   ├── updateMemory.ts
+│   │   └── deleteMemory.ts
+│   ├── db/
+│   │   ├── client.ts          # Database connection
+│   │   ├── schema.ts          # Drizzle schema
+│   │   └── migrations/        # Database migrations
+│   ├── services/
+│   │   ├── embeddings.ts      # OpenAI embeddings
+│   │   ├── vectorSearch.ts    # pgvector operations
+│   │   └── memoryLifecycle.ts # Memory management
+│   ├── types/
+│   │   └── index.ts           # TypeScript types
+│   └── utils/
+│       ├── logger.ts          # Structured logging
+│       └── errors.ts          # Error handling
+├── tests/
+│   ├── unit/
+│   ├── integration/
+│   └── fixtures/
+├── .env.example
+├── .mcp.json                  # MCP manifest
+├── tsconfig.json
+├── package.json
+├── drizzle.config.ts
+└── README.md
+```
+
+### 2. Package Dependencies
+
+```json
+{
+  "name": "memory-mcp-server",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint . --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:studio": "drizzle-kit studio"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@neondatabase/serverless": "^1.0.1",
+    "drizzle-orm": "^0.44.4",
+    "zod": "^4.0.17",
+    "openai": "^4.0.0",
+    "pgvector": "^0.2.0",
+    "dotenv": "^16.0.0",
+    "winston": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "tsx": "^4.0.0",
+    "nodemon": "^3.0.0",
+    "jest": "^29.0.0",
+    "@types/jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "eslint": "^8.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "drizzle-kit": "^0.32.0"
+  }
+}
+```
+
+### 3. TypeScript Configuration
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+```
+
+### 4. Environment Variables
+
+```bash
+# .env
+DATABASE_URL="postgresql://user:pass@host/dbname?sslmode=require"
+OPENAI_API_KEY="sk-..."
+MCP_SERVER_PORT=3000
+LOG_LEVEL=info
+NODE_ENV=development
+
+# Vector search settings
+VECTOR_SEARCH_LIMIT=10
+SIMILARITY_THRESHOLD=0.7
+
+# Memory lifecycle
+MEMORY_EXPIRATION_DAYS=90
+MAX_MEMORIES_PER_USER=10000
+IMPORTANCE_DECAY_RATE=0.1
+```
+
+### 5. MCP Manifest
+
+```json
+{
+  "name": "memory-mcp-server",
+  "version": "1.0.0",
+  "description": "Persistent memory management for AI assistants",
+  "author": "Your Name",
+  "license": "MIT",
+  "server": {
+    "command": "node",
+    "args": ["dist/index.js"],
+    "transport": "stdio"
+  },
+  "tools": {
+    "create_memory": {
+      "description": "Create a new memory with vector embedding",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "content": { "type": "string" },
+          "type": { "type": "string" },
+          "importance": { "type": "number" },
+          "expires_at": { "type": "string" }
+        },
+        "required": ["content", "type"]
+      }
+    },
+    "search_memories": {
+      "description": "Search memories using semantic similarity",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": { "type": "string" },
+          "limit": { "type": "number" },
+          "threshold": { "type": "number" }
+        },
+        "required": ["query"]
+      }
+    }
+  }
+}
+```
+
+## Database Setup
+
+Initialize Neon PostgreSQL with pgvector:
+
+### 1. Create Database
+
+```sql
+-- Enable pgvector extension
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- Create database schema
+CREATE SCHEMA IF NOT EXISTS memory_mcp;
+```
+
+### 2. Drizzle Schema
+
+```typescript
+// src/db/schema.ts
+import { pgTable, uuid, text, timestamp, boolean, real, vector, index, jsonb } from 'drizzle-orm/pg-core';
+
+export const users = pgTable('users', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  external_id: text('external_id').notNull().unique(),
+  created_at: timestamp('created_at').defaultNow().notNull(),
+  metadata: jsonb('metadata')
+});
+
+export const companions = pgTable('companions', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  name: text('name').notNull(),
+  user_id: uuid('user_id').references(() => users.id),
+  created_at: timestamp('created_at').defaultNow().notNull(),
+  is_active: boolean('is_active').default(true)
+});
+
+export const memories = pgTable('memories', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  companion_id: uuid('companion_id').references(() => companions.id),
+  user_id: uuid('user_id').references(() => users.id),
+  content: text('content').notNull(),
+  type: text('type').notNull(),
+  embedding: vector('embedding', { dimensions: 1536 }),
+  importance: real('importance').default(0.5),
+  access_count: integer('access_count').default(0),
+  last_accessed: timestamp('last_accessed'),
+  expires_at: timestamp('expires_at'),
+  is_archived: boolean('is_archived').default(false),
+  created_at: timestamp('created_at').defaultNow().notNull(),
+  updated_at: timestamp('updated_at').defaultNow().notNull()
+}, (table) => ({
+  embeddingIdx: index('memories_embedding_idx')
+    .using('ivfflat', table.embedding.op('vector_cosine_ops'))
+    .with({ lists: 100 }),
+  userIdx: index('memories_user_idx').on(table.user_id),
+  companionIdx: index('memories_companion_idx').on(table.companion_id),
+  typeIdx: index('memories_type_idx').on(table.type)
+}));
+```
+
+### 3. Migration Commands
+
+```bash
+# Generate migration
+npx drizzle-kit generate
+
+# Run migrations
+npx drizzle-kit migrate
+
+# Open Drizzle Studio
+npx drizzle-kit studio
+```
+
+## Initial Server Implementation
+
+```typescript
+// src/index.ts
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { createMemoryTool } from './tools/createMemory.js';
+import { searchMemoriesTool } from './tools/searchMemories.js';
+
+const server = new Server({
+  name: 'memory-mcp-server',
+  version: '1.0.0'
+}, {
+  capabilities: {
+    tools: {}
+  }
+});
+
+// Register tools
+server.setRequestHandler('tools/list', async () => ({
+  tools: [
+    createMemoryTool.definition,
+    searchMemoriesTool.definition
+  ]
+}));
+
+server.setRequestHandler('tools/call', async (request) => {
+  const { name, arguments: args } = request.params;
+  
+  switch (name) {
+    case 'create_memory':
+      return await createMemoryTool.handler(args);
+    case 'search_memories':
+      return await searchMemoriesTool.handler(args);
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+});
+
+// Start server
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.log('Memory MCP Server started');
+```
+
+## Testing Setup
+
+```bash
+# Install test dependencies
+npm install -D jest @types/jest ts-jest
+
+# Create Jest config
+npx ts-jest config:init
+
+# Run tests
+npm test
+```
+
+## Development Workflow
+
+```bash
+# Start development server
+npm run dev
+
+# In another terminal, test MCP connection
+npx @modelcontextprotocol/cli connect stdio "npm run start"
+
+# Test tool execution
+npx @modelcontextprotocol/cli call create_memory '{"content": "Test memory"}'
+```
+
+## Production Deployment
+
+```dockerfile
+# Dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY dist ./dist
+CMD ["node", "dist/index.js"]
+```
+
+## Monitoring & Observability
+
+```typescript
+// src/utils/logger.ts
+import winston from 'winston';
+
+export const logger = winston.createLogger({
+  level: process.env.LOG_LEVEL || 'info',
+  format: winston.format.json(),
+  transports: [
+    new winston.transports.Console(),
+    new winston.transports.File({ filename: 'error.log', level: 'error' }),
+    new winston.transports.File({ filename: 'combined.log' })
+  ]
+});
+```
+
+This setup provides a complete foundation for the Memory MCP Server with all necessary configurations and best practices.