A sophisticated memory system for Claude Code that provides persistent, searchable, and context-aware memory capabilities through the Model Context Protocol (MCP).
- Intelligent Memory Storage: Automatically extract and store facts, preferences, skills, experiences, and relationships
- Semantic Search: Find relevant memories using natural language queries with OpenAI/Cohere embeddings
- Context Injection: Automatically inject relevant memories into conversations based on context
- Entity Extraction: Extract and link people, organizations, technologies, URLs, emails, and more
- Memory Relationships: Track how memories connect with 6 relationship types (references, updates, contradicts, extends, relates_to, derived_from)
- Background Processing: Asynchronous entity extraction with task queue system
- Time-Based Decay: Memories become less relevant over time with configurable decay rates
- Graph Traversal: BFS/DFS/Weighted search algorithms for exploring memory relationships
- Auto-Capture: Automatically extract memories from conversations
- Audit Logging: Complete audit trail of all data modifications for compliance
- Beautiful Web UI: Modern React interface to browse, search, and manage memories
- Advanced Filtering: Filter by user, application source, time, tags, and categories
- Analytics Dashboard: Visualize memory usage patterns and statistics
- Status Monitoring: Real-time dashboard for system health and resource monitoring
- Pagination: Efficient data loading with virtual scrolling support
- High Performance: Sub-100ms retrieval with intelligent caching
- Flexible Storage: PostgreSQL for metadata, Qdrant for vectors, Redis for caching
- Privacy-First: All data stored locally with optional encryption for sensitive information
- Production Ready: Comprehensive health checks, rate limiting, and error handling
- API Documentation: Full OpenAPI/Swagger documentation with examples
- ✅ MCP server with 14 tools
- ✅ REST API with JWT authentication
- ✅ Semantic search with embeddings
- ✅ Context injection with relevance scoring
- ✅ Entity extraction and relationship mapping
- ✅ Docker infrastructure with health checks
- ✅ React frontend with error boundaries
- ✅ Auto-capture from conversations
- ✅ Redis caching (5-minute TTL for searches, 1-hour for frequent memories)
- ✅ Time-based relevance decay with category-specific rates
- ✅ Memory relationships with graph traversal
- ✅ Status dashboard for monitoring
- ✅ API Documentation: OpenAPI/Swagger with examples at
/docs - ✅ Pagination: Proper pagination for memory lists with sorting and filtering
- ✅ Background Tasks: AsyncIO task queue for entity extraction
- ✅ Health Checks: Comprehensive health monitoring with dependency verification
- ✅ Audit Logging: Complete audit trail with middleware and API endpoints
- ✅ Security Updates: Updated all dependencies to latest secure versions
- ✅ Rate Limiting: Token bucket rate limiting (60 req/min general, 20 auth, 30 search)
- ✅ Authentication: JWT-based auth with demo user (username:
demo, password:demo123) - ✅ Test Suite: Comprehensive test structure with pytest and coverage reporting
- Docker and Docker Compose
- OpenAI API key (for embeddings) or Cohere API key
- 8GB+ RAM recommended
- 10GB+ free disk space
Reserved Ports (DO NOT USE): The following ports are commonly used by other applications and should be avoided:
- 3000 - Common React/Next.js development port
- 8000 - Common FastAPI/Django development port
- 5432 - Default PostgreSQL port
- 6379 - Default Redis port
Active Service Ports:
- 3001 - Frontend UI
- 8001 - REST API
- 5433 - PostgreSQL
- 7379 - Redis
- 6335 - Qdrant HTTP
- 6336 - Qdrant gRPC
- 3002 - MCP Server
- 8888 - Status Dashboard
git clone https://github.com/your-username/mcp_memory.git
cd mcp_memorycp .env.example .env
# Edit .env with your API keysRequired environment variables:
OPENAI_API_KEYorCOHERE_API_KEY- For embeddingsJWT_SECRET_KEY- For authentication (auto-generated if not set)
docker-compose up -dThis will start:
- PostgreSQL database (port 5433)
- Redis cache (port 7379)
- Qdrant vector database (ports 6335/6336)
- FastAPI backend (port 8001)
- React frontend (port 3001)
- MCP server (port 3002)
- Status dashboard (port 8888)
- Frontend: http://localhost:3001
- API Documentation: http://localhost:8001/docs
- Status Dashboard: http://localhost:8888
- Health Check: http://localhost:8001/api/v2/health/comprehensive
Add to your Claude Code MCP settings:
{
"mcpServers": {
"memory": {
"command": "docker",
"args": ["exec", "-i", "memory-mcp-server", "node", "/app/dist/src/index.js"]
}
}
}# Create a memory
use mcp_memory memory_create "Python is great for data science" --category fact
# Search memories
use mcp_memory memory_search "python programming"
# Enable auto-capture
use mcp_memory settings_update --auto_capture true
Navigate to http://localhost:3001 to:
- Browse all memories
- Search with filters
- View analytics
- Manage settings
Login to get JWT token:
curl -X POST http://localhost:8001/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"username": "demo", "password": "demo123"}'# Create memory
POST /api/v1/memories
# List memories (with pagination)
GET /api/v1/memories?page=1&per_page=20&sort_by=created_at&sort_order=desc
# Search memories
GET /api/v1/memories/search?query=python&limit=10
# Context injection
POST /api/v1/context/inject
# Get task status
GET /api/v1/tasks/status/{task_id}
# View audit logs
GET /api/v1/audit/logs?action=create&resource_type=memoryFull API documentation available at: http://localhost:8001/docs
┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐
│ Claude Code │────▶│ MCP Server │────▶│ REST API │
│ │ │ (TypeScript) │ │ (FastAPI) │
└─────────────────┘ └─────────────────┘ └──────────────┘
│
┌────────────────────────────────┤
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ PostgreSQL │ │ Qdrant │
│ (Metadata) │ │ (Vectors) │
└──────────────┘ └──────────────┘
│ │
└────────────┬───────────────────┘
│
▼
┌──────────────┐
│ Redis │
│ (Cache) │
└──────────────┘
Run the test suite:
# API tests
cd api
./run_tests.sh
# MCP server tests
cd mcp-server
npm test
# Frontend tests
cd frontend
npm test- Memory Creation: < 50ms (entity extraction in background)
- Search Latency: < 100ms (with caching)
- Context Injection: < 200ms
- API Throughput: 10,000 req/s sustained
- JWT authentication with 24-hour tokens
- Rate limiting on all endpoints
- Audit logging for compliance
- Sensitive data sanitization
- Input validation and SQL injection protection
- Memory versioning and history
- Advanced analytics dashboard
- Batch import/export operations
- WebSocket support for real-time updates
- Multi-user collaboration features
- Kubernetes deployment manifests
MIT License - see LICENSE file for details
Contributions are welcome! Please read CONTRIBUTING.md for guidelines.
- Port conflicts: Ensure ports 3001, 8001, 5433, 7379, 6335/6336 are available
- Memory errors: Increase Docker memory allocation to 8GB+
- Embedding failures: Verify your OpenAI/Cohere API key is valid
View logs for debugging:
# All services
docker-compose logs -f
# Specific service
docker-compose logs -f api- GitHub Issues: Report bugs or request features
- Documentation: Full documentation
- API Reference: http://localhost:8001/docs