Personal AI Kukku Me User Guide

What's New in Kukku 2.0

• Redesigned look & feel: refreshed UI with new animations and emoji icons rendered with Metal shaders.
• New Home Dashboard: the Kukku Smart card, Reflection card, call-to-action agents and horizontal rails put your day and your agents right at hand.
• All Agents view: browse every agent in either grid or card layout.
• Four new seeded agents: Habits, Expenses, Food & Nutrition (Nutrition Analyst) and Everyday Agent, plus an updated Health & Fitness agent.
• Journals: a new per-agent feature with today, weekly and monthly views for habits, expenses, nutrition and health.
• Skills: Kukku native Habit Tracker and Expense Tracker skills, with support for additional skills that follow the skills.md standard. See the Skills Guide.
• New local model: a Gemma 4 E2B model option on capable devices for stronger on-device results.
• Escalation & remote models: connect an agent to a more powerful remote or OpenAI-compatible endpoint with your own API key — Kukku always asks first.
• Experimental MCP tools: early support for Model Context Protocol tools.

Your Home Dashboard

The home screen is your day at a glance, reading across meals, habits, money and movement — all on-device.

Kukku Smart card

Reads across your activity, food, habits and spending and writes back a plain-English summary of how your day is really going.

Reflection card

An evening check-in that closes the loop and helps you wind down.

CTA agents & horizontal rails

Quick call-to-action tiles and scrollable rails surface your most-used agents and next actions without hunting through menus.

All Agents view

Open the full dashboard to see every agent, switching between grid and card layouts to suit how you browse.

Seeded Agents & Journals

Kukku 2.0 ships with ready-to-use agents so tracking and analytics work immediately. (For the separate Habit Tracker and Expense Tracker skills, see the Skills Guide.)

• Habits — streaks, completion and daily nudges.
• Expenses — budgets, categories, spending trends and receipt scanning.
• Food & Nutrition (Nutrition Analyst) — calorie and macro estimates from a meal photo, with meal history.
• Health & Fitness — steps, activity, heart rate and sleep from Apple Health.
• Everyday Agent — calendar events and quick everyday tasks.
• Plus updated Image Analyzer and Knowledge Base agents.

Point your camera at real life

Snap a receipt to log an expense, or snap a meal to estimate calories and macros — no forms, no typing.

Journals

As agents log data, each relevant agent builds Journals with today, weekly and monthly views for habits, expenses, nutrition and health — whichever window best suits the data. Journals are a built-in agent feature, and analytics happens internally.

Disclaimer: Calorie, macro and health figures are estimates for personal awareness, not medical advice.

1. Quick Start

1. Complete onboarding and model setup.
2. Select an agent from your dashboard.
3. Ask your first question (text or image).
4. Enable required tools for your workflow.
5. Upload documents if you want document-grounded answers.

Premium Subscription: Required for Analyzer mode (tools orchestration), Near By Kukku Agents, and Near By Kukku Bots.

2. Model Setup and Modes

Kukku provides two routing modes in setup:

• Analyzer mode: Required for all tool orchestration and multi-step tool execution.
• Direct mode: Direct responses only; tool flows are not available in this mode.

Subscription note: Tool usage requires Analyzer mode and Premium subscription. Basic mode uses Direct routing without tool flows.

Local models

Local AI is powered by community models optimized for Apple MLX. On capable, higher-memory devices you can select a Gemma 4 E2B model (effective 2B parameters, ~5.3B actual per Google) for stronger on-device results; lower-memory devices should keep the default low-memory profile for stability.

Escalation and remote models

• Escalation mode lets an agent reach out to a more powerful model when a task needs it. Kukku always asks before routing your request off-device.
• Connect an agent to a remote model or an OpenAI-compatible external endpoint by adding your own API key, base URL and model name.
• Only the prompt and context for that request are sent to the provider you configured; local-first stays the default.

Enable MCP Client Tool

MCP is off by default. In Model Setup, open Tooling Features and turn on Enable MCP Client Tool. Once enabled, an “MCP Client” tool type appears in Tools and can call configured MCP servers. For the full connection walkthrough, see Connect an MCP Server below.

