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

```bash
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:

```bash
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](SPEC.md) 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](docs/migration-v1.md)).

The [conformance corpus](conformance/) 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

```json
{
  "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](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](https://github.com/paperdavid/manoma/issues). MIT / CC0.