Skip to main content
Glama
deenesjakoruzh
SurajKGoyal

amnesic

by SurajKGoyal
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

amnesic — der MCP-Server mit dem ironischsten Namen im Registry

PyPI version Python License: MIT MCP Registry Glama score

Das institutionelle Gedächtnis deiner Datenbank, als MCP-Server. Der Name ist ironisch – er erinnert sich an alles.

„Der MCP-Server mit dem ironischsten Namen im Registry. Er ist alles andere als amnesisch – er erinnert sich an deine Datenbank, damit deine KI es nicht tun muss."

Die meisten Datenbank-MCP-Server sind Query-Executors: Sie verbinden sich, untersuchen, führen SQL aus und vergessen. amnesic ist ein semantisches Gedächtnis – es sammelt, was dein Schema bedeutet (was status = 3 ist, welche Spalten wirklich Fremdschlüssel sind, wofür diese Legacy-Tabelle gut ist) und übergibt es jeder zukünftigen Sitzung automatisch. Stell dir einen Datenkatalog vor, minus Plattform, minus Ingestions-Pipeline, minus Rechnung. Wo amnesic passt ↓

Funktioniert mit Claude Code · Claude Desktop · Cursor · VS Code · Cline · Windsurf – jedem MCP-kompatiblen Client.

Verfügbar auf Offizielles MCP-Registry · Claude-Code-Plugin-Marketplace

👋 Nutzt du amnesic? Sag Hallo im Adopters-Thread – Download-Zahlen sagen mir nicht, was tatsächlich verwendet wird, und das beeinflusst direkt, was als Nächstes gebaut wird.

🔒 Von Natur aus schreibgeschützt. amnesic weigert sich, INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE, EXEC, MERGE, GRANT, REVOKE auszuführen – und auch jede Schreibanweisung, die in einem WITH-CTE versteckt ist. Zwei Verteidigungsebenen: Statische SQL-Analyse lehnt die Anweisung ab, bevor eine Verbindung hergestellt wird, und jede Abfrage läuft in einer Transaktion, die sofort zurückgerollt wird. Sicher, um auf Produktion zu zeigen. Details ↓

Das Problem

Jede Sitzung mit einer KI beginnt kalt. Du verbringst die ersten Minuten damit, erneut zu erklären, welche Tabellen existieren, was ein status-Spaltenwert von 3 bedeutet, welcher FK orders mit users verbindet. Dann endet die Sitzung, und morgen machst du alles noch einmal.

amnesic behebt das. Es gibt deiner KI einen persistenten SQLite-Wissensspeicher – einen pro Datenbank – der über Sitzungen hinweg überlebt. Annotiere einen Status-Enum einmal; jede zukünftige Sitzung sieht diese Labels automatisch. Entdecke FK-Beziehungen einmal; jede zukünftige JOIN-Abfrage nutzt diesen Graphen.

Das Wissen ist auch portabel und überlebt deinen Zugriff auf die Datenbank. Wenn du von einem Projekt abgezogen wirst, übergibt amnesic export dem nächsten Entwickler alles, was du ihm beigebracht hast – Jahre von „oh, diese Spalte bedeutet eigentlich…", die sonst mit dir gehen würden.

Related MCP server: engram-mcp

Wo amnesic passt

Das Datenbank-MCP-Ökosystem teilt sich in zwei Lager, und amnesic ist bewusst in keinem von beiden.

Query-Executors – DBHub, Postgres MCP Pro, Googles MCP-Toolbox und die Vendor-Server (Supabase, Neon). Sie untersuchen live, führen SQL aus, und einige gehen tief in die Performance – Postgres MCP Pro macht echtes Index-Tuning und PgHero-artige Health-Checks. Sie sind darin exzellent. Sie sind auch zustandslos: Jede Sitzung lernt dein Schema von Grund auf neu, und nichts, was sie zurückgeben, kann dir sagen, was eine Spalte bedeutet, weil die Datenbank es auch nicht weiß.

Enterprise-Kataloge – DataHub, Atlan, Cube, AtScale. Diese halten semantischen Kontext: Glossare, Spaltenbeschreibungen, Eigentümerschaft, Linie. Sie sind auch eine Plattform-Verpflichtung – Metadaten-Ingestion, ein Dienst, der läuft, normalerweise eine kostenpflichtige Stufe. Bei Unternehmensgröße lohnenswert; unverhältnismäßig für einen einzelnen Entwickler, der sich merken muss, was sechs Statuscodes in einer Legacy-MSSQL-Datenbank bedeuten, die niemand jemals in einen Katalog aufnehmen wird.

amnesic ist das Dritte: Katalogreifes semantisches Gedächtnis zu den Einrichtungskosten eines Query-Executors. pipx install, eine TOML-Datei, eine lokale SQLite-Datei pro Datenbank. Keine Plattform, keine Ingestion, kein Server, der läuft.

Ehrlicher Vergleich

amnesic

Query-Executors

Enterprise-Kataloge

Semantischer Kontext (was ein Wert bedeutet)

✅ persistent, dein

❌ keiner

✅ plattformverwaltet

Überlebt Sitzungen

✅

❌

✅

Portabel / überlebt DB-Zugriff

✅ export/import

❌

⚠️ plattformgebunden

Einrichtungskosten

ein Befehl

ein Befehl

Ingestions-Pipeline

Live-Schema-Frische

⚠️ gecacht, manuelle Aktualisierung

✅ immer live

⚠️ Ingestions-Verzögerung

Ausführungspläne / Index-Tuning

❌

✅ (Postgres MCP Pro)

❌

Linie / Eigentümerschaft / Governance

❌

❌

✅

Funktioniert auf Legacy-Schemata ohne FK-Constraints

✅ annotiere sie selbst

❌ nichts zu untersuchen

⚠️ braucht Ingestion

Verwende einen Query-Executor statt amnesic, wenn du Ausführungspläne, Index-Empfehlungen oder Datenbank-Health-Diagnosen willst – das ist nicht amnesics Aufgabe, und es hinzuzufügen würde es zu einer schlechteren Version eines Tools machen, das bereits existiert.

Verwende amnesic neben einem. Sie komponieren: Nichts hindert dich daran, beide laufen zu lassen. amnesic hält die Bedeutung; sie halten die Maschinerie.

Die mit ⚠️ markierten Zeilen oben sind bekannte Lücken mit offenen Issues – siehe Roadmap ↓.

