Creating a Private Local-First Memory Layer with Alma

Overview

Alma is an experimental, local-first Model Context Protocol (MCP) server designed to provide AI agents with a persistent memory layer that remains under your control. By storing facts and preferences locally, Alma prevents your personal context from being trapped within individual vendor accounts while ensuring that agents do not gain permanent, unmonitored write access to your data. The project is currently an experimental hobby project, meaning APIs and behaviors may change.

Core Concepts

Alma operates on the principle of a self-model, where information is stored as facets—values associated with specific dimensions like person.display_name or work-style preferences. Each facet carries metadata including status, confidence, source, and evidence. The system maintains an append-only event log as the source of truth, allowing for full auditability and reversibility of changes by replaying the log.

The architecture enforces a strict consent-by-default model. Agents are treated as untrusted, and the human user remains the final authority. Reads are scoped by grant and purpose, and the default agent surface is set to least privilege. Sensitive layers and lens namespaces are opt-in, and every reading is audited. The practical result is that an agent can adapt to you, but it cannot quietly take over your memory.

Prerequisites and Setup

As of September 2026, Alma is an experimental project without pre-packaged releases. You must build the binaries from source using the Rust toolchain. Ensure you have cargo installed, then follow these steps:

cd alma
cargo build --release

After building, you can initialize your environment using the guided setup:

./target/release/alma quickstart

Alternatively, you can manually connect specific hosts:

./target/release/alma connect cursor --apply --global
./target/release/alma connect claude --apply

Once configured, the alma MCP server will be available to your chosen AI hosts. All data is stored at ~/.alma/alma.db by default, though this can be overridden using the ALMA_DB environment variable. The project uses the pinned Rust toolchain, and just is recommended for local checks such as just fmt-check, just lint, just test, just conformance, just coverage, and just check.

Workflow for Agents

Agents interact with Alma via the MCP protocol using the Rust rmcp SDK over stdio. The interaction follows a specific pattern:

• Reading: Agents use the alma_get_reading tool. Alma ranks relevant dimensions based on the agent's query. If an agent is unsure of the required keys, it can call list_dimensions to retrieve valid canonical dimensions. If an agent requests an unknown dimension, Alma returns UNKNOWN_DIMENSION with suggestions.
• Writing: Alma employs a "propose and approve" workflow. An agent calls alma_propose_facet, which triggers a confirmation request for the user. Once the user approves the change via the CLI or the alma-companion TUI, the agent receives a one-time token to execute alma_record_facet. No approval token means no durable write.

Management and Portability

The alma-companion tool provides a local UI for users who prefer not to edit JSON directly. 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, and approve or deny proposed memories. You can launch it as follows:

alma-companion
ALMA_SEED=./my-self.json alma-companion

To ensure portability, Alma supports exporting 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 and Deletion

You can erase the local store and start over using the CLI. Deletion is a human-only action and is not exposed as an MCP tool to prevent accidental or malicious data loss. Commands include:

• alma delete: Asks for confirmation before removing local data.
• alma delete --yes: Performs a non-interactive deletion.
• alma delete --keep-key: Wipes the store but retains the signing key.

Who Should Use Alma

Alma is intended for users who want to maintain strict control over their AI interactions and are comfortable building software from source. It is ideal for those who use multiple AI agents and want a unified, portable, and auditable memory layer that prevents vendor lock-in. For more information, visit the official repository.