hippocampus

Install

Download the disk image, open it and drag Hippocampus to Applications.

Or with Homebrew:

brew install --cask amyjainberkeley/tap/hippocampus

Or with the one-line installer. scripts/install.sh is the script it runs, and says every step:

curl -fsSL https://github.com/amyjainberkeley/hippocampus/releases/latest/download/install.sh | sh

It downloads the latest release, checks its checksum, Apple’s notarization and the developer’s signature, and copies Hippocampus to Applications. The installer and the Homebrew cask also put the mci-agent command on your PATH.

Setup is five short screens. It shows what you get first, then asks for two permissions, Screen Recording and Accessibility, and reads nothing until you click Start Remembering.

What it does

Today. Where you left off, with its screenshot, and your day as sessions you can click. Resume reopens what you had open for that project: its pages, documents, code folder and apps, only the ones you tick.

Working On. Your projects and documents by name, from their window titles. Each has a page with where you left off, its files, the pages you read alongside it, its meetings and its history.

History. Every moment, newest first, as it read on screen: headings, paragraphs, lists, code and chats. Web Pages, Documents, Code, Conversations and Looked Up show the same moments by kind. Looked Up, like Today, lists your searches when the browser extension gives the page’s address; reading addresses through Automation is off by default.

Ask. Press Shift twice (or Fn, if you choose it) and Ask drops from the menu bar over any app, like Spotlight. It finds projects, pages and moments as you type, and answers questions with sources, this window first. ⌃⇧Space works too.

Your AI tools start with what you’re working on. Connect Claude Code or Codex from the menu bar. They can then search your memory through the hippocampus MCP server, with tools such as recall, context and person_model. If you let them, a session starts with up to four lines of your recent work and up to six things learned about you, with sources: every Claude Code session, and every Codex session once you allow its hook in Codex. Until then, or with Codex’s hooks turned off, Codex is asked to fetch your recent work when a task starts, and Codex decides. Ask Claude opens Claude, Codex or Cursor with what you picked already in its message box, and you press send; for ChatGPT it is copied, ready to paste. AI Tools shows the exact words each tool gets.

About You. What Hippocampus has learned about you, in the exact words your AI tools are given, with the moments behind each line. Mark what’s right. Forget what isn’t.

Your calendar, if you want it. Today’s meetings over your day, and calls named after them. It is off until you turn it on, and read only on your Mac.

Answers and summaries need Apple Intelligence (macOS 26) or a model on your Mac. Hippocampus finds Ollama or LM Studio by itself. Without either, search still works.

Privacy

• You can tell. A solid dot means it is remembering. No solid dot means it is not.
• Your memory stays on your Mac, encrypted. Hippocampus itself has no cloud service. There is no account, no telemetry and no crash reporting, and it uploads nothing you saw. The text reader runs with no network access. Your memory is left out of Time Machine unless you include it in Preferences.
• Some things are skipped. Password fields, password managers and authenticator apps, private browser windows that show they are private, and a list of bank, sign-in and password-manager sites. Text in a few secret shapes is refused before it is stored, whatever it came from: a password, secret, API key or token written as name: value, an API key in the shape a known service gives it (Anthropic, OpenAI, GitHub, Stripe and others), a private key, a JSON web token, a card number that passes the Luhn check, and a one-time code next to words like “verification code”. These are rules, so a lone code with no such word nearby, or a bank alert on screen, can be kept. PRIVACY.md says exactly what they catch and miss.
• Screenshots are kept, encrypted. Of the window you’re in, and of other windows you can see when their text changes, each sealed in its own file. A picture of another window shows only that window: anything in front of it is blanked out, and none is kept of a call, a video or a private window it recognizes. Those pictures use at most 2 GB, or 2% of the disk if that is less (1, 2 or 5 GB in Preferences), are thinned out as they age, and Preferences turns them off (more).
• Your AI tools get it only if you connect them, or send it yourself. What a connected tool reads goes to the company that runs it. So does what you send. Ask Claude opens the tool with the message in its box, and nothing is sent until you press send. A connected tool can read your memory while Hippocampus is quit, until you disconnect it in Preferences, under AI Tools, and restart the tool.
• You can stop it. Pause from the menu bar. Quit, or Stop Sharing in macOS, stops remembering.
• Forgetting is real. Forget a moment, a session, the last 10 minutes, the last hour, today or everything, and what was learned from it goes too. Delete Everything also deletes the memory’s key, so copies in earlier backups can’t be read.

PRIVACY.md says what is stored, where, every request the app makes, and its threat model. SECURITY.md says how to report a gap.

What it costs

Reading the screen is the cost. The numbers below are measured, each with its source.

A working hour hasn’t been measured yet: CPU, memory, energy and disk over an hour of real use. To measure one on your own Mac, run this from a source checkout while Hippocampus runs and you work:

./scripts/launch/footprint.sh 3600

