Amnesic

amnesic — 注册目录中名字最具讽刺意味的 MCP 服务

将数据库的组织记忆作为 MCP 服务提供。这个名字颇具讽刺意味——它什么都记得。

“注册目录中名字最具讽刺意味的 MCP 服务。它一点也不健忘——它会记住你的数据库，让 AI 无需操心。”

大多数数据库 MCP 服务都是查询执行器：它们连接数据库、检查结构、运行 SQL，然后就忘了。amnesic 是一种语义记忆——它会不断积累关于架构含义的信息（status = 3 代表什么，哪些列实际上是外键，那个遗留表有什么用途），并自动提供给之后的每个会话。可以把它看作数据目录，但没有平台、数据摄取管道和账单。了解 amnesic 的定位 ↓

适用于 Claude Code · Claude Desktop · Cursor · VS Code · Cline · Windsurf——以及任何 兼容 MCP 的客户端。

可通过以下渠道获取： Official MCP Registry · Claude Code plugin marketplace

👋 正在使用 amnesic？ 来采用者讨论帖打个招呼——下载量无法告诉我大家实际在用什么，而你的反馈会直接影响接下来要构建的内容。

🔒 从设计上保证只读。 amnesic 拒绝执行 INSERT、UPDATE、DELETE、DROP、TRUNCATE、ALTER、CREATE、EXEC、MERGE、GRANT、REVOKE，以及任何藏在 WITH CTE 中的写入语句。两层防护：静态 SQL 分析会在连接前拒绝该语句，并且每个查询都会在随即回滚的事务中运行。可放心连接生产环境。详情 ↓

问题所在

每次与 AI 开启会话时，都得从头开始。你要先花几分钟重新解释有哪些表、status 列的值 3 代表什么，以及哪个外键连接了 orders 和 users。然后会话结束，第二天又得从头来过。

**amnesic 能解决这个问题。**它为 AI 提供持久化的 SQLite 知识库——每个数据库对应一个——并且能够跨会话保留。只需标注一次状态枚举，之后每个会话都会自动看到这些标签。只需发现一次外键关系，之后的每个 JOIN 查询都能使用这张关系图。

这些知识还可移植，即使你无法再访问数据库也能保留下来。当你从一个项目调离时，amnesic export 会把你教给它的一切交给下一位开发者——多年来积累的“哦，那个列其实表示……”等信息，不会再随着你离开而流失。

amnesic 的定位

数据库 MCP 生态分为两大阵营，而 amnesic 刻意不属于其中任何一方。

查询执行器 — DBHub、Postgres MCP Pro、Google's MCP Toolbox 和各厂商提供的服务（Supabase、Neon）。它们会检查实时数据库、执行 SQL，有些还深入处理性能问题——Postgres MCP Pro 可进行真正的索引调优和 PgHero 风格的健康检查。它们在这方面表现出色，但也都是无状态的：每次会话都要从头了解你的架构，而且它们返回的信息无法告诉你某个列代表什么，因为数据库自己也不知道。

企业级目录 — DataHub、Atlan、Cube、AtScale。它们确实能保存语义上下文：术语表、列描述、所有权、数据血缘。但使用它们也意味着采用一整套平台——元数据采集、需要运行的服务，通常还要付费。对企业规模而言物有所值；但如果只是某位开发者想记住旧版 MSSQL 数据库里六种状态码的含义，而这套数据库永远不会接入目录，这种做法就太过了。

amnesic 是第三种选择：以查询执行器级别的配置成本，获得目录级别的语义记忆。pipx install、一个 TOML 文件、每个数据库一个本地 SQLite 文件。不需要平台，不需要数据采集，也不需要运行服务。

坦诚对比

如果你需要执行计划、索引建议或数据库健康诊断，请改用查询执行器，而不是 amnesic——这不是 amnesic 的职责，加入这些功能只会让它变成现有工具的较差版本。

将 amnesic 与查询执行器搭配使用。 两者可以协同工作：你完全可以同时运行它们。amnesic 保存语义；查询执行器提供工具能力。

上表中标记为 ⚠️ 的项目是已知缺口，且已有开放问题——请参阅路线图 ↓。

快速开始（90 秒）

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

⚡ 无需凭据即可试用。 改为运行 amnesic init --demo——它会添加一个独立的 SQLite 示例数据库（电子商务架构：customers / products / orders，包含 FK 和枚举列），让你在一分钟内试用所有工具。先快速了解一下，再将 amnesic 连接到真实数据库，非常合适。

