Skip to content
KOSHA

Quick start

This page walks you through installing KOSHA on your Mac and running your first query. Total time: about five minutes once Gemma 4 has finished downloading.

Before you start

You need:

  • A Mac running macOS 13 (Ventura) or later. Apple Silicon (M1/M2/M3/M4) recommended; Intel works but slower.
  • At least 8 GB of RAM to run local Gemma 4 (E2B). Less than 8 GB → KOSHA disables local mode and uses your chosen cloud LLM only.
  • About 8 GB of free disk for the model file plus the database.
  • A Google account for sign-in.

Step 1 — Install Ollama (one-time)

KOSHA’s local mode runs on top of Ollama, the standard local-LLM runtime. Install it once:

Terminal window
brew install ollama

Or download the installer from ollama.com/download.

Verify it works:

Terminal window
ollama --version

Step 2 — Pull the Gemma 4 model

Pull the E2B variant (~7.2 GB on disk):

Terminal window
ollama pull gemma4:e2b

This download takes 5–15 minutes on a fast connection. The model is stored at ~/.ollama/models/.

Step 3 — Install KOSHA

Download the latest .dmg from the beta site. Open it and drag the app to Applications.

The first time you launch, macOS asks if you trust the developer. KOSHA is signed by SUMA Pro AI — click Open.

Step 4 — Sign in with Google

KOSHA opens to a sign-in screen. Click Sign in with Google, choose your account, and grant the requested scopes (openid, email, profile — KOSHA reads your name and email, nothing else).

Behind the scenes, KOSHA creates:

  • A row in kosha_users for your Google identity.
  • A KOSHA database (kosha_dbs) on this Mac, owned by you.
  • One workspace (kosha_nabhas) named Personal.
  • Eight default categories (kosha_grahas at depth 0) inside that workspace: WORK, FAMILY, HEALTH, FINANCE, IDENTITY, SOCIAL, LOGISTICS, KNOWLEDGE.

You can rename any of the eight, but you can’t delete them.

Step 5 — Drop in your first piece of data

Click any of the eight categories. Inside, click + to create a new GRAHA, give it a name (for example, Tesla research), and paste a paragraph of source text:

Suman bought a Tesla Model Y from a private seller in San Francisco for $58,000 last week. The car had 12,000 miles on it and one previous owner.

KOSHA stores the paragraph and, in the background, asks Gemma 4 to extract structured ASHRU facts from it. Within a couple of seconds you’ll see something like:

V|buy|Suman|Tesla Model Y|$58000||private seller|San Francisco|p|0|date=2026-04-30

That’s a 10-column pipe row. The fields are positional — no JSON keys, no whitespace tax — and contain enough structure for the LLM to answer questions about the fact later.

Step 6 — Ask your first question

Open the chat sidebar and ask:

What did Suman buy and from whom?

KOSHA looks up GRAHAs whose content is relevant, plus extracted ASHRU facts, and sends them to Gemma 4 along with your question. Gemma 4 answers locally:

Suman bought a Tesla Model Y from a private seller for $58,000 in San Francisco.

The status indicator in the menu bar should be 🟢 green — meaning the query never left your laptop. Below the answer you’ll see “Tokens used: 1,243 — saved $0.0023 vs cloud.”

What’s next

If something went wrong

  • “unidentified developer” on first launch — right-click the app → Open, then Open in the dialog. (One-time only.)
  • Sign-in loops — confirm your Mac’s clock is set automatically (System Settings → General → Date & Time). OAuth signature validation depends on accurate time.
  • Local Gemma not detected — confirm Ollama is running: ollama serve. Then in KOSHA, Settings → Local AI → Re-detect.

If none of those help, open an issue with the output of Settings → About → Diagnostics.