agami-core

Point an AI agent at a database and it answers by guessing — at the join, at what "revenue" means, at which rows it's allowed to read. agami-core is the governed layer between the agent and your data: it turns your schema into a semantic model where every join is FK-derived or human-approved, every metric is signed off by name and role, and every answer ships a receipt — the exact SQL, the model version it pinned, and who vouched for each definition. The rules live in the model, not the prompt. And it all runs on your machine — credentials, schema, and results never leave it.

What you get

• ✅ Governed answers, not guesses — every join is FK-derived or human-approved; every metric is signed off (name + role) before the runtime trusts it.

• 🧾 A receipt on every answer — the literal SQL, the tables touched, the relationships used, and the model version it pinned. Reproducible, auditable.

• 🔒 Local and private — runs inside Claude Code via Bash/Read/Write. Credentials, schema, and results never touch a server we operate.

• 🧩 A portable semantic model — plain, git-native YAML you own (subject areas, tables, entities, metrics, relationships). No lock-in.

• 🗄️ Works with your database — Postgres · Supabase · Redshift · MySQL · Snowflake · BigQuery · SQL Server · Oracle · Databricks · Trino · DuckDB · SQLite.

• 🛠️ Zero infra — no backend, no proxy. If you have a DB CLI you have everything; an optional local MCP server lets Claude Desktop use the same model.

Related MCP server: gov-mcp

Quickstart (under 5 minutes)

Fastest path — the built-in sample (no database, no credentials)

agami ships with Acme Store, a small local SQLite dataset (commerce + subscriptions) and a ready-made, signed-off semantic model. You get a governed answer — with a full receipt — in under a minute, and nothing leaves your machine.

# 1. Install the plugin (see Install below for the per-host steps).

# 2. Try the sample — no connection needed:
/agami-connect sample      # or just say "I don't have a database" / "try the sample"

# 3. Ask a question — see governance ENFORCED:
who are the top 5 customers by total spend?

# 4. Now watch the model get BUILT — see governance MADE:
/agami-connect reintrospect

Step 3 deliberately crosses a fan trap (orders → line items → payments), where a naive agent silently double-counts. agami's pre-flight catches it and returns the correct number with the join receipt — the trust layer, enforced on your first query.

Step 4 is the real point. Natural-language querying is everywhere; what's rare is where the trust comes from. reintrospect re-derives the sample's model from the live schema — introspect → infer + confidence-score every join → gate metric sign-off → re-validate examples — so you watch the governed model take shape rather than just consuming it. To see it built from a blank slate (full LLM enrichment, descriptions and all), run /agami-connect sample and pick "build the model from scratch so I can see it work" the first time. Either way it takes a few minutes — it's the demo of how the receipts you saw in step 3 are earned. Full flow: docs/usage.md.

Real database

When you're ready to connect your own database:

# 1. Run connect — picks your DB type, writes a credentials template (first run only)
/agami-connect

# 2. Fill in the template, then save + lock it down
#    (agami only runs read-only queries, so use a read-only DB user if you can —
#     ask agami for "the read-only grant" to get the exact GRANT SQL)
$EDITOR <artifacts_dir>/local/credentials.example
mv <artifacts_dir>/local/credentials.example <artifacts_dir>/local/credentials
chmod 600 <artifacts_dir>/local/credentials

# 3. Re-run connect to introspect: build the semantic model + seed examples
/agami-connect

# 4. Ask a question
how many orders did we ship last month?

/agami-connect is one-stop: it picks up missing credentials, introspects the live DB, computes confidence on every entity, auto-approves the high-signal ones (FK joins, DBA-commented fields, structural names), gates a metric sign-off before generating seed examples, and leaves the low-confidence long tail in an optional panel that self-approves as you query. Full flow: docs/usage.md. Credentials per dialect: docs/credentials.md.

Install

Platform note. Validated on macOS and Linux. On Windows the skills need Git for Windows (Claude Code uses Git Bash for its Bash tool); Windows is not yet validated end-to-end. The optional local MCP server is pure-stdlib Python and is cross-platform.

The same plugin works across Claude Code CLI, VS Code, and Cursor.

Claude Code CLI — in the Claude Code prompt:

/plugin marketplace add AgamiAI/agami-core
/plugin install agami-core@agami

