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

pip install hippocampus-memory-mcp

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

# 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

"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()

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"}
)

# 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"
)

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

# 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"])

python test_memory.py

┌─────────────────────────────────────────────────────┐
│  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_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)

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