Learnings & memory

NeuBird gets better with use. It automatically saves two types of knowledge from each investigation: SQL rules and table mappings. These persist across sessions and are injected into the AI’s context, helping it avoid past mistakes and skip schema exploration.

SQL learnings

When a SQL query fails or produces unexpected results (common with Foreign Data Wrappers), NeuBird saves a rule like:

• “never use JOIN”
• “avoid ILIKE — FDW cannot push it down”
• “always aggregate before filtering”

These rules are scoped to a specific schema and stored as plain text files at:

~/.config/neubird/learnings/<schema>.txt

Each rule is a short, imperative instruction (max 8 words). On the next session, these rules are loaded into the system prompt so the AI follows them from the start.

Viewing learnings

Use the /learnings slash command to see all saved SQL rules:

> /learnings

This shows rules grouped by schema.

How they work

1. NeuBird runs a query that fails or returns unexpected results
2. The AI calls save_sql_learning with a concise rule
3. The rule is deduplicated and appended to the schema’s file
4. Next session, all rules are loaded and included in the system prompt

Table learnings

At the end of a successful investigation, NeuBird saves which tables were useful for that type of investigation. For example:

latency, p99, response time → metrics.http_duration, traces.spans
  Notes: Use duration column for p99, filter by service_name

These are stored as JSON at:

~/.config/neubird/tablelearnings/

Table learnings include:

• Scenario keywords — Comma-separated terms describing the investigation type
• Tables — Fully qualified table names that contained useful data
• Notes — Brief notes on key columns and usage

How they work

1. NeuBird completes a successful investigation
2. The AI calls save_table_learning with scenario keywords and useful tables
3. If a matching scenario already exists, the entry is updated (tables merged, notes refreshed)
4. Next session, matching scenarios are injected as “known useful tables” in the system prompt
5. The AI can skip schema exploration and go straight to the right tables

Tip

Table learnings are capped at 50 entries. Old entries are automatically evicted when the cap is reached. Scenarios with overlapping keywords are merged rather than duplicated.

Storage locations

Learning type	Location	Format
SQL rules	~/.config/neubird/learnings/<schema>.txt	Plain text, one rule per line
Table mappings	~/.config/neubird/tablelearnings/	JSON files by scenario

Both are human-readable and can be manually edited if needed.