adolf/docs/ARCHITECTURE.md

# Adolf — Solution Architecture

**Status:** Proposed · **Date:** 2026-07-05 · **Owner:** alvis

Adolf is a self-hosted personal AI assistant on Agap, reachable first over Matrix
(`@bot:mtx.alogins.net`). It is built on **OpenClaw** (the multi-channel assistant shell), driven by
the **Kimi Code CLI** on the existing flat `kimi login` subscription (no per-token cost), with
**Cognee** as long-term memory.

---

## 1. Goals & decisions

- **Base = OpenClaw** (`github.com/openclaw/openclaw`, Node.js). Provides the multi-channel inbox,
  session/agent routing, SOUL.md persona, tool/MCP registry, and later WebChat + voice.
- **Brain = Kimi Code CLI subscription, hybrid.** The CLI owns the agent loop, but OpenClaw's
  tools/MCP are **not bypassed** — they are exposed to the CLI as a **shared MCP layer**.
- **Memory = Cognee, "auto + tool".** Auto-ingest every exchange and inject retrieved memory each
  turn, *and* expose explicit `memory_search`/`memory_add` MCP tools.
- **Cognee's backend LLM also runs on the Kimi subscription — via its own separate wrapper**
  (`cognee-llm`), because its usage (stateless, structured, batch, no media/streaming) is unlike
  OpenClaw's. Embeddings stay on LiteLLM (`embedder` = nomic-embed).
- **The existing `kimi-agent` service is left untouched** (still used for OpenWebUI experiments); we
  build **new, separate wrappers**.
- **First surface = Matrix chat** only (voice/pipecat, WebChat, OpenWebUI deferred).

### Why the hybrid works (de-risked)
OpenClaw runs its own agent loop and expects a *raw LLM* backend (provider `api: openai-completions`
or `anthropic-messages`, configured with `baseUrl`/`apiKey`). The Kimi CLI is *itself* an agent, so
naively wrapping it would bypass OpenClaw's tools. Confirmed escape hatch: **Kimi Code CLI supports
MCP** (`~/.kimi/mcp.json`, headless `--mcp-config-file <file>`, `kimi mcp add/list/remove/auth`) plus
**image/video input**, session **resume** (`-r`), headless `-p`, and `--output-format stream-json`.
We point the CLI at the same MCP servers OpenClaw uses → the CLI can call OpenClaw/cognee tools while
OpenClaw stays the channel/session/persona/memory layer.

---

## 2. Topology & data flow

```
Matrix ⇄ OpenClaw (Gateway: inbox, session routing, SOUL.md "Adolf")
             │  OpenAI /v1/chat/completions (streaming, images)   model = "adolf"
             ▼
      adolf-llm  (NEW wrapper container, :8010)
        • maps OpenClaw session → Kimi session (1:1 resume)
        • cognee.search() → inject memories into prompt   (auto-retrieve)
        • spawn: kimi -r <sess> -p <prompt> --output-format stream-json
                      --mcp-config-file <shared-mcp.json>
        • stream stream-json → SSE deltas (real streaming)
        • persist inbound images to session dir, reference by path (media)
        • after turn: cognee.add(user+assistant)             (auto-ingest)
             │                         ▲ MCP
             ▼                         │
        kimi CLI (agent) ── MCP ──► shared MCP servers:
                                     • cognee-mcp  (memory_search / add / cognify)
                                     • openclaw-tools bridge (OpenClaw integrations)

  cognee ──► cognee-llm  (SEPARATE wrapper, :8011)
               • stateless one-shot: kimi -p (fresh disposable session per call)
               • NO resume, NO media, NO MCP, NON-streaming, structured/JSON out
               • high concurrency for batch cognify
             ──► embeddings: LiteLLM `embedder` (nomic-embed), NOT the CLI
```

Reused infra (all in `agap_git/openai/docker-compose.yml`): **Qdrant** `:6333` (cognee vectors),
**LiteLLM** `:4000` (embeddings + optional observability + fallback LLM), **Langfuse**, Postgres.

---

## 3. Components

### 3.1 OpenClaw ("Adolf") — the shell
Node 24 (≥22.19). Cloned into this repo. Configuration:
- **Model provider** (custom): `{ baseUrl: "http://adolf-llm:8010/v1", apiKey: "${ADOLF_KEY}",
  api: "openai-completions", models: [{ id: "adolf", input: ["text","image"] }] }`; default agent
  model `adolf`.
- **SOUL.md** persona "Adolf" (Russian-friendly, concise).
- **Matrix channel** with bot creds from Vaultwarden (`MATRIX_ADOLF_PASSWORD` / `MATRIX_ADOLF_TOKEN`);
  route room/peer → the Adolf agent.
