agami-core

The trust layer between AI and your data. Local. Private. Yours.

_{agami-core — the fair-code core of Agami.}

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.

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 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.

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.

• Step-by-step deploy (VM, DNS, TLS, the variants — Cloudflare Tunnel, managed Postgres, Cloud Run):
  deploy/README.md.
• Env-var contract, the pip install "agami-core[server]" path, and Google / Microsoft (OIDC) login:
  docs/self-hosting.md.

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 — the HTTP server, env-var contract, OIDC login
• 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.