# CyberBrain26 Knowledge Plane Completion Plan

**status:** draft (requires owner approval before any src/ or tests/ changes)
**project:** CyberBrain26-v4
**version:** v3
**owner:** orchestrator
**last_updated:** 2026-11-04
**phase:** F2 → F3 boundary (complete knowledge plane end-to-end)

---

## 1. Souhrn v jedné větě

Dokončíme knowledge plane (MemoryService + CLI knowledge command) tak, aby fungoval kompletní end-to-end pipeline s automatickou klasifikací, temporální validitou (stale-fact prevence) a knowledge grafovou navigací, inspirováno ByteRover, MemGraphRAG a MemStrata.

---

## 2. Stav aktuální (ověřeno)

### Co existuje a funguje

| Komponenta | Soubor | Stav | Důkaz |
|---|---|---|---|
| MemoryService | `src/cyberbrain26/knowledge_plane/memory_service.py:46-461` | Implementováno | 461 řádků, plný pipeline |
| CLI knowledge | `src/cyberbrain26/cli.py:590-722` | PARTIAL | `ingest`/`search`/`kg1` akce existují |
| Klasifikace (LLM) | `src/cyberbrain26/knowledge_plane/classifier.py` | LIBRARY-ONLY | `LLMClassifier` volá Ollama, ale není voláno z `register_file` konzistentně |
| KnowledgeNavigator | `src/cyberbrain26/knowledge_plane/navigation.py:36-120` | PARTIAL | Topic/tag index, žádný graf, žádná temporální navigace |
| DeduplicationEngine | `src/cyberbrain26/knowledge_plane/deduplication.py` | WORKING | Hash + URL dedup, semantic vyžaduje Ollama |
| Tests (independent) | `tests/test_independent_memory.py:389` | WORKING | 21 testů, bez externích služeb |
| Tests (integration) | `tests/test_knowledge_integration.py:237` | PARTIAL | Vyžaduje Ollama/LanceDB, skipuje se bez nich |

### Co chybí (mezery proti F2 completu)

1. **Automatická klasifikace při `register_file`** — volá se `self._classify_document` ale není integrována do navigátoru s entity/topic/intent z klasifikátoru konzistentně.
2. **Temporal validity (MemStrata)** — žádná kontrola zastaralých faktů, žádný bi-temporal ledger (`valid_from`, `valid_to`, `superseded_by`).
3. **Knowledge graf (MemGraphRAG pattern)** — žádné entity-relationship propojení, žádné traversal, žádné multi-agent konfliktní risolvence.
4. **CLI rozšíření** — chybí `--auto-classify`, `--validate-stale`, `--timeline`, `--graph`, `--traversal` volby.
5. **Export/import** — žádný způsob, jak knowledge vyexportovat/importovat.
6. **Enterprise security** — žádná PII detekce, žádná sensitivity redaction při ingestu.

---

## 3. Výzkum (2026, deep-web research) — all 4 subagents completed

### 3.1 ByteRover — agent-native memory (nejvyšší priority)
- **Zdroj:** arXiv:2604.01599 + byterover.dev docs (přístup 2026-11-04)
- **Architektonický vzor:** Agent-native memory — LLM kurátuje vlastní paměť. Context Tree v markdown souborech `.brv/context-tree/`, 3 úroveň: Domain > Topic > Subtopic + 5 komponent (relation set, raw concept, narrative, snippets, lifecycle metadata).
- **Benchmarky:** LoCoMo 92.2% / LongMemEval-S 92.8% — nejvyšší na trhu.
- **5-tier retrieval:** Tier 0 (exact cache ~0ms) → Tier 4 (agentic loop 8-15s). Tiers 0-2 bypass LLM úplně.
- **Git-like branch/merge:** 16 příkazů `brv vc ...` nad markdown soubory, full diff/merge conflict support.
- **ToolsSDK sandbox:** 5 atomic operací (ADD/UPDATE/UPSERT/MERGE/DELETE) s `reason` polem pro audit trail.
- **Použití v plánu:** Kontextový strom KnowledgeDocument.metadata → `.md` soubory pod `data/knowledge/context-tree/`, 5-tier retrieval enhancement do `semantic_search`, branch/merge pro knowledge versioning.

