amnesic 0.1.0__tar.gz

amnesic-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e .[dev]
+
+      - name: Run tests
+        run: pytest tests/ -v

amnesic-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+
+    # Trusted Publishing — no token, no secrets to manage.
+    # Configure once at https://pypi.org/manage/account/publishing/
+    permissions:
+      id-token: write   # required for OIDC to PyPI
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No password/token needed — OIDC handles authentication via Trusted Publisher.

amnesic-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.env
+.pytest_cache/
+.coverage
+htmlcov/
+.DS_Store

amnesic-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suraj Goyal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

amnesic-0.1.0/PKG-INFO

@@ -0,0 +1,326 @@
+Metadata-Version: 2.4
+Name: amnesic
+Version: 0.1.0
+Summary: The MCP server with the most ironic name in the registry — persistent semantic memory for your SQL databases
+Project-URL: Homepage, https://github.com/SurajKGoyal/amnesic
+Project-URL: Repository, https://github.com/SurajKGoyal/amnesic
+Project-URL: Issues, https://github.com/SurajKGoyal/amnesic/issues
+Author-email: Suraj Goyal <sgoyal275@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-tools,claude,database,llm,mcp,mssql,mysql,postgres,sql
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: rich>=13.0
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: all
+Requires-Dist: psycopg2-binary>=2.9; extra == 'all'
+Requires-Dist: pymssql>=2.2; extra == 'all'
+Requires-Dist: pymysql>=1.1; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: mssql
+Requires-Dist: pymssql>=2.2; extra == 'mssql'
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.1; extra == 'mysql'
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary>=2.9; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# 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."*
+
+---
+
+## 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.
+
+---
+
+## Install
+
+```bash
+# Core only (SQLite works out of the box)
+pip install amnesic
+
+# With driver extras
+pip install "amnesic[postgres]"
+pip install "amnesic[mssql]"
+pip install "amnesic[mysql]"
+pip install "amnesic[all]"
+
+# Or run directly with uvx (no install needed)
+uvx amnesic
+```
+
+---
+
+## Setup
+
+### 1. Create config
+
+```bash
+amnesic init
+```
+
+This creates `~/.config/amnesic/connections.toml` with a commented template.
+
+### 2. Edit the config
+
+```toml
+# ~/.config/amnesic/connections.toml
+
+# Nested style: [connections.product.env]
+[connections.orders.prod]
+driver = "mssql"
+server = "localhost"
+port = 11433
+database = "OrdersDB"
+user = "${ORDERS_PROD_USER}"
+password = "${ORDERS_PROD_PASSWORD}"
+tunnel_script = "~/.scripts/mssql-tunnel.sh"  # optional SSH tunnel
+
+[connections.orders.staging]
+driver = "mssql"
+server = "localhost"
+port = 11434
+database = "OrdersDB_Staging"
+user = "${ORDERS_STAGING_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 = "/Users/me/data/local.db"
+```
+
+Use `${ENV_VAR}` for credentials — never hardcode passwords.
+
+Canonical connection names use dot notation: `orders.prod`, `orders.staging`, `analytics`, `local`.
+
+### 3. Test connectivity
+
+```bash
+amnesic test              # tests all connections
+amnesic test orders.prod  # tests one connection
+```
+
+---
+
+## Add to your AI client
+
+### Claude Code
+
+Add to `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "amnesic": {
+      "command": "uvx",
+      "args": ["amnesic"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "amnesic": {
+      "command": "uvx",
+      "args": ["amnesic"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):
+
+```json
+{
+  "mcpServers": {
+    "amnesic": {
+      "command": "uvx",
+      "args": ["amnesic"]
+    }
+  }
+}
+```
+
+### VS Code (with MCP extension)
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "amnesic": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["amnesic"]
+    }
+  }
+}
+```
+
+---
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `db_list_connections()` | List all configured connections (no secrets exposed) |
+| `db_list_tables(connection)` | All known tables with descriptions and column counts |
+| `db_get_schema(table, connection)` | Column schema merged with saved annotations |
+| `db_query(sql, connection)` | Execute a read-only SELECT query |
+| `db_annotate(table, connection, ...)` | Persist semantic annotations for tables/columns |
+| `db_sync_knowledge(from, to)` | Copy annotations between connections (e.g. staging → prod) |
+| `db_discover_relationships(connection)` | Discover all FK relationships from the live DB |
+| `db_get_relationships(table, connection)` | Navigate the FK graph for JOIN planning |
+
+---
+
+## The knowledge layer
+
+The core differentiator. Every annotation survives restarts, model updates, and new sessions.
+
+### Session 1 — you discover something
+
+```
+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.
+```
+
+### Session 2 — the knowledge is already there
+
+```
+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 ...
+```
+
+No re-discovery. No wasted turns. The annotation persisted.
+
+---
+
+## Relationship graph
+
+Understand your schema's JOIN structure once, reuse it forever.
+
+```
+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
+```
+
+Now the AI knows exactly how to JOIN across your schema without guessing.
+
+---
+
+## Sync between environments
+
+Build up annotations in staging, then promote to prod:
+
+```
+db_sync_knowledge(from_connection="orders.staging", to_connection="orders.prod")
+```
+
+Returns `{synced: [...], skipped: [{table, reason}], warnings: [{table, column, reason}]}`.
+
+Tables missing from the target schema cache are skipped with a clear reason. Columns missing from target schema are warned but don't block the rest of the sync.
+
+---
+
+## Supported databases
+
+| Database | Driver | Extra |
+|----------|--------|-------|
+| PostgreSQL | psycopg2 | `pip install "amnesic[postgres]"` |
+| MySQL / MariaDB | pymysql | `pip install "amnesic[mysql]"` |
+| Microsoft SQL Server | pymssql | `pip install "amnesic[mssql]"` |
+| SQLite | built-in | no extra needed |
+
+---
+
+## Security
+
+- **Read-only enforcement**: two layers — static SQL analysis rejects any write/DDL statement before a connection opens, plus every query runs inside an immediately-rolled-back transaction.
+- **No credentials in responses**: `db_list_connections` strips passwords and usernames from output.
+- **Credentials via env vars**: `${ENV_VAR}` expansion at load time — secrets never touch the config file on disk.
+- **Identifier validation**: table names, schema names, and database names are validated against `[A-Za-z0-9_]` before any interpolation into SQL.
+
+---
+
+## Roadmap
+
+What's coming: knowledge lifecycle management (v0.2 — `db_deprecate`, drift detection, export/import for team handoff), query intelligence (v0.3 — `db_explain`, query history), team sharing (v0.4), and more. See [ROADMAP.md](./ROADMAP.md) for the full picture.
+
+Have an idea? [Open an issue.](https://github.com/SurajKGoyal/amnesic/issues/new)
+
+---
+
+## Track usage
+
+[pypistats.org/packages/amnesic](https://pypistats.org/packages/amnesic)
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

amnesic-0.1.0/README.md

@@ -0,0 +1,289 @@
+# 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."*
+
+---
+
+## 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.
+
+---
+
+## Install
+
+```bash
+# Core only (SQLite works out of the box)
+pip install amnesic
+
+# With driver extras
+pip install "amnesic[postgres]"
+pip install "amnesic[mssql]"
+pip install "amnesic[mysql]"
+pip install "amnesic[all]"
+
+# Or run directly with uvx (no install needed)
+uvx amnesic
+```
+
+---
+
+## Setup
+
+### 1. Create config
+
+```bash
+amnesic init
+```
+
+This creates `~/.config/amnesic/connections.toml` with a commented template.
+
+### 2. Edit the config
+
+```toml
+# ~/.config/amnesic/connections.toml
+
+# Nested style: [connections.product.env]
+[connections.orders.prod]
+driver = "mssql"
+server = "localhost"
+port = 11433
+database = "OrdersDB"
+user = "${ORDERS_PROD_USER}"
+password = "${ORDERS_PROD_PASSWORD}"
+tunnel_script = "~/.scripts/mssql-tunnel.sh"  # optional SSH tunnel
+
+[connections.orders.staging]
+driver = "mssql"
+server = "localhost"
+port = 11434
+database = "OrdersDB_Staging"
+user = "${ORDERS_STAGING_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 = "/Users/me/data/local.db"
+```
+
+Use `${ENV_VAR}` for credentials — never hardcode passwords.
+
+Canonical connection names use dot notation: `orders.prod`, `orders.staging`, `analytics`, `local`.
+
+### 3. Test connectivity
+
+```bash
+amnesic test              # tests all connections
+amnesic test orders.prod  # tests one connection
+```
+
+---
+
+## Add to your AI client
+
+### Claude Code
+
+Add to `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "amnesic": {
+      "command": "uvx",
+      "args": ["amnesic"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "amnesic": {
+      "command": "uvx",
+      "args": ["amnesic"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):
+
+```json
+{
+  "mcpServers": {
+    "amnesic": {
+      "command": "uvx",
+      "args": ["amnesic"]
+    }
+  }
+}
+```
+
+### VS Code (with MCP extension)
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "amnesic": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["amnesic"]
+    }
+  }
+}
+```
+
+---
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `db_list_connections()` | List all configured connections (no secrets exposed) |
+| `db_list_tables(connection)` | All known tables with descriptions and column counts |
+| `db_get_schema(table, connection)` | Column schema merged with saved annotations |
+| `db_query(sql, connection)` | Execute a read-only SELECT query |
+| `db_annotate(table, connection, ...)` | Persist semantic annotations for tables/columns |
+| `db_sync_knowledge(from, to)` | Copy annotations between connections (e.g. staging → prod) |
+| `db_discover_relationships(connection)` | Discover all FK relationships from the live DB |
+| `db_get_relationships(table, connection)` | Navigate the FK graph for JOIN planning |
+
+---
+
+## The knowledge layer
+
+The core differentiator. Every annotation survives restarts, model updates, and new sessions.
+
+### Session 1 — you discover something
+
+```
+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.
+```
+
+### Session 2 — the knowledge is already there
+
+```
+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 ...
+```
+
+No re-discovery. No wasted turns. The annotation persisted.
+
+---
+
+## Relationship graph
+
+Understand your schema's JOIN structure once, reuse it forever.
+
+```
+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
+```
+
+Now the AI knows exactly how to JOIN across your schema without guessing.
+
+---
+
+## Sync between environments
+
+Build up annotations in staging, then promote to prod:
+
+```
+db_sync_knowledge(from_connection="orders.staging", to_connection="orders.prod")
+```
+
+Returns `{synced: [...], skipped: [{table, reason}], warnings: [{table, column, reason}]}`.
+
+Tables missing from the target schema cache are skipped with a clear reason. Columns missing from target schema are warned but don't block the rest of the sync.
+
+---
+
+## Supported databases
+
+| Database | Driver | Extra |
+|----------|--------|-------|
+| PostgreSQL | psycopg2 | `pip install "amnesic[postgres]"` |
+| MySQL / MariaDB | pymysql | `pip install "amnesic[mysql]"` |
+| Microsoft SQL Server | pymssql | `pip install "amnesic[mssql]"` |
+| SQLite | built-in | no extra needed |
+
+---
+
+## Security
+
+- **Read-only enforcement**: two layers — static SQL analysis rejects any write/DDL statement before a connection opens, plus every query runs inside an immediately-rolled-back transaction.
+- **No credentials in responses**: `db_list_connections` strips passwords and usernames from output.
+- **Credentials via env vars**: `${ENV_VAR}` expansion at load time — secrets never touch the config file on disk.
+- **Identifier validation**: table names, schema names, and database names are validated against `[A-Za-z0-9_]` before any interpolation into SQL.
+
+---
+
+## Roadmap
+
+What's coming: knowledge lifecycle management (v0.2 — `db_deprecate`, drift detection, export/import for team handoff), query intelligence (v0.3 — `db_explain`, query history), team sharing (v0.4), and more. See [ROADMAP.md](./ROADMAP.md) for the full picture.
+
+Have an idea? [Open an issue.](https://github.com/SurajKGoyal/amnesic/issues/new)
+
+---
+
+## Track usage
+
+[pypistats.org/packages/amnesic](https://pypistats.org/packages/amnesic)
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).