cldmemory

MCP Memory Server

A human-like memory system using Qdrant vector database and OpenAI embeddings, accessible through the Model Context Protocol (MCP).

Features

• Human-like Memory Types:

  • Episodic (personal experiences)
  • Semantic (facts and knowledge)
  • Procedural (how to do things)
  • Emotional (emotional memories)
  • Sensory (sensory impressions)
  • Working (short-term memory)

• Memory Characteristics:

  • Importance scoring (0-1)
  • Emotional valence (-1 to 1)
  • Associations between memories
  • Context (location, people, mood, activity)
  • Decay factor and access tracking
  • Automatic project tracking (hostname:folder)
  • Custom metadata via environment variables

Setup

1. Install dependencies:

   npm install
   

2. Configure environment:

   cp .env.example .env
   # Edit .env with your settings
   

   New environment variables:

   • MEMORY_METADATA - Optional metadata to include with all memories
     • Format: "key:value,key2:value2" or just "value" (stored as user:value)
     • Examples: "server:prod,user:john" or "davidstrejc"

3. Start Qdrant (if using local):

   docker run -p 6333:6333 -p 6334:6334 \
     --name qdrant-memory \
     -v $(pwd)/qdrant_storage:/qdrant/storage:z \
     qdrant/qdrant
   

   Note: Qdrant URL supports both HTTP and HTTPS protocols (e.g., https://your-qdrant-instance.com:6333)

4. Build the project:

   npm run build
   

Testing with Claude Code

Use the MCP configuration file with Claude Code CLI:

# Basic usage
claude -p "Store a memory about today's meeting" --mcp-config claude-code-mcp.json

# Skip permissions for automation
claude -p "Search my memories" --mcp-config claude-code-mcp.json --dangerously-skip-permissions

# List available tools
claude -p "List available memory tools" --mcp-config claude-code-mcp.json

Available MCP tools (prefixed with mcp__memory__):

• store_memory - Store a new memory
• search_memories - Search for memories using natural language (returns full details)
• quick_search_memories - Fast search returning only summaries for browsing
• get_memory - Retrieve a specific memory by ID
• update_memory - Update an existing memory
• delete_memory - Delete a memory
• analyze_memories - Analyze memory patterns

Example Usage

IMPORTANT: All MCP tools expect JSON objects as parameters, NOT plain strings.

// ✅ CORRECT - Store a memory with JSON object
store_memory({
  "content": "Had lunch with Sarah at the Italian restaurant",
  "type": "episodic",
  "context": {
    "location": "Downtown Italian restaurant",
    "people": ["Sarah"],
    "mood": "happy"
  },
  "importance": 0.8
})

// ❌ WRONG - Do not pass plain strings
store_memory("Had lunch with Sarah")  // This will fail!

// ✅ CORRECT - Search with JSON object
search_memories({
  "query": "restaurant experiences",
  "limit": 5,
  "includeAssociations": true
})

// ❌ WRONG - Do not pass plain strings
search_memories("restaurant experiences")  // This will fail!

// ✅ CORRECT - Quick search for browsing (returns only summaries)
quick_search_memories({
  "query": "programming tips",
  "limit": 50  // Can handle more results since only summaries
})

// Then get full details of a specific memory
get_memory({
  "id": "abc-123-def-456"  // Use ID from quick search results
})

New Features

Automatic Project Tracking: All memories now include a project field that captures the hostname and current working directory (e.g., "myserver:/home/user/project").

Environment Metadata: Set the MEMORY_METADATA environment variable to automatically include custom metadata in all memories:

export MEMORY_METADATA="server:production,team:engineering,region:us-west"

This metadata is automatically:

• Added to all new memories
• Included in memory embeddings for better search relevance
• Used in search queries to improve context matching

Memory Analytics Tool

A comprehensive CLI tool is included for analyzing memories:

# Quick start
./memory-analytics count    # Count memories by agent
./memory-analytics tags     # Analyze tag usage
./memory-analytics compare  # Compare agents
./memory-analytics all      # Run all analytics

See docs/MEMORY_ANALYTICS.md for detailed documentation.

Development

• npm run dev - Run in development mode
• npm run build - Build TypeScript
• npm run test - Run tests
• npm run lint - Run linter
• npm run typecheck - Type check