🧠 Memory Bank MCP

A Model Context Protocol (MCP) server for Claude Code that enables persistent memory, structured thinking, team collaboration, and project-based knowledge management — with full export, revision, and analysis capabilities. Now featuring comprehensive coding integration to prevent package reinvention and enforce existing API usage.

---

🚀 Features

🧠 Core Memory Management

• Session-Based Thinking: Start with a problem and track related insights
• Persistent Storage: Store and retrieve memories across sessions
• Collections: Group related memories with clear purposes
• Revision & Dependencies: Refine ideas, track changes and links

💻 Coding Integration (NEW)

• Package Discovery: Auto-scan installed packages and extract API signatures
• Reinvention Prevention: Validate code against existing libraries before implementation
• Code Pattern Storage: Store and retrieve proven code templates and examples
• Coding Sessions: Specialized session types for development workflows
• Validation Gates: Catch potential issues and suggest existing solutions

📦 Project & Export System

• Export to Markdown/JSON: Full or filtered memory exports
• Project Structure Generation: Standardized folders for teams
• Project Indexing: Maintain status updates and documentation
• Context Loading: Load ongoing work for seamless continuation

📊 Search & Analytics

• Tag-Based Search: Find insights by topics or keywords
• Importance Scores: Prioritize content using confidence metrics
• Session Analysis: Detect contradictions, gaps, and themes

---

⚡ Quick Start

git clone https://github.com/spideynolove/memory-bank-mcp
cd memory-bank-mcp
uv sync
uv run main.py

Requires Python 3.10+ and uv

---

🛠 Installation Options

• Direct run: uv run main.py
• Global install: uv tool install .
• Development mode: uv pip install -e .

---

🧪 Test

uv run -c "import main; print('Installation successful')"

---

🔧 Session Workflow (API Example)

Basic Memory Session

create_memory_session(
    problem="Implement user auth",
    success_criteria="Secure + scalable",
    constraints="Use existing DB"
)

store_memory(
    content="Use JWT with refresh",
    tags="auth,jwt",
    importance=0.9
)

analyze_memories()
export_session_to_file("auth_session.md")

Coding Session with Validation

# Start a coding-specific session
create_memory_session(
    problem="Build HTTP client for API integration",
    success_criteria="Efficient, maintainable, using existing libraries",
    constraints="Must handle auth, retries, rate limiting",
    session_type="coding_session"
)

# Discover what packages are already available
discover_packages()

# Check if functionality already exists before coding
prevent_reinvention_check("HTTP client for REST APIs")
# Returns: Found existing APIs: requests.get(), urllib3.request(), etc.

# Validate code before implementation
validate_package_usage("""
def make_request(url):
    import urllib.request
    return urllib.request.urlopen(url).read()
""")
# Returns: Warning - Consider using requests library

# Store proven patterns for reuse
store_codebase_pattern(
    pattern_type="api_usage",
    code_snippet="import requests\nresponse = requests.get(url, headers=headers)",
    description="Standard HTTP GET with auth headers",
    language="python"
)

⚠️ Must start with create_memory_session() before storing anything.

---

🧩 Session Tools

Core Memory Tools

Tool	Description
create_memory_session()	Start a new thinking session (now supports session_type)
store_memory()	Save insights with tags and confidence (now supports code_snippet)
revise_memory()	Update previous memories
create_collection()	Group insights
merge_collection()	Combine collections
analyze_memories()	Run quality checks
export_session_to_file()	Export full sessions
export_memories_to_file()	Export filtered memories
load_project_context()	Resume prior sessions
update_project_index()	Document team progress

💻 Coding Integration Tools (NEW)

Tool	Description
discover_packages()	Auto-scan installed packages and extract APIs
validate_package_usage()	Validate code against existing packages
explore_existing_apis()	Find existing APIs for needed functionality
prevent_reinvention_check()	Comprehensive reinvention prevention warning
store_codebase_pattern()	Store code patterns with metadata
load_codebase_context()	Load project structure into memory

Enhanced Tools

• create_memory_session(): Now accepts session_type parameter for coding_session, debugging_session, architecture_session
• store_memory(): Now accepts code_snippet, language, pattern_type parameters for code integration

---

