memoria

<div align="center"> <img src="assets/memoria-logo.png" alt="Memoria Logo" width="300"/>

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.

Image: CI Image: Release Image: GitHub Stars Image: Downloads Image: License Image: MCP Image: MatrixOne Image: Paper

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

</div>

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

<table> <tr> <td align="center" width="33%">

🔀 Git for Memory

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

</td> <td align="center" width="33%">

🔍 Semantic Search

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

</td> <td align="center" width="33%">

🛡️ Self-Governing

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

</td> </tr> </table>

<table> <tr> <td align="center" width="33%">

🔒 Private by Default

Local embedding model option — no data leaves your machine

</td> <td align="center" width="33%">

🧠 Cross-Conversation

Preferences, facts, and decisions persist across sessions

</td> <td align="center" width="33%">

📋 Full Audit Trail

Every memory mutation has a snapshot + provenance chain

</td> </tr> </table>

Supported Agents

<p align="center"> <a href="https://kiro.dev"><img src="https://img.shields.io/badge/Kiro-00C853?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHRleHQgeD0iNCIgeT0iMTgiIGZvbnQtc2l6ZT0iMTYiIGZpbGw9IndoaXRlIj5LPC90ZXh0Pjwvc3ZnPg==&logoColor=white" alt="Kiro"/></a> <a href="https://cursor.sh"><img src="https://img.shields.io/badge/Cursor-000000?style=for-the-badge&logo=cursor&logoColor=white" alt="Cursor"/></a> <a href="https://docs.anthropic.com/en/docs/claude-code"><img src="https://img.shields.io/badge/Claude_Code-D97757?style=for-the-badge&logo=anthropic&logoColor=white" alt="Claude Code"/></a> <a href="https://openai.com/index/introducing-codex/"><img src="https://img.shields.io/badge/Codex-412991?style=for-the-badge&logo=openai&logoColor=white" alt="Codex"/></a> <a href="https://geminicli.com"><img src="https://img.shields.io/badge/Gemini_CLI-4285F4?style=for-the-badge&logo=google&logoColor=white" alt="Gemini CLI"/></a> <a href="plugins/openclaw/README.md"><img src="https://img.shields.io/badge/OpenClaw-FF6B6B?style=for-the-badge" alt="OpenClaw"/></a> <a href="plugins/hermes/README.md"><img src="https://img.shields.io/badge/Hermes-8B5CF6?style=for-the-badge" alt="Hermes"/></a> </p>

<p align="center"><i>Works with any MCP-compatible agent</i></p>

🧠 Memoria in Hermes

Memoria is available from the Hermes plugin catalog. Log in at Memoria and create/copy a memory-service API key, then run:

hermes plugins install memoria --yes-deps --enable
hermes memory setup
hermes memory status

In the interactive setup, select memoria, paste your API key at the masked prompt, and choose whether to enable automatic capture (off by default). Confirm that status reports memoria, installed and available, then exit any existing conversation and start a new one with hermes. Status checks local readiness; verify a live write using the complete Hermes guide. The free Memoria Cloud requires no local Memoria server or database. Self-hosting, fixed GitHub installation and named profiles are covered in the same guide.

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

For example, search your memories from Astra:

astra memory search "deployment preferences"

🚀 Quick Start

<details open> <summary><b>☁️ Memoria Cloud (Recommended — no Docker, no database)</b></summary> <br/>

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?"

</details>

<details> <summary><b>🐳 Self-Hosted (Docker — full data control)</b></summary> <br/>

# 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?"

</details>

<details> <summary><b>🦞 OpenClaw Plugin</b></summary> <br/>

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

</details>

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

💡 Why Memoria?

🔬 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

<p align="center"> <img src="assets/git4data-story-writing-demo.svg" alt="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." width="100%"/> </p>

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.

<details> <summary><b>What the demo shows</b></summary>

• 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

</details>

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

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

<details> <summary><b>Example: Conversation Lifecycle</b></summary>

┌─────────────────────────────────────────────────────────────────────────────┐
│  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             │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘

</details>

<details> <summary><b>Example: Goal-Driven Evolution</b></summary>

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

</details>

<details> <summary><b>Example: Branch for Risky Experiments</b></summary>

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

</details>

📚 API Reference

Core Tools

<details> <summary><b>Snapshots & Branches</b></summary>

</details>

REST clients can use cached-count snapshot listing to avoid historical count queries and exclude automatic safety snapshots.

<details> <summary><b>Maintenance</b></summary>

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.

</details>

Memory Types

Full API details: API Reference Skill

Retry-safe single-memory writes: Idempotent store protocol.

Trusted adapter content preservation: Content-filter policy.

🔧 Commands

🤖 For AI Agents

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

1. Load the Setup Skill — it has step-by-step instructions

2. Ask before acting: which AI tool? · database mode? · embedding service? (Self-Hosted only)

3. Run memoria init -i in the user's project directory

4. 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):

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

Image: Star History Chart

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

License

Apache-2.0 © MatrixOrigin