mcp-assoc-memory

mako10k/mcp-assoc-memory

3.2

If you are the rightful owner of mcp-assoc-memory and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The MCP Associative Memory Server is an intelligent system designed to enhance the capabilities of large language models (LLMs) by providing a robust memory storage and retrieval mechanism.

Tools
5
Resources
0
Prompts
0

CI PyPI

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:

# 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

🚀

Get up and running in 5 minutes with essential commands and patterns.

💡

Comprehensive guide to optimizing your associative memory workflow.

🔧

Complete technical documentation for all MCP tools and parameters.

🏢

Practical usage patterns for developers, teams, and organizations.

🆘

Solutions for common issues and system maintenance procedures.

📊

Ready-to-import memory dataset with 28 curated memories demonstrating system capabilities.

🚀

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:

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:

export MCP_DATABASE_PATH="/custom/path/memory.db"
export MCP_DATA_DIR="/custom/data/directory"

See 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

pip install mcp-assoc-memory

pipx (isolated global install)

pipx install mcp-assoc-memory

GitHub (latest/dev version)

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)

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:
📋 GitHub Copilot Rules:
🔄 Development Workflow:

✅ 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

  • - Architecture and structure documentation
  • - API specs and feature details
  • - Authentication and transport configuration
  • - Curated development knowledge

Contributing

  1. Check before contributing
  2. Review for system understanding
  3. Follow for AI-assisted development
  4. Update relevant documentation when making changes

🚀 Quick Start

1. Clone the repository

git clone https://github.com/mako10k/mcp-assoc-memory.git
cd mcp-assoc-memory

2. Set up your environment

python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate  # Windows

3. Install dependencies

pip install -r requirements.txt
pip install -r requirements-dev.txt

4. Run tests and linting

python scripts/smart_lint.py
pytest tests/ -v

5. Start the MCP server

python -m mcp_assoc_memory.server --config config.json

For Docker users:

docker-compose up --build

License

MIT License