{"id":"506af670-2c08-4002-9071-fa0e29d641eb","slug":"ragy","kind":"mcp","name":"ragy","summary":"Temporal memory for your AI agents, financial research, and knowledge workflows.","owner":"Arseni1919","repoUrl":"https://github.com/Arseni1919/ragy","license":"MIT","licenseTier":"permissive","trust":"community","stars":5,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-04-01T19:34:35.000Z","addedAt":"2026-10-21T08:35:59.775Z","logoUrl":"https://avatars.githubusercontent.com/u/55444116?u=081abd6b5f12226622e26ea0ff9d2c6744b32990&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["databases","search","memory-knowledge"],"tags":["rag","ai-agents","apscheduler","chroma","chromadb","time-series","vector-database","temporal-rag"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T12:48:06.086Z","sample":false,"url":"https://conduits.dev/tools/ragy","language":"Python","transports":["stdio"],"install":{"pypi":"ragyapp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<div align=\"center\">\n\n![RAGY](docs/screenshots/banner.png)\n\n[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![GitHub](https://img.shields.io/badge/github-Arseni1919%2Fragy-blue)](https://github.com/Arseni1919/ragy)\n\n**Most RAG systems are stateless. Every query re-fetches, re-embeds, re-ranks.**\n\nragy is different: index any topic across a full time window *once*, then use semantic similarity to retrieve the right days — not all days. Temporal memory for your AI agents, financial research, and knowledge workflows.\n\n</div>\n\n---\n\n## Why ragy?\n\nStandard RAG retrieves documents. ragy retrieves *moments in time*.\n\nYou define a query (e.g. `\"Fed interest rate signals\"`) and a time window (e.g. 365 days). ragy fetches and embeds every day's content once, stores it in a local vector database, and lets you instantly answer: **\"which days in the past year most resembled this?\"** — ranked by cosine similarity, plotted on a timeline.\n\n**Key difference from other RAG projects:**\n\n| | Standard RAG | ragy |\n|---|---|---|\n| Data model | Documents | Days in time |\n| Re-fetch per query? | Yes | No — indexed once |\n| Time-aware? | No | Yes — date is a first-class dimension |\n| Visualization | None | Similarity timeline (`xray`) |\n| Scheduling | Manual | Built-in APScheduler |\n| Agent integration | Varies | Native MCP server |\n\n---\n\n## What You Can Build\n\n**🌐 Enterprise data collection** — Use Bright Data for large-scale web scraping, structured data extraction, and professional-grade data collection. Index competitive intelligence, market research, or any web data with advanced scraping capabilities.\n\n**📈 Financial research** — Index a year of market news with yfinance, query `\"Fed pivot signals\"`, get back the 10 most semantically similar trading days with similarity scores and related tickers on a timeline. Track multiple stocks with scheduled daily updates — no API costs.\n\n**🔍 Competitive intelligence** — Schedule daily indexing of topics with Bright Data or Tavily. Ask \"what weeks had the most activity around X?\" Retrieve content ranked by relevance, not recency.\n\n**🤖 AI agent long-term memory** — Give your Claude / LangGraph / n8n agent a persistent temporal knowledge base via MCP. No search API call on every turn — just semantic retrieval from your local index.\n\n**💹 Stock monitoring dashboard** — Create collections for each stock you track (AAPL, NVDA, TSLA) using yfinance source. Query across time to find similar market conditions, earnings patterns, or news sentiment shifts.\n\n---\n\n## See It in Action\n\n### The `xray` command — your temporal similarity radar\n\n![Xray Timeline](docs/screenshots/xray-timeline.png)\n\n```bash\nragy> xray\nCollection: Stock_JNJ\nQuery: high price expected\nTop K: 10\n```\n\nReturns a ranked list of dates with similarity scores, plotted on a timeline. This is the fastest way to understand *when* your topic was most relevant.\n\n### Financial Data Search\n\n```bash\nragy> search_yfin\nSearch query: tesla stock\nMax results: 3\n```\n\nReturns financial news articles with related ticker symbols (e.g., TSLA), publisher information, and direct links to Yahoo Finance. Perfect for quick market research or monitoring specific stocks.\n\n---\n\n## Quick Start\n\n### One-command install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Arseni1919/ragy/main/install.sh | bash\n```\n\n### Manual setup\n\n```bash\ngit clone https://github.com/Arseni1919/ragy.git\ncd ragy\nuv sync\n```\n\nCreate a `.env` file — API keys optional depending on data source:\n\n```bash\n# For Bright Data (advanced scraping)\nBRIGHT_DATA_API_KEY=\"your-key-here\"\nBRIGHT_DATA_ZONE=\"your-zone\"\n\n# For Tavily (general web search)\nTAVILY_API_KEY=\"your-key-here\"   # Get free at tavily.com\n\n# Note: yfinance (financial data) needs no API key\n```\n\nStart the stack:\n\n```bash\n# Terminal 1 — API\nuv run uvicorn ragy_api.main:app --reload\n\n# Terminal 2 — CLI\nuv run ragy\n```\n\n**First run note:** embedding models (~80MB) download automatically in the background. First query may take 10–30 seconds; subsequent runs are instant.\n\n### Docker Quick Start\n\nThe fastest way to run RAGY:\n\n```bash\ngit clone https://github.com/Arseni1919/ragy.git\ncd ragy\ncp .env.example .env\n# Add your Tavily API key to .env\ndocker-compose up -d\n```\n\nAccess at http://localhost:8000/docs\n\nSee [README-DOCKER.md](README-DOCKER.md) for complete Docker documentation.\n\n---\n\n## Core Workflow\n\n### 1. Index a topic over time\n\n```bash\nragy> create_index\nQuery: artificial intelligence news\nCollection name: ai_2024\nNumber of days: 365\n```\n\nThis fetches, embeds, and stores one entry per day for the past 365 days. Run once. Query forever.\n\n### 2. Retrieve semantically relevant days\n\n```bash\nragy> extract\nCollection: ai_2024\nQuery: transformer architecture improvements\nTop K: 5\n```\n\nReturns the 5 days most semantically similar to your query — not keyword matches, not most recent, but most *relevant*.\n\n### 3. Visualize similarity over time\n\n```bash\nragy> xray\nCollection: ai_2024\nQuery: open source model releases\nTop K: 10\n```\n\nPlots similarity scores as a timeline. Instantly see if your topic had a spike, a gradual trend, or scattered activity.\n\n### 4. Schedule automatic updates\n\n```bash\nragy> create_job\nQuery: tech news\nCollection name: daily_tech\nData source: bright_data   # or 'tavily' or 'yfinance'\nInterval type: day\nInterval amount: 1\n```\n\n**Example with yfinance for financial monitoring:**\n\n```bash\nragy> create_job\nQuery: nvidia stock news\nCollection name: nvidia_tracker\nData source: yfinance       # financial news + quotes with tickers\nInterval type: day\nInterval amount: 1\n```\n\nragy updates your collection every day at the scheduled hour. Your index stays current without manual work. Choose `bright_data` for advanced scraping, `tavily` for general web search, or `yfinance` for financial data (stocks, news, quotes) — no API key needed for yfinance.\n\n---\n\n## Data Sources\n\nragy supports multiple data sources for indexing and search. Choose based on your use case:\n\n### Bright Data (Advanced Web Scraping)\n- **Best for:** Structured data extraction, large-scale web scraping, alternative search\n- **Requires:** API key and zone credentials\n- **Content:** Web pages, structured data, search results\n- **Use when:** Need more control over scraping, bypassing restrictions, or professional-grade data collection\n\n### Tavily (General Web Search)\n- **Best for:** News, articles, general web content, research\n- **Requires:** API key (free tier available at [tavily.com](https://tavily.com))\n- **Content:** Web pages, news articles, blog posts\n- **Use when:** Tracking general topics, news, or web content\n\n### yfinance (Financial Data)\n- **Best for:** Stock market news, financial data, company information\n- **Requires:** No API key needed (uses Yahoo Finance)\n- **Content:** Financial news articles with related tickers, stock quotes, company data\n- **Use when:** Monitoring stocks, tracking financial news, building investment research tools\n\n**Example comparison:**\n\n```bash\n# Advanced scraping → use Bright Data\nragy> create_job\nQuery: competitor analysis\nData source: bright_data  # Advanced web scraping capabilities\n\n# General tech news → use Tavily\nragy> create_job\nQuery: artificial intelligence breakthroughs\nData source: tavily\n\n# Stock-specific news → use yfinance\nragy> create_job\nQuery: nvidia earnings\nData source: yfinance    # Returns news + NVDA ticker info\n```\n\n---\n\n## CLI Reference\n\n21 commands across 5 categories:\n\n### Index Management\n| Command | Description |\n|---------|-------------|\n| `create_index` | Build temporal vector index for a query + time window |\n| `delete_index` | Remove a collection |\n| `upload_csv` | Import from CSV (`date`, `content` columns required) |\n\n### Query & Extract\n| Command | Description |\n|---------|-------------|\n| `extract` | Retrieve top-K days by semantic similarity |\n| `search` | Live web search via Tavily |\n| `search_yfin` | Search financial data via yfinance (stocks, news, quotes) |\n\n### Inspect\n| Command | Description |\n|---------|-------------|\n| `list` | All collections |\n| `status` | Document count for a collection |\n| `sample` | Inspect a single document by index |\n| `head_index` / `tail_index` | Preview first / last 5 documents |\n| `stats` | Full database overview |\n| `xray` | Similarity timeline plot |\n\n### Scheduling\n| Command | Description |\n|---------|-------------|\n| `jobs` | List scheduled jobs |\n| `create_job` | Set up recurring index updates |\n| `delete_job` | Remove a job |\n\n### System\n| Command | Description |\n|---------|-------------|\n| `health` | API health check |\n| `info` | Embedding model details |\n| `change_emb` | Swap embedding model |\n| `help` / `exit` / `shutdown` | Utility commands |\n\n---\n\n## REST API\n\n19 endpoints. Full Swagger UI at `http://localhost:8000/docs`.\n\n| Category | Key Endpoints |\n|----------|--------------|\n| **Index** | `POST /api/v1/index/create` (SSE streaming) |\n| **Extract** | `POST /api/v1/extract/data` · `POST /api/v1/extract/all` |\n| **Database** | `GET /api/v1/database/stats` · `GET /api/v1/database/collection/{name}/distribution` |\n| **Search** | `POST /api/v1/search/web` (Tavily) · `POST /api/v1/search/yfinance` (financial data) |\n| **Scheduler** | `POST /api/v1/system/scheduler/jobs/create` |\n| **Upload** | `POST /api/v1/upload/csv` |\n\n---\n\n## MCP Integration\n\nragy ships a native MCP server, letting Claude Desktop (and any MCP-compatible agent) query your temporal knowledge base directly.\n\n### Available tools\n\n| Tool | Description |\n|------|-------------|\n| `list_collections` | See all indexed topics |\n| `extract_all` | Retrieve relevant days by semantic similarity |\n| `search_web` | Live web search via Tavily |\n| `get_database_stats` | Database overview |\n| `health_check` | API status |\n\n### Setup\n\n**1. Start the API:**\n```bash\nuv run uvicorn ragy_api.main:app --host 0.0.0.0 --port 8000\n```\n\n**2. Add to `claude_desktop_config.json`:**\n\nmacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"ragy\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"ragy-mcp\"],\n      \"cwd\": \"/absolute/path/to/ragy\"\n    }\n  }\n}\n```\n\n**3. Ask Claude:**\n- *\"Which days in my ai_2024 collection are most similar to 'GPT-4 level breakthroughs'?\"*\n- *\"Show me database stats\"*\n- *\"Search the web for recent LLM benchmark results\"*\n\n---\n\n## Architecture\n\n```mermaid\ngraph TD\n    D[Search Engines<br/>Bright Data / Tavily / yfinance] -->|fetch + index| B\n    C[Embeddings<br/>HuggingFace / Ollama] -->|encode| B\n    A[zvec<br/>local vector store] <-->|store / retrieve| B[FastAPI Backend]\n    B --> E[CLI Client]\n    B --> F[MCP Server]\n    B --> G[HTTP / REST]\n    H[APScheduler] -->|daily update| B\n\n    style B fill:#0066FF,color:#fff\n    style E fill:#00DDFF,color:#000\n    style F fill:#00DDFF,color:#000\n```\n\n**Data flows:**\n1. **Index**: Bright Data/Tavily/yfinance → FastAPI → Embeddings → zvec (runs once)\n2. **Query**: CLI / MCP / HTTP → FastAPI → Embeddings → zvec → ranked results\n3. **Schedule**: APScheduler → FastAPI → Bright Data/Tavily/yfinance → zvec (runs daily)\n\nAll processing is local. Only search API calls (Bright Data, Tavily, yfinance) go to the network.\n\n---\n\n## Configuration\n\n```bash\n# Required (only for Tavily search)\nTAVILY_API_KEY=\"...\"           # Get free key at tavily.com\n                               # Note: yfinance search works without any API key\n\n# Optional — sensible defaults shown\nHF_EMB_MODEL=\"google/embeddinggemma-300m\"\nDB_PATH=\"./ragy_db\"\nDB_PROVIDER=\"zvec\"             # Vector database: \"zvec\" (default) or \"chromadb\"\nRAGY_MAX_CONCURRENT=10\nAPI_HOST=\"0.0.0.0\"\nAPI_PORT=8000\nSCHEDULER_ENABLED=true\nSCHEDULER_HOUR=2               # Daily update hour (UTC)\nSCHEDULER_TIMEZONE=\"UTC\"\nJOBS_DB_PATH=\"./ragy_jobs.db\"\n\n# Optional — for Bright Data integration\nBRIGHT_DATA_API_KEY=\"...\"\nBRIGHT_DATA_ZONE=\"...\"\n```\n\n**Data Source Selection:**\n- Use `bright_data` source for advanced scraping: requires BRIGHT_DATA_API_KEY and BRIGHT_DATA_ZONE in `.env`\n- Use `tavily` source when creating jobs: requires TAVILY_API_KEY in `.env`\n- Use `yfinance` source for financial data: no API key needed, works out of the box\n\n**Vector Database:**\n- **zvec** (default): High-performance C++ vector database from Alibaba, optimized for speed and memory\n- **chromadb**: Python-based alternative, can be switched via `DB_PROVIDER=\"chromadb\"` in `.env`\n\nTo use Ollama embeddings instead of HuggingFace:\n```bash\nragy> change_emb\n# Select: ollama\n# Model: nomic-embed-text\n```\n\n---\n\n## CSV Upload Format\n\nBring your own data — any time-series corpus works:\n\n```csv\ndate,content,title,url\n2024-01-15,Full text of article or document...,Optional title,https://...\n2024-01-16,...\n```\n\n`date` and `content` are required. Any additional columns are stored as metadata and returned in query results.\n\n---\n\n## Project Structure\n\n```\nragy/\n├── ragy_api/          # FastAPI backend (19 endpoints)\n│   ├── services/      # Business logic\n│   └── routers/       # Route handlers\n├── ragy_cli/          # Terminal interface (21 commands)\n├── ragy_mcp/          # MCP server (5 tools)\n├── conn_db/           # Database factory (zvec/chromadb)\n├── conn_zvec/         # zvec connector (default)\n├── conn_emb_hugging_face/\n├── conn_emb_ollama/\n├── conn_tavily/       # Tavily search API\n├── conn_bright_data/  # Bright Data scraping API\n├── sample_data/       # Sample datasets to try immediately\n└── pyproject.toml\n```\n\n---\n\n## Contributing\n\n```bash\ngit fork https://github.com/Arseni1919/ragy\ngit checkout -b feature/your-feature\nuv sync\n# make changes\ngit commit -m \"feat: your feature\"\ngit push origin feature/your-feature\n# open PR\n```\n\nSee [CLAUDE.md](CLAUDE.md) for code conventions, testing guidelines, and development workflows.\n\n---\n\n## Acknowledgments\n\n- [zvec](https://github.com/alibaba/zvec) — high-performance C++ vector database\n- [Bright Data](https://brightdata.com/) — web scraping and data collection\n- [Tavily](https://tavily.com/) — web search API\n- [yfinance](https://github.com/ranaroussi/yfinance) — Yahoo Finance data access\n- [Sentence Transformers](https://www.sbert.net/) — embedding models\n- [FastAPI](https://fastapi.tiangolo.com/) — web framework\n- [Rich](https://rich.readthedocs.io/) — terminal formatting\n\n---\n\n<div align=\"center\">\n\nMIT License · [Issues](https://github.com/Arseni1919/ragy/issues) · [Discussions](https://github.com/Arseni1919/ragy/discussions)\n\n**Made with ❤️ by Arseniy**\n\n</div>\n"}