# Ticket: Linked Markdown wiki alternative to RAG

## Metadata
- Type: Ticket
- Status: Planned
- Project: Pi / Knowledge System
- Created: 2026-05-17
- Updated: 2026-05-17
- Priority: High

## Goal

Design and prototype a linked Markdown wiki knowledge system inspired by Andrej Karpathy's wiki-style approach, as an alternative or complement to embedding/vector RAG.

## Why

A linked `.md` knowledge base can be more transparent, inspectable, editable, and durable than opaque vector retrieval. It may fit this repo/Obsidian-style workflow well because Pi can follow explicit links, summaries, indexes, tags, and backlinks.

## Scope

Included:
- Research and summarize the relevant Karpathy wiki/knowledge-management concept from available sources when web access is available.
- Define a local linked Markdown structure for Pi knowledge.
- Compare linked Markdown navigation against traditional RAG for this use case.
- Design conventions for links, indexes, tags, summaries, backlinks, and source notes.
- Prototype a small wiki section using existing repo docs.
- Define how Pi should traverse/read linked notes safely and predictably.

Not included:
- Replacing all existing docs immediately.
- Building a vector database unless separately justified.
- Blindly importing external content without source tracking.

## Acceptance Criteria

This ticket is done when:
- [ ] A short research note exists describing the Karpathy-style wiki idea and source links.
- [ ] A proposed Markdown wiki structure is documented.
- [ ] Link/backlink/tag conventions are defined.
- [ ] A small prototype wiki area exists.
- [ ] A retrieval/traversal procedure for Pi is documented.
- [ ] Risks and tradeoffs versus RAG are documented.

## Questions

- Which specific Karpathy wiki system/material should be treated as canonical?
- Should this live in `wiki/`, `docs/wiki/`, or an Obsidian vault-backed folder?
- How much automated link generation should Pi do versus user-authored curation?

## Plan / Next Actions

- [ ] Research the source material when browsing is available.
- [ ] Draft a spec for the Markdown wiki system.
- [ ] Create a minimal folder/index/link convention.
- [ ] Convert a small existing topic into wiki-style linked notes.
- [ ] Evaluate whether Pi can use it effectively without vector search.

## 2026-05-17 Spec Advancement

Confidence level: medium for architecture direction; low for exact Karpathy source details until safe browsing or user-provided links are available.

Decisions now stable:
- This should start as transparent Markdown conventions, not a vector database.
- The system should complement the repo/ticket/runbook model and Obsidian, not replace it immediately.
- Pi traversal should be explicit and bounded: start at an index, follow selected links, summarize findings, cite file paths.

Proposed MVP spec:
- Create a `wiki/` or `docs/wiki/` proof of concept with an index note.
- Each note has: title, summary, links, backlinks/manual references, tags, source/provenance, last reviewed date.
- Use hub pages for domains such as Nextcloud, Pi architecture, YouTube capture, and security.
- Define a traversal budget: e.g. read index + up to N linked notes before asking or summarizing.

Updated next actions:
- [ ] Choose folder location for the prototype wiki.
- [ ] Draft link/frontmatter conventions.
- [ ] Convert one small domain, likely Nextcloud Talk assistant, into wiki-style notes.
- [ ] Add research/source section after safe browsing exists.

## Notes

- User requested this as Pi upgrade item 2 on 2026-05-17.
- This depends partly on safe web browsing/research capability or user-provided source links.