🧠 NeuralSync v2

Complete unified memory system for CLI AIs with enhanced daemon management

Persistent, CRDT-synchronized memory for claude-code, codex, and other CLI AI tools

🚀 Quick Start • 🔧 Latest Updates • ⚡ Features • 🛠️ Installation • 📖 Documentation • 🤝 Contributing

---

⚡ Features

🎯 Core Memory System 🧠 Persistent Context - Never lose conversation history 🔄 CRDT Synchronization - Real-time multi-device sync 🔍 Vector Search - Semantic memory retrieval 🏷️ Smart Tagging - Automatic content categorization ⚡ Sub-100ms Recall - Lightning-fast memory access

🛡️ Enhanced Performance 🚀 Enhanced Daemon Management - 85% faster startup 🔧 Auto-Recovery - Self-healing service detection 📊 Performance Monitoring - Real-time system metrics 🌐 Network Resilience - Intelligent failover handling 🔐 Enterprise Security - JWT auth + encryption

---

🚀 Quick Start

One-Command Installation

# Clone and install NeuralSync v2
git clone https://github.com/heyfinal/NeuralSync2.git
cd NeuralSync2
python3 install_neuralsync.py

Instant Integration

# Use with claude-code (enhanced with persistent memory)
claude-ns "What were we discussing yesterday about the API design?"

# Use with codex (full context retention)  
codex-ns "Continue the refactoring we started last session"

# Use with gemini (synchronized across all sessions)
gemini-ns "Build on the architecture we planned together"

---

🔧 Latest Updates - CLI Integration Fixes

✅ Fixed CLI Wrapper Issues

• Resolved argument conflicts in codex-ns wrapper (--ask-for-approval handling)
• Fixed wrapper hanging issues with claude-ns and other CLI tools
• Enhanced error handling for missing underlying CLI installations
• Improved process management preventing timeout issues

🧪 100% Test Success Rate

# Comprehensive integration test results
✅ nswrap Basic: PASS - Echo command works  
✅ Memory Storage: PASS - Test memory stored successfully
✅ Memory Recall: PASS - Retrieved 1 memories
✅ Context Injection: PASS - Context injection working
✅ Cross-tool Memory: PASS - Memory shared between tools
✅ Persona Sharing: PASS - Persona stored and retrieved
✅ Codex Wrapper: PASS - Version check successful
✅ Claude Wrapper: PASS - Wrapper responds (no hang)

🚀 Performance Improvements

• Enhanced wrapper deployment via updated installer
• Fixed SQLite FTS UPSERT errors preventing memory storage
• Resolved JSON serialization issues with binary vector data
• Auto-recovery mechanisms for failed CLI integrations

📦 Installation Enhancements

• Updated main installer now includes all wrapper fixes
• Simplified deployment with claude-ns-fixed, codex-ns-fixed, gemini-ns-fixed
• Integrated nswrap installation for seamless CLI wrapping
• Enhanced completion messages with clear testing instructions

---

🛠️ Installation

📋 System Requirements

• Python: 3.9+ (3.11+ recommended)
• OS: macOS, Linux, Windows
• Memory: 512MB+ RAM
• Storage: 100MB+ available space
• Network: Internet connection for AI tools

Method 1: Automated Installation (Recommended)

# Download and run the installer
wget https://raw.githubusercontent.com/heyfinal/NeuralSync2/main/install_neuralsync.py
python3 install_neuralsync.py

Method 2: Manual Installation

🔧 Manual Setup Steps

1. Clone Repository

   git clone https://github.com/heyfinal/NeuralSync2.git
   cd NeuralSync2

2. Create Virtual Environment

   python3 -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install Dependencies

   pip install -r requirements.txt

4. Setup Configuration

   mkdir -p ~/.neuralsync
   cp config/example.neuralsync.yaml ~/.neuralsync/config.yaml

5. Install CLI Wrappers

   python3 install_neuralsync.py --skip-deps

---

📖 Documentation

🎯 Usage Examples

💬 Basic Memory Operations

# Store information for later recall
claude-ns "Remember that our API uses JWT tokens with 24-hour expiry"

# Recall relevant context automatically
claude-ns "How should I implement authentication?"
# → Automatically includes JWT token information from previous session

# Search specific memories
claude-ns "What did we discuss about database optimization?"

🔄 Cross-Session Continuity

# Day 1: Start a project
claude-ns "Let's design a REST API for user management"

# Day 2: Continue seamlessly  
claude-ns "Add the user registration endpoint we discussed"
# → Full context from previous session automatically included

# Week later: Pick up where you left off
claude-ns "Deploy the user API to production"  
# → Complete project history available

