PersonaOS

Your life, remembered. The patterns, surfaced.

PersonaOS is an open-source AI that quietly remembers who you are — the people in your life, the decisions you've made, the goals you've set — and reads it back when it matters. Your memory, on your computer, in plain text files you fully own.

Status: v0.1 — initial public release. Onboarding works end-to-end.

What you get

After a few weeks of conversation, the AI starts noticing things you couldn't see alone:

You've mentioned Anna in seven notes this month. Last time was a year ago. Something shifted.

You set "sleep before midnight" as a value in February. Of your last fourteen sleep entries, eleven were after 1am. Worth revisiting?

You're stuck on the career framing. Three months ago you wrote you wanted to work on "something that matters more than scale." Does that still apply?

It reads back across years of your own writing. You wrote all of this — it just remembered.

Three things make PersonaOS different from a regular AI chat:

1. A memory that's actually yours. Years of who you are — kept on your computer, in plain markdown files you can open in any editor (Obsidian, VS Code, Apple Notes). Nothing locked in a company's cloud. If you stop using PersonaOS tomorrow, you keep everything.

2. Patterns you couldn't see alone. The AI reads across everything you've ever told it — not just the last chat — and tells you what's repeating, drifting, or stuck.

3. It asks before it pushes back. The AI stays gentle by default. If you want it to challenge you on something — your sleep, your career, a habit — you say so once, and only then. You're always in charge of the tone.

Get started

PersonaOS works with any AI agent that auto-loads AGENTS.md or CLAUDE.md. If you don't have one yet, three free options to pick from:

• Claude Code — Anthropic's CLI
• OpenAI Codex CLI — OpenAI's CLI
• opencode — fully open source, MIT

All three install in about five minutes on Mac, Windows, or Linux. Open your agent in any folder and paste this message:

Set up PersonaOS for me. The project is at
https://github.com/serafim-builds/PersonaOS. I'm not a developer —
please walk me through every step, then start the onboarding interview.

The agent clones the project, creates a private folder for your memory, and starts the onboarding interview. About 30 minutes, no setup commands to learn.

If you already have an agent set up

Cursor, Aider, Kimi-CLI, and most other agentic CLIs work too. Clone the repo and start your tool inside the directory:

git clone https://github.com/serafim-builds/PersonaOS.git personaos
cd personaos
# start your agent here — the contract auto-loads

For tools that don't auto-load AGENTS.md or CLAUDE.md, paste the contents of PERSONAOS.md into your tool's system-prompt mechanism manually.

How it works

When you tell the AI something about yourself, your life, or someone you know, it does four things:

1. Notices what kind of thing you mentioned — a person, a goal, a feeling, a decision.
2. Looks up what it already knows in your folder.
3. Decides: save as new, link to something existing, or — if what you said contradicts what was there before — show you a diff and ask which version is right.
4. Saves each accepted fact as its own entry in git history. You can always see exactly what changed and when.

That's the whole protocol. The full technical spec lives in PERSONAOS.md.

Your data

• Default location: .vault/ inside the project folder, gitignored — never leaves your machine.
• Alternative: ~/PersonaOS-vault (anywhere outside the project — onboarding asks).
• Format: plain markdown files with structured frontmatter. Open them in Obsidian, VS Code, Apple Notes — anything that reads .md.
• Has its own git history, separate from the PersonaOS project. Updating PersonaOS never touches your data.
• Override the path via PERSONAOS_VAULT_PATH in .env.

Contributing

Bug reports, cross-tool compatibility reports, and stored view recipes welcome. See CONTRIBUTING.md before opening a feature PR.

License

MIT — see LICENSE.