Skip to content

Repository files navigation

🧠 Synaptic - Decentralized MCP

Synaptic Logo

VersionLicenseNode.jsTypeScriptDockerAPI

🚀 Making AI Truly Yours - A revolutionary decentralized protocol that gives you complete control over your AI memories and interactions across all platforms.

🌟 What is Synaptic?

Synaptic is the world's first Decentralized MCP that solves the fundamental problem of AI memory fragmentation. Instead of your conversations and insights being trapped in isolated AI platforms, Synaptic creates a unified, encrypted, and user-owned memory layer that works across all AI tools.

🎯 Core Problems We Solve

  • 🔗 Memory Fragmentation: Your AI conversations are scattered across different platforms
  • 👤 Data Ownership: You don't control your AI interaction data
  • 🔒 Privacy Concerns: Your sensitive conversations are stored on corporate servers
  • 🧠 Context Loss: AI tools can't learn from your previous interactions on other platforms
  • 💰 No Incentives: You don't get rewarded for contributing quality data to AI ecosystems

✨ Key Features

🔐 Privacy-First Architecture

  • End-to-end encryption with AES-256-GCM
  • Local-first storage - your data stays on your devices
  • Zero-knowledge architecture - we can't see your data even if we wanted to
  • Granular privacy controls with 4-level privacy system

🤖 Universal AI Integration

  • Claude (Anthropic) - Full conversation memory extraction
  • OpenAI (GPT) - Complete interaction history
  • Google Gemini - Native integration support
  • Cursor - Development conversation memory
  • Windsurf - AI coding assistant integration
  • Custom APIs - Extensible adapter framework

🧠 Intelligent Memory Management

  • Semantic search with vector embeddings
  • Automatic categorization of memories by type and context
  • Quality assessment with AI-powered scoring
  • Smart context injection for relevant memory retrieval
  • Cross-platform memory synthesis

💰 Token Economics & Rewards

  • $SYNA Token - Native ecosystem currency on Solana
  • Quality-based mining - earn tokens for valuable contributions
  • Decentralized governance - token holders control protocol evolution

🏗️ System Architecture

📊 High-Level Architecture Diagram

graph TB
subgraph "User Interface Layer"
A[Desktop App<br/>Electron] B[Mobile App<br/>React Native]
C[Browser Extension<br/>Chrome/Firefox]
D[Web Dashboard<br/>React]
end
subgraph "API Gateway Layer"
E[REST API Server<br/>Express.js]
F[WebSocket Server<br/>Socket.io]
G[Rate Limiter<br/>Redis]
H[Authentication<br/>JWT]
end
subgraph "Core Protocol Layer"
I[MemoryConnectionProtocol<br/>Central Orchestrator]
J[CrossMindBridge<br/>AI Integration]
K[PrivacyGuard<br/>Encryption & Privacy]
L[MemoryMiner<br/>Token Mining]
end
subgraph "Storage Layer"
M[MemoryVault<br/>Encrypted Storage]
N[Vector Database<br/>Semantic Search]
O[Cache Layer<br/>Redis/Memory]
P[Backup System<br/>IPFS]
end
subgraph "Blockchain Layer"
Q[Solana Network<br/>$SYNA Token]
R[Smart Contracts<br/>Rust/Anchor]
S[Mining Rewards<br/>Quality Assessment]
end
subgraph "External AI Platforms"
T[Claude API<br/>Anthropic]
U[OpenAI API<br/>GPT Models]
V[Gemini API<br/>Google]
W[Custom APIs<br/>Extensible]
end
A --> E
B --> E
C --> E
D --> E
E --> G
E --> H
E --> F
G --> I
H --> I
F --> I
I --> J
I --> K
I --> L
I --> M
M --> N
M --> O
M --> P
L --> Q
L --> R
L --> S
J --> T
J --> U
J --> V
J --> W
Loading

🔧 Core Components Architecture

1. 🧠 MemoryConnectionProtocol (Central Orchestrator)