Schnellstart (90 Sekunden)

pipx install amnesic            # install the core
amnesic init                    # interactive wizard

⚡ Probiere es ohne Anmeldedaten aus. Führe stattdessen amnesic init --demo aus – es fügt eine eigenständige SQLite-Beispieldatenbank hinzu (E-Commerce-Schema: Kunden / Produkte / Bestellungen mit FKs und einer Enum-Spalte), sodass du jedes Tool in unter einer Minute ausprobieren kannst. Großartig für einen ersten Blick, bevor du amnesic auf eine echte Datenbank richtest.

Der Assistent fragt, mit welchem Datenbanktyp du dich verbindest, und nennt dir den einen Befehl, den du ausführen musst, falls sein Treiber noch nicht installiert ist – du musst nie im Voraus raten, was zusätzlich nötig ist.

Der Assistent:

  • Fragt nach Datenbanktyp, Host und Anmeldedaten

  • Testet die Verbindung, bevor er etwas speichert

  • Speichert das Passwort sicher in ~/.config/amnesic/.env (chmod 600)

  • Schreibt den Verbindungsblock in ~/.config/amnesic/connections.toml

Dann füge amnesic zu deinem KI-Client hinzu und starte neu.

Installiere pipx (einmalig):

brew install pipx                                  # macOS
sudo apt install pipx                              # Linux (Debian/Ubuntu)
python -m pip install --user pipx                  # Windows / generic

Oder verwende uv (Single-Binary-Alternative – schnell, kein Python nötig):

brew install uv                                            # macOS
curl -LsSf https://astral.sh/uv/install.sh | sh            # Linux / macOS
powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows

uv tool install amnesic

Oder normales pip (installiert in deine aktive Python-Umgebung):

pip install amnesic

Egal, was du wählst, amnesic init fragt, mit welcher Datenbank du dich verbinden wirst, und gibt den einen zusätzlichen Befehl aus, um diesen Treiber zu installieren – keine Notwendigkeit, sich im Voraus auf Extras festzulegen.

Nach der Installation funktioniert amnesic --help von jedem Terminal aus.

Wo amnesic Dinge speichert

Datei

macOS / Linux

Windows

Konfiguration

~/.config/amnesic/connections.toml

%APPDATA%\amnesic\connections.toml

Geheimnisse

~/.config/amnesic/.env (chmod 600)

%APPDATA%\amnesic\.env (Benutzerprofil-ACL)

Wissen

~/.config/amnesic/knowledge_<name>.db

%APPDATA%\amnesic\knowledge_<name>.db

Setze $AMNESIC_HOME (oder $XDG_CONFIG_HOME unter Linux), um den Speicherort zu überschreiben.

Später weitere Verbindungen hinzufügen

amnesic add          # add another connection to existing config
amnesic test         # verify all connections
amnesic test orders.prod  # verify one connection

Passwörter setzen und rotieren

amnesic init und amnesic add speichern dein Passwort automatisch – für den typischen Einrichtungsablauf musst du diesen Abschnitt nie beachten.

Verwende set-secret, wenn du ein gespeichertes Passwort später ändern musst – die IT hat es rotiert, du hast es bei der Einrichtung falsch getippt, oder du bearbeitest die Konfiguration von Hand.

$ amnesic set-secret ORDERS_PROD_PASSWORD
Value: ****            ← hidden input (your typing is invisible)
Confirm: ****
✓ Set ORDERS_PROD_PASSWORD in ~/.config/amnesic/.env

Wie lautet der Variablenname? Es ist die Umgebungsvariable, auf die deine connections.toml für das Passwort dieser Verbindung verweist. Der Assistent generiert diese automatisch als <CONNECTION_NAME_UPPERCASE_WITH_UNDERSCORES>_PASSWORD:

Verbindungsname

Generierte Umgebungsvariable

orders.prod

ORDERS_PROD_PASSWORD

analytics

ANALYTICS_PASSWORD

drive.staging

DRIVE_STAGING_PASSWORD

Um den genauen Namen zu sehen, den deine Konfiguration verwendet, schaue in ~/.config/amnesic/connections.toml – alles innerhalb von ${...} ist die Variable, die du an set-secret übergeben musst.

Unter der Haube: Schreibt (oder ersetzt) die Zeile in ~/.config/amnesic/.env, setzt die Dateiberechtigung auf chmod 600 (nur dein Benutzer kann sie lesen), erhält alle anderen Einträge.

Verbindungen und Wissen verwalten

Wissen sammelt sich pro Verbindung in einer lokalen SQLite-Datei. Diese Befehle ermöglichen es dir, es zwischen Maschinen zu verschieben und aufzuräumen:

# Hand off everything you've taught amnesic about a database (annotations +
# relationships, not the re-derivable schema cache) as portable JSON:
amnesic export orders.prod -o orders-knowledge.json
amnesic export orders.prod            # or print to stdout to pipe/redirect

# Load that knowledge into another connection (e.g. promote staging → prod,
# or onboard a teammate). Unconditional upsert — existing entries are overwritten:
amnesic import orders.prod orders-knowledge.json

# Wipe stored knowledge for a connection but keep the config entry:
amnesic clear orders.staging

# Drop a connection from connections.toml entirely (knowledge file kept
# unless you pass --delete-knowledge):
amnesic remove old.connection
amnesic remove old.connection --delete-knowledge

export/import/clear/remove arbeiten ausschließlich mit lokalen Dateien – sie verbinden sich nie mit der Datenbank, funktionieren also auch, wenn die Anmeldedaten einer Verbindung nicht gesetzt sind. remove bearbeitet connections.toml mit chirurgischen String-Änderungen und lässt die Formatierung und Kommentare jedes anderen Blocks byte-für-byte intakt.

Zu deinem KI-Client hinzufügen

Sobald amnesic mit den richtigen Treiber-Extras installiert ist (siehe Schnellstart), ist der Befehl amnesic in deinem PATH. Verwende denselben Ausschnitt in jedem MCP-Client:

Claude Code

Einzeilige Installation (empfohlen – kein JSON-Bearbeiten). Innerhalb von Claude Code:

/plugin marketplace add https://github.com/SurajKGoyal/amnesic-marketplace
/plugin install amnesic@amnesic

