repo-knowledge-wiki
Repository-local knowledge architecture combining llm-wiki, mex symbol
grounding, and zvec-grep scoped retrieval inside one Git repository.
When to use this skill
- Bootstrapping a repository-local
knowledge/tree (raw/,queries/,work/active/,work/archive/,concepts/) separated from source code - Pairing query history, design decisions, or active work checklists to exact code symbols via
.mex/context/knowledge-pairings.md - Running minimal-context retrieval (Context Gate) so code searches exclude wiki noise and wiki searches exclude
raw/andwork/archive/ - Auditing pairing drift between
knowledge/frontmatter (paired_symbols) and.mex/grounded entities
Architecture (Dual-Layer Bridge)
mex-agent only indexes Markdown inside .mex/, while zvec-grep (zg) skips
hidden directories like .mex/ by default. This skill bridges both:
knowledge/(Git-tracked,zg-indexed): Human- and Obsidian-readable Markdown (index.md,log.md,raw/,queries/,work/active/,work/archive/,concepts/)..mex/context/knowledge-pairings.md(mex-grounded): Bridge entities (<!-- mex:entity ... -->withmex.grounds_to) linking code symbols (file+symbol) toknowledge/*.mdpaths.
Instructions
1. Bootstrap a repository
python3 .agent-skills/repo-knowledge-wiki/scripts/bootstrap.py --project /path/to/repo --dry-run --json
python3 .agent-skills/repo-knowledge-wiki/scripts/bootstrap.py --project /path/to/repo --json
Idempotent: creates missing knowledge/ directories, index.md, log.md,
and .mex/context/knowledge-pairings.md (when .mex/ exists) without
overwriting existing files. If .gitignore uses a root /* allowlist, adds
!/knowledge/.
2. Follow the Context Gate on every lookup
- Before editing code: run
mex-agent wiki for-code <nodeId>ormex-agent impact <symbol|file>and read only the linkedknowledge/sections. - Searching past queries or active work:
Inspect paths/headings/line ranges first, then read only the needed lines.zg query "<topic>" -g 'knowledge/**' -g '!knowledge/raw/**' -g '!knowledge/work/archive/**' --preview none --limit 5 - Searching code only:
zg query "<symbol or concept>" -g '!knowledge/**' --preview none --limit 8
3. Pair documents and audit drift
Every durable note in knowledge/queries/, knowledge/work/active/, or
knowledge/concepts/ uses frontmatter status, paired_files, and
paired_symbols (path/to/file.py#symbol_name or path/to/file.py:line). Audit or sync pairings:
python3 .agent-skills/repo-knowledge-wiki/scripts/pair_sync.py --project /path/to/repo --json
python3 .agent-skills/repo-knowledge-wiki/scripts/pair_sync.py --project /path/to/repo --sync --dry-run --json
python3 .agent-skills/repo-knowledge-wiki/scripts/pair_sync.py --project /path/to/repo --sync --json
--sync generates an idempotent mex-agent wiki apply batch under .mex/local/setup-ops/pair-sync.json, refreshes .mex/graph.db and .zvec-grep/, and verifies pairing integrity.
4. Archive completed work checks
When a knowledge/work/active/<task>.md checklist finishes:
- Update
status: donein frontmatter and move it toknowledge/work/archive/. - Update
knowledge/index.mdand append one line toknowledge/log.md. - Run
zg indexso default active-work queries exclude the archived note.
