Using Kucatoo-Code

1. Choosing a model

The left column lists every configured model (Kimi, GLM, DeepSeek, Qwen, MiniMax). Click one to select it — it gets a green glow. The temperature slider in the header snaps to that model's default.

• no key badge — the API key for that model isn't set in .env; the model is skipped until you add one.
• The default badge marks the model used when none is selected.

2. The Prompt & Response panels

Type your request in the Prompt box (middle column). Press Ctrl+Enter (or Cmd+Enter on Mac) — or click Run — to send it. The answer streams into the Response box on the right as it's generated.

• Run turns into Stop while streaming; click it again to cancel.
• The ⎘ (copy) and 💾 (save) icons copy or save the prompt/response to disk.
• The footer shows token usage and elapsed time after each run.

Run controls: Stop, Pause/Resume, New session

• Stop — while a query streams, Run turns into Stop; click it to cancel the run.
• Pause — freezes the stream display mid-run; the button becomes Resume and the footer shows paused. Click Resume to continue exactly where you left off. (Pause holds back the stream client-side; a few already-buffered tokens may appear instantly on resume.)
• ✚ New session — clears the response, thinking block and agent trace, and starts a fresh conversation context (previous exchanges no longer influence the model). Any running query is cancelled.

3. Direct vs Agent mode

The Direct / Agent toggle in the header controls how your prompt is processed:

Direct mode (default)

Your prompt is sent straight to the selected model and the answer streams back token-by-token. Fast, single-shot, like a normal chat. Best for most questions, writing, and code.

Agent mode

The prompt is handed to an agent that runs a reasoning loop — it can think, call tools, observe results, and take several steps before giving a final answer. Use this for multi-step tasks like "read this file and summarize it" or "find the bug and fix it".

• In Agent mode, an agent type dropdown appears: react (act-observe loop), planner (breaks the goal into a plan first), or reflective (self-corrects on failure).
• The mode buttons in the header pick what the agent may do: Explore (read-only investigation), Plan (read-only, asks you clarifying questions, then produces a structured plan), Write & Test (full access, runs code/tests to verify its work), or Write (no test) (full write access, but never runs tests, validators, or builds unless you ask). Write modes ask for approval on each write unless you tick auto-approve.
• An Agent trace panel appears under the Response box, showing each thought, tool call, and observation live as it runs.
• The final answer still lands in the Response box.

4. The Agent trace

In Agent mode, a Trace button appears in the Prompt column header. Click it to swap the prompt editor for the Agent trace: the agent's reasoning loop live, one row per event, auto-scrolling as it runs (the button becomes Prompt — click again to switch back). Each row has a coloured label on the left:

• thought (grey) — the agent's reasoning about what to do next.
• tool (orange) — a tool call, with its arguments as JSON, e.g. write_file {"filepath": "recipes/pie.md", ...}.
• obs (accent) — the observation: the result the tool returned, which the agent reads before its next thought.
• step — a step boundary/status marker in the reasoning loop.
• failed (red) — a step that failed; the agent typically self-corrects on the next step (especially with the reflective strategy).

Header controls

• Agent type dropdown — the reasoning strategy: reflective (self-corrects on failure), react (thought → act → observe loop), or planner (writes a plan first, then executes it).
• steps input — maximum reasoning steps (3–60, default 30) before the agent stops, as a guard against runaway loops.
• Auto-approve writes/tests checkbox — when ticked, tools that modify disk or run code (write_file, execute_python) run immediately without asking. When unticked, each such call pauses the run and shows an Approve / Deny card above the trace — the run waits until you answer.
• × button — clears the trace. The trace is also cleared automatically when you start a new run.
• 💾 button — saves the trace to disk (the traces directory) on its own, without saving the response.
• 🔍 button — analyzes the trace with AI (see below).

Analyzing the trace with AI

The 🔍 (analyze) icon in the trace header saves the current trace and opens the Trace Analysis panel at the side of the window. The trace is summarized, sent to an LLM, and the panel shows a read-out of the run: what the agent did, where it struggled, and how it reached its answer.