// Location: src/core/MemoryConnectionProtocol.ts (498 lines)classMemoryConnectionProtocol{privatememoryVault: MemoryVault;privatecrossMindBridge: CrossMindBridge;privateprivacyGuard: PrivacyGuard;privatememoryMiner: MemoryMiner;// Core memory operationsasynccreateMemory(content: string,type: MemoryType,category: MemoryCategory): Promise<Memory>asyncsearchMemories(query: string,options?: SearchOptions): Promise<Memory[]>asyncprocessAIInteraction(platform: AIPlatform,prompt: string,response: AIResponse): Promise<void>asyncgetMemoryStats(): Promise<MemoryStats>}

2. 🗄️ MemoryVault (Intelligent Storage)

// Location: src/storage/MemoryVault.ts (428 lines)classMemoryVault{privatestorage: StorageAdapter;privateencryption: EncryptionService;privatevectorSearch: VectorSearchEngine;// Storage operations with encryptionasyncstoreMemory(memory: Memory): Promise<string>asyncretrieveMemory(id: string): Promise<Memory|null>asyncsearchSemantic(query: string,options: SearchOptions): Promise<SearchResult[]>asyncupdateMemory(id: string,updates: Partial<Memory>): Promise<Memory>}

3. 🌉 CrossMindBridge (AI Integration)

// Location: src/ai/CrossMindBridge.ts (290 lines)classCrossMindBridge{privateadapters: Map<AIPlatform,AIAdapter>;// AI platform integrationasyncprocessInteraction(platform: AIPlatform,interaction: AIInteraction): Promise<ProcessedInteraction>asyncextractMemories(conversation: Conversation): Promise<Memory[]>asyncinjectContext(platform: AIPlatform,memories: Memory[]): Promise<ContextInjection>}

4. 🛡️ PrivacyGuard (Security & Privacy)

// Location: src/privacy/PrivacyGuard.ts (258 lines)classPrivacyGuard{privateencryption: EncryptionService;privateanonymizer: AnonymizationService;// Privacy protectionasyncencryptMemory(memory: Memory): Promise<EncryptedMemory>asyncanonymizeContent(content: string): Promise<AnonymizedContent>asyncdetectPII(text: string): Promise<PIIDetectionResult>}

🔄 Data Flow Architecture

📈 Memory Creation Flow

sequenceDiagram
participant U as User
participant API as API Server
participant MCP as MemoryConnectionProtocol
participant PG as PrivacyGuard
participant MV as MemoryVault
participant VS as VectorSearch
participant BC as Blockchain
U->>API: POST /api/memory
API->>API: Validate Request
API->>MCP: createMemory()
MCP->>PG: encryptMemory()
PG->>PG: Detect PII
PG->>PG: Apply Encryption
PG-->>MCP: Encrypted Memory
MCP->>MV: storeMemory()
MV->>VS: Generate Embeddings
VS-->>MV: Vector Embeddings
MV->>MV: Store to Database
MV-->>MCP: Memory ID
MCP->>BC: Mine Quality Score
BC-->>MCP: Mining Result
MCP-->>API: Created Memory
API-->>U: HTTP 201 Response
Loading

🔍 Memory Search Flow

sequenceDiagram
participant U as User
participant API as API Server
participant MCP as MemoryConnectionProtocol
participant MV as MemoryVault
participant VS as VectorSearch
participant Cache as Cache Layer
U->>API: GET /api/memory/search?query=...
API->>API: Validate & Rate Limit
API->>MCP: searchMemories()
MCP->>Cache: Check Cache
alt Cache Hit
Cache-->>MCP: Cached Results
else Cache Miss
MCP->>MV: searchSemantic()
MV->>VS: Vector Search
VS->>VS: Similarity Calculation
VS-->>MV: Ranked Results
MV->>MV: Apply Privacy Filters
MV-->>MCP: Filtered Results
MCP->>Cache: Store Results
end
MCP-->>API: Search Results
API-->>U: HTTP 200 Response
Loading

🤖 AI Interaction Processing Flow

sequenceDiagram
participant AI as AI Platform
participant CMB as CrossMindBridge
participant MCP as MemoryConnectionProtocol
participant MV as MemoryVault
participant MM as MemoryMiner
participant BC as Blockchain
AI->>CMB: New Interaction
CMB->>CMB: Extract Memories
CMB->>MCP: processAIInteraction()
MCP->>MV: Store Interaction
MCP->>MM: Assess Quality
MM->>MM: AI Quality Analysis
MM->>BC: Submit for Mining
BC->>BC: Validate & Mine
BC-->>MM: Mining Rewards
MM-->>MCP: Quality Score
MCP->>MV: Update Memory Quality
MCP-->>CMB: Processing Complete
CMB-->>AI: Context Injection
Loading

