io.github.paperdavid/manoma — MCP server for soul.md

The io.github.paperdavid/manoma MCP server enables MCP-aware LLM clients to read a local soul.md file, described as an open format for an “AI identity.” It is positioned as a portable layer that can be carried between tools and versioned in git.

🛠️ Key Features

soul.md is a plaintext, user-owned file kept on the machine in a repo
Designed to be portable across MCP-aware clients
Presented as a reference MCP server for making LLMs read soul.md
Emphasizes versioning, forkability, and git-diffable identity data

🚀 Use Cases

Keeping an AI identity (values, voice, skills, taste) in a single file
Reusing that identity across tools like Claude Desktop, Cursor, Zenflow, and other MCP-aware clients

⚡ Developer Benefits

Treat identity data as an open, version-controlled format in git
Share or fork the identity format by carrying soul.md between environments

⚠️ Limitations

The provided data does not describe supported operations beyond reading soul.md via MCP clients

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

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.

Repo

code

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.

io.github.paperdavid/manoma