向导会询问你要连接的数据库类型；如果尚未安装对应驱动，它会告诉你需要运行的唯一一条命令——你无需一开始就猜测要安装哪些额外组件。

向导将：

• 询问数据库类型、主机和凭据
• 在保存任何内容之前测试连接
• 将密码安全地存储在 ~/.config/amnesic/.env 中（chmod 600）
• 将连接配置块写入 ~/.config/amnesic/connections.toml

然后将 amnesic 添加到你的 AI 客户端并重启。

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

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 install amnesic

安装后，可在任何终端中运行 amnesic --help。

amnesic 存储文件的位置

设置 $AMNESIC_HOME（或在 Linux 上设置 $XDG_CONFIG_HOME）以覆盖存储位置。

稍后添加更多连接

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——例如，IT 部门轮换了密码、设置时输错了密码，或者你在手动编辑配置。

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

变量名是什么？ 它是 connections.toml 中该连接的密码所引用的环境变量。向导会自动按 <CONNECTION_NAME_UPPERCASE_WITH_UNDERSCORES>_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，其他区块的格式和注释均保持逐字节不变。

添加到你的 AI 客户端

安装 amnesic 并添加正确的驱动额外依赖后（参见快速入门（90 秒）），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 会为你完成配置：

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

不进行全局安装（临时使用）

如果你不想在系统上安装 amnesic，可以使用 uvx 或 pipx，在每次 MCP 客户端启动时获取它。请注意，必须显式传入驱动额外依赖：

// 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 经常发布新版本。请使用安装时所用的工具升级：

然后重启 MCP 客户端（Claude Code、Cursor 等），让它重新启动 amnesic 服务并加载新增工具。

升级安全，不会丢失注释。 首次加载时，你的知识文件会自动迁移到新架构；amnesic 只会添加列，从不会删除你的数据。

查看已安装版本：amnesic --version。最新版本：PyPI · Releases。

工具

搜索知识库

对于大型架构，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 排序——速度快、在本地运行，无需嵌入或外部服务。搜索语法支持：

结果会返回经过排序的表/列行，并附带描述和高亮片段。

知识层

这是核心差异化功能。每条注释都会跨重启、模型更新和新会话保留。

会话 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

现在，AI 无需猜测，就能准确知道如何跨架构执行 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，使用 # 添加注释）。对于 TOML 中引用的每个 ${VAR_NAME}，使用 amnesic set-secret VAR_NAME 填写对应的 .env 条目（输入内容会隐藏，并设置 chmod 600），也可以自行编写 .env。

规范的连接名称使用点号表示法：orders.prod、orders.staging、analytics、local。

支持的数据库

安全性与只读强制机制

amnesic 的设计旨在安全地连接生产数据库。

为什么 AI 无法破坏你的数据

每条查询在到达数据库之前，都会经过两个独立层的检查：

1. 静态分析（位于 amnesic/readonly.py）——SQL 会被分词；如果包含以下任一语句，就会被拒绝： INSERT、UPDATE、DELETE、DROP、TRUNCATE、ALTER、CREATE、EXEC、EXECUTE、MERGE、BULK、GRANT、REVOKE、DENY。 这也包括藏在 CTE 中的写入语句（例如 WITH x AS (SELECT ...) UPDATE ... 会被检测并拒绝）。
2. 事务回滚——即使写入语句以某种方式绕过了静态检查，查询也会在 BEGIN TRANSACTION ... ROLLBACK 中运行，因此任何操作都不会被提交。双重保险。

只有 SELECT 和 WITH ... SELECT 会到达数据库。分析前会去除注释，因此无法通过 /* DELETE FROM users */ 隐藏攻击。

其他安全措施

• 响应中不包含凭据：db_list_connections 会从输出中移除密码和用户名。AI 可以看到有哪些连接，但永远看不到如何向这些连接进行身份验证。
• 凭据仅通过环境变量提供：配置加载时扩展 ${ENV_VAR}——密码绝不会写入磁盘上的 connections.toml。
• 安全存储 .env：在 macOS/Linux 上使用 chmod 0o600（仅所有者可读写）；在 Windows 上，.env 位于 %APPDATA%，Windows ACL 会将其限制在你的用户配置文件范围内。
• 标识符验证：在将表名、模式名和数据库名称插入 SQL 字符串之前，会根据 [A-Za-z0-9_]+ 对其进行检查。
• 经过测试：tests/test_readonly.py 中的 40 多个单元测试涵盖所有写入关键字、注释剥离边界情况、尝试在 CTE 中写入、以分号分隔的多条语句，以及标识符注入尝试。运行 pytest tests/test_readonly.py，即可在你的机器上验证。

