Agami Core

What is Agami Core about?

Agami Core provides a trust layer between AI agents and your data. It turns a database schema into a portable, git‑native YAML semantic model where every join, metric, and entity is either derived from foreign keys or explicitly signed off. Each AI‑generated answer includes a receipt that shows the exact SQL, relationships used, model version, and sign‑off details, preventing silent guesses and ensuring auditable results.

How to use Agami Core?

1. Install the plugin in Claude Code, VS Code, or Cursor (/plugin marketplace add AgamiAI/agami-core).
2. Connect to a data source with /agami-connect. You can:
   • Run the built‑in sample (/agami-connect sample) for a zero‑setup demo.
   • Provide a real database connection; the tool creates a credentials template, you fill it in, and Agami introspects the schema.
3. Ask natural‑language questions directly in the chat. The system routes the query to /agami-query, generates and runs the SQL, and returns results with a provenance receipt.
4. Govern the model via /agami-model to review, edit, and sign off metrics, joins, and entities. Unreviewed items trigger warnings in receipts.
5. Share with a team by deploying the optional HTTP MCP server (Docker bundle) and letting teammates point their Claude instances to a single URL.

Key features of Agami Core

• Governed answers: joins are FK‑derived or human‑approved; metrics require sign‑off.
• Receipt on every answer: full SQL, tables, relationships, model snapshot hash, and author information.
• Local and private execution: runs on the user’s machine; no data leaves the environment.
• Portable semantic model: plain YAML stored under ~/agami-artifacts/, versioned with Git.
• Broad database support: Postgres, MySQL, Snowflake, BigQuery, Redshift, SQL Server, Oracle, Databricks, Trino, DuckDB, SQLite, etc.
• Zero‑infra start: optional local MCP server for Claude Desktop; Docker‑based shared server for teams.
• Self‑hosted Docker deployment: one‑command bundle creates HTTPS endpoint with OAuth and admin console.

Use cases of Agami Core

• Business intelligence: enable analysts to ask ad‑hoc questions in natural language while guaranteeing data governance.
• Data validation: compare existing dashboard numbers with AI‑generated queries using /agami-reconcile.
• Metric catalog management: maintain a centrally governed catalog of business metrics with versioned sign‑offs.
• Secure AI‑assisted reporting: provide AI‑driven insights inside regulated environments where audit trails are required.
• Team‑wide self‑service analytics: deploy a shared server so non‑technical users can query the governed model without installing anything.

FAQ from the Agami Core

Q: Do I need to expose my database to the cloud? A: No. All introspection and query execution happen locally; the optional server is self‑hosted within your infrastructure.

Q: What if I don’t have a database? A: Use the built‑in sample (/agami-connect sample) which ships a small SQLite dataset and a pre‑signed semantic model.

Q: How are metrics approved? A: Each metric must have an approver email, role, and a non‑empty calculation. Until approved, the receipt flags the metric as unreviewed.

Q: Can I edit the semantic model? A: Yes, via the /agami-model dashboard or by editing the YAML files directly; changes are tracked with Git.

Q: What platforms are supported? A: macOS and Linux are validated; Windows works with Git Bash for the CLI part. The MCP server is pure Python and cross‑platform.

Get started in 2 minutes

In Claude Code — CLI, VS Code, or Cursor:

/plugin marketplace add AgamiAI/agami-core
/plugin install agami-core@agami
/agami-connect sample          # zero setup: no database, no credentials
who are the top 5 customers by total spend?

That last line returns a governed answer with a receipt (the exact SQL, the joins used, the model version) — and it crosses a fan trap a naive agent would silently double-count. Three ways to go from here:

• 🧪 No database? The commands above answer from a built-in sample — nothing leaves your machine.
• 🗄️ Have a database? Run /agami-connect to introspect it into a governed semantic model, then just ask questions.
• 👥 Want your team on it? Deploy a shared server » — teammates and business users point their own Claude (claude.ai or the desktop app) at one URL and query your governed model. They install nothing.

Each path is walked through in full below (Quickstart · Install · Deploy a shared server).

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 to start — 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.
• 👥 Shareable with your team — when you're ready, deploy one governed server that your whole team and business users query from their own Claude over a URL — self-hosted, still zero-egress.

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.

Your own database

