如何给 AI Agent 添加结构化数据检索？Lithium-core 让 PostgreSQL ltree 成为 Agent 的确定性记忆层

问题：AI Agent 的数据检索困境

AI 编码 Agent（Claude Code、Codex、Cursor）最令人头疼的问题之一，就是它们记不住结构化信息。你的项目有清晰的架构分层，但当你让 Agent 回忆某个模块的设计文档时，它要么返回模糊的近似结果，要么编造一个不存在的路径。这不是 Agent 能力不足——而是工具链的缺失。向量数据库擅长语义近似搜索但无法回答精确查询，图数据库查询速度随规模增长急剧下降。

Lithium-core 给出了一个截然不同的答案：用 PostgreSQL ltree 作为 Agent 的结构化存储层，将层次化数据的检索从模糊搜索变成确定性的索引查找。

Lithium-core 是什么

Lithium-core 是一个 TypeScript 开源库，在 PostgreSQL 的 ltree 数据类型之上封装了一套完整的层次化存储引擎，专为 AI Agent 设计。

简单来说，它让你可以用两行命令给任何 AI 编码工具（Claude Code、Cursor、Windsurf）添加「结构化记忆」——不是模糊的向量嵌入，而是精确的、版本化的、作用域限定的树形结构。

npx @lithium-ai/kit init --adapter postgres
claude mcp add lithium -- npx @lithium-ai/kit serve

两行命令之后，你的 Agent 就有了确定性的层次化数据检索能力。

为什么是 ltree 而非向量或图？

Lithium-core 的技术选择非常务实。对比一下三种方案：

核心洞察是：AI Agent 需要的大部分「记忆」本质上是层次化的——项目结构、架构决策、团队规范、API 文档，它们天然符合树形组织。用 ltree 做索引查找，比用向量做近似搜索既快又准。

快速上手：两行命令

前提条件

• 一个 PostgreSQL 数据库（本地或远程均可）
• Node.js 18+

安装

npx @lithium-ai/kit init --adapter postgres

psql $LITHIUM_DATABASE_URL -f lithium/schema.sql

init 命令会生成一个 .env 文件，你只需要填写数据库连接字符串。schema 包含三张核心表：clusters（层次节点）、entries（条目）、entry_versions（版本控制）。

连接 AI 工具

claude mcp add lithium -- npx @lithium-ai/kit serve

{
  "mcpServers": {
    "lithium": {
      "command": "npx",
      "args": ["@lithium-ai/kit", "serve"]
    }
  }
}

连接成功后，AI 工具会获得四个 MCP 工具：list_clusters（查看层次结构）、get_context（按路径检索数据）、create_cluster（创建层次节点）、create_entry（创建版本化条目）。

实战：给一个 Web 项目建立 Agent 结构记忆

第一步：构建层次结构

假设你的项目有 4 个核心模块：基础设施、API、前端、数据库。

import { Lithium } from "@lithium-ai/core";
import { postgresAdapter } from "@lithium-ai/postgres";
import postgres from "postgres";

const sql = postgres(process.env.LITHIUM_DATABASE_URL!);
const lithium = new Lithium(postgresAdapter(sql));

// 构建层次结构
await lithium.clusters.create({ name: "engineering" });
await lithium.clusters.create({ name: "database", parentPath: "engineering" });
await lithium.clusters.create({ name: "auth", parentPath: "engineering.database" });
await lithium.clusters.create({ name: "api", parentPath: "engineering" });
await lithium.clusters.create({ name: "users", parentPath: "engineering.api" });

第二步：存储架构决策

// 在 engineering.database.auth 路径下存储认证架构决策
const authEntry = await lithium.entries.create({
  clusterId: authCluster.id,
});
// content 通过 content resolver 回调存储
// 版本 1

// 更新决策——版本自动递增
await lithium.entries.update({ id: authEntry.value.entry.id });
// 版本 2

第三步：作用域检索

// 检索 engineering 下所有内容
const allContext = await lithium.getContext({ path: "engineering" });