• Model dropdown — which LLM performs the analysis. Your choice is remembered for the session; the default comes from the saved analysis-model preference.
• Ask about this trace… — the input at the bottom of the panel asks follow-up questions (why did the agent call delete_file?); the conversation keeps the trace as context.
• Copy / Save icons — export the analysis transcript as Markdown, to the clipboard or as a downloaded trace_analysis_*.md file.
• × — closes the panel. The conversation is kept for the session and restored when you reopen the analysis.

Analyzing prompts & responses

The same panel analyzes more than traces. The 🔍 icon in the Response column header analyzes the current prompt + response pair — does the answer actually address the prompt, where it falls short, and how to improve it. When the run has an agent trace, an Include trace checkbox appears in the panel (on by default) so all three — prompt, response, and trace — are analyzed together for deeper process insight; untick it and the analysis re-runs on the pair alone.

The History tab has an Analyze series button: it reviews the sequence of prompt/response pairs recorded under the active workspace — recurring themes, repeated failure modes, and how the work is evolving. Only runs made under workspace tagging count, so the series builds up as you use the app.

Quantified improvement: every analysis ends with a machine-readable SCORES: line (1–10 ratings) and is appended with objective metrics (steps, tool calls, failures, tokens, run counts) to analysis_log.jsonl in the data directory. GET /api/analysis/log returns the records plus mean-score aggregates, so you — or an LLM — can diff two periods and measure whether things are actually getting better.

Saving the trace

The 💾 (save) icon in the Response header saves the response text to the responses directory and, if a trace is present, writes a companion file with the same name plus a .trace.txt suffix, so the two files sort together and you can see exactly how the answer was produced.

Tip: the final answer always lands in the Response box — the trace is the "working out", not the result.

5. Tools & "Run tool"

Tools are actions the agent (or you) can invoke: read_file, write_file, list_files, web_search, and execute_python. They live in the Tools tab of the right-hand console.

Enabling tools for an agent run

