MoonRDB

一款由 MoonBit 驱动、面向本地 Agent 的 Agentic Database Engine，将向量检索、RDF/图谱推理与 SQLite 兼容的关系型引擎整合到同一个本地优先底座中。

概述

MoonRDB 是一款 Agentic Database Engine——面向本地 Agent 的嵌入式、本地优先多模数据库，服务知识密集型应用。它不再需要把向量数据库、图数据库和关系型存储拼凑在一起，而是提供一个统一的数据库内核，支持：

关系型存储：用于结构化元数据、权限控制和事务状态。
RDF / 图谱存储：用于实体、关系、知识图谱和多跳推理。
向量检索：用于语义召回、记忆检索和基于嵌入的排序。
SQLite 兼容引擎：支持熟悉的 SQL 工作流和本地持久化。
MoonBit 原生实现：借助静态类型、trait 和快速编译，获得更可靠的数据库内核。

MoonRDB 尤其适合：

本地 AI 记忆与检索层
个人知识图谱
结合结构化上下文与语义上下文的 Agent 推理
需要离线语义搜索的移动端 / 边缘端应用
希望使用 RDF 风格关系但不想部署独立图服务器的应用

为什么需要 MoonRDB

现代 AI 应用通常需要同时处理三类数据：

数据模型	典型场景	传统方案
关系型	用户、文档、权限、元数据	SQLite / PostgreSQL
图谱 / RDF	实体、关系、知识图谱	Neo4j / RDF 存储
向量	嵌入、语义搜索、记忆召回	独立向量库（Milvus / Qdrant）

分开管理会带来同步成本、部署复杂性和一致性风险。MoonRDB 将这些能力放进同一个进程，使语义检索、图遍历和关系查询共享同一事务边界和存储布局。

向量一路的口径：MoonRDB 复用两件既有引擎而非自研——sqlite-vec（在线 KNN + SQL 过滤）与 FAISS（离线大规模召回 / 重排候选集）；被替换的是「另起一个独立向量数据库服务」的部署形态。

架构

MoonRDB 采用六边形架构，存储引擎和检索策略通过明确定义的端口接入。应用层不直接调用驱动，而是通过 SemanticRouter 在推理语义与向量检索之间做边界决策。

用例 / 执行面   UseCase · Orchestrator      按 plan 调 port，合成答案
      │
组合件          SemanticRouter              只产 RetrievalPlan；不实现 port、不直呼引擎
      │
──────┼──── 六边形 ───────────────────────────────────────────────────────────
带①  内核        core（ProtoDB）            持 port 抽象；只依赖抽象，禁引引擎符号
带②  驱动侧 port  VectorQueryPort · VectorSyncPort        外界调入（可换装：算子 / gRPC / CLI）
带③  被驱动 port  VectorPort · GraphPort · DocPort         内核调出（Faiss / 内存 / 图引擎 / SQL）
                  FrameStream/FrameStore · BM25Port · ReasoningPort
──────┼──── 边界 ────────────────────────────────────────────────────────────
带④  适配器      引擎词唯一存活处：faiss.mbt（FAISS）· Memory*（原型）· @moondb.Driver（SQL）
                  storage_schema gen（RocksDB 物理面）· sqlite-vec（在线 KNN）· FAISS（离线召回）

四带：① 内核（六边形中心，持抽象）· ② 驱动侧 port（左，外界调入）· ③ 被驱动 port（右，内核调出）· ④ 适配器（边界之外，引擎词唯一存活处）。

SemanticRouter 不是业务层，也不是驱动层，而是 Port 之上的组合件（决策面，只产 RetrievalPlan）。它决定：

当前查询是否需要向量检索；
是否需要本体/图谱推理；
是否直接读取 Jelly 帧；
是否触发 Owl 推理层；
是否需要回退到纯文档加载模式；
是否命中推理缓存。

各 Port 只负责自身能力，不互相耦合。

已定（2026-10-05）：ReasoningPort = 被驱动侧 port（推理执行），OwlLayer = port 之上的编排（只出规则计划）；答案合成归执行面（UseCase / Orchestrator），不归 port。全量方位与落地细节见 spec.md §2 方位表（本图是它的投影，表改 ⇒ 图同笔）。

路由策略设计

MoonRDB 不使用全局 enable_vector 这类硬编码布尔开关，而是把“开关”设计成推理语义边界上的路由策略集合，由 SemanticRouter 统一决策。

策略集合与设备能力


pub enum ReasoningLevel {
  None
  Rdfs
  OwlEl
}

pub enum DeviceCapability {
  Low
  Medium
  High
}

pub struct RouterPolicy {
  default_reasoning: ReasoningLevel,
  max_vector_k: Int,
  enable_cache: Bool,
  cache_ttl_seconds: Int64,
  allow_owl_el: Bool,
  vector_pre_filter: Bool,
  fallback_on_cache_miss: Bool,
}

pub struct DeviceProfile {
  capability: DeviceCapability,
  available_memory_mb: Int,
  max_embedding_dim: Int,
  inference_latency_budget_ms: Int,
}

推理缓存层


