如何给 AI Agent 接入结构化数据存储：Lithium + PostgreSQL ltree 实战

2026-06-06 · 技术指南

如果你在用 AI 编码工具（Claude Code、Cursor、Codex）处理项目时遇到过一个尴尬的问题——Agent 记不住你之前做过的架构决策，每次对话都要重新解释上下文——那你不是一个人。

现在主流方案是向量数据库 + Pinecone 做语义搜索，或者用 Memory Graph 做知识图谱。但这两种方案对 AI Agent 来说都有点”打偏了”：Agent 需要的不是”和这段话相似的内容”，而是“engineering.auth 目录下的所有配置”。这是一个精确的结构化查询，不是模糊的相似度搜索。

Lithium 就是在解决这个问题。它是一个用 TypeScript 写的存储引擎，构建在 PostgreSQL 的 ltree 扩展之上，给 AI Agent 提供层次化、带版本、有作用域的结构化数据检索能力。本文介绍如何上手。

为什么 Agent 需要结构化数据

先理解一下问题的本质。

当你让 Agent 开发一个功能，它需要知道：

• 项目的架构分层是什么
• 数据库表结构是什么样的
• 之前的接口设计决策是什么

这些信息天然是树形结构的：项目 → 模块 → 子模块 → 配置项。向量搜索给不出精确的树形查询结果（”engineerig”相关的内容可能返回30条文档摘要，但没有一条是你要的 auth 模块配置）。图数据库虽然能做树形查询，但需要单独部署和维护一套基础设施。

Lithium 的思路很直接：你的 PostgreSQL 数据库已经在跑着了，它的 ltree 扩展就是为树形数据设计的。 不需要新服务，不需要新基础设施，两行命令就能让 Agent 获得精确的结构化数据检索能力。

快速上手

Lithium 提供了 5 个 npm 包，但普通人只需要一个命令就能跑起来。

前置条件

• Node.js 18+
• 一个可用的 PostgreSQL 数据库（本地或远程都可以）
• Claude Code（或其他支持 MCP 的 AI 编码工具）

第一步：初始化

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

这个命令会在当前目录生成 lithium/schema.sql 文件和项目结构。

第二步：创建数据库表

psql $LITHIUM_DATABASE_URL -f lithium/schema.sql

就这么简单。这条 SQL 会创建三张核心表：clusters（集群/节点）、entries（条目）和 entry_versions（版本）。

第三步：连接 AI 工具

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

现在 Claude Code 就多了四个 MCP 工具可以用：list_clusters、get_context、create_cluster、create_entry。

如果你用 Cursor 或 Windsurf，在 MCP 配置文件中加一段：

{
  "mcpServers": {
    "lithium": {
      "command": "npx",
      "args": ["@lithium-ai/kit", "serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

实战：构建项目知识层次

假设你正在用 Lithium 管理一个后端项目的架构知识。先创建层次结构：

const lithium = new Lithium(postgresAdapter(sql));

// 创建顶层节点
await lithium.clusters.create({ name: "project" });

// 创建子节点
await lithium.clusters.create({
  name: "infrastructure",
  parentPath: "project"
});
await lithium.clusters.create({
  name: "database",
  parentPath: "project.infrastructure"
});
await lithium.clusters.create({
  name: "auth",
  parentPath: "project.infrastructure"
});

// 找出刚创建的 auth 节点
const authCluster = await lithium.clusters.findByPath({
  path: "project.infrastructure.auth"
});

// 在 auth 节点下存储配置
const entry = await lithium.entries.create({
  clusterId: authCluster.value.id
});
await lithium.entries.update({ id: entry.value.entry.id });
// → 自动创建 v2

当你或者 Agent 需要了解 auth 模块的相关信息时，只需要查询作用域：

const context = await lithium.getContext({
  path: "project.infrastructure.auth"
});
// 返回该路径下的所有 clusters、entries 和版本

关键点在于 ltree 索引让这个查询是精确的、确定性的，不像向量搜索那样需要调相似度阈值。

与 AI Agent 的自动化集成

Lithium 真正出彩的地方在于它的Hooks 集成。你可以在 Claude Code 的配置中设置两个自动钩子：

读钩子（每次对话前自动拉取上下文）：

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "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": [
    {
      "matcher": "",
      "hooks": [
        {
          "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 的每个条目都有自动递增的版本号。每次 update() 操作都创建新版本，旧版本不会被覆盖。

entry_versions
  id: 1, entryId: 42, version: 1
  id: 2, entryId: 42, version: 2  ← 最新

这让你可以回溯 Agent 的决策历史。如果某个自动化操作写入了错误的配置，可以比较 v1 和 v2 的内容差异来恢复。

与向量搜索和图数据库的对比

适用场景

• Agent 项目知识库：架构决策、API 规范、配置参数的结构化管理
• 多模块配置中心：微服务架构下的配置版本控制
• 团队 Onboarding 文档：树形结构的团队知识库，Agent 可自动检索
• 文档层次管理：按项目→模块→子模块组织技术文档

注意事项

1. 层次深度设计很重要：Lithium 按路径检索，路径越深返回结果越精确。建议优化树的深度而非宽度
2. 内容存储在你的表里：Lithium 的 Entry 只存结构骨架，你的业务数据存在自己的表中，通过 entryVersionId 外键关联
3. Result 模式：所有 API 返回 Result 而非抛出异常——TypeScript 的类型系统会强制你处理错误情况

总结

Lithium 解决了一个被很多人忽视的问题：AI Agent 需要的不是更好的搜索，而是更好的结构化数据访问。它不引入新基础设施，构建在你已有的 PostgreSQL 之上，通过 MCP 协议直接对接主流 AI 编码工具。如果你厌倦了 Agent 每次对话都”失忆”，Lithium 值得一试。

GitHub: github.com/0xJaksun/lithium-core
npm:   @lithium-ai/kit
协议:  MIT