From 125f74c563b8dfa6bb2ef6c2529ca52b8392b4bb Mon Sep 17 00:00:00 2001 From: truetype Date: Sun, 10 May 2026 17:36:15 +0200 Subject: [PATCH] add: AGENTS.md schema, seed files, sample topic page --- AGENTS.md | 104 ++++++++++++++++++++++++++++++++ wiki/topics/llm-wiki-pattern.md | 35 +++++++++++ 2 files changed, 139 insertions(+) create mode 100644 AGENTS.md create mode 100644 wiki/topics/llm-wiki-pattern.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e9007da --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,104 @@ +# LangCode Agent Wiki — Schema + +## Purpose +Persistent knowledge base for the LangCode Agent project. Maintained entirely by an LLM agent running on Ollama (Gemma 2 9B). This wiki sits between raw source documents and your questions — knowledge is compiled once here, then kept current. + +## Directory Structure +\`\`\` +llmwiki/ +├── AGENTS.md ← this file (schema) +├── raw/ ← immutable source documents +│ ├── articles/ ← web articles, blog posts +│ ├── papers/ ← research papers, technical docs +│ ├── repos/ ← code repository notes +│ └── assets/ ← images, downloads, attachments +└── wiki/ ← LLM-generated, interlinked pages + ├── index.md ← master catalog (updated every ingest) + ├── log.md ← append-only changelog + ├── overview.md ← wiki purpose & architecture + ├── concepts/ ← one file per key concept + ├── entities/ ← one file per person, org, tool + ├── sources/ ← one file per source document + └── comparisons/ ← comparative analysis pages +\`\`\` + +## Conventions + +### Filenames +- lowercase, hyphens instead of spaces (e.g. \`self-attention.md\`) +- no special characters, no camelCase +- prefix with date for time-sensitive entries: \`2026-05-10-some-event.md\` + +### Page Structure +Every wiki page must follow this template: +\`\`\`markdown +# Title + +> One-sentence summary of this page. + +## Tags +\`concept\` \`entity\` \`source-name\` \`date\` + +## Body +[Content here — use ## and ### for sections] + +## Related +- [[page-name]] — brief description of connection +- [[another-page]] — brief description + +## Sources +- [Source Title](raw/sources/filename) — relevant passage or page range +\`\`\` + +## Ingest Procedure +When a new source is added to \`raw/\`: +1. Read the source end-to-end +2. Identify key concepts, entities, claims, and data points +3. For each: create or update the relevant wiki page in \`wiki/\` +4. Add/update cross-references using \`[[wikilinks]]\` +5. Update \`wiki/index.md\` with new/modified pages +6. Append entry to \`wiki/log.md\` with format: + \`\`\` + ## YYYY-MM-DD HH:MM — [source filename] + - Created: [new pages] + - Updated: [modified pages] + - Key takeaways: [bullet summary] + \`\`\` +7. Run the lint checklist (below) + +## Query Procedure +When asked a question: +1. Read \`wiki/index.md\` first to identify relevant pages +2. Load only those pages (not the entire wiki at scale) +3. Synthesize answer from compiled wiki knowledge +4. Cite specific wiki pages: \`[[page-name]]\` +5. If the answer is valuable and reusable, file it as a new wiki page + +## Lint Checklist +Run weekly or after every 5-10 ingests: +- [ ] Every page in \`wiki/\` appears in \`index.md\` +- [ ] Every \`[[wikilink]]\` resolves to an existing file +- [ ] No two pages cover the same concept (merge duplicates) +- [ ] Conflicting claims between pages are flagged, not silently overwritten +- [ ] No orphan pages (pages with zero inbound links) +- [ ] All pages follow the template structure above +- [ ] Tags are consistent across related pages +- [ ] Log entries are present and properly formatted +- [ ] Sources in \`raw/\` that have been updated are reflected in wiki + +## Conflict Resolution +When sources disagree: +1. Note both claims explicitly on the relevant page +2. Cite both sources +3. Add a "Status" field: \`verified\` / \`disputed\` / \`unverified\` +4. Do NOT silently overwrite — preserve the history of claims + +## Naming Conventions +- Page titles: Title Case (e.g. "Self-Attention Mechanism") +- Filenames: lowercase-hyphens (e.g. \`self-attention-mechanism.md\`) +- Tags: lowercase, hyphens (e.g. \`#attention-mechanism\`) + +## Growth Targets +- After 10-20 sources: start querying the wiki for answers +- After 50+ sources: consider adding qmd for enhanced search +- After 100+ sources: review and potentially restructure wiki subdirectories diff --git a/wiki/topics/llm-wiki-pattern.md b/wiki/topics/llm-wiki-pattern.md new file mode 100644 index 0000000..374f2d2 --- /dev/null +++ b/wiki/topics/llm-wiki-pattern.md @@ -0,0 +1,35 @@ +# LLM Wiki Pattern (Karpathy) + +> A method for building persistent, structured knowledge bases using LLM agents — compiled once, kept current, queried efficiently. + +## Tags +`concept` `methodology` `knowledge-management` `2026-05-10` + +## Overview +Andrej Karpathy proposed the "LLM Wiki" pattern as an alternative to RAG (Retrieval-Augmented Generation). Instead of searching raw documents on every query, an LLM agent incrementally builds and maintains a wiki of interlinked markdown pages. + +## Core Architecture + +### Three Layers +1. **Raw Sources** (`raw/`) — Original documents, immutable. Never modified by the LLM. +2. **Wiki** (`wiki/`) — Structured, interlinked markdown pages compiled by the LLM. +3. **Schema** (`AGENTS.md`) — Rules, conventions, and workflows. The "operating system" of the wiki. + +### Workflows +- **Ingest**: Drop source in `raw/` → LLM reads, extracts, creates/updates ~10-15 wiki pages per source +- **Query**: Ask question → LLM reads `index.md` → drills into relevant pages → synthesizes answer with citations +- **Lint**: Periodically audit wiki for contradictions, orphans, stale claims + +## Key Principles +- One concept = one file +- Cross-reference everything with `[[wikilinks]]` +- The LLM owns the wiki directory; humans only edit `raw/` and the schema +- Good answers get filed back into the wiki as new pages (compounding knowledge) +- Works with any LLM that can read/write files (Claude Code, Codex, Cursor, local models via Ollama) + +## Related +- [[AGENTS.md]] — Schema file for this wiki +- [[index]] — Master catalog + +## Sources +- Karpathy's original idea file (GitHub Gist)