🛠️ Technical Implementation

🔧 Core Technology Stack

LayerTechnologyPurpose
FrontendReact, Electron, React NativeMulti-platform user interfaces
BackendNode.js, Express.js, TypeScriptAPI server and business logic
DatabaseSQLite, PostgreSQL, RedisData storage and caching
SearchVector embeddings, Semantic searchIntelligent memory retrieval
BlockchainSolana, Rust, AnchorToken economics and mining
AI IntegrationOpenAI, Anthropic, Google APIsMulti-platform AI support
SecurityAES-256-GCM, JWT, bcryptEncryption and authentication
DevOpsDocker, Docker ComposeContainerization and deployment

📁 Project Structure

synaptic/
├── 📁 src/ # Source code
│ ├── 📁 core/ # Core protocol implementation
│ │ └── MemoryConnectionProtocol.ts # Central orchestrator (498 lines)
│ ├── 📁 storage/ # Storage layer
│ │ └── MemoryVault.ts # Encrypted storage (428 lines)
│ ├── 📁 ai/ # AI integration
│ │ └── CrossMindBridge.ts # AI platform bridge (290 lines)
│ ├── 📁 privacy/ # Privacy and security
│ │ └── PrivacyGuard.ts # Privacy protection (258 lines)
│ ├── 📁 blockchain/ # Blockchain integration
│ │ └── MemoryMiner.ts # Token mining (212 lines)
│ ├── 📁 api/ # REST API server
│ │ ├── server.ts # Express server (232 lines)
│ │ ├── 📁 routes/ # API endpoints
│ │ │ ├── memory.ts # Memory operations (159 lines)
│ │ │ ├── ai.ts # AI interactions (95 lines)
│ │ │ ├── health.ts # Health monitoring (287 lines)
│ │ │ ├── auth.ts # Authentication (70 lines)
│ │ │ └── blockchain.ts # Blockchain operations (68 lines)
│ │ └── 📁 middleware/ # API middleware
│ │ ├── auth.ts # JWT authentication (146 lines)
│ │ ├── rateLimiter.ts # Rate limiting (186 lines)
│ │ └── validation.ts # Request validation (310 lines)
│ ├── 📁 utils/ # Utility modules
│ │ ├── DatabaseManager.ts # Database abstraction (296 lines)
│ │ ├── ErrorHandler.ts # Error management (332 lines)
│ │ ├── PerformanceMonitor.ts # Performance tracking (317 lines)
│ │ ├── CacheManager.ts # Caching system (395 lines)
│ │ ├── ConfigManager.ts # Configuration (347 lines)
│ │ ├── Logger.ts # Logging system (104 lines)
│ │ ├── Validator.ts # Input validation (172 lines)
│ │ └── Encryption.ts # Encryption utilities (121 lines)
│ ├── 📁 types/ # TypeScript definitions
│ │ └── index.ts # Type definitions (408 lines)
│ ├── 📁 config/ # Configuration files
│ ├── 📁 scripts/ # Setup and utility scripts
│ │ └── setup.ts # Automated setup (426 lines)
│ ├── 📁 examples/ # Usage examples
│ │ └── basic-usage.ts # Comprehensive examples (424 lines)
│ └── index.ts # Main entry point (119 lines)
├── 📁 apps/ # Multi-platform applications
│ ├── 📁 desktop/ # Electron desktop app
│ ├── 📁 mobile/ # React Native mobile app
│ └── 📁 extension/ # Browser extension
├── 📁 contracts/ # Solana smart contracts
├── 📁 tests/ # Test suite
├── 📁 docs/ # Documentation
├── 📁 config/ # Environment configurations
├── 🐳 Dockerfile # Container configuration
├── 🐳 docker-compose.yml # Development stack
├── 📦 package.json # Dependencies and scripts
├── 🔧 tsconfig.json # TypeScript configuration
├── 🔧 .eslintrc.js # Code quality rules
├── 🔧 .prettierrc # Code formatting
└── 📖 README.md # This documentation

