A development kit for building the operating system of a self.
selfOS is a blueprint, a toolkit, and a set of agent protocols for turning your entire digital footprint — email archives, chat exports, photos, documents, financial records, app data — into two things:
- A self-knowledge repository: a queryable, machine-readable knowledge base of your life. Any AI can retrieve any fact about you, with dates, places, and evidence.
- A twin: a simulation of you, built on your factual history, your verbatim writings, your inner patterns, and actively elicited material — something you (or the people you choose) can talk to.
You don't run selfOS like an app. You clone it, point a coding agent (Claude Code or equivalent) at the repo, and the agent bootstraps your instance: it interviews you, sets up your data lake, and starts ingesting your first export by following the protocols in this repo. The kit is the accumulated structure — architecture, pipelines, agent skills, and hard-won safety rules — so you don't have to discover them the slow way.
Data enters on two branches: mining (everything that already exists — exports, drives, chats, documents, ongoing sync jobs) and elicitation (deliberately created data: instrument batteries, structured interviews — because the archive says what you did, and elicitation says who you are). Everything lands raw and immutable in bronze, passes relevance and privacy gates (local models decide what never reaches a cloud API), and is extracted by cheap agent swarms into claims — the system's core unit.
A claim is a grounded assertion in one of two kinds: an event (external: trips, jobs, purchases) or an appraisal (internal: tastes, beliefs, patterns — hypotheses with evidence, never truths). Every claim carries a confidence tier (stated > documentary > parsed > inferred) and an orthogonal salience tier (how much it matters — trivia is demoted, never deleted):
A standing adjudication stage merges duplicates, finds contradictions, and refers what it can't resolve back to you: your rulings return as the highest grade of evidence there is. Above that, a frontier model synthesizes the gold layer (biography, person model, topic briefs), and audience-scoped views (self / partner / friends / public) decide what any twin or exposed application is compiled from — a public view contains no third-party-derived content by construction.
The reasoning behind each choice: fourteen ADRs.
selfOS is the generalization of VladOS, a working instance built by Vlad Gheorghe over an intensive period in 2026. Starting from a ~250GB digital footprint (Google Takeout, three Gmail accounts, Telegram, ChatGPT and Claude histories, LinkedIn, Spotify, Amazon, scanned documents, therapy transcripts, a decade of photos), VladOS grew into:
- 36,000+ structured claims with full provenance, timestamps, and confidence tiers, all embedded and searchable
- 48,000+ photos captioned with OCR, scene, and salience metadata; face clusters extracted locally
- ~2,000 documents in a registered, audited repository with vision-read transcripts — the engine of a bureaucracy assistant that actually works
- 413,000 chat messages across 51,000 embedded sessions
- A psyche layer: 1,000+ era-stamped, quote-anchored appraisals distilled from therapy transcripts, private writings, and conversations
- A working twin on Telegram, built on a hosted agent, with a feedback loop and eval battery
None of that content is in this repo — that's the point. What is here is everything that made it work: the architecture, the claims model, the enrichment protocols, the agent skills, the privacy discipline — and a catalog of pitfalls, each one paid for in the original instance, with the guard that prevents it.
| Piece | Where | What it gives you |
|---|---|---|
| Vision & architecture | docs/ | The three-layer vision, medallion lakehouse, claims model, gold layer, psyche layer, twin design — with charts |
| Decisions | docs/decisions/ | 14 ADRs from the working instance — the choices that mattered, including the v2 revision (claims, salience, adjudication, gates, views) |
| Privacy guide | docs/privacy.md | Threat model, data hygiene, third-party data, agent-safety rules. Read before ingesting anything. |
| Pitfalls | docs/pitfalls.md | What can go wrong — data safety, agent operations, cost, exposure — and the guard for each |
| Agent skills | .claude/skills/, .agents/skills/ |
Seven protocols your agent follows: setup, enrich, oracle, record, twin, images, voice |
| Pipelines & connectors | src/selfos/ |
Parsers for common exports (Takeout, Gmail, Telegram, ChatGPT, Claude, LinkedIn, Spotify, Amazon, photos, documents); extraction, embedding, publishing, search |
| Getting started | docs/getting-started.md | Clone → agent → interview → first ingestion |
The personal-data-plus-AI space is busy; here's the rough map, so you can tell what selfOS is and isn't before cloning:
| If you want | Look at | selfOS instead |
|---|---|---|
| Chat with your notes and documents | Khoj, AnythingLLM, Open WebUI | Ingests your whole export corpus and derives structured claims from it, rather than indexing curated content |
| Ambient screen/audio capture | Screenpipe, Omi, ActivityWatch | Captures nothing passively; ingests exports (including recorder outputs) through gates you control |
| Memory infrastructure for AI apps | mem0, Zep/Graphiti, Letta | Not an SDK — a personal data system operated by your coding agent, with its own evidence model |
| Export importers and timelines | HPI, Timelinize, Dogsheep, MemryLab | The closest relatives; selfOS adds the claims layer, elicitation, the twin, and its evaluation on top of that idea |
| A hosted twin of yourself | Delphi, Personal.ai | Local, MIT-licensed, inspectable; nobody hosts your data because there is no host |
Most of the ingredients exist elsewhere in some shape; selfOS is one working combination of them — export mining, claims with provenance and salience, elicitation, a twin, and the evaluation to check it — packaged as protocols an agent can run.
- No personal data in git.
data/and.envare gitignored; skills and docs describe structure, never content. - Bring your own everything. DuckDB + parquet locally is the default; any Postgres, any S3-compatible bucket, any LLM provider if and when you want a serving layer. Nothing is tied to a specific vendor.
- Docs-first. Decisions are immutable ADRs; the journal is append-only; agents record what they did.
- Protocols over improvisation. Agents follow the established protocols; new source types get new protocols, proposed to you first.
- Canonical stores are additive. Publishes upsert, never truncate; deletion needs an explicit flag and a human yes; rollback snapshots are standing.
- Simplest thing that serves the vision. The vision is fixed; the architecture is provisional.
- Cost discipline. Most of a corpus needs no LLM at all; small models for bulk extraction; frontier models only for synthesis and the twin.
git clone https://github.com/vlad-ds/selfos my-selfos
cd my-selfos
claude # or your coding agent of choice
> "Set me up. Read the setup skill and interview me."
Full walkthrough in docs/getting-started.md. Read docs/privacy.md first — you're about to concentrate the most sensitive dataset that exists about you, and the guide is the distilled experience of doing exactly that.
The archive says what you did; elicitation captures what it can't — values, trade-offs, self-image, the answers to questions life never asked you directly. The kit includes a local web app for taking a structured interview battery:
python -m selfos.elicit # serves a localhost GUI, stdlib-only, no dependencies
Battery sessions are plain markdown files with [ ] answer slots and spoiler-hidden scoring keys, living under gitignored data/bronze/elicitations/battery/. The app renders the right control per item (scales, choices, rank boards, free text), autosaves drafts, and writes dated JSON records when you complete a session.
The kit ships the app and the format, not the test items — many psychological instruments are copyrighted, and your battery (like your answers) belongs under data/, not in a repo. Assemble your own from public-domain pools: the IPIP is public domain by design and covers personality measurement completely; PHQ-9, GAD-7, WHO-5, SWLS and the Moral Foundations Questionnaire are freely usable with attribution; the highest-value modules (structured life-story interviews, trade-off probes, twin-calibration banks) you write yourself with your agent. Full guidance, including the sealed-prediction protocol that turns every session into twin ground truth: docs/architecture/elicitation.md.
selfOS is also an instrument. With a sealed elicitation battery (your answers recorded before any twin exists), it supports experiments the original instance is now running: how well can models predict a person's psychometric responses, and from which sources? Can people close to you tell your answers from your twin's? How accurate is your own memory of your life, measured against your archive? And the headline question — how many tokens is a self? Results will be published as they land.
Extracted from a living, working instance. The architecture is real and battle-tested; the generalization is young, and the code implements v1 of the claims model in places (see the v2 ADRs for the migration path). Issues and PRs welcome — see CONTRIBUTING.md. Licensed MIT.