### 3.2 MemGraphRAG — memory-based multi-agent GraphRAG
- **Zdroj:** arXiv:2606.00610, KDD 2026 (přístup 2026-11-04); GitHub: https://github.com/XMUDeepLIT/MemGraphRAG (MIT)
- **Architektura:** Tři agenti (Extraction, Conflict Detection, Conflict Resolution) + Shared Memory (Ontology + Fact + Passage layers).
- **Memory-aware retrieval:** Multi-layer filtering z všech 3 paměťových vrstev, Strukturální node inicializace s hub suppression, Personalized PageRank pro globally relevant context.
- **Performance:** 59.25% gener accuracy, +38-43% relativní zisk oproti baselines. Fact retrieval 89.56%, complex reasoning 88.53%.
- **Klíčové poznatky:** Není to agent memory system (jako Mem0/Zep/Hindsight) — je to GraphRAG framework. Baselines jsou GraphRAG varianty, ne agent memory služby.
- **Použití v plánu:** Memory-guided filtering nad existujícím KnowledgeVectorStore (short-term), NE-full multi-agent orchestration rewrite (long-term, out of F2 scope).

### 3.3 MemStrata — temporální validita (kritické pro enterprise)
- **Zdroj:** arXiv:2606.26511 (přístup 2026-11-04); MemStrata.dev live demo
- **Architektura:** Bi-temporal ledger s poli `valid_from`, `valid_to`, `superseded_by`. Deterministické (subject, relation, object) supersedence pravidlo. Žádný similarity threshold, žádné LLM volání pro stale fact retirement.
- **Měření:** RAG stale-fact-error rate 15-40% vs MemStrata ~0%. Retrieval latency ~2.1s vs 16-18s pro LLM-reranking baselines.
- **Marker-free evaluation:** Fakt jsou textově identické kromě změněné hodnoty.
- **Použití v plánu:** Fáze B — přidání temporal validation do `KnowledgeDocument` (polí `valid_from`/`valid_to`), deterministická kontrola v `KnowledgeNavigator`, CLI `--validate-stale` volba.

### 3.4 H-Mem — hybrid multi-dimensional memory
- **Zdroj:** arXiv:2603.27910v1 (přístup 2026-11-04); ACL findings 2026
- **Architektura:** Tři dimenze paměti: Fact Nodes, Temporal Nodes, Semantic Nodes. Dva režimy retrievalu: Sekvenční (semantic → temporal) a Paralelní. Mode Controller dynamicky volí režim podle dotazu.
- **Comparison:** Lepší cover factual recall než single-dimensionální systémy, ale složitější na implementaci.
- **Použití v plánu:** Fáze C — volitelné rozšíření pro multi-dimenzionální retrieval (po F2 completion).

## 3.1 Shrnutí vzorů pro CyberBrain26

| Vzor | Co převzít | riziko | časová osa |
|---|---|---|---|
| **ByteRover Context Tree** | Markdown knowledge storage, 5-tier retrieval, branch/merge | Nízké (pouze struktura, ne LLM) | Fáze A (měsíc 1) |
| **MemGraphRAG filtering** | Memory-aware retrieval enhancement | Nízké (enhancement, ne rewrite) | Fáze A (stežné s ByteRover) |
| **MemStrata temporal** | Bi-temporal ledger, stale-fact prevence | Nízké (metadata pole + kontrola) | Fáze A (první úkol) |
| **H-Mem multi-dim** | Fact/temporal/semantic režimy | Střední (rozšíření navigátoru) | Fáze C (po F2) |

## 4. Upravené fáze implementace

**Fáze A — Core features (Měsíc 1) — upraveno na základě výzkumu**

