Hypabase

Hypabase

一个支持溯源和 SQLite 持久化的 Python 超图库。

安装

uv add hypabase

快速示例

from hypabase import Hypabase

hb = Hypabase("my.db")

# One edge connecting five entities
hb.edge(
    ["dr_smith", "patient_123", "aspirin", "headache", "mercy_hospital"],
    type="treatment",
    source="clinical_records",
    confidence=0.95,
)

# Query edges involving a node
hb.edges(containing=["patient_123"])

# Find paths between entities
hb.paths("dr_smith", "mercy_hospital")

功能特性

• 超边 — 一条边可在单个关系中连接 2 个或更多节点
• 溯源 — 每条边都包含 source 和 confidence
• SQLite 持久化 — 数据会自动持久化到本地文件
• O(1) 顶点集查找 — 按节点的精确集合查找边
• 命名空间隔离 — 使用 .database("name") 在单个文件中创建限定范围的视图
• 溯源查询 — 按 source 和 min_confidence 筛选，并通过 sources() 汇总
• 记忆 MCP 服务 — 为 AI Agent 提供 7 种持久化记忆工具（remember、recall、forget、consolidate、connections、who_knows_what、resolve_contradiction）
• CLI — hypabase init、hypabase node、hypabase edge、hypabase query

溯源

每条边都包含 source 和 confidence：

hb.edge(
    ["patient_123", "aspirin", "ibuprofen"],
    type="drug_interaction",
    source="clinical_decision_support_v3",
    confidence=0.92,
)

# Bulk provenance via context manager
with hb.context(source="schema_analysis", confidence=0.9):
    hb.edge(["a", "b"], type="fk")
    hb.edge(["b", "c"], type="fk")

# Query by provenance
hb.edges(source="clinical_decision_support_v3")
hb.edges(min_confidence=0.9)

# Overview of all sources
hb.sources()

命名空间隔离

在单个文件中将数据隔离到不同命名空间：

hb = Hypabase("knowledge.db")

drugs = hb.database("drugs")
sessions = hb.database("sessions")

drugs.node("aspirin", type="drug")
sessions.node("s1", type="session")

drugs.nodes()     # -> [aspirin]
sessions.nodes()  # -> [s1]

什么是超图？

在普通图中，一条边恰好连接两个节点。在超图中，一条边（称为超边）可以同时连接任意数量的节点。

来看一个医疗事件：Smith 医生在 Mercy 医院为 123 号患者开具阿司匹林来治疗头痛。 在传统图中，你需要将其拆分为二元边——医生与患者、医生与药物、患者与医院——而这些事实属于同一事件这一点就成了推断结果，而非图结构的一部分。超图可以原生存储这一信息：用一条边连接全部五个实体。

这很重要，因为现实世界中的关系往往涉及两个以上的事物。一篇论文通常有三四位作者，而非一位。一笔交易涉及买家、卖家、商品和支付方式。一次化学反应的两侧都有反应物和产物。将这些关系强行拆成成对关系，就会让它们之间的关联变成隐式信息。

为什么需要溯源？

当关系来自不同来源（手动录入、大模型提取、传感器数据、临床记录）时，你需要知道每条关系的来源，以及对它的信任程度。Hypabase 通过每条边上的两个字段来跟踪这些信息：source（标识来源的字符串）和 confidence（取值范围为 0 到 1 的浮点数）。你可以按这些字段筛选查询，也可以通过 hb.sources() 获取图中所有来源的汇总。

超图的应用场景

• 知识图谱 — 表示复杂的现实世界关系，而无需拆分
• Agent 记忆 — 为 AI Agent 提供结构化、可查询且可跨会话持久保存的记忆
• 生物医学数据 — 药物相互作用、临床事件、分子通路
• RAG 流水线 — 存储提取出的关系，用于检索增强生成
• 供应链、协作网络，以及任何关系涉及两个以上事物的场景

这一更广泛的理念源于 OpenCog 的 AtomSpace 等 AI 研究，该研究可追溯到更早时期。AtomSpace 使用类似超图的结构来表示 AGI 知识。近期研究则将超图专门应用于检索和推理：

• HyperGraphRAG — 面向医学、农业、计算机科学和法律的多元知识检索
• Cog-RAG — 结合主题级和实体级回忆的双超图检索
• Hypergraph Memory for Multi-step RAG — 基于超图的长上下文关系建模记忆

MCP 服务

Hypabase 包含一个 Memory MCP 服务，提供 7 个工具，让 AI Agent 可以将其用作结构化的持久记忆。兼容 Claude Code、Claude Desktop、Cursor、Windsurf 以及任何兼容 MCP 的客户端。

uv add hypabase
hypabase-memory

命令行

uv add hypabase
hypabase init
hypabase node dr_smith --type doctor
hypabase edge dr_smith patient_123 aspirin --type treatment --source clinical_records
hypabase query --containing dr_smith
hypabase stats

文档

docs.hypabase.app

许可证

Apache 2.0