amnesic

Purpose

amnesic is an MCP server that provides persistent semantic memory for SQL databases. Every AI session starts "cold": you need to re-explain which tables exist, what the 3 in the status column means, and which foreign key connects orders and users. amnesic solves this problem with a local SQLite knowledge base stored per database, so that these annotations and relationships persist across sessions. It positions itself as a third option between a "query executor" and an enterprise-grade data catalog: it has data-catalog-level semantic memory, but only the deployment cost of a query executor.

Main capabilities

• Persistent annotations: Add annotations to tables and columns; annotations remain after restarts, model updates, and new sessions. Annotate a status enum once, and every future session automatically sees the labels.
• Relationship graph: Discover and save foreign key relationships; future JOIN queries can use this graph directly.
• Searchable knowledge base: Use SQLite FTS5 with BM25 ranking for keyword search, with no embeddings and no external services. db_search supports finding relevant tables/columns by keyword in large schemas, returning ranked results with descriptions and highlighted snippets.
• Synchronization between environments: Accumulate annotations in staging, then sync to prod. Returns {synced, skipped, warnings}; tables missing in the target schema are skipped with an explanation, and missing columns produce warnings but do not block the rest of the sync.
• Portability: Knowledge can be exported, imported, cleared, and removed, and local files can be operated on even without database credentials.
• Read-only safety design: Rejects INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE, EXEC, EXECUTE, MERGE, BULK, GRANT, REVOKE, DENY, including write statements hidden in WITH CTEs. Only SELECT and WITH ... SELECT can reach the database.

Usage

Installation can be done in one of three ways:

• pipx (one-time install):
• uv (single-binary alternative, fast, no Python required):
• regular pip (install into the current Python environment):

After installation, amnesic init asks for the database type, host, and credentials, teststhe connection, and then saves it; the password is stored securely in ~/.config/amnesic/.env (chmod 600), and the connection block is written to ~/.config/amnesic/connections.toml. Setting $AMNESIC_HOME or $XDG_CONFIG_HOME overrides the storage location.

If you do not want to use credentials, you can run amnesic init --demo, which adds a self-contained SQLite sample database (e-commerce schema: customers / products / orders, with foreign keys and enum columns), letting you try all the tools within a minute.

To add more connections later, use amnesic add; to rotate a password, use amnesic set-secret. The variable name is the environment variable name referenced by ${...} in connections.toml, and the wizard automatically generates it as <CONNECTION_NAME_UPPERCASE_WITH_UNDERSCORES>_PASSWORD.

When adding amnesic to an AI client, all MCP clients use the same snippet:

• Claude Code: use one-line installation, no need to edit JSON (source: SurajKGoyal/amnesic-marketplace).
• Claude Desktop: add to the configuration file, which is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows, and ~/.config/Claude/claude_desktop_config.json on Linux.
• Cursor: one-click installation, or add to the project .cursor/mcp.json or the global ~/.cursor/mcp.json.
• VS Code (with the MCP extension): add to .vscode/mcp.json.

When not using a global installation (temporary approach), you can use uvx or pipx to fetch it each time the MCP client starts, and you must explicitly pass the driver extras, with multiple drivers separated by commas, such as amnesic[postgres,mssql], or use amnesic[all].

Upgrade using the same tool as installation, then restart the MCP client. Upgrades are safe, comments are not lost, and knowledge files are automatically migrated to the new schema on first load; columns are only added, data is never deleted. To check the version, use amnesic --version.

Commands for managing connections and knowledge: export / import / clear / remove. These commands only operate on local files and work even if connection credentials are not set. remove performs a precise string edit of connections.toml, keeping the formatting and comments of other blocks byte-for-byte unchanged.

Advanced usage: if you want to manage the configuration file yourself, you can generate a blank template, write out ~/.config/amnesic/connections.toml, and exit the wizard. Use ${ENV_VAR} for credentials; do not hardcode passwords. Secrets are automatically loaded from ~/.config/amnesic/.env (format KEY=VALUE, one per line, # for comments). Use dot notation for canonical connection names, for example orders.prod, orders.staging, analytics, local.

Applicable scenarios

• Individual developers using Claude Pro / Cursor / Copilot on their own projects, development databases, or test data.
• Hobby projects querying personal SQLite or self-hosted Postgres.
• Open source maintainers working with public schemas.
• Teams using enterprise-grade AI with clear isolation: AWS Bedrock (tenant + IAM), Azure OpenAI (region-pinned, own subscription), Anthropic Enterprise (zero data retention, opted out of training), Vertex AI (own GCP project), self-hosted (Ollama, vLLM, local Claude/GPT, data never leaves the network).
• Any user on a paid AI plan with zero-retention guarantees and a DPA covering the relevant processing.

Limitations

• It does not perform write operations such as inserts, updates, or deletes, nor does it provide execution plans, index recommendations, or database health diagnostics—these are not its responsibility and should be used together with a query executor.
• The database itself does not know the meaning of columns; only through amnesic's annotation layer can itprovide semantics.
• If the database stores other people's data (users, customers, patients) and you have not confirmed that the AI provider's terms cover that processing, or if you use consumer-grade AI to process regulated data (PHI for HIPAA-covered entities, cardholder data under PCI-DSS, restricted PII under GDPR or India's DPDP Act), or if employer policy restricts the use of external AI tools on production databases, or if you are subject to data residency rules, more careful evaluation is needed.
• The trust boundary depends on where the MCP client sends data, not on amnesic itself.
• The documentation does not provide more information beyond specific charges, prices, and platform compatibility details.