How blackx16/okf-wiki-template works
1. What this repo is
- This is a filesystem-first OKF wiki template: the knowledge base lives entirely in Markdown/YAML files, not in a database or proprietary wiki backend.
- The architecture is optimized for LLM agents to read, write, validate, and traverse knowledge deterministically.
2. Core storage boundary
- The main boundary is between immutable source material in raw/ and curated knowledge in wiki/.
- raw/ holds inbound documents by source type: articles/, github/, notes/, papers/, tutorials/, youtube/.
- The repo treats raw/ as write-protected input: agents read from it but do not edit it.
3. Knowledge layers inside wiki/
- wiki/sources/ contains processed reading notes derived from raw inputs.
- wiki/concepts/ contains synthesized abstractions that combine multiple sources into a durable concept page.
- wiki/entities/ stores structured metadata about people, organizations, products, or projects.
- wiki/queries/ is reserved for query-oriented artifacts or agent retrieval outputs.
4. OKF schema as the organizing model
- Every note is expected to follow the OKF pattern with explicit frontmatter fields, especially a required type.
- Relationships are declared explicitly through related: [], which makes the knowledge graph traversable without inference-heavy search.
- The result is a typed document graph rather than a loose collection of notes.
5. Templates as the content contract
- templates/ contains the canonical shapes for new OKF pages: concept-page.md, entity-page.md, and source-page.md.
- These templates act as a governance layer, ensuring new files conform to the repo’s schema and naming conventions.
- In architecture terms, templates are the content interface between agent-generated knowledge and the vault.
6. Ingestion and automation pipeline
- setup.py is the bootstrapper: it creates the folder structure, checks dependencies, and generates local config needed for agent operation.
- wiki_auto_ingest_manifest.py suggests a manifest-driven ingestion step that tracks what has been processed into the wiki.
- The readme describes a scheduled daemon workflow, driven by run_daemon.sh created during setup, to continuously ingest new raw files into curated wiki pages.
7. Agent/runtime integration
- The repo is designed to work with external MCP servers so AI agents can interact with the vault and source material.
- Key integrations called out in the readme are:
- obsidian for direct markdown read/write access,
- markitdown for converting PDFs/HTML/office docs into Markdown,
- youtube-transcript for transcript extraction,
- github-official for repository search/reference,
- context7 for developer documentation lookup.
- These integrations form the repo’s ingest and enrichment edge.
8. Operational control plane
- AGENTS.md is the operating manual for maintenance behavior: provenance rules, linting, and OKF compliance expectations.
- agent_prompt_template.md is intended to configure a scheduled background agent or cron-like daemon.
- system-context.md and log.md appear to support operational memory and audit/history for the maintenance process.
9. Quality assurance and health checks
- wiki_health_check.py is the validation subsystem: it scans the vault for orphans, thin notes, stale files, broken links, and contradictions.
- This provides a repository-level integrity check over the knowledge graph, complementing the ingestion pipeline.
- Architecturally, it is the main guardrail preventing the curated wiki from drifting out of schema or becoming disconnected.
10. Auxiliary assets and scaffolding
- assets/ is for non-text resources that may support pages or diagrams.
- .gitkeep files indicate that several directories are intentionally present as empty scaffolding so the vault structure is stable from the start.
- OBSIDIAN_MCP_SETUP.md is a targeted setup guide for one important integration path, reinforcing that this repo is meant to be used inside an agent-enabled note-taking workflow.
11. How data flows through the system
- External documents enter through raw/ via manual drop-in or MCP-assisted acquisition.
- The daemon/ingest workflow reads those inputs, converts or enriches them, and writes structured derivatives into wiki/sources/, wiki/concepts/, and wiki/entities/.
- Validation then checks the resulting graph, while the agent uses explicit links and type metadata to navigate and extend the knowledge base.
12. How to draw the architecture
- Model this repo as a local knowledge vault with three planes:
- Input plane: raw/ plus external MCP services,
- Processing plane: setup.py, daemon/manifest logic, templates, health checks,
- Knowledge plane: wiki/ as the durable typed graph.
- The key architectural constraint is that all state lives in plain files, with explicit schemas and relationships enabling deterministic agent behavior.
Main entry points: setup.py Setup · README.md README · templates Templates · mcp-config.json.template MCP services
Components 24
Input plane
Inbound documents and external acquisition/enrichment services.
- Raw inputs · Write-protected inbound documents organized by source type.
raw - MCP services · Agent-facing connectors for vault access, conversion, transcript extraction, code search, and docs lookup.
mcp-config.json.template - OKF article · Example raw article about OKF in the inbound area.
raw/articles/what-is-okf.md - Obsidian setup · Targeted setup guide for one important MCP path.
OBSIDIAN_MCP_SETUP.md
Processing plane
Bootstrapping, ingestion orchestration, templates, and validation.
- Setup · Creates the folder structure, checks dependencies, and prepares local runtime config.
setup.py - Ingest manifest · Tracks what content has been processed into the wiki.
wiki_auto_ingest_manifest.py - Health check · Scans the vault for orphans, thin notes, broken links, and contradictions.
wiki_health_check.py - Templates · Canonical page shapes for new OKF notes.
templates - Concept template · Frontmatter and structure for concept pages.
templates/concept-page.md - Entity template · Frontmatter and structure for entity pages.
templates/entity-page.md - Source template · Frontmatter and structure for source pages.
templates/source-page.md
Knowledge plane
Durable typed wiki content organized as source, concept, entity, and query layers.
- Wiki · Durable curated knowledge stored as plain Markdown with explicit relationships.
wiki - Sources · Reading notes derived from raw inputs.
wiki/sources - Concepts · Cross-source abstractions and durable concept pages.
wiki/concepts - Entities · People, organizations, products, and projects with explicit metadata.
wiki/entities - Queries · Query-oriented artifacts and agent retrieval outputs.
wiki/queries - Source note · Example processed source note in the wiki.
wiki/sources/what-is-okf.md - OKF concept · Curated concept page for Open Knowledge Format.
wiki/concepts/open-knowledge-format.md - OKF Foundation · Structured entity page for Open Knowledge Foundation.
wiki/entities/open-knowledge-foundation.md
Operations
Runtime guidance, prompts, and audit memory for agent maintenance.
- README · Explains the filesystem-first OKF wiki workflow and overall usage model.
README.md - AGENTS.md · Repository maintenance rules, provenance expectations, and OKF compliance guidance.
AGENTS.md - Agent prompt · Template for scheduled background agent or daemon behavior.
agent_prompt_template.md - System context · Shared operational memory and environment context for the maintenance process.
system-context.md - Log · Operational history and notes for maintenance runs.
log.md
Connections 30
- README → Raw inputs: defines intake · Describes raw as the inbound write-protected boundary.
- README → Wiki: describes · Frames the wiki as the durable knowledge plane.
- README → Setup: introduces · Explains bootstrap and local environment preparation.
- README → Health check: documents · Covers repository integrity checks and validation behavior.
- README → MCP services: integrates · Lists external services used for acquisition and enrichment.
- Setup → Templates: creates · Bootstraps the canonical note scaffolding.
- Setup → Raw inputs: creates tree · Initializes the input folder structure.
- Setup → Wiki: creates tree · Initializes the curated wiki structure.
- Setup → Agent prompt: writes · Generates local daemon or agent configuration.
- Agent prompt → Ingest manifest: drives · Schedules or guides ongoing ingestion runs.
- MCP services → Raw inputs: ingests · Provides acquisition and conversion paths into raw inputs.
- MCP services → Wiki: writes · Enables agent-mediated markdown read/write access.
- Raw inputs → Sources: feeds · Inbound documents are processed into source notes.
- Sources → Concepts: supports synthesis · Source notes are combined into durable abstractions.
- Sources → Entities: extracts metadata · Source material informs structured entity records.
- Concepts → Entities: references · Concept pages link to people, organizations, products, or projects.
- Wiki → Health check: validated by · The curated graph is checked for structural and content health.
- Ingest manifest → Sources: tracks · Records which raw items became curated source pages.
- Templates → Concept template: includes · Provides the concept page contract.
- Templates → Entity template: includes · Provides the entity page contract.
- Templates → Source template: includes · Provides the source page contract.
- AGENTS.md → Setup: governs · Defines expected bootstrap and maintenance behavior.
- AGENTS.md → Health check: governs · Sets compliance and quality expectations.
- System context → Agent prompt: informs · Supplies operational context for background agents.
- Log → Ingest manifest: records · Supports auditability of ingestion activity.
- OKF article → Source note: becomes · Example raw article is curated into a source page.
- Source note → OKF concept: links to · Processed notes point to higher-level concepts.
- OKF concept → OKF Foundation: mentions · Concepts connect to entity records.
- Obsidian setup → MCP services: onboards · Documents one key integration path for vault access.
- Queries → Health check: consumes findings · Retrieval artifacts can be used to support inspection and review.