pub struct InferenceCacheKey {
  ontology_module: String,
  input_ids: Array[String],
  reasoning_level: ReasoningLevel,
}

pub struct InferenceCacheEntry {
  inferred_triples: Array[Triple],
  computed_at: Int64,
  expires_at: Int64,
}

pub trait InferenceCache {
  fn get(self, key: InferenceCacheKey) -> Option[InferenceCacheEntry]
  fn put(self, key: InferenceCacheKey, entry: InferenceCacheEntry) -> Unit
  fn invalidate(self, ontology_module: String) -> Unit
}

缓存策略：写入时预计算：Jelly 帧入库 → 提取三元组 → 跑 RDFS/OWL-EL → 闭包写入 RocksDB；查询时命中缓存：InferenceCache.get() 命中则零推理延迟； TTL 过期：本体更新时按 ontology_module 批量失效；缓存未命中降级：fallback_on_cache_miss = true 时退回 Rdfs 或 None。 3. 降级决策逻辑


fn decide_reasoning_level(
  self,
  policy: RouterPolicy,
  profile: DeviceProfile,
  intent: QueryIntent,
  cache_hit: Bool,
) -> ReasoningLevel {
  // 降级链（已定）：OwlEl → Rdfs → None，逐档下退、不跳档
  if !policy.allow_owl_el {
    return Rdfs
  }

  match profile.capability {
    Low => None
    Medium =>
      if cache_hit {
        policy.default_reasoning
      } else if policy.fallback_on_cache_miss {
        Rdfs
      } else {
        policy.default_reasoning
      }
    High =>
      if intent.needs_deep_reasoning {
        OwlEl
      } else {
        policy.default_reasoning
      }
  }
}

fn decide_vector_k(
  self,
  policy: RouterPolicy,
  profile: DeviceProfile,
  reasoning_level: ReasoningLevel,
) -> Int {
  let base = policy.max_vector_k
  if reasoning_level != None && profile.capability != High {
    base / 2
  } else {
    base
  }
}


pub struct RetrievalPlan {
  reasoning_level: ReasoningLevel,
  vector_k: Int,
  use_cache: Bool,
  need_doc_load: Bool,
  frame_ids: Option[Array[String]],
  ontology_modules: Array[String],
}

pub trait SemanticRouter {
  fn route(
    self,
    query: QueryContext,
    policy: RouterPolicy,
    profile: DeviceProfile,
  ) -> RetrievalPlan raise RouterError

  fn on_ontology_update(self, module: String) -> Unit
}

实现骨架：


fn route(
  self,
  ctx: QueryContext,
  policy: RouterPolicy,
  profile: DeviceProfile,
) -> RetrievalPlan {
  let intent = classify_intent(ctx.query)
  let cache_key = build_cache_key(intent, policy.default_reasoning)
  let cache_hit = policy.enable_cache && self.cache.get(cache_key) != None

  let reasoning = decide_reasoning_level(policy, profile, intent, cache_hit)
  let k = decide_vector_k(policy, profile, reasoning)

  {
    reasoning_level: reasoning,
    vector_k: k,
    use_cache: policy.enable_cache && cache_hit,
    need_doc_load: intent.needs_raw_frame,
    frame_ids: ctx.frame_ids,
    ontology_modules: intent.relevant_modules,
  }
}

fn on_ontology_update(self, module: String) -> Unit {
  self.cache.invalidate(module)
}

执行侧对接


fn execute(self, plan: RetrievalPlan, ctx: QueryContext) -> Answer {
  let intent = classify_intent(ctx.query)   // 与 route 同源：两处缓存键必须同一构造
  let vectors = if plan.vector_k > 0 {
    vector_port.search(ctx.embedding, plan.vector_k)
  } else { [] }

  let owl_results = if plan.reasoning_level != None {
    if plan.use_cache {
      self.cache.get(build_cache_key(intent, plan.reasoning_level))
    } else {
      reasoning_port.reasonize(        // 推理执行归 port（B-D14）；OwlLayer 只在 route 决策期出规则计划
        ctx.query,
        vectors.map(|v| v.document_id),
        plan.reasoning_level,
        plan.ontology_modules,
      )
    }
  } else { None }

  let frames = if plan.need_doc_load {
    let ids = plan.frame_ids ?? vectors.map(|v| v.frame_id)
    ids.map(|id| doc_port.load_frame(id))
  } else { [] }

  synthesize_answer(ctx.query, vectors, owl_results, frames)   // 合成归执行面（UseCase/Orchestrator），不归 port
}

这样 SemanticRouter 就是一个完整的策略集合开关：它根据设备能力、查询意图、缓存命中情况动态决定推理级别和向量规模，并在本体更新时自动失效缓存，手机端推理引擎侧也能通过 DeviceProfile 动态适配资源约束。

手机端推理引擎适配

移动端推理引擎受内存与延迟约束较强，RouterPolicy 按设备能力动态调整——本节不另立一份规则，一切以上方「降级规则」表为唯一口径：

