Skip to content

AGENTS.md

Latest commit

 

History

History
167 lines (127 loc) · 6.6 KB

AGENTS.md

File metadata and controls

167 lines (127 loc) · 6.6 KB
Raw

PyAutoMemory wikis — shared schema + usage rules

Every sub-wiki under wiki/ gives an AI assistant broad scientific context for one domain. They follow Karpathy's "LLM Wiki" pattern: concise, cross-linked pages are read at query time, while canonical citation metadata lives separately in ../bibliography/. This file defines the schema once; each sub-wiki's own AGENTS.md diverges only on scope.

Layout

PyAutoMemory/                  # repo root
├── wiki/                     # all sub-wikis (in git)
│   ├── AGENTS.md             # this file — schema + usage rules
│   └── <domain>/             # one domain per sub-wiki, e.g. lensing/
│       ├── AGENTS.md         # the sub-wiki's scope notes
│       ├── index.md          # the sub-wiki's own navigation
│       ├── log.md            # append-only compilation log
│       ├── concepts/         # one topic per page — the science
│       ├── entities/         # named things: surveys, instruments, software
│       ├── sources/          # compact claim support (one paper = one section)
│       └── seed/             # unverified 2026-05 import, not citeable yet
└── bibliography/             # canonical BibTeX and citation tooling

Papers are the ground truth; wiki pages are syntheses. If they disagree, update the wiki and note the change in the sub-wiki's log.md.

References and citation metadata

  • sources/*.md records compact guidance about what claims a paper supports.
  • seed/*.md is the same shape, unverified: the 2026-05 import's stubs, held apart so nothing cites them by accident.
  • ../bibliography/pyautomemory.bib records canonical metadata and keys.

Never record local PDF paths or fabricate metadata — source PDFs live off-repo. One declared exception: a page's frontmatter may carry an archive: list — the read-only archival filenames of the off-repo PDFs the 2026-05 import seeded it from (e.g. Strong_Lens/Suyu2016Holicow.pdf). These are provenance history, never live paths; nothing may resolve or grow them — new papers cite the bibliography, not an archive path. A canonical key is local to PyAutoMemory: resolve it against a target project's .bib before patching LaTeX. See ../bibliography/README.md for the workflow.

Page types

Type Folder Scope
Concept concepts/ One scientific concept (e.g. mass-sheet degeneracy)
Entity entities/ One named thing (survey, lens, code, collaboration)
Sources sources/ Claim support for one topic, one section per paper
Seed seed/ Source pages from the 2026-05 import whose every entry is still a filename-inferred stub (Canonical BibTeX key: TODO) — never cite one until the paper is verified and the entry promoted into sources/
Index/log root Navigation and provenance

Naming

  • File names are lowercase kebab-case: mass-sheet-degeneracy.md, h0licow.md, time-delay-cosmography.md.
  • One concept per concept page. If a page tries to cover two ideas, split it.
  • Source-collection pages are named by topic: sources/dark-matter-substructure.md.

Cross-references

Use [[page-slug]] for wiki-internal links — for example [[mass-sheet-degeneracy]] or [[h0licow]]. Slugs match the filename without .md; a sources/ page also answers to [[sources-<topic>]] and a seed/ page to [[seed-<topic>]]. A [[link]] that has no target file yet is fine — it marks a future page to write, and scripts/validate_wikilinks.py ratchets that backlog (it fails only on a new unresolved target, against scripts/wikilink_baseline.txt).

External references use verified DOI, arXiv, journal, or author/year/title metadata, never a local path.

Frontmatter

Every wiki file starts with YAML frontmatter:

---
title: Mass-sheet degeneracy
type: concept            # concept | entity | sources | meta
topics: [degeneracies, cosmography]
sources:                 # optional — papers most relevant to this page
  - Suyu et al. 2017 — H0LiCOW overview
  - Birrer et al. 2020 — TDCOSMO IV
status: stub             # stub | drafted | reviewed
---

Sources may be [] for pages that synthesize general field knowledge.

Concept page structure

# Title

## TL;DR
One paragraph an assistant can quote back to a user.

## What it is
The physics / definition.

## Why it matters
How this concept shows up in the decisions the domain's software users make.

## Key results from the literature
Bullet list. Each bullet ends with `([[author-year-stub]])` so the LLM can
follow the link to the per-paper section.

## See also
- [[related-concept-1]]
- [[related-concept-2]]

Entity page structure

Same idea but the headings are "What it is / Key facts / Papers / See also". Use entity pages for: surveys (BELLS, H0liCOW), specific objects (Abell 1201, the Cosmic Horseshoe), software (PyAutoLens, lenstronomy), collaborations (TDCOSMO, Space Warps).

Source-collection page structure

# Sources: <topic>

Papers covering this topic. Each paper has its own H2 section; cross-link with
`[[sources-<topic>#author-year-slug]]`.

## Author Year — short tag

**Canonical BibTeX key:** `KeyYYYY`
**Reference:** DOI/arXiv/journal reference if known
**Concepts:** [[concept-1]], [[concept-2]]

**Supports:**
- Claim this paper directly supports.
- Another claim this paper directly supports.

**Use when:**
- Situation where the citation is appropriate.

**Do not use for:**
- Similar but unsupported claim.

Keep entries short: normally 2–5 support bullets and no long prose. Do not copy abstracts or infer claims from filenames. Add a TODO when support is unverified.

How the assistant should use a wiki

  1. On a user question, first open the sub-wiki's index.md.
  2. Follow the relevant concepts/ or entities/ page.
  3. Follow the source entry for claim scope and its canonical key for metadata.
  4. Resolve that key against downstream .bib files before changing LaTeX.
  5. If support or metadata is unclear, read the public paper and add a TODO rather than guessing. Log verified upgrades.

Adding a sub-wiki

Create wiki/<domain>/ with its own AGENTS.md (scope notes only — this schema is inherited, not copied), index.md, log.md, and the page folders it needs (seed/ only if it is taking an unverified import). Give it a row in the repo-root index.md and README.md tables.