de en es ja ko ru zh

amnesic

Name: amnesic
Author: SurajKGoyal

by SurajKGoyal

Overview Schema Related Servers Score Discussions

Python

Local

amnesic — MCP-сервер с самым ироничным названием в реестре

PyPI version Python License: MIT MCP Registry Glama score

Институциональная память вашей базы данных в виде MCP-сервера. Название ироничное — он помнит всё.

«MCP-сервер с самым ироничным названием в реестре. Он вовсе не амнезик — он запоминает вашу базу данных, чтобы вашему ИИ не приходилось этого делать».

Большинство MCP-серверов для баз данных — это исполнители запросов: они подключаются, проводят интроспекцию, выполняют SQL и забывают. amnesic — это семантическая память: он накапливает то, что означает ваша схема (что такое status = 3, какие колонки на самом деле являются внешними ключами, для чего нужна та легаси-таблица), и автоматически передаёт это каждой будущей сессии. Думайте о каталоге данных, только без платформы, конвейера ingestion и счетов. Где уместен amnesic ↓

Работает с Claude Code · Claude Desktop · Cursor · VS Code · Cline · Windsurf — с любым MCP-совместимым клиентом.

Доступен в официальном MCP-реестре · маркетплейсе плагинов Claude Code

👋 Пользуетесь amnesic? Поздоровайтесь в ветке adopters — счётчики загрузок не расскажут мне, что реально используется, а это напрямую влияет на то, что будет создано дальше.

🔒 Только чтение по замыслу. amnesic отказывается выполнять INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE, EXEC, MERGE, GRANT, REVOKE — а также любые write-операторы, протащенные внутри CTE WITH. Два уровня защиты: статический анализ SQL отклоняет оператор до подключения, и каждый запрос выполняется внутри транзакции, которая немедленно откатывается. Безопасно направлять на прод. Подробности ↓

Проблема

Каждая сессия с ИИ начинается с чистого листа. Вы тратите первые несколько минут, заново объясняя, какие таблицы существуют, что означает значение 3 в колонке status, какой внешний ключ связывает orders с users. Затем сессия заканчивается — и завтра вы делаете всё это снова.

amnesic решает эту проблему. Он даёт вашему ИИ постоянное хранилище знаний на SQLite — по одному на базу данных, — которое переживает сессии. Аннотируйте enum статусов один раз; каждая будущая сессия автоматически увидит эти метки. Обнаружьте связи внешних ключей один раз; каждый будущий JOIN-запрос будет использовать этот граф.

Знания также переносимы и переживают ваш доступ к базе данных. Когда вы уходите с проекта, amnesic export передаёт следующему разработчику всё, чему вы его научили — годы «о, эта колонка на самом деле означает…», которые иначе ушли бы вместе с вами.

Related MCP server: engram-mcp

Где уместен amnesic

Экосистема MCP для баз данных делится на два лагеря, и amnesic сознательно не входит ни в один из них.

Исполнители запросов — DBHub, Postgres MCP Pro, MCP Toolbox от Google и вендорные серверы (Supabase, Neon). Они проводят интроспекцию в реальном времени, выполняют SQL, а некоторые глубоко копают в производительность — Postgres MCP Pro делает настоящую настройку индексов и проверки здоровья в стиле PgHero. Они в этом отличны. Но они также не сохраняют состояние: каждая сессия заново изучает вашу схему с нуля, и ничто из того, что они возвращают, не может сказать вам, что означает колонка, потому что база данных этого тоже не знает.

Корпоративные каталоги — DataHub, Atlan, Cube, AtScale. Они действительно хранят семантический контекст: глоссарии, описания колонок, владельцев, lineage. Но они также являются обязательством перед платформой — ingestion метаданных, сервис, который нужно запускать, обычно платный тариф. Это оправдано в масштабах компании; совершенно непропорционально для одного разработчика, которому нужно помнить, что означают шесть кодов статусов в легаси-базе MSSQL, которую никто никогда не будет подключать к каталогу.