Das verdrahtet amnesic automatisch als MCP-Server. Quelle: SurajKGoyal/amnesic-marketplace.

{
  "mcpServers": {
    "amnesic": {
      "command": "amnesic"
    }
  }
}

Claude Desktop

Füge zur Claude-Desktop-Konfiguration deiner Plattform hinzu:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "amnesic": {
      "command": "amnesic"
    }
  }
}

Cursor

Ein-Klick-Installation – klicke auf den Button unten und Cursor verdrahtet es für dich:

Füge zu .cursor/mcp.json in deinem Projekt hinzu (oder global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "amnesic": {
      "command": "amnesic"
    }
  }
}

Ohne globale Installation (ephemer)

Wenn du amnesic lieber nicht auf deinem System installierst, verwende uvx oder pipx, um es bei jedem Start des MCP-Clients abzurufen. Beachte, dass die Treiber-Extras explizit übergeben werden müssen:

// uvx — requires `uv` installed (see Install section for per-OS instructions)
{
  "mcpServers": {
    "amnesic": {
      "command": "uvx",
      "args": ["--from", "amnesic[mssql]", "amnesic"]
    }
  }
}

// pipx — usually pre-installed via Homebrew or system package manager
{
  "mcpServers": {
    "amnesic": {
      "command": "pipx",
      "args": ["run", "--spec", "amnesic[mssql]", "amnesic"]
    }
  }
}

Für mehrere Treiber, kommagetrennt innerhalb der Klammern – z. B. amnesic[postgres,mssql] oder verwende amnesic[all] für alles.

VS Code (mit MCP-Erweiterung)

Füge zu .vscode/mcp.json hinzu:

{
  "servers": {
    "amnesic": {
      "type": "stdio",
      "command": "amnesic"
    }
  }
}

Aktualisieren

amnesic wird oft veröffentlicht. Aktualisiere mit demselben Tool, mit dem du es installiert hast:

Installiert über

Upgrade-Befehl

pipx

pipx upgrade amnesic

uv tool

uv tool upgrade amnesic

pip

pip install --upgrade amnesic

uvx (ephemeral, in deiner MCP-Konfig)

uvx cached Builds — führe uv cache clean amnesic aus, um die neueste Version zu holen

Starte dann deinen MCP-Client neu (Claude Code, Cursor, …), damit er den amnesic-Server neu startet und neue Tools übernimmt.

Das Upgrade ist sicher — du verlierst keine Annotationen. Deine Wissensdateien werden beim ersten Laden automatisch auf das neue Schema migriert; amnesic fügt nur Spalten hinzu, löscht aber nie deine Daten.

So prüfst du die installierte Version: amnesic --version. Neueste Version: PyPI · Releases.

Tools

Tool

Beschreibung

db_list_connections()

Alle konfigurierten Verbindungen auflisten (keine Geheimnisse werden offengelegt)

db_list_tables(connection)

Alle bekannten Tabellen mit Beschreibungen und Spaltenanzahl

db_search(query, connection, target, limit)

BM25-Suche über Tabellen-/Spaltenbeschreibungen und Aliase

db_get_schema(table, connection)

Spaltenschema, zusammengeführt mit gespeicherten Annotationen

db_query(sql, connection)

Eine schreibgeschützte SELECT-Abfrage ausführen

db_annotate(table, connection, ...)

Semantische Annotationen für Tabellen/Spalten dauerhaft speichern

db_deprecate(table, connection, column?, reason?, undo?)

Eine veraltete Annotation weich zurückziehen — markiert (und gewarnt), aber behalten, umkehrbar

db_detect_drift(connection)

Annotationen gegen das Live-Schema prüfen — verwaiste Annotationen + undokumentierte Tabellen finden

db_forget(table, connection, column?, cascade?)

Annotation hart löschen (Cascade optional) — dauerhaft

db_sync_knowledge(from, to)

Annotationen zwischen Verbindungen kopieren (z. B. Staging → Prod)

db_discover_relationships(connection)

Alle Fremdschlüssel-Beziehungen aus der Live-DB ermitteln

db_get_relationships(table, connection)

Den Fremdschlüssel-Graphen für die JOIN-Planung durchsuchen

Suche in der Wissensdatenbank

Bei großen Schemata ist db_list_tables unpraktisch — du würdest 500+ Zeilen in den Kontext von Claude laden. Verwende stattdessen db_search, um die relevanten Tabellen/Spalten per Stichwort zu finden:

"What table tracks customer payments?"
  → db_search("payments")
    Top results:
      - dbo.payments  (table) "Customer payment records..."
      - dbo.orders.payment_method  (column) "Mode of payment..."

db_search verwendet SQLite FTS5 mit BM25-Ranking — schnell, lokal, ohne Embeddings oder externe Dienste. Die Suchsyntax unterstützt:

Syntax

Wirkung

payment

Wort finden (mit Stammformreduktion — findet auch „payments", „paying")

"payment method"

Exakte Phrase

pay*

Präfix-Treffer — „payment", „payable", usw.

payment AND status

Beide Begriffe erforderlich

payment OR refund

Einer der beiden Begriffe

Die Ergebnisse liefern nach Relevanz sortierte Tabellen-/Spaltenzeilen mit Beschreibungen und hervorgehobenen Ausschnitten.

Die Wissensebene

Das entscheidende Unterscheidungsmerkmal. Jede Annotation überlebt Neustarts, Modell-Updates und neue Sitzungen.

Sitzung 1 — du entdeckst etwas

You: What does status=3 mean in the orders table?
AI: Let me check. [runs db_query: SELECT DISTINCT status FROM dbo.orders]
    I see values 1, 2, 3, 4. Let me look at some examples...
    Based on the data, 3 appears to be "cancelled".

You: Save that. And status=1 is "pending", 2 is "confirmed", 4 is "delivered".
AI: [calls db_annotate]
    db_annotate(
      table="dbo.orders",
      column="status",
      column_description="Order lifecycle status",
      enum_values={"1": "pending", "2": "confirmed", "3": "cancelled", "4": "delivered"}
    )
    Saved. Future sessions will see these labels automatically.

Sitzung 2 — das Wissen ist bereits da

You: How many cancelled orders are there this month?
AI: [calls db_get_schema("dbo.orders")]
    Schema response includes:
      column: "status"
      description: "Order lifecycle status"
      enum_values: {"1": "pending", "2": "confirmed", "3": "cancelled", "4": "delivered"}

    [writes correct SQL immediately]
    SELECT COUNT(*) FROM dbo.orders WHERE status = 3 AND ...

