Local-first personal memory and model server for trusted MCP agents on macOS.
Local-first personal memory and model server for trusted MCP agents on macOS. It provides an MCP-accessible service intended for using personal, privacy-oriented data in agent workflows, with implementation and tooling aligned to macOS environments.
🛠️ Key Features
Local-first personal memory
Targeted for trusted MCP agents
macOS support
🚀 Use Cases
Supplying personal memory to MCP agents during agent runs on macOS
Using model content that is linked to evidence in a viewer workflow (as referenced in the readme excerpt)
⚡ Developer Benefits
MCP integration for agents
Topics include agent-memory, local-first, privacy, and python (indicating developer focus areas)
⚠️ Limitations
Description and excerpt specify macOS; other platforms are not stated
Build your HUMAN.md — one evidence-linked Personal Model for Claude Code, Codex, Cursor Agent, and other trusted MCP clients.
Personal 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.
Runs locally on your Mac. Private by default. Yours to inspect, correct, export, and delete.
Illustration of a mature Personal Model with evidence-linked Points, Lines, Faces, Volumes, and a Root
Concept illustration of a mature Personal Model.
Why Personal Model
Personal 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.
One memory across agents. Connect the same Personal Model to Claude Code,
Codex, Cursor Agent, and other MCP-compatible clients.
Evidence, not hidden summaries. Important claims retain source receipts;
new evidence can strengthen, revise, or overturn an earlier inference.
User-owned by design. Inspect, correct, export, or delete your model and
data without depending on a hosted memory service.
More than chat history. Personal Model learns from focused activity after you
explicitly grant macOS permissions.
Your Personal Model is your HUMAN.md
Personal Model connects activity into progressively deeper context:
Layer
Meaning
Point
A sourced observation or event
Line
A relationship or change over time
Face
A pattern supported by related evidence
Volume
A higher-order structure across projects or areas of life
Root
The current integrated model of you
The result is a living model of what matters now, how you tend to decide, and
where your attention is moving.
Works with Claude Code, Codex, Cursor Agent, and MCP clients
The MCP client guide covers prerequisites, verification,
the permission boundary, transport details, HTTP fallback, and troubleshooting.
Personal Model is an MCP server used by trusted MCP clients. Other MCP servers—such
as Filesystem, GitHub, Slack, or Google Drive—are separate tools and are not
Personal Model integrations unless that path is explicitly built and tested.
Use cases
These visuals show agent workflows enabled by Personal Model. The Runtime
supplies evidence-linked local context through MCP; connected agents own task
selection and execution, and external actions still require your authority.
1. One Root — A Model of You
Thousands of moments. One evolving model of you.
Personal 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.
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
One Personal Model MCP connection gives trusted coding agents evidence-linked context.
Your coding agent finds its own work
Connect 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.
A connected agent can search Personal Model for unfinished work, rank proposed
next steps against your priorities, and separate local implementation from
external actions that need your approval.
Continue where you left off
Concept illustration of a connected coding agent using Personal Model context to continue unfinished work. The panels show README, onboarding, and MCP tasks alongside restored work state, current goal, next step, project directory, Git status, and unstaged changes.
Work while you sleep
Concept illustration of a connected coding agent using Personal Model context to review open loops, filter proposed local work by permission scope, and prepare a morning report while leaving external actions for owner approval.
Install, connect, and verify
Install Personal Model, connect a trusted MCP client, then verify the local Runtime.
1. Install with your data
Requirements: macOS 13 or newer and Xcode Command Line Tools. For the shortest package-managed installation:
text
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:
text
git clone https://github.com/Intuition-Lab/personal-model.git
cd personal-model
bash install.sh
After successful interactive onboarding, the source installer opens the unified
local setup experience immediately.
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. Personal Model 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:
text
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; Personal Model
stores only its executable path, routing policy, and a durable daily call cap:
text
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 Personal Model;
the CLI bridge is the opt-in path that also powers unattended stages.
The commands above install only the MCP server. To also give background
semantic stages explicit consent to use a supported coding-agent subscription,
add --fund-model; the default cap is 50 model invocations per local day:
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:
MCP access is a personal-data capability; register only clients you trust.
3. Verify and ask grounded questions
text
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; Personal Model reports missing geometry instead of fabricating Faces, Volumes, or a Root.
After connecting an MCP client, try one of these recipes:
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.
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.
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.
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.
4. Update Personal Model
For a uv tool installation, upgrade with the package manager and re-run Runtime proof:
text
uv tool upgrade --python 3.12 personal-model
persome onboard
persome model open --after 30
After any upgrade, restart editors that host a Personal Model 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:
text
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.
Use the client guide with the prompts above to install, prove the connection,
test evidence-grounded retrieval, understand the permission boundary, and
diagnose the most common failures.
Where Personal Model fits
Personal Model is an owner-local macOS Runtime, not a hosted multi-tenant memory
service or only a graph library. It can coexist with product-native memory in
ChatGPT or Claude and with developer memory infrastructure.
If your client is not listed above, start with the
generic MCP setup. If it works, open an
issue with the client
name, version, transport, verification steps, and any permission caveats. A
client moves into the verified table only after the path is reproducible.
See CONTRIBUTING.md for the development workflow and DCO
requirements.
