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
yaadecommand
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 itemsj/kor↑/↓- Move selectionEnter- Select itemCtrl+P- Switch themesQ- 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 memorye- Edit selected memoryd- Delete selected memoryr- 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
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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.shagain
Claude not connecting
- Verify config file path is correct for your OS
- Ensure
commandmatches 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 syncin 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
Metadata
Release files for yaade 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| yaade-0.1.0.tar.gz | 206.2 kB | With provenance | Details for yaade-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| yaade-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for yaade-0.1.0-py3-none-any.whl |
Total release size: 275.2 kB
Release files / yaade-0.1.0.tar.gz
| Download URL | yaade-0.1.0.tar.gz |
|---|---|
| Size | 206.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
202f267a9f137e5193cc88730c4228e292ac5002131d06a3097128a5c69e6254
|
|
BLAKE2b-256 checksum How to use checksums |
64e7a021319330f0f2edf613abda3d96a01112f41e1d0dd65473ff3d6581e89c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 1, 2026.
Transparency logRelease files / yaade-0.1.0-py3-none-any.whl
| Download URL | yaade-0.1.0-py3-none-any.whl |
|---|---|
| Size | 69.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
865473770feb9820ff00f95ec2c47c55ab53cef219bcb48c66b76998ad97329d
|
|
BLAKE2b-256 checksum How to use checksums |
0c499a28bd0d3caed5ef1b1e18bd5b40ea9c1cff9eac0e34f6bb394ccbe6e175
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 1, 2026.
Transparency logSecurity for yaade 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for yaade-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Feb 1, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.