The difference between “revenue is down 15%” and “it’s August.”

An agent wired to a semantic layer aggregates with the right definitions and gets as far as revenue fell. What no schema tells it is that the fall arrives every August — Obon, the week the whole country stops buying — that a move inside ±6% is ordinary noise, or that a late morning partition is indistinguishable from a genuinely bad day. Those readings live in somebody’s experience and nowhere in the schema. ochakai is a context layer for data agents: it keeps them verified, with provenance, and serves them to Claude Code and every other data agent over MCP, REST and a CLI.

Ask the live demo — no account View on GitHub

$ ochakai search "why is revenue down?"
insights/reading-revenue      stable  売上の読み方
metrics/revenue               stable  売上
policies/revenue-recognition  stable  売上計上ポリシー (FY2026)

$ ochakai get insights/reading-revenue
売上が 1 割下がったなら、まず件数を見る。
# If revenue is down a tenth, look at order count
#  first.

直近 6 か月はどの月も、売れた金額の 27〜29% が
返品で抜けている。
# In each of the last six months, 27-29% of what
#  was sold was later pulled back out by returns.

linked from: metrics/revenue (Metric, unverified)

Two calls against the live demo, with columns trimmed. The Japanese is what the demo returns, verbatim; the # lines are this page’s rendering of it, not output. The demo’s knowledge base is written in Japanese, because that is what a knowledge base a Japanese team keeps looks like — and an English question still reaches it, which is the whole point of the search. The linked from line is the same row the other way round: ochakai get metrics/revenue names this reading, which is how the caveat that says how to read a metric reaches whoever reads the metric. It reads unverified because the demo was imported and nobody has ruled on it here: a human ruling is the only thing that makes a concept verified — and the demo takes writes, so that human can be you. No LLM ran to produce any of it.

Start by asking the public demo

There is nothing to sign up for. Install the CLI and three commands later the knowledge comes back. Latest release v0.27.5, 2026-08-27.

go install github.com/na0fu3y/ochakai/cmd/ochakai@latest
ochakai use https://demo.ochak.ai
ochakai search "why is revenue down?"
ochakai get insights/reading-revenue

search ranks what bears on the question; get hands one concept back in full.

ochakai ui --url https://demo.ochak.ai

To read it in a browser instead, the same CLI serves the web UI. Open http://127.0.0.1:8098 and the review screen further down this page comes up, pointed at the demo. There is nothing to deploy.

No Go toolchain? Take a prebuilt binary

# Apple Silicon Mac shown. Intel Mac is darwin_amd64, Linux linux_amd64 / linux_arm64,
# Windows windows_amd64.zip — all on the same release page
curl -LO https://github.com/na0fu3y/ochakai/releases/download/v0.27.5/ochakai_0.27.5_darwin_arm64.tar.gz
tar xzf ochakai_0.27.5_darwin_arm64.tar.gz
sudo mv ochakai /usr/local/bin/
ochakai use https://demo.ochak.ai
ochakai search "why is revenue down?"

The archive carries the examples/demo knowledge bundle too, so it is also what you import later into a base of your own.

On Claude Desktop: a one-click MCP install

1. Download ochakai_0.27.5.mcpb from the release page.

2. Open the file and Claude Desktop installs it. The one thing it asks for is the server URL, and the public demo’s is already filled in, so confirming it connects you (macOS and Windows).

Definitions and how to read them, in the same search

A definition on its own doesn’t get an agent to a right answer. It also needs how to read the number, which query it may trust, which rules decide it, what the words mean inside this company, and the traps already known about the underlying table. One ochakai search ranks all of them together. Documents that are not text — screenshots, PDFs — are searchable too.

Metric

What the number means, and the names it goes by inside the company

Attested Computation

A sanctioned computation, and the means to check a run of it afterwards. Golden queries

Skill

The procedure for actually running one of those computations. What the executor reads

Insight

How to read a metric. Baselines, seasonality, caveats, thresholds

Policy

The rules that decide a number: revenue recognition, cost allocation

Glossary Term

The vocabulary itself. What a word means here

BigQuery Dataset

The catalog entry one level up: the container the tables sit in

BigQuery Table

The catalog entry: where the data comes from, notes on the columns, and the problems people already know about

Reference

A copy of an outside document: an enum's definition, a license, a schema doc

Those are the recommended types, and the types your own domain needs go in as they are. How to write one is the OKF v0.2 spec; what written ones look like is the demo bundle.

The agent learns; a human confirms

Agents learn something new on every job. ochakai has them write it back as drafts, and puts those drafts in front of a human to verify.

