astra-knowledge-base-mcp

MCP (Model Context Protocol) server for managing and searching multi-tenant knowledge bases.

Part of Astra AI Agent Infrastructure

Overview

Astra Knowledge Base MCP provides AI agents with persistent, searchable knowledge bases backed by PostgreSQL 16+ with pgvector — hybrid full-text and vector search, plus SAG (SQL-Retrieval Augmented Generation) for relational reasoning across chunks.

Each knowledge base is an isolated namespace. Content is auto-chunked on ingestion (recursive, heading-anchor, or semantic splitting), embedded via any OpenAI-compatible endpoint, and indexed for three complimentary retrieval paths.

Related MCP server: server-memory

Prerequisites

• Python 3.11+

• uv — Python package manager (pip install uv)

• PostgreSQL 16+ with pgvector — installation guide: pgvector.org

Setup

1. Configure PostgreSQL

Create the database and enable pgvector:

CREATE DATABASE astra_kb;
\c astra_kb
CREATE EXTENSION IF NOT EXISTS vector;

2. Install dependencies

uv sync

3. Configure environment

# Embedding endpoint (any OpenAI-compatible API; a local AI Gate works too)
export ASTRA_EMBED_BASE_URL=https://api.siliconflow.cn/v1
export ASTRA_EMBED_API_KEY=sk-...
export ASTRA_EMBED_MODEL=embedding
export ASTRA_EMBED_DIM=1024

# Optional: LLM endpoint for SAG extraction
export ASTRA_LLM_BASE_URL=https://api.siliconflow.cn/v1
export ASTRA_LLM_API_KEY=sk-...
export ASTRA_LLM_MODEL=auto/best-free

# PostgreSQL connection
export ASTRA_KB_PG_DSN=dbname=astra_kb user=postgres host=/run/postgresql

4. Start

uv run server.py

Configuration

Provider-agnostic by default. Both ASTRA_EMBED_BASE_URL and ASTRA_LLM_BASE_URL accept any OpenAI-compatible endpoint — a local AI Gate or a hosted provider. When a base URL is set, an API key is only needed for non-local endpoints. If both are empty the server starts in a degraded mode (keyword-only retrieval, no embedding).

No hardcoded provider defaults. ASTRA_EMBED_BASE_URL and ASTRA_LLM_BASE_URL must be set explicitly. The old SILICONFLOW_API_KEY fallback has been removed — use ASTRA_EMBED_API_KEY or ASTRA_LLM_API_KEY instead.

Usage

MCP Tools

Registering in Hermes Agent

Add to your Hermes config.yaml:

mcp_servers:
  astra-knowledge-base:
    command: /path/to/astra-knowledge-base-mcp/scripts/run.sh
    enabled: true

Then restart Hermes Agent. The tools become available automatically.

Architecture

AI Agent (Hermes)
    │  MCP stdio protocol
    ▼
astra-knowledge-base-mcp (Python, uv run)
    │
    ├── PostgreSQL (psycopg2 + pgvector) → astra_kb
    │   ├── kb_registry         ← KB metadata & status
    │   ├── kb_*.chunks         ← Per-KB schema (tsvector FTS + vector(1024))
    │   ├── kb_*.events         ← SAG event index (vector(1024))
    │   ├── kb_*.entities       ← SAG entity index (vector(1024))
    │   └── mgmt                ← Operational data (services, health_log, api_keys)
    │
    └── Embedding cache (PostgreSQL) → embed_cache table

Three complimentary retrieval paths:

• FTS — keyword search via PostgreSQL tsvector / ts_rank

• Vector — semantic search via cosine similarity on pgvector indexes

• SAG — SQL-Retrieval Augmented Generation: event-entity extraction + query-time hyperedge expansion for multi-hop reasoning across chunks

Agent Guide

See AGENTS.md for AI-agent-oriented documentation (entry points, workflows, Hermes integration).

Related

• astra-aiagent-infra — ecosystem portal

• Hermes Agent — AI agent framework

• MCP — Model Context Protocol

Dependencies

• PostgreSQL 16+ with pgvector — primary data store

• psycopg2-binary — PostgreSQL driver

• MarkItDown — file import (PDF, DOCX, PPTX)

Retrieval Strategy

We implement SAG (SQL-Retrieval Augmented Generation) — an original retrieval architecture that replaces both traditional RAG and GraphRAG. SAG uses event-entity indexing and query-time dynamic hyperedges to deliver both semantic retrieval and relational reasoning in a single pipeline.

Reference:

• SAG paper: arxiv 2606.15971 — Yuchao Wu et al., Zleap AI (MIT)

• Reference implementation: github.com/Zleap-AI/SAG — MIT License

Our implementation follows the SAG algorithm directly on our PostgreSQL/pgvector infrastructure, without wrapping the reference package.

License

MIT — see LICENSE.

中文版

概述

Astra Knowledge Base MCP 为 AI Agent 提供基于 PostgreSQL 16+ + pgvector 的持久化、可搜索知识库——支持混合全文/向量检索和 SAG（SQL 检索增强生成）关联推理。

每个知识库是隔离的命名空间，内容引入时自动分块（递归、heading-anchor 或语义切分），通过任意 OpenAI 兼容的端点进行向量化，并建立三种互补的检索路径。

Minimal setup:

export ASTRA_EMBED_BASE_URL=https://api.siliconflow.cn/v1
export ASTRA_EMBED_API_KEY=sk-...
uv run server.py