For that hour it samples every process in Hippocampus.app every 5 seconds. It reads only the kernel’s counters for those processes and the size of the memory folder, never what is in them. It prints CPU as Activity Monitor counts it, where one core is 100%, and as a share of the whole Mac, then memory, the CPU’s energy, what Hippocampus wrote to disk, and how much the memory folder grew. docs/STATUS.md will carry the hour once it is measured.

	Measured	Source
Reading one window	3.7 to 4.8 CPU-seconds and about 4 J at the median; 1.3 to 1.7 GB peak memory while reading	Reader bake-off, MacBook Air M3, made-up screens
Lines read exactly, on the bench’s flat screens	96.7% (Apple Vision, tuned: 93.9%)	The same bake-off
Disk image	177 MB	docs/STATUS.md: the notarized 0.3.0 candidate of October 18
Installed app	365 MB, 253 MB of it the reader	The same candidate, in Finder’s units

How hard it may work is set in code, not measured: the window in front is read at most every 3 seconds, other windows at most every 30, and after each read the reader rests three times as long as the read took. On battery those rests are longer, and in Low Power Mode only the window in front is read (PRIVACY.md).

The reader is PP-OCR, bundled. It reads code and small text more exactly than Apple Vision on the repo’s bench, and costs 8 to 10 times Vision’s CPU per read. To check the numbers yourself, run tools/ocr/screens/bakeoff.py with the capture helper’s OCRQualityProbe, as the bake-off’s Reproduce section shows.

This is a beta. docs/STATUS.md says what works today and how it was checked.

Check it yourself

Each of these runs from a source checkout, and none of them reads your memory.

./scripts/launch/no-egress.sh          # every line of shipping code that can open a network connection, and why
./scripts/launch/no-listener.sh        # while Hippocampus runs: no Hippocampus process listens on a TCP port
./scripts/launch/verify-encryption.sh  # a made-up memory can't be read without its key, and holds no plain text
./scripts/launch/secret-matrix/run.sh  # made-up secrets through the same rules the app runs

no-egress.sh reads the shipping source and fails on any network call it can’t account for. The only ones it allows are the update check to GitHub and connections that stay on this Mac, to a model server or to an MCP server you list. verify-encryption.sh builds and runs tests on a throwaway memory in a temporary folder, never yours. docs/launch/network-check.md says how to watch the network while the app runs.

The planted-secret test, secret-matrix/run.sh, builds made-up cases (an app, a window’s title and address, the text read from it and the signals macOS gives) and runs them through the rules the app uses to skip and refuse things before anything is stored. Its results from October 17 are in eval/secret-matrix-2026-10-17.md, where all 15 of its rows passed:

• Skipped or refused: password fields, password managers and authenticator apps, private browser windows that show they are private, bank and sign-in pages by their address, keys and tokens in a terminal or an editor, card numbers that pass the Luhn check, and one-time codes next to words like “verification code”.
• Kept on purpose, and checked: a number with no such word nearby, and a 16-digit number that fails the Luhn check, so phone numbers, order numbers and dates stay searchable.
• Missed, as the results say: a one-time code worded in a way those words don’t name, a long random token with no label, and a card number read too poorly to form one run of digits.
• Needs a person: a private Safari or Arc window that shows no word the reader knows, and whether a code or a card on a real screen is caught from end to end. The results file says how to check each one on a real Mac.

Build from source

You need Xcode 26, the Rust toolchain named in rust-toolchain.toml, and Python 3.12 with uv for the text reader.

git clone https://github.com/amyjainberkeley/hippocampus.git && cd hippocampus
./scripts/try-it.sh    # search over a made-up memory, with no permissions
./scripts/check.sh     # every check, as CI runs them

To build a disposable copy of the app for your own Mac:

uv venv tools/ocr/.venv --python 3.12
uv pip install --python tools/ocr/.venv/bin/python --require-hashes --no-deps -r tools/ocr/requirements.txt
env -i HOME="$HOME" PATH=/usr/bin:/bin tools/ocr/.venv/bin/python tools/ocr/prepare.py
cargo build -p mci-agent --bins -p hippocampus-native-host
for package in apps/hippocampus adapters/macos/MCICaptureHelper apps/recall-ui apps/onboarding apps/mind apps/demo-memory; do
  ./scripts/swift-package.sh build --package-path "$package"
done
./apps/hippocampus/Resources/build-app.sh --debug --development-ad-hoc --development-lite

A development copy uses the same data folder as an installed one, so build it under a separate macOS user. docs/GUIDE.md covers the command line, scripts/README.md covers signed builds and releases, ARCHITECTURE.md is the map, and CONTRIBUTING.md says how to send a change.

Built on research

Hippocampus learns the way a general user model does (Shaikh et al., 2025). It keeps what it learns as a personal context model: plain statements on your Mac, each linked to the moments behind it, in the exact words your AI tools receive. You can read each one, mark it right, or remove it.

Omar Shaikh, Shardul Sapkota, Shan Rizvi, Eric Horvitz, Joon Sung Park, Diyi Yang and Michael S. Bernstein. Creating General User Models from Computer Use. 2025.

License

Apache 2.0. See LICENSE and NOTICE.