低配设备：路由取 None（不做推理），只走向量检索 + Jelly 帧精确读取；
中配设备：缓存未命中且 fallback_on_cache_miss 为真 → 退回 Rdfs；推理开启且资源紧张 → 向量 k 减半；
高配设备：需深度推理时开启 OwlEl，向量 + 本体 + 文档三路并行。

不设 enable_vector 这类全局开关（与本节开头「不使用全局开关」一致）：关哪一路由 RetrievalPlan 的 reasoning_level / vector_k 表达。 降级链（已定 2026-10-05，B-D11）：OwlEl → Rdfs → None——逐档下退、不跳档；「降到哪一档」由 DeviceProfile.capability 与资源预算（inference_latency_budget_ms）共同决定，最终表达在 RetrievalPlan.reasoning_level。低配设备 = 链底 None（关推理），只走向量 + Jelly 帧。

快速开始

前置条件

MoonBit 工具链支持的运行时目标，例如 Wasm、Native 或 JS

构建


moon build

运行测试


moon test

基本用法


// 伪 API；实际接口取决于具体实现
let db = MoonRDB.open("agent_memory.db")

db.sql("CREATE TABLE documents (id TEXT PRIMARY KEY, content TEXT)")

db.upsert_node("doc:1", { title: "MoonRDB Design" })
db.upsert_edge("doc:1", "REFERENCES", "doc:2")

db.insert_vector("doc:1", [0.12, 0.45, -0.33])

let candidates = db.semantic_search("database architecture", top_k=10)
let context = db.graph_context(candidates, depth=2)

设计目标

本地优先：在应用进程内运行，无需独立数据库服务器。多模：关系型、图谱/RDF 和向量数据共存于同一数据库。可嵌入：适合移动端、边缘端、桌面端和 Agent 运行时。 MoonBit 原生：利用静态类型、trait 和快速编译构建可靠内核。可插拔后端：向量索引、图谱存储和 SQL 引擎可独立演进。面向 AI：为检索、记忆和推理工作负载设计，而非仅面向通用 OLTP。显式边界：通过 SemanticRouter 管理推理语义与向量检索的组合策略。可降级：根据设备能力、缓存状态和查询意图动态调整推理级别与检索规模。

当前状态

MoonRDB 处于早期开发阶段。API、存储格式和查询接口可能会发生变化。规划里程碑（K1–K6 能力编号，与下方路线图一一对应；交付阶段轴另见范式卷 S1–S6，两轴正交）： SQLite 兼容的关系型引擎 RDF 三元组存储与基础图遍历向量检索集成 SemanticRouter 路由策略层 InferenceCache 推理缓存层混合 SQL + 图谱 + 向量查询 MoonBit 原生绑定与示例面向检索和推理工作负载的基准测试

路线图

K1 · 关系型底座

SQLite 兼容 SQL 引擎基础表、索引和事务支持嵌入式存储后端 MoonBit 原生查询接口

K2 · RDF / 图谱层

RDF 风格三元组存储节点 / 边 API 基础图遍历和多跳查询混合 SQL + 图谱查询

K3 · 向量检索

向量列与嵌入存储 KNN / 语义搜索可插拔向量索引后端混合 SQL + 图谱 + 向量查询

K4 · 路由与推理边界

SemanticRouter 策略层 RetrievalPlan 与 RouterPolicy ReasoningPort / VectorPort / DocPort 边界定义移动端自适应路由策略 RDFS/OWL-EL 子集做轻量约束和解释层

K5 · 推理缓存与降级

InferenceCache 缓存层 RDFS / OWL-EL 预计算闭包缓存失效与 TTL 策略设备能力感知降级逻辑

K6 · Agent 与检索工作负载

面向 AI Agent 的检索 API 记忆召回与上下文组装本地优先工作负载基准测试移动端 / 边缘端部署示例

演进方向

MoonRDB 不止于「多模数据库 + AI 插件」，而是朝 Agentic Database Engine——面向本地 Agent 的多模记忆与执行引擎——演进：把 Agent 所需的能力收进同一进程，经统一 Port 暴露。

记忆：Jelly 帧（短期 / 长期记忆载体）
检索：BM25（可解释文本）· sqlite-vec / FAISS（语义）
推理：属性图 + 轻量本体（结构化关系与约束）

上层 Agent 不必知道底层实现（sqlite-vec / RocksDB / …），只需经 Port 调用。进一步的方向是在这三者之上补齐可审计、可回放、可回滚的执行闭环——从「多模检索库」走向「Agentic Database Engine」的关键一步。

贡献

欢迎贡献。添加新存储后端、路由策略或查询算子时，请遵循：保持公共接口稳定并提供清晰文档。为关键不变量补充属性测试或模糊测试。提供 SQL、图谱、向量和路由策略的使用示例。设计说明和接口文档优先使用 AsciiDoc 编写。

许可证

本项目采用 木兰宽松许可证，第 2 版（MulanPSL v2）（裁定 2026-10-05，B-D1；换文已落，2026-10-05）。

元数据：moon.mod 记 license = "MulanPSL-2.0"（与 LICENSE 两处一致，同笔）。
子模块 moonttl 的许可在其自身仓另行裁定（子模块边界，本轮不动）。