Skip to content

Architecture Miso

Jump to bottom
Haoxiang Xu edited this page Mar 12, 2026 · 2 revisions

Architecture - Miso

Home | Architecture | Architecture - Mini UI | Architecture - PuPu

Miso is the local Python sidecar process that PuPu launches from Electron main. It is not a remote backend. PuPu uses it for chat streaming, toolkits, model catalog data, memory, and workspace-aware execution.

Startup Model

The Electron main process owns sidecar lifecycle in electron/main/services/miso/service.js.

Development resolution:

  1. MISO_SOURCE_PATH, if set and valid
  2. sibling checkout at ../miso

Packaged resolution:

  • Prefer a bundled miso-server binary under miso_runtime/dist/<platform>/
  • Fall back to running miso_runtime/server/main.py with a valid Python runtime if the binary is absent

Python rules:

  • PuPu expects Python 3.12.x
  • MISO_PYTHON_BIN overrides the runtime interpreter when provided
  • If MISO_PYTHON_BIN is unset, PuPu inspects PuPu/.venv first and then miso/.venv

Sidecar Runtime Behavior

Important startup facts:

  • Host: 127.0.0.1
  • Port search range: 5879 through 5895
  • Boot timeout: 10000ms
  • Health retry interval: 250ms
  • Restart delay after unexpected failure: 1500ms
  • Auth: a random MISO_AUTH_TOKEN is generated per app launch and sent as x-miso-auth

Additional runtime env injected by Electron:

  • MISO_VERSION
  • MISO_PROVIDER
  • MISO_MODEL
  • MISO_DATA_DIR
  • MISO_PARENT_PID
  • MISO_SOURCE_PATH in development when a valid checkout is found

The sidecar watches the Electron parent PID and exits if the parent disappears, which prevents stale processes from holding runtime locks after crashes.

Main HTTP Endpoints

The sidecar is a Flask app registered from miso_runtime/server/app.py and miso_runtime/server/routes.py.

Core endpoints:

  • GET /health
  • GET /models/catalog
  • GET /toolkits/catalog
  • POST /chat/stream/v2
  • POST /chat/tool/confirmation
  • GET /memory/projection
  • GET /memory/long-term/projection

These routes are app-internal integration points. They are not documented as stable public APIs for third-party clients.

Memory Subsystem

The memory implementation lives mainly in miso_runtime/server/memory_factory.py.

Storage under MISO_DATA_DIR:

  • memory/qdrant
  • memory/sessions
  • long-term profile data under memory/long_term_profiles

Embedding provider resolution order:

  1. explicit memory_embedding_provider
  2. current chat model provider, if that provider supports embeddings
  3. OpenAI fallback when an API key is available
  4. Ollama fallback when reachable
  5. no memory for that request

Important rules:

  • Tool traffic is not dialog history and should not count as turns
  • The memory sanitization layer strips tool-only noise before prepare and commit
  • Empty or malformed session payloads are cleaned before they become long-lived memory state

Workspace And Toolkit Injection

Workspace information arrives from the renderer through payload options prepared in src/SERVICEs/api.miso.js.

Contract rules:

  • The renderer resolves selectedWorkspaceIds into real paths before sending the request
  • The sidecar receives workspaceRoot, workspace_root, and workspace_roots
  • The sidecar does not treat workspace IDs as a backend contract

Toolkit behavior:

  • multiple roots can map to a multi-workspace toolkit
  • a single root can map to the workspace toolkit variant
  • invalid workspace paths raise runtime errors instead of being silently accepted

When To Touch Miso

Work in the Miso layer when you need to change:

  • streaming frames or event semantics
  • model catalog data
  • toolkit catalog data
  • tool confirmation flow
  • memory behavior
  • provider runtime defaults
  • workspace attachment rules

Do not touch Miso to solve pure renderer presentation problems.

Clone this wiki locally