🔑 Key Implementation Details

1. 🗄️ Memory Storage with Encryption

// src/storage/MemoryVault.tsclassMemoryVault{asyncstoreMemory(memory: Memory): Promise<string>{// 1. Encrypt sensitive contentconstencryptedContent=awaitthis.encryption.encrypt(memory.content);// 2. Generate vector embeddings for searchconstembeddings=awaitthis.vectorSearch.generateEmbeddings(memory.content);// 3. Store in database with metadataconststoredMemory={
...memory,content: encryptedContent,
embeddings,createdAt: newDate(),updatedAt: newDate()};returnawaitthis.storage.save(storedMemory);}}

2. 🔍 Semantic Search Implementation

// Vector-based semantic searchasyncsearchSemantic(query: string,options: SearchOptions): Promise<SearchResult[]>{// 1. Generate query embeddingsconstqueryEmbeddings=awaitthis.vectorSearch.generateEmbeddings(query);// 2. Calculate similarity scoresconstsimilarities=awaitthis.vectorSearch.findSimilar(queryEmbeddings,options.limit||10,options.minSimilarity||0.7);// 3. Apply privacy filtersconstfilteredResults=similarities.filter(result=>this.privacyGuard.canAccess(result.memory,options.userId));returnfilteredResults;}

3. 🤖 AI Platform Integration

// src/ai/CrossMindBridge.tsclassCrossMindBridge{asyncprocessInteraction(platform: AIPlatform,interaction: AIInteraction): Promise<void>{// 1. Get platform-specific adapterconstadapter=this.adapters.get(platform);// 2. Extract memories from conversationconstmemories=awaitadapter.extractMemories(interaction);// 3. Store memories with quality assessmentfor(constmemoryofmemories){constqualityScore=awaitthis.assessQuality(memory);awaitthis.memoryVault.storeMemory({
...memory,
qualityScore,
platform,sessionId: interaction.sessionId});}// 4. Trigger mining processawaitthis.memoryMiner.processNewMemories(memories);}}

4. 🔒 Privacy Protection

// src/privacy/PrivacyGuard.tsclassPrivacyGuard{asyncencryptMemory(memory: Memory): Promise<EncryptedMemory>{// 1. Detect and mask PIIconstpiiDetection=awaitthis.detectPII(memory.content);constmaskedContent=this.maskPII(memory.content,piiDetection);// 2. Apply encryption based on privacy levelconstencryptionKey=this.generateKey(memory.privacyLevel);constencryptedContent=awaitthis.encryption.encrypt(maskedContent,encryptionKey);// 3. Store encryption metadatareturn{
...memory,content: encryptedContent,encryptionMetadata: {algorithm: 'AES-256-GCM',keyId: encryptionKey.id,piiMasked: piiDetection.found}};}}

🚀 API Documentation

📋 REST API Endpoints

Memory Management

POST /api/memory # Create new memoryGET /api/memory/:id # Get memory by IDPUT /api/memory/:id # Update memoryDELETE /api/memory/:id # Delete memoryGET /api/memory/search # Search memoriesGET /api/memory/stats # Get memory statistics

AI Interactions

POST /api/ai/interaction # Process AI interactionGET /api/ai/context # Get AI contextPOST /api/ai/inject # Inject memory contextGET /api/ai/platforms # List supported platforms

Authentication & Users

POST /api/auth/register # Register new userPOST /api/auth/login # User loginPOST /api/auth/refresh # Refresh tokenGET /api/auth/profile # Get user profile

Blockchain & Mining

GET /api/blockchain/balance # Get token balancePOST /api/blockchain/mine # Start mining processGET /api/blockchain/rewards # Get mining rewardsGET /api/blockchain/stats # Get blockchain stats

Health & Monitoring

GET /health # Basic health checkGET /health/detailed # Detailed system healthGET /health/metrics # Performance metricsGET /health/errors # Error statistics

📊 API Response Examples

Create Memory

curl -X POST http://localhost:3000/api/memory \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{ "content": "TypeScript provides static typing for JavaScript", "type": "knowledge", "category": "technical", "tags": ["typescript", "programming", "javascript"], "privacyLevel": 1 }'