amnesic — это третье: семантическая память каталогового уровня при затратах на настройку уровня исполнителя запросов. pipx install, один TOML-файл, локальный SQLite-файл на базу данных. Никакой платформы, никакого ingestion, никакого сервера для запуска.

Честное сравнение

	amnesic	Исполнители запросов	Корпоративные каталоги
Семантический контекст (что означает значение)	✅ постоянный, ваш	❌ нет	✅ управляется платформой
Переживает сессии	✅	❌	✅
Переносим / переживает доступ к БД	✅ `export`/`import`	❌	⚠️ привязан к платформе
Стоимость настройки	одна команда	одна команда	конвейер ingestion
Актуальность живой схемы	⚠️ кэшируется, ручное обновление	✅ всегда актуальна	⚠️ задержка ingestion
Планы выполнения / настройка индексов	❌	✅ (Postgres MCP Pro)	❌
Lineage / владельцы / управление	❌	❌	✅
Работает с легаси-схемами без FK-ограничений	✅ аннотируйте их сами	❌ нечего интроспектировать	⚠️ нужен ingestion

Используйте исполнитель запросов вместо amnesic, если вам нужны планы выполнения, рекомендации по индексам или диагностика здоровья базы данных — это не работа amnesic, и добавление этого сделало бы его худшей версией инструмента, который уже существует.

Используйте amnesic вместе с ним. Они сочетаются: ничто не мешает вам запускать оба. amnesic хранит смысл; они хранят механику.

Строки, отмеченные ⚠️ выше, — известные пробелы с открытыми issues — см. Roadmap ↓.

Быстрый старт (90 секунд)

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

⚡ Попробуйте без учётных данных. Выполните amnesic init --demo — он добавит самодостаточную демонстрационную базу SQLite (схема электронной коммерции: customers / products / orders с внешними ключами и enum-колонкой), чтобы вы могли опробовать каждый инструмент меньше чем за минуту. Отлично для первого знакомства, прежде чем направлять amnesic на реальную базу данных.

Мастер спросит, к какому типу базы данных вы подключаетесь, и подскажет единственную команду для запуска, если его драйвер ещё не установлен — вам никогда не придётся угадывать дополнительные пакеты заранее.

Мастер:

Спрашивает тип базы данных, хост и учётные данные
Проверяет соединение перед сохранением чего-либо
Хранит пароль безопасно в ~/.config/amnesic/.env (chmod 600)
Записывает блок подключения в ~/.config/amnesic/connections.toml

Затем добавьте amnesic в свой ИИ-клиент и перезапустите.

Установите pipx (однократно):

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

Или используйте uv (однобинарная альтернатива — быстро, Python не требуется):

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

Или обычный pip (устанавливается в ваше активное окружение Python):

pip install amnesic

Что бы вы ни выбрали, amnesic init спросит, к какой базе данных вы будете подключаться, и выведет единственную дополнительную команду для установки этого драйвера — не нужно заранее выбирать дополнительные пакеты.

После установки amnesic --help работает из любого терминала.

Где amnesic хранит данные

Файл	macOS / Linux	Windows
Конфигурация	`~/.config/amnesic/connections.toml`	`%APPDATA%\amnesic\connections.toml`
Секреты	`~/.config/amnesic/.env` (chmod 600)	`%APPDATA%\amnesic\.env` (ACL профиля пользователя)
Знания	`~/.config/amnesic/knowledge_<name>.db`	`%APPDATA%\amnesic\knowledge_<name>.db`

Установите $AMNESIC_HOME (или $XDG_CONFIG_HOME в Linux), чтобы переопределить расположение.

Добавление новых подключений позже

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

Установка и смена паролей

amnesic init и amnesic add сохраняют ваш пароль автоматически — при типичном процессе настройки вам никогда не придётся думать об этом разделе.

Используйте set-secret, когда нужно изменить сохранённый пароль позже — ИТ-отдел его ротировал, вы ошиблись при вводе во время настройки или вы вручную редактируете конфигурацию.

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

