Persome

Persome

The local-first Personal Model Runtime for macOS. Persome observes the appsyou already use, turns cross-app activity into an inspectable model of a realperson, and serves that model to MCP agents.

Star Persome on GitHub tofollow the Runtime and help prioritize the next MCP integrations.

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

Product job

Persome runs quietly on one Mac and does four jobs:

1. Collect focused macOS Accessibility (AX) context across apps, with anoptional on-device OCR fallback for AX-poor surfaces.
2. Model observations into sourced facts, evolving relations, stablepatterns, cross-domain structure, and one current Root.
3. Serve local memory and model tools over MCP.
4. Give control back through receipts, time travel, correction, export, anddeletion.

This is the Runtime, not a hosted account or a single assistant's privatememory. One local model can be used by Claude Code, Codex, Cursor, or anothertrusted MCP client.

Five-minute sample demo

See the whole model without an API key, Accessibility permission, or access toyour real ~/.persome data. This path requires Git anduv:

git clone https://github.com/Persome-ai/persome-core.git
cd persome-core
uv run python scripts/sample_demo.py

Add --showcase to render the denser, still fully synthetic model used in theREADME image.

The script opens http://127.0.0.1:8743/model, serves MCP athttp://127.0.0.1:8743/mcp, and deletes its temporary synthetic data when youpress Ctrl-C. To inspect the exact search, receipt, and snapshot payloads:

PERSOME_LLM_MOCK=1 uv run python scripts/sample_demo.py --json

With the sample server still running, verify the actual MCP transport from asecond terminal:

uv run python scripts/verify_sample_mcp.py

This sample path is deliberately separate from the real-data path below.

Quick start with your data

Requirements: macOS 13 or newer, Xcode Command Line Tools, and a Python buildwith SQLite 3.42+ (the installer verifies the secure FTS capability). The installerfinds or installs uv, provisions Python 3.11-3.13, compiles the Swift AXhelpers, generates the local screenshot-encryption key, enables and verifieslocal OCR, and offers to register detected MCP clients. Before it reportssuccess, a native onboarding flow explains and requests Accessibility andScreen Recording separately, starts Persome, checks local health, and writes afresh capture. Its fallback uv download is version-pinned and checkedagainst repository-pinned SHA-256 digests; the Runtime environment is installedfrom the committed uv.lock, and the complete build-backend closure ishash-constrained rather than resolved afresh.

git clone https://github.com/Persome-ai/persome-core.git
cd persome-core
bash install.sh

persome doctor
persome onboard
persome ocr status --check
persome model open

persome onboard is the repeatable recovery path. It shows one plain-languagemacOS dialog before each system permission request and does not complete untilAccessibility and Screen Recording are granted. It then verifies theisolated OCR worker, leaves the daemon running, polls GET /health, and forcesone fresh capture. OCR supplies text for AX-poor apps such as WeChat and Feishu;pixels never enter an LLM prompt. Persome does not require Full Disk Access.

# Recheck or repair OCR onboarding; disable is always explicit and reversible.
persome onboard
persome ocr setup
persome ocr status --check
persome ocr disable

An LLM is optional for collection and BM25 recall, but required for semanticmodeling. During installation, the provider wizard asks you to choose a serviceand enter its API key. Persome supplies that provider's endpoint and defaultmodel, tests completion and tool calling, and only then saves the route. Existingkeys are detected automatically. API keys go to the owner-only~/.persome/env file under the provider-neutral PERSOME_LLM_API_KEY name;provider-specific environment variables are import sources only. The non-secretroute goes to ~/.persome/config.toml. Nothing ships with a key.

# If provider setup was skipped during installation:
persome llm providers
persome llm setup
persome llm status --check

# Restart after changing the active provider:
persome stop || true
persome start

