About manoma
manoma is a CLI and MCP server for maintaining a portable AI identity in a local soul.md file. It exposes that context to tools and can write decisions and lessons back, with user approval for updates.
Key features
- 01Create soul.md through an interview
- 02Compile identity into tool configurations
- 03Read context and skill depth
- 04Record decisions, lessons, and current focus
- 05Refresh the identity file with approval
Use cases
- 01Provide consistent personal context across AI tools
- 02Keep decisions and lessons in a local identity file
- 03Wire soul.md into a Claude Code configuration
MCP support
The MCP server exposes context, skill-depth, and section queries to MCP clients, along with tools for writing decisions, lessons, and current focus. Writes are provenance-stamped and sanitized.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y manoma-mcpSOUL_MD_PATHPath to your soul.md file. Defaults to ~/soul.md if not set.Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
7Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| mode | string | No | Mode to resolve context for (work, personal, creative, learning). Defaults to active_mode from config. |
Details
From the project READMEsoul.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.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.