Knowledge Hub simplification plan

Short answer

Do not restart in a fresh repo.

Knowledge Hub's core foundation is already close to the right shape: - markdown files on disk - git-backed history - a lightweight web/API layer for remote agents - persistent wiki-style documents - raw sources kept separate from compiled knowledge

The main issue is not the substrate. The main issue is that the project accumulated more workflows and product language than the core idea strictly required.

The right move is a soft reset in framing and defaults, not a rewrite.

The clarified product idea

Knowledge Hub should be framed primarily as:

A web-accessible, self-hosted, markdown-first wiki for humans and agents.

Everything else should be treated as either: - a convenience layer, or - an advanced workflow

The core requirement is simple: - any agent, local or remote, should be able to read and write the shared knowledge base over HTTP - the knowledge base should remain human-readable and git-versioned

What already matches the core idea

The current codebase already supports the important pieces:

1. Raw sources

• sources/
• attachments/

2. Persistent wiki

• markdown files under vault folders
• canonical folders like lessons/, playbooks/, projects/, references/
• captures and session notes under inbox/ and journal/

3. Remote agent access

• HTTP read/write/search surface
• bearer-token write protection

4. Durable history

• git-backed changes in persistent storage

This means the codebase is fundamentally pointed in the right direction.

Where complexity crept in

The complexity is mostly in the workflow layer, not the storage model.

Examples of higher-level workflows that are useful but not essential to the core story: - compile - promotions - curation suggestions - audit - manifests - some UI/product framing around these helpers

These should remain available, but they should not define the system for new users or for day-to-day use.

Recommended reframing

Tier 1: default workflow

This should be the everyday path: 1. search before writing 2. capture raw notes or source material 3. read existing wiki pages 4. append or update durable pages 5. keep a session log 6. promote stable knowledge into canonical folders when useful

For most real usage, this is enough.

Tier 2: helpful helpers

These improve usability but should stay secondary: - browser UI - tags - backlinks - history - activity feed

Tier 3: advanced workflows

These are optional power tools: - compile - promotion workflows as a formal operation - curation suggestions - audit - generated manifests

Product wording change

Use simpler language in docs and explanations.

Prefer: - shared markdown wiki - web-accessible for agents - persistent knowledge base - git-backed history

De-emphasize: - substrate-heavy wording when not needed - too many named workflows in the first explanation - product complexity before the core use case is clear

Search expectations

The current search implementation is acceptable, but it should be described honestly.

What it does well

• exact keyword retrieval
• project memory lookup
• title/body matching
• filtering by vault, type, and tag

What it does not do well yet

• typo tolerance
• fuzzy matching
• semantic retrieval
• automatic recall from tags unless tag filters are used explicitly

This is not a reason to redesign. It only means search should be treated as a useful helper rather than the essence of the product.

What not to do

Do not: - start over just to simplify the narrative - replace markdown with a database-only model - throw away git-backed history - remove web access for remote agents - overreact to helper-feature complexity by deleting useful primitives

What to do next

1. Re-center docs

• make the README tell the simpler story first
• treat advanced workflows as optional

2. Use a canonical operating model

For most sessions, use only: - search - capture - read - put/patch - history - session log

3. Keep a rolling project memory

Use a doc like: - projects/knowledge-hub/session-log.md

This keeps the system aligned with the compounding-wiki idea.

4. Promote only durable knowledge

Use lessons/, playbooks/, and references/ for reusable outputs. Do not force formal workflows for every interaction.

5. Improve search incrementally, not architecturally

Good future upgrades would be: - include tags in FTS text - add prefix/fuzzy fallback - add semantic search only if truly needed later

Final recommendation

Knowledge Hub does not need a rewrite.

It needs: - a simpler explanation - a clearer default workflow - a stronger distinction between core behavior and advanced helpers

The foundation is already compatible with the original idea: a persistent markdown wiki that agents can maintain over time and that humans can inspect and trust.

Status update — 2026-04-08

Wave 1 has landed: - docs and guidance now tell the simpler wiki-first story first - minimal UI copy now reinforces the default workflow - backend was intentionally left unchanged in this wave because the substrate was already aligned

Validated with the full server test suite (28 passed).