Kein erneutes Entdecken. Keine verschwendeten Schritte. Die Annotation wurde gespeichert.

Beziehungsgraph

Verstehe die JOIN-Struktur deines Schemas einmal und nutze sie für immer.

AI: [db_discover_relationships(connection="orders.prod")]
    Discovered 47 foreign key relationships.

AI: [db_get_relationships(table="orders", depth=2)]
    neighbors:
      orders → users (via user_id → id)
      orders → order_items (via id ← order_id)
    paths:
      orders -> users
      orders -> order_items
      order_items -> products

Jetzt weiß die KI genau, wie sie über dein Schema JOINen muss, ohne zu raten.

Synchronisierung zwischen Umgebungen

Baue Annotationen im Staging auf und übertrage sie dann in die Produktion:

db_sync_knowledge(from_connection="orders.staging", to_connection="orders.prod")

Gibt {synced: [...], skipped: [{table, reason}], warnings: [{table, column, reason}]} zurück.

Tabellen, die im Ziel-Schema-Cache fehlen, werden mit einem klaren Grund übersprungen. Spalten, die im Ziel-Schema fehlen, erzeugen eine Warnung, blockieren aber nicht den Rest der Synchronisierung.

Fortgeschritten: die TOML-Datei manuell bearbeiten

Wenn du die Konfigurationsdatei lieber selbst verwaltest, generiere eine leere Vorlage:

amnesic init --template

Das schreibt ~/.config/amnesic/connections.toml mit kommentierten Beispielen und beendet sich — ohne Assistenten. Bearbeite die Datei direkt:

# ~/.config/amnesic/connections.toml

# Nested style: [connections.product.env]
[connections.orders.prod]
driver = "mssql"
server = "localhost"
port = 11433
database = "OrdersDB"
user = "${ORDERS_USER}"
password = "${ORDERS_PROD_PASSWORD}"
tunnel_script = "~/.scripts/mssql-tunnel.sh"     # macOS / Linux (bash)
# tunnel_script = "C:/scripts/mssql-tunnel.ps1"  # Windows (PowerShell)

[connections.orders.staging]
driver = "mssql"
server = "localhost"
port = 11434
database = "OrdersDB_Staging"
user = "${ORDERS_USER}"
password = "${ORDERS_STAGING_PASSWORD}"

# Flat style: [connections.name]
[connections.analytics]
driver = "postgres"
server = "analytics.company.com"
port = 5432
database = "warehouse"
user = "${ANALYTICS_DB_USER}"
password = "${ANALYTICS_DB_PASSWORD}"

# SQLite — no credentials needed
[connections.local]
driver = "sqlite"
database = "/absolute/path/to/local.db"       # macOS / Linux
# database = "C:/path/to/local.db"            # Windows (use forward slashes)

Verwende ${ENV_VAR} für Zugangsdaten — niemals Passwörter hartkodieren.