The ochakai draft review queue, in the Japanese web UI: two concepts an agent wrote back, each with a draft badge, its tags, how often it was actually read, and Verify and Reject buttons. — In the draft review queue, the drafts that were actually read most often rank highest, so the knowledge most in demand gets reviewed first.

The ontology promise, without the FDEs

Build a digital twin of the organization and run decisions on top of it. ochakai gives you the promise a Palantir-style ontology sells, without the expensive platform and without the forward-deployed engineers (FDEs) who encode the meaning for you.

Documents connect to each other through the markdown links in their own bodies. You can start with a few terms and metrics, and what you write is what becomes structure: the smallest ontology that still works.

How to divide the work with the tools you run

If all you need is metric definitions served to agents over MCP, semantic layers and data catalogs already do that. What this table shows is where ochakai differs and what it deliberately refuses. It is a division of labour, not a scoreboard, and they compose: preferences to a memory layer, models to a semantic layer, verified data knowledge to ochakai.

ochakai compared with semantic layers, memory layers, data catalogs, and forward-deployed-engineer ontologies
Capability	ochakai	Semantic layers / warehouse-nativedbt, Cortex Analyst, Databricks Genie	Memory layersmem0, Zep, Letta	Data catalogsOpenMetadata, DataHub, Atlan	FDE ontologiesPalantir-style
Interpretation knowledge	Has a type of its own. `Insight` holds the baseline, the seasonality and the caveats, ranks in the same search as the definition, and is named on the definition’s own read	Has none. The definition comes back; whether the number is good or bad does not	Has it, but only what an LLM extracted, and per user	Has none. Definitions, lineage and owners, and it stops there	Has it, written into the ontology by hand
Human review and provenance	A human promotes a draft to `verified`. Who wrote it, and who verified it when, is on every document, and every change is kept as a revision	Yes, through the same code review the data already goes through	No review. A wrong memory quietly stays wrong	Yes. Stewardship and certification, different in every tool	Yes, built by hand by the engineers on site
What growing it costs	The standing labour is the agent’s. A human verifies only the judgment-heavy core	Modeling work, folded into the workflow that already ships the data	Automatic. The LLM extracts and nobody curates. By far the least effort, and right for what it is for	Harvested by connectors, then curated	Forward-deployed engineers, on site
Which clients it serves	Any. MCP, REST and a CLI feed Claude Code, hosted agents and CI jobs from one knowledge base	It varies. dbt is open over MCP; Cortex Analyst and Genie each stay inside their own chat	Any, through an SDK or an API	Any, through an API	Only inside the platform
What the knowledge is left as when you stop	Markdown with frontmatter. The files ochakai stores, which go into git as they are, and trust and provenance ride in the same file	Files in your own repository. dbt models are already there	The vendor’s own format, as it is	Pulled out through an API, in a format that differs by tool	Nothing is left. The ontology is the platform’s
Does it touch the warehouse	It doesn’t. A real weakness, said plainly: it holds no warehouse credentials and lives outside it. Running the SQL is the agent’s job	It does. Inside the warehouse, next to the data and its governance	It doesn’t	It doesn’t. It describes the data	It does, inside the platform
Self-hostable	Yes. MIT, run per tenant on one Go binary and Postgres for about $10 a month. Google Cloud is recommended, not required (off it, search is lexical only)	Partly. dbt yes; Cortex Analyst and Genie come with the warehouse	Partly. mem0 and Letta have open-source editions	Yes. OpenMetadata and DataHub are open source	No

Deploy it

ochakai runs inside your own Google Cloud project, and the knowledge and its provenance stay with you.

When you stop, ochakai export hands the whole base back as OKF (markdown with frontmatter). It carries straight into whatever tool you use next, after ochakai is switched off.

Stand it up Terraform brings up Cloud Run + Cloud SQL

git clone https://github.com/na0fu3y/ochakai && cd ochakai/deploy/terraform
cp terraform.tfvars.example terraform.tfvars   # project, region, invokers
terraform init
terraform apply    # creating Cloud SQL takes 10–15 minutes

# one manual step: bootstrap the schema (terraform output prints the SQL to paste)
gcloud sql users set-password postgres --instance=ochakai --prompt-for-password
cloud-sql-proxy "$(terraform output -raw sql_connection_name)" --port 55432 &
psql "host=localhost port=55432 dbname=ochakai user=postgres"
# inside psql, run the output of `terraform output -raw database_bootstrap_sql` and you are done

terraform output -raw use_command   # the ochakai use command to hand your team

Without Terraform: the gcloud commands, one at a time

Excerpted as-is from the deployment guide (Japanese), which also explains why each resource is shaped the way it is, carries the full text of the one-off bootstrap SQL, and covers the branches: sharing an existing Postgres instance, GCS for file attachments, and so on.

