The Problem
AI agents today lack a persistent, version‑controlled memory layer. Facts, preferences, and decisions are lost or silently overwritten across sessions, leading to hallucinations, contradictory context, and the need for manual data duplication when experimenting with new behaviors.
What This Does
Memoria adds Git‑style version control to agent memory. Every mutation creates a snapshot stored in the MatrixOne database (memoria/crates/memoria-storage/src/store.rs), with a full provenance chain that enables instant branching, merging, and time‑travel rollback. The API surface lives in memoria/crates/memoria-api/src/lib.rs and exposes routes for memory CRUD, snapshots, and governance under memoria/crates/memoria-api/src/routes/. Embedding is handled by memoria/crates/memoria-embedding/src/lib.rs which supports a local model option for privacy‑first deployments. Governance logic—contradiction detection and quarantine—is implemented in memoria/crates/memoria-service/src/governance.rs and driven by plugin hooks in memoria/crates/memoria-service/src/plugin/. The CLI tool is at memoria/crates/memoria-cli/src/main.rs, and a Makefile at the repo root provides targets such as make build and make up for local development.
How To Use It
Setup
Clone the repo git clone https://github.com/matrixorigin/Memoria.git cd Memoria
Copy the example environment file and fill in your keys cp .env.example .env # root .env.example cp memoria/.env.example memoria/.env
Build the Rust workspace (requires Rust toolchain)
make build # referenced in the root Makefile
Start the stack (MatrixOne + Memoria services)
docker compose up -d # docker-compose.yml at repo root
Configuration
Required keys are defined in memoria/.env.example (e.g., MATRIXONEDSN, EMBEDDINGMODELPATH). The Dockerfile at memoria/Dockerfile builds the runtime image; the docker-compose.remote.yml file shows how to deploy to a remote host.
Running it
Start the API server: memoria/crates/memoria-cli/src/main server # CLI entry point
Or, via Docker: docker compose up memoria-api
The API listens on http://localhost:8080 (configured in memoria/crates/memoria-api/src/routes/mod.rs).
Basic workflow (from the README “See Git for Data in Action”): Create a branch of the current memory state: memoria branch create experimental. Add or update memories while on the branch; each change is snapshotted automatically. When satisfied, merge back into main: memoria branch merge experimental main. Roll back to a prior snapshot if needed: memoria snapshot rollback <snapshot-id>.
Real‑World Use
An autonomous research agent accumulates papers, notes, and hypotheses across weeks. With Memoria the agent’s knowledge base lives on main. When the team wants to test a novel reasoning strategy, they branch the memory, let the agent explore the new approach, and after validation merge the improved reasoning patterns. If the experiment degrades performance, a single rollback command restores the last stable snapshot, preserving weeks of accumulated context without manual export/import.
Code Health & Issues
Tests & CI: 24 test files exist across crates (memoria/crates/memoria-api/tests/, memoria/crates/memoria-mcp/tests/, etc.) and GitHub Actions workflows (.github/workflows/test.yml, test-gate.yml) run on every PR. License & Lockfile: LICENSE and Cargo.lock are present, confirming dependency hygiene. SDLC: Makefile provides make test, make lint, and make fmt targets; coverage appears adequate for the core crates. Potential risk: The rhai‑based governance plugin (memoria/crates/memoria-service/src/plugin/governancehook.rs) executes user‑written scripts; insufficient sandboxing could allow code injection if plugin manifests are not strictly validated. Missing: No explicit secrets‑scanning hook in the CI pipelines, but the .env.example is never committed, mitigating accidental key leakage.
The Bottom Line
Memoria delivers a genuine Git‑for‑Data experience for AI memory, with snapshot/branch/merge primitives, audit trails, and optional local embeddings—all backed by a mature Rust codebase, CI, and a clear licensing path. It is best suited for teams or products that need reproducible, rollback‑able agent context rather than solo developers seeking a lightweight RAG substitute.