Knowledge base

Save reusable business context so SQLsaber answers the same metric the same way.

Knowledge entries are:

Scoped to one database
Stored locally, in SQLite by default
Retrieved by the built-in search_knowledge tool when they match the question

Add an entry

name and description are required. --sql and --source are optional.

# Add to the default database
saber knowledge add "Revenue KPI" "Recognized revenue from shipped orders only"

# Add a SQL pattern and a source
saber knowledge add "Monthly revenue rollup" \
  "Use shipped orders for monthly recognized revenue" \
  --sql "SELECT date_trunc('month', shipped_at) AS month, SUM(amount) FROM orders WHERE status = 'shipped' GROUP BY 1" \
  --source "finance-wiki"

# Add to a named connection
saber knowledge add "NRR formula" "Net Revenue Retention excludes new logo revenue" -d prod-db

For long text, read from files:

saber knowledge add "Revenue definition" "$(cat ./knowledge/revenue_definition.md)"

saber knowledge add "Monthly revenue rollup" "$(cat ./knowledge/monthly_revenue_notes.md)" \
  --sql "$(cat ./sql/monthly_revenue_rollup.sql)" \
  --source "finance-wiki"

List, search, and inspect

saber knowledge list

Search by keyword. The default limit is 10:

saber knowledge search "revenue shipped" --limit 5

Show one entry by ID:

saber knowledge show a1b2c3d4-e5f6-7890-abcd-ef1234567890

Remove entries

Remove one entry:

saber knowledge remove a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Non-interactive
saber knowledge remove a1b2c3d4-e5f6-7890-abcd-ef1234567890 --yes

Clear every entry for a database:

saber knowledge clear

# Skip confirmation
saber knowledge clear --yes

How the agent uses knowledge

You do not call search_knowledge in chat. The SQLsaber agent calls it when it needs a definition, a term, or a known SQL pattern.

Search is scoped to the active database. Entries saved for one database do not appear in another.

Inject a store from Python

If you already own a knowledge store, pass it into SQLSaberOptions:

import asyncio

from sqlsaber import SQLSaber, SQLSaberOptions
from sqlsaber.knowledge import KnowledgeManager, SQLiteKnowledgeStore


async def main() -> None:
    manager = KnowledgeManager(store=SQLiteKnowledgeStore(db_path="knowledge.db"))

    await manager.add_knowledge(
        database_name="analytics",
        name="Gross margin",
        description="(Revenue - COGS) / Revenue",
        source="finance-handbook",
    )

    async with SQLSaber(
        options=SQLSaberOptions(
            database="analytics",
            model_name="anthropic:claude-sonnet-4-5-20250929",
            api_key="YOUR_API_KEY",
            knowledge_manager=manager,
        )
    ) as saber:
        result = await saber.query("How do we define gross margin?")
        print(result.text)


if __name__ == "__main__":
    asyncio.run(main())

See Advanced for lifecycle details.

See saber knowledge --help, or Commands.