yaade 0.1.0

Yaade (यादें) - Local MCP-compatible memory storage for AI agents with semantic search

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)

pip install yaade

Option 2: Install from Source

# 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 package manager if not present
• Install all dependencies
• Create a global yaade command

To uninstall the source installation:

./uninstall.sh

Quick Start

Launch the TUI

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

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

Model Management

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:

# 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:

{
  "mcpServers": {
    "yaade": {
      "command": "yaade",
      "args": ["serve"],
      "env": {
        "YAADE_LOG_LEVEL": "INFO"
      }
    }
  }
}

If installed from source:

{
  "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:

{
  "mcpServers": {
    "yaade": {
      "type": "stdio",
      "command": "yaade",
      "args": ["serve"],
      "env": {}
    }
  }
}

If installed from source:

{
  "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

Setup

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

Running Tests

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/:

# 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 file for details.

Acknowledgments

• Anthropic for the MCP specification
• ChromaDB for the vector database
• sentence-transformers for embeddings
• Textual for the TUI framework
• UV for package management