Geheimnisse werden automatisch aus ~/.config/amnesic/.env geladen (Format: KEY=VALUE, eine pro Zeile, # für Kommentare). Für jede ${VAR_NAME}-Referenz in deiner TOML-Datei fülle den passenden .env-Eintrag mit amnesic set-secret VAR_NAME aus (verdeckte Eingabe, chmod 600) oder schreibe .env selbst.

Kanonische Verbindungsnamen verwenden Punktnotation: orders.prod, orders.staging, analytics, local.

Unterstützte Datenbanken

Datenbank

Python-Treiber

Installiert durch

PostgreSQL

psycopg2-binary

Assistenten-Hinweis bei Postgres-Auswahl, oder amnesic[postgres]-Extras

MySQL / MariaDB

pymysql

Assistenten-Hinweis bei MySQL-Auswahl, oder amnesic[mysql]-Extras

Microsoft SQL Server

pymssql

Assistenten-Hinweis bei MSSQL-Auswahl, oder amnesic[mssql]-Extras

SQLite

stdlib sqlite3

immer verfügbar — keine Extras

Sicherheit & Schreibschutz-Erzwingung

amnesic ist darauf ausgelegt, sicher gegen Produktionsdatenbanken gerichtet zu werden.

Warum deine KI deine Daten nicht beschädigen kann

Jede Abfrage durchläuft zwei unabhängige Ebenen, bevor sie die Datenbank erreicht:

  1. Statische Analyse (in amnesic/readonly.py) — das SQL wird tokenisiert und abgelehnt, wenn es eines der folgenden enthält: INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE, EXEC, EXECUTE, MERGE, BULK, GRANT, REVOKE, DENY. Das umfasst auch Schreibanweisungen, die in CTEs eingeschleust werden (WITH x AS (SELECT ...) UPDATE ... wird erkannt und abgelehnt).

  2. Transaktions-Rollback — selbst wenn eine Schreibanweisung die statische Prüfung irgendwie umgeht, läuft die Abfrage innerhalb von BEGIN TRANSACTION ... ROLLBACK, sodass niemals etwas committet wird. Doppelte Absicherung.

Nur SELECT und WITH ... SELECT erreichen die Datenbank. Kommentare werden vor der Analyse entfernt, sodass /* DELETE FROM users */ nicht zum Verstecken eines Angriffs verwendet werden kann.

Weitere Sicherheitsmaßnahmen

  • Keine Zugangsdaten in Antworten: db_list_connections entfernt Passwörter und Benutzernamen aus der Ausgabe. Die KI kann sehen, welche Verbindungen existieren, aber nie, wie sie sich authentifiziert.

  • Zugangsdaten nur über Umgebungsvariablen: ${ENV_VAR}-Erweiterung beim Laden der Konfiguration — Passwörter landen nie in connections.toml auf der Festplatte.

  • Sichere .env-Speicherung: unter macOS/Linux chmod 0o600 (nur Besitzer lesen/schreiben); unter Windows liegt die .env in %APPDATA%, das durch Windows-ACLs auf dein Benutzerprofil beschränkt ist.

  • Bezeichner-Validierung: Tabellen-/Schema-/Datenbanknamen werden vor jeder String-Interpolation in SQL gegen [A-Za-z0-9_]+ geprüft.

  • Getestet: 40+ Unit-Tests in tests/test_readonly.py decken jedes Schreib-Schlüsselwort, Kommentar-Entfernungs-Grenzfälle, CTE-mit-Schreibversuche, durch Semikolon getrennte Mehrfachanweisungen und Bezeichner-Injektionsversuche ab. pytest tests/test_readonly.py, um es auf deinem Rechner zu verifizieren.

Ist das mit meinen Daten sicher?

amnesic ist rein lokal und rein protokollbasiert. Es führt keine neue externe Vertrauensgrenze ein — die Vertrauensgrenze liegt dort, wo dein MCP-Client Daten hinsendet, nicht bei amnesic selbst. Die Wahl des KI-Clients bestimmt die Richtlinie, die für deine Zeilen gilt.

your DB → amnesic (local) → MCP client → your AI deployment
                                          ↑ trust boundary lives here

Die ehrliche Frage, ob Indie-Entwickler oder Unternehmen:

Vertraue ich meinem KI-Client die Daten in dieser Datenbank an?

Wenn ja — und bei den meisten Einrichtungen ist die Antwort ja — bist du gut aufgestellt. Das umfasst:

  • Solo-Entwickler mit Claude Pro / Cursor / Copilot, die ihre eigenen Projekte, Dev-Datenbanken oder Testdaten verwenden

  • Nebenprojekte, die persönliche SQLite- oder selbst gehostete Postgres-Datenbanken abfragen

  • Open-Source-Maintainer, die mit öffentlichen Schemata arbeiten

  • Teams mit Unternehmens-KI mit expliziter Isolierung: AWS Bedrock (Tenant + IAM), Azure OpenAI (regionsgebunden, dein Abonnement), Anthropic Enterprise (keine Datenspeicherung, Trainings-Opt-out), Vertex AI (dein GCP-Projekt), selbst gehostet (Ollama, vLLM, On-Premises-Claude/GPT — Daten verlassen nie das Netzwerk)

  • Alle mit einem bezahlten KI-Plan mit Null-Speicher-Garantien und einer DPA, die deine Nutzung abdeckt

Einen genaueren Blick wert, wenn

  • Deine Datenbank Daten anderer Personen enthält (Benutzer, Kunden, Patienten) und du nicht verifiziert hast, dass die Bedingungen deines KI-Anbieters diese Verarbeitung abdecken

  • Du Consumer-KI (kostenlos / persönliches Pro) UND regulierte Daten verwendest — PHI (HIPAA-geschützte Einrichtung), Kartendaten (PCI-DSS), eingeschränkte personenbezogene Daten gemäß DSGVO / Indiens DPDP-Gesetz

  • Dein Arbeitgeber eine explizite Richtlinie hat, die die Nutzung externer KI-Tools auf Produktionsdatenbanken einschränkt

  • Du unter Datenresidenz-Regeln stehst, bei denen Zeilen eine bestimmte Region nicht verlassen dürfen

Datenminimierung ist eingebaut

Eine Eigenschaft des Designs, kein nachträglicher Gedanke: Die Annotationsebene bedeutet, dass die KI die meisten Schemafragen aus einer lokalen SQLite-Wissensdatei beantwortet — kein db_query läuft, keine Zeilendaten werden irgendwohin gesendet.

  • „Was bedeutet status=3?" → wird aus deiner gespeicherten Annotation beantwortet

  • „Wie verbinden sich orders mit users?" → wird aus dem Fremdschlüssel-Graphen beantwortet

  • „Welche Tabellen haben eine created_at-Spalte?" → wird aus dem Schema-Cache beantwortet

Für rein strukturelle Erkundungen berühren sechs Tools deine Daten nie: db_list_tables, db_get_schema, db_search, db_annotate, db_discover_relationships, db_get_relationships. Sie liefern nur Metadaten.

Das ist messbar weniger Datenbewegung als ein „nackter" SQL-MCP — der jedes Mal SELECT DISTINCT status FROM orders ausführen muss, wenn die KI bei einem Enum unsicher ist. amnesic beantwortet das einmal aus lokalen Annotationen.

Haftungsausschluss: amnesic wird wie besehen unter der MIT-Lizenz bereitgestellt (keine Garantie, keine Haftung — siehe LICENSE). Dieser Abschnitt ist keine Rechts- oder Compliance-Beratung. Deine Nutzung von amnesic und des KI-Clients, mit dem du es verbindest, liegt in deiner Verantwortung. Wenn du regulierte Daten verarbeitest, konsultiere dein Sicherheits-/Compliance-Team, bevor du es auf die Produktion richtest.

Roadmap

Bisher ausgeliefert: die Wissensebene (v0.1), BM25-Suche (v0.1.5), Lebenszyklusverwaltung — Deprecate / Drift-Erkennung / Forget (v0.2) und portabler Wissensexport/-import (v0.2.2).

Als Nächstes (v0.3 — „Earn the memory"): Wissen, das sich ohne manuelle Eingabe ansammelt — automatische Enum-Erkennung, Soft-FK-Inferenz für Legacy-Schemata ohne Constraints und JOIN-Muster-Lernen. Dazu die Grundlagenarbeit: ein Token-Budget für jede Antwort, Indizes und Primärschlüssel im Schema-Abruf, Cache-Veraltungs-Flags und eine kleinere Tool-Oberfläche.

Siehe ROADMAP.md für das Gesamtbild und die Begründung hinter der Reihenfolge.

🙌 Beiträge erwünscht

Jeder v0.3-Punkt ist als GitHub-Issue mit bereits durchdachtem Design erfasst – das Problem, die vorgeschlagene Form, die zu ändernden Dateien und wie man es testet. Mehrere sind mit good first issue gekennzeichnet.

Wähle einen aus und öffne einen PR – du musst nicht vorher fragen. Kommentiere einfach das Issue, damit nicht zwei Personen dasselbe bauen.

Hast du eine Idee, die nicht aufgeführt ist? Öffne ein Issue. Ein Anwendungsfall schlägt einen Patch – er erspart dir Nacharbeit.

Nutzung verfolgen

pypistats.org/packages/amnesic

Lizenz

MIT – siehe LICENSE.

MCP Registry

Dieser Server ist im offiziellen MCP Registry registriert.

mcp-name: io.github.SurajKGoyal/amnesic

Available Tools

12 tools
db_annotateA
Persist semantic annotations for a table or column — survives across sessions.

This is the core of amnesic's persistent memory. Every annotation saved here
is automatically merged into future db_get_schema() responses, so the AI
never has to rediscover what a status code means or what a table is for.

Call this after discovering: what an enum value means, what a column represents,
how a table relates to another, or what a table is used for.

Args:
    table:              Table name, optionally schema-qualified to match your
                        DB — e.g. "users", "public.users" (Postgres),
                        "dbo.Orders" (MSSQL), "mydb.orders" (MySQL).
    connection:         Connection name. Defaults to first defined.
    table_description:  Human-readable description of the table's purpose.
    table_aliases:      Alternative names the table is known by.
    column:             Column to annotate (required for column-level args below).
    column_description: What this column represents in the business domain.
    enum_values:        Dict mapping stored values to labels {"1": "active", "2": "inactive"}.
    foreign_key:        FK reference as "other_table.column_name".
    example_values:     Representative sample values from this column.

Returns:
    {table, connection, updated: {table_knowledge?, column_knowledge?}}
ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
connectionNo
table_descriptionNo
table_aliasesNo
columnNo
column_descriptionNo
enum_valuesNo
foreign_keyNo
example_valuesNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavior. It states annotations survive sessions, are merged into future db_get_schema responses, and calls it the core of persistent memory. This effectively communicates the mutating and persistent nature. It doesn't discuss permissions or reversibility, but given the positive intent (annotating for better future queries), the transparency is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a brief summary, contextual motivation, usage guidance, parameter list, and return type. Every sentence adds value, and the length is appropriate for the tool's complexity. There is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite 9 parameters and no annotations or output schema, the description covers the tool's purpose, when to use it, parameter semantics, and return format. It also explains how it integrates with db_get_schema, providing sufficient context for an AI agent to use it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% coverage (no descriptions), so the description must compensate. The Args section provides clear semantic explanations for each parameter, including schema qualification for table, relationship between column and column-level fields, and the dict format for enum_values. This adds significant meaning beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool persists semantic annotations for tables or columns, surviving across sessions. It distinguishes from siblings by positioning itself as the persistent memory mechanism that feeds into db_get_schema, a unique role not covered by other sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises calling this tool after discovering semantic knowledge (enum meanings, column purposes, relationships). While it doesn't list when to avoid it or name alternatives, the context and sibling list imply when to use versus when to use other tools like db_get_schema or db_query.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_deprecateA
Soft-retire a table or column annotation — flag it stale without deleting it.

Use when a table/column still exists but should no longer be relied on. The
deprecation flag is surfaced in db_get_schema so the AI is warned off it on
future calls. Reversible via undo=True. To remove an annotation entirely
(e.g. the column was dropped from the DB), use db_forget instead.

Args:
    table:      Table name, optionally schema-qualified (e.g. "users",
                "public.users", "dbo.Orders", "mydb.orders").
    connection: Connection name. Defaults to first defined.
    column:     Column to deprecate. Omit to deprecate the whole table.
    reason:     Why it's deprecated (e.g. "replaced by status_v2").
    undo:       Clear the deprecation flag instead of setting it.

Returns:
    {table, connection, column, target, deprecated, reason}
ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
connectionNo
columnNo
reasonNo
undoNo

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but description explains the deprecation flag is surfaced in db_get_schema and that operation is reversible. Lacks details on permissions or side effects, but sufficient for a soft-retire tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with summary, usage guidelines, and argument list. Slightly wordy but each sentence adds value. No redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters, no output schema, and no annotations, the description covers all inputs, explains return format, and mentions interaction with db_get_schema. Distinguishes from sibling db_forget.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description provides full argument list with detailed explanations, defaults, and usage nuances (e.g., connection defaults to first defined, column omitted means whole table).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool soft-retires a table or column annotation, distinguishing it from db_forget which removes entirely. Specific verb+resource combination.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (table/column still exists, should not be relied on) and when not (use db_forget instead). Also mentions reversibility via undo=True.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_detect_driftA
Audit saved annotations against the live database schema (read-only).

Surfaces drift after the schema evolves:
  - orphaned annotations — a table or column you annotated that no longer
    exists in the DB. Remove with db_forget, or db_deprecate if pending.
  - undocumented tables — live tables with no annotation yet (coverage gaps).

Changes nothing — purely a report. Run after schema changes, or periodically.

Args:
    connection: Connection name. Defaults to first defined.

Returns:
    {connection, orphaned_tables, orphaned_columns, undocumented_tables,
     undocumented_truncated, summary}
ParametersJSON Schema
NameRequiredDescriptionDefault
connectionNo

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description explicitly states the tool is read-only ('Changes nothing — purely a report.') and details what it surfaces (orphaned annotations, undocumented tables). It also outlines the return structure (connection, orphaned_tables, etc.), providing full transparency without relying on annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: it opens with a clear verb-resource statement, uses bullet points for key outputs, and includes a separate Args/Returns section. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having only one optional parameter and no output schema, the description fully covers the tool's function, when to use it, what it detects, and the format of its return. No gaps remain for the intended use case.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema only has one parameter (connection) with default null. The description adds meaning by stating 'Defaults to first defined,' which goes beyond the schema's default value. Given the parameter's simplicity, the description provides sufficient context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Audit saved annotations against the live database schema (read-only).' It specifies the verb (audit) and the resource (annotations vs live schema), and distinguishes itself from sibling tools like db_forget and db_deprecate by emphasizing it is a read-only report that detects drift.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: 'Run after schema changes, or periodically.' It also advises on follow-up actions ('Remove with db_forget, or db_deprecate if pending.'), making the usage context clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_discover_relationshipsA
Discover all foreign key relationships in the database and save them to the graph.

Runs driver-specific FK introspection queries against the live database and
persists results to the local KnowledgeStore. Run once per database; re-run
after schema changes. After discovery, use db_get_relationships to navigate
the graph when planning complex JOIN queries.

Args:
    connection: Connection name. Defaults to first defined.

Returns:
    {connection, discovered: count, relationships: [{from_table, from_column, to_table, to_column}]}
ParametersJSON Schema
NameRequiredDescriptionDefault
connectionNo

TDQS

A4.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavior: runs driver-specific FK introspection queries, persists to KnowledgeStore, and implies potential impacts (live database query). Could mention performance implications or permissions, but still transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with a short summary, usage guidelines, and listed args/returns. Every sentence adds value, no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Completely covers the tool's lifecycle, return format, and relationship to sibling tools. No gaps given the simple parameter set and no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description includes an Args section explaining the single parameter 'connection', its meaning, and default behavior ('Defaults to first defined'), adding value beyond the schema which only shows default null.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool discovers all foreign key relationships and saves them to the graph. It uses specific verbs (discover, save) and resources (foreign key relationships, database, graph), and distinguishes from sibling tool db_get_relationships.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('Run once per database; re-run after schema changes') and when not, by directing to use db_get_relationships for navigation after discovery.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_forgetA
Permanently delete a table or column annotation. Safe by default — NOT reversible.

Use to remove a wrong annotation, or to clean up after a table/column was
dropped from the DB (pairs with db_detect_drift). Unlike db_deprecate, this
hard-deletes. Cascade is opt-in so you can't nuke a table by accident:
  - db_forget(table)               -> ONLY the table's own annotation
  - db_forget(table, column="x")   -> ONLY that column's annotation
  - db_forget(table, cascade=True) -> the table + all its column annotations
                                      + all relationships touching it

Only the local knowledge store is changed — never the live database.

Args:
    table:      Table name, optionally schema-qualified (e.g. "users",
                "public.users", "dbo.Orders", "mydb.orders").
    connection: Connection name. Defaults to first defined.
    column:     Column annotation to delete. Omit to target the table.
    cascade:    When targeting a table, also delete its columns +
                relationships. Ignored when column is given.

Returns:
    {table, connection, column, removed_table, removed_columns, removed_relationships}
ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
connectionNo
columnNo
cascadeNo

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully discloses behavior. It states 'Safe by default — NOT reversible,' explains cascade behavior, and clarifies that only the local knowledge store is changed, never the live database.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with bullet points and examples. Every sentence adds value, and critical information is front-loaded immediately after the first line.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description explains the return object structure. It covers all necessary context: irreversibility, local-only modification, cascade behavior, and relation to siblings. Complete for a destructive knowledge store tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 0% schema description coverage, the description provides detailed semantics for all 4 parameters: table examples, connection default, column omit behavior, cascade ignored when column given. This adds significant value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Permanently delete a table or column annotation.' It uses specific verbs and resources, and explicitly distinguishes from siblings like db_deprecate (soft-delete) and pairs with db_detect_drift.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'Use to remove a wrong annotation, or to clean up after a table/column was dropped from the DB.' Provides when-not guidance by contrasting with db_deprecate, and explains cascade opt-in to prevent accidents.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_get_relationshipsA
Get the foreign key relationship graph for a table up to the given traversal depth.

Depth 1 returns direct neighbors (tables one JOIN away). Depth 2 returns
neighbors-of-neighbors. Returns both a flat neighbor list and formatted join
path strings to help plan multi-table queries. Requires db_discover_relationships
to have been run first.

Args:
    table:      Table name (e.g. "Orders").
    connection: Connection name. Defaults to first defined.
    depth:      BFS traversal depth (default 1, recommended max 3).

Returns:
    {table, connection, neighbors: [...], paths: ["TableA -> TableB -> TableC", ...]}
ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
connectionNo
depthNo

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the output format (neighbor list and join paths) and the prerequisite step. As no annotations are provided, the description carries full burden; it lacks explicit mention of side effects or idempotency but is sufficient for understanding behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections for Args and Returns. It is concise without unnecessary words, front-loading the primary purpose and then detailing parameters and output.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description is comprehensive: it explains the output structure, prerequisite, and each parameter fully. An agent can correctly invoke this tool based solely on the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining all three parameters, their purposes, defaults, and even a recommended maximum depth for depth. This provides complete semantic understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: retrieving the foreign key relationship graph for a table up to a given depth. It distinguishes itself from sibling tools by explicitly requiring db_discover_relationships to have been run first.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: it explains depth levels and that the prerequisite tool must be run first. However, it does not explicitly state when not to use this tool or mention alternatives beyond the prerequisite.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_get_schemaA
Get column schema for a table, merged with any saved semantic annotations.

Checks the local cache first; fetches from the database on cache miss or
when force_refresh=True. Saves the result to cache for future calls.
Merges column descriptions, enum value mappings, and FK references from
previous db_annotate() calls into the response.

Args:
    table:         Table name, optionally schema-qualified. Use whatever your
                   DB uses — e.g. "users", "public.users" (Postgres),
                   "dbo.Orders" (MSSQL), "mydb.orders" (MySQL).
    connection:    Connection name. Defaults to first defined.
    force_refresh: Bypass cache and fetch fresh schema from the database.

Returns:
    {table, connection, columns (with annotations merged in), table_description, cached}
ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
connectionNo
force_refreshNo

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Given no annotations, the description fully discloses caching behavior, force refresh mechanism, and annotation merging, providing complete behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, front-loaded with the purpose, and every subsequent sentence adds necessary detail without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite lacking output schema, the description covers all essential aspects: purpose, caching, param details, and return structure, making it complete for a 3-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description thoroughly explains each parameter: table with DB-specific examples, connection with default, and force_refresh with functionality, adding significant value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves column schema merged with semantic annotations, distinguishing it from sibling tools like db_annotate (which adds annotations) and db_list_tables (which lists tables).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context on when to use (to get annotated schema) and parameter usage, but lacks explicit guidance on when not to use or alternatives to sibling tools, which would improve clarity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_list_connectionsA
List all configured database connections without exposing passwords or usernames.

Use this first to see what databases are available before calling other tools.
Returns connection names, drivers, databases, and server addresses.

Returns:
    {connections: [{name, driver, database, server}]}
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that passwords and usernames are not exposed, which is a key behavioral trait. However, does not explicitly state read-only nature or any side effects, though implied for a list operation. No annotations to contradict or supplement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise: two sentences plus a returns block. Front-loaded with main purpose. Every sentence adds value, no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Fully explains what the tool does and what it returns (list of connections with name, driver, database, server). No missing info given the simplicity of the tool and absence of parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so baseline is 4. Description does not need to add parameter info. Schema coverage is 100% by default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states listing all configured database connections without exposing sensitive info. Differentiates from siblings like db_list_tables by specifying the resource (connections). Uses specific verb 'list' and describes return fields.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to use this tool first before other tools to see available databases. Provides a clear usage context and sequential guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_list_tablesA
List all known tables for a connection, with descriptions and column counts.

Tables appear once they have been fetched via db_get_schema or annotated via
db_annotate. Descriptions come from the knowledge store — richer than raw
INFORMATION_SCHEMA.

Args:
    connection: Connection name. Defaults to first defined.

Returns:
    {connection, database, tables: [{table_fqn, description, aliases, column_count}]}
ParametersJSON Schema
NameRequiredDescriptionDefault
connectionNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries the burden. It discloses that descriptions come from the knowledge store (richer than raw schema) and that tables are only shown if known. No destructive behavior implied. Return format is given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear purpose, behavioral notes, Args, and Returns. Every sentence adds value, no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one optional parameter, no output schema), the description covers all essential aspects: purpose, prerequisites, return format, and parameter behavior. Complete for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Single optional parameter 'connection' is documented with default behavior ('Defaults to first defined'), adding useful meaning beyond the schema type and default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it lists all known tables for a connection, including descriptions and column counts. It distinguishes itself from siblings like db_get_schema (which fetches schema) and db_annotate (which annotates) by noting that tables appear only after those actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides context by explaining that tables appear only after being fetched or annotated, guiding the user on prerequisites. However, it does not explicitly state when to use or not use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_queryA
Execute a read-only SELECT query and return rows as a list of dicts.

All queries run inside an immediately-rolled-back transaction — write
statements are blocked both statically and at the transaction level.
Call db_get_schema first if you are unfamiliar with the table structure.

Args:
    sql:        SELECT query to execute. No INSERT/UPDATE/DELETE allowed.
    connection: Connection name (e.g. "orders.prod"). Defaults to first defined.
    max_rows:   Maximum rows to return (default 500). Set lower for large tables.

Returns:
    {rows, row_count, connection, database, truncated}
ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYes
connectionNo
max_rowsNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that queries run in an immediately-rolled-back transaction and that write statements are blocked both statically and at the transaction level. It also outlines the return structure (rows, row_count, connection, database, truncated). Since no annotations are provided, the description carries the full burden and does so well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a single sentence stating the core purpose, followed by a brief note on transaction behavior and a recommendation to use a sibling tool, then a bullet-style summary of parameters and return value. No superfluous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 parameters, no output schema), the description covers the main behavioral aspects (transaction, write blocking), parameter semantics, and return format. It could optionally mention error handling or performance implications, but overall it is sufficiently complete for an AI agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description provides comprehensive meaning for all three parameters: sql (SELECT-only), connection (defaults to first defined), and max_rows (default 500, lower for large tables). This goes far beyond the bare schema, which only supplies names and types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool executes a read-only SELECT query and returns rows as a list of dicts. It specifies that write statements are blocked, making the purpose unambiguous. Although not explicitly compared to siblings, the verb-resource combination ('Execute a read-only SELECT query') is specific and distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises to call db_get_schema first if unfamiliar with the table structure, providing a clear alternative. It also implicitly limits usage to read-only queries (SELECT only) and mentions max_rows for large tables. However, it does not explicitly exclude other query types or describe when not to use the tool beyond the SELECT constraint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_sync_knowledgeA
Copy annotations from one connection's knowledge store to another.

