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 · 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.

🔀 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

🚀 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 toolcd 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 existscommand -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

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.

Name		Name	Last commit message	Last commit date
.claude/rules		.claude/rules
.cursor/rules		.cursor/rules
.gemini		.gemini
.github		.github
.kiro		.kiro
assets		assets
benchmarks/datasets		benchmarks/datasets
config		config
docs		docs
grafana		grafana
memoria		memoria
plugins		plugins
scripts		scripts
sdk/python		sdk/python
skills		skills
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.mergify.yml		.mergify.yml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SKILLS.md		SKILLS.md
cliff.toml		cliff.toml
docker-compose.remote.yml		docker-compose.remote.yml
docker-compose.yml		docker-compose.yml

Navigation Menu

Uh oh!

Repository files navigation

Memoria

Overview

Supported Agents

🚀 Quick Start

💡 Why Memoria?

🔬 Research Foundation

🎬 See Git for Data in Action

📖 Steering Rules

📚 API Reference

Core Tools

Memory Types

🔧 Commands

🤖 For AI Agents

🏗️ Architecture

🛠️ Development

📝 Citation

🌟 Community

License

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Memoria

Overview

Supported Agents

🚀 Quick Start

💡 Why Memoria?

🔬 Research Foundation

🎬 See Git for Data in Action

📖 Steering Rules

📚 API Reference

Core Tools

Memory Types

🔧 Commands

🤖 For AI Agents

🏗️ Architecture

🛠️ Development

📝 Citation

🌟 Community

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages