# 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**:
   ```bash
   npm install
   ```

2. **Configure environment**:
   ```bash
   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):
   ```bash
   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**:
   ```bash
   npm run build
   ```

## Testing with Claude Code

Use the MCP configuration file with Claude Code CLI:

```bash
# 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.

```json
// ✅ 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:
```bash
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:

```bash
# 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](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