Typical use: after confirming that staging and prod share the same schema,
sync all the semantic knowledge you've built up in staging to prod.
Only syncs tables and columns that exist in the target schema cache —
tables missing from target are reported in 'skipped', columns in 'warnings'.

Args:
    from_connection: Source connection (e.g. "orders.staging").
    to_connection:   Target connection (e.g. "orders.prod").
    tables:          Optional list of specific table FQNs to sync. Defaults to all.

Returns:
    {synced: [...], skipped: [{table, reason}], warnings: [{table, column, reason}]}
ParametersJSON Schema
NameRequiredDescriptionDefault
from_connectionYes
to_connectionYes
tablesNo

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully bears the transparency burden. It discloses that only tables/columns existing in target are synced, with skipped and warnings reported. It also describes the return structure in detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured with a typical use case, behavior explanation, and clear Args/Returns sections. No superfluous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 3 parameters, no output schema, and no annotations, the description is highly complete. It covers the sync process, edge cases (missing items), and return format, leaving no critical gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description adds meaning by explaining 'from_connection' and 'to_connection' as source/target with example values ('orders.staging', 'orders.prod'), and 'tables' as an optional list of FQNs defaulting to all. This provides clarity beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool copies annotations between knowledge stores. It uses a specific verb 'sync' and resource 'annotations from knowledge store', distinguishing it from sibling tools like db_annotate or db_query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides a typical use case: syncing from staging to prod after confirming schema match. It also explains behavior for missing tables/columns. However, it does not explicitly exclude other scenarios or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 12 tool updatesv0.2.2
    • First observeddb_annotate
    • First observeddb_deprecate
    • First observeddb_detect_drift
    • First observeddb_discover_relationships
    • First observeddb_forget
    • First observeddb_get_relationships
    • First observeddb_get_schema
    • First observeddb_list_connections
    • First observeddb_list_tables
    • First observeddb_query
    • First observeddb_search
    • First observeddb_sync_knowledge
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.7/5.0
Disambiguation5/5

Each tool has a clear, distinct purpose. There is no overlap: annotation management (annotate, deprecate, forget), schema retrieval (get_schema, list_tables), querying (query), searching (search), relationship discovery (discover_relationships, get_relationships), drift detection (detect_drift), and knowledge sync (sync_knowledge) are all separate concerns.

Naming Consistency5/5

All tools follow the consistent pattern `db_<verb>_<noun>` using snake_case. The verbs are descriptive and indicate the action (e.g., annotate, query, list_tables). No mixing of conventions or vague names.

Tool Count5/5

With 12 tools, the server is well-scoped for a database knowledge management system. Each tool serves a necessary function in the lifecycle of schema understanding, annotation, querying, and maintenance. Not overloaded nor sparse.

Completeness4/5

The tool set covers the core workflow: connection listing, table discovery, schema retrieval, querying, annotation CRUD (annotate, deprecate, forget), relationship discovery, drift detection, and knowledge sync. Missing a direct tool to view all annotations in isolation, but schema retrieval and search provide access.

Maintenance

ActivityActive
ResponsivenessSlow

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/SurajKGoyal/amnesic'

If you have feedback or need assistance with the MCP directory API, please join our Discord server