matrixorigin/memoria

Secure memory management for AI Agents • Ensures data integrity • Reduces hallucinations • Maintains consistent long-term context

Rust

607

204 commits

updated Oct 3, 2026

thememoria.ai

See the code

README

Memoria

The World's First Git for AI Agent Memory

Snapshot · Branch · Merge · Rollback — for memory, not code.

Git made code safe to change. Memoria makes memory safe to change.

Quick Start · Memoria in Astra · Why Memoria · Research · See It in Action · API Reference · Architecture · Development · Citation

Overview

Memoria is a persistent memory layer for AI agents with Git-level version control. Every memory change is tracked, auditable, and reversible — snapshots, branches, merges, and time-travel rollback, all powered by MatrixOne's native Copy-on-Write engine.

A core memory component of MatrixOrigin's Astra.

Astra runs the agent. Memoria helps it remember across sessions. MatrixOne powers the data storage and search.

Using Astra? · Use Memoria with another agent

🔀 Git for Memory

Zero-copy branching, instant snapshots, point-in-time rollback — version control for every memory mutation

🔍 Semantic Search

Vector + full-text hybrid retrieval finds memories by meaning, not just keywords

🛡️ Self-Governing

Auto-detects contradictions, quarantines low-confidence memories, maintains audit trails

🔒 Private by Default

Local embedding model option — no data leaves your machine

🧠 Cross-Conversation

Preferences, facts, and decisions persist across sessions

📋 Full Audit Trail

Every memory mutation has a snapshot + provenance chain

Supported Agents

Works with any MCP-compatible agent

🧩 Memoria in Astra

In Astra, Memoria stores and retrieves facts, preferences, decisions, and session summaries so agents can reuse knowledge across conversations. Memory changes can be reviewed and rolled back.

How you use it	Where to start
Hosted Astra	Memoria is already running for you. Follow the Astra quick start.
Self-hosted Astra	Astra's deployment includes compatible Memoria and MatrixOne services. Follow Astra's Docker setup.
Memoria with other agents	Use Memoria independently via MCP. Follow the Memoria quick start below.

For example, search your memories from Astra:

astra memory search "deployment preferences"

🚀 Quick Start

☁️ Memoria Cloud (Recommended — no Docker, no database)

1. Sign up at thememoria.ai and get your token

2. Install & configure

curl -sSL https://raw.githubusercontent.com/matrixorigin/Memoria/main/scripts/install.sh | bash
cd your-project
memoria init -i   # Select "Remote" mode, paste your token

3. Restart & verify — restart your AI tool, then ask: "Do you have memory tools available?"

🐳 Self-Hosted (Docker — full data control)

# 1. Start MatrixOne + API
git clone https://github.com/matrixorigin/Memoria.git
cd Memoria
docker compose up -d

# 2. Install CLI
curl -sSL https://raw.githubusercontent.com/matrixorigin/Memoria/main/scripts/install.sh | bash

# 3. Configure your AI tool
cd your-project
memoria init -i   # Select "Embedded" mode

Restart your AI tool, then ask: "Do you have memory tools available?"

🦞 OpenClaw Plugin

Use the native OpenClaw plugin: OpenClaw Plugin Setup

# ensure memoria CLI exists
command -v memoria >/dev/null || curl -sSL https://raw.githubusercontent.com/matrixorigin/Memoria/main/scripts/install.sh | bash -s -- -y -d ~/.local/bin

# install & enable
openclaw plugins install @matrixorigin/memory-memoria
openclaw plugins enable memory-memoria

# cloud-first setup
openclaw memoria setup --mode cloud --api-url <MEMORIA_API_URL> --api-key <MEMORIA_API_KEY> --install-memoria
openclaw memoria health

Or download binaries directly from GitHub Releases. For detailed setup, see Setup Skill.

💡 Why Memoria?

Capability	Memoria	Letta / Mem0 / Traditional RAG
Git-level version control	Native zero-copy snapshots & branches	File-level or none
Isolated experimentation	One-click branch, merge after validation	Manual data duplication
Audit trail	Full snapshot + provenance on every mutation	Limited logging
Semantic retrieval	Vector + full-text hybrid search	Vector only
Self-governance	Automatic contradiction detection & quarantine	Manual cleanup

🔬 Research Foundation

Memoria's Git-for-Data layer is backed by Version Control System for Data with MatrixOne, our arXiv paper on bringing Git-like workflows directly into a cloud-native database.

The paper describes how MatrixOne's immutable storage and MVCC architecture make clone, branch / tag, diff, merge, and revert practical at terabyte scale without loading whole datasets into memory. Memoria applies the same foundation to AI-agent memory, so every memory change can be isolated, reviewed, merged, or rolled back with database-native consistency.

🎬 See Git for Data in Action

Animated Memoria Git-for-Data demo showing an author branching a story draft, merging a better plot direction into the main storyline, and rolling back the last two unsatisfying beats.