| Úkol | Popis | Soubory | `declared_actions` | Vzorec |
|---|---|---|---|---|
| A1 | Přidat `auto_classify` do `register_file` — ukládat `topic`, `tags`, `entities`, `intent` z `LLMClassifier` do `KnowledgeDocument.metadata` a navigátoru | `memory_service.py:122-222`, `classifier.py` | `read_file`, `execute_python` | ByteRover Classifier pattern + prompt schema z `classifier.py:32-46` |
| A2 | Přidat temporální pole do `KnowledgeDocument`: `valid_from`, `valid_to`, `superseded_by` (MemStrata) | `contracts.py:72-86` | `read_file`, `write_file` | MemStrata bi-temporal ledger |
| A3 | Přidat `TemporalValidator` do `KnowledgeNavigator` — deterministická kontrola zastaralých faktů (MemStrata) | `navigation.py` | `read_file`, `write_file` | MemStrata deterministic supersession |
| A4 | Rozšířit CLI `knowledge` o `--auto-classify` a `--validate-stale` volby | `cli.py:615-722` | `read_file`, `write_file`, `execute_shell` | ByteRover CLI + MemStrata CLI |
| A5 | Napsat integrační testy pro A1-A4 (full pipeline s klasifikací a temporální validací) | `tests/test_knowledge_temporal.py`, `tests/test_knowledge_classification.py` | `read_file`, `write_file` | Unit testy pro nové features |

**Fáze B — Knowledge graf & enterprise features (Měsíc 2)**

| Úkol | Popis | Soubory | `declared_actions` | Vzorec |
|---|---|---|---|---|
| B1 | Rozšířit `KG1Node` o entity-relationship tracking (MemGraphRAG extraction agent pattern) | `contracts.py:102-112`, `memory_service.py` | `read_file`, `write_file` | MemGraphRAG extraction agent třída |
| B2 | Přidat `--graph` a `--traversal` CLI volby (hledání sousedů, cesty mezi entitami) | `cli.py` | `read_file`, `write_file` | ByteRover graph traversal |
| B3 | PII/sensitivity detekce a redaction při ingestu (expandní classifier) | `classifier.py`, `memory_service.py` | `read_file`, `write_file` | Enterprise security pattern |
| B4 | Export/import knowledge (JSON/Markdown, ByteRover Context Tree pattern) | `memory_service.py` | `read_file`, `write_file` | ByteRover export/import |
| B5 | Testy pro graf, PII, export/import | nové testy | `read_file`, `write_file` |  |

**Fáze C — Optimalizace & hardening (Měsíc 3)**

| Úkol | Popis | Soubory | `declared_actions` | Vzorec |
|---|---|---|---|---|
| C1 | Paralelní zpracování batch operací | `memory_service.py`, `deduplication.py` | `read_file`, `write_file`, `execute_python` | ByteRover batch curate |
| C2 | Caching strategie pro embeddings a search | `embedding_service.py`, `vector_store.py` | `read_file`, `write_file` | 5-tier retrieval enhancement |
| C3 | Advanced monitoring a metriky | `cli.py`, `memory_service.py` | `read_file`, `write_file` |  |
| C4 | Performance benchmarky (LongMemEval-S) | `tests/test_knowledge_benchmark.py` | `read_file`, `write_file` |  |

## 5. Kritéria přijetí (upravena)

1. Všechny CLI `knowledge` akce fungují end-to-end: `ingest --auto-classify`, `search --validate-stale`, `kg1`
2. Temporal validace funguje: MemStrata pattern, žádné zastaralé fakt ve výsledcích searchu — stale-fact-error ~0%
3. Klasifikace accuracy >85% (měřeno na test sadě)
4. Recall >90% na LongMemEval-S kompatibilní test sadě (5-tier retrieval enhancement)
5. 100% test coverage pro všechny nové features (fáze A + B první verze)
6. Gate 1/2 zelené (pytest, ruff, mypy) před a po každé fázi
7. Žádné citlivé údaje (PII) neprojdou ingestem bez redaction

## 6. Rizika a mitigace (aktualizováno)

