Personal Knowledge Operating System (PKOS) Design

planactive

Architecture Decision Record for the Personal Knowledge Operating System — a living, structured, bidirectional knowledge system replacing MASTER_REFERENCE.md as a static document.

Problem solved: Knowledge was scattered across MASTER_REFERENCE.md, 25+ repo READMEs, Notion (unlinked), OTHER/workspace/docs, and Gemini GEMINI.md session notes. No unified, queryable, cross-linked, auto-maintained record of projects, tools, plans, or identity.

Intended outcome: Feed any Markdown document → AI extracts records → DB grows → MASTER_REFERENCE auto-regenerates → Notion syncs → edits in Notion flow back → perpetual refinement loop.

Architecture (hybrid local + Notion):

  • Local db/ as source of truth (versionable, offline, grep-able)
  • Notion as rich editing UI (4 databases: KB Projects, KB Assets, KB Profile, KB Plans)
  • Bidirectional sync via LocalFile property as join key
  • 7-skill Claude Code plugin: extract, ingest, develop, consolidate, sync-push, sync-pull, query

Key design decisions: | Decision | Choice | Rationale | |---|---|---| | Storage | Hybrid (local=truth, Notion=UI) | Local is versionable + offline; Notion is rich editing interface | | Entity types | 4 (project, asset, profile, plan) | "Assets" absorbs tools/extensions/prompts/configs — anything used rather than built | | Sync key | LocalFile property in Notion | File paths are stable; names can change | | Conflict strategy | Per-record user choice | Automated resolution causes data loss | | Aggregation | extension-set / mcp-server-set records | 103 individual extension records = 103 files; one aggregated record is realistic | | HUMAN markers | <!-- HUMAN --> ... <!-- /HUMAN --> | Escape hatch for manually authored sections surviving consolidation |

Plugin location: C:\Users\mesha\Configs\plugins\local\knowledge\ — matches existing 4-plugin pattern.