Docs / usage / first-atom

First atom

1. Make a workspace

mkdir my-prime && cd my-prime
mkdir -p primes/sources/@my

2. Write the first atom (a fact)

Save as primes/sources/@my/fact-water-boils-at-100c.prime:

fact WaterBoilsAt100C {
  id: "@my/fact-water-boils-at-100c"
  version: "1.0.0"
  description: "Pure water boils at 100°C at 1 atm."
  domain: physics

  statement: "At one atmosphere of pressure, pure water boils at 100°C (212°F)."
  confidence: 0.99
}

3. Write a term it uses

Save as primes/sources/@my/term-celsius.prime:

term Celsius {
  id: "@my/term-celsius"
  version: "1.0.0"
  description: "A unit of temperature where 0° = water freezing at 1 atm."
  domain: physics

  definition: "A temperature scale on which 0° is the freezing point of water and 100° is its boiling point at 1 atmosphere."
}

4. Write a rule that requires both

Save as primes/sources/@my/rule-altitude-affects-boiling.prime:

rule AltitudeAffectsBoiling {
  id: "@my/rule-altitude-affects-boiling"
  version: "1.0.0"
  description: "Boiling point drops ~0.3°C per 100 m of altitude."
  domain: physics

  claim: "Above 1 atm, water boils below 100°C; the loss is ~0.3°C per 100 m."
  applies-to: [cooking, climbing, science]
  severity: informational

  requires: [
    @my/term-celsius,
    @my/fact-water-boils-at-100c,
  ]

  validates-with: [
    @my/source-nist-water-properties,
  ]
}

5. Compile

The directory-level compile script lives inside the prime-system repo (see Install). Run it from there, pointing --src / --out at this workspace:

# Run from inside your prime-system clone
bun /abs/path/to/prime-system/scripts/build-atom-dirs.ts \
  --src /abs/path/to/my-prime/primes/sources \
  --out /abs/path/to/my-prime/primes/compiled

# → output:
#   primes/compiled/@my/fact-water-boils-at-100c/{atom.yaml, chunks/}
#   primes/compiled/@my/term-celsius/{atom.yaml, chunks/}
#   primes/compiled/@my/rule-altitude-affects-boiling/{atom.yaml, chunks/}
#   primes/compiled/_index.xml

Note: a first-class prime compile --dir <src> --out <dst> subcommand is on the roadmap and will replace the script invocation above.

L1 catches the missing @my/source-nist-water-properties reference (you haven't authored it). Two ways to handle:

1. Author it, or
2. Drop the validates-with line for now and re-compile.

6. Inspect

prime list --dir primes/compiled
# → @my/fact-water-boils-at-100c            fact
# → @my/term-celsius                        term
# → @my/rule-altitude-affects-boiling       rule

prime show @my/rule-altitude-affects-boiling --dir primes/compiled
# Prints kind, fields, edges out, edges in.

cat primes/compiled/@my/rule-altitude-affects-boiling/chunks/summary.md
# Prints the ~30-token summary.

7. Boot the MCP server

PRIME_DIR=$PWD/primes/compiled \
  bun /abs/path/to/prime-system/packages/mcp-server-core/src/index.ts
# Server up on stdio. Wire it into Claude Code (next page).