The context your warehouse can’t hold:
how to interpret the numbers.

Same question, different answer once the knowledge is there

What changes when a data agent can read ochakai? Pick a question to see two answers to it side by side, and the one line of knowledge that changed the answer. The answers are excerpts of what Claude actually replied in our eval, translated from the Japanese.

Every answer in full, with its grading, is in examples/demo-eval/results. The scores and how the eval was run are below; to ask the same questions from your own agent, see Try the public demo.

Try the public demo

No signup required. The demo holds 37 concepts about Google’s public thelook_ecommerce dataset, built so an agent can answer one question to the end: revenue fell — why, and what now? (Latest release: v0.31.1.)

go install github.com/na0fu3y/ochakai/cmd/ochakai@latest
ochakai use https://demo.ochak.ai
ochakai search "why is revenue down?"   # Find relevant concepts
ochakai get insights/why-revenue-falls  # The full text, and what links to it

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

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

The same questions: 9 of 18 with BigQuery alone, 18 of 18 with the knowledge

Nine questions, asked twice each of Claude Code (Sonnet 5). Both runs had the same instructions and the same BigQuery; the only difference was that one could read the demo’s 37 concepts over ochakai’s MCP. A separate Claude call graded each answer against a per-question rubric, and numeric truths were computed in BigQuery at run time (2026-09-27).

Every wrong answer read the warehouse correctly and still missed. BigQuery alone summed revenue over every status (3.8 times the real figure), put all items under the return rate (10.5% where the definition gives 28.8%), and gave a fall within the usual swing a cause. Nothing in the schema says which reading is right; a few of the 37 documents did. Questions the data answers by itself, both runs got right.

It has a price: with the knowledge, twice the tool calls per question (5.5 → 11.4 turns) and twice the cost ($0.20 → $0.42). The questions were chosen by the people who wrote the knowledge, each was asked twice, with one model, graded by Claude. What it shows is that a few curated documents changed the answers to the kind of question they cover — not an accuracy figure for data agents in general. The answers, the grading and how to run it with your own questions are in examples/README.md (Japanese).

Definitions and interpretation context, in a single search

A formula alone isn’t enough for an AI agent to draw accurate conclusions. Agents also need to understand expected baselines, validated SQL queries, business policies, internal definitions, and known data quirks. ochakai indexes these concepts together, providing complete context in one lookup. Non-text assets like PDFs and diagrams are searchable as well.

These represent the recommended types, and you can easily add custom types to match your business domain. Learn more in the OKF v0.2 spec or browse practical examples in the demo bundle.

Agents discover; humans verify

Data agents uncover new insights and edge cases during real-world tasks. ochakai automatically captures these as Draft concepts in a human review queue. Once approved by a domain expert, they become verified institutional knowledge shared across all agents. Bundled hooks for Claude Code make this recall and write-back loop effortless.

The demo carries two diagnoses of revenue an agent wrote back, both still drafts: May 2024’s −13%, which it judged within the usual swing and proposed nothing for, and March 2026, when booked items rose 17% and revenue did not. Each keeps its BigQuery job ids as receipts and waits for a person to verify it.

A practical ontology, without enterprise overhead

Connecting data schemas to business meaning is what lets agents make sound, context-aware decisions. ochakai asks for no dedicated ontology type and no forward-deployed engineers (FDEs): concepts link to each other through ordinary Markdown links, and those links are the structure.

In the demo, table concepts play the part of objects, and joins live in each table’s # Joins section and in the Insights about joins that are not obvious. Revenue is split into three Metrics — booked items, completion rate and average item price — and from each you can follow links to the computation that says which one moved, the action it leads to, and where the data runs out. How this maps onto Palantir Foundry’s vocabulary is in glossary/ontology (Japanese).

How ochakai fits into your stack

If all you need is metric definitions served to agents over MCP, semantic layers and data catalogs already do that. ochakai is designed to complement existing tools rather than replace them: user preferences and session history live in memory layers, data models in semantic layers, and human-verified domain insights in ochakai. The data-agent platforms are another matter: Databricks Genie, Snowflake Cortex Agents, BigQuery Conversational Analytics and Hex Threads are finished data agents, and ochakai's own agent (off by default) competes with them head-on, and today loses on features. What it competes on: an answer names the concepts it rests on and whether a person confirmed them, and the knowledge leaves whole as OKF.

Deploy & Get Started

ochakai deploys directly into your own Google Cloud project, keeping your data, context, and provenance strictly under your own control.

Data portability is guaranteed: ochakai export retrieves your entire knowledge base in standard OKF format (Markdown with YAML frontmatter), ready to check into Git or migrate to any other tool.

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

# One-time manual setup: bootstrap the schema (SQL printed by terraform output)
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 SQL output from `terraform output -raw database_bootstrap_sql`

terraform output -raw use_command   # Output the ochakai use command to share with your team

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

# Project table schemas into draft concepts. ochakai never connects to your warehouse
# Note: --max_rows ensures all columns are captured (default query truncates at 100 rows)
bq query --max_rows=100000 --format=json --nouse_legacy_sql \
  'SELECT table_schema, table_name, column_name, data_type, is_nullable
     FROM `your-project.your_dataset.INFORMATION_SCHEMA.COLUMNS`
    ORDER BY ordinal_position' \
  | ochakai seed - | ochakai import -

claude mcp add ochakai -- ochakai mcp-stdio

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