iKnow opens Apple's personal knowledge graph on your own Mac

What iKnow is

iKnow is a look under the hood of Apple's personal knowledge graph — the data macOS quietly builds about who you know, how it decided those people are related to you, whom you write to and how often, whose faces recur in your photos, and where you might be next. The daemon that builds this graph gets a one-line man page from Apple; iKnow is an attempt at a user-facing account of what the store holds.

It ships as a small web app: server.py plus a browser front end under public/. You run it on your own Mac, open a printed link, and read pages about yourself. It has been tested only on macOS 26.6.2, 26.7.1 and 27.0.1; Apple changes these stores between releases, so other versions may render incomplete pages — the page says so under its title when it cannot read something.

How it works

The design is deliberately minimal. server.py is a Python standard-library HTTP server: no Flask, no npm, no build step, nothing to install beyond Python 3. It binds only 127.0.0.1, and there is no flag to change that host — the page fetches from that one process and nowhere else, enforced by a Content-Security-Policy (default-src 'self') so a mistake fails loudly instead of silently pulling from a CDN.

A token guards every request. Each start mints a fresh random token with secrets.token_urlsafe(32) and prints a link carrying it; opening the link swaps the token into an HttpOnly cookie, drops it from the address bar, and reloads work until the server stops. Loopback keeps other machines out; the token keeps out other programs, other accounts on this Mac, and web pages in your browser that can reach 127.0.0.1. It is not a sandbox — a program running as you, with access to your terminal or browser history, could still find it — but nothing stores the token, so a restart shuts every open tab out.

Everything is read-only. Every SQLite handle opens with mode=ro on a file URI (api/db.py), and connections are thread-local because the server is threaded. Nothing caches row values to disk; values travel from the stores over loopback into your browser tab and are never persisted, not even request logs.

The source carries no data: every name and number on screen is queried live when a page loads. The code holds the queries; your Mac holds the answers.

What it reads

iKnow opens the live stores where macOS keeps them:

• the graph under ~/Library/IntelligencePlatform
• the ontology inside the system's IntelligencePlatformCore.framework
• the four sources the graph resolves against: Messages, Photos, Calendar and Contacts

Nothing is extracted or copied first. Because daemons hold these files open in WAL mode and write while you read, each connection sees a consistent snapshot of its own store but two stores read a second apart can disagree — a page reloaded later may differ.

One detail worth noting: entity ids are 64-bit and routinely exceed JavaScript's safe integer range. server.py ships a BigIntEncoder that serialises any int outside 2^53 - 1 as a string, so join keys do not silently round into missing data.

Running it

git clone https://github.com/8rank/iKnow.git
cd iKnow
python3 server.py

The terminal you start the server from needs Full Disk Access, because macOS privacy controls protect these stores. On startup server.py checks each store and prints ok or DENY beside it, so a missing permission is obvious rather than a bare SQLite error. The README walks through granting it under System Settings → Privacy & Security, quitting the app completely (the permission is picked up at launch), and switching it back off when you are done.

For reading an extracted copy instead of this Mac:

python3 server.py --port 9000                    # another port
python3 server.py --bundle /path/to/extracted    # an extracted copy, not this Mac

How the pages fit together

Routes are discovered, not registered: every module in api/ that exposes a ROUTES dict is mounted automatically (discover_routes()), so adding a page never means editing server.py. The front end mirrors that with self-contained modules under public/js/pages/, each exporting a meta object and a render(root) function, registered in one import list in app.js.

app.js registers twelve page modules and groups them into four sidebar sections. The overview page is the one app.js itself depends on for its sidebar subtitle; several of its measurements are not lookups but small experiments run at request time — testing every cnContact: reference against the AddressBook stores, re-deriving bundle tokens as base64(sha256(bundle id)), and so on.

A redaction switch in the sidebar is meant for sharing your screen: while it is on, every request asks for a payload rewritten by api/redact.py, turning names, phone numbers, mail and postal addresses into numbered stand-ins, and photographs are blurred. The setting survives reloads via localStorage, so reloading mid-call cannot put the real names back.

Asking an agent instead

MANUAL_FOR_YOUR_AGENT.md is written for an AI agent with a shell on your Mac — Claude Code or Codex. It covers where each store lives, how to open it read-only (sqlite3 "file:…?mode=ro", never immutable=1 because that skips the write-ahead log), what the tables and codes mean, how to join out to Contacts, Photos, Calendar and Messages, and which columns mislead. The manual's first rule is consent: before reading anything it asks you whether your LLM provider can be trusted with your graph, since unlike iKnow an agent sends what it reads to wherever its model runs.

The project is Apache 2.0 licensed and, per the README, fully LLM-generated — worth keeping in mind when a page on an untested macOS version comes out incomplete.