Verify with /plugin list → you should see agami-core@agami v0.3.3.

VS Code / Cursor — install the Claude Code extension, type /plugin in the chat to open Manage Plugins, add the AgamiAI/agami-core marketplace, then install agami-core from the Plugins tab.

Per-host walkthroughs: docs/install/.

The trust layer

Most AI data agents quietly pick a join, quietly pick a definition of "revenue", and quietly return a number. agami makes every one of those decisions auditable:

• Confidence + review state on every entry. Each join, metric, and entity carries a flat trust block (confidence, review_state, and a sign-off identity once approved) — no vendor blobs, no scores to tune. DB-declared FKs and structural column names auto-approve; everything inferred stays unreviewed and surfaces in the Review tab.

• Metrics must be signed off (Rule 1). A metric needs an approver email, a role, and a non-empty calculation before the runtime treats it as truth — one bad metric skews every report that uses it. Joins & entities are lazy (Rule 2): usable while unreviewed, flagged on the receipt until confirmed.

• Every answer ships a receipt — the literal SQL, tables + row counts, relationships used (with confidence/state), metric definitions with author + date, data freshness, and the model snapshot hash. A warning banner appears if any unreviewed entry was used. Nothing is silently trusted.

• Snapshot-pinned + git-native. The model is YAML under ~/agami-artifacts/<profile>/, git init'd on first introspect. Every answer records the model snapshot hash, so old answers reproduce exactly and schema drift flips affected entries to stale instead of silently changing the number.

Full mechanics — the trust block, Rule 1/Rule 2, the review queue, the receipt, examples validation: docs/trust-layer.md.

Skills (slash commands)

Natural-language phrasing routes to each skill automatically — "open the review dashboard" / "save this as a correction" / "introspect my schema" all work without typing the slash command.

Privacy

agami runs entirely locally — credentials (chmod 600), the semantic model, charts, exports, and dashboards all live under ~/agami-artifacts/, and the skill never reads files outside those paths (except your DB tool's auth config, set up on first connect with your permission). Details: docs/privacy.md.

Fair-code vs hosted

agami is fair-code (source-available). Running it on your own machine — introspection, the portable semantic model, NL→SQL + local execution, the trust layer, corrections, and the local MCP server — is free to self-host for your own team. Exposing data or the MCP to people outside your organization is the paid line — the team cloud (a multi-tenant model registry over a remote MCP endpoint, shared governed context, always-on evals). The boundary, stated plainly: docs/open-vs-hosted.md.

Self-hosting the team server

Beyond the local single-player setup, agami ships an HTTP MCP server so a team can point their Claude at one shared, governed model. It's cloud-neutral (a VM + Postgres, or a stateless platform like Cloud Run + managed Postgres), configured entirely by environment variables, and LLM-free + zero-egress by default. The full setup — the pip install "agami-core[server]" install, the env-var contract, and optional Google / Microsoft (OIDC) login — is in docs/self-hosting.md. For a one-command deploy bundle, use the /agami-deploy skill.

Documentation

• Quickstart & usage — first-run walkthrough + common workflows

• Credentials — every dialect, the connection-method picker

• The trust layer — confidence, sign-off, receipts, snapshots

• Format spec — the semantic-model layout + a worked example

• MCP server — use agami from Claude Desktop

• Self-hosting the team server — the HTTP server, env-var contract, OIDC

• Troubleshooting & uninstall

• Fair-code vs hosted · Privacy

Contributing

Issues + PRs welcome at github.com/AgamiAI/agami-core. See CONTRIBUTING.md for test commands and the version-bump discipline — every user-visible change needs a version bump in .claude-plugin/marketplace.json (twice) and plugins/agami/.claude-plugin/plugin.json, or existing installs stay on the cached old version. Notable changes: CHANGELOG.md.

Before pushing, run the checks locally with uv run dev.py check (ruff + the test suite + gitleaks — the same gate CI runs on every PR). One-time setup and the full command list are in CONTRIBUTING.md; the coding + customer-safety conventions are in CLAUDE.md. CI gates every PR regardless.

If agami is useful to you, a ⭐ on the repo genuinely helps others find it.

License

fair-code (source-available) — the Agami Functional Use License. See LICENSE and NOTICE.

What's free vs. paid (internal use vs. external exposure): LICENSING.md.

Built by Agami AI.