yaade 0.1.0
Yaade (यादें) - Local MCP-compatible memory storage for AI agents with semantic search
License: MIT
Requires Python: >=3.12
Keywords: ai, claude, embeddings, mcp, memory, vector-database

# Yaade - Memory Storage for AI Agents

**Yaade** (यादें) - Hindi for "memories" - is a local MCP-compatible server that provides centralized memory storage for AI tools including Claude Desktop, Claude Code, OpenCode, and other MCP-compatible clients.

## Features

- **Semantic Memory Storage**: Store and retrieve memories using vector embeddings
- **Intelligent Search**: Search memories by meaning, not just keywords
- **MCP Compatible**: Full Model Context Protocol (MCP) v2025-06-18 support
- **Local-First**: No cloud dependencies, all data stays on your machine
- **TUI Interface**: Beautiful terminal UI for memory management
- **Multiple Embedding Models**: Choose from 8 sentence-transformer models
- **Memory Cleanup**: Detect duplicates and consolidate related memories
- **Theme Support**: 3 built-in cyberpunk themes with live preview
- **Easy Integration**: Automated setup scripts for Claude Desktop, Claude Code, and OpenCode

## Installation

### Option 1: Install from PyPI (Recommended)

```bash
pip install yaade
```

### Option 2: Install from Source

```bash
# Clone the repository
git clone https://github.com/reyanshgupta/yaade.git
cd yaade

# Run the install script
./install.sh
```

