Memory-Man 🧠

A persistent memory system for Claude Code that solves the context window problem by storing and retrieving project knowledge across sessions.

What is Memory-Man?

Memory-Man is an MCP (Model Context Protocol) server that acts as Claude's long-term memory. Instead of losing context when the conversation window fills up, Claude can now:

• Store important information about your projects

• Search through past conversations and decisions

• Retrieve relevant context when working on similar problems

• Track patterns across multiple projects

Related MCP server: Claude Memory MCP Server

Features

• 🗂️ Project-Aware Storage - Memories are organized by project

• 🔍 Smart Search - Find relevant memories by content, tags, or category

• 📊 Usage Analytics - Track which memories are most valuable

• 🏷️ Intelligent Tagging - Categorize memories for easy retrieval

• ⚡ Fast SQLite Backend - Efficient local storage

• 🔧 Easy Integration - Works with Claude Code out of the box

Quick Start

1. Install Dependencies:

   source venv/bin/activate
   pip install -r requirements-core.txt

2. Test the Server:

   python test_server.py

3. Configure Claude Code (see Integration Guide below)

Memory Categories

• architecture - System design decisions and patterns

• setup - Project configuration and environment

• bug_fix - Solutions to bugs and issues

• todo - Future work and planned features

• pattern - Reusable code patterns and best practices

• command - Useful commands and scripts

Integration with Claude Code

Method 1: Global MCP Configuration

Add to your global Claude Code config (~/.claude/mcp_servers.json):

{
  "mcpServers": {
    "memory-man": {
      "command": "python",
      "args": ["-m", "memory_man"],
      "env": {
        "PYTHONPATH": "/home/beano/DevProjects/python/memory-man/src"
      }
    }
  }
}

Method 2: Project-Specific Configuration

Add mcp_config.json to any project:

{
  "mcpServers": {
    "memory-man": {
      "command": "python",
      "args": ["-m", "memory_man"],
      "env": {
        "PYTHONPATH": "/home/beano/DevProjects/python/memory-man/src"
      }
    }
  }
}

Usage Examples

🚀 Smart Auto-Store (Recommended)

# Just provide the content - everything else is auto-detected!
memory_auto_store(
    content="We use JWT tokens with Redis for session management. Tokens expire after 24 hours."
)

# Auto-detects:
# - Project: current directory name
# - Category: architecture (based on content)  
# - Tags: ["jwt", "redis", "auth", "database"]
# - Framework: detected from project files

🔍 Smart Project Detection

# Analyze your current project
project_detect()

# Returns project info + suggestions:
# - Technology stack (Python, JavaScript, etc.)
# - Framework (Django, React, FastAPI, etc.) 
# - Recommended memory categories
# - Setup suggestions

🧠 Context-Aware Suggestions

# Get relevant memories for current work
memory_suggest_related(context="authentication setup")

# Returns:
# - Related memories from current project
# - Similar patterns from other projects
# - Smart suggestions based on context

📝 Manual Storage (When You Need Control)

# Store architecture decision manually
memory_store(
    content="We use Redis for session storage with 24-hour TTL",
    category="architecture", 
    project="my-web-app",
    tags=["redis", "sessions", "auth"],
    importance=8
)

# Search memories
memory_search(query="authentication", project="my-web-app")

# Get project overview
project_summary(project="my-web-app")

Available Tools

Core Tools

Smart Tools ✨

Advanced Tools 🔧

Configuration

Environment variables (optional):

# Database location
MEMORY_MAN_DATABASE_URL=sqlite+aiosqlite:///./data/memories.db

# Storage directory
MEMORY_MAN_DATA_DIR=./data

# Search settings
MEMORY_MAN_SEARCH_LIMIT=20
MEMORY_MAN_MAX_MEMORY_SIZE=10000

# Logging
MEMORY_MAN_LOG_LEVEL=INFO
MEMORY_MAN_DEBUG=false

Development

Running Tests

python test_server.py

Code Quality

# Format code
black src/

# Lint code
ruff check src/

# Type checking
mypy src/

Adding New Features

1. Models: Add to src/memory_man/models/

2. Tools: Add to src/memory_man/server.py

3. Config: Update src/memory_man/config.py

Troubleshooting

Server Won't Start

• Check Python path in MCP configuration

• Ensure virtual environment is properly set up

• Verify all dependencies are installed

Memory Search Issues

• Check if database exists in data/memories.db

• Verify project names match exactly

• Try broader search terms

Performance Issues

• Database will be created automatically on first run

• Consider adding indexes for large datasets

• Use importance levels to prioritize memories

Contributing

This is designed as a personal tool for your Claude Code workflow. Feel free to modify:

• Add new memory categories

• Implement semantic search

• Add memory expiration

• Create backup/sync features

License

MIT License - Feel free to use and modify as needed.