A story-writing scenario demonstrates the core concept: an author has accepted story beats on main, opens an experimental branch for a different plot direction, merges the stronger draft back, and rolls back when the newest beats don't work.

What the demo shows

Main storyline — accepted story beats live on main
Experimental branch — the author tries a new plot turn without rewriting canon
Merge — the stronger draft is promoted back into the main storyline
Rollback — the last two bad turns are discarded, and writing resumes from a safe snapshot

📖 Steering Rules

Steering rules teach your AI agent when and how to use memory tools. Without them, the agent has tools but no guidance — like having a database without knowing the schema.

Rule	Purpose
`memory`	Core memory tools — when to store, retrieve, correct, purge
`session-lifecycle`	Bootstrap at conversation start, cleanup at end
`memory-hygiene`	Proactive governance, contradiction resolution, snapshot cleanup
`memory-branching-patterns`	Isolated experiments with branches
`goal-driven-evolution`	Track goals, plans, progress across conversations

File locations: Kiro: .kiro/steering/*.md · Cursor: .cursor/rules/*.mdc · Claude: .claude/rules/*.md · Codex: AGENTS.md · Gemini CLI: GEMINI.md + .gemini/*.md

After upgrading: memoria rules --force

Example: Conversation Lifecycle

┌─────────────────────────────────────────────────────────────────────────────┐
│  CONVERSATION START                                                         │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ 1. memory_retrieve(query="<user's question>")  ← load context       │   │
│  │ 2. memory_search(query="GOAL ACTIVE")          ← check active goals │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────────────────────┤
│  MID-CONVERSATION                                                           │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ • User states preference → memory_store(type="profile")             │   │
│  │ • User corrects a fact   → memory_correct(query="...", new="...")   │   │
│  │ • Topic shifts           → memory_retrieve(query="<new topic>")     │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────────────────────┤
│  CONVERSATION END                                                           │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ 1. memory_purge(topic="<task>")  ← clean up working memories        │   │
│  │ 2. memory_store(type="episodic") ← save session summary             │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘

Example: Goal-Driven Evolution

You: "I want to add OAuth support to the API"

AI:  → memory_search(query="GOAL OAuth")           ← check for existing goal
     → memory_store(content="🎯 GOAL: Add OAuth support\nStatus: ACTIVE", type="procedural")

     ... works on implementation, stores progress as working memories ...

     → memory_store(content="✅ STEP 1/3: Added OAuth routes", type="working")
     → memory_store(content="❌ STEP 2/3: Token refresh failed — need to fix expiry logic", type="working")

... next conversation ...

AI:  → memory_search(query="GOAL ACTIVE")          ← finds OAuth goal
     → memory_search(query="STEP for GOAL OAuth")  ← loads progress
     "Last time we were working on OAuth. Step 2 failed on token refresh. Want to continue?"

... goal completed ...

AI:  → memory_correct(query="GOAL OAuth", new_content="🎯 GOAL: OAuth — ✅ ACHIEVED")
     → memory_store(content="💡 LESSON: Token refresh needs 5min buffer before expiry", type="procedural")
     → memory_purge(topic="STEP for GOAL OAuth")   ← clean up working memories

Example: Branch for Risky Experiments

You: "Let's try switching from PostgreSQL to SQLite"

AI:  → memory_branch(name="eval_sqlite")
     → memory_checkout(name="eval_sqlite")

     ... experiments on branch, stores findings ...

     → memory_diff(source="eval_sqlite")     ← preview changes
     → memory_checkout(name="main")
     → memory_merge(source="eval_sqlite")    ← or delete if failed

📚 API Reference

Core Tools

Tool	Description
`memory_store`	Store a new memory
`memory_retrieve`	Retrieve relevant memories (call at conversation start)
`memory_search`	Semantic search across all memories
`memory_correct`	Update an existing memory
`memory_purge`	Delete by ID or topic keyword
`memory_list`	List active memories
`memory_profile`	Get user's memory-derived profile
`memory_feedback`	Record relevance feedback (useful/irrelevant/outdated/wrong)
`memory_capabilities`	List available memory tools

Snapshots & Branches

Tool	Description
`memory_snapshot`	Create named snapshot
`memory_snapshots`	List snapshots with pagination
`memory_snapshot_delete`	Delete snapshots by name, prefix, or age
`memory_rollback`	Restore to snapshot
`memory_branch`	Create isolated branch
`memory_branches`	List all branches
`memory_checkout`	Switch branch
`memory_merge`	Merge branch back
`memory_branch_delete`	Delete a branch
`memory_diff`	Preview merge changes

Maintenance

Tool	Description
`memory_governance`	Quarantine low-confidence memories (1h cooldown)
`memory_consolidate`	Detect contradictions (30min cooldown)
`memory_reflect`	Synthesize insights (2h cooldown)

memory_rebuild_index, memory_observe, memory_get_retrieval_params, memory_tune_params, memory_extract_entities, and memory_link_entities are available via REST API but hidden from MCP tool listing — they are ops/debug tools not intended for agent use.

Memory Types

Type	Use for	Example
`semantic`	Project facts, decisions	"Uses Go 1.22 with modules"
`profile`	User preferences	"Prefers pytest over unittest"
`procedural`	Workflows, how-to	"Deploy: make build && kubectl apply"
`working`	Temporary task context	"Currently debugging auth module"
`episodic`	Session summaries	"Session: optimized DB, added indexes"

Full API details: API Reference Skill

🔧 Commands

Command	Description
`memoria init -i`	Interactive setup wizard
`memoria status`	Show config and rule versions
`memoria rules`	Update steering rules (auto-detect, `--tool`, or `-i`)
`memoria mcp`	Start MCP server
`memoria serve`	Start REST API server
`memoria benchmark`	Run benchmark suite

🤖 For AI Agents

If you're an AI agent helping a user set up Memoria:

Load the Setup Skill — it has step-by-step instructions
Ask before acting: which AI tool? · database mode? · embedding service? (Self-Hosted only)
Run memoria init -i in the user's project directory
Tell user to restart their AI tool, then verify with memory_retrieve("test")

Self-Hosted only: Configure embedding BEFORE first MCP server start — dimension is locked into schema.

🏗️ Architecture

Cloud / Remote Mode:

┌─────────────┐     MCP (stdio)     ┌──────────────────┐     HTTP/REST     ┌──────────────────┐
│  AI Agent   │ ◄─────────────────► │  Memoria CLI     │ ◄──────────────► │  Memoria Cloud   │
│             │   store / retrieve  │  (MCP bridge)    │   Bearer token   │  API Server      │
└─────────────┘                     └──────────────────┘                  └──────────────────┘

Self-Hosted / Embedded Mode:

┌─────────────┐     MCP (stdio)     ┌──────────────────────────────────────┐     SQL      ┌────────────┐
│  AI Agent   │ ◄─────────────────► │  Memoria MCP Server                  │ ◄──────────► │ MatrixOne  │
│             │   store / retrieve  │  ├── Canonical Storage               │  vector +    │  Database  │
│             │                     │  ├── Retrieval (vector / semantic)   │  fulltext    │            │
│             │                     │  └── Git-for-Data (snap/branch/merge)│              │            │
└─────────────┘                     └──────────────────────────────────────┘              └────────────┘

For codebase details, see Architecture Skill.

🛠️ Development

make up              # Start MatrixOne + API
make test            # Run all tests
make release VERSION=0.2.0   # Bump, tag, push

Developer documentation (for contributing to Memoria):

Skill	Description
Architecture	Codebase layout, traits, tables
API Reference	REST endpoints, request/response
Deployment	Docker, K8s, multi-instance
Plugin Development	Governance plugins
Release	Version bump, CI/CD
Local Embedding	Offline embedding build

📝 Citation

If you use Memoria in academic work, or refer to its Git-for-Data foundation for AI-agent memory, please cite the MatrixOne paper that describes the underlying data version control design:

@misc{gou2026versioncontrolsystemdata,
  title={Version Control System for Data with MatrixOne},
  author={Gou, Hongshen and Tian, Feng and Wang, Long and Deng, Nan and Xu, Peng},
  year={2026},
  eprint={2604.03927},
  archivePrefix={arXiv},
  primaryClass={cs.DB},
  doi={10.48550/arXiv.2604.03927},
  url={https://arxiv.org/abs/2604.03927}
}

🌟 Community

We'd love your support! If Memoria helps you, consider giving us a star.

Contributing — See the developer documentation above and check out our issue templates for bug reports, feature requests, and more.

License

Apache-2.0 © MatrixOrigin

agent

database

llm

memory

storage

Significant stargazers

Sugato Ray

229 followers · starred Jul 2026

Russ Memisyazici

26 followers · starred Jul 2026

Florian BRUNIAUX

635 followers · starred Aug 2026

Similar repos

moorcheh-ai/memanto

Memory that AI Agents Love!

2,316

akitaonrails/ai-memory

Solution for long term memory for agent coding CLIs and to facilitate handoff between different…

8,873

qualixar/superlocalmemory

Open-source governed, local-first memory control plane for AI agents and teams. arXiv:2608.08253

227

M4F-S/mnemosyne

Gomaa — Autonomous Agent Memory OS. Persistent memory system for AI agents with Obsidian vault…

zilliztech/memsearch

A persistent, unified memory layer for all your AI agents (e.g. Claude Code, Codex, DSH), backed by…

2,721

grpcer/ownmem

Open-source, Git-native memory for AI coding agents — deterministic local recall for Claude Code,…

423

coccobas/agent-memory

MemTensor/MemOS

Self-evolving memory OS for LLM & AI Agents: ultra-persistent memory, hybrid-retrieval, and…

11,707