Как называется переменная? Это переменная окружения, на которую ссылается ваш connections.toml для пароля этого подключения. Мастер автоматически генерирует их в формате <ИМЯ_ПОДКЛЮЧЕНИЯ_ВЕРХНИМ_РЕГИСТРОМ_С_ПОДЧЁРКИВАНИЯМИ>_PASSWORD:

Имя подключения	Сгенерированная переменная окружения
`orders.prod`	`ORDERS_PROD_PASSWORD`
`analytics`	`ANALYTICS_PASSWORD`
`drive.staging`	`DRIVE_STAGING_PASSWORD`

Чтобы увидеть точное имя, которое использует ваша конфигурация, проверьте ~/.config/amnesic/connections.toml — всё внутри ${...} — это переменная, которую нужно передать в set-secret.

Как это работает: записывает (или заменяет) строку в ~/.config/amnesic/.env, устанавливает права файла chmod 600 (читать может только ваш пользователь), сохраняет все остальные записи.

Управление подключениями и знаниями

Знания накапливаются для каждого подключения в локальном файле SQLite. Эти команды позволяют перемещать их между машинами и выполнять очистку:

# 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 работают исключительно с локальными файлами — они никогда не подключаются к базе данных, поэтому работают, даже если учётные данные подключения не заданы. remove редактирует connections.toml хирургическими строковыми правками, оставляя форматирование и комментарии всех остальных блоков байт-в-байт нетронутыми.

Добавление в ваш ИИ-клиент

После установки amnesic с нужными драйверными extras (см. Быстрый старт) команда amnesic доступна в вашем PATH. Используйте один и тот же фрагмент во всех MCP-клиентах:

Claude Code

Установка одной командой (рекомендуется — без редактирования JSON). Внутри Claude Code:

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

Это автоматически подключает amnesic как MCP-сервер. Источник: SurajKGoyal/amnesic-marketplace.

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

Claude Desktop

Добавьте в конфигурацию Claude Desktop вашей платформы:

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

Установка в один клик — нажмите кнопку ниже, и Cursor подключит его за вас:

Добавьте в .cursor/mcp.json в вашем проекте (или в ~/.cursor/mcp.json глобально):

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

Без глобальной установки (эфемерно)

Если вы предпочитаете не устанавливать amnesic в систему, используйте uvx или pipx, чтобы получать его при каждом запуске MCP-клиента. Обратите внимание, что драйверные extras нужно передавать явно:

// 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"]
    }
  }
}

Для нескольких драйверов перечислите их через запятую внутри скобок — например, amnesic[postgres,mssql] или используйте amnesic[all] для всего.

VS Code (с расширением MCP)

Добавьте в .vscode/mcp.json:

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

Обновление

amnesic выпускает обновления часто. Обновитесь тем же инструментом, которым устанавливали:

Способ установки	Команда обновления
`pipx`	`pipx upgrade amnesic`
`uv tool`	`uv tool upgrade amnesic`
`pip`	`pip install --upgrade amnesic`
`uvx` (временный, в вашем MCP-конфиге)	uvx кэширует сборки — выполните `uv cache clean amnesic`, чтобы получить свежую версию

Затем перезапустите ваш MCP-клиент (Claude Code, Cursor, …), чтобы он заново запустил сервер amnesic и подхватил новые инструменты.

Обновление безопасно — вы не потеряете аннотации. Ваши файлы знаний автоматически переносятся в новую схему при первой загрузке; amnesic только добавляет колонки и никогда не удаляет ваши данные.

Чтобы проверить установленную версию: amnesic --version. Последний релиз: PyPI · Releases.

Инструменты

