{ "markdown": "# Personal Model: local-first AI memory for coding agents\n\n

\n \n \"Looping\n \n

\n

\n Auto-playing preview · Full-quality demo and v0.3.2 release notes\n

\n\n\n\n![Build your HUMAN.md — local-first AI memory for Claude Code, Codex, and MCP](docs/assets/readme/human-md-hero.png)\n\nBuild your `HUMAN.md` — one evidence-linked Personal Model for Claude Code, Codex, Cursor Agent, and other trusted MCP clients.\n\nPersonal Model is an open-source, local-first long-term memory Runtime. It learns how you think and work from focused activity captured on your Mac after you grant macOS permission, then gives your AI tools inspectable context to continue work and make grounded decisions.\n\n**Runs locally on your Mac. Private by default. Yours to inspect, correct, export, and delete.**\n\n[![CI](https://github.com/Intuition-Lab/personal-model/actions/workflows/ci.yml/badge.svg)](https://github.com/Intuition-Lab/personal-model/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/Intuition-Lab/personal-model)](https://github.com/Intuition-Lab/personal-model/releases) [![GitHub stars](https://img.shields.io/github/stars/Intuition-Lab/personal-model?style=flat&logo=github&label=Stars)](https://github.com/Intuition-Lab/personal-model) [![License: Apache-2.0](https://img.shields.io/badge/code-Apache--2.0-blue)](LICENSE) [![macOS 13+](https://img.shields.io/badge/macOS-13%2B-black)](#1-install-with-your-data) [![MCP](https://img.shields.io/badge/interface-MCP-0b7285)](MCP.md) [![Official MCP Registry](https://img.shields.io/badge/Official_MCP_Registry-Personal_Model-6f42c1)](https://registry.modelcontextprotocol.io/?q=personal-model)\n\n[Install Personal Model](#1-install-with-your-data) · [Connect your AI tool](#works-with-claude-code-codex-cursor-agent-and-mcp-clients) · [Star Personal Model on GitHub](https://github.com/Intuition-Lab/personal-model)\n\n![Illustration of a mature Personal Model with evidence-linked Points, Lines, Faces, Volumes, and a Root](docs/assets/readme/personal-model.png)\n\n_Concept illustration of a mature Personal Model._\n\n---\n\n## Why Personal Model\n\nPersonal Model turns focused activity from the apps you use into a portable context layer, keeps it on your Mac, and makes it available to the trusted AI clients you choose.\n\n- **One memory across agents.** Connect the same Personal Model to Claude Code,\n Codex, Cursor Agent, and other MCP-compatible clients.\n- **Evidence, not hidden summaries.** Important claims retain source receipts;\n new evidence can strengthen, revise, or overturn an earlier inference.\n- **User-owned by design.** Inspect, correct, export, or delete your model and\n data without depending on a hosted memory service.\n- **More than chat history.** Personal Model learns from focused activity after you\n explicitly grant macOS permissions.\n\n### Your Personal Model is your `HUMAN.md`\n\nPersonal Model connects activity into progressively deeper context:\n\n| Layer | Meaning |\n| --- | --- |\n| **Point** | A sourced observation or event |\n| **Line** | A relationship or change over time |\n| **Face** | A pattern supported by related evidence |\n| **Volume** | A higher-order structure across projects or areas of life |\n| **Root** | The current integrated model of you |\n\nThe result is a living model of what matters now, how you tend to decide, and\nwhere your attention is moving.\n\n## Works with Claude Code, Codex, Cursor Agent, and MCP clients\n\n| Client | Connection | Setup |\n| --- | --- | --- |\n| [Claude Code](docs/mcp-clients.md#claude-code) | Native Personal Model installer | `persome install claude-code` |\n| [Codex CLI and IDE extension](docs/mcp-clients.md#codex-cli-and-ide-extension) | Native Personal Model installer | `persome install codex` |\n| [Cursor Agent CLI](docs/mcp-clients.md#cursor-agent-cli) | Native Personal Model installer | `persome install cursor-agent` |\n| [Claude Desktop](docs/mcp-clients.md#claude-desktop) | Managed stdio config | `persome install claude-desktop` |\n| [opencode](docs/mcp-clients.md#opencode) | Managed local stdio config | `persome install opencode` |\n| [Other compatible clients](docs/mcp-clients.md#generic-clients) | Generated MCP JSON | `persome install mcp-json --filename persome-mcp.json` |\n\nThe [MCP client guide](docs/mcp-clients.md) covers prerequisites, verification,\nthe permission boundary, transport details, HTTP fallback, and troubleshooting.\n\n> Personal Model is an MCP server used by trusted MCP clients. Other MCP servers—such\n> as Filesystem, GitHub, Slack, or Google Drive—are separate tools and are not\n> Personal Model integrations unless that path is explicitly built and tested.\n\n## Use cases\n\n> These visuals show agent workflows enabled by Personal Model. The Runtime\n> supplies evidence-linked local context through MCP; connected agents own task\n> selection and execution, and external actions still require your authority.\n\n### 1. One Root — A Model of You\n\n**Thousands of moments. One evolving model of you.**\n\nPersonal Model 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.\n\n

\"One

\n\nFrom Points to Lines, Faces, Volumes, and one Root—a living model of who you are and what matters now.\n\n### 2. Same AI. Different You.\n\n

\"The

\n\n**The model is the same. The person it understands is different.**\n\nTwo 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.\n\nThe same prompt should not produce the same answer for everyone. Give AI a model of you.\n\n### 3. One MCP — Turn coding agents into proactive agents\n\n

\"One

\n\n**Your coding agent finds its own work**\n\nConnect Personal Model once through MCP. Codex, Claude Code, and other trusted agents can use the same model of your goals, priorities, working patterns, and boundaries.\n\nA connected agent can search Personal Model for unfinished work, rank proposed\nnext steps against your priorities, and separate local implementation from\nexternal actions that need your approval.\n\n#### Continue where you left off\n\n

\"Concept

\n\n#### Work while you sleep\n\n

\"Concept

\n\n## Install, connect, and verify\n\n**Install Personal Model, connect a trusted MCP client, then verify the local Runtime.**\n\n### 1. Install with your data\n\nRequirements: macOS 13 or newer and Xcode Command Line Tools. For the shortest package-managed installation:\n\n```text\nuv tool install personal-model\npersome onboard\npersome model open --after 30\n```\n\nThe distribution is named `personal-model`; the installed CLI is `persome`.\n\nFor the most explicit source-based first run:\n\n```text\ngit clone https://github.com/Intuition-Lab/personal-model.git\ncd personal-model\nbash install.sh\n```\n\nAfter successful interactive onboarding, the source installer opens the unified\nlocal setup experience immediately.\n\n**What onboarding proves**\n\n- `persome onboard` explains each macOS request before it appears.\n- Accessibility is granted to the versioned `mac-ax-helper` and, only when event-driven capture is enabled, `mac-ax-watcher`.\n- Screen Recording is requested only when the effective screenshot or local-OCR policy requires pixels. Personal Model never requires Full Disk Access.\n- On Apple Silicon, local OCR uses bundled PP-OCRv6; on Intel, it uses the macOS\n Apple Vision framework. Onboarding verifies the isolated worker on both architectures.\n- Unified localhost onboarding offers a read-only, multi-source import and builds the first model\n from existing Markdown history. Local folders are always available; Obsidian\n and Notion appear only when detected on the Mac. The same sources remain\n available through `persome import-data`; see [the import guide](docs/importing.md).\n- 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.\n\nAn LLM is optional for collection and BM25 recall, but required for semantic modeling. You can configure a hosted/local provider for unattended processing:\n\n```text\npersome llm setup\npersome llm status --check\n```\n\nAlternatively, explicitly lend an existing coding-agent subscription to the\nbackground Runtime. The client CLI keeps and refreshes its own login; Personal Model\nstores only its executable path, routing policy, and a durable daily call cap:\n\n```text\npersome llm agent setup --client codex --daily-call-limit 50 --check\n# also supported: claude-code, cursor-agent\npersome llm status\n```\n\nA trusted MCP client that supports Sampling with tools can still call\n`process_pending_model_work` for a one-request, 1–10-session batch. Both paths\nuse the connected agent allowance without exposing its OAuth token to Personal Model;\nthe CLI bridge is the opt-in path that also powers unattended stages.\n\n### 2. Connect a trusted MCP client\n\nRegister whichever owner-local clients you use:\n\n```text\npersome install claude-code\npersome install codex\npersome install cursor-agent\npersome install claude-desktop\npersome install opencode\n```\n\nThe commands above install only the MCP server. To also give background\nsemantic stages explicit consent to use a supported coding-agent subscription,\nadd `--fund-model`; the default cap is 50 model invocations per local day:\n\n```text\npersome install codex --fund-model --daily-call-limit 50\n# also supported: claude-code, cursor-agent\n```\n\n`persome llm agent disable` revokes that consent without logging the client out\nor deleting a fallback provider profile.\n\nThese stdio registrations launch the MCP process on demand, so the daemon does\nnot need to be running after onboarding has initialized the local database, and\nno HTTP bearer is copied into client configuration. Schema creation and\nmigration remain daemon-owned; a brand-new or externally upgraded data root\nmust run `persome start` once before stdio clients use it. Stdio writes remain\navailable while the daemon is stopped, but WAL maintenance waits for the daemon;\nstart it periodically if you use write tools in that mode so the WAL stays bounded.\n\nFor another Cursor-compatible setup, you can still generate a stdio object and\nmerge `mcpServers.persome` manually:\n\n```text\npersome install mcp-json --filename persome-mcp.json\n```\n\n> MCP access is a personal-data capability; register only clients you trust.\n\n### 3. Verify and ask grounded questions\n\n```text\npersome status\npersome model status\npersome model open\n\n# Only if you configured a semantic provider:\npersome llm status --check\n```\n\nA sparse or degraded model can be valid early; Personal Model reports missing geometry instead of fabricating Faces, Volumes, or a Root.\n\nAfter connecting an MCP client, try one of these recipes:\n\n> Search my Personal Model 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.\n\n> Help me continue where I left off on **[project]**. Search recent Personal Model context, distinguish observed facts from inferences, and show the receipts behind the proposed next step.\n\n> Review my current Personal Model with the default `get_model_snapshot` overview. Page only the specific model sections needed for the answer, cite supporting evidence, and call out anything sparse, stale, or conflicted.\n\nActive 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.\n\n### 4. Update Personal Model\n\nFor a `uv tool` installation, upgrade with the package manager and re-run Runtime proof:\n\n```text\nuv tool upgrade --python 3.12 personal-model\npersome onboard\npersome model open --after 30\n```\n\nAfter any upgrade, restart editors that host a Personal Model stdio MCP process before\nresuming Runtime writes. A process loaded from the previous release cannot join\nthe new cross-process SQLite maintenance gate until the editor reconnects it.\n\nFor an installation created by `install.sh`, run the transactional updater from any directory:\n\n```text\npersome update\n```\n\n`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.\n\n---\n\n## Recipes\n\n- [Use Personal Model with Claude Code](docs/mcp-clients.md#claude-code)\n- [Use Personal Model with Codex CLI and the IDE extension](docs/mcp-clients.md#codex-cli-and-ide-extension)\n- [Use Personal Model with Cursor Agent](docs/mcp-clients.md#cursor-agent-cli)\n- [Use Personal Model with Claude Desktop](docs/mcp-clients.md#claude-desktop)\n- [Use Personal Model with opencode](docs/mcp-clients.md#opencode)\n- [Connect any compatible MCP client](docs/mcp-clients.md#generic-clients)\n\nUse the client guide with the prompts above to install, prove the connection,\ntest evidence-grounded retrieval, understand the permission boundary, and\ndiagnose the most common failures.\n\n## Where Personal Model fits\n\nPersonal Model is an owner-local macOS Runtime, not a hosted multi-tenant memory\nservice or only a graph library. It can coexist with product-native memory in\nChatGPT or Claude and with developer memory infrastructure.\n\n[Read the Runtime boundary](ARCHITECTURE.md) and\n[evaluation limits](docs/benchmarks.md#what-is-not-measured-here) before\ntreating this as a hosted service or a benchmark claim.\n\n## Privacy, ownership, and evidence\n\n- Personal Model runs owner-locally on macOS and captures activity only after the\n relevant permissions are explained and granted.\n- Important memories and model objects retain provenance that trusted clients\n can inspect with `read_receipt` and `resolve_evidence`.\n- Corrections preserve audit history. Exports are redacted by default, and\n explicit erasure commands are available when history itself must be deleted.\n- MCP access is access to personal data. Register only clients you trust, and\n do not expose the localhost Runtime through a public tunnel.\n\nRead the complete [security and privacy model](SECURITY_PRIVACY.md),\n[model and evidence contract](MODEL_FORMAT.md), and [MCP tool contract](MCP.md).\n\n## Help us test more MCP clients\n\nIf your client is not listed above, start with the\n[generic MCP setup](docs/mcp-clients.md#generic-clients). If it works, open an\n[issue](https://github.com/Intuition-Lab/personal-model/issues) with the client\nname, version, transport, verification steps, and any permission caveats. A\nclient moves into the verified table only after the path is reproducible.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and DCO\nrequirements.\n\n---\n\n

Star Personal Model on GitHub · Official MCP Registry · MCP client setup · Security & privacy

\n\n
\nContributors\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n \"Singularity\"\n   Singularity
\n   💻 Code\n 		\n \"Li_Xufeng\"\n   Li_Xufeng
\n   💻 Code\n 		\n \"Siyi\"\n   Siyi
\n   🎨 Design\n
\n \"Kevin\"\n   Kevin
\n   💻 Code\n 		\n \"huachenjie238-oss\"\n   huachenjie238-oss
\n   📈 Growth\n 		\n \"Jing@Meowy\"\n   Jing@Meowy
\n   📈 Growth\n
\n \"Zhiheng\n   Zhiheng Chen
\n   💻 Code\n
\n\n\n
\n\n## Star History\n\n

\n \n \"Star\n \n

\n\n

Snapshot through July 31, 2026 · Open on Star History

\n", "bytes": 20292, "sha": "7bce281e7e2136a07eedde12a61d63ce0a017099af3eeafd254a774c370bb155", "repo_slug": "intuition-lab/personal-model", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_intuition_lab_personal_model_571eef36/readme" }