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 がこの問題を解決します。 データベースごとに、セッションをまたいで残る永続的な SQLite ナレッジストアを AI に提供します。ステータス列挙値に一度注釈を付ければ、今後のすべてのセッションでそのラベルが自動的に使われます。外部キーの関係を一度見つければ、今後のすべての JOIN クエリでその関係グラフが使われます。

ナレッジは持ち運び可能で、データベースへのアクセス権を失ったあとも残ります。プロジェクトを離れるとき、amnesic export を使えば、次の開発者に教えたことをすべて引き継げます。そうしなければあなたとともに失われてしまう、何年分もの「そのカラムは実は……」という知識です。

amnesic の位置づけ

データベース MCP エコシステムは 2 つの陣営に分かれていますが、amnesic は意図的にどちらにも属しません。

クエリ実行ツール — DBHub、Postgres MCP Pro、Google's MCP Toolbox、およびベンダーのサーバー（Supabase、Neon）です。稼働中のデータベースをイントロスペクションし、SQL を実行します。また、パフォーマンスを深く分析できるものもあります。Postgres MCP Pro は、実際のインデックス調整や PgHero 形式のヘルスチェックを行います。これらは優れたツールです。一方で、ステートレスです。セッションごとにスキーマを最初から学び直す必要があり、返される情報から列の意味を知ることはできません。データベース自体もその意味を知らないからです。

エンタープライズカタログ — DataHub、Atlan、Cube、AtScale です。これらは用語集、列の説明、オーナーシップ、リネージといったセマンティックコンテキストを保持します。その一方で、プラットフォームへのコミットメントが必要です。メタデータの取り込み、稼働させるサービス、通常は有料プランが求められます。企業規模なら導入する価値がありますが、レガシーな MSSQL データベースにある 6 つのステータスコードの意味を記憶しておきたいだけの開発者 1 人にとっては、明らかに過剰です。そのデータベースがカタログに登録されることは今後もないでしょう。

amnesic は第 3 の選択肢です。クエリ実行ツール並みのセットアップコストで、カタログ相当のセマンティックメモリを提供します。pipx install、TOML ファイル 1 つ、データベースごとのローカル SQLite ファイルを使います。プラットフォームも、取り込みも、稼働させるサーバーも不要です。

公平な比較

実行計画、インデックスの推奨事項、データベースのヘルス診断が必要なら、amnesic ではなくクエリ実行ツールを使ってください。 それは amnesic の役割ではありません。追加すれば、すでに存在するツールの劣化版になってしまいます。

クエリ実行ツールと併用してください。 これらは組み合わせて使えます。両方を実行するのを妨げるものはありません。amnesic は意味を保持し、クエリ実行ツールは仕組みを担います。

上記で ⚠️ が付いている項目は、未解決の課題として報告されている既知の不足点です。ロードマップ ↓を参照してください。

クイックスタート（90 秒）

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

⚡ 認証情報なしで試せます。 代わりに amnesic init --demo を実行してください。自己完結型の SQLite サンプル DB（EC スキーマ：customers／products／orders、外部キーと enum 列を含む）が追加され、1 分もかからずにすべてのツールを試せます。実際のデータベースを 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 はパスワードを自動的に保存するため、一般的なセットアップの流れでは、このセクションを気にする必要はありません。

後から保存済みのパスワードを変更する必要がある場合（IT 部門がパスワードをローテーションした場合、セットアップ時に入力を間違えた場合、または設定を手動で編集している場合）は、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 が参照する環境変数です。ウィザードは、次の形式でこれらの変数名を自動生成します：<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 をインストールすると（クイックスタートを参照）、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 は BM25 ランキングを使用した SQLite FTS5 を使います。高速でローカルに動作し、埋め込みや外部サービスは不要です。検索構文は次のとおりです。

結果には、説明と強調表示されたスニペットを含む、ランキング順のテーブル／列の行が返されます。

ナレッジレイヤー

amnesic の中核となる差別化要素です。すべてのアノテーションは、再起動、モデルの更新、新しいセッション後も保持されます。

セッション 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、1 行につき 1 つ、コメントには # を使用）。TOML で参照する各 ${VAR_NAME} について、amnesic set-secret VAR_NAME（入力は非表示、chmod 600）で対応する .env エントリを設定するか、.env を自分で作成してください。

接続名の標準形式ではドット表記を使用します：orders.prod、orders.staging、analytics、local。

対応データベース

安全性と読み取り専用の適用

amnesic は、本番データベースに接続しても安全に使えるように設計されています。

AI にデータを破損させない仕組み

すべてのクエリは、データベースに到達する前に、独立した 2 つのレイヤーを通過します。

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 はローカル専用かつプロトコル専用です。新たな外部の信頼境界を設けるものではありません。信頼境界となるのは、amnesic 自体ではなく、MCP クライアントがデータを送信する先です。 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）を利用し、かつ規制対象データ（HIPAA の対象事業者が扱う PHI、カード会員データ（PCI-DSS）、GDPR／インドの DPDP Act に基づく制限対象の PII）を扱う場合
• 雇用主が本番データベースでの外部 AI ツールの使用を制限する明示的なポリシーを定めている場合
• レコードを特定のリージョン外に出せないデータレジデンシー規則の対象である場合

データ最小化を組み込み済み

これは後付けではなく、設計上の特性です。アノテーション層により、AI はスキーマに関する質問の大半にローカルの SQLite ナレッジファイルから回答できます。db_query は実行されず、レコードデータがどこかに送信されることもありません。

• 「status=3 は何を意味しますか？」 → 保存済みのアノテーションから解決します
• 「orders と users はどのように結合しますか？」 → 外部キーグラフから解決します
• 「created_at 列があるテーブルはどれですか？」 → スキーマキャッシュから解決します

純粋に構造を調べる場合、6 つのツールはデータに一切触れません。db_list_tables、db_get_schema、db_search、db_annotate、db_discover_relationships、db_get_relationships です。返されるのはメタデータのみです。

これは、AI が列挙型について判断に迷うたびに SELECT DISTINCT status FROM orders を実行しなければならない「むき出し」の SQL MCP よりも、データの移動量を明確に減らします。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 レジストリ

このサーバーは公式 MCP レジストリに登録されています。

mcp-name: io.github.SurajKGoyal/amnesic