export PROJECT_ID=<your-project>
export REGION=asia-northeast1
gcloud config set project $PROJECT_ID
gcloud services enable run.googleapis.com sqladmin.googleapis.com \
  sql-component.googleapis.com artifactregistry.googleapis.com

# Cloud Run cannot pull from ghcr.io directly, so create a repository that proxies it
gcloud artifacts repositories create ghcr \
  --repository-format=docker \
  --mode=remote-repository \
  --remote-docker-repo=https://ghcr.io \
  --location=$REGION
export VERSION=0.27.5
export IMAGE=$REGION-docker.pkg.dev/$PROJECT_ID/ghcr/na0fu3y/ochakai:$VERSION

# the database (10–15 minutes to create)
gcloud sql instances create ochakai \
  --database-version=POSTGRES_17 \
  --edition=enterprise \
  --tier=db-f1-micro \
  --region=$REGION \
  --storage-size=10 \
  --storage-type=SSD \
  --no-storage-auto-increase \
  --no-backup \
  --database-flags=cloudsql.iam_authentication=on
gcloud sql databases create ochakai --instance=ochakai
export DB_PASSWORD=$(openssl rand -hex 24)
gcloud sql users create ochakai --instance=ochakai --password=$DB_PASSWORD

# the service account. IAM database auth, so no password appears anywhere in the deployment
gcloud iam service-accounts create ochakai-run --display-name="ochakai service"
export SERVICE_ACCOUNT=ochakai-run@$PROJECT_ID.iam.gserviceaccount.com
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:$SERVICE_ACCOUNT --role=roles/cloudsql.client
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:$SERVICE_ACCOUNT --role=roles/cloudsql.instanceUser
export DB_SA_USER=ochakai-run@$PROJECT_ID.iam
gcloud sql users create $DB_SA_USER --instance=ochakai --type=cloud_iam_service_account

# here, once, cloud-sql-proxy + psql set up the extensions and object grants (full SQL in §3 of the guide)

# deploy, and let your organization invoke it
gcloud run deploy ochakai \
  --image=$IMAGE \
  --region=$REGION \
  --service-account=$SERVICE_ACCOUNT \
  --no-allow-unauthenticated \
  --min-instances=0 --max-instances=1 \
  --cpu=1 --memory=512Mi \
  --add-cloudsql-instances=$PROJECT_ID:$REGION:ochakai \
  --set-env-vars="OCHAKAI_DB_IAM_AUTH=true" \
  --set-env-vars="OCHAKAI_DATABASE_URL=postgres:///ochakai?host=/cloudsql/$PROJECT_ID:$REGION:ochakai&user=$DB_SA_USER"
gcloud run services add-iam-policy-binding ochakai --region=$REGION \
  --member=domain:your-org.example --role=roles/run.invoker

# semantic search (particularly worth it for a Japanese base)
gcloud services enable aiplatform.googleapis.com
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:$SERVICE_ACCOUNT --role=roles/aiplatform.user

Grow it Put your own knowledge in

# project the skeleton of your own tables. ochakai never touches the warehouse
# --max_rows is not optional: bq query prints the first 100 rows and says nothing about the rest
bq query --max_rows=100000 --format=json --nouse_legacy_sql \
  'SELECT table_schema, table_name, column_name, data_type, is_nullable, description
     FROM `your-project.your_dataset.INFORMATION_SCHEMA.COLUMNS`
    ORDER BY ordinal_position' \
  | ochakai seed - | ochakai import -

Every document you import lands as a draft. It becomes knowledge once somebody adds how to read it. How small to scope it, what to write in what order, which documents to link, and how to check that an agent’s search really finds what you wrote are all in the guide, the first month (Japanese). The manual is Japanese by design; docs/en.md is the English reader’s way into it: what each page holds, in what order, and the names to search for.

Per-client MCP setup

Claude Code has a shell, so the CLI is the recommended interface there (tool schemas never occupy the agent’s context). To attach it as an MCP tool anyway:

claude mcp add ochakai -- ochakai mcp-stdio

For Claude Desktop the .mcpb bundle above is the shortest path. To write it yourself, put this in the claude_desktop_config.json that Settings → Developer → Edit Config opens:

{
  "mcpServers": {
    "ochakai": { "command": "ochakai", "args": ["mcp-stdio"] }
  }
}

Cursor, VS Code, Windsurf, Cline, Zed and Gemini CLI take the same two shapes with different key names. The full list, and how to tell what is wrong when a client won’t connect, is in the MCP guide (Japanese). Against Cloud Run, every client needs ochakai on PATH and a gcloud auth login.