MANØMA

Documentation

How to create your soul.md, wire it into your tools, and keep it alive.

Quick start

Three commands, no config files:

npx manoma init        # create ~/soul.md (a starter template)
npx manoma interview   # let an AI you already use write it with you
npx manoma compile     # wire it into Claude Code
  1. init creates a starter ~/soul.md — eight plain-markdown sections with visible hints.
  2. interview prints a prompt you paste into your usual ChatGPT or Claude; it interviews you and writes the whole file. (Also available as a web page.)
  3. compile adds a managed block to ~/.claude/CLAUDE.md with a live import of your soul.md. Every new Claude Code session starts already knowing you; edits apply immediately, nothing to re-run. Use --print to preview, --inline for a rendered snapshot.

Keep it alive: the MCP server

The file is the product; the server is its maintenance loop. Add manoma to any MCP-aware client and the AI records decisions, captures lessons, and refreshes your current focus in soul.md as you work — every change a readable git diff.

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

Two companion commands work with your AI's own memory: npx manoma refresh asks an AI that has been learning about you to propose updates to your file (recall, compare, propose — your approval required), and npx manoma remember saves 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.

Want soul.md somewhere else? Set SOUL_MD_PATH in the MCP config env block. A private git repo is the best home (history + sync). Never a public repo — soul.md is personal.

The format

soul.md v2 is a one-page spec: eight sections (/identity /values /voice /skills /now /memory/decisions /memory/lessons /preferences), plain markdown, no configuration syntax. It's designed to stay useful pasted raw into any tool, and every file written for the older v1.4 format keeps working unchanged. The spec and its conformance fixtures are public domain (CC0) — implementations welcome.

Read the spec →

Templates

Prefer starting from a pre-filled example? Pick your role — the interview usually produces something more you, but these show what a finished file looks like.