> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.
# What is HeavenBase?
> An overview of HeavenBase as an agent-native polyglot engine for structured data management.
*Your data, speakable by agents.*
*One model. Many backends. Every agent.*
## 1. Data Observability: The Data Silos Dilemma
Modern enterprises already possess the information needed to power intelligent agentic systems. The challenge is that this knowledge is scattered across fragmented infrastructure (i.e., data silos): transactional databases, search engines, vector stores, file systems, and more.
For human operators, this fragmentation creates operational complexity. For agents, it creates **blindness**.
Three patterns show up again and again: the agent does not know a silo exists, its map of sources is out of date, or it misreads the vocabulary your teams actually use. The scenarios below are fictional, but the failure modes are routine in enterprise deployments.
The more silos and interfaces there are, the harder it is for agents to discover and access the data they need. LLMs keep improving at reasoning, searching, and learning, but they cannot *infer data they were never shown exists*.
A procurement team asks an agent to find "all vendor contracts expiring this month." The agent has access to five systems: two covering **deals and orders**, and three covering code and documents.
It queries the deals-and-orders sources — where most active contracts live — and returns **73 results** with a confident summary.
But **43 more contracts** exist only as scanned PDF amendments in the legal team's **document repository**.
That repository is indexed in enterprise search, but no one from the legal team had registered it as a contracts source.
From the agent's perspective, the list is complete — it checked every source relevant to deals and orders.
From the business's perspective, 43 renewals are invisible until a vendor invoice lands.
> **Takeaway**: An agent cannot query a silo it does not know exists or is relevant to the task.
A customer-support agent starts with a clear data map: customer context in Salesforce, billing in NetSuite, product FAQs in Confluence.
**Six months later**, the product team loads **compatibility notes** from field-service reports into a new vector database. **The agent's source catalog is never updated.**
A customer asks whether their 2019 controller works with the latest firmware. The agent checks Confluence and Salesforce, confidently walking them through an upgrade path.
The vector index says that combination is unsupported. The customer books a service visit that was entirely avoidable.
> **Takeaway**: Data observability decays the moment your landscape changes and the agent's map does not.
A finance analytics agent is equipped with a detailed, up-to-date manual: what to look for and where, for every scenario.
Then a routine request from the finance team breaks it: "Generate the regional **DFA** report for Q3."
"DFA"? The agent has no idea what that means.
Regional metrics live in the `regional_performance` table according to the manual, so the agent queries it — and finds nothing.
It turns out DFA stands for **Double-Factor Analysis** — a spreadsheet methodology the finance team has been using for years.
The reports are stored on a file drive with names like `FY25/Q2/Regional_DFA_v3.xlsx`. The manual never explains the term; it assumes everyone already knows it.
> **Takeaway**: A precise source map can still fail when domain vocabulary is not part of the observable layer.
A deep research agent has access to vector search over professional literature, company knowledge, and data ontology.
It is asked to summarize the trends across all recent papers in the field of time-series forecasting.
It uses **vector search** to find relevant papers, then summarizes the **top 20** most relevant results.
It runs a follow-up check for any missed papers, finds **20 more**, revises its summary, and submits the report with confidence.
But 20 is just the **default top-k** of the vector search. There are actually 100+ relevant papers in the index.
> **Takeaway**: Knowing "what" and "where" to look is not enough — "how many" matters too.
An agent is working on a margin report. It accurately locates everything it thinks it needs: revenue data, cost data, and other relevant figures.
To compute the margin, it subtracts cost from revenue — straightforward enough.
The missing piece is **tax**: it must also be deducted from revenue, with a different rate for each state.
The agent never makes the connection because "tax" appears nowhere in its search path — it queried "margin," "revenue," "cost," none of which point to tax.
There is a separate "tax computation" manual that has a paragraph about tax computation during margin report. The agent finds the manual, but concludes it has nothing to do with a margin report and moves on without reading it.
> **Takeaway**: Finding the right data is only half the job — finding the right manual and playbook matters just as much.
***
The most important reason agents fail in real-world applications is not that they lack intelligence, but that they lack **data observability**.
Recognizing this problem, many enterprises have tried to solve it by integrating their data silos into a single system, either by building a data warehouse, a data lake, or a new type of database with heavy ETLs. This approach often leads to suboptimal performance, increased operational complexity, and most importantly, high migration costs.
Agentic systems do not need new data sources, they need an **intuitive, unified way** to access their existing ones.
This is where HeavenBase comes in.
## 2. The HeavenBase Solution: A Polyglot Engine for Agents
HeavenBase sits between your agents and your data; it does not replace your databases, search engines, or vector stores — it connects to them.
HeavenBase aims to offer a **unified data interface** that abstracts away the complexities of different backends, designed natively for agents to discover, query, manipulate and organize data across silos without needing to know where the data actually lives or how to query it.
To start working with HeavenBase, you simply create a new workspace, inform it about your available data backends, and then start to connect your data sources and pour your business knowledge into it. Technically, HeavenBase employs an intuitive *object-oriented data model* to manage your knowledge, as well as your data. You can now work with your data in the same logical workspace as your business knowledge, orchestrate your agents, and manage your workflows with the same interface as before. Meanwhile, HeavenBase handles the complexities of physical storage, query planning, and execution across your backends, allowing you and your agents to focus on reasoning and decision-making.
Then, with all the data and decisions flowing through HeavenBase in the same logical workspace, **data insights** start to emerge.
For example, a support agent can answer a customer question by reaching the order record, product policy, prior conversations, and internal notes through one HeavenBase workspace.
Source data, metadata, domain knowledge, agent traces, tools, prompts, user preferences, and statistics are unified in HeavenBase workspace in the same logical data model, and thus can be consistently managed by **meta-agents**. This allows you to feed insights back to worker agents *proactively* or *on-demand*, ensuring they are always aware of the big picture and can access the right information at the right time.
## 3. What HeavenBase Provides
As an **individual user**, you can use HeavenBase as a *memory layer* for your agents, a notebook for your agent to keep track of its thoughts, tasks, your preferences, and any other information it needs to know to serve you better. HeavenBase is available as *a plug-and-play MCP server with Skills* for agents to use.
As an **enterprise user**, you can immediately enable your agents to talk to your data, and *continuously learn from your data*, gaining valuable insights and improving decision-making. You can choose to expose the interface to you and your agents in any form that you feel most comfortable working with: Python ORM expressions, MongoDB-style JSON queries, SQL, Python programs, or natural language instructions, and HeavenBase will help your agents translate those into efficient physical queries across the right data stores.
As a **developer**, you can use the HeavenBase CLI and Python SDK to help build your agents and applications faster than ever before. Create a new workspace, define your entities, connect your backends, and start focusing on your business logic and agentic workflows, while HeavenBase takes care of the data plumbing and management for you.
As a **manager or platform leader**, you can use HeavenBase as a data plane for your agentic systems, monitoring interactions, consolidating business knowledge, and continuously improving your data landscape.
TODO: HeavenBase GUI for catalog and observability; data governance and lineage features
## Further Exploration
**Related resources:**
* [Philosophy](/introduction/philosophy) - Design values and tradeoffs
* [Architecture](/introduction/architecture) - System structure
* [Quickstart](/quickstart/installation) - Get running in minutes