Persome speaks two wire protocols: native Anthropic Messages andOpenAI-compatible Chat Completions. Presets cover Anthropic, OpenAI, DeepSeek,OpenRouter, Gemini, Groq, Mistral, xAI, Qwen, Moonshot/Kimi, Zhipu GLM,SiliconFlow, Together, Fireworks, Cerebras, Azure OpenAI, Ollama, LM Studio, andvLLM. custom-openai and custom-anthropic accept another compatible endpoint.Azure and custom endpoints use a clearly marked advanced setup path. A presetmeans the route is configured, not that every model has the necessarycapabilities; Persome warns when the default model cannot call tools.

Active work is reduced every five minutes by default. A first useful recall istherefore expected within ten minutes of valid capture plus a working semanticprovider; persome status, persome model status, and the viewer explain sparseor degraded states instead of inventing geometry.

Proof points

Local-first

• Durable Markdown, SQLite/FTS5, model snapshots, and logs live under~/.persome unless PERSOME_ROOT is set.
• AX is the default signal. Optional PP-OCRv6 runs locally in an isolatedsubprocess with bundled weights.
• The HTTP/MCP server is restricted to loopback (127.0.0.1 by default), requires an owner-localbearer on API/MCP routes (or its one-use derived viewer capability), and emits no telemetry.
• Only configured semantic stages send derived text to the selected provider'sLLM or embedding endpoint.

Cross-app

The Swift watcher reads the focused AX tree across native and browser apps.Persome normalizes focused element, visible text, window, application, URL, andtime into one capture and session pipeline. OCR is a fallback, not a parallelcloud recorder.

Agent-ready

• Authenticated streamable HTTP MCP: http://127.0.0.1:8742/mcp
• stdio MCP: persome mcp
• Stable model contract: persome model export and GET /model/graph
• Evidence tools: search, read_receipt, verify_fact, andget_model_snapshot

Connect an MCP client

Register an owner-local stdio server. These clients launch it on demand, so thedaemon does not need to be running and no bearer is copied into their config:

persome install claude-code
persome install codex
persome install claude-desktop
persome install opencode

# Generate a stdio config that can be merged into Cursor's MCP config:
persome install mcp-json --filename persome-mcp.json

The canonical JSON shape is:

{
  "mcpServers": {
    "persome": {
      "command": "persome",
      "args": ["mcp"]
    }
  }
}

See MCP client setup and verification for authenticatedHTTP configs, uninstall commands, and privacy boundaries.

Real MCP query with a cited answer

The following result is generated by the committed synthetic sample through thesame search and read_receipt implementation exposed by MCP.

Tool: search
Input: {"query":"When does the user prefer focused writing?","top_k":2}

Top result:
  id:        20260701-0800-d4e5f6
  path:      project-work.md
  timestamp: 2026-07-01T08:00
  content:   The user reserves mornings for focused writing and review.

Tool: read_receipt
Input: {"entry_id":"20260701-0800-d4e5f6"}

A grounded client response can then say:

The user prefers mornings for focused writing and review.[project-work.md, 2026-07-01 08:00;receipt 20260701-0800-d4e5f6]

The receipt is resolvable, the superseded earlier statement remains availableas history, and the answer does not rely on the model's unsupported memory.

Benchmark and verification status

This repository reports Runtime engineering evidence, not a paper-qualitypersonalization benchmark.

The sample uses synthetic fixtures and cannot establish recall quality on areal person. No cross-user benchmark, next-action accuracy, latency percentile,or comparison win is claimed. The launch machine's three isolated sourceinstalls had an 11.896-second median with a warm uv cache; conditions andlimitations are recorded in benchmark scope.

Why Persome

These projects solve adjacent but different jobs:

Persome is not a replacement for a full screen archive, a hosted vector memory,or a provider's preference feature. Choose it when the core requirement is alocal, cross-app, auditable model that multiple agents can query.

How it works

