sandraschi/advanced-memory-mcp

](https://github.com/sandraschi/advanced-memory-mcp)

Advanced Memory MCP & Webapp

Research-Driven Knowledge Platform - A dual-purpose system serving as both a powerful Model Context Protocol (MCP) server and a standalone React-based web application. Transform AI assistants into comprehensive research tools with multi-source intelligence gathering, semantic search (RAG), and intelligent skill synthesis.

[!IMPORTANT] Dual Architecture: MemOps is a hybrid system consisting of a high-concurrency FastMCP Server (for tool integration) and a premium React Webapp (for visual knowledge management).

Advanced Memory evolves from a simple memory tool into an enterprise-grade research platform, integrating a robust vector database for semantic understanding.

Core Capabilities

• Multi-Source Research: Web search, academic papers (arXiv), code repositories (GitHub), narrative patterns (TV Tropes)
• Semantic Intelligence:
  • RAG Engine: LanceDB + FastEmbed vector search with hybrid Whoosh/FTS5 integration.
  • Optimized Reranking: BGE-Reranker-v2-m3 with Flash Attention 2 support (RTX 4090).
  • Encryption: Transparent Fernet/AESnd (AES-128) metadata encryption for sensitive knowledge.
• Portmanteau Tools:
  • adn_knowledge_rag: High-density context retrieval bridge for OpenFang.
• Document Intelligence: PDF/EPUB processing with intelligent chunking and automated vector ingestion.
• Agentic Workflows: FastMCP 2.14.1+ SEP-1577 sampling with real tool functions — LLM autonomously orchestrates multi-step knowledge workflows via ctx.sample(tools=[...], result_type=Model)
• Skill Synthesis: Research-driven expert skill generation using FastMCP sampling
• Knowledge Management: Zettelkasten-based note system with Claude Skills export/import
• Ecosystem Observability: Real-time fleet discovery (Apps Hub) and agent session monitoring (Control Room)
• Hardware Telemetry: Native substrate tracking (GPU/CPU/RAM) with RTX 4094 optimization
• Conversational AI (Planned): Natural language interaction with ADN tools and knowledge graph (FREE - uses local Ollama) →
• Production Observability: State-of-the-art monitoring with Grafana dashboards, Prometheus metrics, Loki logs
• Cross-Platform Support: Compatible with Claude Desktop, Cursor IDE, Windsurf, and other MCP clients
• Web Interface: Standalone React application for direct usage without MCP client requirements

Architecture

advanced-memory-mcp/
├── src/                    # MCP server source code
├── webapp/                 # React web application
├── docs/                   # Documentation
├── tests/                  # Test suite
└── scripts/                # Build and utility scripts

Quick Start

🚀 Installation

Prerequisites

• uv installed (RECOMMENDED)
• Python 3.12+

📦 Quick Start

Run immediately via uvx:

uvx advanced-memory

🎯 Claude Desktop Integration

Add to your claude_desktop_config.json:

"mcpServers": {
  "advanced-memory": {
    "command": "uv",
    "args": ["--directory", "D:/Dev/repos/advanced-memory-mcp", "run", "advanced-memory"]
  }
}

📦 Packaging & Distribution

This repository is SOTA 2026 compliant and uses the officially validated @anthropic-ai/mcpb workflow for distribution.

Pack Extension

To generate a .mcpb distribution bundle with complete source code and automated build exclusions:

# SOTA 2026 standard pack command
mcpb pack . dist/advanced-memory-mcp.mcpb

### Standalone Web Application (Automatic Startup)
```powershell
# RECOMMENDED: Clean startup (kills zombies, prevents port conflicts)
.\run-webapp-clean.bat  # Opens http://localhost:17770

# Alternative: Standard startup
.\run-webapp.bat  # Opens http://localhost:17770

# Check port usage and zombie processes
.\check-webapp-port.ps1  # Diagnose port conflicts

# Graceful remote shutdown
.\shutdown-adn.ps1 "Maintenance shutdown"  # Graceful shutdown via API
.\shutdown-adn.bat "System update"         # Batch version

Important: Webapp runs on port 17770 (strict port, no hopping allowed). Always use run-webapp-clean.bat to kill zombie processes before restart. Use graceful exit endpoint for remote shutdown.

Restart all: Run .\kill-adn-zombies.bat, then .\run-webapp-clean.bat. Alternatively, start node auto-start-service.js, wait a few seconds, then POST http://localhost:8003/start-all to bring up startup, bridge, and webapp.

The webapp automatically detects and starts the ADN MCP server when you access the Notes page.

Skill System

Advanced Memory MCP includes a comprehensive Claude Skills ecosystem with multi-IDE support.

Skill Locations

CRITICAL: Skill directories are located in user home directories, NOT in this repository:

• Cursor Skills: C:\Users\[username]\.cursor\skills-cursor
• Windsurf Skills: C:\Users\[username]\.codeium\windsurf\skills
• ADN Skills: D:\Dev\repos\advanced-memory-mcp\skills (this repository)
• Antigravity Skills: C:\Users\[username]\.gemini\antigravity\skills

Skill Documentation

• : Complete workflow for creating and distributing skills
• : Finding and accessing skills across IDEs
• : Quality and compatibility requirements
• : Current adoption trends and statistics
• : Technical implementation details

The webapp scans these directories recursively for SKILL.md files (including nested layouts such as skills/category/skill-name/SKILL.md) and displays them in the Skills page. Use All collections to show Cursor, WindSurf, Antigravity, and ADN skills together; you can also filter by folder.

Manual Web Application Setup

# Install dependencies
npm install
cd webapp && npm install

# Start services
node auto-start-service.js    # Service orchestrator
node startup-service.js       # Bridge server manager
cd webapp && npm run dev      # Web UI on http://localhost:17770

Docker (webapp)

# Build and run the webapp container (port 17770)
docker compose build webapp
docker compose up -d webapp
# Open http://localhost:17770

The webapp container serves the React UI only. Run the bridge and MCP server on the host (e.g. .\run-webapp-clean.bat) for full API access, or use the MCP Docker service (SSE on 8000) and configure VITE_API_URL if your setup differs.

MCP Integration

The Advanced Memory MCP server provides comprehensive tools for knowledge management, research, and skill-based automation.

Supported MCP Clients

• Cursor: Full integration with stdio transport
• Claude Desktop: Full integration with stdio transport
• Web Bridge Server: HTTP-to-MCP bridge for web applications
• External MCP Servers: BrightData and Fetch integration

Tool Categories

Knowledge & Content:

• adn_content - Unified content management (write, read, edit, delete, quick, daily, move, etc.)
• adn_search - Unified search across notes, Obsidian, Joplin, Notion, and Evernote
• adn_project - Multi-project session and lifecycle management
• adn_observability - AI agent session recording and repository checkpointing

Research & Analysis:

• adn_research - Multi-source research (Web, arXiv, GitHub, TV Tropes)
• adn_document_ingest - Document processing and vector search ingestion

Skill System:

• adn_skills - Claude Skills ecosystem management and automated synthesis

System & Integration:

• adn_system - Health checks, sync status, and inter-server communication relay
• adn_audio - Direct voice dictation and transcription (requires [voice] extra)

External MCP Integration:

• BrightData MCP Server:

  • search_engine - Anti-bot bypassed web search
  • scrape_as_markdown - Web content scraping with anti-bot bypass
  • search_engine_batch - Batch search operations
  • scrape_batch - Batch scraping operations

• Fetch MCP Server:

  • fetch - Advanced HTTP requests with full options

Web Bridge Server

The included Node.js bridge server (bridge-server.js) provides HTTP access to MCP functionality:

# Start the bridge server
node bridge-server.js

# Access via HTTP endpoints
GET  /health                    # Server health and MCP status
GET  /api/v1/notes              # ADN notes via MCP
POST /api/v1/brightdata/search  # BrightData search
POST /api/v1/brightdata/scrape  # BrightData scraping
POST /api/v1/fetch              # HTTP fetch operations

Default Port: 8001 (configurable)

Features:

• Automatic MCP server discovery and initialization
• Realistic MCP response simulation
• CORS-enabled for web application integration
• Comprehensive logging and error handling

Documentation

Development Status

Version: 1.5.0 Status: Production Ready (RAG Enabled) MCP Compatibility: FastMCP 2.14.3+ Test Coverage: 98% pass rate (1,136/1,161 tests) + 90% MCP Integration (18/20 tests) Glama Rating: Silver Tier (80/100) Web Interface: React application included (Apps Hub, Control Room, Skill Studio) MCP Ecosystem: Full integration with BrightData, Fetch, and ADN servers

Requirements

• Python 3.11+
• Node.js 18+ (for web interface)
• Compatible MCP client (Claude Desktop, Cursor, etc.)

Future Developments

Conversational AI Extension (Low Priority, 8 weeks)

Transform the webapp into a Claude-like conversational assistant with natural language interaction, tool orchestration, and conversation memory stored in the ADN knowledge graph.

Key Features:

• Natural language queries instead of manual navigation
• Automatic ADN tool discovery and execution
• Context-aware responses using knowledge graph
• Conversation persistence as searchable knowledge
• Real-time tool execution visualization
• 💰 100% FREE - Uses local Ollama, no API costs

|

License

AGPL-3.0-or-later

Advanced Memory MCP - Enterprise-grade research platform for AI assistants with state-of-the-art observability, evolved from Basic Memory MCP with expanded research capabilities and production reliability.