Locuset is a macOS memory app and local MCP server. It stores memories, provenance, tags, summaries, and agent context in an encrypted local database, then exposes only the tools allowed by each client's grant.
The core app does not need an account or hosted database. External model calls and network connectors are optional. Locuset shows what will leave the Mac and asks for approval before each model send.
Locuset is an independent clean-room implementation. The repository contains only original source and project assets.
- Saves manual notes and context from capture sources you choose.
- Searches by text, meaning, time, source, person, tag, and relationship.
- Gives MCP clients separate, revocable grants instead of one shared credential.
- Keeps model credentials in Keychain, 1Password, Bitwarden, or the provider's own installed command-line client.
- Supports cited chat, briefs, reflections, graph exploration, time review, saved materials, encrypted backups, and local summary schedules.
Memories are encrypted before SQLite writes them. Packaged builds keep the database key in macOS Keychain and use keyed blind indexes for private search. This protects data at rest, but it cannot make a compromised macOS account trustworthy.
For an installed build:
- Move
Locuset.appto Applications. - Open Locuset.
- Complete the local setup.
- Add a memory, then find it from Search.
The first-memory tutorial walks through the whole flow.
To connect Hermes:
/Applications/Locuset.app/Contents/Resources/bin/locuset-connect \
apply --client hermes
/Applications/Locuset.app/Contents/Resources/bin/locuset-connect \
verify --client hermesThe configuration stores a path to an owner-only enrollment file. It does not contain the enrollment credential itself. See Connect agents for Codex, Claude, Cursor, VS Code, OpenAI Agents SDK, and generic MCP clients.
The documentation follows Diátaxis. Start with the kind of help you need:
| Need | Documentation |
|---|---|
| Learn the app | Tutorials |
| Complete a task | How-to guides |
| Look up exact behavior | Reference |
| Understand the design | Explanation |
Audits, certification notes, release evidence, and clean-room research live under Project records. They are kept out of the user path so dated evidence is not mistaken for current guidance.
The desktop app combines an AppKit and WebKit shell, a Python and SQLite core, a React interface, and a bundled MCP stdio adapter. The native app owns a numeric-loopback service used by the dashboard and approved local clients.
Read Local-first architecture for the process boundaries and Local storage encryption for the data model.
The current package targets Apple Silicon on macOS 14 or later. Building requires Xcode command-line tools, Python 3.9 or later, and Node.js 22.22.2+, 24.15.0+, or 26+.
./packaging/macos/build_app.sh --dmgThe command writes:
.build/release/Locuset.app
.build/release/Locuset.dmg
Run the source and packaged-product checks with:
python3 -m unittest discover -s tests/core -v
python3 -m unittest discover -s tests/integrations -v
npm --prefix ui test
npm --prefix ui run build
npm --prefix ui run test:e2e
python3 scripts/verify_release.pyLocal builds use ad hoc signing. Public distribution still needs Developer ID signing, notarization, and a signed update feed. Maintainer instructions are in Sign and notarize the macOS app.
Please read SECURITY.md before reporting a vulnerability. Security boundaries are documented in:
The repository's pre-commit hook scans staged files for private keys, tokens, environment files, passwords, credential-bearing configuration, and secret-like test data.
Locuset is available under the MIT License.