Connecting your database is a short back-and-forth with agami — you fill in one template, and it handles the rest:

1. Start setup. Run /agami-connect (or just say "connect to my database"). agami asks which database you use, has you name the connection, and writes a credentials template for you to fill in.
2. Fill in the template. Open the file agami points you to, add your connection details, and save it — leave the filename as-is. agami only ever runs read-only queries, so a read-only database user is all it needs; ask agami for "the read-only grant" and it gives you the exact SQL to create one.
3. Say "introspect my database" (or just "continue"). agami takes it from there: it locks the file down for you (no manual chmod), reads your schema, builds the semantic model, and seeds a few validated example queries. You don't move or rename anything.
4. Ask a question — "how many orders did we ship last month?"

That's the whole setup. Along the way agami scores its confidence in every join and entity, auto-approves the clear ones (real foreign keys, well-named columns), and asks you to sign off the judgment calls. Full walkthrough: docs/usage.md. Connection details for each database: 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 installed.

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.

Command	What it does
/agami-connect	One-stop setup + introspect: detect/collect credentials, introspect the live DB into the semantic model (tables, columns, PK grain, FK relationships, sensitive-column flags), layer LLM enrichment, generate EXPLAIN-validated seed examples. Validator-gated; git init + snapshots. Also /agami-connect sample for the no-DB sample.
/agami-query	Answers a natural-language question: picks examples + relationships, generates and runs SQL, formats the result + chart, and surfaces a provenance receipt. Flags any unreviewed entry it relied on. (Usually you don't type this — plain language routes here.)
/agami-model	One dashboard to browse, curate, and sign off the model: every table/field/metric/entity/join, per-table/column Exclude/Include, edits, new metrics. The Review tab is the trust-layer sign-off queue. Open it on the queue with /agami-model review.
/agami-save-correction	Records a correction and routes it to the right home (SQL example, column metadata, display preference, business concept, or a new metric), showing its classification before writing. Attribution surfaces on future answers it influences.
/agami-reconcile	Point it at an existing dashboard — a screenshot (Metabase / Power BI / Tableau / Looker) or a CSV of known numbers; it generates each question, runs it through agami, and shows a side-by-side diff with tolerances. Validate the model against numbers you already trust.
/agami-serve	Use agami from the Claude Desktop app: wires up the optional local MCP server (same tools as the hosted connector, backed by your local model + execution — stdio, read-only, no network). See docs/mcp-server.md.
/agami-deploy	Deploy a shared team server. Writes a ready-to-run Docker bundle (the published image + HTTPS + OAuth + an admin console) so a team can stand up one governed server their Claude connects to. Business users query it over a URL — no local setup. Detailed steps: deploy/README.md.

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.

Deploy a shared server for your team

The local setup is single-player. To put your whole team — and non-technical business users — on one governed model, deploy agami's HTTP MCP server to your own host. Everyone then connects their own Claude (claude.ai as a custom connector, or the desktop app) to one HTTPS URL and asks questions in plain language. They install nothing, touch no credentials, and only ever see the model you've governed. An admin console (/admin) controls who's allowed in; the warehouse stays behind a read-only user, and no data leaves your environment.

The paved path is one command in Claude:

/agami-deploy      # writes a ready-to-run Docker bundle: published image + HTTPS (Caddy) + OAuth + admin

It gathers your hostname and admin identity, writes docker-compose.yml + a filled agami.env (referencing the published ghcr.io/agamiai/agami-core image — no clone, no build), and either runs docker compose up locally or prints the exact VM steps and the shareable /mcp URL.

The full step-by-step — VM, DNS/TLS, and every variant (Cloudflare Tunnel, managed Postgres, Cloud Run) — is in deploy/README.md. (Prefer to wire it up by hand instead of using the bundle? The manual install + environment-variable reference covers that.) Admins sign in with a password; teammates get per-user access to /mcp.

It's cloud-neutral (a VM + Postgres, or a serverless platform + managed Postgres), configured entirely by environment variables, and LLM-free + zero-egress by default. Self-hosting this for people inside your organization is free; exposing data to people outside it is the paid line (fair-code vs hosted).

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
• Deploy a shared team server — the Docker bundle, step-by-step (VM, DNS/TLS, variants)
• Self-hosting reference — manual (non-Docker) install + the environment-variable reference
• 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.