@lithium-ai/kit

Give your AI agents structured data retrieval in two commands.

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

Your agents can navigate, store, and retrieve hierarchical versioned data on your existing Postgres. No graph DB, no vector store, no new infrastructure.

Why?

AI agents need exact, structured data. Graph DBs are expensive and slow to update. Vector stores return fuzzy results. When an agent asks for everything under engineering.auth, that should be one indexed lookup.

Lithium uses PostgreSQL's ltree for tree-structured storage. Index-backed subtree queries, immutable version history, deterministic results. @lithium-ai/kit gets it running in your project in two commands.

Get Started

1. Scaffold

npx @lithium-ai/kit init

Choose your adapter interactively, or pass it directly:

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

This creates:

your-project/
  lithium/
    server.ts        # MCP server, ready to customise
    schema.sql       # PostgreSQL migrations (or schema.ts for Drizzle)
  lithium.config.json
  package.json       # deps added automatically

2. Migrate

pnpm install
psql $LITHIUM_DATABASE_URL -f lithium/schema.sql

Or with Drizzle:

pnpm install
npx drizzle-kit push

3. Serve

npx @lithium-ai/kit serve

4. Connect

Claude Code:

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

Cursor, Windsurf, or any MCP client:

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

What Your AI Tools Get

Four MCP tools, available immediately:

| Tool | What it does | |---|---| | list_clusters | See the full hierarchy | | get_context | Get all entries under a path (e.g. engineering.database) | | create_cluster | Create a new node in the tree | | create_entry | Add a versioned entry to a cluster |

Ask your AI: "What do we know about engineering?" It calls get_context with path engineering and returns every entry under that scope.

You Own the Server

lithium/server.ts lives in your project, not inside a package. It's scaffolded code, not a black box.

Add content read and write callbacks to store and retrieve your data:

const lithium = new Lithium(postgresAdapter(sql), {
  read: async (versionIds) => {
    const rows = await sql`
      SELECT entry_version_id, data
      FROM content
      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 content (entry_version_id, data) VALUES (${versionId}, ${sql.json(content)})`;
    return content;
  },
});

Add custom MCP tools. Swap adapters. Wire up auth. The scaffolded server is a starting point. serve runs whatever you put there.

How It Works

lithium.config.json tells serve where your server file is:

{
  "mcpServer": "lithium/server.ts"
}

serve loads your .env, then runs your server file using jiti for runtime TypeScript support. No build step required.

Part of Lithium

@lithium-ai/kit is the fastest way to get started with the Lithium storage engine.

| Package | What | Size | |---|---|---| | @lithium-ai/core | Storage engine | | | @lithium-ai/postgres | PostgreSQL adapter | | | @lithium-ai/drizzle | Drizzle ORM adapter | | | @lithium-ai/mcp | MCP server | | | @lithium-ai/kit | CLI toolbox | You are here |

License

MIT