💻 Coding Session Types & Workflows

Session Types

• coding_session: General development work with package discovery and validation
• debugging_session: Problem-solving focused with enhanced error pattern storage
• architecture_session: System design with emphasis on integration patterns

Validation Workflow

# 1. Start coding session
create_memory_session("Build user service", "Efficient API", session_type="coding_session")

# 2. Discover available packages
discover_packages()
# Scans environment and stores: requests, fastapi, pydantic, etc.

# 3. Check for existing solutions before coding
prevent_reinvention_check("HTTP server framework")
# ⚠️ POTENTIAL REINVENTION DETECTED ⚠️
# Found existing APIs: fastapi.FastAPI(), flask.Flask(), etc.

# 4. Validate specific code patterns
validate_package_usage("""
class CustomHTTPServer:
    def __init__(self, port):
        self.port = port
    def start(self):
        # custom server implementation
        pass
""")
# Warning: Consider using FastAPI or Flask instead

# 5. Store proven patterns for team reuse
store_codebase_pattern(
    pattern_type="api_endpoint",
    code_snippet="""
@app.get("/users/{user_id}")
async def get_user(user_id: int):
    return {"user_id": user_id}
""",
    description="Standard FastAPI endpoint pattern",
    language="python",
    tags="api,fastapi,endpoint"
)

🔍 MCP Resources for Coding

Access coding data through these resources:

Resource	Description
codebase://packages	View discovered packages in session
codebase://patterns	View stored code patterns
codebase://validation-checks	View validation check history

Example Usage

# View discovered packages
# Resource: codebase://packages
{
  "requests": [
    {"signature": "requests.get(url, **kwargs)", "usage_example": "requests.get('https://api.example.com')"},
    {"signature": "requests.post(url, data=None, json=None, **kwargs)", "usage_example": "requests.post(url, json={'key': 'value'})"}
  ],
  "fastapi": [
    {"signature": "fastapi.FastAPI()", "usage_example": "app = FastAPI()"}
  ]
}

# View code patterns  
# Resource: codebase://patterns
[
  {
    "id": "abc123",
    "type": "api_endpoint", 
    "description": "Standard FastAPI endpoint",
    "language": "python",
    "tags": ["api", "fastapi"],
    "code_snippet": "@app.get('/users/{user_id}')\nasync def get_user(user_id: int)..."
  }
]

---

🏗 Project Structure

memory-bank/
├── thinking_sessions/
├── domain_knowledge/
├── implementation_log/
├── exports/
├── project_knowledge_index.md
└── README.md

Initialize with:

create_project_structure("My Project")

---

🧑‍🤝‍🧑 Collaboration Patterns

Developer A - Research Phase

create_memory_session("Research auth libs", "Evaluate options", session_type="coding_session")
discover_packages()  # Find available auth libraries
prevent_reinvention_check("JWT authentication")
store_memory("Use FastAPI JWT plugin", code_snippet="from fastapi_jwt import JWT", language="python")
export_session_to_file("thinking_sessions/research_alice.md")

Developer B - Implementation Phase

load_project_context("memory-bank")
create_memory_session("Design auth flow", "Complete plan", session_type="architecture_session")

# Load existing patterns from team
# Resource: codebase://patterns shows Alice's JWT pattern

validate_package_usage("""
def custom_jwt_encode(payload):
    import base64
    return base64.b64encode(json.dumps(payload).encode())
""")
# Warning: Consider using existing JWT libraries

export_memories_to_file("domain_knowledge/auth_decisions.json")

Developer C - Debugging Phase

create_memory_session("Fix auth token expiry", "Resolve production issue", session_type="debugging_session")
explore_existing_apis("JWT token refresh")
store_codebase_pattern("debugging", "Token expiry logs", "Check exp claim in JWT payload")

---

💥 Error Recovery

try:
    analyze_memories()
except:
    create_memory_session("Recovery", "Rebuild context")

Safe export:

def safe_export(path):
    try:
        export_session_to_file(path)
    except:
        export_session_to_file(path.replace(".md", ".json"))

---

🧑‍💼 Role-Based Usage

