Molecular MCP Server 🧬

A persistent memory system for Claude instances, enabling cross-session intelligence through vector embeddings and semantic search.

Overview

Molecular captures development events at a granular level ("molecular granularity") and provides:

• Persistent Memory across Claude sessions
• Semantic Search to find similar past solutions
• Cross-Project Intelligence through vector embeddings
• Event Classification with smart compression and buffering

Quick Start

See QUICKSTART.md for installation and basic usage.

Architecture

Built with Rust for performance and reliability:

• LanceDB for vector storage with ML embeddings
• all-MiniLM-L6-v2 sentence transformer for semantic embeddings (384-dimensional)
• Candle for pure Rust ML inference (no Python dependencies!)
• Ring Buffer for flood protection and event classification
• MCP Protocol for Claude Desktop integration
• Async/Tokio for concurrent operations

See SYSTEM_ARCHITECTURE.md for detailed technical documentation.

Current Status (v1.6.0)

✅ Working Features

• Event capture and persistent storage
• Multi-tier ring buffer with compression
• Semantic search with ML-based embeddings (all-MiniLM-L6-v2)
• Session management and tracking
• Command execution with logging
• MCP protocol implementation
• Pure Rust ML inference pipeline with Candle

⚠️ Known Issues

• P0: Similarity scores show 0% (LanceDB distance bug)
• P0: Timestamps display as 1970-01-01 (fix available)
• P1: Project detection shows "unknown"

See KNOWN_ISSUES.md for details and fixes.

Project Structure

molecular/
├── src/                     # Source code
│   ├── vector_molecular.rs  # Main MCP server
│   ├── vector_database.rs   # LanceDB integration
│   ├── vector_schema.rs     # Event data structures
│   ├── embeddings.rs        # Vector embeddings
│   ├── ring_buffer.rs       # Event buffering
│   ├── semantic_classifier.rs # Event classification
│   ├── config.rs            # Configuration
│   └── bin/
│       └── duck.rs          # Claude Desktop wrapper
├── tools/                   # Utility scripts
├── Cargo.toml              # Rust dependencies
└── docs/
    ├── QUICKSTART.md       # Getting started
    ├── SYSTEM_ARCHITECTURE.md # Technical details
    ├── KNOWN_ISSUES.md     # Bug tracking
    ├── CONTRIBUTING.md     # Contribution guide
    ├── VERSIONING.md       # Version management
    └── CHANGELOG.md        # Version history

MCP Tools

Tool	Description	Status
welcome	Session info and stats	✅ Working
exec	Execute commands with logging	✅ Working
semantic_search	Find similar past events	⚠️ 0% similarity bug
guestbook	Leave notes for future Claudes	✅ Working
register_claude_session	Track Claude Code sessions	✅ Working
close_session	Graceful shutdown	✅ Working

Development

Building

cargo build --release

Testing

cargo test
cargo clippy

Contributing

See CONTRIBUTING.md for guidelines.

Configuration

Environment variables:

• MOLECULAR_SESSION - Session identifier
• MOLECULAR_PROJECT - Project name
• MOLECULAR_VERBOSE - Enable debug logging
• MOLECULAR_CWD - Working directory

See src/config.rs for all configuration options.

Philosophy

"Code Boutique, Not Factory" - We prioritize quality over quantity, focusing on doing fewer things exceptionally well.

Version History

Current: v1.6.0 - Multi-Claude session tracking

See CHANGELOG.md for detailed history.

License

[To be determined]

---

Built with 🧬 by the Molecular team
"From molecular events to emergent intelligence"