Trophe

A local nutrition journal for people and their agents.

Trophe comes from Ancient Greek τροφή (trophē): nourishment or food. Dictionary source.

Tell your agent what you ate, show it a label or meal photo, or ask how your week looks. The agent interprets the request. Trophe stores the evidence, checks the records, and does the arithmetic.

Design

your agent ── CLI or MCP ── validated actions ── Markdown files
     │
     └── its own vision and web tools, when needed

• Markdown with YAML front matter is the source of truth: profile, saved foods, meal logs, assumptions, and notes.

• One TypeScript core handles validation, serving calculations, and date totals.

• No account, application server, built-in model, API key, or database service.

• The CLI and MCP server expose the same operations and input schemas.

• Food edits do not alter past meals. Each logged item stores a nutrition snapshot.

• Estimates stay marked as estimates. Missing nutrients stay null.

There is no SQLite layer in this first version. A personal journal is small enough to read directly. If indexing becomes useful, it can be rebuilt from the files.

Related MCP server: Food Tracker MCP Server

Start

Requires Node.js 22 or newer and Yarn 4.14.1.

yarn install
yarn build

# Default data location: ~/.trophe
yarn trophe init --timezone America/Toronto
yarn trophe food put --input examples/food.json
yarn trophe meal log --input examples/meal.json
yarn trophe day 2026-09-21
yarn trophe validate

The examples are fictional. They are added only when you run these commands. To use a separate example journal, add --data ./data to every command. TROPHE_HOME can also set a fixed data directory. An absolute path is best in agent configuration. Opening a missing journal fails; only init creates one.

The executable is node /absolute/path/to/trophe/dist/cli.js. yarn trophe is a repository shortcut. Command results are JSON, or raw NDJSON for NDJSON exports. Errors go to stderr.

Commands

Use tools to print all tool argument schemas. schema prints the stored record schemas. call <tool> --json '{...}' invokes any shared action directly. --input - reads JSON from stdin. JSON input files contain the full tool arguments: for example, { "meal": { ... } }.

Native NDJSON export

yarn trophe export ndjson > journal.ndjson

This exports the profile, all saved foods, and all meals, including void records. Each line is one complete native record with schema_version, kind, and notes. Targets, evidence, unknown values (null), and known zero values are preserved. There is no outer array or revision envelope. The MCP tool export_ndjson takes no arguments and returns the same raw text.

The export reads the whole journal; it has no date filter. Attachment references in notes are included, but attachment files are not. See SCHEMA.md for ordering and format details. Markdown remains the source of truth.

FHIR export

# Export all logged meals. Supply the ID for the journal's subject.
yarn trophe export fhir5 --patient-id example-person > nutrition.fhir.json

# Optional inclusive dates use the journal's configured timezone.
yarn trophe export fhir5 --patient-id example-person \
  --from 2026-09-01 --to 2026-09-30 > september.fhir.json

# FHIR NDJSON uses one resource type per file.
yarn trophe export fhir5 --patient-id example-person \
  --format ndjson --resource-type Patient > Patient.ndjson
yarn trophe export fhir5 --patient-id example-person \
  --format ndjson --resource-type NutritionIntake > NutritionIntake.ndjson

The default output is a native FHIR R5 Bundle of type collection: a minimal Patient and one NutritionIntake per logged meal. Each intake contains NutritionProduct snapshots with the consumed portions, nutrition values, sources, and assumptions. Voided meals are included with status: entered-in-error. Export only reads local records; it does not upload data or require a FHIR server.

With --format ndjson, the output is one FHIR resource per line. Select Patient or NutritionIntake with --resource-type. The same MCP tool accepts "format": "ndjson" and "resource_type": "Patient" or "NutritionIntake".

Use a stable patient ID that you choose for this journal. Trophe does not infer demographics or match the subject to an external patient record. The export covers meal history; unused saved foods and profile targets are not included. See FHIR.md for mappings, units, identity, and export limits, and examples/fhir-bundle.json for a fictional example.

Agent setup

Give your agent SKILL.md and the absolute command and data paths. Agents with shell access can use the CLI. Agents with MCP support can use:

{
  "mcpServers": {
    "trophe": {
      "command": "node",
      "args": [
        "/absolute/path/to/trophe/dist/cli.js",
        "mcp",
        "--data",
        "/absolute/path/to/your/nutrition-journal"
      ]
    }
  }
}

The server uses stdio. It opens no network port. It exposes the guide as trophe://guide, the schema explanation as trophe://schema-guide, and generated JSON Schemas as trophe://schemas. The FHIR export guide is trophe://fhir-guide.

Photo interpretation and online food lookup use the host agent's capabilities. Trophe itself does not call a model or nutrition provider. An agent can save photo references and source links in the Markdown notes, with files in attachments/. Using an external agent or web tool can share the information you give it; local storage does not make those external services local.

Data you can read

~/.trophe/
├── profile.md
├── foods/
│   └── example-yogurt.md
├── journal/
│   └── 2026-09-21-breakfast.md
└── attachments/

Read SCHEMA.md for the record format and examples/meal.md for a full meal record. You can edit Markdown directly; run validate afterward. Stop concurrent tools before manual edits. Back up the whole data directory with your preferred file backup tool. Personal data is separate from the code and is not pushed by this repository.

Tool writes use an exclusive directory lock and an atomic file replacement. Updates require the SHA-256 revision returned by a read. This prevents one tool from overwriting another tool's edits. Repeating an identical write is safe. A changed payload with an existing ID fails until an explicit update is made.

If a process crashes while holding .write-lock, stop all Trophe writers and remove that empty lock directory before retrying. The lock protects cooperating Trophe processes; external editors must not write concurrently. Records are current state, not a full revision archive. Backups preserve older versions.

Totals and targets

The profile timezone determines the day for a timestamp, including daylight saving time. Targets have effective dates. A report uses the target in effect on each day. Changing the profile timezone regroups historical timestamps into that timezone.

Each nutrient reports a known subtotal, unknown_items, and whether the value is complete for the logged items. This does not mean every meal was logged. remaining is null if a nutrient is unknown or no target exists. An empty day has logged: false; it is not treated as a confirmed fast. Estimates are counted separately. Voided meals remain readable but are excluded from totals.

Development

yarn check
yarn test

The tests cover persisted records, duplicate retries, serving calculations, corrections, unknown values, local dates, malformed files, CLI behavior, and real MCP client/server calls. See AGENTS.md for development conventions.

This initial version covers saved foods, meal logging, dated targets, and daily or period summaries. Recipes can be saved as foods with known per-serving values. Automatic recipe calculation, barcode lookup, body measurements, synchronization, and a graphical interface are outside the initial scope.

License

MIT. Copyright (c) 2026 Flexpa.