Field Mapper

You bring a concept you half-know -- an overheard term, a stray question, a phrase from an article -- and Field Mapper gives you working literacy in the whole field it belongs to, then files every result into a well-classified, growing knowledge library so your notes become an organized reference instead of loose scraps.

This repository is two things at once:

1. A reusable agent workflow -- a set of instruction files (CLAUDE.md, AGENTS.md, GEMINI.md + .workflow-references/) that turn any capable AI agent into "Field Mapper."
2. A living knowledge library -- the knowledge/ folder, where every field the agent maps is shelved and catalogued. Browse it like a reference book.

---

How to use this repo

There are three ways in, depending on what you want. Pick yours.

A. Just read the knowledge (you want the notes)

Start at knowledge/INDEX.md -- the catalog. It lists every field and every concept, each a clickable link. Open a field's _map.md first (it gives the mental model and the concept list in learning order), then follow into individual concept files.

Each concept file answers three questions in plain language: what it is, why it matters, and how it connects to the other concepts -- so you can read one file or the whole shelf.

The library's canonical text is English. If a concept has been requested in another language, a translated copy sits under <field>/<lang>/ (e.g. zh/), and the concept's INDEX.md entry marks which translations exist.

You do not need an AI agent or any setup for this. Clone or download the repo and read the Markdown:

git clone https://github.com/Josh-Chung/field-mapper.git
cd field-mapper
# open knowledge/INDEX.md in any Markdown viewer or your editor

B. Grow the library yourself (you want to map new fields)

Open this repo with an AI agent -- it reads its entry file and becomes Field Mapper:

Your agent	Reads
Claude (Claude Code, claude.ai)	CLAUDE.md
Codex / other AGENTS.md agents	AGENTS.md
Gemini	GEMINI.md

The three entry files are content-equivalent -- they differ only in the agent identity block. Pick the one matching your runtime.

Then just send a concept, a question, or a phrase. For example:

"I keep hearing 'idempotency' -- what world is that from?"

The agent will locate the field, map its 8-20 load-bearing concepts, explain them, file everything into knowledge/, update the catalog, and then answer your original question. See What the agent does below for the full pipeline.

Ask in any language. The agent keeps the canonical map in English and, for a non-English question, writes a localized copy of the piece you asked about under <field>/<lang>/, then answers you in your language -- so the library stays consistent while you read in whatever language you prefer.

No filesystem? If you paste the instructions into a chat with no file access, the agent detects that (its Capability Model) and switches to Session Mode: it produces the identical content inline and gives you a catalog block to paste, instead of pretending to write files.

C. Version and share the library (you want to keep it safe)

The library is plain Markdown, so it versions beautifully with git. This repo already uses Conventional Commits, one commit per mapping action -- see .workflow-references/GIT_WORKFLOW.md. Quick reference:

feat(<field>):     a new field mapped, or a concept added
docs(<field>):     an existing concept expanded (no new concepts)
refactor(<field>): a shelf reorganized (files moved)
fix(<field>):      an inaccuracy corrected
chore(catalog):    INDEX.md / MEMORY.md upkeep

Push your library to a remote so it is backed up -- a library that lives on one machine only is one disk failure from gone.

---

How the repo is laid out

field-mapper/
+-- CLAUDE.md / AGENTS.md / GEMINI.md   # agent entry files (pick one per runtime)
+-- .workflow-references/               # companion rules, read on demand
|   +-- library-discipline.md           #   classification, catalog, anti-clutter
|   +-- field-mapping-method.md         #   concept selection, tiers, templates
|   +-- glossary.md                     #   controlled vocabulary
|   +-- GIT_WORKFLOW.md                 #   commit + branch conventions
+-- MEMORY.md                           # the agent's operational memory (see below)
+-- knowledge/                          # THE LIBRARY -- produced content
|   +-- INDEX.md                        #   the catalog: every field + concept
|   +-- <field>/                        #   one folder per field
|       +-- _map.md                     #     field overview + concept list (English canonical)
|       +-- <concept>.md                #     one file per concept (English canonical)
|       +-- <lang>/                     #     localized copies, e.g. zh/ (ISO 639-1)
|           +-- <concept>.md            #       translation of ../<concept>.md
+-- README.md                           # this file
+-- llms.txt                            # machine-readable manifest

Two memory systems, and why they never overlap:

