io.github.paperdavid/manoma

soul.md

Your identity, not theirs. One plain-text file that tells every AI who you are — and that you own.

soul.md is an open format for your AI identity: values, voice, skills, current focus. It lives on your machine, versions in git, and gets compiled into the tools you use. Manoma is the CLI and MCP server that make it work.

npx manoma init        # create your soul.md
npx manoma interview   # let an AI you already use write it with you
npx manoma compile     # wire it into Claude Code — every session knows you

Two more commands close the loop with your AI's own memory:

npx manoma refresh     # the AI that's been learning about you proposes updates
                       # to your file — your approval required, never silent
npx manoma remember    # save your soul.md INTO the AI's memory, so even plain
                       # chats with zero setup know you

Their memory collects; your file is the owned, current copy.

• User-owned — a file on your machine. No cloud, no account, no vendor.
• Works everywhere — compiled into tool configs, pasted into instruction fields, readable by anything.
• Stays alive — add the MCP server and the AI records decisions and lessons into the file as you work, dated and signed; every change is a git diff.

The format

The specification is one page and public domain (CC0): eight plain-markdown sections, a deterministic grammar, and one invariant — a soul.md must stay useful pasted raw into any prompt. Every file written for the older v1.4 format keeps working (migration guide).

The conformance corpus defines correct parsing; a reader that reproduces its expected outputs is conformant. Parallel implementations are welcome — a Python or Rust parser that passes the corpus is a first-class citizen.

The MCP server

{
  "mcpServers": {
    "manoma": { "command": "npx", "args": ["-y", "manoma-mcp"] }
  }
}

One block in Claude Desktop, Cursor, or any MCP client. Six tools: get_context, get_skill_depth, list_sections, and the write-back trio add_decision / add_lesson / update_now — provenance-stamped, sanitized, disclosed. Details in mcp/README.md.

Repo

manoma/
├── mcp/          — the MCP server + manoma CLI (npm: manoma-mcp, manoma)
├── cli/          — the `manoma` npm name (forwards to manoma-mcp)
├── conformance/  — the normative parsing corpus
├── docs/         — migration guide, archived v1.4 spec
├── templates/    — v1.4-era example files (valid, being modernized)
├── SPEC.md       — the format specification (CC0)
└── LICENSE       — MIT (code)

Philosophy

Every AI vendor keeps its own memory of you, in its own cloud. soul.md is the opposite bet: your identity as a plain file you control, portable between tools, diff-able in git, built to outlive any individual model.

The schema is the thing. The runtime is just how it's read.

Feedback, forks, and parallel implementations welcome — issues. MIT / CC0.