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"