AGENTS.md — A personal LLM Wiki contract for Obsidian vaults. Inspired by Karpathy's LLM Wiki idea.

Inspired by

[Karpathy's LLM Wiki idea]— a persistent knowledge base maintained by LLMs that compounds over time instead of re-deriving context on every prompt.

This 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.

A 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.

vault/
├── AGENTS.md              ← this file; schema and operating contract
├── index.md               ← content catalog; update on every ingest
├── log.md                 ← append-only session log
├── raw/                   ← immutable source captures (never modify)
└── wiki/                  ← LLM-maintained knowledge pages
    ├── overview.md        ← evolving high-level synthesis
    ├── sources/           ← one summary page per raw source
    ├── entities/          ← people, orgs, tools, projects, books
    ├── concepts/          ← ideas, frameworks, patterns, terms
    └── queries/           ← saved answers to notable questions

Rules:

raw/

is read-only. Never edit, rename, or delete captured sources.wiki/

is fully LLM-owned. Create, edit, reorganize, and link freely.index.md

andlog.md

live at the vault root.

Every wiki page uses this structure:

---
title: Human-readable Title
type: source | entity | concept | query | overview
sources: [source-slug-1, source-slug-2]
updated: YYYY-MM-DD
---


One-sentence summary.

## Content

...

## Related

- [[page-name]] — why it's related

Naming:

• Filenames: kebab-case.md

• One canonical page per thing — search before creating to avoid duplicates.

• Use Obsidian [[wiki links]]

matching the target filename without.md

.

Provenance fields (add only when they apply):

sources

— which source pages this knowledge derives fromraw_paths

— paths to raw evidence filescanonical_ref

— stable external reference (URL, DOI, etc.)captured_at

— date the source was captured

• Treat raw/

as immutable evidence. Once captured, never edit in place. - If a source changes or a better capture is needed, add a new dated file.

• Preserve enough context for trust and reproducibility without hoarding.
• For web sources, save as raw/YYYY-MM-DD-slug.md

. - For repos, save only the README/key docs — not full clones.

Triggered when a new source arrives (file in raw/

, pasted content, or URL).

Read the source in full.Discuss with the user: key takeaways, what to emphasize, what surprised them.Write a source summary page inwiki/sources/

.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

Update with new pages.index.md

Append to:log.md

## [YYYY-MM-DD] ingest | Source Title

Report to the user: pages created, pages updated, contradictions found.

Triggered when the user asks a question.

• Read index.md

to find relevant pages. - Read relevant wiki pages and their cited evidence.

• Synthesize an answer with inline [[citations]]

. - If the answer is worth revisiting: offer to save it in wiki/queries/

. - Append to log.md

:## [YYYY-MM-DD] query | Question summary

Triggered on request. Check for and report:

• Contradictions between pages (with quotes and sources)
• Stale claims superseded by newer sources
• Orphan pages (no inbound links)
• Important concepts mentioned but lacking their own page
• Missing cross-references (A mentions B but doesn't link)
• Data gaps: claims that could be verified with a web search
• Provenance gaps: wiki claims without traceable sources

After reporting, ask: "Should I fix any of these now?" Append to log.md

: ## [YYYY-MM-DD] lint | N issues found

index.md

is a scannable catalog, not a narrative.

Sections in order:

Overview****Sources(newest first)** Entities**(alphabetical)** Concepts**(alphabetical)** Queries**(newest first)

Entry format: - [[page-name]] — one-line description

log.md

is append-only. Never rewrite past entries.

## [YYYY-MM-DD] <type> | <title>

One or two sentences on what happened.

Types: ingest

, query

, lint

, note

• Write for a knowledgeable peer, not a general audience.

• Source summaries should include a "My Take" section — be opinionated.

• The overview is a living thesis, not a neutral summary. It should have a point of view.

• When sources contradict, note it explicitly on the relevant page.

• Use (speculative),(uncertain), or**(contested)** inline for weak claims.

• Commit messages: <operation>: <brief description>

(e.g.,ingest: Attention paper

) - One logical wiki operation per commit.

• Never force-push.

At the start of every session:

• Read this file.
• Read log.md

(last 10 entries). - Read index.md

. - Greet the user with a brief status: what's in the wiki, what happened recently.

source & further reading

gist.github.com — original article Pi Talk Mode extension AGENTS.md authoring skill Meng_To_Design_Skill.md