From 66cbcc4957021dddf27dae01552f9d13c5a9ae84 Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Sun, 5 Apr 2026 11:08:41 +1000 Subject: [PATCH 1/2] feat: add knowledge wiki schema Adds a new bundled schema for LLM-maintained knowledge wikis. Supports source_summary, concept, synthesis, personal, and index node types with a flat entity model, wikilinks for cross-referencing, aliases, and validation rules for provenance and coherence. Based on the pattern described in Karpathy's LLM Wiki (2026). --- schemas/knowledge_wiki.json | 204 ++++++++++++++++++++++++++++++++++++ 1 file changed, 204 insertions(+) create mode 100644 schemas/knowledge_wiki.json diff --git a/schemas/knowledge_wiki.json b/schemas/knowledge_wiki.json new file mode 100644 index 0000000..c1535e4 --- /dev/null +++ b/schemas/knowledge_wiki.json @@ -0,0 +1,204 @@ +{ + "$schema": "https://raw.githubusercontent.com/mindsocket/ost-tools/main/schemas/generated/_ost_tools_schema_meta.json", + "$id": "ost-tools://knowledge_wiki", + "title": "Knowledge Wiki", + "description": "Lightweight schema for LLM-maintained knowledge wikis. Supports source summaries, concept pages, syntheses, and personal notes. Designed for compounding knowledge bases where the LLM creates and maintains wiki pages from raw sources.\n\nFlat entity model — no hierarchy, no required parent links. Wikilinks between any pages are valid for arbitrary cross-referencing. The schema validates structure and provenance; it does not constrain meaning.\n\nBased on the pattern described in Karpathy's LLM Wiki (2026).", + "$metadata": { + "aliases": { + "study": "source_summary", + "article": "source_summary", + "paper": "source_summary", + "research": "source_summary", + "note": "personal", + "journal": "personal", + "framework": "concept", + "model": "concept", + "chat_transcript": "source_summary", + "chat-transcript": "source_summary" + }, + "rules": [ + { + "id": "source-has-origin", + "category": "validation", + "description": "Source summaries should reference their origin via url, author, or book field", + "type": "source_summary", + "check": "current.url != null or current.author != null or current.book != null" + }, + { + "id": "synthesis-references-sources", + "category": "coherence", + "description": "Syntheses should reference at least one contributing source in their sources array", + "type": "synthesis", + "check": "$exists(current.sources) and $length(current.sources) >= 1" + }, + { + "id": "concept-has-summary", + "category": "best-practice", + "description": "Concept pages should have a short summary for index discoverability", + "type": "concept", + "check": "$exists(current.summary) and $length(current.summary) > 0" + } + ] + }, + "oneOf": [ + { + "type": "object", + "description": "A processed summary of a raw source (article, paper, book, video, thread, podcast, etc.). Captures key information from the source in structured form with provenance.", + "allOf": [ + { "$ref": "ost-tools://_ost_tools_base#/$defs/baseNodeProps" }, + { "$ref": "ost-tools://_ost_tools_base#/$defs/ostEntityProps" } + ], + "properties": { + "type": { "const": "source_summary" }, + "url": { + "type": "string", + "description": "URL of the original source" + }, + "author": { + "type": "string", + "description": "Author or creator of the source" + }, + "book": { + "type": "string", + "description": "Book title and author if the source is a book" + }, + "published_date": { + "type": "string", + "description": "Original publication date (ISO 8601 or natural language)" + }, + "source_type": { + "type": "string", + "description": "Kind of source material. Free-form — common values include article, paper, book, video, podcast, thread, substack, tweet, website, chat_transcript. Not enum-constrained to allow evolving vocabulary." + }, + "sources": { + "type": "array", + "items": { "type": "string" }, + "description": "Wikilinks to other source pages that this one references or extends" + } + }, + "required": ["type"], + "additionalProperties": true, + "examples": [ + { + "type": "source_summary", + "title": "Study - Glutamate buildup and cognitive fatigue (Dr Dominic Ng)", + "author": "Dr Dominic Ng", + "url": "https://www.brainhealthdecoded.com/p/how-to-stop-wasting-your-evenings", + "source_type": "substack", + "tags": ["adhd", "executive-function", "cognitive-fatigue"], + "status": "active" + } + ] + }, + { + "type": "object", + "description": "A concept or entity page — defines and frames a specific idea, mechanism, model, or domain term. May draw from multiple sources. The building blocks of the wiki's knowledge graph.", + "allOf": [ + { "$ref": "ost-tools://_ost_tools_base#/$defs/baseNodeProps" }, + { "$ref": "ost-tools://_ost_tools_base#/$defs/ostEntityProps" } + ], + "properties": { + "type": { "const": "concept" }, + "sources": { + "type": "array", + "items": { "type": "string" }, + "description": "Wikilinks to source_summary pages that contributed to this concept" + }, + "related": { + "type": "array", + "items": { "type": "string" }, + "description": "Wikilinks to related concept or synthesis pages" + } + }, + "required": ["type"], + "additionalProperties": true, + "examples": [ + { + "type": "concept", + "title": "Executive function", + "summary": "A set of cognitive processes including inhibitory control, working memory, and cognitive flexibility that enable goal-directed behaviour", + "tags": ["adhd", "neuroscience", "cognition"], + "status": "active" + } + ] + }, + { + "type": "object", + "description": "A synthesis page — connects multiple concepts and sources into a coherent model, framework, or thesis. The highest-value pages in a knowledge wiki. Must reference contributing sources.", + "allOf": [ + { "$ref": "ost-tools://_ost_tools_base#/$defs/baseNodeProps" }, + { "$ref": "ost-tools://_ost_tools_base#/$defs/ostEntityProps" } + ], + "properties": { + "type": { "const": "synthesis" }, + "sources": { + "type": "array", + "items": { "type": "string" }, + "description": "Wikilinks to source_summary or concept pages that this synthesis draws from" + }, + "related": { + "type": "array", + "items": { "type": "string" }, + "description": "Wikilinks to related pages" + } + }, + "required": ["type"], + "additionalProperties": true, + "examples": [ + { + "type": "synthesis", + "title": "System 1/System 2 and the AuDHD Operating System", + "summary": "How Kahneman's framework explains interview freeze, organizational fatigue, and AI cognitive crush in AuDHD", + "sources": ["[[Study - Glutamate buildup and cognitive fatigue]]", "[[ADHD modelling notes]]"], + "status": "active" + } + ] + }, + { + "type": "object", + "description": "Personal notes, journal entries, appointments, experiential records. Your own data about your journey — not sourced from external material.", + "allOf": [ + { "$ref": "ost-tools://_ost_tools_base#/$defs/baseNodeProps" }, + { "$ref": "ost-tools://_ost_tools_base#/$defs/ostEntityProps" } + ], + "properties": { + "type": { "const": "personal" }, + "date": { + "type": "string", + "description": "Date this entry was created or relates to" + } + }, + "required": ["type"], + "additionalProperties": true, + "examples": [ + { + "type": "personal", + "title": "ADHD diagnosis", + "date": "2023-10-15", + "tags": ["adhd", "diagnosis"], + "status": "active" + } + ] + }, + { + "type": "object", + "description": "The wiki index — a catalog of all pages with links, summaries, and metadata. Updated by the agent on ingest. Used as the primary navigation entry point.", + "allOf": [ + { "$ref": "ost-tools://_ost_tools_base#/$defs/baseNodeProps" }, + { "$ref": "ost-tools://_ost_tools_base#/$defs/ostEntityProps" } + ], + "properties": { + "type": { "const": "index" } + }, + "required": ["type"], + "additionalProperties": true, + "examples": [ + { + "type": "index", + "title": "index", + "status": "active" + } + ] + } + ] +} From 5a9776c931a097018548d315f3f248a43f168ded Mon Sep 17 00:00:00 2001 From: Roger Barnes Date: Sun, 5 Apr 2026 21:22:42 +1000 Subject: [PATCH 2/2] refactor: address PR review feedback on knowledge wiki schema MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename source_summary → source (canonical); source_summary becomes alias - Rename personal → note (canonical); remove personal alias - Remove framework, model, chat_transcript aliases - Remove source-has-origin rule; make url required on source type - Use wikilink $ref for all wikilink array items - Add local_copy property (wikilink) to source type - Split synthesis related → sources + concepts properties - Add relationship metadata entries for sources/concepts fields - Replace examples with generic design/UX domain content --- schemas/knowledge_wiki.json | 111 +++++++++++++++++++++--------------- 1 file changed, 64 insertions(+), 47 deletions(-) diff --git a/schemas/knowledge_wiki.json b/schemas/knowledge_wiki.json index c1535e4..9487040 100644 --- a/schemas/knowledge_wiki.json +++ b/schemas/knowledge_wiki.json @@ -2,28 +2,40 @@ "$schema": "https://raw.githubusercontent.com/mindsocket/ost-tools/main/schemas/generated/_ost_tools_schema_meta.json", "$id": "ost-tools://knowledge_wiki", "title": "Knowledge Wiki", - "description": "Lightweight schema for LLM-maintained knowledge wikis. Supports source summaries, concept pages, syntheses, and personal notes. Designed for compounding knowledge bases where the LLM creates and maintains wiki pages from raw sources.\n\nFlat entity model — no hierarchy, no required parent links. Wikilinks between any pages are valid for arbitrary cross-referencing. The schema validates structure and provenance; it does not constrain meaning.\n\nBased on the pattern described in Karpathy's LLM Wiki (2026).", + "description": "Lightweight schema for LLM-maintained knowledge wikis. Supports source pages, concept pages, syntheses, and notes. Designed for compounding knowledge bases where the LLM creates and maintains wiki pages from raw sources.\n\nFlat entity model — no hierarchy, no required parent links. Wikilinks between any pages are valid for arbitrary cross-referencing. The schema validates structure and provenance; it does not constrain meaning.\n\nBased on the pattern described in Karpathy's LLM Wiki (2026).", "$metadata": { "aliases": { - "study": "source_summary", - "article": "source_summary", - "paper": "source_summary", - "research": "source_summary", - "note": "personal", - "journal": "personal", - "framework": "concept", - "model": "concept", - "chat_transcript": "source_summary", - "chat-transcript": "source_summary" + "source_summary": "source", + "study": "source", + "article": "source", + "paper": "source", + "research": "source", + "journal": "note" }, - "rules": [ + "relationships": [ + { + "parent": "source", + "type": "source", + "field": "sources", + "fieldOn": "child", + "multiple": true + }, { - "id": "source-has-origin", - "category": "validation", - "description": "Source summaries should reference their origin via url, author, or book field", - "type": "source_summary", - "check": "current.url != null or current.author != null or current.book != null" + "parent": "source", + "type": "synthesis", + "field": "sources", + "fieldOn": "child", + "multiple": true }, + { + "parent": "concept", + "type": "synthesis", + "field": "concepts", + "fieldOn": "child", + "multiple": true + } + ], + "rules": [ { "id": "synthesis-references-sources", "category": "coherence", @@ -49,11 +61,15 @@ { "$ref": "ost-tools://_ost_tools_base#/$defs/ostEntityProps" } ], "properties": { - "type": { "const": "source_summary" }, + "type": { "const": "source" }, "url": { "type": "string", "description": "URL of the original source" }, + "local_copy": { + "$ref": "ost-tools://_ost_tools_base#/$defs/wikilink", + "description": "Wikilink to a local copy of the source (e.g. a saved PDF or clipped note)" + }, "author": { "type": "string", "description": "Author or creator of the source" @@ -68,31 +84,31 @@ }, "source_type": { "type": "string", - "description": "Kind of source material. Free-form — common values include article, paper, book, video, podcast, thread, substack, tweet, website, chat_transcript. Not enum-constrained to allow evolving vocabulary." + "description": "Kind of source material. Free-form — common values include article, paper, book, video, podcast, thread, substack, tweet, website. Not enum-constrained to allow evolving vocabulary." }, "sources": { "type": "array", - "items": { "type": "string" }, + "items": { "$ref": "ost-tools://_ost_tools_base#/$defs/wikilink" }, "description": "Wikilinks to other source pages that this one references or extends" } }, - "required": ["type"], + "required": ["type", "url"], "additionalProperties": true, "examples": [ { - "type": "source_summary", - "title": "Study - Glutamate buildup and cognitive fatigue (Dr Dominic Ng)", - "author": "Dr Dominic Ng", - "url": "https://www.brainhealthdecoded.com/p/how-to-stop-wasting-your-evenings", - "source_type": "substack", - "tags": ["adhd", "executive-function", "cognitive-fatigue"], + "type": "source", + "title": "The Design of Everyday Things - Don Norman", + "author": "Don Norman", + "url": "https://example.com/design-of-everyday-things", + "source_type": "book", + "tags": ["design", "ux", "psychology"], "status": "active" } ] }, { "type": "object", - "description": "A concept or entity page — defines and frames a specific idea, mechanism, model, or domain term. May draw from multiple sources. The building blocks of the wiki's knowledge graph.", + "description": "A concept or entity page — defines and frames a specific idea, mechanism, or domain term. May draw from multiple sources. The building blocks of the wiki's knowledge graph.", "allOf": [ { "$ref": "ost-tools://_ost_tools_base#/$defs/baseNodeProps" }, { "$ref": "ost-tools://_ost_tools_base#/$defs/ostEntityProps" } @@ -101,12 +117,12 @@ "type": { "const": "concept" }, "sources": { "type": "array", - "items": { "type": "string" }, - "description": "Wikilinks to source_summary pages that contributed to this concept" + "items": { "$ref": "ost-tools://_ost_tools_base#/$defs/wikilink" }, + "description": "Wikilinks to source pages that contributed to this concept" }, "related": { "type": "array", - "items": { "type": "string" }, + "items": { "$ref": "ost-tools://_ost_tools_base#/$defs/wikilink" }, "description": "Wikilinks to related concept or synthesis pages" } }, @@ -115,9 +131,9 @@ "examples": [ { "type": "concept", - "title": "Executive function", - "summary": "A set of cognitive processes including inhibitory control, working memory, and cognitive flexibility that enable goal-directed behaviour", - "tags": ["adhd", "neuroscience", "cognition"], + "title": "Affordance", + "summary": "A property of an object that signals how it can be used, first described by Gibson and popularised in design by Norman", + "tags": ["design", "ux"], "status": "active" } ] @@ -133,13 +149,13 @@ "type": { "const": "synthesis" }, "sources": { "type": "array", - "items": { "type": "string" }, - "description": "Wikilinks to source_summary or concept pages that this synthesis draws from" + "items": { "$ref": "ost-tools://_ost_tools_base#/$defs/wikilink" }, + "description": "Wikilinks to source pages this synthesis draws from" }, - "related": { + "concepts": { "type": "array", - "items": { "type": "string" }, - "description": "Wikilinks to related pages" + "items": { "$ref": "ost-tools://_ost_tools_base#/$defs/wikilink" }, + "description": "Wikilinks to concept pages this synthesis connects" } }, "required": ["type"], @@ -147,9 +163,10 @@ "examples": [ { "type": "synthesis", - "title": "System 1/System 2 and the AuDHD Operating System", - "summary": "How Kahneman's framework explains interview freeze, organizational fatigue, and AI cognitive crush in AuDHD", - "sources": ["[[Study - Glutamate buildup and cognitive fatigue]]", "[[ADHD modelling notes]]"], + "title": "Affordances and feedback loops in interface design", + "summary": "How Norman's affordance model and feedback principles combine to explain intuitive vs confusing interfaces", + "sources": ["[[The Design of Everyday Things - Don Norman]]"], + "concepts": ["[[Affordance]]", "[[Feedback loop]]"], "status": "active" } ] @@ -162,7 +179,7 @@ { "$ref": "ost-tools://_ost_tools_base#/$defs/ostEntityProps" } ], "properties": { - "type": { "const": "personal" }, + "type": { "const": "note" }, "date": { "type": "string", "description": "Date this entry was created or relates to" @@ -172,10 +189,10 @@ "additionalProperties": true, "examples": [ { - "type": "personal", - "title": "ADHD diagnosis", - "date": "2023-10-15", - "tags": ["adhd", "diagnosis"], + "type": "note", + "title": "Reflections after reading chapter 3", + "date": "2024-03-15", + "tags": ["reading-log"], "status": "active" } ]