Tick the checkboxes next to the tools you want available. When you next run in Agent mode, only the checked tools can be used. (Direct mode ignores tools — it's a plain completion.)

"Run tool" — calling a tool directly

You don't need an agent to use a tool. At the bottom of the Tools tab:

1. Type a tool name (e.g. read_file). Both fields are multi-line — drag their lower edge to make them taller.
2. Enter its arguments as JSON, e.g. {"filepath": "README.md"}.
3. Click Run tool.

The result appears in the output box below. This is handy for quick file reads or testing a tool before wiring it into an agent.

Examples

• read_file — {"filepath": "notes/todo.md"} returns the file's contents (add "max_lines": 50 to cap it).
• write_file — {"filepath": "recipes/pie.md", "content": "# Pie\n…"} writes the file (asks for confirmation first).
• list_files — {"pattern": "*.md"} lists matching files in the workspace (add "directory": "recipes", "recursive": true to search a subfolder tree).
• web_search — {"query": "kucatoo pie", "top_k": 3} searches the web (needs TAVILY_API_KEY).
• execute_python — {"code": "print(sum(range(10)))"} runs sandboxed Python (no file/network access; asks for confirmation).

Where files live: the file tools are sandboxed to the agent workspace — the WORKSPACE_DIR setting in .env (default: a workspace folder next to the data directory). Paths outside it are refused.

Note: write_file and execute_python are marked confirm — they modify disk or run code, so they require confirmation.

6. Memory

The harness remembers things across runs in a tiered store (short / medium / long term). The Memory tab lets you search and add to it.

• Recall — type a query and hit Recall (or Enter). It returns the most relevant stored memories by semantic similarity. Example: pie recipes finds "the user likes fruit pies" even though the words differ.
• Remember — type a fact (e.g. "the user prefers concise answers" or "workspace files go to D:/kucatoo-code/workspace") and click Remember to store it for future runs.

In Agent mode, the agent automatically pulls relevant memories into its context, so things you've remembered influence its answers. Example: after remembering "the user is allergic to nuts", a later agent run asked for a cake recipe will avoid nuts without being told.

Remembering from chat (memory proposals)

In Direct mode you can store a fact straight from the chat: start your prompt with a trigger phrase like remember that…, remember this…, note that…, don't forget…, memorize…, add … to memory, or keep in mind…. The app detects the intent before calling the model (no tokens are spent), extracts the fact, and shows a confirmation card in the chat with Remember and Dismiss buttons. Example: typing remember that my editor is Neovim proposes the fact "my editor is Neovim".

• Remember stores the fact via the same endpoint the Memory tab uses — it behaves exactly as if you had typed it there.
• Dismiss stores nothing; the card collapses to "Not stored — kept in conversation context." The prompt still lives in your session history, so the model can use it for the rest of the conversation — it just won't survive into future sessions.
• Each proposal gets its own card, so several remember-prompts in one session can be confirmed or dismissed independently.

Detection is deliberately conservative: the trigger phrase must lead the prompt and yield a usable fact. Questions such as "do you remember my name?" are not intercepted — they go to the model as normal chat. Likewise, indirect phrasings ("hey, could you maybe remember…") intentionally fall through to normal chat rather than risk false positives. To switch proposals off entirely, set direct_chat_memory_proposals: false in the harness YAML config and restart the server.

Try it: type remember that my editor is Neovim and click Remember, then recall which text editor does the user like in the Memory tab — semantic search finds it even though the wording differs.

7. Voice: dictation, editing & spoken responses (STT/TTS)

You can talk to the app instead of typing, and have it read answers back to you. Two buttons control this: the mic button (🎙) in the Prompt panel header for dictation (speech to text), and the Speak toggle (🔊) in the Response panel header for spoken responses (text to speech).

Dictation uses the browser's Web Speech API, which is available in Chrome and Edge — on other browsers (e.g. Firefox) the mic button stays hidden. The first time you click the mic, the browser asks for microphone permission; allow it once and it sticks. Spoken responses use the browser's built-in speech synthesis, which works in most browsers; if it's unavailable, the Speak button stays hidden.

A typical dictation workflow

1. Click the mic button — a red pulsing dot shows you're recording, and the dictation panel opens below the prompt box.
2. Dictate naturally. Each time you pause, that spoken chunk is cleaned up (filler words, false starts and speech-to-text glitches removed) and appended to the draft.
3. Watch the two panes: Raw transcript (everything verbatim) on the left, Interpreted draft (the cleaned version) on the right.
4. Fix anything by hand-editing the draft, or with a voice command (see below) — e.g. "computer, make that more formal".
5. Click Apply prompt — the draft is copied into the prompt box. Clear empties both panes and closes the panel.
6. Review the prompt and hit Run when ready. Nothing is ever sent automatically — your voice only ever fills the prompt box; you always press Run yourself.

How the cleanup works (STT details)

Cleanup is pause-triggered, not continuous: each time an utterance finalizes (you pause), that chunk is sent to a small cleanup model which fixes speech-to-text artifacts, disfluencies and false starts, and resolves explicit self-corrections ("born in Hanoi — no wait, Saigon" keeps Saigon). The cleaned text is appended to the interpreted draft, so your manual edits are never overwritten by new utterances — only edit commands replace the draft. The raw pane always preserves the verbatim transcript.

If the cleanup model is unreachable, dictation silently falls back to raw transcripts only — nothing breaks. Controlled by stt_assist_enabled (default true) and stt_assist_model (default deepseek-v4-flash) in the harness YAML config; restart the server after changing them.

Voice editing

• Wake word — start an utterance with computer and it becomes an edit instruction applied to the draft instead of dictation content.
• Push-to-talk command mode — hold the Space bar (while not typing in a text box) and everything you say until you release it is an edit instruction. The panel border highlights while command mode is active.

Example instructions:

• delete the last sentence
• make it more formal
• change Saigon to Hanoi
• start over (clears the draft)
• apply prompt (or send it) — moves the draft into the prompt box, same as the Apply prompt button; still never auto-sends
• clear draft / clear raw / clear prompt / clear all — empties the interpreted draft, the raw transcript, the prompt box, or everything (panel stays open)

You can always hand-edit either pane instead — draft edits are kept and new dictated chunks are appended after them.

Spoken responses (TTS)

Toggle Speak (🔊) in the Response panel header and each finished direct-mode answer is read aloud. Toggling it off — or starting a new query — stops playback immediately. Code blocks are summarized as "code block" rather than read character by character. Voice and quality depend on the speech voices installed in your OS/browser.

Tips

• Dictate punctuation explicitly (comma, period, new line) — the cleanup handles the rest.
• Speak in complete chunks rather than single words — fewer, better cleanups.
• Use command mode (or the wake word) for edits so instructions don't land in the draft as content.
• Troubleshooting: Chrome dictation routes audio through Google's speech service, so VPNs/firewalls can block it (symptom: recording dot pulses but nothing is transcribed) — check chrome://speech-internals for error codes such as network or not-allowed.

8. Skills

Skills are higher-level, pre-built capabilities that combine a model with a prompt and (optionally) tools — e.g. code_review, summarizer, translator, debugger. The Skills tab lists them.

To run one — example with summarizer:

1. Enter the skill id: summarizer.
2. Provide its parameters as JSON, e.g. {"text": "The long article text goes here…"} (each skill lists its required params under its name).
3. Click Run skill.

The skill's output appears below — for summarizer, a condensed version of the text you passed. Other examples: translator with {"text": "Hello", "target_language": "French"}, or code_review with {"filepath": "run_webapp.py"}. Skills are a shortcut for common, well-structured tasks.

9. Status

The Status tab shows a live snapshot of the whole harness — click Refresh to update it. You'll see:

• capabilities — which subsystems are wired (provider mesh, tools, agents, memory, workflows, skills, domains, profiles).
• health — per-model circuit-breaker state (healthy / degraded / down). Example: if Kimi returns errors, its entry flips to degraded and routing avoids it until it recovers.
• cost — cumulative token spend, by model and total. Example: {"total_tokens": 15420, "cost_usd": 0.0123}.

Useful if a model is failing — check here whether it's marked down. Example workflow: a query fails with 402 Insufficient Balance → open Status → the model shows down → top up that provider or pick another model.

10. Workspaces

Workspaces are project folders. The workspace root is set by WORKSPACE_DIR in the app's .env file — the root itself and every subdirectory of it is a selectable workspace, so you can keep one folder per project and switch between them.

The workspace bar (second header row) has a dropdown of all workspaces, a New button to create a project folder, and a Stats button. Switching workspaces changes the root that all file tools, the Files tab, and context files operate on; the choice is remembered across restarts.

Per-workspace stats

Every query is recorded against the active workspace. Click Stats to see, for the current workspace: total queries, tokens (prompt / completion / cached), cost in USD, cumulative elapsed time, and a per-provider/model breakdown with first and last activity. Stats persist on disk, so they survive restarts.

11. Context files

You can attach files from the active workspace to any query — their contents are injected into the prompt as a === Context files === block, in both Direct and Agent mode. There are two ways to attach:

• Drag & drop — drop files from your OS anywhere on the prompt panel (it highlights). Dropped files are uploaded into the active workspace first, then attached.
• Attach file button (📄, next to the image button) — opens a picker that browses the active workspace; tick multiple files and choose Attach selected.

Attached files appear as removable chips under the image thumbnails and are cleared after each run. Limits: up to 20 files, 20 KB per file, 200 KB total; binary files are skipped. You can also attach files straight from the Files tab via Add to context.

12. The Files tab

The Files tab is a file explorer for the active workspace. While it is open, the console column widens to four times the width of the Prompt/Response columns (which shrink accordingly) to give you room to work; switching to another tab restores the normal layout.

• Browse — click a directory to enter it, use the breadcrumbs or Up to go back. .git, venv, __pycache__, node_modules and backup folders are hidden.
• View & edit — click a text file to open it in the editor, edit, then Save (the previous version is backed up automatically). Image files (PNG, JPG, …) open in an image viewer.
• Select — tick individual files or use the all checkbox to select everything in the current directory, then use the toolbar:

• Zip — download the selected files/folders as a zip (auto-generated and venv content excluded).
• Backup — copy the selection into a timestamped backup under .kucatoo_backups/ in the workspace.
• Restore — pick a file, choose one of its backups, and revert to it (the current content is backed up first).
• Delete, New folder — with a confirmation prompt.
• +.gitignore / −.gitignore — add or remove the selected paths in the workspace's .gitignore (created if missing).
• Add to context — attach the selected files to your next query (see Context files).

13. The Sites tab

The Sites tab is the control panel for the whole Kucatoo site family. It reads the registry (Kucatoo-Sites' projects.json) and merges in live status, so one row per site shows everything at a glance:

• Status dot — green: something answers HTTP on the site's registered port. Grey: offline. The check is done live each time the list loads, so Refresh re-probes every port.
• Group — the harness folder the site lives under (Qwen-Code, Kucatoo-Code, Legacy, Archive), per the file-structure layout.
• Stage badges — dev is always present; beta/prod light up once those worktrees exist. When prod exists, the row also shows the tag it sits on (e.g. prod@v1.0.0).

Slow actions (starting a big site, running the backup mirrors) show the rainbow spinner with a timer in the corner of the panel.

Start / Stop / Log

• Start runs the site's registered start script (start.bat / run.bat) detached, with output appended to data\site_logs\<site>.log. If the port already answers, Start refuses — that's your signal it's already up.
• Stop finds the process that owns the site's port and kills its whole process tree (after a confirmation). Use it instead of hunting PIDs.
• Log shows the tail of the launch log — the first place to look when a site won't come up.
• Kucatoo-Code itself is protected: its row has no Start/Stop buttons. Manage it with the server controls in the header, so the console can't saw off the branch it's sitting on.

Staging: what beta and prod are

Each site is a git repo checked out at Sites\<Group>\<Site>\dev. The +beta and +prod buttons create the other stages as git worktrees — additional working directories that share the same repository history. A worktree is not a copy: there is one .git, and each stage directory simply has a different commit checked out. This makes staging cheap and exact: prod\ can sit on a release tag while dev\ moves ahead.

• +beta creates beta\ on a stage-beta branch at dev's current HEAD — a release-candidate sandbox you can run and test in parallel.
• +prod creates prod\ the same way. You normally don't need to click it by hand — Promote creates the prod worktree automatically on first use.

Promote, in detail

Promote is the release button: it takes whatever is committed on dev right now and makes it the production version. Clicking it asks for a tag name, then does exactly this:

1. Validates the tag name and refuses if the tag already exists (so you can't silently overwrite a release).
2. Tags dev HEAD — an annotated git tag (e.g. v1.0.0) is created on the latest commit of the site's dev checkout. Only committed work is tagged — uncommitted edits in dev are not included, so commit first.
3. Points prod at the tag — if there is no prod\ worktree yet, it is created as a checkout of the tag; if one exists, it is switched (git checkout) to the new tag. Either way, prod\ afterwards contains exactly the tagged code.

The row then shows prod@v1.0.0 (or whatever the tag is), which is read live from the prod worktree on every Refresh.

• Typical flow: work in dev\ → commit → optionally test in beta\ → Promote v1.1.0 → run the site from prod\.
• Rollback: point prod at an older tag with git — git -C prod checkout v1.0.0 (Promote deliberately refuses existing tags, so rollback is a git command, or you promote a fix forward as a new tag). Promote never deletes or rewrites tags.
• Failure modes are explicit: a duplicate tag name is rejected up front; if the prod checkout fails after tagging, the error says so and the tag remains (safe to retry after fixing the checkout problem, e.g. uncommitted edits inside prod\).
• Never edit inside prod\ — it is a checkout of a tag; changes there are detached from any branch and will block the next promote.

Run backup

Mirrors F:\Kucatoo\Sites, F:\Kucatoo\Data, and F:\customers to D:\Backups\Kucatoo\ with robocopy (venvs, node_modules, model weights excluded — they're reproducible). The summary of each job appears in the panel output, and the full log is appended to data\site_logs\backup.log. The spinner runs for the duration — the first full mirror can take minutes, later ones only copy changes.

Rule of thumb: edit only in dev\; prod\ should always sit on a tag.

14. Tips & shortcuts

• Ctrl/Cmd + Enter in the prompt box = Run.
• The temperature slider is sent with each query; higher = more creative, lower = more deterministic. (Kimi models require temperature 1.)
• The theme toggle (☼) switches dark/light high-contrast and is remembered across reloads.
• The A− / A+ controls adjust font size.
• If a model errors with 402 Insufficient Balance or no key, it's an account/config issue — see the Status tab and your .env.
• The History tab (console column) records every completed run automatically — prompt, response, model, elapsed time. Click an entry to reload it into the Prompt/Response boxes.
• Help opens in a new browser tab, so you can keep it next to the app.

15. Memory landscape & the coder-memory docs

There are three distinct memory systems around Kucatoo-Code. They are easy to conflate, so here is the full map: what each one is, whether it has a GUI, where it lives, how to access it, and how to populate it.

In-app harness memory — short / medium / long term

The harness remembers across runs in three tiers modeled on human cognition (this is what the Memory tab talks to):

• STM — Short-Term: in-memory ring buffer; current-session context; lost on restart (RAM only).
• MTM — Medium-Term: SQLite + embeddings; survives restarts (data/memory/mtm.db).
• LTM — Long-Term: vector store with automatic summarization of long content (data/memory/ltm/).

Plus AUTO routing: the memory manager decides which tiers an item lands in based on importance, and can consolidate/promote items between tiers over time.

• Access (GUI): Memory tab → Recall box — semantic search across all tiers.
• Populate (GUI): Memory tab → Remember box; or in Direct chat, start a prompt with a trigger phrase (remember that… etc.) and confirm the proposal card (see Memory).
• Populate (automatic): in Agent mode, relevant memories are pulled into context automatically; high-importance outcomes are promoted to higher tiers.

Coder-memory doc pair (owner + assistant versions)

A versioned pair of living documents recording how the owner uses Kucatoo-Code and how an AI assistant should help — with a verification quiz that catches stale instructions:

• D:\kucatoo-code\kucatoo-coder-memory.md — assistant version: structured how-to entries, UI map, troubleshooting, owner preferences; each entry carries confidence/source metadata.
• D:\kucatoo-code\kucatoo-coder-memory-owner.md — owner version: the answer key and verification quiz; ground truth when the two disagree.

• GUI: none — markdown files, not an app feature; the running app does not read them.
• Access: open in any text editor, or hand them to an AI session.
• Populate: the owner edits the owner file freely (it wins conflicts); the assistant file changes only via propose → owner-approve → version-bump, logged in its §10.

Qwen assistant memory (MEMORY.md & friends)

• MEMORY.md is only an index — one line per memory (- [Title](file.md) — hook); the content lives in the linked files under typed folders (user/, feedback/, project/, reference/).
• GUI: none — plain markdown files.
• Access: open the files directly, or ask the assistant to recall/check its memory.
• Populate: ask the assistant to remember something and it saves the file + index line; or edit by hand.

Working with the indexes day-to-day

• Read: open a MEMORY.md — each line is a pointer; the real content lives in the linked file. Both indexes are auto-loaded into every assistant session.
• Add: tell the assistant remember that… — it writes the memory file and the index line. Manual alternative: create the file under its type folder and add one pointer line.
• Change: edit the linked file; keep the index line accurate and under ~150 characters.
• Remove: say forget X (assistant removes file + line) or delete both yourself. Each directory keeps its own index — no cross-linking.
• Everyday shortcut: talk to the assistant (remember…, forget…, what do you know about X?) and open the files only when auditing.

Example: a realistic memory conversation

A worked example showing the habits that make the memory system work well:

You: Remember that Kucatoo-Code's deploy source is F:\Kucatoo\Sites\Kucatoo-Code\Kucatoo-Code\dev — the D: drive copy is stale and I keep losing time when tools look there first.

Assistant: Saved as workspace feedback memory → feedback/kucatoo-code-source-location.md, with the reason included, and added the index line. Future sessions will check F: first.

— skill: give the fact AND the why. A memory with a reason survives edge cases; a bare fact gets misapplied. —

You: Also remember that we're fixing the Sites tab bug this afternoon.

Assistant: That's current-task state, not durable memory — it belongs in the session's todo list, not the memory files. I've tracked it there instead.

— skill: memory is for things future sessions need. In-progress work lives in todos/plans, or it becomes stale noise. —

You: Show me what you actually saved.

Assistant: (reads the file back — rule, reason, how-to-apply)

— skill: audit anytime. Every memory is a plain file you can open and read. —

You: That's slightly wrong — the path gained a new folder level last week.

Assistant: Updated the existing memory in place and fixed the index line. No duplicate created.

— skill: correct freely. Memories update in place; corrections are as valuable as the original save. —

You (a different session, days later): Where should I look for the Kucatoo-Code source?

Assistant: F:\Kucatoo\Sites\Kucatoo-Code\Kucatoo-Code\dev — per a saved memory; the D: copy is stale. (verifies the path still exists before recommending it)

— skill: this is the payoff. Memories surface automatically when relevant, and the assistant verifies before acting on them. —

You: We don't use that F: path anymore — forget it.

Assistant: Removed the memory file and its index line.

— skill: prune. A deleted fact is better than a stale one; "forget X" removes both the file and the pointer. —

The habits in one list: save facts with their why · keep in-progress work out of memory · audit by reading the files · correct in place instead of stacking new entries · let memories surface, but expect verification · forget what's no longer true.

The rules they run on

• Real, current features only — future ideas are parked, never written as real.
• No secrets, ever.
• "I don't know" is a valid answer — it starts an exploration, logged with its dead ends, instead of a guessed entry.
• Corrections are confirmed visually before saving (voice may dictate, never silently write).

16. Google Drive backup

The Drive button in the Files tab toolbar zips the selected files and folders and uploads the archive to your Google Drive. The file lands in a folder named Kucatoo-Code Backups (created on first use) with a timestamped name like kucatoo-backup-20260101-120000.zip.

Connecting. The first Drive backup redirects you to Google to grant access (scope drive.file — the app only sees files it created). After consent you return to the console and a "Google Drive connected" toast confirms it; retry the Drive button to run the backup. The OAuth token lives at data/drive_token.json and refreshes itself. This requires GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET in your .env — the same credentials as Google sign-in.

The same path safety rules as the local Backup apply: only entries inside the active workspace can be selected, and generated folders (venv, .git, node_modules, …) are skipped.

17. Billing (Stripe)

Kucatoo-Code has an operator billing spine built on Stripe: a checkout flow, a webhook endpoint that records payment events, and a clients table that tracks who has paid. It is configured with the environment keys STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET and STRIPE_PRICE_ID; with none of them set the billing routes stay inert and the console runs exactly as before.

18. Settings — your own provider keys (BYOK)

The Settings page (also linked from the header) lets signed-in users store their own provider API keys — Kimi, DeepSeek, GLM, Qwen, MiniMax and OpenRouter — and run those models on their own quota instead of the server's shared keys. Stored keys take effect immediately for your requests and make the corresponding models available in the model list (trial accounts can use non-trial models whose provider key they have added).

• Each provider also accepts an optional custom base URL — leave it blank for the default international endpoint; Chinese-mainland endpoints can be entered here as they become available.
• OpenRouter key storage is ready for upcoming OpenRouter model routing — no OpenRouter models are registered yet.
• Only a masked hint (last 4 characters) of a stored key is ever shown; full keys never leave the server.

19. Hosting tiers

Hosted Kucatoo-Code sites run on their own micro-VM (fly.io), one per client — your workspace, history and memory are fully isolated. Each site is deployed on one of these tiers, with a choice of disk size (1 / 2 / 3 / 5 GB — disk can grow later but not shrink). Prices are in US dollars; quarterly and annual billing save 15%.

Credits are how we meter shared-model usage: 1 credit = $0.01 of included model usage. A Flash request and a Pro request simply use different numbers of credits. Your price and credit balance are fixed month to month — if our provider reprices, the credit value never changes.

What tier do I need?

• Micro is the cheapest option, sized for plain BYOK chat. It is intentionally tight — heavy use belongs on Basic.
• Basic is enough for almost everyone: chat, agent runs and tools, with DeepSeek V4 Flash included on the shared key (600 credits / month) and every other model running on the keys you add in Settings. The slim build leaves out the heavy local-embedding libraries, which is what lets it run comfortably in 512 MB.
• Plus adds the full build — local sentence embeddings for semantic memory recall — plus DeepSeek V4 Pro on the shared key (1,000 credits / month) and more memory and disk to carry them.
• Pro is planned for heavier multi-agent and team workloads and becomes available later.
• Bring your own keys: every tier accepts your own provider keys (DeepSeek, Kimi, GLM, Qwen, MiniMax) — your requests then run on your own quota, with no shared-allowance limits. Heavy users should bring a provider plan: it is cheaper than any top-up and your provider bill does not change.

You can move between tiers at any time: memory/disk changes are applied to the running VM, and your data always stays on your site's own volume. Disk can be grown but not shrunk — a downgrade adjusts memory/CPU only. Which tiers are offered can change: your operator may enable or disable a tier at any time, without affecting sites already running on it.

20. Model profiles & the optimization loop

Kucatoo-Code can improve how each model behaves over time using model profiles — small per-model JSON overlays (config/model_profiles/<model>.json) that adjust prompts and agent budgets, never code. A background job (profile-optimize, on the Jobs page) diagnoses recent failures, proposes a profile change, and — after your review — the change is adopted. The loop is always human-gated: nothing is applied without your click. On the Jobs page, the profile-optimize row lets you pick the optimizer model (which writes proposals) and the subject model (whose profile is optimized), and to enable auto-evaluation of each proposal with a budget cap; its Enabled checkbox arms weekly automatic runs — the manual run button works regardless.

Reading the Jobs page

• Recent executions lists every run (persisted across restarts). Click a row to filter Profile proposals to that run's artifacts; click again to clear. Wide screens show a sticky viewer column on the right for artifact contents.
• Verdict ball (hover the Artifacts header for the legend): ● adopt — gates pass, Adopt button shown inline with its held-out budget cap; ● reject — the eval regressed, do not adopt; ● pending — not yet evaluated; ● adopted — already live. The verdict uses the same gate math as the adoption endpoint, so it never disagrees with the gate.
• Loop status (top of Profile proposals): one line per profiled model with its current version and when to run the next iteration.
• Run costs: per-run tokens and cost for every job (optimizer and subject spend recorded separately), with rolling subtotals (24h/7d/30d/365d/all), a period filter, and a pager.

Do profile runs actually improve the app?

Yes — reliability, not speed. Profiles teach the harness to prevent the failure modes your own traces diagnosed (claiming completion without evidence, wandering reconnaissance, skipping parts of a task). Example from the first iteration on deepseek-v4-flash: pass rate on the 39-task evaluation suite went from 53.8% to 61.5% at 7% lower cost per success. Each profile takes effect immediately for every run of that model — chat, agents, jobs, everything.

How do my everyday prompts help?

Every query you run produces a trace; when you run a trace or response analysis, its scores are logged per model. The diagnosis step aggregates exactly those scores — so your normal usage, once analyzed, becomes the evidence the next profile proposal is built on. Note: traces alone don't feed the loop; analyzed traces do.

Can I switch between models?

Freely. Profiles, diagnosis and cost estimates are all tracked per model — using glm-5.2 or k3 today touches nothing about Flash's profile or evidence. The only rule: evaluation comparisons are per-model (a suite run on glm is the start of glm's own baseline, not comparable to Flash's).

Who grades the evaluations? (the judge)

Rubric scoring is done by a judge model you choose via the EVAL_JUDGE_MODEL environment variable; unset, it defaults to the cheapest configured model. Profiles never influence the judge — that separation keeps the loop from grading its own homework. Tip: point the judge at a different model than the subject for an independent signal.

The evaluation suite

The suite (flash_opt_suite.json) has 56 tasks in four categories — tool sequences, document coverage, recon discipline, planning — split 39 visible / 17 held-out. The held-out slice is the adoption gate: proposals are tuned only against visible tasks, so a held-out pass proves the gain is real and not overfitting to the exam. The suite grows over time: whatever weaknesses remain after profile tuning become the next specialized task categories.

Adopting a proposal

On the Jobs page, open a run's patch artifact and click Adopt profile. Adoption is gated: it needs a completed evaluation, rejects any visible-split regression, and runs the held-out split as a final check (budget-capped — the first adoption records the held-out baseline). The merge is written to the profile file and logged to an audit trail; the git commit is yours to make.

Looking ahead: fine-tuning

The data you're accumulating today — traces with scores, eval run records, adoption decisions — is the raw material for future post-training (SFT/DPO) of specialized models. Profiles improve the harness around a model; fine-tuning would improve the model itself, and the two compound.