Advanced settings

Fine-tune quality/performance with temperature, top-p, repetition controls, and token limits.

3. Quick Agent Setup and Editing

Quick Agent Setup

1. Open agent actions and choose Quick Agent Setup.
2. Pick domain/expertise and define role/personality.
3. Select recommended tools for that role.
4. Review prompts and save.

Quick Agent Setup is designed for general device compatibility and does not require high-memory hardware.

Edit Agents

• Update name, description, personality, suggested prompts, and response style.
• Adjust routing behavior and workflow intent for the agent.
• Revisit tool assignment after every major agent change.

4. Tools Management (Practical)

1. Open Tools and create or edit tool entries.
2. Configure credentials for provider-backed tools.
3. Add custom keywords when you want stronger tool routing hints.
4. Assign tools to specific agents only where needed.
5. Tools are agent-specific. After a tool is edited, update only the agents that use that tool.
6. Use ToolPack import if required tool groups are missing.

Important after Edit Tool: Ensure you add/remove that tool in each agent that uses it, then Save Agent, so the edited tool configuration takes effect in that specific agent. Recommended steps per affected agent: open Edit Agent → remove the tool → Save Agent → open Edit Agent again → add the same tool → Save Agent.

If a tool is not used during chat, check: agent assignment, permissions, credentials, and tool keywords.

Connect an MCP Server (MCP Client Tool)

The MCP Client tool lets an agent call tools exposed by a Model Context Protocol (MCP) server. First enable it in Model Setup → Tooling Features → Enable MCP Client Tool, then add it like any other tool.

Quick setup

1. Go to Actions → Tools and add a new tool of type MCP Client.
2. Fill the MCP Client Configuration fields (see below).
3. Save the tool, then assign it to an agent and Save Agent.
4. In Analyzer mode, ask the agent to use the capability; MCP tools are discovered from the server automatically.

Configuration fields

• MCP Name — a label for this connection, e.g. My Tickets.
• Server URL — the MCP server endpoint, e.g. https://mcp.example.com/mcp.
• Authentication — how credentials are sent: Bearer token (recommended), Header API key, Query API key, or None.
• API Key / Token — your key, session key or token (shown for every mode except None).
• API Secret (optional) — a paired secret, shown for Header and Query modes when your server needs one.
• Header Name — the header the key is sent in (Header mode; default x-api-key).
• Query Key Name — the query parameter the key is sent in (Query mode; default api_key).
• Default MCP Tool (optional) — a specific tool name to call by default, e.g. list_tickets.

Advanced MCP Options

• Extra Headers JSON (optional) — additional headers as JSON, e.g. {"X-Org":"acme"}.
• Include Tools — comma-separated allowlist; only these server tools are exposed, e.g. list_tickets,create_ticket.
• Exclude Tools — comma-separated denylist to hide specific tools, e.g. delete_ticket.
• Read-only tools only — expose only non-destructive tools.
• Max tools exposed — cap the number of tools surfaced to the model (default 3, range 1–20).
• Discovery Mode — how eagerly tools are discovered: Simple, Progressive, or Aggressive (recommended).

Connection examples