• knowledge/ holds the content -- the fields, maps, and concepts you can read. This is the product.
• MEMORY.md holds the agent's operational decisions -- your learning profile, how cross-field concepts are filed, calibration. It is how the agent stays consistent across sessions. It is not study material; you rarely read it directly.

One home per fact -- content never leaks into MEMORY.md, decisions never leak into knowledge/.

---

What the agent does (the pipeline)

Every request runs one pipeline, in order:

0. Orient -- self-check for file access (Library vs. Session Mode); read MEMORY.md.
1. Read the input -- a question, a bare concept, or a misframed prompt.
2. Locate the field -- confirm only if genuinely ambiguous.
3. Classify into the library -- decide the shelf before writing; keep the root clean; if the field already exists, point it out instead of duplicating.
4. Build or extend the map -- 8-20 load-bearing concepts in a Core tier (~5-10 must-knows) + an Extended tier, ordered by dependency.
5. Write -- small field -> one file; large field -> a directory. Each concept: what it is / why it matters / how it connects, plus field Best Practices and Common Pitfalls. Canonical text is English; a non-English request also gets a localized copy under <field>/<lang>/.
6. Update the catalog (INDEX.md) and run the Library Ceiling Check (proposes a split when a shelf gets crowded -- never moves files without asking).
7. Answer the original question, grounded in the map.
8. Offer the next move -- go deeper, quiz you, map an adjacent field.
9. Self-check a Definition-of-Done gate before finishing.

Success looks like: after reading, a motivated beginner has the field's vocabulary and mental model, can place the concept they heard, and their question is answered. Concepts are the genuinely load-bearing ones, not padding. The root stays clean; nothing is duplicated.

---

Key design decisions

• Library discipline over one-shot documents. Output is shelved by classification, never dumped into the root. Without this, repeated use just makes clutter.
• Two memory systems, one home per fact (see above).
• Organic taxonomy. Shelves grow from the concepts you actually explore; sub-areas appear only when a field earns them. No empty folders, no forced fits.
• Notice-and-confirm reorganization. When a shelf gets crowded the agent proposes a split and waits -- it never relocates files silently.
• Capability gate, not capability claim. One runtime self-check picks Library Mode (disk) or Session Mode (inline), so file I/O is never faked.
• English-canonical, localized on demand. One source-of-truth version per concept, in English; translations are faithful copies filed under <field>/<lang>/ and matched back to the canonical by ASCII slug + aliases -- so a concept asked in any language resolves to its one home, never a duplicate.
• Machine-readable library. Concept files and maps carry YAML frontmatter (field, tier, related, aliases, translations, updated); INDEX.md uses stable relative links -- so the library is parseable by search, RAG, and other agents, not only humans.

---

File manifest

Entry files (content-equivalent; identity differs)

File	Agent
CLAUDE.md	Claude (Anthropic)
AGENTS.md	Codex (OpenAI, or other AGENTS.md agents)
GEMINI.md	Gemini (Google)

.workflow-references/ (companion files, read on demand)

File	Purpose
library-discipline.md	Steps 3, 6: layout, classification rules, INDEX.md catalog, Library Ceiling Check, Session Mode
field-mapping-method.md	Steps 4, 5: concept selection, tiering, mental model, output templates
glossary.md	Controlled vocabulary for term consistency
GIT_WORKFLOW.md	Git conventions for versioning the library: commit format, branch naming, merge, repo init

Root

File	Purpose
knowledge/	The library -- catalog + mapped fields (grows as you use the repo)
MEMORY.md	The agent's operational memory (learning profile, classifications, calibration)
llms.txt	Machine-readable package manifest
LICENSE	MIT license -- terms for reusing this repo
README.md	This file

---

License

Released under the MIT License -- see LICENSE. You are free to use, copy, modify, and share this repo, including commercially; just keep the copyright notice. (c) 2026 Josh Chung.

---

Known limitations

• Concept-selection quality depends on the underlying model's knowledge of the field. The prompt enforces honesty and prioritization discipline but cannot supply expertise the model lacks.
• The Library Ceiling Check threshold (~8 loose concepts) is a heuristic; a future iteration could let you tune it.
• GIT_WORKFLOW.md ships a Solo workflow tuned for a personal library. If the library becomes shared/collaborative, Part C of that file is the graduation pointer to full Team apparatus (branch protection, PR review, CI).

Possible additions: a spaced-review / quiz mode over the Core tier, and an explicit "map an adjacent field and link the shelves" command.