| Riziko | Dopad | Mitigace |
|---|---|---|
| Ollama/LanceDB nedostupné | Vysoké | Testy graceful skip, nezávislé testy `test_independent_memory.py` pokrýjí bez-externí komponenty |
| Komerční licence MemStrata | Středné | Použití pouze open-source vzoru z arXiv paperu (nekomerční použití) |
| `gate3-auditor` typ unavailable | Středné | Gate 3 přes `verifier` deterministický běh + nezávislý model |
| Pracovní strom není commitnut | Nízké | Všechna schválení před zápisem do src/ |

## 7. Sekvence schválení (D6 invariant)

Pro každou fázi:
1. Orchestrátor připraví diff → **schválení vlastníka** (vyžadováno pro `src/`, `tests/`, `.kilo/kilo.jsonc`, `pyproject.toml`)
2. `implementer` aplikuje diff (po schválení)
3. `tester` Gate 2 (pytest, ruff, mypy)
4. `code-reviewer` revize diffu
5. `verifier` nezávislá verifikace tvrzení
6. `documenter` aktualizace `docs/` + `CHANGELOG.md`

## 8. Implementation milestones (co udělám první)

1. **Den 1-3:** A1-A3 — přidat auto-klassifikaci do `register_file`, přidat temporální pole do `KnowledgeDocument`, přidat TemporalValidator do navigátoru
2. **Den 4-7:** A4 — rozšířit CLI o `--auto-classify` a `--validate-stale`, napsat základní testy
3. **Den 8-10:** Schválení vlastníka + implementer aplikace diffu
4. **Den 11-14:** Tester Gate 2 + code-reviewer + verifier
5. **Den 15-20:** Dokumenter aktualizace, CHANGELOG.md

**První akce:** Spustit `bash` příkaz pro ověření aktuálního stavu a připravit první diff k recenzi.

### MemGraphRAG — memory-based multi-agent GraphRAG
- **Zdroj:** arXiv:2606.00610, KDD 2026 přijato (přístup 2026-11-04)
- **Klíčový vzor:** Společnost spolupracujících agentů se sdílenou pamětí, globální kontext při extrakci grafu, memory-aware hierarchické retrieval, logická konfliktní risolvence,strukturální propojenost korpusu.
- **Použití v plánu:** Knowledge graf nad existujícím KnowledgeNavigator, entity-relationship uzly, multi-perspektivní retrieval.

### MemStrata — temporální validita (nejdůležitější pro enterprise)
- **Zdroj:** arXiv:2606.26511 (přístup 2026-11-04)
- **Klíčový vzor:** Deterministické (subject, relation, object) pravidlo supersedence nad bi-temporálním ledgerem (`valid_from`, `valid_to`, `superseded_by`), žádný similarity threshold, žádný LLM volání pro odchod zastaralých faktů, stale-fact-error rate RAG 15-40% vs MemStrata ~0%, retrieval latency ~2.1s vs 16-18s LLM-reranking.
- **Použití v plánu:** Temporal validace v `KnowledgeNavigator` a `MemoryService`, bi-temporal metadata v `KnowledgeDocument`.

---

## 4. Implementační fáze

### Fáze A — Core features (Měsíc 1)

| Úkol | Popis | Soubory | `declared_actions` |
|---|---|---|---|
| A1 | Přidat `auto_classify` pipeline do `MemoryService.register_file()` — ukládat `topic`, `tags`, `entities`, `intent` z `LLMClassifier` do dokument metadata a navigátoru | `memory_service.py`, `classifier.py` | `read_file`, `execute_python`, `access_network` |
| A2 | Rozsírit `KnowledgeDocument` o temporální pole: `valid_from`, `valid_to`, `superseded_by` (MemStrata pattern) | `contracts.py` | `read_file`, `write_file` |
| A3 | Přidat `TemporalValidator` do `KnowledgeNavigator` — deterministická kontrola zastaralých faktů (MemStrata) | `navigation.py` | `read_file`, `write_file` |
| A4 | Rozšířit CLI `knowledge` o `--auto-classify` a `--validate-stale` volby | `cli.py` | `read_file`, `write_file`, `execute_shell` |
| A5 | Napsat integrační testy pro A1-A4 (full pipeline s klasifikací a temporální validací) | `tests/test_knowledge_temporal.py`, `tests/test_knowledge_classification.py` | `read_file`, `write_file` |

