| name | wiki-schema |
| description | Vault knowledge schema for the obsidian-llm-wiki plugin. Defines the three-layer source model, page types, frontmatter schemas, tag rules, cross-linking conventions, and the format of _index.md, _log.md, _manifest.json, and hot.md. Read this before any wiki operation (ingest, scan, query, save, lint, hot, tags-refresh). Triggers on: wiki schema, wiki conventions, wiki structure, wiki rules.
|
Wiki Schema — obsidian-llm-wiki
Vault knowledge schema for the wiki layer. All wiki skills read this file before
operating. This is the single source of truth for conventions, boundaries, and formats.
All /wiki-* slash commands follow these conventions identically across
both Claude Code and GitHub Copilot.
Critical Boundary Rule
Wiki operations (ingest, scan, query, save, lint, hot, tags-refresh) MUST NEVER write
to or delete files from:
Meetings/Daily/Projects/Customers/People/Clippings/Research/
These are Layer 1 — read-only knowledge sources. The wiki reads them; it never modifies them.
The wiki layer includes two task-management commands (/wiki-task and
/wiki-tasks-extract) that intentionally write outside the wiki directory — to
Projects/ and Tasks.md. These commands follow the task-creation rules in
_shared/task-rules.md. All other wiki operations remain wiki-directory-only.
Three-Layer Source Model
Layer 1 — Sources (read-only for wiki):
Meetings/ ← meeting notes (primary knowledge source)
Daily/ ← daily notes — extract ## Notes and ## Worklog sections only;
skip Dataview task queries (they are not content)
Projects/ ← project context, decisions, tech stack
includes Products/, Data Generators/, Jira/ subdirs
Customers/ ← customer notes
People/ ← person/team notes
Clippings/ ← web clippings
Research/ ← research notes
Layer 2 — Inbox (read + archive after processing):
.raw/ ← external sources: PDFs, exports, web clips
The ONLY directory wiki may clean up.
After successful ingest: move to .raw/_processed/YYYY-MM/
For HTML files: use defuddle if available before ingesting
npx defuddle parse <file> --md
Layer 3 — Wiki output (write exclusively here):
wiki/ ← all wiki pages and meta files
Wiki Output Structure
wiki/
├── _index.md ← master catalog (every page, one-line summary, category)
├── _log.md ← append-only operation log
├── _manifest.json ← delta tracker {filepath: {hash, ingested_at, wiki_pages[]}}
├── hot.md ← recent context cache (last ~3 sessions, ≤300 words)
├── concepts/ ← technology/domain concept pages
├── entities/ ← people, teams, customers (synthesis, not replacement of source files)
├── decisions/ ← architectural/product decisions extracted from meetings + projects
├── patterns/ ← reusable approaches, solutions, gotchas
└── sources/ ← one summary page per .raw/ file ingested
Source files in Layer 1 dirs do NOT get sources/ pages — they are referenced via
backlinks in the sources: frontmatter field of wiki pages.
Page Types
| Type | Folder | Use for |
|---|
concept | concepts/ | Technology, framework, or domain idea that recurs across sources |
entity | entities/ | Person, team, customer, or product appearing in multiple sources |
decision | decisions/ | Architectural/product/strategic decision extracted from meetings or projects |
pattern | patterns/ | Reusable approach, solution, gotcha, or workflow |
source-summary | sources/ | Summary of one .raw/ file (full extraction, for inbox files only) |
Frontmatter Schemas
Required fields on all wiki pages
---
type: concept | entity | decision | pattern | source-summary
title: "Page Title"
wiki-status: seed | developing | stable
created: YYYY-MM-DD
updated: YYYY-MM-DD
tags:
- <tag from .obsidian/copilot/tag-index.md only — see Tag Rules>
---
wiki-status meanings:
seed — placeholder, minimal content, created to avoid dead linksdeveloping — content present but incomplete or sparsely sourcedstable — well-sourced, cross-referenced, unlikely to change soon
Concept page
---
type: concept
title: "MCP Server"
wiki-status: developing
created: 2026-04-28
updated: 2026-04-28
tags:
- ai
- mcp
- mgd
sources:
- "[[Meetings/MGD/2026-04-10 MCP Planning.md]]"
related:
- "[[concepts/API Gateway]]"
- "[[decisions/MCP Server Architecture]]"
---
Entity page
---
type: entity
title: "John Brown"
wiki-status: stable
created: 2026-04-28
updated: 2026-04-28
tags:
- mgd
sources:
- "[[People/John Brown.md]]"
related:
- "[[entities/BRAVO Team]]"
---
Decision page
---
type: decision
title: "Use gRPC for MCP Transport"
wiki-status: stable
created: 2026-04-28
updated: 2026-04-28
decision-date: 2026-04-10
decision-status: active | superseded | proposed
tags:
- mcp
- mgd
- api
sources:
- "[[Meetings/MGD/2026-04-10 MCP Planning.md]]"
related:
- "[[concepts/MCP Server]]"
---
Pattern page
---
type: pattern
title: "Hot Cache Pattern"
wiki-status: stable
created: 2026-04-28
updated: 2026-04-28
tags:
- ai
- doc
sources:
- "[[Research/LLM Wiki Notes.md]]"
related:
- "[[concepts/LLM Wiki]]"
---
Source summary page (.raw/ files only)
---
type: source-summary
title: "Article or Document Title"
wiki-status: stable
created: YYYY-MM-DD
updated: YYYY-MM-DD
tags:
- doc
source-file: ".raw/articles/filename-YYYY-MM-DD.md"
source-url: "https://..."
related:
- "[[concepts/Related Concept]]"
---
Tag Rules
Only use tags from .obsidian/copilot/tag-index.md. Never invent new tags.
Most applicable tags for wiki pages:
| Category | Tags |
|---|
| Work area | #mgd #oa #saas |
| Technical | #ai #mcp #api #k8s #lambda #docker #security #sql |
| Work type | #doc #learn #review |
| Special | #hide (exclude from task dashboards if wiki page appears in them) |
If content clearly needs a tag that does not exist: use the closest existing tag AND
note tag-needed: <proposed-tag> in the _log.md ingest entry. The user can then
approve and add it via /wiki-tags-refresh,
which scans the vault (or a target directory) for undocumented tags and updates tag-index.md.
Cross-Linking Rules
- Between wiki pages:
[[Page Title]] — Obsidian resolves by filename; no path
prefix needed as long as filenames are unique across the vault.
- Back to Layer 1 source files: use full vault-root-relative path:
[[Meetings/MGD/2026-04-10 MCP Planning.md]]
- First mention rule: the first time a concept, entity, or decision appears in a
wiki page body, make it a wikilink.
- Every non-seed page must have at least one
related wikilink in frontmatter.
- Do not wikilink folder names — only specific files.
Filename uniqueness
Wiki page filenames must be unique across the entire vault. Before creating a page,
verify the name does not conflict with any existing file anywhere in the vault. If a
conflict exists, add a disambiguating qualifier: MCP Server (Managed).md.
_index.md Format and Update Rules
Update after every ingest or save. Add a row for every new page immediately.
Sort each section alphabetically by page title.
---
type: meta
title: "Wiki Index"
updated: YYYY-MM-DD
---
# Wiki Index
## Concepts
| Page | Summary | Tags | Updated |
|------|---------|------|---------|
| [[concepts/MCP Server]] | Protocol connecting LLMs to external tools | #ai #mcp | 2026-04-28 |
## Entities
| Page | Summary | Tags | Updated |
|------|---------|------|---------|
| [[entities/John Brown]] | Software engineer, BRAVO team | #mgd | 2026-04-28 |
## Decisions
| Page | Summary | Tags | Updated |
|------|---------|------|---------|
| [[decisions/Use gRPC for MCP Transport]] | gRPC chosen over REST for latency | #mcp #api | 2026-04-28 |
## Patterns
| Page | Summary | Tags | Updated |
|------|---------|------|---------|
| [[patterns/Hot Cache Pattern]] | Short-term context cache for LLM sessions | #ai | 2026-04-28 |
## Sources
| Page | Summary | Source | Ingested |
|------|---------|--------|---------|
| [[sources/LLM Wiki Article]] | Karpathy's LLM wiki pattern explained | .raw/articles/... | 2026-04-28 |
Never delete index rows. If a page is removed, mark its summary as (archived).
_log.md Format
_log.md is append-only. New entries go at the top (newest first). Never edit or
delete past entries.
---
type: meta
title: "Wiki Log"
---
# Wiki Log
## [2026-04-28] ingest | Meetings/MGD/2026-04-10 MCP Planning.md
- Pages created: [[concepts/MCP Server]], [[decisions/Use gRPC for MCP Transport]]
- Pages updated: [[entities/John Brown]]
- Key insight: Team chose gRPC for latency; REST considered but rejected.
## [2026-04-28] save | Hot Cache Pattern
- Type: pattern
- Location: [[patterns/Hot Cache Pattern]]
- From: conversation about LLM session continuity
## [2026-04-28] scan | Meetings/ — 3 new, 1 changed, 12 unchanged
## [2026-04-28] lint | health check — 12 pages, 2 orphans, 1 dead link
## [2026-04-28] hot | manual refresh
## [2026-04-28] tags-refresh | 2 new tags proposed, 1 approved
Entry type prefixes (grep-parseable):
ingest — single file ingestedscan — directory scan + batch ingestsave — conversation saved as wiki pagelint — health check runhot — manual hot cache refreshtags-refresh — tag index sync run
_manifest.json Format
Tracks ingested files to prevent duplicate processing.
{
"version": 1,
"sources": {
"Meetings/MGD/2026-04-10 MCP Planning.md": {
"hash": "abc123def456",
"ingested_at": "2026-04-28",
"wiki_pages": [
"wiki/concepts/MCP Server.md",
"wiki/decisions/Use gRPC for MCP Transport.md"
]
},
".raw/articles/llm-wiki-2026-04-20.md": {
"hash": "789xyz012",
"ingested_at": "2026-04-28",
"wiki_pages": [
"wiki/sources/LLM Wiki Article.md",
"wiki/patterns/Hot Cache Pattern.md"
]
}
}
}
Hash computation: md5sum <filepath> | cut -d' ' -f1
Rules:
- Before ingest: if path exists in manifest AND hash matches → skip (already up to date).
- After successful ingest: write/update the entry with current hash, date, and wiki_pages.
- Never delete Layer 1 file entries (keep history).
.raw/ entries remain after the source file is archived to _processed/.
Hot Cache (hot.md) Format and Update Rules
---
type: meta
title: "Hot Cache"
updated: YYYY-MM-DDTHH:MM:SS
---
# Recent Context
## Last Updated
YYYY-MM-DD. [One sentence: what happened in the most recent wiki session]
## Key Recent Facts
- [Most important recent takeaway]
- [Second most important]
- [Third, only if truly significant]
## Recent Changes
- Created: [[concepts/MCP Server]], [[decisions/Use gRPC for MCP Transport]]
- Updated: [[entities/John Brown]] (added context from 2026-04-10 meeting)
- Flagged: Potential contradiction between [[concepts/MCP Server]] and [[decisions/REST API]]
## Active Threads
- [Topic currently being researched or worked on]
- [Open question not yet resolved]
Update rules:
- After ingest — update with what was ingested and key insights.
- After save — note the new page and its topic.
- After lint — note issues found and any fixes made.
- Session end (Stop hook) — summarize the full session; keep last 3 session blocks,
delete older ones. Total file ≤300 words.
- Session start (SessionStart hook) — read silently to restore context; do not announce.
- After PostCompact — re-read silently to restore context lost during compaction.
Total file length: ≤300 words. It is a cache, not a journal.
