🧠 Hippocampus Memory MCP Server

Name: Hippocampus Memory MCP Server
Author: jameslovespancakes

Persistent, Semantic Memory for Large Language Models

Python 3.9+ MCP License: MIT

Features • Installation • Quick Start • Documentation • Architecture

📖 Overview

A Python-based Model Context Protocol (MCP) server that gives LLMs persistent, hippocampus-inspired memory across sessions. Store, retrieve, consolidate, and forget memories using semantic similarity search powered by vector embeddings.

Why Hippocampus? Just like the human brain's hippocampus consolidates short-term memories into long-term storage, this server intelligently manages LLM memory through biological patterns:

🔄 Consolidation - Merge similar memories to reduce redundancy
🧹 Forgetting - Remove outdated information based on age/importance
🔍 Semantic Retrieval - Find relevant memories through meaning, not keywords

✨ Features

Feature	Description
🗄️ Vector Storage	FAISS-powered semantic similarity search
🎯 MCP Compliant	Full MCP 1.2.0 spec compliance via FastMCP
🧬 Bio-Inspired	Hippocampus-style consolidation and forgetting
🔒 Security	Input validation, rate limiting, injection prevention
🔎 Semantic Search	Sentence transformer embeddings (CPU-optimized)
♾️ Unlimited Storage	No memory count limits, only per-item size limits
🆓 100% Free	Local embedding model - no API costs

🚀 Quick Start

5 Core MCP Tools

memory_read # 🔍 Retrieve memories by semantic similarity memory_write # ✍️ Store new memories with tags & metadata memory_consolidate # 🔄 Merge similar memories memory_forget # 🧹 Remove memories by age/importance/tags memory_stats # 📊 Get system statistics

📦 Installation

Quick Install (Recommended)

pip install hippocampus-memory-mcp

Prerequisites: Python 3.9+ • ~200MB disk space (for embedding model)

Claude Desktop Integration

Add to your Claude Desktop config (claude_desktop_config.json):

{ "mcpServers": { "memory": { "command": "python", "args": ["-m", "memory_mcp_server.server"] } } }

🎉 That's it! Claude will now have persistent memory across conversations.

Install from Source (Alternative)

# Clone the repository git clone https://github.com/jameslovespancakes/Memory-MCP.git cd Memory-MCP # Install dependencies pip install -r requirements.txt # Run the server python -m memory_mcp_server.server

📚 Documentation

Memory Operations via MCP

Once connected to Claude, use natural language:

"Remember that I prefer Python for backend development" → Claude calls memory_write() "What do you know about my programming preferences?" → Claude calls memory_read() "Consolidate similar memories to clean up storage" → Claude calls memory_consolidate()

Direct API Usage

✍️ Writing Memories

from memory_mcp_server.storage import MemoryStorage from memory_mcp_server.tools import MemoryTools storage = MemoryStorage(storage_path="my_memory") await storage._ensure_initialized() tools = MemoryTools(storage) # Store with tags and importance await tools.memory_write( text="User prefers dark mode UI", tags=["preference", "ui"], importance_score=3.0, metadata={"category": "settings"} )

🔍 Reading Memories

# Semantic search result = await tools.memory_read( query_text="What are my UI preferences?", top_k=5, min_similarity=0.3 ) # Filter by tags and date result = await tools.memory_read( query_text="Python learning", tags=["learning", "python"], date_range_start="2024-01-01" )

🔄 Consolidating Memories

# Merge similar memories (threshold: 0.85) result = await tools.memory_consolidate(similarity_threshold=0.85) print(f"Merged {result['consolidated_groups']} groups")

🧹 Forgetting Memories

# Remove by age await tools.memory_forget(max_age_days=30) # Remove by importance await tools.memory_forget(min_importance_score=2.0) # Remove by tags await tools.memory_forget(tags_to_forget=["temporary"])

Testing

Run the included test suite:

python test_memory.py

This tests all 5 operations with sample data.

🏗️ Architecture

┌─────────────────────────────────────────────────────┐ │ MCP Client (Claude Desktop, etc.) │ └───────────────────┬─────────────────────────────────┘ │ JSON-RPC over stdio ┌───────────────────▼─────────────────────────────────┐ │ FastMCP Server (server.py) │ │ ├─ memory_read │ │ ├─ memory_write │ │ ├─ memory_consolidate │ │ ├─ memory_forget │ │ └─ memory_stats │ └───────────────────┬─────────────────────────────────┘ │ ┌───────────────────▼─────────────────────────────────┐ │ Memory Tools (tools.py) │ │ ├─ Input validation & sanitization │ │ └─ Rate limiting (100 req/min) │ └───────────────────┬─────────────────────────────────┘ │ ┌───────────────────▼─────────────────────────────────┐ │ Storage Layer (storage.py) │ │ ├─ Sentence Transformers (all-MiniLM-L6-v2) │ │ ├─ FAISS Vector Index (cosine similarity) │ │ └─ JSON persistence (memories.json) │ └─────────────────────────────────────────────────────┘

🔄 Memory Lifecycle

Step	Process	Technology
📝 Write	Text → 384-dim vector embedding	Sentence Transformers (CPU)
💾 Store	Normalized vector → FAISS index	FAISS IndexFlatIP
🔍 Search	Query → embedding → top-k similar	Cosine similarity
🔄 Consolidate	Group similar (>0.85) → merge	Vector clustering
🧹 Forget	Filter by age/importance/tags → delete	Metadata filtering

🔒 Security

Protection	Implementation
🛡️ Injection Prevention	Regex filtering of script tags, eval(), path traversal
⏱️ Rate Limiting	100 requests per 60-second window per client
📏 Size Limits	50KB text, 5KB metadata, 20 tags per memory
✅ Input Validation	Pydantic models + custom sanitization
🔐 Safe Logging	stderr only (prevents JSON-RPC corruption)

⚙️ Configuration

Environment Variables

MEMORY_STORAGE_PATH="memory_data" # Storage directory EMBEDDING_MODEL="all-MiniLM-L6-v2" # Model name RATE_LIMIT_REQUESTS=100 # Max requests RATE_LIMIT_WINDOW=60 # Time window (seconds)

Storage Limits

✅ Unlimited total memories (no count limit)
⚠️ Per-memory limits: 50KB text, 5KB metadata, 20 tags

🐛 Troubleshooting

First run downloads all-MiniLM-L6-v2 (~90MB). Ensure internet connection and ~/.cache/ write permissions.

pip uninstall torch transformers sentence-transformers -y pip install torch==2.1.0 transformers==4.35.2 sentence-transformers==2.2.2

The model runs on CPU. Ensure 2GB+ free RAM. Reduce top_k in read operations if needed.

📝 License

MIT License - feel free to use in your projects!

🤝 Contributing

PRs welcome! Please:

Follow MCP security guidelines
Add tests for new features
Update documentation

🔗 Resources

Built with 🧠 for persistent LLM memory

Report Bug · Request Feature

Hippocampus Memory MCP Server