内容
# amnesic — 注册中名称最具讽刺意味的MCP服务器
[](https://pypi.org/project/amnesic/)
[](https://pypi.org/project/amnesic/)
[](LICENSE)
[](https://registry.modelcontextprotocol.io)
[](https://glama.ai/mcp/servers/SurajKGoyal/amnesic)
**针对 SQL 数据库的持久语义记忆。名称带有讽刺意味 — 它记得一切。**
*"注册中名称最具讽刺意味的MCP服务器。它绝非健忘 — 它记得你的数据库，这样你的 AI 不必记住。"*
<p align="center">
<img src="assets/demo.svg" alt="只需教你的 AI 一个状态码，然后用普通语言查询它，永久生效。你的 AI 代理调用 amnesic 的工具；amnesic 跨会话记住。" width="720">
</p>
**适用于** Claude Code · Claude Desktop · Cursor · VS Code · Cline · Windsurf — 任意 [MCP 兼容客户端](https://modelcontextprotocol.io/clients)。
**可在** [官方 MCP 注册表](https://registry.modelcontextprotocol.io) · [Claude Code 插件市场](https://github.com/SurajKGoyal/amnesic-marketplace)
> 🔒 **设计为只读。** amnesic 拒绝执行 `INSERT`、`UPDATE`、`DELETE`、`DROP`、`TRUNCATE`、`ALTER`、`CREATE`、`EXEC`、`MERGE`、`GRANT`、`REVOKE` — 以及任何通过 `WITH` CTE 偷运的写语句。两层防御：静态 SQL 分析在连接前拒绝该语句，**并且** 每个查询都在一个立即回滚的事务中运行。安全地指向生产环境。[详情 ↓](#安全性和只读强制)
---
## 问题
每次与 AI 的会话都从头开始。你花费前几分钟时间重新解释存在哪些表、`status` 列的值为 `3` 代表什么，哪个外键连接 `orders` 和 `users`。然后会话结束，你又要在明天重新做一遍。
**amnesic 解决了这个问题。** 它为你的 AI 提供了一个持久的 SQLite 知识库 — 每个数据库一个 — 该知识库在会话之间存活。注释一次状态枚举；每个未来的会话都会自动看到这些标签。发现一次外键关系；每个未来的 JOIN 查询都会使用该图。
---
## 快速入门（90 秒）
```bash
pipx install amnesic # 安装核心
amnesic init # 交互式向导
```
> ⚡ **无需凭证试用。** 运行 `amnesic init --demo` — 它添加了一个自包含的 SQLite 示例数据库（电子商务模式：客户/产品/订单，带有外键和枚举列），这样你可以在一分钟内测试所有工具。非常适合在指向真实数据库之前先了解一下。
向导会询问你要连接的数据库类型，并告诉你一个命令，如果其驱动程序尚未安装 — 你无需预先猜测额外的依赖。
向导：
- 询问你的数据库类型、主机和凭证
- 在保存任何内容之前测试连接
- 安全地将密码存储在 `~/.config/amnesic/.env`（chmod 600）
- 将连接块写入 `~/.config/amnesic/connections.toml`
然后 [将 amnesic 添加到你的 AI 客户端](#添加到你的AI客户端) 并重启。
<details>
<summary><b>没有 <code>pipx</code>？或更喜欢 <code>uv</code> / 普通 <code>pip</code>？</b></summary>
<br/>
**安装 `pipx`** （一次性）：
```bash
brew install pipx # macOS
sudo apt install pipx # Linux（Debian/Ubuntu）
python -m pip install --user pipx # Windows / 通用
```
**或使用 `uv`** （单二进制替代 — 快速，无需 Python）：
```bash
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 环境）：
```bash
pip install amnesic
```
> 无论你选择哪种，`amnesic init` 都会询问你要连接的数据库，并打印安装该驱动程序所需的命令 — 无需预先提交额外的依赖。
</details>
安装后，`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`（或 Linux 上的 `$XDG_CONFIG_HOME`）以覆盖位置。
### 稍后添加更多连接
```bash
amnesic add # 将另一个连接添加到现有配置
amnesic test # 验证所有连接
amnesic test orders.prod # 验证一个连接
```
### 设置和旋转密码
`amnesic init` 和 `amnesic add` 自动保存你的密码 — 对于典型的设置流程，你无需考虑本节。
使用 `set-secret` 当你需要更改存储的密码时 — IT 旋转了它，你在设置过程中输入错误了，或者你正在手动编辑配置文件。
```bash
$ amnesic set-secret ORDERS_PROD_PASSWORD
Value: **** ← 隐藏输入（你的输入不可见）
Confirm: ****
✓ 在 ~/.config/amnesic/.env 中设置 ORDERS_PROD_PASSWORD
```
**变量名是什么？** 它是你的 `connections.toml` 引用的环境变量，用于该连接的密码。向导自动生成这些变量，格式为 `<CONNECTION_NAME_UPPERCASE_WITH_UNDERSCORES>_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 文件中。这些命令允许你在机器之间移动它并进行清理：
```bash
# 导出 amnesic 关于数据库的所有内容（注释 +
# 关系，不是可推导的模式缓存）为可移植的 JSON：
amnesic export orders.prod -o orders-knowledge.json
amnesic export orders.prod # 或打印到 stdout 进行管道/重定向
# 将该知识加载到另一个连接（例如，从暂存区提升到生产环境，
# 或为队友提供支持）。无条件更新 — 现有条目将被覆盖：
amnesic import orders.prod orders-knowledge.json
# 清除连接的存储知识，但保留配置项：
amnesic clear orders.staging
# 从 connections.toml 中完全删除一个连接（知识文件保留
# 除非你传递 --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 SurajKGoyal/amnesic-marketplace
/plugin install amnesic@amnesic
这会自动将 amnesic 配置为 MCP 服务器。来源：[SurajKGoyal/amnesic-marketplace](https://github.com/SurajKGoyal/amnesic-marketplace)。
<details>
<summary><b>或手动配置 — 编辑 <code>~/.claude/mcp.json</code></b></summary>
<br/>
```json
{
"mcpServers": {
"amnesic": {
"command": "amnesic"
}
}
}
```
</details>
### 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`
```json
{
"mcpServers": {
"amnesic": {
"command": "amnesic"
}
}
}
```
### Cursor
**一键安装** — 点击下面的按钮，Cursor 会为你配置：
<a href="https://cursor.com/en-US/install-mcp?name=amnesic&config=eyJjb21tYW5kIjoiYW1uZXNpYyJ9"><img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="将 amnesic 添加到 Cursor" height="32"></a>
<details>
<summary><b>或手动配置 — 编辑 <code>.cursor/mcp.json</code></b></summary>
<br/>
在项目中添加 `.cursor/mcp.json`（或全局 `.cursor/mcp.json`）：
```json
{
"mcpServers": {
"amnesic": {
"command": "amnesic"
}
}
}
```
</details>
### 无全局安装（临时）
如果你不想在系统上安装 amnesic，请使用 `uvx` 或 `pipx` 在每次 MCP 客户端启动时获取它。注意，必须显式传递驱动程序扩展：
```json
// uvx — 需要安装 `uv`（请参阅每个 OS 的安装部分）
{
"mcpServers": {
"amnesic": {
"command": "uvx",
"args": ["--from", "amnesic[mssql]", "amnesic"]
}
}
}
// pipx — 通常通过 Homebrew 或系统包管理器预安装
{
"mcpServers": {
"amnesic": {
"command": "pipx",
"args": ["run", "--spec", "amnesic[mssql]", "amnesic"]
}
}
}
```
对于多个驱动程序，请在方括号内用逗号分隔 — 例如 `amnesic[postgres,mssql]` 或使用 `amnesic[all]` 获取所有驱动程序。
### VS Code（带有 MCP 扩展）
将以下内容添加到 `.vscode/mcp.json`:
```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](https://pypi.org/project/amnesic/) · [Releases](https://github.com/SurajKGoyal/amnesic/releases).
---
## 工具
| 工具 | 描述 |
|------|-------------|
| `db_list_connections()` | 列出所有配置的连接（不暴露机密） |
| `db_list_tables(connection)` | 所有已知表及其描述和列数 |
| `db_search(query, connection, target, limit)` | 表/列描述和别名的 BM25 搜索 |
| `db_get_schema(table, connection)` | 合并注释的列模式 |
| `db_query(sql, connection)` | 执行只读 SELECT 查询 |
| `db_annotate(table, connection, ...)` | 持久化表/列的语义注释 |
| `db_deprecate(table, connection, column?, reason?, undo?)` | 软退役过时的注释 — 标记（和警告）但保留，可逆 |
| `db_detect_drift(connection)` | 审核注释 vs 实时模式 — 查找孤立的注释 + 未记录的表 |
| `db_forget(table, connection, column?, cascade?)` | 硬删除注释（可选级联） — 永久 |
| `db_sync_knowledge(from, to)` | 在连接之间复制注释（例如，从暂存区到生产环境） |
| `db_discover_relationships(connection)` | 从实时数据库发现所有外键关系 |
| `db_get_relationships(table, connection)` | 导航 FK 图以进行 JOIN 规划 |
---
## 搜索知识库
对于大型模式，`db_list_tables` 不实用 — 你会向 Claude 的上下文中转储 500+ 行。使用 `db_search` 而是按关键字查找相关表/列：
```
"哪个表跟踪客户付款？"
→ db_search("payments")
顶级结果：
- dbo.payments （表）"客户付款记录...”
- dbo.orders.payment_method （列）"付款方式...”
```
`db_search` 使用 **SQLite FTS5 with BM25 ranking** — 快速，本地，无需嵌入式或外部服务。搜索语法支持：
| 语法 | 效果 |
|--------|--------|
| `payment` | 匹配单词（带有词干 — 也匹配“payments”，“paying”） |
| `"payment method"` | 确切短语 |
| `pay*` | 前缀匹配 — "payment", "payable", etc. |
| `payment AND status` | 两个术语必需 |
| `payment OR refund` | 任一术语 |
返回带有描述和突出显示的表/列行。
---
## 知识层
核心区别。每个注释在重启、模型更新和新会话之间存活。
### 会话 1 — 你发现了某些东西
```
你：status=3 在 orders 表中意味着什么？
AI: Let me check. [runs db_query: SELECT DISTINCT status FROM dbo.orders]
我看到值 1, 2, 3, 4. Let me look at some examples...
根据数据，3 似乎是“cancelled”。
你：保存。 And status=1 是“pending”，2 是“confirmed”，4 是“delivered”。
AI: [calls db_annotate]
db_annotate(
table="dbo.orders",
column="status",
column_description="订单生命周期状态",
enum_values={"1": "pending", "2": "confirmed", "3": "|": "cancelled", "4": "delivered"}
)
Saved. Future sessions will see these labels automatically.
```
### 会话 2 — 知识现成可用
```
你：本月有多少个已取消的订单？
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。
---
## 环境间同步
在暂存区建立注释，然后推广到生产环境：
```bash
db_sync_knowledge(from_connection="orders.staging", to_connection="orders.prod")
```
返回 `{synced: [...], skipped: [{table, reason}], warnings: [{table, column, reason}]}`。
目标模式缓存中缺少的表会被跳过，并附有明确的原因。目标模式中缺少的列会被警告，但不会阻止同步的其余部分。
---
## 高级：手动编辑 TOML
如果您更喜欢自己管理配置文件，请生成一个空白模板：
```bash
amnesic init --template
```
这会写入 `~/.config/amnesic/connections.toml` 并退出 — 无需向导。直接编辑文件：
```toml
# ~/.config/amnesic/connections.toml
# 嵌套风格： [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}"
# 平坦风格： [connections.name]
[connections.analytics]
driver = "postgres"
server = "analytics.company.com"
port = 5432
database = "warehouse"
user = "${ANALYTICS_DB_USER}"
password = "${ANALYTICS_DB_PASSWORD}"
# SQLite — 无需凭证
[connections.local]
driver = "sqlite"
database = "/absolute/path/to/local.db" # macOS / Linux
# database = "C:/path/to/local.db" # Windows (使用正斜杠)
```
使用 `${ENV_VAR}` 获取凭证 — 永远不要硬编码密码。
机密会自动从 `~/.config/amnesic/.env` 加载（格式：`KEY=VALUE`，一行一个，`#` 为注释）。对于每个在 TOML 中引用的 `${VAR_NAME}`，使用 [`amnesic set-secret VAR_NAME`](#设置和旋转密码)（隐藏输入，chmod 600），或自己编写 `.env`。
规范的连接名称使用点表示法：`orders.prod`、`orders.staging`、`analytics`、`local`。
---
## 支持的数据库
| 数据库 | Python 驱动程序 | 安装方式 |
|----------|---------------|--------------|
| PostgreSQL | `psycopg2-binary` | 向导提示时安装，或使用 `amnesic[postgres]` 扩展 |
| MySQL / MariaDB | `pymysql` | 向导提示时安装，或使用 `amnesic[mysql]` 扩展 |
| Microsoft SQL Server | `pymssql` | 向导提示时安装，或使用 `amnesic[mssql]` 扩展 |
| SQLite | 标准库 `sqlite3` | 始终可用 — 无需额外 |
---
## 安全性和只读强制
amnesic 设计为指向生产数据库是安全的。
### 为什么您的人工智能无法损害您的数据
每个查询在到达数据库之前都会经过 **两个独立的层** 的检查：
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` 会从其输出中剥离密码和用户名。 人工智能可以知道哪些连接存在，但无法知道如何验证这些连接。
- **凭证仅通过环境变量传递**：`${ENV_VAR}` 在配置加载时会被展开 — 密码永远不会接触到磁盘上的 `connections.toml` 文件。
- **安全的 `.env` 存储**：在 macOS/Linux 上，`.env` 文件的权限被设置为 `0o600`（仅所有者可读/写）；在 Windows 上，`.env` 文件存放在 `%APPDATA%` 目录中，该目录仅对您的用户配置文件开放，受到 Windows ACL 的限制。
- **标识符验证**：在将表/模式/数据库名称插入 SQL 查询之前，会检查它们是否匹配正则表达式 `[A-Za-z0-9_]+`。
- **经过测试**：`tests/test_readonly.py` 中的 40 多个单元测试涵盖了每个写操作关键字、注释剥离边缘情况、带有写操作的 CTE 尝试、 semicolon 分隔的多语句和标识符注入尝试。 可以通过运行 `pytest tests/test_readonly.py` 在本地验证。
---
## 这对我的数据安全吗？
amnesic 仅限本地使用且仅限于协议层面。 它不会引入新的外部信任边界 — **信任边界是您的 MCP 客户端发送数据的地方，而不是 amnesic 本身**。 选择人工智能客户端决定了适用于您的数据行的策略。
```
您的数据库 → amnesic（本地）→ MCP 客户端 → 您的人工智能部署
↑ 信任边界位于此处
```
您需要诚实地问问自己，无论您是独立开发者还是企业用户：
**我是否信任我的 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**（免费/个人专业版）并且正在处理受监管的数据 — **PHI**（HIPAA 涵盖的实体），**卡片持有者数据**（PCI-DSS），**GDPR/印度 DPDP 法案下的受限 PII**
- 如果您的雇主有 **明确的政策** 限制在生产数据库上使用外部 AI 工具
- 如果您受到 **数据驻留** 规则的约束，数据行不能离开特定区域
### 数据最小化是内置的
这是一种设计属性，而不是事后才想到的：注解层意味着 AI 可以从 **本地 SQLite 知识文件** 中回答大多数模式问题 — 不会运行 `db_query`，不会将任何行数据发送到任何地方。
- *"status=3 是什么意思？"* → 从您保存的注解中解析
- *"订单如何与用户关联？"* → 从外键图解析
- *"哪些表有 `created_at` 列？"* → 从模式缓存中解析
对于纯粹的结构探索，六种工具永远不会触及您的数据：`db_list_tables`，`db_get_schema`，`db_search`，`db_annotate`，`db_discover_relationships`，`db_get_relationships`。 它们只返回元数据。
这比“裸”SQL MCP（每次 AI 对枚举感到困惑时都必须运行 `SELECT DISTINCT status FROM orders`）要好得多。 amnesic 只需从本地注解中回答一次。
> **免责声明**：根据 MIT 许可证（无担保，无责任 — 参见 [LICENSE](LICENSE)）提供 amnesic。 本节不是法律或合规建议。 您使用 amnesic 以及您连接到的 AI 客户端是您的责任。 如果您处理受监管的数据，请在将其指向生产环境之前咨询您的安全/合规团队。
---
## 路线图
即将推出：知识生命周期管理（v0.2 — `db_deprecate`，漂移检测，导出/导入团队交接），查询智能（v0.3 — `db_explain`，查询历史），团队共享（v0.4）等。 有关完整内容，请参见 [ROADMAP.md](./ROADMAP.md)。
有想法吗？ [打开一个问题](https://github.com/SurajKGoyal/amnesic/issues/new)。
---
## 跟踪使用情况
[pypistats.org/packages/amnesic](https://pypistats.org/packages/amnesic)
---
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
---
## MCP 注册表
此服务器已在 [官方 MCP 注册表](https://registry.modelcontextprotocol.io) 注册。
```
mcp-name: io.github.SurajKGoyal/amnesic
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器