Hypatia 解读

背景

Hypatia 是一个面向 AI 的内存管理系统（AI-oriented memory management system），由 Rust 编写。其核心目标是将结构化知识存储为由 Knowledge（知识节点） 和 Statement（关系边） 组成的知识图谱，并提供一套名为 JSE (JSON Search Expression) 的自定义查询语言。 该系统最大的特点是零外部模型依赖（没有调用任何 Embedding/LLM 大模型来实现搜索），它采用了双数据库存储架构（Dual-Database Storage）：底层利用 DuckDB 进行结构化的高效查询，利用 SQLite FTS5（集成 Porter stemmer 和多列 BM25 算法）进行全文检索，并通过服务层自动同步两者数据。

⚡ TL;DR / 快速总结

• 语言：Rust
• 核心架构：DuckDB（关系和属性查询） + SQLite FTS5（全文检索）双引擎。
• 数据模型：
  • Knowledge：图谱节点，包含名称、标签、数据、同义词。
  • Statement：图谱边，S-P-O（主-谓-宾）三元组，支持时间范围。
• 查询语言 (JSE)：基于 JSON 的查询语言，支持逻辑组合（$and,$or, $not）、SQLLIKE（$like）、三元组匹配（$triple）、全文搜索（$search）等，运行时编译为参数化 SQL 交给 DuckDB/SQLite 处理。
• 适用场景：AI Agent 的本地知识库/长期记忆管理工具，提供 CLI 和 REPL，并支持 Claude Code skill 接入。作为无 Embedding 方案，适合资源受限或需要绝对确定性匹配的本地 Agent。

核心设计与实现细节

1. 双数据库存储与同步机制 (Dual-Write)

Hypatia 的每个 Shelf（数据库实例目录）内部都包含两个文件：data.duckdb 和 index.sqlite。

• DuckDB 负责处理复杂的 SQL 查询，如按标签、名称前缀 ($like‘)过滤，以及复杂的三元组(‘$triple) 查询。DuckDB 对分析型和复杂的属性过滤有极高效率。
• SQLite 利用 FTS5 扩展专门处理全文搜索。知识点的内容会被提取成 JSON 字符串，插入 SQLite 的 FTS 虚拟表中。
• 同步逻辑：在 Service 层（如 KnowledgeService::create），所有的写入操作会通过双写（Dual-write）策略同步执行：先插入 DuckDB，再将提取出的 FtsDoc 插入 SQLite。目前未看到复杂的分布式一致性保障机制，因为是本地系统，这足以应对大部分场景。

2. JSE (JSON Search Expression) 引擎

引擎目录 (src/engine/) 实现了将 JSON 查询转化为 SQL 的过程。

• Parser & AST：将客户端传来的 JSON 数组解析为抽象语法树 (AstNode)。
• SqlBuilder：核心功能，例如遇到 $knowledge‘目标，它会将内部的‘$eq, $and 转化为 WHERE name = ? AND ... 的条件片段，并将参数提取到单独的集合中，防止 SQL 注入。
• 对于带有全文搜索 ($search) 的混合查询，设计上可能是先通过 SQLite 获取命中关键词的 ID，再作为 DuckDB 查询的过滤条件，或者两套语法分开执行。

3. 数据模型

• Content 模型：允许节点和边携带元数据，通过 FtsFields 结构体，Content 中的 data, tags, synonyms 会被平铺成纯文本供 SQLite FTS5 建立索引。
• 同义词 (Synonyms)：这是一个非常关键的设计。由于抛弃了 Vector Embedding，Hypatia 无法自动理解"car"和"automobile"的语义相似性。作为补偿，它允许在创建知识时手动提供 synonyms 列表，这些词会被加入 SQLite 的 FTS 索引，从而实现近似的语义召回效果。

踩坑总结 / 对比分析