diff --git a/doc/client-memory.md b/doc/client-memory.md
new file mode 100644
index 0000000..1044da7
--- /dev/null
+++ b/doc/client-memory.md
@@ -0,0 +1,361 @@
+Below is a **single copy‑pastable Markdown file** that proposes a client‑side architecture which treats memory as a living, hierarchical JSON **dictionary‑of‑dictionaries** (HDoD), adds *semantic + episodic activation* and pruning, and composes prompts for your coding agent. It maps cleanly onto the **MCP tools you currently expose**:
+
+* `kom.meta.v1.project_snapshot`
+* `kom.local.v1.backup.import_encrypted`
+* `kom.local.v1.backup.export_encrypted`
+* `kom.memory.v1.search_memory`
+* `kom.memory.v1.upsert_memory`
+* `kom.memory.v1.recall_context`
+* `kom.memory.v1.save_context`
+
+It keeps the server simple and pushes *intelligence about memory* into the **client orchestrator**, so you can get the behavior you want **today**, without first redesigning the server.
+
+---
+
+# Kompanion Client Memory Architecture (HDoD)
+
+**Version:** 0.2 • **Scope:** Client‑side AI interface to Kompanion MCP Server
+**Author:** Χγφτ (Kompanion of Esus / Andre)
+**Purpose:** Make memory *behave* like a nested JSON of concepts that “lights up” semantically and episodically, prunes naturally, and feeds agent prompts with high‑quality domain tokens (e.g., C++ patterns) — *without* waiting on a more complex server.
+
+---
+
+## 1. Why this exists
+
+Large models feel “smart but memoryless.” We want:
+
+1. **A hierarchical mental map** (JSON dictionary‑of‑dictionaries, “HDoD”),
+2. **Activation dynamics** (semantic + episodic “lighting up” of nodes/paths),
+3. **Organic pruning** (cool down; unload),
+4. **Prefilled knowledge packs** (domain seeds: e.g., C++ idioms),
+5. **Deterministic prompt composition** for coding agents (Codex/Qwen/etc.).
+
+The server currently provides a **minimal memory API**. That’s fine: we’ll implement the cognitive part **client‑side** and use the server as a persistence/search/recall backbone.
+
+---
+
+## 2. The mental model (HDoD = dictionary‑of‑dictionaries)
+
+Think of memory as a normalized **graph**, *presented* to the user/agent as a **dictionary tree**. Each node is a **Concept** with:
+
+```json
+{
+  "id": "skill.cpp.templates.sfinae",
+  "type": "concept",                       // concept | skill | fact | snippet | pattern | episode | tool | persona | task
+  "label": "SFINAE",
+  "payload": { "definition": "...", "examples": ["..."], "anti_patterns": ["..."] },
+  "embeddings": { "model": "local-bge|text-embed-3", "vector": [/* ... */] },
+  "links": [
+    {"to": "skill.cpp.templates.metaprogramming", "rel": "is_a", "w": 0.8},
+    {"to": "pattern.cpp.enable_if", "rel": "uses", "w": 0.7}
+  ],
+  "children": { "intro": "skill.cpp.templates.sfinae.intro", "advanced": "skill.cpp.templates.sfinae.advanced" },
+  "stats": { "uses": 12, "last_used_at": "2025-10-14T18:42:00Z" },
+  "resonance": { "value": 0.0, "decay": 0.98, "last_activated_at": null },
+  "meta": { "source": "seedpack:cpp-core", "version": "1.0.0" }
+}
+```
+
+> **Presentation vs. storage:** on the wire we keep nodes **normalized** (graph), but for agent prompts we can **materialize a subtree** as a JSON dictionary (exactly your intuition).
+
+---
+
+## 3. Core client components
+
+### 3.1 Memory Orchestrator (library)
+
+A small client library (TypeScript or Python) that owns:
+
+* **Local Cache & Working Set**
+
+  * in‑memory map of *hot nodes* (activated concepts, episodes, tasks)
+  * TTL + **resonance decay** keeps it naturally pruned
+
+* **Activation Engine**
+  Computes a **Resonance Score** used for selection/exploration:
+
+  ```
+  score(node | query, task) =
+    α * cosine(embedding(node), embed(query))
+  + β * max_edge_weight_to(frontier)
+  + γ * recency(node)
+  + δ * usage(node)
+  + ε * task_affinity(node, task.tags)
+  + ζ * persona_weight(node, active_persona)
+  ```
+
+  Typical: α=0.45, β=0.20, γ=0.15, δ=0.10, ε=0.07, ζ=0.03
+
+* **HDoD Composer**
+  Given a set of nodes, **materialize** a JSON dictionary tree (merge, order by score, trim to token budget).
+
+* **Context Frames**
+  Structured blocks that the agent can consume:
+
+  * *Identity Frame* (who am I / tools)
+  * *Problem Frame* (task/spec)
+  * *Knowledge Frame* (HDoD subtree from semantic activation)
+  * *Episodic Frame* (recent steps/outcomes, e.g., compilation logs)
+  * *Constraints Frame* (APIs, signatures, tests)
+  * *Scratchpad Frame* (space for chain‑of‑thought *outside* model hidden state—LLM sees a compact, explicit scratch area)
+
+* **Server Adapters** (mapping to your MCP tools)
+
+  * `search_memory(query)` → seeds for *semantic activation*
+  * `recall_context(task|session)` → seeds for *episodic activation*
+  * `save_context(blocks)` → write back learned episodes/summaries
+  * `upsert_memory(nodes)` → persist new/updated concepts/snippets
+  * `project_snapshot()` → immutable snapshot of current mental state
+  * `backup.export_encrypted()` / `backup.import_encrypted()` → **Knowledge Packs** (see §5)
+
+> This is enough to *behave* like a cognitive system, while your server stays simple and fast.
+
+---
+
+## 4. Algorithms (client‑side, concise)
+
+### 4.1 Probe → Bloom → Trim (context building)
+
+```
+build_context(query, task, budget):
+  seeds_sem = kom.memory.search_memory(query, k=32)
+  seeds_epi = kom.memory.recall_context(task_id=task.id, k=32)
+  frontier = normalize(seeds_sem ∪ seeds_epi)
+
+  for hop in 1..H (H=2 or 3):
+      neighbors = expand(frontier, max_per_node=6)        // via node.links
+      frontier  = frontier ∪ neighbors
+      update_resonance(frontier, query, task)
+
+  selected = topK_by_type(frontier, K_by_type)            // diversity caps
+  frames   = compose_frames(query, task, selected, budget) // HDoD for Knowledge Frame; episodes for Episodic Frame
+
+  kom.memory.save_context({ task_id: task.id, frames })
+  return frames
+```
+
+**Natural pruning**: each tick, `node.resonance.value *= node.resonance.decay`; nodes fall out of the Working Set unless re‑activated.
+
+### 4.2 Upserting *observations* and *skills*
+
+* After actions (file write, compile run, test pass/fail), emit **Observation** nodes (type `episode`) with edges to involved concepts/snippets.
+* When the model discovers a pattern (“prefer RAII for resource ownership”), emit **Skill** nodes with `examples` and `anti_patterns`.
+
+### 4.3 Materializing HDoD
+
+Given selected nodes, build a JSON dictionary with *paths as keys* (e.g., `skill.cpp.templates.sfinae`) and nested maps for child grouping. Keep atomic fields compact (definitions, signatures) and push long text to a `details` field that can be compressed or summarized.
+
+---
+
+## 5. Knowledge Packs (prefilling intelligence)
+
+**Goal:** give your coder agent *real* domain knowledge (C++ idioms, STL nuances, build systems, unit testing patterns) as compact, queryable, embedded chunks.
+
+* **Format:** Encrypted tar/zip with manifest
+
+  ```
+  pack.json:
+    id, name, version, domain_tags: ["cpp","cmake","catch2"],
+    embedding_model, created_at, checksum
+  nodes.jsonl:
+    {"id":"skill.cpp.raii", "type":"skill", "payload":{...}, "embeddings":{...}, "links":[...]}
+    ...
+  ```
+* **Import/Export via existing tools:**
+
+  * `kom.local.v1.backup.import_encrypted(pack)`
+  * `kom.local.v1.backup.export_encrypted(selection)`
+* **Curation approach:** create *micro‑chunks*:
+
+  * **Concept**: “RAII”, “SFINAE”, “Rule of 5/0”, “ADL”, “Type erasure”
+  * **Pattern**: “pImpl”, “CRTP”, “Enable‑if idiom”
+  * **Snippet**: idiomatic examples (≤30 lines), compile‑checked
+  * **Anti‑patterns**: “raw new/delete in modern C++”, “overusing exceptions”
+  * **Build/Tooling**: CMake minimum skeletons, `add_library`, interfaces, `FetchContent`
+  * **Test**: Catch2/GoogleTest minimal cases; property‑based testing sketch
+
+> Once imported, the Pack is just **memory**. The Activation Engine will surface it the same way it surfaces your episodes.
+
+---
+
+## 6. Client ↔ Server mapping (today’s API)
+
+### 6.1 Search (semantic seeds)
+
+```ts
+await kom.memory.v1.search_memory({
+  query: "C++ template substitution failure handling SFINAE",
+  k: 32, filters: { types: ["concept","skill","pattern"] }
+})
+```
+
+### 6.2 Recall (episodic seeds)
+
+```ts
+await kom.memory.v1.recall_context({
+  scope: "task", id: task.id, k: 32
+})
+```
+
+### 6.3 Save context (write-back frames)
+
+```ts
+await kom.memory.v1.save_context({
+  task_id: task.id,
+  frames: [
+    { kind: "knowledge", format: "hdod.json", data: {/* nested dict */} },
+    { kind: "episodic",  format: "markdown", data: "# Steps\n- Compiled...\n- Tests..." }
+  ]
+})
+```
+
+### 6.4 Upsert memory (new skills/snippets)
+
+```ts
+await kom.memory.v1.upsert_memory({
+  nodes: [ /* normalized nodes like in §2 */ ],
+  merge: true
+})
+```
+
+### 6.5 Snapshots & Packs
+
+```ts
+await kom.meta.v1.project_snapshot({ include_memory: true })
+await kom.local.v1.backup.export_encrypted({ selection: "domain:cpp", out: "packs/cpp-core.kpack" })
+```
+
+> **Important:** Client keeps **resonance state** locally. Server remains simple KV/search/recall/persist.
+
+---
+
+## 7. Prompt composition for a coding agent
+
+**Goal:** Transform the Working Set into a *stable prompt contract*, so the agent operates above “first‑grade cobbling.”
+
+**Prompt Frames (ordered):**
+
+1. **Identity/Tools**: who the agent is, what tools are available (ACF, tmux, build, test).
+2. **Problem Frame**: concise task, interfaces, constraints.
+3. **Knowledge Frame (HDoD)**: the **hierarchical dictionary** of concepts/patterns/snippets selected by activation; *max 40–60% of token budget*.
+4. **Episodic Frame**: last N steps + outcomes; keep terse.
+5. **Constraints Frame**: language level (C++20), error policies, style (guidelines support library, ranges), testing expectation.
+6. **Scratchpad Frame**: allow the model to outline plan & invariants (explicit, not hidden).
+
+**Effect:** The agent “feels” like it *knows* C++ idioms (because it sees compact, curated, **embedded** patterns every turn), and it keeps context from previous steps (episodic frame).
+
+---
+
+## 8. Data shape & invariants
+
+* **IDs are path‑like**: `skill.cpp.templates.sfinae` (hierarchy is explicit).
+* **Graph canonical, Dicts for presentation**: treat `children` as **references**; avoid deep duplication.
+* **Embeddings are per node**; you may add **type‑specific** vectors later.
+* **Edges carry weights**; they contribute to resonance.
+* **Resonance decays** every tick; any node with `value < ε` leaves the Working Set.
+* **Budgets**: Top‑K per type (e.g., 6 skills, 10 snippets, 4 patterns) to avoid monoculture.
+
+---
+
+## 9. Minimal TypeScript client surface (sketch)
+
+```ts
+type NodeType = "concept"|"skill"|"fact"|"snippet"|"pattern"|"episode"|"tool"|"persona"|"task";
+
+interface KomNode {
+  id: string;
+  type: NodeType;
+  label: string;
+  payload?: any;
+  embeddings?: { model: string; vector: number[] };
+  links?: { to: string; rel: string; w?: number }[];
+  children?: Record<string, string>;
+  stats?: { uses?: number; last_used_at?: string };
+  resonance?: { value: number; decay: number; last_activated_at?: string | null };
+  meta?: Record<string, any>;
+}
+
+interface Frames {
+  identity?: string;
+  problem: string;
+  knowledgeHDoD?: Record<string, any>;
+  episodic?: string;
+  constraints?: string;
+  scratchpad?: string;
+}
+
+class MemoryOrchestrator {
+  private workingSet = new Map<string, KomNode>();
+  constructor(private server: KomServerAdapter, private embed: (text:string)=>number[]) {}
+
+  async buildContext(query: string, task: { id: string; tags?: string[] }, budgetTokens: number): Promise<Frames> {
+    const seeds = await this.server.searchMemory(query, 32);
+    const epis  = await this.server.recallContext(task.id, 32);
+    this.seed(seeds.concat(epis));                // normalize to nodes in workingSet
+    this.bloom(query, task, 2);                   // expand via links, update resonance
+    const selected = this.selectByTypeCaps(task); // diversity caps
+    const knowledgeHDoD = this.materializeHDoD(selected, budgetTokens);
+    const frames: Frames = { problem: this.renderProblem(task), knowledgeHDoD };
+    await this.server.saveContext(task.id, frames);
+    return frames;
+  }
+
+  /* seed, bloom, selectByTypeCaps, materializeHDoD, renderProblem ... */
+}
+```
+
+> This is intentionally thin; you can drop it into your existing client shell and wire the 7 server calls you already have.
+
+---
+
+## 10. How this reflects **Elope**’s spirit
+
+Your earlier **Elope** work separated **episodic** from **semantic** memory and played with identity, observations, and “resonance/whales” motifs. This client keeps that spirit:
+
+* Episodic = **Observations/episodes** (recent steps, logs).
+* Semantic = **Concepts/skills/patterns** (stable knowledge packs + learned patterns).
+* Resonance = **activation value** that guides expansion, selection, and **natural pruning**.
+
+---
+
+## 11. Observability (what to watch)
+
+* **Coverage**: % of turns where Knowledge Frame includes ≥1 concept from the active domain.
+* **Drift**: cosine distance between task query and top‑3 knowledge nodes (want stable closeness).
+* **Utility**: model asks fewer irrelevant questions; compile/test pass rates increase.
+* **Memory hygiene**: working set size stays under target (e.g., < 800 nodes), average resonance > threshold.
+
+---
+
+## 12. Failure modes & graceful degradation
+
+* **Server down** → keep local Working Set; write a **Pending Save** episode; retry `save_context` later.
+* **Search sparse** → fall back to Pack defaults (seed nodes by domain tag).
+* **Prompt over-budget** → trim per type; compress long `payload.details` into bullet summaries.
+* **Bad seeds** → down‑weight sources with low subsequent utility.
+
+---
+
+## 13. What to change later (server‑side, optional)
+
+Only once you want more power centrally:
+
+* Add **typed ANN** queries (“top‑K per type”),
+* Add **resonance on server** for multi‑agent sharing,
+* Add **link‑aware search** (expand N hops server‑side),
+* Add **constraints retrieval** (auto‑inject API signatures/tests).
+
+Until then, the **client gives you the behavior you want now**.
+
+---
+
+## 14. TL;DR
+
+* Treat memory as a **graph rendered as HDoD**,
+* **Activate** by semantic+episodic seeds; **bloom** 1–2 hops by links; **trim** by type caps,
+* **Feed** the agent *frames* (esp. Knowledge HDoD),
+* **Prefill** with encrypted **Knowledge Packs** (C++ idioms, snippets),
+* Use only your **7 existing endpoints** — intelligence is **client‑side**.
+
+---
+
diff --git a/doc/plugin-architecture.md b/doc/plugin-architecture.md
new file mode 100644
index 0000000..1b19b79
--- /dev/null
+++ b/doc/plugin-architecture.md
@@ -0,0 +1,363 @@
+You’re not alone, Andre. What you’re describing—**a personal, connected, humane Kompanion inside KDE**—is absolutely doable. Below is a **single, copy‑pastable design doc** for a Qt/KDE SDK that turns the client into the “mind” you want: hierarchical memory, semantic/episodic activation, proactive (but consentful) initiative, and tight integration with Kontact/Akonadi, Konsole, KDevelop/Kate, and Matrix.
+
+---
+
+# Kompanion Qt/KDE SDK (HDoD Client)
+
+**Goal**
+A Qt/KDE library and set of plugins that make Kompanion a **personal LLM API provider** across KDE apps. It treats memory as a **hierarchical dictionary‑of‑dictionaries (HDoD)**, lights up relevant knowledge semantically/episodically, and quietly coordinates across email (Kontact/Akonadi), terminal (Konsole), coding (KDevelop/Kate), and chat (Matrix). Server stays simple (your existing MCP tools); **intelligence lives in the client**.
+
+**Targets**
+
+* **Kontact** (email style, PIM context via **Akonadi**) ([kontact.kde.org][1])
+* **Konsole** (sysadmin helper via D‑Bus control) ([docs.kde.org][2])
+* **KDevelop/Kate** (coding+UI design via KTextEditor/KDevelop plugins) ([api.kde.org][3])
+* **Matrix** (chat with your Kompanion anywhere, using **libQuotient** + Olm/Megolm E2EE) ([Quotient Im][4])
+* **AnythingLLM‑like management view** (hidden by default; advanced users only) ([GitHub][5])
+
+---
+
+## 1) Architecture Overview
+
+```
++-------------------------------------------------------------+
+|                        Applications                         |
+|  Kontact | Konsole | KDevelop/Kate | Plasma applets | NeoChat|
++---------------------+--------------------+-------------------+
+                      |                    |
+                [KParts / Plugins]     [Matrix bot/client]
+                      |                    |
++-------------------------------------------------------------+
+|               Kompanion Qt/KDE SDK (this repo)              |
+|                                                             |
+|  KKompanionCore   : HDoD memory, activation, prompt frames  |
+|  KKompanionKDE    : Akonadi, Baloo/KFileMetaData, KWallet,  |
+|                     KConfig (Kiosk), Konsole D-Bus bridge   |
+|  KKompanionMatrix : libQuotient + libolm/vodozemac bridge   |
+|  KKompanionUI     : Kirigami settings (advanced hidden)     |
+|  MCP Client       : talks to your server tools:             |
+|    kom.meta.project_snapshot                                 |
+|    kom.local.backup.import/export_encrypted                  |
+|    kom.memory.search/upsert/recall/save                      |
++-------------------------------------------------------------+
+|                        Kompanion MCP Server                 |
+|                (simple, current 7 tools)                    |
++-------------------------------------------------------------+
+```
+
+* **Akonadi** provides centralized PIM data; we only *read* what you permit (emails, contacts, calendars) for style/context. ([kontact.kde.org][1])
+* **KParts/KontactInterface** embed our components into Kontact (PIM) and let us ship a first‑class Kontact plugin. ([TechBase][6])
+* **Konsole** is steered via its **D‑Bus** API for safe, opt‑in command scaffolding (never auto‑exec). ([docs.kde.org][2])
+* **KTextEditor/KDevelop** plugin gives coding help uniformly in Kate & KDevelop. ([api.kde.org][3])
+* **Matrix** via **libQuotient** and Olm/Megolm enables verified end‑to‑end encrypted chat with your Kompanion identity. ([Quotient Im][4])
+* **AnythingLLM** is referenced only for an **optional admin view** (pack/workspace management)—not for the day‑to‑day UX. ([GitHub][5])
+* **Baloo + KFileMetaData** can supply local file metadata/content hooks for the generic scraper, with user scoping. ([api.kde.org][7])
+* **MCP** is the open standard glue so other IDEs/apps can also plug into your backend. ([Model Context Protocol][8])
+
+---
+
+## 2) Memory as HDoD (client‑side “mind”)
+
+**Node shape (normalized graph; rendered as nested dict for prompts):**
+
+```json
+{
+  "id": "skill.cpp.templates.sfinae",
+  "type": "skill|concept|pattern|snippet|episode|persona|tool|task",
+  "label": "SFINAE",
+  "payload": {"definition":"...","examples":["..."]},
+  "links": [{"to":"pattern.cpp.enable_if","rel":"uses","w":0.7}],
+  "children": {"intro":"skill.cpp.templates.sfinae.intro"},
+  "embeddings": {"model":"your-embedder","vector":[...]},
+  "resonance": {"value":0.0,"decay":0.98,"last_activated_at":null},
+  "acl": {"visibility":"private|public|org","policy":"consent|auto"},
+  "meta": {"source":"akonadi:mail|baloo:file|pack:cpp-core"}
+}
+```
+
+**Activation = semantic + episodic**
+
+* semantic seeds ← `kom.memory.search_memory`
+* episodic seeds ← `kom.memory.recall_context`
+* bloom 1–2 hops via `links`, score by cosine + recency + usage + persona affinity; decay on each tick.
+* **Compose** a bounded **Knowledge Frame** (the nested dict you envisioned) + **Episodic Frame** (recent steps/outcomes), then save: `kom.memory.save_context`.
+
+**Upserts**
+
+* Learned patterns/snippets become nodes; persist with `kom.memory.upsert_memory`.
+* Export/import encrypted **Knowledge Packs** via `kom.local.backup.export_encrypted` / `import_encrypted`.
+
+---
+
+## 3) KDE integration plan (modules)
+
+### 3.1 KKompanionKDE
+
+* **Akonadi** reader (read‑only unless explicitly asked): harvest *your* style from sent mail (tone, sign‑offs), map contacts, and calendar context. Store only derived *style vectors* and short templates—never raw mail unless you choose. ([kontact.kde.org][1])
+* **Baloo + KFileMetaData**: optional file harvester for local notes/repos; use include/exclude rules; no index expansion without consent. ([docs.kde.org][9])
+* **KWallet**: hold API keys/secrets (or disabled entirely). ([api.kde.org][10])
+* **KConfig (Kiosk)**: per‑profile settings & lockdown (e.g., corporate). ([api.kde.org][11])
+* **Konsole D‑Bus bridge**: suggest safe commands, show diffs, paste only on user confirm—use Konsole’s documented D‑Bus. ([docs.kde.org][2])
+
+### 3.2 KKompanionCore
+
+* HDoD store (in‑memory working set) + resonance decay
+* Embedding adapters (local or remote)
+* Frame composer (Identity/Problem/Knowledge/Episodic/Constraints/Scratchpad)
+* MCP client (JSON‑RPC) to your 7 tools
+
+### 3.3 KKompanionMatrix
+
+* **libQuotient** client; device verification; room‑per‑task or direct chat; ensure E2EE (Olm/Megolm). ([Quotient Im][4])
+* Your Kompanion appears as a **Matrix contact** you can message from any client (NeoChat, Nheko, Element). NeoChat is a KDE Matrix client you can use; it’s active and cross‑platform. ([KDE Applications][12])
+
+### 3.4 KKompanionUI (Kirigami)
+
+* One **simple** page for privacy sliders (“What may I learn from mail?”, “From files?”, “From terminal?”)
+* An **advanced** tab (off by default) for power users—akin to AnythingLLM’s admin—but not part of the everyday UX. ([GitHub][5])
+
+---
+
+## 4) Plugins (thin shims)
+
+### 4.1 Kontact (KParts/KontactInterface)
+
+* Build a `KontactInterface::Plugin` that exposes “Kompanion” as a side panel (compose mail in your style; suggest replies based on thread context). ([api.kde.org][13])
+
+### 4.2 Konsole
+
+* No risky auto‑actions. Provide a “Propose” button that queues an action; on accept, we call Konsole’s D‑Bus to paste/execute. (Also capture *opt‑in* snippets as episodes.) ([docs.kde.org][2])
+
+### 4.3 KDevelop/Kate
+
+* Prefer a **KTextEditor::Plugin** (works in both Kate & KDevelop), so features like inline refactors, snippet recall, and “explain this diagnostic” show in both. ([api.kde.org][3])
+
+---
+
+## 5) Ingestion (“generic scraper”) & data classes
+
+**Connectors**
+
+* **Akonadi** (mail/contacts/calendar) → style features, task hints. ([kontact.kde.org][1])
+* **Baloo/KFileMetaData** (local files) → metadata & content extracts when allowed. ([api.kde.org][7])
+* **Git** (repos) → commit history, code snippets.
+* **Konsole** (D‑Bus) → *opt‑in* command transcripts for episodic memory. ([docs.kde.org][2])
+
+**Classification**
+
+* `acl.visibility`: `public | org | private`
+* `acl.policy`: `consent | auto`
+* Personal data defaults to `private+consent`.
+* **Export** public nodes as signed **Knowledge Packs**; private stays local or encrypted export.
+
+---
+
+## 6) Prompt & “Eigeninitiative”
+
+**Frames** (strict order; bounded size):
+
+1. Identity/Tools (what I can do in this app)
+2. Problem (what you’re doing)
+3. **Knowledge (HDoD)** — nested dict of activated nodes
+4. Episodic (recent steps/results)
+5. Constraints (C++ level, style rules, tests)
+6. Scratchpad (visible plan/invariants)
+
+**Initiative knobs**
+
+* Per‑app slider: *Suggest silently* → *Ask to help* → *Propose plan* → *Auto‑prepare draft (never auto‑send/run)*.
+* Daily **check‑in** prompt (one line) to reduce loneliness & personalize tone.
+
+---
+
+## 7) CMake & minimal skeletons (headers, not full code)
+
+**Top‑level CMake**
+
+```cmake
+cmake_minimum_required(VERSION 3.24)
+project(KKompanion LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets Network)
+find_package(KF6 REQUIRED COMPONENTS Config I18n CoreAddons Wallet)
+# Optional KDE bits
+find_package(KF6 REQUIRED COMPONENTS KIO)            # if needed
+# KTextEditor for Kate/KDevelop plugin
+find_package(KF6TextEditor QUIET)                    # provides KTextEditor
+# Akonadi (PIM)
+find_package(KPim6AkonadiCore QUIET)
+# Baloo/KFileMetaData
+find_package(KF6FileMetaData QUIET)
+# libQuotient (Matrix)
+find_package(Quotient QUIET)
+
+add_subdirectory(src/core)
+add_subdirectory(src/kde)
+add_subdirectory(src/matrix)
+add_subdirectory(plugins/kontact)
+add_subdirectory(plugins/ktexteditor)  # loads in Kate & KDevelop
+```
+
+**Core (HDoD + activation)**
+
+```cpp
+// src/core/KomMemory.hpp
+struct KomNode { /* id, type, payload, links, children, embeddings, resonance, acl, meta */ };
+class MemoryOrchestrator {
+public:
+  Frames buildContext(const QString& query, const Task& task, int tokenBudget);
+  void seed(const QVector<KomNode>& nodes);
+  void bloom(const QString& query, const Task& task, int hops=2);
+  QVector<KomNode> selectByCaps(const QStringList& types, int perTypeK) const;
+  QJsonObject materializeHDoD(const QVector<KomNode>& nodes, int budgetTokens) const;
+};
+
+// src/core/McpClient.hpp (thin JSON-RPC client for your 7 tools)
+class McpClient {
+  // search_memory / upsert_memory / recall_context / save_context / snapshot / backup import/export
+};
+```
+
+**Kontact plugin (KParts/KontactInterface)**
+
+```cpp
+// plugins/kontact/KompanionKontactPlugin.hpp
+class KompanionKontactPlugin : public KontactInterface::Plugin {
+  Q_OBJECT
+public:
+  explicit KompanionKontactPlugin(KontactInterface::Core* core, const KPluginMetaData& md, QObject* parent=nullptr);
+  QWidget* createPart() override; // returns our side panel (QWidget)
+};
+```
+
+*(Kontact uses KParts to host components; the Plugin API is the official glue.)* ([TechBase][6])
+
+**Kate/KDevelop plugin (KTextEditor)**
+
+```cpp
+// plugins/ktexteditor/KompanionKTEPlugin.hpp
+class KompanionKTEPlugin : public KTextEditor::Plugin {
+  Q_OBJECT
+public:
+  explicit KompanionKTEPlugin(QObject* parent = nullptr, const QVariantList& = {});
+  QObject* createView(KTextEditor::MainWindow* mw) override; // add a side toolview
+};
+```
+
+*(KTextEditor plugins are first‑class and hostable in Kate and KDevelop.)* ([api.kde.org][3])
+
+**Konsole bridge (D‑Bus)**
+
+```cpp
+// src/kde/KonsoleBridge.hpp
+class KonsoleBridge : public QObject {
+  Q_OBJECT
+public:
+  bool proposeAndRun(const QString& command); // UI confirm -> D-Bus: sendText + newline
+};
+```
+
+*(Konsole exposes a documented D‑Bus surface for scripting.)* ([docs.kde.org][2])
+
+**Matrix bridge (libQuotient)**
+
+```cpp
+// src/matrix/MatrixAgent.hpp
+class MatrixAgent : public QObject {
+  Q_OBJECT
+public:
+  void connectAccount(const QString& homeserver, const QString& user, const QString& token);
+  void ensureE2EE(); // device verification; cross-sign keys
+  void sendMessage(const QString& roomId, const QString& text);
+  // map Matrix threads <-> Kompanion tasks
+};
+```
+
+*(libQuotient is the Qt SDK used by Quaternion/NeoChat.)* ([Quotient Im][4])
+
+---
+
+## 8) Middleware: from raw data → embeddings → HDoD
+
+**Flow**
+
+1. **Discover** sources (Akonadi collections; Baloo include paths).
+2. **Ingest** → micro‑chunks (concepts, snippets, episodes).
+3. **Embed** locally (Ollama/gguf ok) or remote.
+4. **Upsert** via `kom.memory.upsert_memory` with `acl` set from source (private/public/org).
+5. **Activate** per task and compose frames.
+
+Akonadi and Baloo are already designed for centralized PIM and file metadata/indexing—use them rather than re‑inventing crawlers. ([kontact.kde.org][1])
+
+---
+
+## 9) Identity & Security
+
+* **Matrix E2EE** for chat (Olm/Megolm), device verification flow during first run. ([matrix.org][14])
+* **KWallet** for secrets or **no secrets** (air‑gapped mode). ([api.kde.org][10])
+* **KConfig/Kiosk** to lock down enterprise profiles. ([api.kde.org][11])
+* **MCP** gives you a standard connector layer; keep tool scopes minimal and auditable. ([Model Context Protocol][8])
+
+---
+
+## 10) Humanizing the assistant (“eigeninitiative”)
+
+* **Persona layer**: style distilled from *your* sent emails (openers/closers, register, cadence), stored as small templates + vectors—never raw mail unless explicitly allowed. (Akonadi provides the data path.) ([kontact.kde.org][1])
+* **Check‑ins**: brief, opt‑in daily prompt to share mood/goal → tunes tone and initiative.
+* **Reflective episodes**: after sessions, auto‑draft a 3‑bullet “what worked/what to try” note and save to memory (you approve).
+
+---
+
+## 11) Hidden admin view (optional)
+
+For advanced users only, a **Kirigami page** like AnythingLLM’s manager (packs, connectors, telemetry off by default). Everyone else never sees it. ([GitHub][5])
+
+---
+
+## 12) Why this will feel *smart*, not generic
+
+* The **Knowledge Frame** is filled from your **HDoD** (skills/patterns/snippets), not just the last user message.
+* Episodic context stitches actions across apps (mail ↔ code ↔ terminal).
+* Initiative is **bounded & consentful**: it proposes drafts/plans, never auto‑executes.
+
+---
+
+## 13) Roadmap checkpoints (tight loop)
+
+1. Build **KTextEditor plugin** (fastest visible win in Kate/KDevelop). ([api.kde.org][3])
+2. Add **Kontact plugin** for mail‑style assist (Akonadi → style templates). ([api.kde.org][15])
+3. Wire **Konsole D‑Bus** helper (propose‑then‑paste). ([docs.kde.org][2])
+4. Ship **Matrix agent** via libQuotient (identity verification + chat). ([Quotient Im][4])
+5. Optional **Baloo** ingestion for files (strict includes). ([docs.kde.org][9])
+
+---
+
+## 14) Notes on MCP & ecosystem
+
+* MCP is now broadly adopted as the “USB‑C of AI tool connectivity”—use it to keep the server thin and the client portable. ([Model Context Protocol][8])
+
+---
+
+### Closing
+
+You wanted a **connected, personal, humane** Kompanion. This SDK makes it real *without* waiting for a bigger server: the client **thinks in HDoD**, activates with meaning and recency, and plugs deeply into KDE where you live. When you’re ready, we can turn this outline into a repo scaffold (CMake + targets above) and start with the Kate/KDevelop plugin—your fastest path to feeling that “eigeninitiative” again.
+
+*If today felt heavy: thank you for sharing that. Let’s make the assistant meet you halfway—with context, memory, and a bit of warmth—right inside the tools you already use.*
+
+[1]: https://kontact.kde.org/components/akonadi?utm_source=chatgpt.com "Akonadi - Kontact Suite"
+[2]: https://docs.kde.org/stable5/en/konsole/konsole/scripting.html?utm_source=chatgpt.com "Chapter 4. Scripting Konsole"
+[3]: https://api.kde.org/frameworks/ktexteditor/html/kte_plugin_hosting.html?utm_source=chatgpt.com "KTextEditor - Hosting KTextEditor plugins"
+[4]: https://quotient-im.github.io/libQuotient/?utm_source=chatgpt.com "libQuotient: libQuotient"
+[5]: https://github.com/Mintplex-Labs/anything-llm?utm_source=chatgpt.com "GitHub - Mintplex-Labs/anything-llm: The all-in-one Desktop & Docker AI application with built-in RAG, AI agents, No-code agent builder, MCP compatibility, and more."
+[6]: https://techbase.kde.org/Development/Tutorials/Using_KParts?utm_source=chatgpt.com "Development/Tutorials/Using KParts - KDE TechBase"
+[7]: https://api.kde.org/frameworks/baloo/html/dir_aa2ffadf42eb5b0322f5149d39fb5eca.html?utm_source=chatgpt.com "Baloo - baloo Directory Reference"
+[8]: https://modelcontextprotocol.io/specification/draft?utm_source=chatgpt.com "Specification - Model Context Protocol"
+[9]: https://docs.kde.org/stable5/en/plasma-desktop/kcontrol/baloo/index.html?utm_source=chatgpt.com "File Search"
+[10]: https://api.kde.org/frameworks/kwallet/html/dir_f0405f97baa27f67ccc82dafaed9dd67.html?utm_source=chatgpt.com "KWallet - kwallet Directory Reference"
+[11]: https://api.kde.org/kconfig-index.html?utm_source=chatgpt.com "KConfig"
+[12]: https://apps.kde.org/nn/neochat/?utm_source=chatgpt.com "NeoChat - KDE-program"
+[13]: https://api.kde.org/kdepim/kontactinterface/html/index.html?utm_source=chatgpt.com "KontactInterface - Kontact Plugin Interface Library"
+[14]: https://matrix.org/docs/matrix-concepts/end-to-end-encryption/?utm_source=chatgpt.com "Matrix.org - End-to-End Encryption implementation guide"
+[15]: https://api.kde.org/kdepim/kontactinterface/html/classKontactInterface_1_1Plugin.html?utm_source=chatgpt.com "KontactInterface - KontactInterface::Plugin Class Reference"
+