// 只检索 database 相关内容
const dbContext = await lithium.getContext({ path: "engineering.database" });

// 只检索 auth 相关内容——最精确
const authContext = await lithium.getContext({ path: "engineering.database.auth" });

检索是按 ltree 索引路径匹配的，时间复杂度 O(log n)。无论你的数据量多大，查询速度恒定。

第四步：配置 Agent 自动上下文加载

在 .claude/settings.json 中添加钩子，让 Agent 在每次交互前自动加载相关上下文：

{
  "UserPromptSubmit": [
    {
      "type": "command",
      "command": "echo 'Before writing or suggesting code, call mcp__lithium__list_clusters first, then call mcp__lithium__get_context for each relevant cluster to retrieve stored context.'"
    }
  ],
  "Stop": [
    {
      "type": "command",
      "command": "echo 'Only store to Lithium if a clear, concrete decision or important context emerged from this interaction. Reason about what was decided and where it fits in the existing hierarchy before writing. If unsure, do not store.'"
    }
  ]
}

这样每次与 Agent 对话时，它都会先查 Lithium 中的结构化上下文，再回答问题或写代码，而非依赖对话窗口中的碎片化记忆。

Content Resolver：你的数据你做主

Lithium-core 只存储条目版本 ID 和路径结构，实际内容通过 content resolver 回调来读写：

const lithium = new Lithium(postgresAdapter(sql), {
  read: async (versionIds) => {
    const rows = await sql`
      SELECT entry_version_id, data FROM your_content_table
      WHERE entry_version_id = ANY(${versionIds})`;
    return new Map(rows.map(r => [r.entry_version_id, r.data]));
  },
  write: async (versionId, content) => {
    await sql`INSERT INTO your_content_table (entry_version_id, data)
      VALUES (${versionId}, ${sql.json(content)})`;
  },
});

这种设计让你在享受层次化检索的同时，内容存储策略完全由你掌控。

层次结构优化策略

深路径优于宽路径。engineering.database.auth.connection-pool 比 engineering 的检索结果精确得多。每层减少一个无关结果，Agent 的真实响应质量就提升一个台阶。

按作用域划分而非按文件划分。存的是「API 设计规范」「数据库连接池配置」「认证流程决策」这样的语义单元，而非文件路径。

写入钩子控制信息质量。只有清晰的、具体的决策值得存储，避免 Lithium 被无关内容污染。

与已有方案的对比

Lithium-core 的定位不是取代向量数据库或图数据库，而是在它们力所不及的领域填补空白：

向量数据库（Pinecone、Weaviate）擅长语义相似度搜索。但当你需要「给我 engineering 下的第 2 条记录」这种精确查询时，向量索引无能为力。

图数据库（Neo4j）擅长关系查询，但对于严格树形结构用图遍历是过度设计——查询速度随深度非线性增长。

Lithium 只做一件事：树形数据的确定性检索。因为做了减法，所以每项指标都优于通用方案。

适用场景

• 项目架构知识库：让 Agent 在写代码前先查当前模块的架构规范
• API 文档索引：让 AI Agent 按路径精确查找 API 端点文档
• 配置管理：环境配置、密钥路径、服务依赖的结构化存储
• 多仓库上下文共享：通过同一个 PostgreSQL 实例，多个 Agent 共享工程知识

局限性

• 必须使用 PostgreSQL——其他数据库需要额外配置适配器
• 仅支持 ltree 路径——不适合社交图谱等非层次化关系数据
• 社区仍小（11⭐），API 可能随迭代变化

总结

Lithium-core 解决了一个被 Vector DB 和 Graph DB 忽视的空白：AI Agent 对精确、层次化、版本化的结构化数据的需求。两行命令搭建、四步 MCP 集成——如果你已经在用 PostgreSQL，这是一个零额外基础设施成本的高价值补充。

下次你的 Agent 再问「这个模块的架构规范是什么」时，答案已经躺在 ltree 索引里了。