• Bearer token: Authentication = Bearer token, API Key / Token = your token. Sent as Authorization: Bearer <token>.
• Header API key: Authentication = Header API key, API Key / Token = your key, Header Name = x-api-key (or your server's header). Add API Secret only if required.
• Query API key: Authentication = Query API key, API Key / Token = your key, Query Key Name = api_key (or your server's parameter).
• Filtering: use Include / Exclude Tools and Read-only tools only to keep the agent focused and safe.

Experimental: MCP support is early and may change across releases. Quick setup needs only Name, Server URL, Authentication and API Key — use Advanced options only when your MCP server requires them. Credentials are stored on-device and redacted from backups.

5. How to Influence Agent Output

Agent-level controls

• System prompt: Define role, tone, guardrails, and response format (for example bullets, JSON, table, step-by-step).
• Assigned tools: Add or remove tools to control what actions the agent can perform.
• Workflow section: Add deterministic tool-calling steps when you need strict execution order.

Tool-level controls

• Tool name and description: Strongly influence when and why the model picks that tool.
• Keyword routing: Improves trigger precision for specific intents.
• Tool usage examples: Teach correct invocation patterns and reduce routing mistakes.

Model-level synthesis controls

• Advanced settings: Tune temperature, top-p, repetition controls, and output token limits.
• Longer responses: Increase output token limit (not character count) for more detailed answers.

Ground the agent with an advisory document

Uploading a document to an agent is the most direct way to bias its responses toward guidance you trust. When you add an advisory — a note from a coach, dietician, physician, or financial advisor — the agent reads it as context and takes it into consideration when it answers, so its suggestions follow that advisory's preferences, limits, and tone instead of generic defaults.

How to use it:

1. Download a sample advisory below (or write your own as a plain .txt).
2. In the app, open Actions → Manage Documents, select the Scope (the agent name) you want to ground, and upload the file from iOS.
3. Ask a related question. The agent now grounds its reply in the advisory — for example a Health & Fitness agent will keep activity within a physician's stated limits.

Sample advisories to download and upload:

• Wellness coach — habit plan · grounds a Habits agent
• Dietician — nutrition plan · grounds a Food & Nutrition agent
• Physician — post-discharge activity note · grounds a Health & Fitness agent
• Financial advisor — budget note · grounds an Expenses agent

Grounding vs. facts: An advisory biases how the agent responds; it does not guarantee the model repeats it verbatim. Keep advisories short and specific for the strongest effect. These samples are for demonstration only and are not professional medical, dietetic, or financial advice — replace them with guidance from your own qualified professional.

Practical order: First adjust system prompt/workflow, then tool metadata, then model advanced settings.

6. Team Agents

• Team Agents orchestrate multiple member agents for larger workflows.
• Use Team Agents when you need multi-step, multi-specialist responses.
• Best experience is on high-memory devices due to higher runtime load.

Recommendation: Use Team Agents primarily on higher-memory devices for smoother performance.

7. Connecting to Near By Kukku Agents

1. Open Near By Kukku Agents from dashboard.
2. Set a pairing password in Pairing Security (required).
3. Tap Scan to discover nearby peers.
4. Select a peer and tap Connect (Locked).
5. Enter pairing password if prompted.
6. After connection, wait for remote agent list.
7. Tap Add on any remote agent to include it in your dashboard.

Premium only: Near By Kukku Agents requires Premium subscription. Insecure peers are not connectable.

8. Connecting to Near By Kukku Bots

1. Open Near By Kukku Bots from dashboard.
2. Scan and select a discovered bot.
3. Add your Gateway Token in the bot flow.
4. Tap Connect and complete approval if requested.
5. Tap Discover to load remote bot agents.
6. Tap Add to bridge selected agents into dashboard.

Premium only: Near By Kukku Bots requires Premium subscription. OpenClaw-compatible local gateway discovery is supported; no special Wi-Fi name is required.

9. Tools and Output Cards

Assign tools to each agent based on use case (search, reminders, calendar, messaging, knowledge, finance, sports).

For per-tool setup and examples, use the dedicated Tools Guide.

• For messaging tools, Kukku may resolve recipient details first using contacts.
• Health and stock flows can render specialized cards in chat for easier consumption.
• If a tool fails, verify permission + API setup + agent assignment.

10. Documents and Backup

Document workflows

• Upload PDF, image, or text files in Document Library, or attach using the chat Files option.
• Wait for processing before asking document-specific questions.
• Use clear prompts and include document name for precise retrieval.
• If retrieval does not trigger on first try, use phrases like “this file”, “uploaded document”, or “recent pdf” in your prompt.

Fallback tip: if document tools are not triggered automatically, rephrase with explicit file context and retry in the same chat.

Backup and restore

Backups include agents, tools, and setup preferences. API keys are redacted by design and must be re-entered after restore.