Outline future plans
This commit is contained in:
Χγφτ Kompanion
parent
f71b2ef510
commit
fd289edded
|
|
@ -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**.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -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"
|
||||
|
||||
Loading…
Reference in New Issue