### Fáze B — Knowledge graf & enterprise features (Měsíc 2)

| Úkol | Popis | Soubory | `declared_actions` |
|---|---|---|---|
| B1 | Implementovat entity-relationship uzly nad `KG1Node` (MemGraphRAG) | `navigation.py`, `memory_service.py` | `read_file`, `write_file` |
| B2 | Přidat `--graph` a `--traversal` CLI volby (hledání sousedů, cesty mezi entitami) | `cli.py` | `read_file`, `write_file` |
| B3 | Přidat PII/sensitivity detekci a redaction při ingestu | `classifier.py`, `memory_service.py` | `read_file`, `write_file` |
| B4 | Export/import knowledge (JSON/Markdown formát, ByteRover Context Tree pattern) | `memory_service.py` | `read_file`, `write_file` |
| B5 | Testy pro graf, PII, export/import | `tests/test_knowledge_graph.py`, `tests/test_knowledge_pii.py` | `read_file`, `write_file` |

### Fáze C — Optimalizace & hardening (Měsíc 3)

| Úkol | Popis | Soubory | `declared_actions` |
|---|---|---|---|
| C1 | Paralelní zpracování batch operací (deduplikace, klasifikace) | `memory_service.py`, `deduplication.py` | `read_file`, `write_file`, `execute_python` |
| C2 | Caching strategie pro embeddings a search | `embedding_service.py`, `vector_store.py` | `read_file`, `write_file` |
| C3 | Pokročilé monitoring a metriky (latency, recall, throughput) | `cli.py`, `memory_service.py` | `read_file`, `write_file` |
| C4 | Performance benchmarky (LongMemEval-S kompatibilní) | `tests/test_knowledge_benchmark.py` | `read_file`, `write_file` |

---

## 5. Kritéria přijetí (acceptance criteria)

1. Všechny CLI `knowledge` akce fungují end-to-end: `ingest --auto-classify`, `search --validate-stale`, `kg1`
2. Temporal validace funguje: MemStrata pattern, žádné zastaralé fakt ve výsledcích searchu
3. Klasifikace accuracy >85% (měřeno na test sadě)
4. Recall >90% na LongMemEval-S kompatibilní test sadě
5. 100% test coverage pro všechny nové features (fáze A + B)
6. Gate 1/2 zelené (pytest, ruff, mypy) před a po každé fázi
7. Žádné citlivé údaje (PII) neprojdou ingestem bez redaction

---

## 6. Rizika a blokery

| Riziko | Dopad | Mitigace |
|---|---|---|
| Ollama/LanceDB nedostupné v testovacím prostředí | Vysoký | Testy skipují graceful, 독립né testy (test_independent_memory) pokrývají bez-externí komponenty |
| Komerční licence MemStrata (kontakt: memstrata@gmail.com) | Střední | Použití pouze open-source vzoru z arXiv paperu, ne comercíální služby |
| `gate3-auditor` typ není v Task toolu dostupný | Střední | Gate 3 přes `verifier` s deterministickým během |
| Pracovní strom není commitnut (necommitnuté změny) | Nízký | Všechna schválení před zápisem do src/ |

---

## 7. Sekvence schválení (D6 invariant)

Pro každou fázi:
1. Orchestrátor připraví diff → **schválení vlastníka** (vyžadováno pro `src/`, `tests/`, `.kilo/kilo.jsonc`, `pyproject.toml`)
2. `implementer` aplikuje diff (po schválení)
3. `tester` Gate 2 (pytest, ruff, mypy)
4. `code-reviewer` revize diffu
5. `verifier` nezávislá verifikace tvrzení
6. `documenter` aktualizace `docs/` + `CHANGELOG.md`

---

## 8. Poznámky k výzkumu

Všechny výzkumné tvrzení jsou podloženy URL + datem přístupu (viz sekce 3). Žádné tvrzení není prezentováno jako `[OVĚŘENO]` bez `file:line` důkazu v tomto repu. Výzkumné vzory (ByteRover, MemGraphRAG, MemStrata) jsou inspirace, ne přímé importy kódu.