Alma gives AI agents a memory that belongs to you.
It is a local-first MCP server for the facts and preferences you keep repeating across new chats: your name, role, working style, answer preferences, current context, principles, values, and other parts of your self model.
The goal is simple: an agent should be able to understand you without trapping that understanding inside one vendor account, and without getting permanent write access to your personal context.
Alma keeps the data on your machine, exposes only the parts you approve, and makes every durable change auditable.
Status: experimental hobby project. APIs and behavior may change.
AI agents are becoming long-running collaborators, but their memory is still fragmented:
- Each tool learns a separate version of you.
- New chats often start from zero.
- Vendor memory is hard to inspect, move, or share across tools.
- Letting an agent write directly to long-term memory is too much trust.
Alma is a small local layer between you and the agents you use. The agent can ask Alma what it is allowed to know, and Alma returns a scoped Reading instead of the full store.
Alma stores a self model as facts called facets. A facet is a value for a specific
dimension, such as person.display_name
or a work-style preference. Facets carry status, confidence, source, and evidence.
The source of truth is an append-only event log. Current state is rebuilt from the log, which keeps changes inspectable and reversible by replay.
Agents do not edit facts directly. They can observe weak signals, record evidence-backed behavior when explicitly granted, or propose a new facet for the person to approve. Durable writes require a human approval token.
Alma treats the agent as untrusted and the local human as the authority.
- Reads are scoped by grant and purpose.
- The default agent surface is least privilege.
- Sensitive layers and lens namespaces are opt-in.
- Admin actions live in the CLI, Companion, or an explicit admin server mode.
- Every Reading is audited.
- Full export is admin-only.
The practical result: an agent can adapt to you, but it cannot quietly take over your memory.
Agents talk to Alma over MCP, using the official Rust rmcp SDK over stdio.
The main read tool is alma_get_reading
. Agents pass the user's question and Alma
ranks the relevant dimensions in the Reading focus. If an agent needs exact keys,
it calls list_dimensions
first instead of guessing.
For example, a question about your name should resolve to person.display_name
,
not a made-up key like identity.name
. If an agent asks for an unknown canonical
dimension, Alma returns UNKNOWN_DIMENSION
with suggestions.
For writes, the normal path is propose and approve:
- The agent calls
alma_propose_facet
. - Alma returns a confirmation question for the person.
- The person approves from the CLI or Companion.
- The agent redeems the one-time token with
alma_record_facet
.
No approval token, no durable write.
Alma currently builds three local binaries:
alma-server
: the MCP server agents connect to.alma
: the CLI for setup, grants, proposals, export, and reset.alma-companion
: a local TUI for reviewing and managing your self model.
All three use the same store at ~/.alma/alma.db
. You can override it with
ALMA_DB
.
There are no packaged releases yet. Build from source with Cargo.
cd alma
cargo build --release
Then run the guided setup:
./target/release/alma quickstart
Or connect a host manually:
./target/release/alma connect cursor --apply --global
./target/release/alma connect claude --apply
Reload the host and the alma
MCP server should appear.
alma-companion
is the local UI for people who do not want to edit JSON. It opens the same store as the server and CLI.
Use it to:
- Browse and confirm facets.
- Preview the Reading an agent would receive.
- Review grants, requests, and audit events.
- Approve or deny proposed memories.
alma-companion
ALMA_SEED=./my-self.json alma-companion
Your self model should not be trapped in one app.
alma_export_bundle
exports the full event log as a compact JWS signed with Ed25519. The public key is embedded in the header, so the bundle can be verified without a prior key exchange. Import replays the events into a fresh store, and tampering invalidates the signature.
You can erase the local store and start over.
alma delete # asks for DELETE before removing local data
alma delete --yes # non-interactive
alma delete --keep-key # keep the signing key, wipe the store
Deletion is a human-only action. It is not exposed as an MCP tool.
The wire contract lives in the repo:
: JSON Schemas for protocol artifacts.schemas/2026-06/
: conformance cases for running implementations.conformance/2026-06/
The project uses the pinned Rust toolchain. just
is optional but recommended for local checks.
just fmt-check
just lint
just test
just conformance
just coverage
just check
CI runs build, tests, lint, conformance, coverage, and cargo audit
. Release automation is intentionally not enabled yet; builds are local-only.
Apache-2.0. See LICENSE.