Role	Actions
Lead	create_project_structure(), update_project_index(), discover_packages()
Developer	create_memory_session(), validate_package_usage(), store_codebase_pattern()
New Teammate	load_project_context(), explore_existing_apis(), prevent_reinvention_check()

🗄️ Database Schema Extensions

The coding integration adds 4 new tables to the SQLite database:

New Tables

-- Package APIs discovered in sessions
CREATE TABLE package_apis (
    id TEXT PRIMARY KEY,
    session_id TEXT NOT NULL,
    package_name TEXT NOT NULL,        -- e.g., "requests"
    api_signature TEXT NOT NULL,       -- e.g., "requests.get(url, **kwargs)"
    usage_example TEXT,                -- e.g., "requests.get('https://api.com')"
    documentation TEXT,                -- API documentation excerpt
    discovered_at TIMESTAMP,
    usage_count INTEGER DEFAULT 0
);

-- Code patterns stored for reuse
CREATE TABLE codebase_patterns (
    id TEXT PRIMARY KEY,
    session_id TEXT NOT NULL,
    pattern_type TEXT NOT NULL,        -- 'api_usage', 'integration', 'structure'
    code_snippet TEXT NOT NULL,       -- Actual code
    description TEXT,                  -- Human description
    language TEXT,                     -- 'python', 'javascript', etc.
    file_path TEXT,                    -- Original file path if applicable
    tags_json TEXT DEFAULT '[]',       -- JSON array of tags
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);

-- Coding session metadata
CREATE TABLE coding_sessions (
    session_id TEXT PRIMARY KEY,
    session_type TEXT NOT NULL,       -- 'coding_session', 'debugging_session', 'architecture_session'
    project_path TEXT,               -- Project directory
    language TEXT,                   -- Primary language
    framework TEXT,                  -- Primary framework
    packages_discovered INTEGER,     -- Count of packages found
    patterns_stored INTEGER,         -- Count of patterns stored
    validation_checks INTEGER        -- Count of validations run
);

-- Validation check results  
CREATE TABLE validation_checks (
    id TEXT PRIMARY KEY,
    session_id TEXT NOT NULL,
    check_type TEXT NOT NULL,         -- 'package_usage', 'reinvention_prevention'
    target_code TEXT NOT NULL,       -- Code that was validated
    result TEXT NOT NULL,            -- 'passed', 'failed', 'warning'
    message TEXT,                    -- Human-readable result
    suggestions_json TEXT,           -- JSON array of suggestions
    created_at TIMESTAMP
);

Migration & Compatibility

• Automatic Migration: New tables created automatically when first used
• Backwards Compatible: Existing sessions continue to work unchanged
• Schema Evolution: Database adapts seamlessly to new features
• Data Isolation: Coding features are project-specific via session isolation

---

📘 Best Practices

General Memory Management

• Always start with create_memory_session()
• Use specific tags for search/export
• Run analyze_memories() before final export
• Use collections for structure
• Track everything under version control

Coding Integration Best Practices

• Start coding sessions with package discovery: discover_packages() first
• Check for reinvention before coding: Use prevent_reinvention_check() early
• Validate code patterns: Run validate_package_usage() before implementation
• Store proven patterns: Use store_codebase_pattern() for team knowledge sharing
• Load project context: Always load_codebase_context() when joining existing projects
• Use appropriate session types:
  • coding_session for general development
  • debugging_session for problem-solving
  • architecture_session for system design

Team Workflow

# 1. Project Lead: Set up discovery
create_memory_session("Project kickoff", "Team alignment", session_type="architecture_session")
discover_packages()  # Establish baseline
load_codebase_context()  # Scan existing code

# 2. Developers: Check before coding
prevent_reinvention_check("user authentication")  # Before starting work
validate_package_usage(proposed_code)  # Before committing

# 3. Knowledge Sharing: Store patterns
store_codebase_pattern("error_handling", error_code, "Team standard error pattern")
export_session_to_file("team_standards.md")

---

🧩 Claude Desktop Integration

{
  "mcpServers": {
    "memory-bank": {
      "command": "uv",
      "args": ["run", "/path/to/memory-bank-mcp/main.py"]
    }
  }
}

---

📄 License

MIT License

---

🆘 Support

• Open an issue on GitHub
• Read the usage examples above