Why I Am Building Manoma

Fifty First Sessions

Every new AI session starts the same way. The model does not know who I am, what I do, or how I want to be spoken to. So I explain. Again.

I run Claude Code, Cursor, and a handful of agents. Each tool keeps its own memory, in its own format, on someone else's servers. None of them share. Switch tools and you start from zero.

Then it clicked: the vendors like it this way. Your memory is their retention feature. The more an assistant knows about you, the harder it is to leave. That is not memory. That is a moat, and you are the water.

What soul.md Is

soul.md is a plaintext file that describes you to an AI: who you are, what you value, how you want to be spoken to, what you are good at, and what you are doing now.

Eight sections: /identity, /values, /voice, /skills, /now, /memory/decisions, /memory/lessons, /preferences.

It lives at ~/soul.md. It is versioned in git. You can read every line, edit every line, delete every line. It is a file, not a service. That is the point.

What Manoma Is

Manoma is the tooling around the format.

npx manoma init interviews you and writes your first soul.md. manoma compile pushes the file into each AI tool's own config, so the AI knows you every session without relying on it remembering to look.

The MCP server keeps the file alive. As you work, it records your decisions and lessons back into the file. Every line the AI writes is stamped with the date and the tool that wrote it. A git diff always shows which words are yours and which are the machine's.

The Manifesto

Your identity is not a vendor feature. Every AI company is building memory right now, and every one of them is building it inside their own walls. soul.md is the opposite bet: your identity as a file you control, interchangeable between tools, outliving any individual model.

A file beats a service. A file has no uptime, no account, no terms of service, no acquisition risk. It cannot be deprecated. It cannot leak from a server, because it never lived on one. Everything a memory service promises, a file in git delivers with less.

Dump-safe or wrong. The whole file has to work when pasted raw into any model prompt. No preprocessing, no runtime, no magic. This is the design rule for the entire format: if a feature would make a naively pasted soul.md worse, the feature is wrong. It has killed several clever features already. Good.

You always know who wrote what. AI write-back is useful and dangerous in equal parts. So every AI-written entry carries a stamp, and git history holds the receipts. An identity file where you cannot tell your own words from the machine's is not yours anymore.

Nothing is deleted silently. When memory sections fill up and old entries rotate out, the tool says so, and the entries move to an archive file instead of disappearing. A tool built on "your property" does not quietly throw your property away.

Private by default. The file can hold notes about other people. Those never get compiled into configs or auto-loaded into conversations unless you explicitly opt in. The most sensitive content gets the most conservative default.

Built to outlive models. Models change every quarter. The schema is the thing; the runtime is just how it gets read. The spec is public domain, the reference implementation is MIT, and parallel implementations are welcome. If Manoma disappears tomorrow, your soul.md still works, pasted into anything.

Where It Stands

The v2 spec is frozen and implemented by the reference MCP server. Starter templates exist for founders, engineers, designers, and PMs.

The repo is public: github.com/paperdavid/manoma.

My own soul.md wrote parts of this post's voice. That is the product working.