flowchart LR
  AX[macOS AX watcher] --> S0[S0 debounce]
  OCR[Optional local OCR] --> S1[S1 normalized capture]
  S0 --> S1
  S1 --> BUF[Capture buffer]
  BUF --> TL[1-minute timeline]
  TL --> SES[Deterministic sessions]
  SES --> DELTA[5-minute memory delta]
  DELTA --> PL[Points and Lines]
  PL --> FV[Faces and Volumes]
  FV --> ROOT[Root]
  PL --> RET[BM25 and optional dense retrieval]
  FV --> MCP[MCP, export, viewer]
  ROOT --> MCP
  RET --> MCP

Every modeled object keeps source receipts and bitemporal history. A sparsestore can truthfully contain Points and Lines without a Face, Volume, or Root.The viewer shows that incomplete state rather than fabricating one.

Read Runtime architecture, themodel contract, and the detailedmaintainer architecture.

Inspect, correct, export, and delete

# Inspect
persome status
persome model status
persome faces-report
persome contradictions
persome model open

# Correct or revoke one memory while retaining its audit trail
persome correct --help
# Agents can also call MCP correct_memory.

# Export a redacted owner-only snapshot (0600)
persome model export

# Delete model memory, or all captures/timeline/model state
persome stop
persome clean memory
persome clean all

For a complete uninstall that preserves personal data by default:

bash uninstall.sh

# Explicitly remove the remaining data, config, env, exports, and logs:
bash uninstall.sh --delete-data --yes

Client registrations are removed separately and idempotently:

persome uninstall claude-code
persome uninstall codex
persome uninstall claude-desktop
persome uninstall opencode

See operations and data control for exact paths, backupadvice, export sensitivity, reset behavior, and manual removal steps.

Privacy boundary

• Personal data remains local until a configured model stage or connected agentsends selected text to its own provider.
• MCP capture tools can return raw screen text, titles, URLs, and focused-fieldvalues. Bearer/stdio access is a personal-data capability; connect onlyclients you trust.
• Screenshots are omitted from MCP by default and encrypted at rest whenretention is enabled.
• persome model export is redacted by default; --raw is an explicit opt-out.
• There is no built-in remote account, sync service, telemetry, meeting audiocapture, computer-use actuation, or filesystem profiler.

Read Security and privacy before using real personaldata, and report vulnerabilities through SECURITY.md.

Platform support

Python 3.11-3.13 with SQLite 3.42+ is supported by the installer. Seeoperations and troubleshooting.

Persome and Personome

Persome is this open-source Runtime and project name. Personome is theresearch term for the learned model of one person: a dynamic state assembledfrom sourced observations, relations, stable patterns, and higher-levelstructure. The product name stays Persome in commands, packages, paths, APIs,and documentation.

Paper and architecture-note status

This repository ships the executable Runtime and an implementation-orientedarchitecture note. The architecture documents are not a peer-reviewed paper,and the Runtime's synthetic gates are not publication benchmarks. The paper,benchmark suite, data statements, and project publication will live as separateartifacts with independent licenses before release. Seelicensing boundaries and benchmark limitations.

Roadmap

The public roadmap is issue-driven:

• more tested MCP client integrations;
• richer first-run permission diagnostics;
• explicit import/export interoperability;
• Intel and future-macOS compatibility evidence;
• a separate, reproducible personal-model benchmark suite.

Browse starter issues orstart a design question inDiscussions.

Contributing and community

Read CONTRIBUTING.md, follow theCode of Conduct, and use SUPPORT.md to choosethe right channel. Every commit requires DCO sign-off, and CI blocks knownsecrets, personal data, non-English source text, contract drift, lint failures,and offline regressions. Third-party Actions are pinned to reviewed commit SHAsand workflow permissions default to read-only.

Support Persome

If an inspectable, user-owned personal model is useful to your agents,star Persome on GitHub andshare the MCP client or workflow you want supported inDiscussions.

License

Runtime code is Apache-2.0. Paper, benchmark, project-note, third-party, andpersonal-data boundaries are explained in LICENSES.md. Requiredincorporated-work notices remain in NOTICE andTHIRD_PARTY_NOTICES.