53 lines
2.2 KiB
Markdown
53 lines
2.2 KiB
Markdown
---
|
|
type: overview
|
|
tldr: High-level map of the cascade knowledge base's directory structure, frontmatter schema, and layering rules.
|
|
last_updated: 2026-07-13
|
|
---
|
|
|
|
# Knowledge Base Overview
|
|
|
|
This is the local (mutable) layer of a cascade knowledge base.
|
|
It sits above read-only upstream KBs in `../linked/` and `../libs/`.
|
|
|
|
## Cascade Priority
|
|
1. **wiki/** (local) — highest priority, agent-managed
|
|
2. **linked/\<name\>/** (symlinked) — read-only upstream source of truth
|
|
3. **libs/\<name\>/** (git-managed) — read-only external KBs
|
|
|
|
When the same entity exists in multiple layers, the local version wins.
|
|
|
|
## Directory Structure
|
|
```
|
|
.
|
|
├── libs/ # Git-managed external KBs (read-only, gitignored)
|
|
├── linked/ # Symlinks to upstream KBs (read-only)
|
|
├── outputs/ # Generated artifacts from the wiki
|
|
├── raw/ # User-provided source material
|
|
│ └── inbox/ # Drop zone for unprocessed material
|
|
├── tmp/ # Temporary files, caches (gitignored)
|
|
├── wiki/ # Local structured wiki (agent-managed)
|
|
│ ├── query-gaps.md # Failed or missing-answer questions for demand-driven ingest
|
|
│ ├── projects/ # Optional local query scopes
|
|
│ ├── entities/ # Typed entity pages
|
|
│ └── graph/ # Edge lists and relationship data
|
|
└── workload/ # Summaries of discussions and decisions
|
|
```
|
|
|
|
## Page Frontmatter
|
|
Every wiki page carries YAML frontmatter with a required `type` field, plus
|
|
optional `resource`, `tldr`, `confidence`, `quality`, `supersedes`,
|
|
`freshness_window_days`, and `retention`. `wiki/index.md` additionally
|
|
declares `kb_schema_version` for the bundle as a whole.
|
|
See AGENTS.md for the full schema.
|
|
|
|
## Recursive Indexes
|
|
`entities/`, `graph/`, and optional topic folders such as `projects/` each
|
|
carry their own `index.md` so navigation stays lazy — read `wiki/index.md`
|
|
first, then only descend into a subdirectory index if its contents are
|
|
relevant to the current task.
|
|
|
|
## Local-First Retrieval Aids
|
|
Project scope pages in `wiki/projects/` can group related sources so a query
|
|
starts narrow before falling back to the full cascade. `wiki/query-gaps.md`
|
|
records questions the wiki could not answer yet, turning failed searches into
|
|
small ingest targets.
|