The install script will:
- Check Python version (3.12+ required)
- Install [uv](https://docs.astral.sh/uv/) package manager if not present
- Install all dependencies
- Create a global `yaade` command

To uninstall the source installation:
```bash
./uninstall.sh
```

## Quick Start

### Launch the TUI

```bash
yaade
```

This opens the interactive terminal interface where you can:
- Manage memories (add, edit, delete, search)
- Configure MCP integration with AI clients
- Select embedding models
- Customize themes

### TUI Navigation

```
┌─────────────────────────────────────────┐
│               Yaade                     │
│        Memory Storage for AI            │
├─────────────────────────────────────────┤
│  [1] Memory Management                  │
│  [2] Setup                              │
│  [3] Settings                           │
│  [Q] Quit                               │
└─────────────────────────────────────────┘
```

**Keyboard shortcuts:**
- `1`, `2`, `3` - Navigate to menu items
- `j`/`k` or `↑`/`↓` - Move selection
- `Enter` - Select item
- `Ctrl+P` - Switch themes
- `Q` - Quit

### Memory Management

The Memory Management screen displays all stored memories in a table with:
- ID, content preview, type, and tags
- Statistics panel showing memory count, model, and storage size

**Operations:**
- `a` - Add new memory
- `e` - Edit selected memory
- `d` - Delete selected memory
- `r` - Refresh list

## CLI Commands

```bash
yaade                    # Launch the TUI (default)
yaade serve              # Run MCP server for Claude integration
yaade --version, -v      # Show version
yaade --help             # Show help
```

### Model Management

```bash
yaade download-model                     # Show help
yaade download-model list                # List all available models with cache status
yaade download-model download <model>    # Download a specific model
yaade download-model check <model>       # Check if model is cached
yaade download-model all                 # Download all supported models
yaade download-model all --force         # Force re-download all models
```

## MCP Integration

### Automated Setup (Recommended)

From the TUI, navigate to **Setup** to automatically configure:
- Claude Desktop (macOS/Windows)
- Claude Code (macOS/Windows)
- OpenCode (macOS/Windows)

Or run the setup scripts directly:

```bash
# Claude Desktop (macOS)
./setup/claude-desktop/setup-mcp-macos.sh

# Claude Code (macOS)
./setup/claude-code/setup-mcp-macos.sh

# OpenCode (macOS)
./setup/opencode/setup-mcp-macos.sh
```

### Manual Configuration

#### Claude Desktop

**Config location:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Roaming\Claude\claude_desktop_config.json`

**If installed via pip:**
```json
{
  "mcpServers": {
    "yaade": {
      "command": "yaade",
      "args": ["serve"],
      "env": {
        "YAADE_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

**If installed from source:**
```json
{
  "mcpServers": {
    "yaade": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/yaade", "yaade", "serve"],
      "env": {
        "YAADE_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

#### Claude Code

**Config location:** `~/.claude.json`

**If installed via pip:**
```json
{
  "mcpServers": {
    "yaade": {
      "type": "stdio",
      "command": "yaade",
      "args": ["serve"],
      "env": {}
    }
  }
}
```

**If installed from source:**
```json
{
  "mcpServers": {
    "yaade": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "yaade", "serve"],
      "cwd": "/path/to/yaade",
      "env": {}
    }
  }
}
```

### Using Memory with Claude

Once configured, interact naturally:

- **Store**: "Remember that I prefer TypeScript over JavaScript"
- **Search**: "What do you remember about my programming preferences?"
- **Check**: "Check the memory server health"

## Available MCP Tools

| Tool | Description |
|------|-------------|
| `add_memory` | Store new memory with semantic embedding |
| `search_memories` | Semantic search across memories |
| `get_memory` | Retrieve specific memory by ID |
| `delete_memory` | Remove memory from storage |
| `health_check` | Check server status and statistics |
| `analyze_memory_cleanup` | Find duplicate/similar memories (non-destructive) |
| `execute_memory_cleanup` | Execute cleanup with confirmation |

### Tool Parameters

**add_memory**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `content` | string | Yes | Memory content to store |
| `memory_type` | string | No | text, image, document, conversation, code |
| `source` | string | No | claude, chatgpt, cursor, browser, api, manual |
| `tags` | list | No | Categorization tags |
| `importance` | float | No | Score from 0.0 to 10.0 |
| `metadata` | dict | No | Additional metadata |

**search_memories**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query |
| `limit` | int | No | Max results (default: 10) |
| `filter_tags` | list | No | Filter by tags |

**analyze_memory_cleanup**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `similarity_threshold` | float | No | Duplicate detection threshold (default: 0.85) |
| `consolidation_threshold` | float | No | Consolidation threshold (default: 0.70) |

**execute_memory_cleanup**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `actions_to_execute` | list | Yes | exact_duplicates, near_duplicates, consolidation |
| `analysis_id` | string | No | Reference to previous analysis |
| `confirm_deletion` | bool | Yes | Must be True to proceed |

## Embedding Models

Yaade supports 8 sentence-transformer models. Select from the TUI Settings or set via environment variable.

| Model ID | Dimensions | Size | Speed | Quality | Best For |
|----------|------------|------|-------|---------|----------|
| `all-MiniLM-L6-v2` (default) | 384 | 80 MB | ★★★ | ★★★ | General use, limited hardware |
| `all-MiniLM-L12-v2` | 384 | 120 MB | ★★★ | ★★★★ | Better accuracy, good performance |
| `all-mpnet-base-v2` | 768 | 420 MB | ★ | ★★★★★ | Maximum accuracy (4GB+ RAM) |
| `paraphrase-MiniLM-L6-v2` | 384 | 80 MB | ★★★ | ★★★ | Finding similar content |
| `multi-qa-MiniLM-L6-cos-v1` | 384 | 80 MB | ★★★ | ★★★ | Q&A and information retrieval |
| `bge-small-en-v1.5` | 384 | 130 MB | ★★★ | ★★★★ | High quality, good efficiency |
| `bge-base-en-v1.5` | 768 | 440 MB | ★★ | ★★★★★ | Best-in-class accuracy |

## Configuration

Configuration via environment variables or `.env` file in the project directory.

| Variable | Default | Description |
|----------|---------|-------------|
| `YAADE_DATA_DIR` | `.yaade` | Base directory for data storage |
| `YAADE_EMBEDDING_MODEL_NAME` | `all-MiniLM-L6-v2` | Embedding model to use |
| `YAADE_EMBEDDING_BATCH_SIZE` | `32` | Batch size for embedding generation |
| `YAADE_EMBEDDING_MAX_SEQ_LENGTH` | `512` | Max tokens per input |
| `YAADE_HOST` | `localhost` | Server host |
| `YAADE_PORT` | `8000` | Server port |
| `YAADE_LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |
| `YAADE_THEME` | `cyberpunk` | TUI theme (cyberpunk, cyberpunk_soft, neon_nights) |

### Data Storage

- **Default location**: `.yaade/`
- **Vector database**: `.yaade/chroma/`
- All data stored locally. No external services or telemetry.

## Themes

Three built-in themes available via Settings or `Ctrl+P`:

| Theme | Description |
|-------|-------------|
| **Cyberpunk** (default) | Hot magenta + electric cyan, high contrast |
| **Cyberpunk Soft** | Subdued version for extended use |
| **Neon Nights** | Purple + teal focus |

## Architecture

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Clients    │    │     Yaade        │    │  Storage        │
│                 │    │                  │    │                 │
│  Claude Desktop │◄──►│  FastMCP Server  │◄──►│  ChromaDB       │
│  Claude Code    │    │  MCP Tools       │    │  Embeddings     │
│  OpenCode       │    │  Memory Service  │    │  Metadata       │
└─────────────────┘    └──────────────────┘    └─────────────────┘
```

### Technology Stack

- **Protocol**: MCP (Model Context Protocol) with stdio transport
- **Vector Database**: ChromaDB for semantic search
- **Embeddings**: sentence-transformers for local text encoding
- **Configuration**: Pydantic v2 with environment variable support
- **TUI**: Textual framework for terminal interface
- **Package Management**: pip or UV

## Project Structure

```
yaade/
├── app/
│   ├── main.py              # FastMCP server entry point
│   ├── cli.py               # CLI entry point
│   ├── models/              # Pydantic data models
│   │   ├── config.py        # Server configuration
│   │   ├── memory.py        # Memory models
│   │   └── embedding_models.py  # Model definitions
│   ├── storage/             # Storage backends
│   │   └── vector_store.py  # ChromaDB integration
│   ├── search/              # Embedding services
│   │   ├── embeddings.py    # Sentence-transformer service
│   │   └── model_downloader.py  # Model management
│   ├── services/            # Business logic
│   │   └── memory_cleanup.py    # Duplicate detection
│   └── tui/                 # Terminal UI
│       ├── app.py           # Main TUI application
│       ├── themes.py        # Color themes
│       ├── screens/         # UI screens
│       ├── settings/        # Settings screens
│       └── widgets/         # Custom components
├── setup/                   # Client setup scripts
│   ├── claude-desktop/
│   ├── claude-code/
│   └── opencode/
├── tests/                   # Test suite
├── .agents/                 # AI agent configurations
│   ├── AGENTS.md            # Central template
│   ├── CLAUDE.md            # Claude Code
│   ├── .cursorrules         # Cursor
│   └── ...                  # Other AI tools
├── install.sh               # Installation script
├── uninstall.sh             # Uninstallation script
└── pyproject.toml           # Project configuration
```

## Development

### Prerequisites

- Python 3.12+
- [UV package manager](https://docs.astral.sh/uv/getting-started/installation/)

### Setup

```bash
git clone https://github.com/reyanshgupta/yaade.git
cd yaade
uv sync
```

### Running Tests

```bash
uv run pytest
uv run pytest --cov=app  # With coverage
```

### AI Agent Setup

For contributors using AI coding assistants, configuration files are available in `.agents/`:

```bash
# Setup symlinks for common tools
./.agents/setup.sh

# Or manually symlink specific tools
ln -sf .agents/CLAUDE.md CLAUDE.md
ln -sf .agents/.cursorrules .cursorrules
```

Supported tools: Claude Code, Cursor, OpenCode, Windsurf, Cody, Aider, Antigravity, Continue

### Contributing

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

## Troubleshooting

### TUI won't start
- Ensure Python 3.12+ is installed
- If installed via pip: `pip install --upgrade yaade`
- If installed from source: run `./install.sh` again

### Claude not connecting
- Verify config file path is correct for your OS
- Ensure `command` matches your installation method
- Restart Claude Desktop/Code after config changes
- Check logs: set `YAADE_LOG_LEVEL=DEBUG`

### Embedding model issues
- Download model manually: `yaade download-model download all-MiniLM-L6-v2`
- Check cache: `yaade download-model check all-MiniLM-L6-v2`
- Ensure sufficient disk space (~80-440 MB per model)

### Import errors
- pip install: `pip install --upgrade yaade`
- Source install: `uv sync` in project directory

## Privacy & Security

- **Local-First**: All processing happens on your machine
- **No Telemetry**: ChromaDB telemetry explicitly disabled
- **No External Calls**: Embeddings generated locally
- **Full Control**: Configure data storage location

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [Anthropic](https://www.anthropic.com) for the MCP specification
- [ChromaDB](https://www.trychroma.com/) for the vector database
- [sentence-transformers](https://www.sbert.net/) for embeddings
- [Textual](https://textual.textualize.io/) for the TUI framework
- [UV](https://docs.astral.sh/uv/) for package management