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.

Why Alma

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.

The model

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.

Consent by default

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.

How agents use it

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:

1. The agent calls alma_propose_facet.
2. Alma returns a confirmation question for the person.
3. The person approves from the CLI or Companion.
4. The agent redeems the one-time token with alma_record_facet.

No approval token, no durable write.

What ships today

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.

Companion

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

Portability

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.

Reset

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.

Protocol

The wire contract lives in the repo:

• schemas/2026-06/: JSON Schemas for protocol artifacts.
• conformance/2026-06/: conformance cases for running implementations.

Development

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.

License

Apache-2.0. See LICENSE.