<div align="center">
# 🧠 Hippocampus Memory MCP Server
### *Persistent, Semantic Memory for Large Language Models*
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
[](https://opensource.org/licenses/MIT)
[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Architecture](#-architecture)
---
</div>
## 📖 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
```python
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)
```bash
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`):
```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)
```bash
# 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
```python
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
```python
# 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
```python
# Merge similar memories (threshold: 0.85)
result = await tools.memory_consolidate(similarity_threshold=0.85)
print(f"Merged {result['consolidated_groups']} groups")
```
#### 🧹 Forgetting Memories
```python
# 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:
```bash
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
```bash
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
<details>
<summary><b>Model won't download</b></summary>
First run downloads `all-MiniLM-L6-v2` (~90MB). Ensure internet connection and `~/.cache/` write permissions.
</details>
<details>
<summary><b>PyTorch compatibility errors</b></summary>
```bash
pip uninstall torch transformers sentence-transformers -y
pip install torch==2.1.0 transformers==4.35.2 sentence-transformers==2.2.2
```
</details>
<details>
<summary><b>Memory errors on large operations</b></summary>
The model runs on CPU. Ensure 2GB+ free RAM. Reduce `top_k` in read operations if needed.
</details>
## 📝 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
- [Model Context Protocol Docs](https://modelcontextprotocol.io/)
- [FastMCP Framework](https://github.com/jlowin/fastmcp)
- [FAISS Documentation](https://github.com/facebookresearch/faiss)
- [Sentence Transformers](https://www.sbert.net/)
---
<div align="center">
**Built with 🧠 for persistent LLM memory**
[Report Bug](https://github.com/jameslovespancakes/Memory-MCP/issues) · [Request Feature](https://github.com/jameslovespancakes/Memory-MCP/issues)
</div>