Response:

{
"success": true,
"data": {
"id": "mem_1234567890",
"content": "TypeScript provides static typing for JavaScript",
"type": "knowledge",
"category": "technical",
"qualityScore": 0.85,
"tags": ["typescript", "programming", "javascript"],
"privacyLevel": 1,
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
}

Search Memories

curl "http://localhost:3000/api/memory/search?query=typescript&limit=5&minQuality=0.7" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
"success": true,
"data": {
"results": [
{
"id": "mem_1234567890",
"content": "TypeScript provides static typing for JavaScript",
"similarity": 0.92,
"qualityScore": 0.85,
"type": "knowledge",
"category": "technical"
}
],
"total": 1,
"query": "typescript",
"executionTime": "45ms"
}
}

🚀 Quick Start Guide

📋 Prerequisites

  • Node.js 18.0.0 or higher
  • npm 9.0.0 or higher
  • Git for cloning the repository
  • Docker (optional, for containerized deployment)

⚡ Installation

  1. Clone the repository

    git clone https://github.com/Synaptic-MCP/Synaptic.git
    cd Synaptic
  2. Install dependencies

    npm install
  3. Configure environment

    cp env.example .env
    # Edit .env with your configuration
  4. Run automated setup

    npm run setup:dev
  5. Start development server

    npm run dev

The API server will be available at http://localhost:3000

🐳 Docker Setup (Recommended)

  1. Using Docker Compose (Full Stack)

    docker-compose up -d
  2. Using Docker directly

    docker build -t synaptic .
    docker run -p 3000:3000 synaptic

🧪 Testing the Installation

  1. Health Check

    curl http://localhost:3000/health
  2. Run Examples

    npm run examples
  3. API Documentation Visit http://localhost:3000/api/docs

💻 Usage Examples

🔧 Basic Usage

importSynaptic,{MemoryType,MemoryCategory,PrivacyLevel}from'synaptic';// Initialize Synapticconstsynaptic=newSynaptic({server: {host: 'localhost',port: 3000},storage: {path: './my-memories.db'},ai: {defaultProvider: 'openai'}});// Start the systemawaitsynaptic.start();// Create a memoryconstmemory=awaitsynaptic.getProtocol().createMemory('React hooks simplify state management in functional components',MemoryType.KNOWLEDGE,MemoryCategory.TECHNICAL,{tags: ['react','hooks','javascript'],privacyLevel: PrivacyLevel.PUBLIC});// Search memoriesconstresults=awaitsynaptic.getProtocol().searchMemories('react state management',{limit: 10,minQuality: 0.7});// Process AI interactionawaitsynaptic.getProtocol().processAIInteraction('claude','How do React hooks work?','React hooks are functions that let you use state and lifecycle features...','session_123');// Get memory statisticsconststats=awaitsynaptic.getProtocol().getMemoryStats();console.log(`Total memories: ${stats.totalMemories}`);

🌐 API Usage Examples

# Create a memory
curl -X POST http://localhost:3000/api/memory \
-H "Content-Type: application/json" \
-d '{ "content": "Machine learning models require quality training data", "type": "knowledge", "category": "technical", "tags": ["ml", "ai", "data"] }'# Search memories
curl "http://localhost:3000/api/memory/search?query=machine%20learning&limit=5"# Get system health
curl http://localhost:3000/health/detailed
# Get performance metrics
curl http://localhost:3000/health/metrics

🔧 Development

📝 Available Scripts

# Development
npm run dev # Start development server
npm run build # Build for production
npm run test# Run test suite
npm run test:watch # Run tests in watch mode# Code Quality
npm run lint # Run ESLint
npm run lint:fix # Fix ESLint issues
npm run format # Format code with Prettier# Setup & Deployment
npm run setup:dev # Development setup
npm run setup:prod # Production setup
npm run docker:build # Build Docker image
npm run docker:run # Run Docker container# Examples & Documentation
npm run examples # Run usage examples
npm run docs # Generate documentation
npm run health # Check server health

🧪 Testing

# Run all tests
npm test# Run tests with coverage
npm run test:coverage
# Run specific test file
npm test -- --testNamePattern="MemoryVault"# Run tests in watch mode
npm run test:watch

