Content
[](https://github.com/mako10k/mcp-assoc-memory/actions)
[](./htmlcov/index.html)
[](./LICENSE)
[](https://pypi.org/project/mcp-assoc-memory/)
# MCP Associative Memory Server
🧠 **Production-Ready Intelligent Memory System** - Store, search, and discover knowledge connections using the Model Context Protocol (MCP) with **74/74 tests passing** and **complete CI/CD pipeline**.
## 🏆 Production Status (July 2025)
**✅ ENTERPRISE-READY:**
- **74/74 tests passing** (100% success rate)
- **Complete CI/CD pipeline** with security and quality gates
- **10 MCP tools** for comprehensive memory management
- **Sub-second performance** with optimized vector search
- **Docker containerized** for production deployment
## 🌟 Overview
Transform your development workflow with an AI-powered memory system that:
- **Stores insights** from your daily work and learning
- **Finds related knowledge** when you need it most
- **Discovers unexpected connections** between ideas
- **Organizes knowledge** in intuitive hierarchical scopes
- **Syncs across environments** for seamless workflow integration
Built with **FastMCP 2.0** for modern LLM integration, optimized for **GitHub Copilot** workflows.
## ✨ Key Features
### 🧠 **Intelligent Memory Operations**
- **Semantic Search**: Find relevant memories using natural language queries
- **Association Discovery**: Automatically discover connections between concepts
- **Complete CRUD**: Create, Read, Update, Delete with full lifecycle management
- **Smart Organization**: Hierarchical scopes with auto-categorization
### 🔍 **Advanced Discovery**
- **Top-K Search**: Optimized threshold (0.1) with LLM-guided relevance judgment
- **Cross-Scope Associations**: Find connections across different knowledge scopes
- **Similarity Scoring**: Transparent relevance metrics for intelligent filtering
- **Creative Connections**: Discover unexpected relationships for innovation
### 🗂️ **Powerful Organization**
- **Hierarchical Scopes**: `work/projects/name`, `learning/technology`, `personal/ideas`
- **Flexible Categorization**: Tags, metadata, and automatic scope suggestions
- **Session Management**: Temporary workspaces for project isolation
- **Memory Movement**: Reorganize knowledge as understanding evolves
### 🔄 **Cross-Environment Sync**
- **Export/Import**: Backup and restore memories across development environments
- **Multiple Formats**: JSON, YAML with compression support
- **Merge Strategies**: Handle duplicates intelligently during sync
- **Git Workflow**: Integrate memory backup into version control processes
### 🛠️ **Developer Experience**
- **GitHub Copilot Integration**: Natural language memory operations
- **VS Code Tasks**: One-click server management and maintenance
- **Real-time Association**: Automatic relationship discovery during storage
- **Performance Optimized**: Sub-second search across thousands of memories
- **Response Level Control**: Minimal, standard, or full detail responses for optimal token usage
### ⚡ **Smart Response Levels**
Control response detail and token usage with three intelligent levels:
- **`minimal`**: Essential information only (~50 tokens) - Perfect for status checks and basic operations
- **`standard`**: Balanced detail for workflow continuity (default) - Optimal for most use cases
- **`full`**: Comprehensive data including metadata, associations, and analysis - Ideal for debugging and detailed exploration
**Example Usage:**
```python
# Quick status check
memory_store(content="meeting notes", response_level="minimal")
# Returns: {"success": true, "message": "Memory stored", "memory_id": "..."}
# Full debugging info
memory_search(query="project ideas", response_level="full")
# Returns: Complete results with similarity scores, metadata, associations
```
## 🎯 Complete MCP Tool Suite
### 🚀 **Modern API (10 Clean Tools)**
### Core Operations (Primary API)
- **`memory_store`** - Store new memories with auto-association
- **`memory_search`** - Unified search with standard and diversified modes
- **`memory_manage`** - Get, update, and delete memory operations
- **`memory_sync`** - Import and export memories for backup/sync
### Discovery and Analysis
- **`memory_discover_associations`** - Find semantically related memories
- **`memory_list_all`** - Browse complete memory collection with pagination
### Organization Management
- **`scope_list`** - Browse hierarchical memory organization
- **`scope_suggest`** - AI-powered scope recommendations
- **`memory_move`** - Reorganize memories into better categories
### Session Management
- **`session_manage`** - Create, list, and cleanup temporary working sessions
### 🎯 **Clean, Modern API**
All tools use intuitive, natural names with powerful unified interfaces for better developer experience.
## 📚 Comprehensive Documentation
### 🚀 **[Quick Start Guide](docs/user-guide/QUICK_START.md)**
Get up and running in 5 minutes with essential commands and patterns.
### 💡 **[Best Practices](docs/user-guide/BEST_PRACTICES.md)**
Comprehensive guide to optimizing your associative memory workflow.
### 🔧 **[API Reference](docs/api-reference/README.md)**
Complete technical documentation for all MCP tools and parameters.
### 🏢 **[Real-World Examples](docs/examples/README.md)**
Practical usage patterns for developers, teams, and organizations.
### 🆘 **[Troubleshooting Guide](docs/troubleshooting/README.md)**
Solutions for common issues and system maintenance procedures.
### 📊 **[Sample Data](examples/sample-data/README.md)**
Ready-to-import memory dataset with 28 curated memories demonstrating system capabilities.
## 🚀 **[Complete Documentation →](docs/README.md)**
## Architecture
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ LLM Client │────│ FastMCP Server │────│ Memory Store │
│ │ │ │ │ │
│ - Claude │ │ - @app.tool() │ │ - ChromaDB │
│ - ChatGPT │ │ - @app.resource()│ │ - SQLite │
│ - Custom LLM │ │ - @app.prompt() │ │ - NetworkX │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
## Technology Stack
- **Language**: Python 3.11+
- **MCP Framework**: FastMCP 2.0
- **Vector Database**: ChromaDB
- **Embedding Model**: OpenAI Embeddings / Sentence Transformers
- **Graph Database**: NetworkX (in-memory)
- **Storage**: SQLite (metadata)
## Installation & Usage
For detailed setup instructions, see `docs/installation.md`.
## Server Startup
### Direct STDIO Mode (Recommended)
**Standard MCP startup method:**
```bash
python -m mcp_assoc_memory.server --config config.json
```
The server operates in **STDIO mode** for direct MCP client integration. This is the recommended approach for VS Code Copilot and other MCP clients.
### Configuration
- Copy `config.json.template` to `config.json`
- Set your OpenAI API key for embeddings
- Configure transport options (STDIO enabled by default)
### Database Path Configuration
**🆕 Workspace Pollution Avoidance (NEW)**: The server now stores database files in OS-appropriate user directories by default, keeping your workspace clean.
**Default Locations:**
- **Linux**: `~/.local/share/mcp-assoc-memory/`
- **macOS**: `~/Library/Application Support/mcp-assoc-memory/`
- **Windows**: `%APPDATA%/mcp-assoc-memory/`
**Override with Environment Variables:**
```bash
export MCP_DATABASE_PATH="/custom/path/memory.db"
export MCP_DATA_DIR="/custom/data/directory"
```
See [Database Path Configuration](docs/database-path-configuration.md) for detailed options.
### Environment Variables
- `OPENAI_API_KEY`: Required for OpenAI embeddings
- `MCP_LOG_LEVEL`: Set logging level (DEBUG, INFO, WARNING, ERROR)
- `MCP_DATABASE_PATH`: Override database file location
- `MCP_DATA_DIR`: Override data directory location
## 🛠️ Installation (PyPI, pipx, GitHub)
### Recommended: PyPI
```bash
pip install mcp-assoc-memory
```
### pipx (isolated global install)
```bash
pipx install mcp-assoc-memory
```
### GitHub (latest/dev version)
```bash
pip install git+https://github.com/mako10k/mcp-assoc-memory.git
# or
pipx install git+https://github.com/mako10k/mcp-assoc-memory.git
```
### Start the server (after install)
```bash
python -m mcp_assoc_memory.server --config config.json
```
- Configure via `.vscode/mcp.json` for VS Code Copilot integration
- MCPクライアントや自動検出ツール（Claude Desktop Extensions, FastMCP, Cursor等）からも自動認識されます。
- Dockerイメージも近日公開予定。
---
## Developer Information
### Development Guidelines
🤖 **AI Development Agent**: [development/workflow/AGENT.md](development/workflow/AGENT.md)
📋 **GitHub Copilot Rules**: [.github/copilot-instructions.md](.github/copilot-instructions.md)
🔄 **Development Workflow**: [development/workflow/DEVELOPER_GUIDELINES.md](development/workflow/DEVELOPER_GUIDELINES.md)
---
## ✅ Quality Status
All code passes **mypy (type check)**, **flake8 (lint)**, and **pytest (unit/integration tests)** as of July 2025.
CI/CD pipeline enforces these checks for every commit.
### Technical Reference
- **[System Architecture](development/architecture/)** - Architecture and structure documentation
- **[Technical Specifications](development/specifications/)** - API specs and feature details
- **[Security & Configuration](development/security/)** - Authentication and transport configuration
- **[Knowledge Base](development/knowledge/)** - Curated development knowledge
- **[Complete Development Docs →](development/README.md)**
### Contributing
1. Check [development guidelines](development/workflow/DEVELOPER_GUIDELINES.md) before contributing
2. Review [architecture documentation](development/architecture/) for system understanding
3. Follow [GitHub Copilot instructions](.github/copilot-instructions.md) for AI-assisted development
4. Update relevant documentation when making changes
## 🚀 Quick Start
### 1. Clone the repository
```bash
git clone https://github.com/mako10k/mcp-assoc-memory.git
cd mcp-assoc-memory
```
### 2. Set up your environment
```bash
python -m venv venv
source venv/bin/activate # Linux/Mac
# or
venv\Scripts\activate # Windows
```
### 3. Install dependencies
```bash
pip install -r requirements.txt
pip install -r requirements-dev.txt
```
### 4. Run tests and linting
```bash
python scripts/smart_lint.py
pytest tests/ -v
```
### 5. Start the MCP server
```bash
python -m mcp_assoc_memory.server --config config.json
```
For Docker users:
```bash
docker-compose up --build
```
---
## License
MIT License