Инструмент	Описание
`db_list_connections()`	Список всех настроенных подключений (без раскрытия секретов)
`db_list_tables(connection)`	Все известные таблицы с описаниями и количеством колонок
`db_search(query, connection, target, limit)`	BM25-поиск по описаниям таблиц/колонок и псевдонимам
`db_get_schema(table, connection)`	Схема колонок, объединённая с сохранёнными аннотациями
`db_query(sql, connection)`	Выполнение read-only SELECT-запроса
`db_annotate(table, connection, ...)`	Сохранение семантических аннотаций для таблиц/колонок
`db_deprecate(table, connection, column?, reason?, undo?)`	Мягкое устаревание аннотации — помечается (и предупреждает), но сохраняется, обратимо
`db_detect_drift(connection)`	Аудит аннотаций относительно живой схемы — поиск осиротевших аннотаций и недокументированных таблиц
`db_forget(table, connection, column?, cascade?)`	Полное удаление аннотации (каскад — по желанию) — необратимо
`db_sync_knowledge(from, to)`	Копирование аннотаций между подключениями (например, staging → prod)
`db_discover_relationships(connection)`	Обнаружение всех FK-связей в живой БД
`db_get_relationships(table, connection)`	Навигация по FK-графу для планирования JOIN

Поиск по базе знаний

Для больших схем db_list_tables непрактичен — вы выгрузите 500+ строк в контекст Claude. Вместо этого используйте db_search, чтобы найти нужные таблицы/колонки по ключевым словам:

"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 использует SQLite FTS5 с BM25-ранжированием — быстро, локально, без эмбеддингов и внешних сервисов. Синтаксис поиска поддерживает:

Синтаксис	Эффект
`payment`	Совпадение по слову (со стеммингом — также находит "payments", "paying")
`"payment method"`	Точная фраза
`pay*`	Совпадение по префиксу — "payment", "payable" и т.д.
`payment AND status`	Оба термина обязательны
`payment OR refund`	Любой из терминов

Результаты возвращают ранжированные строки таблиц/колонок с описаниями и подсвеченными фрагментами.

Слой знаний

Ключевое отличие. Каждая аннотация переживает перезапуски, обновления моделей и новые сессии.

Сессия 1 — вы обнаруживаете что-то новое

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.

Сессия 2 — знание уже на месте

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 ...

Никакого повторного обнаружения. Никаких потраченных впустую ходов. Аннотация сохранилась.

Граф связей

Поймите JOIN-структуру вашей схемы один раз — и используйте её вечно.

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

Теперь ИИ точно знает, как выполнять JOIN по вашей схеме, без догадок.

Синхронизация между окружениями

Накапливайте аннотации в staging, затем переносите в prod:

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

Возвращает {synced: [...], skipped: [{table, reason}], warnings: [{table, column, reason}]}.

Таблицы, отсутствующие в кэше целевой схемы, пропускаются с понятной причиной. Колонки, отсутствующие в целевой схеме, помечаются предупреждением, но не блокируют остальную синхронизацию.

Продвинутый уровень: ручное редактирование TOML

Если вы предпочитаете управлять файлом конфигурации самостоятельно, сгенерируйте пустой шаблон:

amnesic init --template

Это записывает ~/.config/amnesic/connections.toml с примерами в комментариях и завершает работу — без мастера. Редактируйте файл напрямую:

# ~/.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)

Используйте ${ENV_VAR} для учётных данных — никогда не хардкодьте пароли.

