# Mathematical notes as Markdown files

Keep mathematical research in plain Markdown: definitions, proofs, dependencies and notation that you can read in Manifield and work on with AI agents.

## 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:

```markdown
---
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.