Knowledge OS Stage 1 — wiki + ingest + MCP
Context
Aspire org knowledge sits scattered across 12+ surfaces: Hubdoc, Xero, GitLab, Notion, Slack history, Google Drive, individual brains. Asking "who's our backup produce supplier for Chanya?" or "where did we decide on Stripe vs Zinga Pay?" requires manual hunting. KO Stage 1 builds a queryable wiki backed by an Obsidian vault + Postgres index, fed by both human writes and an OCR ingest pipeline. iZinga is the platform brand; KO is its first product.
Detail
Goal
A markdown-based wiki where any Aspire agent or human can answer business questions in <5 seconds via either Obsidian quick-switcher or MCP knowledge_query.
Architecture
graph TD
A["Agents — Claude Code / OpenClaw"] -->|MCP| B["mcp-bridge :8082<br/>FastMCP + JWT"]
H["Humans"] -->|Obsidian edits| V["Vault — git repo<br/>markdown source of truth"]
B -->|HTTP| W["wiki-api :8081<br/>FastAPI"]
W --> V
W --> P[("Postgres + pgvector<br/>index")]
I["Raw docs<br/>PDF / image / transcript"] -->|POST /ingest/upload| O["worker-ocr<br/>async consumer"]
O -->|native PDF first,<br/>then LLM vision| G["Aspire LLM Gateway<br/>llm.aspiredigital.group"]
O -->|writes markdown + commits| V
V -->|git push/pull| GL["GitLab<br/>aspire/knowledge-os-vault"]
classDef src fill:#715EE3,color:#fff,stroke:#291F50;
class V src;
Components
| Component | Status | Notes |
|---|---|---|
Obsidian vault (aspire/knowledge-os-vault) | ✅ live | git-backed, 8 brand namespaces + _meta + _inbox + _templates |
| Obsidian Git plugin (auto-commit 5min, auto-pull 10min) | ✅ live | Verified 2026-05-17 |
| Templater (6 page-type templates) | ✅ live | Hotkey Cmd+Shift+T |
Dataview dashboard (_meta/dashboard.md) | ✅ live | 7 live queries |
wiki-api (FastAPI, port 8081) | ✅ built | Postgres index + REST endpoints |
mcp-bridge (FastMCP, port 8082) | ✅ built | 6 tools: health, knowledge_query, get_page, ingest, update_page, lint_page |
worker-ocr (async PDF → vault) | ✅ built | Vision via claude-haiku-4-5 (qwen-3.6-omni broken upstream); native PDF first |
ko-knowledge MCP wired into Claude Code | ✅ live | Verified end-to-end at 3 layers 2026-05-16 |
| Production VPS deploy on OpenClaw | ⏸ pending | when: manual gate in .gitlab-ci.yml; blast radius 28 agents |
| Aspire LLM Gateway integration | ✅ live | Virtual key knowledge-os smoke-tested 2026-05-19 |
Milestones
- [x] T0 — Vault repo + Obsidian setup (2026-04-19)
- [x] T1–T6 — Engine scaffold + wiki-api + mcp-bridge + worker-ocr (April–May 2026)
- [x] T7d — Ingest fallback chain (pdftotext → pdfplumber → PyMuPDF → AI vision) (2026-05-12)
- [x] T5 — Vault round-trip (human + agent writes both reach
origin/mainwith distinguishable authorship) (2026-05-16) - [x] T5b — Obsidian.app UX layer + 3 plugins configured (2026-05-17)
- [x] Gateway migration — Engine uses Aspire LLM Gateway virtual key (2026-05-17)
- [ ] T0 stress test — 5+ hand-written Chanya supplier pages (in progress)
- [ ] Production deploy — Manual click in GitLab CI when smoke evidence is strong
- [ ] Real PDF batch ingest — process 10-20 real Aspire documents through worker-ocr
Stage 2 / Stage 3 (out of scope this phase)
- Stage 2 = LightRAG semantic over vault when query volume > 1k/day OR pure FTS demonstrably insufficient
- Stage 3 = per-tenant isolated indexes for iZinga's commercial product
Open questions
- Content ownership post-seeding — who maintains vault quality day-to-day?
- cloud-first.ai data retention policy — confirmed on-prem for operational data routing?
- Pilot brand for first real load — Chanya remains the default per original spec.
Provenance
Full architecture: aios-workspace/engineering/projects/izinga/ARCHITECTURE.md. Engine repo: gitlab.dssc.co.th/aspire/infrastructure/knowledge-os. Vault repo: gitlab.dssc.co.th/aspire/knowledge-os-vault.
Related
🔗 Relationships
graph LR
knowledge_os_stage_1["knowledge-os-stage-1"]:::self
knowledge_os_stage_1 --> aspire_llm_gateway_only_egress["aspire-llm-gateway-only-egress"]
knowledge_os_stage_1 --> use_postgresql_by_default["use-postgresql-by-default"]
knowledge_os_stage_1 --> aspire_llm_gateway["aspire-llm-gateway"]
knowledge_os_stage_1 --> aspire_brand_architecture["aspire-brand-architecture"]
classDef self fill:#715EE3,color:#fff,stroke:#291F50;