Persome: Build your Personal Model

The open-source Personal Model that makes every AI yours.

Persome learns how you actually think and work from focused activity captured on your Mac after you grant macOS permission—then gives Codex, Claude Code, and other trusted MCP-compatible clients evidence-linked context to continue your work and make grounded decisions.

Runs locally on your Mac. Private by default. Yours to inspect, correct, export, and delete.

Try the synthetic demo · Install with your data · Connect an MCP client · Star Persome on GitHub

Concept illustration of a mature Personal Model. The deterministic Runtime proof is shown in the demo below.

What is it?

Your HUMAN.md

Persome connects activity into progressively deeper context:

New evidence can strengthen, revise, or overturn an earlier inference. Every important claim keeps receipts.

Use cases

1. One Root — A Model of You

Thousands of moments. One evolving model of you.

Persome turns sourced observations into relationships, patterns, higher-order structure, and one current Root: what matters now, how you tend to decide, and where your attention is moving.

From Points to Lines, Faces, Volumes, and one Root—a living model of who you are and what matters now.

2. Same AI. Different You.

The model is the same. The person it understands is different.

Two people can give the same AI the same prompt and deserve different answers. Your Personal Model changes how an agent prioritizes, decides, writes, and acts—because it understands who it is working for.

The same prompt should not produce the same answer for everyone. Give AI a model of you.

3. One MCP — Turn coding agents into proactive agents

Your coding agent finds its own work

Connect Persome once through MCP. Codex, Claude Code, and other trusted agents can use the same model of your goals, priorities, working patterns, and boundaries.

Persome identifies unfinished work, ranks it against your priorities, and separates safe local tasks from decisions that need you. The connected agent executes; you keep authority over external actions.

Continue where you left off

Work while you sleep

Install, connect, and verify

Choose the path that matches what you want to prove. The synthetic demo and the real-data install are intentionally separate.

1. Five-minute synthetic demo

Try the complete Persome model without touching your personal data. This path requires Git and uv, but no API key, macOS Accessibility permission, or access to your existing ~/.persome data.

git clone https://github.com/Intuition-Lab/personal-model.git
cd personal-model
uv run python scripts/sample_demo.py

The script opens the local viewer at http://127.0.0.1:8743/model and deletes its temporary synthetic data when you press Ctrl-C. Add --showcase for the denser, still fully synthetic graph shown below.

Actual /model screenshot produced by scripts/sample_demo.py --showcase: 424 synthetic Points, 146 Lines, 12 Faces, 4 Volumes, and 1 Root. It contains no personal data.

2. Install with your data

Requirements: macOS 13 or newer and Xcode Command Line Tools. For the shortest package-managed installation:

uv tool install personal-model
persome onboard
persome model open --after 30

The distribution is named personal-model; the installed CLI is persome.

For the most explicit source-based first run:

git clone https://github.com/Intuition-Lab/personal-model.git
cd personal-model
bash install.sh

After successful interactive onboarding, the source installer schedules the one-shot 30-minute viewer reminder automatically.

What onboarding proves

• persome onboard explains each macOS request before it appears.
• Accessibility is granted to the versioned mac-ax-helper and, only when event-driven capture is enabled, mac-ax-watcher.
• Screen Recording is requested only when the effective screenshot or local-OCR policy requires pixels. Persome never requires Full Disk Access.
• On Apple Silicon, local OCR uses bundled PP-OCRv6; on Intel, it uses the macOS Apple Vision framework. Onboarding verifies the isolated worker on both architectures.
• Unified localhost onboarding offers a read-only, multi-source import and builds the first model from existing Markdown history. Local folders are always available; Obsidian and Notion appear only when detected on the Mac. The same sources remain available through persome import-data; see the import guide.
• It proves the final lifecycle owner and Runtime generation, then reports a fresh-capture receipt in standard daemon mode or an explicit readiness/privacy receipt for supported alternate modes such as trusted ingest.

An LLM is optional for collection and BM25 recall, but required for semantic modeling. You can configure a hosted/local provider for unattended processing:

persome llm setup
persome llm status --check

Alternatively, explicitly lend an existing coding-agent subscription to the background Runtime. The client CLI keeps and refreshes its own login; Persome stores only its executable path, routing policy, and a durable daily call cap:

persome llm agent setup --client codex --daily-call-limit 50 --check
# also supported: claude-code, cursor-agent
persome llm status

A trusted MCP client that supports Sampling with tools can still call process_pending_model_work for a one-request, 1–10-session batch. Both paths use the connected agent allowance without exposing its OAuth token to Persome; the CLI bridge is the opt-in path that also powers unattended stages.

3. Connect a trusted MCP client

Register whichever owner-local clients you use:

persome install claude-code --fund-model
persome install codex --fund-model
persome install cursor-agent --fund-model
persome install claude-desktop
persome install opencode

--fund-model is explicit consent to let background semantic stages consume the client's subscription, with a default cap of 50 model invocations per local day. Omit it to install only the MCP server, or change the cap with --daily-call-limit. persome llm agent disable revokes that consent without logging the client out or deleting a fallback provider profile.

These stdio registrations launch the MCP process on demand, so the daemon does not need to be running after onboarding has initialized the local database, and no HTTP bearer is copied into client configuration. Schema creation and migration remain daemon-owned; a brand-new or externally upgraded data root must run persome start once before stdio clients use it. Stdio writes remain available while the daemon is stopped, but WAL maintenance waits for the daemon; start it periodically if you use write tools in that mode so the WAL stays bounded.

For another Cursor-compatible setup, you can still generate a stdio object and merge mcpServers.persome manually:

persome install mcp-json --filename persome-mcp.json

MCP access is a personal-data capability; register only clients you trust.

4. Verify and ask grounded questions

persome status
persome model status
persome model open

# Only if you configured a semantic provider:
persome llm status --check

A sparse or degraded model can be valid early; Persome reports missing geometry instead of fabricating Faces, Volumes, or a Root.

After connecting an MCP client, try:

Search my Persome memory for [topic]. Use search, open the strongest result with read_receipt, and cite the source path, timestamp, and receipt ID. If the evidence is missing or conflicting, say so instead of guessing.

Active work is reduced every five minutes by default. With valid capture and a working semantic provider, a first useful recall is operationally expected within about ten minutes—not guaranteed as a benchmark result.

5. Update Persome

For a uv tool installation, upgrade with the package manager and re-run Runtime proof:

uv tool upgrade --python 3.12 personal-model
persome onboard
persome model open --after 30

After any upgrade, restart editors that host a Persome stdio MCP process before resuming Runtime writes. A process loaded from the previous release cannot join the new cross-process SQLite maintenance gate until the editor reconnects it.

For an installation created by install.sh, run the transactional updater from any directory:

persome update

persome update preserves configuration, credentials, personal data, capture policy, and lifecycle intent, and performs its own mode-aware onboarding before committing the update. Do not use it to update a package-manager-managed installation.