[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80853":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":21,"hasPages":21,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":15,"starSnapshotCount":15,"syncStatus":27,"lastSyncTime":28,"discoverSource":29},80853,"QueryMind","Tangxihong0922\u002FQueryMind","Tangxihong0922","🤖QueryMind is an agent framework for building LLM-powered agents specialized in Text2SQL📊 tasks with agentic retrieval capabilities🔄 and enterprise-grade security🔒.",null,"Python",42,6,35,1,0,5,7,15,56.74,"MIT License",false,"main",[],"2026-06-12 04:01:30","# QueryMind: Build SQL Agents for Real-World Business Databases\n\nQueryMind is an agent framework for building LLM-powered agents specialized in real-world Text2SQL Tasks with agentic retrieval capabilities and enterprise-grade security.\n\n[![Python](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.10%2B-blue.svg)](https:\u002F\u002Fpython.org)\n[![README_zh](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FREADME-简体中文-0ea5e9.svg)](README_zh.md)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-green.svg)](LICENSE)\n\nhttps:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fe87fc532-ef82-4765-96a7-e693924de5c7\n\n\u003Ctable>\n  \u003Ctr>\n    \u003Ctd align=\"center\" valign=\"top\" width=\"33%\">\n      \u003Cimg src=\"docs\u002Ffigures\u002Fchat-ui\u002Fchat-panel.png\" alt=\"chat-panel\" width=\"240\" \u002F>\n      \u003Cbr \u002F>\u003Csub>Chat panel\u003C\u002Fsub>\n    \u003C\u002Ftd>\n    \u003Ctd align=\"center\" valign=\"top\" width=\"33%\">\n      \u003Cimg src=\"docs\u002Ffigures\u002Fchat-ui\u002Fschema-management.png\" alt=\"schema-management\" width=\"240\" \u002F>\n      \u003Cbr \u002F>\u003Csub>Schema management\u003C\u002Fsub>\n    \u003C\u002Ftd>\n    \u003Ctd align=\"center\" valign=\"top\" width=\"33%\">\n      \u003Cimg src=\"docs\u002Ffigures\u002Fchat-ui\u002Fuser-query.png\" alt=\"user-query\" width=\"240\" \u002F>\n      \u003Cbr \u002F>\u003Csub>User query\u003C\u002Fsub>\n    \u003C\u002Ftd>\n  \u003C\u002Ftr>\n  \u003Ctr>\n    \u003Ctd align=\"center\" valign=\"top\" width=\"33%\">\n      \u003Cimg src=\"docs\u002Ffigures\u002Fchat-ui\u002Fquery-results.png\" alt=\"query-results\" width=\"240\" \u002F>\n      \u003Cbr \u002F>\u003Csub>Query results\u003C\u002Fsub>\n    \u003C\u002Ftd>\n    \u003Ctd align=\"center\" valign=\"top\" width=\"33%\">\n      \u003Cimg src=\"docs\u002Ffigures\u002Fchat-ui\u002Fsummary.png\" alt=\"summary\" width=\"240\" \u002F>\n      \u003Cbr \u002F>\u003Csub>Summary\u003C\u002Fsub>\n    \u003C\u002Ftd>\n    \u003Ctd align=\"center\" valign=\"top\" width=\"33%\">\n      \u003Cimg src=\"docs\u002Ffigures\u002Fchat-ui\u002Fbar-chart.png\" alt=\"bar-chart\" width=\"240\" \u002F>\n      \u003Cbr \u002F>\u003Csub>Data Visualization\u003C\u002Fsub>\n    \u003C\u002Ftd>\n  \u003C\u002Ftr>\n\u003C\u002Ftable>\n\n---\n\n## 🌟 Core Features\n\n| Feature | Description |\n|---------|-------------|\n| **🗄️Multi-layer memory planes** | conversation storage, agent memory, and schema memory are independent, which keeps history, retrieval, and schema knowledge from bleeding into each other. |\n| **🎛️4 Schema Memory Search Modes** | hybrid \u002F vector \u002F graph \u002F expand - 4 modes allow the agent choose suitable schema retrieval strategy for each query through agentic decision-making. |\n| **🧮Schema Management** | UI pages and commands make business database metadata easier to maintain, update, manually refine, and enrich with AI, keeping the agent grounded in real-world business data. |\n| **🔐SQL safety and RLS** | group-aware tool access and pre-execution SQL governance protect business databases with row-level security, injection detection, and query complexity controls. |\n| **🛠️Integration flexibility** | QueryMind works with OpenAI-compatible, Anthropic, and vLLM model backends, plus PostgreSQL, SQLite, and Neo4j-backed storage and data integrations. |\n| **🗒️Operational visibility** | metrics, audit logs, and evaluation tools make QueryMind runs easier to monitor, inspect, and reproduce. |\n\nWhen the loop runs, QueryMind can stream progress updates, schema results, SQL results, charts, cards, and follow-up actions back to the frontend instead of returning plain text only.\n\n\n## 🏗️ What is New in QueryMind compared to Vanna 2.0\n\n💡QueryMind is inspired by [Vanna's agent framework](https:\u002F\u002Fgithub.com\u002Fvanna-ai\u002Fvanna) and adapts Vanna's webcomponents into a customized demo web experience.\n\nIt builds on that foundation with differences in runtime structure, governance, memory, and business database integration compared to Vanna 2.0.\n\n- **Schema governance** - schema governance standardizes schema retrieval traces, tracks discovered database context, and surfaces lock \u002F recap state as runtime notices while keeping the agent grounded in the right business schema.\n- **SQL governance** - SQL governance standardizes SQL writing patterns, feeds execution feedback into the next reasoning turn, and surfaces anchor \u002F freeze \u002F recap state as runtime notices to help the agent recover from SQL semantic false-negative traps.\n- **Two memory planes** - agent memory and schema memory serve different roles: agent memory captures reusable tool-use experience, while schema memory grounds SQL generation with Neo4j + Mem0 hybrid retrieval over database knowledge.\n- **Schema management** - schema management panel and deterministic slash commands serves as the supporting infrastructure for schema memory and schema retrieval tool, grounding the agent in real-world business databases before the normal LLM\u002Ftool loop begins.\n\n### 📝 Changelog\n\u003Cdetails>\n\u003Csummary> \u003Cb>🔥 2026-05-11\u003C\u002Fb> \u003C\u002Fsummary>\n\n- Unified QueryMind's context assembly around a stable system prompt, message-side runtime notices, and tool-result metadata.\n- Moved dynamic schema lock, schema summary, SQL anchor \u002F freeze \u002F recap, and memory advisory content out of the system prompt path.\n- Kept schema_retrieve visibility on the request-time filter path instead of mutating the tool registry.\n- Reworked runtime notices so dynamic notices are appended at the tail, while short visible signals stay in the notice and finer-grained detail lives in metadata.\n- Aligned the detail-expression profile tags (`case_when`, `null_handling`, `comparison`, `distinct`) with the existing prompt guidance, and updated the prompt-chain \u002F agent-loop \u002F governance docs plus tests to validate tail-appended notices and metadata snapshots.\n- Added a structural rewrite lane for aggregation \u002F rollup \u002F multi-CTE SQL turns so local repair stays focused on window \u002F join \u002F filtering cases.\n- Added detail-family guardrails for `case_when`, `null_handling`, `comparison`, and `distinct` so projection-preserving turns stay conservative.\n- On the evaluation test set, SQL accuracy stayed in the 66%-72% range with no regression, and the input cache hit rate improved from 44.28% to 69.35%.\n\u003C\u002Fdetails>\n\n## 🔄 QueryMind's Agent Loop\n![QueryMind agent loop](docs\u002Ffigures\u002Fcomponents\u002Fagent-loop.png)\n\n## 🧠 How It Works\n\n```mermaid\nsequenceDiagram\n    participant U as User\n    participant UI as QueryMind Chat UI\n    participant API as FastAPI Server\n    participant A as Agent\n    participant W as Workflows and Governance\n    participant T as Tool Registry\n    participant M as Memory and Storage\n\n    U->>UI: Ask a SQL question\n    UI->>API: POST \u002Fapi\u002Fquerymind\u002Fv1\u002Fchat_sse\n    API->>A: Resolve RequestContext and User\n    A->>W: Try \u002Finit_schema or \u002Fschema_* first\n    alt Workflow handled\n        W-->>UI: Stream rich UI components\n    else Continue agent loop\n        A->>T: Validate and execute tools\n        T->>M: Read\u002Fwrite memory, schema knowledge, and history\n        T-->>A: Results, charts, and artifacts\n        A-->>UI: Stream response chunks\n    end\n```\n\n## Get Started\n\nQueryMind provides a bundled demo agent for quickly trying its end-to-end capabilities, with the backend, demo frontend, memory, governance, and evaluation components already wired together.\n\nThe sample agent is assembled like this:\n\n```python\nfrom QueryMind import (\n    Agent,\n    AgentConfig,\n    CompositeLlmContextEnhancer,\n    CompositeWorkflowHandler,\n    ExponentialBackoffStrategy,\n    Neo4jMem0SchemaManagementService,\n    Neo4jMem0SchemaMemory,\n    PrometheusObservabilityProvider,\n)\nfrom QueryMind.core.agent import build_schema_governance_stack, build_sql_governance_stack\nfrom QueryMind.core.enricher import SchemaRetrieveContextEnricher\nfrom QueryMind.integrations.agentmemory import Mem0AgentMemory, create_config_from_env\nfrom QueryMind.integrations.auditlogger import PostgresAuditLogger\nfrom QueryMind.integrations.llmservice import OpenAILlmService\nfrom QueryMind.integrations.local import FileSystemConversationStore\nfrom QueryMind.integrations.schemamemory import Mem0VectorConfig, Neo4jConfig\nfrom QueryMind.rls_registry import RLSToolRegistry\n\nschema_governance = build_schema_governance_stack()\nsql_governance = build_sql_governance_stack()\n\nagent = Agent(\n    llm_service=OpenAILlmService(...),\n    tool_registry=RLSToolRegistry(audit_logger=PostgresAuditLogger(...)),\n    user_resolver=...,\n    agent_memory=Mem0AgentMemory(config=create_config_from_env()),\n    conversation_store=FileSystemConversationStore(...),\n    config=AgentConfig(...),\n    workflow_handler=CompositeWorkflowHandler([...]),\n    schema_memory=Neo4jMem0SchemaMemory(\n        neo4j_config=Neo4jConfig.from_env(),\n        mem0_config=Mem0VectorConfig.from_env(),\n    ),\n    schema_management_service=Neo4jMem0SchemaManagementService(...),\n    hooks=[schema_governance.hook, sql_governance.hook],\n    llm_middlewares=[schema_governance.middleware, sql_governance.middleware],\n    llm_context_enhancer=CompositeLlmContextEnhancer([...]),\n    context_enrichers=[SchemaRetrieveContextEnricher(...)],\n    error_recovery_strategy=ExponentialBackoffStrategy(),\n    observability_provider=PrometheusObservabilityProvider(),\n)\n```\n\n### Prerequisites\n\n- QueryMind Python SDK: see [0. QueryMind Python SDK](docs\u002Fen\u002Fsupport\u002Fprerequisite.md#querymind-python-sdk).\n- PostgreSQL & PgVector: see [1. PostgreSQL & PgVector](docs\u002Fen\u002Fsupport\u002Fprerequisite.md#postgresql-pgvector).\n- AdventureWorks: see [2. AdventureWorks](docs\u002Fen\u002Fsupport\u002Fprerequisite.md#adventureworks).\n- Environment Variables Configuration: see [3. Environment Variables Configuration](docs\u002Fen\u002Fsupport\u002Fprerequisite.md#environment-variables-configuration).\n\nThe deployment guide also covers Neo4j, PostgreSQL audit logging, and the webcomponent build that the demo launcher needs.\n\n### Dependencies Installation\n\n```bash\nuv sync\ncd frontends\u002Fwebcomponent\nnpm install\nnpm run build\n```\n\nIf you prefer editable installs, `pip install -e .` works as a fallback.\n\n### Use `querymind` to start the project\n\n```bash\nquerymind agent-only\nquerymind web-only\nquerymind demo\n```\n\n- `agent-only`: start the backend agent only.\n- `web-only`: start the demo frontend only.\n- `demo`: start both services and open the demo page automatically.\n\nThe same modes are exposed through the `querymind` console script and the repository root `querymind.py` wrapper.\n\n### Direct Launch\n\n```bash\npython my_agent.py\npython webcomponent_demo.py --api-base http:\u002F\u002F127.0.0.1:8000\n```\n\n### Web Component\n\n```html\n\u003Cscript type=\"module\" src=\".\u002Ffrontends\u002Fwebcomponent\u002Fdist\u002Fquerymind-components.js\">\u003C\u002Fscript>\n\u003Cquerymind-chat\n  api-base=\"http:\u002F\u002Flocalhost:8000\"\n  title=\"QueryMind Chat\">\n\u003C\u002Fquerymind-chat>\n```\n\nUse this from any page that can load the built bundle. The component talks to `POST \u002Fapi\u002Fquerymind\u002Fv1\u002Fchat_sse`, `POST \u002Fapi\u002Fquerymind\u002Fv1\u002Fchat_poll`, and `WS \u002Fapi\u002Fquerymind\u002Fv1\u002Fchat_websocket`.\n\n## Full Documentation\n\nThe handbook expands the README into components, advanced-features, use-case, and support pages.\n\n- English: [docs\u002Fen\u002Fquerymind.md](docs\u002Fen\u002Fquerymind.md)\n- 中文: [docs\u002Fzh\u002Fquerymind.md](docs\u002Fzh\u002Fquerymind.md)\n\n## 👉 Ongoing and Future Actions\n\n### Ongoing\n\n1. Iterate on the AdventureWorks micro-benchmark by analyzing tool-call chains, prompt injection patterns, and common SQL failure modes.\n\n\u003Cfigure>\n  \u003Cimg src=\"docs\u002Ffigures\u002Fuse-cases\u002Feval-driven%20iterations.png\" alt=\"Eval-driven iterations\" \u002F>\n  \u003Cfigcaption>Eval-driven iterations: use benchmark feedback to refine prompts, governance, and SQL recovery behavior.\u003C\u002Ffigcaption>\n\u003C\u002Ffigure>\n\n2. Evaluate QueryMind against BIRD-SQL to measure text-to-SQL capability.\n\n\n### Future Actions\n\n1. Explore Agentic RL on top of QueryMind.\n2. Keep tightening the agent with evaluation results and governance feedback.\n\n\u003Ca id=\"license\">\u003C\u002Fa>\n\n## License\n\nQueryMind is released under the MIT License. See [LICENSE](LICENSE).\n\nThis project is developed for personal learning and research purposes. Special thanks to [Vanna](https:\u002F\u002Fgithub.com\u002Fvanna-ai\u002Fvanna) for being an important reference point and source of inspiration for this work.\n","QueryMind 是一个用于构建基于大语言模型（LLM）的代理框架，专门处理Text2SQL任务，并具备自主检索能力和企业级安全特性。其核心功能包括多层次记忆平面、四种模式的模式内存搜索、易于管理的模式维护界面、SQL安全与行级安全性保障以及灵活的集成选项，支持多种后端模型和数据库。该工具适用于需要将自然语言查询转换为SQL语句的真实业务场景中，特别是在那些对数据访问安全性有高要求的企业环境中。通过提供直观的操作界面和强大的安全保障措施，QueryMind能够帮助用户更高效地管理和分析商业数据库。",2,"2026-06-11 04:02:33","CREATED_QUERY"]