- **MCP registry** = cognee-mcp + the openclaw-tools bridge; the same server list feeds
  `shared-mcp.json` (single source of truth).

### 3.2 `adolf-llm` — conversational wrapper (:8010)
New `agap_git/openai/adolf-llm/` (`Dockerfile` + `server.js`), own CLI-home volume + conversations
workspace. OpenAI-compatible `GET /v1/models` + `POST /v1/chat/completions` (model `adolf`).
Reuses proven bits from `agap_git/openai/kimi-agent/server.js` (session map w/ prune, `convTurns`/
`textOf`, `runKimi` spawn + stream-json parse, resume). Adds:
- **Real streaming** — parse stream-json assistant deltas → OpenAI `chat.completion.chunk` SSE.
- **Media** — persist `image_url`/base64 parts to the session dir, reference file paths in the prompt.
- **Session correspondence** — key the map on OpenClaw's session id (not a history hash) → 1:1
  `kimi -r` resume → Moonshot context-cache hits → token savings. Fallback: improved history-hash.
- **Shared MCP** — `--mcp-config-file shared-mcp.json` so the CLI can call OpenClaw/cognee tools.
- **Cognee hooks** — pre-turn `cognee.search()` inject; post-turn async `cognee.add()`.

### 3.3 `cognee-llm` — stateless wrapper (:8011)
New `agap_git/openai/cognee-llm/`, own disposable workspace + CLI-home volume (same subscription).
Shares the `runKimi`/stream-json core but with the **opposite policy**: stateless one-shot
(`kimi -p`, fresh temp dir per call, **no resume**), **non-streaming**, **no media, no MCP**,
structured/JSON-oriented, low temperature, bounded parallelism for batch cognify. Cognee's
`LLM_API_BASE` → `http://cognee-llm:8011/v1`.
> ⚠️ Risk: cognify issues many structured calls; the agentic CLI adds per-call latency and may not
> reliably emit clean JSON. Fallback: route cognee's LLM to a LiteLLM model (`judge`/local qwen)
> while keeping Kimi for the assistant. Decide after a batch cognify test.

### 3.4 Cognee memory service
`cognee` + `cognee-mcp` containers. Backends: **Qdrant** (vectors), **graph store** = Kuzu (embedded)
or Neo4j (decision), **LLM** via `cognee-llm`, **embeddings** via LiteLLM `embedder`. Persist under
`/mnt/ssd/dbs/cognee/`. `cognee-mcp` exposes `memory_search`/`memory_add`/`cognify` into
`shared-mcp.json`. Memories scoped per OpenClaw user/session.

### 3.5 Shared MCP layer ("smart tool integration")
`shared-mcp.json` is the contract both consumers (OpenClaw + Kimi CLI) use. Cognee-mcp is
off-the-shelf. The **openclaw-tools bridge** exposes the OpenClaw integrations Adolf needs
(send-to-channel, cron/reminders, browser/nodes) as MCP tools. Start minimal, grow.

---

## 4. Open gates to verify early
1. **Kimi CLI home/MCP path & package** — current container uses `@moonshot-ai/kimi-code` +
   `/root/.kimi-code`; upstream is now `MoonshotAI/kimi-cli` + `~/.kimi/mcp.json`. Confirm package,
   home dir, `--mcp-config-file`, and that `kimi login` subscription auth persists in the new
   containers' CLI-home volumes.
2. **OpenClaw → provider session identity** — does OpenClaw forward a stable session id to a custom
   provider (header / `user` / `metadata`)? Decides robust mapping vs. hash fallback.
3. **Headless image input** — confirm the CLI accepts images in `-p` runs via file-path references.
4. **Graph store** — Kuzu embedded vs Neo4j service for cognee.
5. **Cognee-llm suitability** — batch cognify latency/JSON reliability via the CLI vs LiteLLM fallback.

---

## 5. End-to-end verification
- Matrix message → OpenClaw → `adolf-llm` → `kimi` → **streamed** reply token-by-token in Matrix.
- Send an **image** on Matrix → CLI reads it (describe-the-image test).
- Follow-up → same **Kimi session resumed** (`sessions.json` maps to one session; reduced prompt
  tokens vs. cold turn).
- **Memory** — a stated fact is recalled in a later session via `memory_search`; cognee graph/Qdrant
  populated (auto-ingest); cognify's LLM served by `cognee-llm` (or LiteLLM fallback).
- **MCP tool** — a tool call works mid-turn (e.g. set a reminder via the bridge).
- The **old `kimi-agent`** service is unchanged and still serves OpenWebUI.