Skip to main content

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

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

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

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

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)

Source distribution for yaade 0.1.0
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)

Table of built distributions (wheels) for yaade 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page