Mathematical notes as Markdown files

#One folder, plain files

A project is a folder on your Mac. Every definition, lemma, theorem and conjecture is its own Markdown file with a little YAML at the top. Everything that matters to the mathematics is in those files; the search index and the graph cache are derived from them and can be deleted and rebuilt.

That means you can open the folder in any editor, keep it in git, sync it however you like, and point an AI agent such as Claude Code or Codex at it. If you've used Obsidian, it's the same idea: your notes are files you own, and the app is a way to read and work on them.

#What is in it

MyProject/
  project.json          name, creation date, format version
  notation.md           notation and conventions; every agent reads it
  macros.tex            your LaTeX macros
  memory.md             research memory: goals, what was tried, what failed
  theory/<id>.md        one item per file
  figures/<id>.png      a figure's image, and <id>.py, the script that drew it
  documents/<slug>/     a file kept with the project: original, full text, metadata
  plans/                research plans
  programs/             research programs and their reports
  sessions/             chat transcripts and run records
  artifacts/            the scripts and outputs behind every computation
  graph.json            derived: dependency edges
  index.sqlite          derived: search index

A minimal project needs only project.json and a theory/ folder.

#An item

This is theory/thm-closed-graph.md from the example project:

---
id: thm-closed-graph
type: theorem
name: Closed graph theorem
status: proof-drafted
depends_on: [def-graph-of-an-operator, lem-products-of-banach-spaces, lem-closed-subspaces-are-banach, cor-bounded-inverse]
tags: [operator, closed-graph, boundedness, banach-space]
section: closed-graphs
---
## Statement
Let $X$ and $Y$ be Banach spaces and let $T:X\to Y$ be an everywhere-defined
linear map. If its graph is closed, then $T$ is bounded.

## Proof
By Lemma~\ref{lem:product}, $X\times Y$ is Banach. …

Field	Meaning
id	Stable identifier, also the file name. Agents and other items refer to it
type	What kind of statement it is (below)
name	The name you see in the library and the graph
status	How much evidence exists (below)
depends_on	The ids this item uses. Attached sources are cited as source-slug:item-id
tags	Free-form keywords
section	The section it belongs to, as a slug
source, order	Where an imported item came from, and its position in the section

The body is Markdown with LaTeX: $…$, \[…\] and the common environments. Your macros from macros.tex apply everywhere.

#Types

Definitions and axioms: definition, axiom, postulate. Results: theorem, main-theorem, corollary, lemma, proposition, claim, fact, observation, identity, inequality, formula, law, principle, algorithm. Open statements: conjecture, hypothesis, problem, open-problem, question. Notes: remark, example, exercise. And figure, whose image lives in figures/.

#Statuses

Status	Value in the file	Who can set it
Conjecture	conjecture	You or an agent
Tested	tested	You or an agent
Proof drafted	proof-drafted	You or an agent
Review found no errors	reviewed-no-errors	You or an agent
Human approved	human-approved	Only you
Cited literature	source	Only you
Formally verified	formally-verified	Only you
Illustration	illustration	For figures, which assert nothing

#Working on it with other tools

• Git works as it does for any text: each item is a small file, so diffs are readable.
• Any editor can change any file. Manifield picks up new files and whole-file saves. Some editors and agents write a file in place instead, and Manifield doesn't notice those yet; use Reload in the toolbar.
• AI agents can read and write the folder directly. Give them this page: the format above is all they need. A file with an unknown type or status is skipped when the library loads, and Manifield doesn't yet show which files were skipped, so check that a new item appears.

Both gaps are on the list to fix.

#Why plain files

Mathematicians work in LaTeX and on paper; AI agents work in folders of text files. Manifield keeps the theory in the format both can use, and shows it through an interface a mathematician actually wants to read. Nothing important lives in a hidden database or a chat log that only one of them can see.