{"slug": "agents-md-a-personal-llm-wiki-contract-for-obsidian-vaults-inspired-by-karpathy", "title": "AGENTS.md — A personal LLM Wiki contract for Obsidian vaults. Inspired by Karpathy's LLM Wiki idea.", "summary": "A developer has created AGENTS.md, a structured file that serves as an operating contract for LLMs working within Obsidian vaults. Inspired by Andrej Karpathy's LLM Wiki concept, the system defines a persistent knowledge base where an LLM ingests immutable raw sources and maintains a living wiki of linked knowledge pages, entities, concepts, and queries. The project enforces strict rules for file organization, naming conventions, and provenance tracking to ensure the LLM compounds knowledge over time rather than re-deriving context on every prompt.", "body_md": "Inspired by\n\n[Karpathy's LLM Wiki idea]— a persistent knowledge base maintained by LLMs that compounds over time instead of re-deriving context on every prompt.\n\nThis file is the operating contract for this vault. Every session, read it first. Every workflow, follow it exactly. When in doubt, check here before acting.\n\nA personal Obsidian vault where an LLM ingests sources, extracts knowledge, connects concepts, and maintains a wiki that grows with you. Raw sources stay immutable; the wiki layer is the living, linked knowledge.\n\n```\nvault/\n├── AGENTS.md              ← this file; schema and operating contract\n├── index.md               ← content catalog; update on every ingest\n├── log.md                 ← append-only session log\n├── raw/                   ← immutable source captures (never modify)\n└── wiki/                  ← LLM-maintained knowledge pages\n    ├── overview.md        ← evolving high-level synthesis\n    ├── sources/           ← one summary page per raw source\n    ├── entities/          ← people, orgs, tools, projects, books\n    ├── concepts/          ← ideas, frameworks, patterns, terms\n    └── queries/           ← saved answers to notable questions\n```\n\n**Rules:**\n\n`raw/`\n\nis read-only. Never edit, rename, or delete captured sources.`wiki/`\n\nis fully LLM-owned. Create, edit, reorganize, and link freely.`index.md`\n\nand`log.md`\n\nlive at the vault root.\n\nEvery wiki page uses this structure:\n\n```\n---\ntitle: Human-readable Title\ntype: source | entity | concept | query | overview\nsources: [source-slug-1, source-slug-2]\nupdated: YYYY-MM-DD\n---\n\n# Title\n\nOne-sentence summary.\n\n## Content\n\n...\n\n## Related\n\n- [[page-name]] — why it's related\n```\n\n**Naming:**\n\n- Filenames:\n`kebab-case.md`\n\n- One canonical page per thing — search before creating to avoid duplicates.\n- Use Obsidian\n`[[wiki links]]`\n\nmatching the target filename without`.md`\n\n.\n\n**Provenance fields** (add only when they apply):\n\n`sources`\n\n— which source pages this knowledge derives from`raw_paths`\n\n— paths to raw evidence files`canonical_ref`\n\n— stable external reference (URL, DOI, etc.)`captured_at`\n\n— date the source was captured\n\n- Treat\n`raw/`\n\nas immutable evidence. Once captured, never edit in place. - If a source changes or a better capture is needed, add a new dated file.\n- Preserve enough context for trust and reproducibility without hoarding.\n- For web sources, save as\n`raw/YYYY-MM-DD-slug.md`\n\n. - For repos, save only the README/key docs — not full clones.\n\nTriggered when a new source arrives (file in `raw/`\n\n, pasted content, or URL).\n\n**Read** the source in full.**Discuss** with the user: key takeaways, what to emphasize, what surprised them.**Write** a source summary page in`wiki/sources/`\n\n.**Create or update entity pages** for significant people, tools, projects, orgs.**Create or update concept pages** for major ideas, patterns, and frameworks.**Update** to reflect what this source adds or challenges.`wiki/overview.md`\n\n**Update** with new pages.`index.md`\n\n**Append to**:`log.md`\n\n`## [YYYY-MM-DD] ingest | Source Title`\n\n**Report** to the user: pages created, pages updated, contradictions found.\n\nTriggered when the user asks a question.\n\n- Read\n`index.md`\n\nto find relevant pages. - Read relevant wiki pages and their cited evidence.\n- Synthesize an answer with inline\n`[[citations]]`\n\n. - If the answer is worth revisiting: offer to save it in\n`wiki/queries/`\n\n. - Append to\n`log.md`\n\n:`## [YYYY-MM-DD] query | Question summary`\n\nTriggered on request. Check for and report:\n\n- Contradictions between pages (with quotes and sources)\n- Stale claims superseded by newer sources\n- Orphan pages (no inbound links)\n- Important concepts mentioned but lacking their own page\n- Missing cross-references (A mentions B but doesn't link)\n- Data gaps: claims that could be verified with a web search\n- Provenance gaps: wiki claims without traceable sources\n\nAfter reporting, ask: \"Should I fix any of these now?\"\nAppend to `log.md`\n\n: `## [YYYY-MM-DD] lint | N issues found`\n\n`index.md`\n\nis a scannable catalog, not a narrative.\n\nSections in order:\n\n**Overview****Sources**(newest first)** Entities**(alphabetical)** Concepts**(alphabetical)** Queries**(newest first)\n\nEntry format: `- [[page-name]] — one-line description`\n\n`log.md`\n\nis append-only. Never rewrite past entries.\n\n```\n## [YYYY-MM-DD] <type> | <title>\n\nOne or two sentences on what happened.\n```\n\nTypes: `ingest`\n\n, `query`\n\n, `lint`\n\n, `note`\n\n- Write for a knowledgeable peer, not a general audience.\n- Source summaries should include a \"My Take\" section — be opinionated.\n- The overview is a living thesis, not a neutral summary. It should have a point of view.\n- When sources contradict, note it explicitly on the relevant page.\n- Use\n**(speculative)**,**(uncertain)**, or**(contested)** inline for weak claims.\n\n- Commit messages:\n`<operation>: <brief description>`\n\n(e.g.,`ingest: Attention paper`\n\n) - One logical wiki operation per commit.\n- Never force-push.\n\nAt the start of every session:\n\n- Read this file.\n- Read\n`log.md`\n\n(last 10 entries). - Read\n`index.md`\n\n. - Greet the user with a brief status: what's in the wiki, what happened recently.", "url": "https://wpnews.pro/news/agents-md-a-personal-llm-wiki-contract-for-obsidian-vaults-inspired-by-karpathy", "canonical_source": "https://gist.github.com/streeck/75777b7d77dcfcc67a9f5d6d3eb3c0d3", "published_at": "2026-06-05 13:15:22+00:00", "updated_at": "2026-06-05 13:44:57.687911+00:00", "lang": "en", "topics": ["large-language-models", "ai-agents", "ai-tools", "ai-research", "ai-infrastructure"], "entities": ["Karpathy", "Obsidian", "LLM Wiki"], "alternates": {"html": "https://wpnews.pro/news/agents-md-a-personal-llm-wiki-contract-for-obsidian-vaults-inspired-by-karpathy", "markdown": "https://wpnews.pro/news/agents-md-a-personal-llm-wiki-contract-for-obsidian-vaults-inspired-by-karpathy.md", "text": "https://wpnews.pro/news/agents-md-a-personal-llm-wiki-contract-for-obsidian-vaults-inspired-by-karpathy.txt", "jsonld": "https://wpnews.pro/news/agents-md-a-personal-llm-wiki-contract-for-obsidian-vaults-inspired-by-karpathy.jsonld"}}