Skip to content

QUICKSTART.md

Latest commit

 

History

History
171 lines (133 loc) · 3.92 KB

QUICKSTART.md

File metadata and controls

171 lines (133 loc) · 3.92 KB
Raw

Molecular Quick Start Guide

What is Molecular?

Molecular is a vector-powered MCP server that gives Claude persistent memory and semantic search capabilities across sessions. Think of it as Claude's long-term memory system.

Installation (5 minutes)

1. Build the Project

cd /home/u/code/mcp-servers/molecular
cargo build --release

2. Install Binaries

mkdir -p ~/.molecular/bin
cp target/release/mlclr ~/.molecular/bin/
cp target/release/duck ~/.molecular/bin/

3. Configure Claude Desktop

Add to ~/AppData/Roaming/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "molecular": {
      "command": "/home/u/.molecular/bin/duck"
    }
  }
}

4. Restart Claude Desktop

The molecular server will start automatically when Claude launches.

Essential MCP Tools

Core Tools (Use These Daily)

welcome

Get session info and orientation

What's the current molecular session status?

exec

Run commands with automatic event logging

Use exec to build the project

semantic_search

Find similar past solutions (currently 0% bug - see KNOWN_ISSUES.md)

Search for "error handling" in past sessions

guestbook

Leave notes for future Claude instances

Sign the guestbook: "Fixed the WebGPU shader bug!"

register_claude_session

Register your Claude Code session

Register my session as "shader-debugging" in project "webgpu-renderer"

How It Works

  1. Events → All development activities create events
  2. Ring Buffer → Events are buffered and classified by importance
  3. Embeddings → Events get 384-dimensional vector embeddings
  4. LanceDB → Vectors stored for semantic search
  5. Search → Find similar past events across all sessions

Current Status

✅ Working

  • Event capture and storage
  • Ring buffer with flood protection
  • Basic semantic search (finds results)
  • Session management tools
  • Command execution tracking

⚠️ Known Issues

  • Similarity scores show 0% (LanceDB bug)
  • Timestamps display as 1970-01-01
  • Projects show as "unknown"

See KNOWN_ISSUES.md for details and fixes.

Project Structure

molecular/
├── src/
│   ├── vector_molecular.rs  # Main MCP server
│   ├── vector_database.rs   # LanceDB integration
│   ├── embeddings.rs        # Vector embeddings
│   ├── ring_buffer.rs       # Event buffering
│   └── bin/
│       └── duck.rs          # Claude wrapper
├── tools/                   # Utilities
├── README.md               # Full documentation
├── QUICKSTART.md          # This file
├── KNOWN_ISSUES.md        # Bug tracking
└── SYSTEM_ARCHITECTURE.md # Technical details

Common Tasks

Check System Health

Show me the molecular session info

Run and Track Commands

Use exec to run: cargo test

Search Past Work

Search for "optimization" in molecular history

Debug Issues

What are the current known issues in molecular?

Environment Variables

  • MOLECULAR_SESSION - Override session ID
  • MOLECULAR_PROJECT - Set project name
  • MOLECULAR_VERBOSE - Enable verbose logging

Troubleshooting

Server Not Starting?

# Check if running
ps aux | grep mlclr

# Check logs
~/.molecular/bin/mlclr  # Run directly to see output

No Search Results?

  • Events need to be flushed from buffer (100ms delay)
  • Check welcome tool for event count
  • Try broader search terms

Need Help?

  • Read SYSTEM_ARCHITECTURE.md for technical details
  • Check KNOWN_ISSUES.md for current bugs
  • Look at CONTRIBUTING.md for development guidelines

Next Steps

  1. Sign the guestbook to establish presence
  2. Use exec for all commands to build history
  3. Try semantic search (even with 0% bug, it finds results)
  4. Read SYSTEM_ARCHITECTURE.md if you need deep technical understanding

"From molecular events to emergent intelligence" 🧬