Agent-Oriented Knowledge Management Platform
Unified knowledge base, episodic memory, and generative synthesis.

Heta is an all-in-one knowledge infrastructure for AI agents. It gives agents a place to store, retrieve, and accumulate knowledge across three complementary layers:

• HetaDB — ingest documents (PDF, DOCX, PPTX, XLS/XLSX, images, …), extract knowledge graphs, and query with five retrieval strategies from naive vector search to multi-hop reasoning.
• HetaMem — a dual-layer memory system: fast episodic recall (MemoryVG) for conversation facts, and a long-term knowledge graph (MemoryKB) that grows with the agent.
• HetaGen — knowledge-base-driven structured content generation: table synthesis, tag-tree construction, and Text-to-SQL. (early stage)

HetaDB

• Ingests PDF, DOCX, PPTX, XLS/XLSX, images, HTML, Markdown, ZIP archives
• LLM-powered knowledge graph extraction with deduplication (Union-Find merging)
• Five query strategies: naive · rerank (BM25 + vector + cross-encoder) · rewriter · multihop (ReAct) · direct
• Inline citations linking answers back to source documents

HetaMem

• MemoryVG — LLM auto-extracts facts from conversations; instant semantic search; full CRUD + history audit
• MemoryKB — LightRAG knowledge graph that grows as the agent learns; hybrid / local / global retrieval modes
• Scope isolation per user_id / agent_id / run_id

HetaGen (early stage)

• Generate structured tables by querying the knowledge base
• Tag-tree construction from topics
• Text-to-SQL over generated tables

HetaDB and HetaMem also expose optional MCP servers (ports 8012 / 8011) for direct integration with MCP-compatible clients such as Claude Desktop and Cursor.

Prerequisites: Docker ≥ 24.0 · Docker Compose ≥ 2.20 · DashScope and SiliconFlow API keys

git clone https://github.com/HetaTeam/Heta.git
cd Heta

# Chinese API providers (DashScope + SiliconFlow)
cp config.example.zh.yaml config.yaml

# International API providers (OpenAI + Gemini)
# cp config.example.yaml config.yaml

Open config.yaml and fill in your API keys:

providers:
  dashscope:
    api_key: "YOUR_DASHSCOPE_KEY"    # required

  siliconflow:
    api_key: "YOUR_SILICONFLOW_KEY"  # required

docker-compose up -d

First run pulls images and builds the stack (~10–20 min). Verify:

docker-compose ps           # all services: healthy
curl localhost:8000/health

docker-compose down         # stop, keep data
docker-compose down -v      # stop and delete all volumes

Prerequisites: Python 3.10 · PostgreSQL · Milvus · Neo4j

# 1. Install backend
conda create -n heta python=3.10 -y && conda activate heta
pip install -e .

# 2. Build frontend
cd heta-frontend && npm install && npm run build && cd ..

# 3. Run (unified — all modules on one port)
PYTHONPATH=src python src/main.py          # → http://localhost:8000

Run each module independently:

export PYTHONPATH=/path/to/Heta/src

python src/hetadb/api/main.py              # HetaDB   → :8001
python src/hetagen/api/main.py             # HetaGen  → :8002
python src/hetamem/api/main.py             # HetaMem  → :8003

# MCP servers
HETAMEM_BASE_URL=http://localhost:8000 python src/hetamem/mcp/server.py  # → :8011
HETADB_BASE_URL=http://localhost:8000  python src/hetadb/mcp/server.py   # → :8012

Port reference:

Heta exposes two integration layers — use one or both:

MCP gives your agent direct tool-call access to HetaDB and HetaMem. Add the following to your MCP client config (e.g. Claude Desktop ~/.claude.json):

{
  "mcpServers": {
    "hetamem": { "type": "http", "url": "http://localhost:8011/mcp/" },
    "hetadb":  { "type": "http", "url": "http://localhost:8012/mcp/" }
  }
}

The agent can now call HetaDB and HetaMem tools directly without any additional setup.

