Hippocampus is a tool. Your memory is a vault. They live in two separate repositories, and the arrangement is the backbone of its privacy model. The vault depends on a pinned version of the tool. The tool never contains, references or knows about any real vault.
The public tool
The Hippocampus repository is public and published to npm as @mehrad77/hippocampus. It holds the code, the vault template that hippo init copies, the fictional example campaign, and these guides. Every example in it, from tests to screenshots to these pages, uses the fictional Lisbon arc: the residency agent, Harbor University, the Migration Agency, a flat in Alfama.
Your private vault
Your vault is a separate repository that you own. It holds your notes, quests, party sheets, the inbox, the chronicle, disputes, and the encrypted secrets/ folder. Keep it private:
- Create the GitHub repo as private before the first push. Session Zero’s Git step checks the repo’s visibility and warns you if it’s public.
- On the hosted app, install its GitHub App on the vault repo only, not on all your repositories.
- On your own machine, give
--githuba fine-grained token with Contents: read and write on the vault repo only. Nothing broader. - The vault’s CI (
.github/workflows/validate.yml) runs inside your private repo, not in the tool’s. .gitignorein the template keeps Obsidian’s workspace files and trash out of git.
What the dashboard never shows
Even to you, signed in, the dashboard holds some things back:
| Never shown | Instead |
|---|---|
| Secret values | A lock. Decrypt on your machine with hippo secrets show |
| Text of secret-bearing inbox episodes | A sealed card until the sleep encrypts the secret |
| API keys saved in Session Zero | “Set” or “unset”. Keys are write-only |
| Your age identity | Never sent to the page; it stays in ~/.config/hippocampus/ |
The pages themselves load nothing from outside: fonts, scripts and styles are bundled, and a strict content security policy keeps it that way. Locally the dashboard answers only on 127.0.0.1, to the browser that opened its sign-in link. On the hosted app, you sign in with GitHub and reach only your own vault. More in the dashboard tour.
If you use a hosted app
Whoever runs a hosted Hippocampus handles your memory on your behalf: a data processor, in privacy terms. Know what that means before you sign up.
The GitHub App’s reach. It asks for three permissions, on the repositories you install it on: Contents (read and write, to read notes and commit memories), Workflows (read and write, only to add the vault’s CI and the optional Actions curator) and Metadata (read). Install it on your vault repo only. The app refuses a public repo, and if you make the vault public later, it disconnects.
What the operator can see:
| What | Where |
|---|---|
| Your vault’s contents | Through the GitHub App, which can read and write the repo |
| A search index and cache of your vault | In your vault’s own storage on Cloudflare. Inbox files, which can hold secrets until sleep, are kept in memory only |
| Your GitHub login and id, your access note, your repo’s name | In the app’s registry |
| Your keys | Only as hashes, with their labels and when they were last used |
| Requests | Route names, status codes and timings, with a hashed vault id. No content |
What it can’t see: your age identity (it’s made in your browser and never sent), so no secret can be decrypted, and nothing your curator agent’s provider does with what it reads.
Each vault is served by its own isolated store, and the app only acts on your repo for requests made with your sign-in or your keys. Deleting your account removes everything the app holds about you and uninstalls the app; your repo stays yours. The instance’s privacy page names who runs it and how long logs are kept. The full threat model is SECURITY.md in the Hippocampus repository.
If that’s more trust than you want to give, run the tool locally, or run your own instance.
Where your data does travel
Privacy is also about the services you choose. Here is everywhere vault content can go, and when:
| Destination | When |
|---|---|
| GitHub | Whenever the vault lives there: a private repo you control |
| Your curator model | During sleep. A local model (LM Studio, Ollama) keeps it on your machine. A hosted provider receives episode text, secrets included before encryption |
| Your embedding model | With semantic recall on. A hosted embeddings API receives note text |
| A hosted app (on Cloudflare) | If you use one. It reads your vault repo through its GitHub App and keeps a search index and cache per vault |
| Your curator agent | With a curator key, that agent and its model’s provider read every new memory, secrets in plain text |
| Your agents’ hosts | Whatever an agent reads through MCP lands in its host’s context: a chat app, a bot, a coding agent |
None of this is hidden behind a default you didn’t choose. The curator defaults to a local LM Studio server, and semantic recall is off until you set a model.
The demo is fiction
hippo dashboard --demo opens the example campaign from the public seed, with three weeks of invented activity replayed through the curator’s own rules. It lives in memory only: nothing is read from or written to your vault. Everything in it is made up: the residency agent and the campus agent, Harbor University and its Language Center, Lisbon, Alfama and Belém, and an insurer called Acme Health.
Use it whenever someone else will see the screen: a screenshot, a bug report, a talk, a question in a forum.
If you contribute to Hippocampus
A quick checklist
- The vault repo is private, and the GitHub App or token reaches that repo only.
- The curator key went only to an agent you trust with your secrets.
- The age identity is backed up, and lives outside the vault.
- If you use a hosted model or hosted embeddings, you’re fine with episode text going there.
- Screenshots and bug reports come from
--demo. - Nothing from your vault has gone into a public issue, pull request or chat.