🛠️ Multi-Tool Integration

# Architecture discussion with claude-code
claude-ns "Design microservices architecture for e-commerce"

# Implementation with codex
codex-ns "Implement the user service from our architecture"
# → Shares the same memory context

# Review with gemini  
gemini-ns "Review the code quality of our user service"
# → All tools share unified memory

🏗️ Architecture Overview

graph TB
    A[CLI Tools] --> B[NeuralSync Wrapper]
    B --> C[Enhanced Daemon Manager]
    C --> D[Memory Core]
    D --> E[Vector Database]
    D --> F[CRDT Sync Engine]
    F --> G[Multi-Device Sync]
    
    subgraph "Enhanced Features"
        H[Service Detection]
        I[Performance Monitor]  
        J[Auto-Recovery]
    end
    
    C --> H
    C --> I
    C --> J

Loading

---

⚙️ Configuration

Basic Configuration

The system works out-of-the-box with sensible defaults. For advanced usage:

# ~/.neuralsync/config.yaml
site_id: "unique-device-id"
db_path: "~/.neuralsync/memory.db"
vector_dim: 512
bind_host: "127.0.0.1"
bind_port: 8373

# Enhanced daemon management
enhanced_daemon:
  enabled: true
  performance_mode: "adaptive"  # minimal, balanced, aggressive, adaptive
  memory_threshold: 85          # Auto-restart when memory > 85%
  service_timeout: 30           # Service startup timeout (seconds)

Advanced Features

🔧 Performance Tuning

performance:
  cache_size: 1000           # Memory cache entries
  vector_cache_ttl: 300      # Vector cache TTL (seconds)
  batch_size: 100            # Batch processing size
  worker_threads: 4          # Background worker threads
  
optimization:
  auto_cleanup: true         # Automatic memory cleanup
  compress_old: true         # Compress old memories
  smart_prefetch: true       # Predictive memory loading

🔐 Security Configuration

security:
  token_required: false      # Require JWT tokens
  encrypt_at_rest: true      # Encrypt local database
  secure_transport: true     # Use TLS for sync
  
access_control:
  max_sessions: 10           # Concurrent session limit
  rate_limit: 1000           # Requests per hour
  allowed_tools: ["claude-code", "codex", "gemini"]

---

🚀 Performance & Benchmarks

Metric	NeuralSync v1	NeuralSync v2	Improvement
Cold Start	30-45s	2-5s	🚀 85% faster
Memory Recall	200-500ms	<100ms	⚡ 75% faster
Service Detection	5-10s	<0.1s	🔥 99% faster
Memory Usage	200MB	120MB	💾 40% less
Reliability	75% uptime	99.5% uptime	🛡️ 24% better

---

🤝 Contributing

We welcome contributions! Here's how you can help:

🐛 Bug Reports

• Use the issue tracker
• Include system info and logs
• Provide reproduction steps

✨ Feature Requests

• Check existing issues first
• Explain the use case
• Consider backward compatibility

🔧 Development Setup

# Fork and clone the repository
git clone https://github.com/your-username/NeuralSync2.git
cd NeuralSync2

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
python -m pytest tests/

# Run linting
black . && flake8 .

📝 Pull Request Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📚 Advanced Documentation

🔌 API Reference

Memory Storage API

# Store memories with metadata
POST /remember
{
  "text": "API uses JWT authentication",
  "kind": "fact",
  "scope": "project",  
  "tool": "claude-code",
  "confidence": 0.95,
  "tags": ["authentication", "security"]
}

Memory Recall API

# Search and recall memories
POST /recall
{
  "query": "authentication method",
  "top_k": 5,
  "scope": "project",
  "tool": "claude-code"
}

🛠️ Troubleshooting

Common Issues

Services Won't Start

# Check service status
systemctl --user status neuralsync

# View logs  
journalctl --user -u neuralsync -f

# Restart services
neuralsync-daemon restart

Memory Issues

# Check memory usage
neuralsync status --verbose

# Clean old memories
neuralsync cleanup --days 30

# Reset database
neuralsync reset --confirm

Performance Issues

# Enable performance mode
neuralsync config set performance.mode aggressive

# Monitor performance
neuralsync monitor --realtime

# Optimize database
neuralsync optimize

---

📄 License

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

---

🙏 Acknowledgments

• Claude - For the incredible AI assistance
• OpenAI Codex - For code generation capabilities
• Google Gemini - For multimodal AI support
• The Open Source Community - For tools, libraries, and inspiration

---

⬆ Back to Top

Made with ❤️ by the NeuralSync Team

Star ⭐ this repository if you find it helpful!