The bundled skill teaches the agent when and how to use each layer — which system to query first, how to store findings, and the correct three-step retrieval order (MemoryVG → HetaDB → MemoryKB).

skills/querying-knowledge-and-memory/SKILL.md

Load it in your agent system!

Datasets and knowledge bases are created and managed through the Heta web UI (http://localhost):

1. Create a dataset and upload your documents (PDF, DOCX, HTML, images, …)
2. Create a knowledge base and link it to your dataset
3. Trigger parsing — Heta extracts a knowledge graph and embeddings (async)

Once indexed, agents query the knowledge base via the chat API:

# List available knowledge bases
curl http://localhost:8000/api/v1/hetadb/files/knowledge-bases

# Query a knowledge base
curl -X POST http://localhost:8000/api/v1/hetadb/chat \
  -H "Content-Type: application/json" \
  -d '{
    "query":      "What are the main contributions?",
    "kb_id":      "research-kb",
    "user_id":    "agent",
    "query_mode": "rerank"
  }'
# → { "response": "...", "citations": [...] }

Available query_mode values: naive · rerank · rewriter · multihop · direct

# Store facts extracted from a conversation
curl -X POST http://localhost:8000/api/v1/hetamem/vg/add \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user",      "content": "I prefer concise Python examples."},
      {"role": "assistant", "content": "Noted."}
    ],
    "agent_id": "agent"
  }'

# Recall relevant facts
curl -X POST http://localhost:8000/api/v1/hetamem/vg/search \
  -H "Content-Type: application/json" \
  -d '{"query": "user coding preferences", "agent_id": "agent"}'
# → { "results": [{"memory": "Prefers concise Python examples", "score": 0.91}] }

# Insert knowledge into the agent's long-term graph (async — ~200s to index)
curl -X POST http://localhost:8000/api/v1/hetamem/kb/insert \
  -F "query=Transformer models use self-attention to process sequences in parallel."

# Query the knowledge graph
curl -X POST http://localhost:8000/api/v1/hetamem/kb/query \
  -H "Content-Type: application/json" \
  -d '{"query": "How do transformers handle long-range dependencies?", "mode": "hybrid"}'
# → { "final_answer": "..." }

The bundled querying skill encodes the recommended retrieval workflow — when to use each layer, in what order, and what to store back. Load it into any skill-aware agent system and it will orchestrate HetaDB, MemoryVG, and MemoryKB automatically.

Three-step retrieval order the skill enforces:

1. MemoryVG  — check fast personal memory first (~100 ms)
2. HetaDB    — deep retrieval from uploaded documents (1–3 s)
3. Store back — cache finding in MemoryVG, or insert into MemoryKB if worth accumulating

Layer selection guide:

Heta/
├── config.example.yaml       # Config template (international: OpenAI / Gemini)
├── config.example.zh.yaml    # Config template (domestic: DashScope / SiliconFlow)
├── docker-compose.yml        # Full-stack deployment
├── Dockerfile
├── pyproject.toml
├── docs/                     # API reference and design documents
├── heta-frontend/            # Web UI
├── skills/                   # Agent skills
│   └── querying-knowledge-and-memory/
└── src/
    ├── main.py               # Unified entry point (port 8000)
    ├── common/               # Shared utilities: logging, config, LLM client, tasks
    ├── hetadb/               # Knowledge-base ingestion & multi-strategy chat
    ├── hetagen/              # Table and tag-tree generation
    └── hetamem/              # Agent memory: MemoryKB + MemoryVG + MCP server

Heta is built on the shoulders of excellent open-source projects:

• MinerU — the document parsing engine powering HetaDB ingestion
• mem0 — the episodic memory engine powering MemoryVG
• LightRAG — the knowledge graph engine powering MemoryKB

We are grateful to their authors for making this work possible.

AGPL-3.0 — see LICENSE for details.

This project incorporates code from the following open-source projects:

• MinerU — AGPL-3.0 License
• LightRAG — MIT License
• mem0 — Apache 2.0 License