这对我的数据安全吗？

amnesic 仅在本地运行，且仅使用协议。它不会引入新的外部信任边界——**信任边界在于 MCP 客户端将数据发送到哪里，而不是 amnesic 本身。**选择 AI 客户端就决定了适用于你数据行的策略。

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

无论你是独立开发者还是企业，都应该坦诚地问自己：

我信任我的 AI 客户端处理此数据库中的数据吗？

如果信任——对于大多数设置来说，答案都是肯定的——那就没问题。适用场景包括：

• 使用 Claude Pro / Cursor / Copilot 处理自己的项目、开发数据库或测试数据的独立开发者
• 查询个人 SQLite 或可自托管 Postgres 的业余项目
• 处理公开架构的开源维护者
• 使用具有明确隔离机制的企业级 AI 的团队：AWS Bedrock（租户 + IAM）、Azure OpenAI（固定区域，使用你的订阅）、Anthropic Enterprise（零数据保留，可选择不用于训练）、Vertex AI（你的 GCP 项目）、可自托管（Ollama、vLLM、本地部署的 Claude/GPT——数据不会离开网络）
• 使用提供零保留保证且 DPA 覆盖你所用场景的付费 AI 计划的用户

值得进一步留意的情况

• 你的数据库中包含属于他人的数据（用户、客户、患者），且你尚未确认 AI 提供商的条款涵盖对此类数据的处理
• 你使用的是面向消费者的 AI（免费版 / 个人 Pro），并且正在处理受监管数据——PHI（受 HIPAA 约束的实体）、持卡人数据（PCI-DSS）、受 GDPR / 印度 DPDP Act 限制的 PII
• 你的雇主有明确政策，限制在生产数据库上使用外部 AI 工具
• 你受数据驻留规则约束，数据行不得离开特定区域

内置数据最小化

这是设计的一部分，而非事后补救：注释层意味着 AI 会从本地 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 相比，这显著减少了数据传输——当 AI 不清楚某个枚举值时，SQL MCP 每次都必须运行 SELECT DISTINCT status FROM orders。amnesic 则会从本地注释中一次性给出答案。

免责声明：amnesic 按原样依据 MIT License 提供（不提供保证、不承担责任——请参阅 LICENSE）。本节不构成法律或合规建议。你使用 amnesic 以及连接到它的 AI 客户端，均由你自行负责。如果你处理受监管数据，请先咨询安全 / 合规团队，再将其用于生产环境。

路线图

目前已发布：知识层（v0.1）、BM25 搜索（v0.1.5）、生命周期管理——弃用 / 漂移检测 / 遗忘（v0.2），以及可移植的知识导出 / 导入（v0.2.2）。

**接下来（v0.3——“让记忆创造价值”）：**无需任何人输入即可积累的知识——枚举自动发现、为没有约束的旧版架构推断软外键，以及学习 JOIN 模式。此外还包括基础工作：为每个响应设置令牌预算、在架构获取中加入索引和主键、缓存陈旧标记，以及精简工具数量。

完整计划及排序背后的原因，请参阅 ROADMAP.md。

🙌 欢迎贡献

v0.3 的每个事项都已作为 GitHub issue 提交，并且设计已考虑周全，包括问题、提议的方案、需要修改的文件以及测试方法。其中有几项标记为 good first issue。

选一个并提交 PR——无需事先征求同意。只需在 issue 下评论，避免两个人做同一件事。

• 👉 浏览未解决的 issue · 需要帮助 · 适合初次贡献的 issue
• 新驱动？请遵循 amnesic/drivers.py 和 amnesic/tools/schema.py 中的结构。
• 测试位于 tests/ 中。新工具需要单元测试；提交 PR 前请运行 pytest tests/。

有未列出的想法？提交 issue。 用例比补丁更有价值——能省去返工。

查看使用情况

pypistats.org/packages/amnesic

许可证

MIT — 详见 LICENSE。

MCP Registry

此服务已在 官方 MCP Registry 注册。

mcp-name: io.github.SurajKGoyal/amnesic