Секреты автоматически загружаются из ~/.config/amnesic/.env (формат: KEY=VALUE, по одному на строку, # для комментариев). Для каждой ${VAR_NAME}, на которую ссылается ваш TOML, заполните соответствующую запись в .env с помощью amnesic set-secret VAR_NAME (скрытый ввод, chmod 600) или запишите .env самостоятельно.

Канонические имена подключений используют точечную нотацию: orders.prod, orders.staging, analytics, local.

Поддерживаемые базы данных

База данных	Python-драйвер	Устанавливается через
PostgreSQL	`psycopg2-binary`	подсказка мастера при выборе Postgres, или доп. пакет `amnesic[postgres]`
MySQL / MariaDB	`pymysql`	подсказка мастера при выборе MySQL, или доп. пакет `amnesic[mysql]`
Microsoft SQL Server	`pymssql`	подсказка мастера при выборе MSSQL, или доп. пакет `amnesic[mssql]`
SQLite	stdlib `sqlite3`	всегда доступен — без дополнений

Безопасность и принудительный read-only режим

amnesic создан так, чтобы его можно было безопасно направлять на production-базы данных.

Почему ваш ИИ не может повредить ваши данные

Каждый запрос проходит через два независимых уровня, прежде чем достигнет базы данных:

Статический анализ (в amnesic/readonly.py) — SQL токенизируется и отклоняется, если содержит что-либо из: INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE, EXEC, EXECUTE, MERGE, BULK, GRANT, REVOKE, DENY. Это включает write-операторы, спрятанные внутри CTE (WITH x AS (SELECT ...) UPDATE ... перехватывается и отклоняется).
Откат транзакции — даже если write-оператор каким-то образом пройдёт статическую проверку, запрос выполняется внутри BEGIN TRANSACTION ... ROLLBACK, так что ничего никогда не фиксируется. Ремень и подтяжки.

До базы данных доходят только SELECT и WITH ... SELECT. Комментарии удаляются перед анализом, так что /* DELETE FROM users */ нельзя использовать для сокрытия атаки.

Другие меры безопасности

Никаких учётных данных в ответах: db_list_connections убирает пароли и имена пользователей из вывода. ИИ может видеть, какие подключения существуют, но никогда — как к ним аутентифицироваться.
Учётные данные только через переменные окружения: подстановка ${ENV_VAR} при загрузке конфига — пароли никогда не попадают в connections.toml на диске.
Безопасное хранение .env: на macOS/Linux chmod 0o600 (чтение/запись только владельцем); на Windows .env находится в %APPDATA%, который ограничен вашим профилем пользователя через Windows ACL.
Проверка идентификаторов: имена таблиц/схем/баз проверяются на соответствие [A-Za-z0-9_]+ перед любой интерполяцией строк в SQL.
Протестировано: 40+ юнит-тестов в tests/test_readonly.py покрывают каждое write-ключевое слово, крайние случаи удаления комментариев, попытки CTE-с-write, многооператорные запросы через точку с запятой и попытки инъекции идентификаторов. pytest tests/test_readonly.py — чтобы проверить на вашей машине.

Безопасно ли это с моими данными?

amnesic работает только локально и только по протоколу. Он не создаёт новой внешней границы доверия — граница доверия находится там, куда ваш MCP-клиент отправляет данные, а не в самом amnesic. Выбор ИИ-клиента определяет политику, применимую к вашим строкам.

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

Честный вопрос, который стоит задать себе, независимо от того, инди вы или предприятие:

Доверяю ли я своему ИИ-клиенту данные в этой базе?

Если да — а для большинства конфигураций ответ «да» — всё в порядке. Это покрывает:

Соло-разработчиков на Claude Pro / Cursor / Copilot, работающих со своими проектами, dev-базами или тестовыми данными
Пет-проекты, запрашивающие личный SQLite или self-hosted Postgres
Мейнтейнеров open-source, работающих с публичными схемами
Команды на корпоративном ИИ с явной изоляцией: AWS Bedrock (тенант + IAM), Azure OpenAI (привязка к региону, ваша подписка), Anthropic Enterprise (нулевое хранение данных, отказ от обучения), Vertex AI (ваш GCP-проект), self-hosted (Ollama, vLLM, локальный Claude/GPT — данные не покидают сеть)
Всех на платных ИИ-тарифах с гарантией нулевого хранения и DPA, покрывающим ваше использование

Стоит присмотреться, если

Ваша БД содержит данные, принадлежащие другим людям (пользователи, клиенты, пациенты), и вы не проверили, что условия вашего ИИ-провайдера покрывают такую обработку
Вы на потребительском тарифе ИИ (бесплатный / личный Pro) И работаете с регулируемыми данными — PHI (организация, подпадающая под HIPAA), данные держателей карт (PCI-DSS), ограниченные PII по GDPR / индийскому DPDP Act
У вашего работодателя есть явная политика, ограничивающая использование внешних ИИ-инструментов на prod-базах
Вы подпадаете под правила резидентности данных, где строки не могут покидать определённый регион

Минимизация данных встроена в архитектуру

Это свойство дизайна, а не запоздалая мысль: слой аннотаций означает, что ИИ отвечает на большинство вопросов о схеме из локального SQLite-файла знаний — без запуска db_query, без отправки данных строк куда-либо.

«Что означает status=3?» → решается из вашей сохранённой аннотации
«Как orders соединяются с users?» → решается из FK-графа
«В каких таблицах есть колонка created_at?» → решается из кэша схемы

Для чисто структурного исследования шесть инструментов никогда не касаются ваших данных: db_list_tables, db_get_schema, db_search, db_annotate, db_discover_relationships, db_get_relationships. Они возвращают только метаданные.

Это измеримо меньше перемещения данных, чем у «голого» SQL MCP — которому приходится выполнять SELECT DISTINCT status FROM orders каждый раз, когда ИИ не понимает enum. amnesic отвечает на это один раз из локальных аннотаций.

Отказ от ответственности: amnesic предоставляется как есть по лицензии MIT (без гарантий, без ответственности — см. LICENSE). Этот раздел не является юридической консультацией или консультацией по комплаенсу. Ваше использование amnesic и ИИ-клиента, к которому вы его подключаете, — ваша ответственность. Если вы работаете с регулируемыми данными, проконсультируйтесь со своей командой безопасности / комплаенса перед подключением к production.

Дорожная карта

Уже выпущено: слой знаний (v0.1), BM25-поиск (v0.1.5), управление жизненным циклом — устаревание / обнаружение дрейфа / забывание (v0.2) и переносимый экспорт/импорт знаний (v0.2.2).

Далее (v0.3 — «Заслужить память»): знания, которые накапливаются без чьего-либо ввода — автоматическое обнаружение enum, мягкий вывод FK для легаси-схем без ограничений и обучение JOIN-паттернам. Плюс обязательная работа: бюджет токенов в каждом ответе, индексы и первичные ключи в выборке схемы, флаги устаревания кэша и меньшая поверхность инструментов.

Полную картину и обоснование порядка см. в ROADMAP.md.

🙌 Вклад приветствуется

Каждый пункт v0.3 оформлен как issue на GitHub с уже продуманным дизайном — проблема, предлагаемая форма, файлы, которые нужно затронуть, и способ тестирования. Некоторые помечены тегом good first issue.

Выберите один и откройте PR — спрашивать разрешения не нужно. Просто оставьте комментарий в issue, чтобы два человека не делали одно и то же.

👉 Смотреть открытые issues · help wanted · good first issue
Новый драйвер? Следуйте структуре в amnesic/drivers.py и amnesic/tools/schema.py.
Тесты находятся в tests/. Для новых инструментов нужны модульные тесты; запустите pytest tests/ перед открытием PR.

Есть идея, которой нет в списке? Откройте issue. Сценарий использования лучше патча — это избавит вас от переделок.

Отслеживание использования

pypistats.org/packages/amnesic

Лицензия

MIT — см. LICENSE.

MCP Registry

Этот сервер зарегистрирован в официальном MCP Registry.

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

Name	Required	Description	Default
`table`	Yes
`connection`	No
`table_description`	No
`table_aliases`	No
`column`	No
`column_description`	No
`enum_values`	No
`foreign_key`	No
`example_values`	No

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

Name	Required	Description	Default
`table`	Yes
`connection`	No
`column`	No
`reason`	No
`undo`	No

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

Name	Required	Description	Default
`connection`	No

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

Name	Required	Description	Default
`connection`	No

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

Name	Required	Description	Default
`table`	Yes
`connection`	No
`column`	No
`cascade`	No

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

Name	Required	Description	Default
`table`	Yes
`connection`	No
`depth`	No

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

Name	Required	Description	Default
`table`	Yes
`connection`	No
`force_refresh`	No

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

Name	Required	Description	Default
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

Name	Required	Description	Default
`connection`	No

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

Name	Required	Description	Default
`sql`	Yes
`connection`	No
`max_rows`	No

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_searchA

Search the knowledge layer for tables/columns matching a query — BM25-ranked.

Use this BEFORE db_list_tables when you're looking for a specific concept
(e.g. "payments", "user email", "shipping address"). db_list_tables returns
every table; db_search returns just the relevant ones with descriptions and
highlighted snippets.

Searches across:
  - Table names, descriptions, and aliases
  - Column names, descriptions, and enum_values
Falls back gracefully to empty results if the query has invalid FTS5 syntax.

Args:
    query:      Search text. Supports FTS5 syntax: phrases ("foo bar"),
                prefix matching (pay*), boolean operators (foo AND bar).
    connection: Connection name. Defaults to first defined.
    target:     "tables", "columns", or "all" (default).
    limit:      Max results to return (default 10).

Returns:
    {query, connection, target, result_count, results: [
        {target_type, table_fqn, column_name, description, snippet, score}, ...
    ]}

ParametersJSON Schema

Name	Required	Default
`query`	Yes
`connection`	No
`target`	No	all
`limit`	No

TDQS

A4.7/5.0

Behavior4/5

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

No annotations, but the description covers search behavior (BM25 ranking), fallback, and output structure. It doesn't explicitly state it's read-only, but the context implies it; still substantive.

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 sections, minimal redundancy, front-loaded usage tip, and efficient use of bullet points. Every sentence adds value.

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 4 parameters, no output schema, and no annotations, the description is comprehensive, covering input, output, and edge cases (invalid syntax). Could mention performance but not necessary.

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 has 0% coverage, but the description fully explains each parameter: query syntax (FTS5), connection default, target options, and limit default, adding significant meaning 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?

Description clearly states the tool searches for tables/columns using BM25 ranking, distinguishes it from db_list_tables, and lists the fields it searches across, providing a specific verb and resource.

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 before db_list_tables when looking for specific concepts, contrasts it with db_list_tables' behavior, and mentions fallback for invalid FTS5 syntax.

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

Name	Required	Description	Default
`from_connection`	Yes
`to_connection`	Yes
`tables`	No

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.

12 tool updatesv0.2.2Jun 23, 2026
- 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

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Related MCP Connectors

Memwyre
io.github.memwyreai
Universal persistent memory and knowledge retrieval layer for AI agents and LLMs.
11
stagenth · AI 记忆库 A
com.stagenth
Hosted persistent memory with semantic search, importance and TTL for AI agents.
Knowledge & Memory RAG Systems
52
DeepMem A
io.github.deepmemteam
Mem0-compatible persistent memory for AI agents: write facts once, recall them semantically.
Knowledge & Memory Autonomous Agents
21113
MemorySyncOAuth
io.memorysync
Persistent memory for AI agents. Search and store durable facts, preferences and decisions.
Knowledge & Memory Autonomous Agents
1

Related MCP Servers

Mnemo - Persistent AI Memory
Knowledge & Memory Workplace & Productivity
n24q02m
A
license
A
quality
A
maintenance
Persistent AI memory with SQLite hybrid search (FTS5 + semantic), built-in Qwen3 embedding, and rclone sync across machines.
Updated a day ago (2026-09-05 11:47 UTC)
15
10
Apache 2.0
engram-mcp
Knowledge & Memory RAG Systems Autonomous Agents
Cartisien
A
license
A
quality
C
maintenance
Persistent semantic memory for AI agents. SQLite-backed, local-first, zero config. Semantic search via Ollama embeddings with keyword fallback. Tools: remember, recall, history, forget, stats.
Updated 5 months ago (2026-04-20 02:08 UTC)
17
37
1
MIT
subconscious-mcp
Knowledge & Memory Vector Databases
vishaltorc
A
license
Not graded
quality
A
maintenance
Local-first semantic memory layer for MCP agents. Recall, remember, forget, stats over stdio. ChromaDB plus sentence-transformers, all on-machine.
Updated 3 months ago (2026-06-15 12:14 UTC)
MIT
claude-memory-mcp
Knowledge & Memory Search
imshota1009
A
license
Not graded
quality
C
maintenance
Provides persistent long-term memory for LLMs via local SQLite storage and semantic search, enabling recall across sessions without external APIs.
Updated 2 months ago (2026-07-05 17:55 UTC)
19
4
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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