🔍 Monitoring & Debugging

# Check system health
npm run health
# View performance metrics
curl http://localhost:3000/health/metrics
# Check error statistics
curl http://localhost:3000/health/errors
# View logs
docker-compose logs -f synaptic

🌍 Deployment

🐳 Production Deployment

  1. Build production image

    docker build -t synaptic:latest .
  2. Run with production configuration

    docker run -d \
    --name synaptic \
    -p 3000:3000 \
    -e NODE_ENV=production \
    -e DATABASE_URL=your_database_url \
    -v /path/to/data:/app/data \
    synaptic:latest
  3. Using Docker Compose

    docker-compose -f docker-compose.prod.yml up -d

☁️ Cloud Deployment

AWS ECS

# Build and push to ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin your-account.dkr.ecr.us-east-1.amazonaws.com
docker build -t synaptic .
docker tag synaptic:latest your-account.dkr.ecr.us-east-1.amazonaws.com/synaptic:latest
docker push your-account.dkr.ecr.us-east-1.amazonaws.com/synaptic:latest

Kubernetes

apiVersion: apps/v1kind: Deploymentmetadata:
name: synapticspec:
replicas: 3selector:
matchLabels:
app: synaptictemplate:
metadata:
labels:
app: synapticspec:
containers:
- name: synapticimage: synaptic:latestports:
- containerPort: 3000env:
- name: NODE_ENVvalue: "production"livenessProbe:
httpGet:
path: /health/liveport: 3000readinessProbe:
httpGet:
path: /health/readyport: 3000

🤝 Contributing

🔄 Development Workflow

  1. Fork the repository
  2. Create a feature branch
    git checkout -b feature/amazing-feature
  3. Make your changes
  4. Run tests and linting
    npm run check
  5. Commit your changes
    git commit -m "feat: add amazing feature"
  6. Push to your branch
    git push origin feature/amazing-feature
  7. Open a Pull Request

📋 Code Standards

  • TypeScript for all source code
  • ESLint for code quality
  • Prettier for code formatting
  • Jest for testing
  • Conventional Commits for commit messages

🧪 Testing Requirements

  • Unit tests for all core functionality
  • Integration tests for API endpoints
  • End-to-end tests for critical user flows
  • Minimum 80% code coverage

📊 Performance & Monitoring

📈 Key Metrics

  • Memory Operations: Create, Read, Update, Delete performance
  • Search Performance: Semantic search response times
  • API Response Times: 95th percentile under 200ms
  • Error Rates: Less than 0.1% error rate
  • Uptime: 99.9% availability target

🔍 Monitoring Endpoints

# System health
GET /health
# Detailed health with component status
GET /health/detailed
# Performance metrics
GET /health/metrics
# Error statistics
GET /health/errors
# System information
GET /health/system

📊 Performance Optimization

  • Caching: Multi-level caching with Redis
  • Database Indexing: Optimized database queries
  • Connection Pooling: Efficient database connections
  • Rate Limiting: API protection and fair usage
  • Compression: Response compression for faster transfers

🔐 Security

🛡️ Security Features

  • End-to-end Encryption: AES-256-GCM encryption
  • JWT Authentication: Secure token-based auth
  • Rate Limiting: Protection against abuse
  • Input Validation: Comprehensive request validation
  • PII Detection: Automatic sensitive data detection
  • Privacy Levels: Granular privacy controls

🔒 Security Best Practices

  • Regular security audits
  • Dependency vulnerability scanning
  • Secure coding practices
  • Data minimization principles
  • Privacy by design architecture

📞 Support & Community

🌐 Connect With Us

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • OpenAI for GPT API integration
  • Anthropic for Claude API support
  • Google for Gemini API access
  • Solana Foundation for blockchain infrastructure
  • Open Source Community for amazing tools and libraries

🧠 Making AI Truly Yours

Built with ❤️ by the Synaptic Team

WebsiteDocumentationTwitter

About

Decentralized AI Memory Connection Protocol - Making AI Truly Yours. A revolutionary protocol that gives you complete control over your AI memories and interactions across all platforms.

Topics

Resources

Stars

28 stars

Watchers

7 watching

Forks

Releases

Packages

Used by

Contributors

Languages