Amnesic

amnesic — the MCP server with the most ironic name in the registry

Persistent semantic memory for your SQL databases. The name is ironic — it remembers everything.

"The MCP server with the most ironic name in the registry. It's anything but amnesic — it remembers your database so your AI doesn't have to."

Works with Claude Code · Claude Desktop · Cursor · VS Code · Cline · Windsurf — any MCP-compatible client.

Available on Official MCP Registry · Claude Code plugin marketplace

🔒 Read-only by design. amnesic refuses to execute INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE, EXEC, MERGE, GRANT, REVOKE — and any write statement smuggled inside a WITH CTE. Two layers of defense: static SQL analysis rejects the statement before connecting, and every query runs inside a transaction that is immediately rolled back. Safe to point at prod. Details ↓

The problem

Every session with an AI starts cold. You spend the first few minutes re-explaining what tables exist, what a status column value of 3 means, which FK connects orders to users. Then the session ends, and you do it all over again tomorrow.

amnesic fixes this. It gives your AI a persistent SQLite knowledge store — one per database — that survives across sessions. Annotate a status enum once; every future session sees those labels automatically. Discover FK relationships once; every future JOIN query uses that graph.

Quickstart (90 seconds)

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

⚡ Try it without credentials. Run amnesic init --demo instead — it adds a self-contained SQLite sample DB (e-commerce schema: customers / products / orders with FKs and an enum column) so you can exercise every tool in under a minute. Great for a first look before pointing amnesic at a real database.

The wizard asks which database type you're connecting to and tells you the one command to run if its driver isn't installed yet — you never need to guess extras up front.

The wizard:

• Asks for your database type, host, and credentials
• Tests the connection before saving anything
• Stores the password securely in ~/.config/amnesic/.env (chmod 600)
• Writes the connection block to ~/.config/amnesic/connections.toml

Then add amnesic to your AI client and restart.

Install pipx (one-time):

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

Or use uv (single-binary alternative — fast, no Python required):

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

Or plain pip (installs into your active Python env):

pip install amnesic

Whichever you pick, amnesic init asks which database you'll connect to and prints the one extra command to install that driver — no need to commit to extras up front.

After install, amnesic --help works from any terminal.

Where amnesic stores things

Set $AMNESIC_HOME (or $XDG_CONFIG_HOME on Linux) to override the location.

Adding more connections later

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

Setting and rotating passwords

amnesic init and amnesic add save your password automatically — for the typical setup flow, you never need to think about this section.

Use set-secret when you need to change a stored password later — IT rotated it, you mistyped it during setup, or you're hand-editing the config.

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

What's the variable name? It's the env var your connections.toml references for that connection's password. The wizard auto-generates these as <CONNECTION_NAME_UPPERCASE_WITH_UNDERSCORES>_PASSWORD:

To see the exact name your config uses, check ~/.config/amnesic/connections.toml — anything inside ${...} is the variable to pass to set-secret.

Under the hood: writes (or replaces) the line in ~/.config/amnesic/.env, sets file permission to chmod 600 (only your user can read it), preserves all other entries.

Managing connections and knowledge

Knowledge accumulates per connection in a local SQLite file. These commands let you move it between machines and clean up:

# 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 operate purely on local files — they never connect to the database, so they work even if a connection's credentials aren't set. remove edits connections.toml with surgical string edits, leaving every other block's formatting and comments byte-for-byte intact.

Add to your AI client

Once amnesic is installed with the right driver extras (see Quickstart), the amnesic command is on your PATH. Use the same snippet across every MCP client:

Claude Code

One-line install (recommended — no JSON editing). Inside Claude Code:

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

That wires amnesic as an MCP server automatically. Source: SurajKGoyal/amnesic-marketplace.

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

Claude Desktop

Add to your platform's Claude Desktop config:

• 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

One-click install — click the button below and Cursor wires it up for you:

<a href="https://cursor.com/en-US/install-mcp?name=amnesic&config=eyJjb21tYW5kIjoiYW1uZXNpYyJ9"><img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add amnesic to Cursor" height="32"></a>

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

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

Without a global install (ephemeral)

If you'd rather not install amnesic on your system, use uvx or pipx to fetch it each time the MCP client starts. Note the driver extras must be passed explicitly:

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

For multiple drivers, comma-separate inside the brackets — e.g. amnesic[postgres,mssql] or use amnesic[all] for everything.

VS Code (with MCP extension)

Add to .vscode/mcp.json:

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

Updating

amnesic ships often. Upgrade with the same tool you installed it with:

Then restart your MCP client (Claude Code, Cursor, …) so it relaunches the amnesic server and picks up any new tools.

Upgrading is safe — you won't lose annotations. Your knowledge files auto-migrate to the new schema on first load; amnesic only ever adds columns, never drops your data.

To check the installed version: amnesic --version. Latest release: PyPI · Releases.

Tools

…