> your AI agent picks dependencies from memory; give it dated facts — try starlog.dev ↗ vet your agent's deps ↗ vibe-coding is fine. vibe-importing isn’t. — try starlog.dev ↗ vibe-importing isn’t fine ↗ your agent has never seen your private packages — try starlog.dev ↗ facts for private packages ↗ a linter for the dependencies your AI agent picks — try starlog.dev ↗ a linter for agent deps ↗ whois is redacted, cdns mask the rest — get the real operator — try whoisgeni.us ↗ who really runs that domain ↗ domain attribution that shows its work — full evidence chain — try whoisgeni.us ↗ domain intel w/ evidence ↗

← Back to Articles

Memoria: Git-Like Version Control for AI Agent Memory

[ View on GitHub ]

Memoria: Git-Like Version Control for AI Agent Memory

Hook

Every Git commit is immutable and branchable. Your AI agent's memory? A mutable mess that corrupts itself over time. Memoria applies version control semantics to the memory layer—not files, but the structured data your agents use to remember who you are and what you've asked.

Context

Long-running AI agents face a memory corruption problem that short conversations never expose. When Claude remembers your coding preferences across weeks of pair programming, or an autonomous research agent builds knowledge over hundreds of sources, memory drift becomes catastrophic. A hallucinated fact poisons future reasoning. Contradictory preferences create inconsistent behavior. One bad memory write ruins an agent that took weeks to train on your workflow.

The standard solution—vector databases with append-only semantics—treats memory like logs: you can add, but rolling back requires manual surgery. Pinecone, Weaviate, and similar tools excel at semantic search but offer no transactional safety. If your agent writes 'user prefers tabs' when you actually prefer spaces, you're debugging embeddings and manually deleting records. Memoria recognizes this is fundamentally a version control problem: agents need to branch memory states during risky operations, snapshot before destructive changes, and merge learnings from isolated experiments—exactly what Git does for code.

Technical Insight

External Services

MatrixOne HTAP

Memoria Core

Client Layer

Initialize & Health

Memory Operations

Memory Operations

Store Typed Records

Semantic Query

Version Control

Retrieve Memories

Generate Embeddings

Scan Memories

Quarantine Low Confidence

Branch/Merge

Zero-Cost Copy

Immutable Versions

CLI Tool

MCP Server

REST API

Memory Engine

Hybrid Retrieval

(Text + Vector)

Contradiction Detection

Snapshot Manager

CoW Storage Engine

MVCC Snapshots

Embedding Model

(Local/Remote)

System architecture — auto-generated

Memoria's architecture sits atop MatrixOne, an HTAP (Hybrid Transactional/Analytical Processing) database with a Copy-on-Write storage engine. This isn't an arbitrary dependency—MatrixOne's CoW primitives enable zero-cost snapshots that make version control practical at the memory layer. Every memory mutation creates an immutable version without duplicating data, just like Git commits share blob storage.

Memory records are typed into four categories with distinct lifecycle semantics. Profile memories persist long-term facts ('prefers Rust for systems work'). Episodic memories capture conversation summaries with timestamps. Procedural memories store learned patterns ('when user says deploy, always ask about staging first'). Working memories are ephemeral task state, purged after goal completion. Each record includes vector embeddings for semantic search and metadata for governance:

// Core memory record structure
pub struct MemoryEntry {
    pub id: Uuid,
    pub memory_type: MemoryType,  // Profile, Episodic, Procedural, Working
    pub content: String,
    pub embedding: Vec<f32>,       // Semantic search vector
    pub confidence: f32,           // For contradiction detection
    pub tags: Vec<String>,
    pub created_at: DateTime<Utc>,
    pub snapshot_id: Option<Uuid>, // Links to version history
}

pub enum MemoryType {
    Profile,      // Long-term user facts
    Episodic,     // Conversation summaries
    Procedural,   // Learned behaviors
    Working,      // Temporary goal state
}

The branching model maps directly to MatrixOne's MVCC isolation levels. Creating a snapshot is a database-level operation, not application logic:

# Create snapshot before risky memory changes
curl -X POST http://localhost:8080/snapshots \
  -H "Content-Type: application/json" \
  -d '{"name": "before-refactor", "description": "Pre-codebase memory state"}'

# Agent makes memory changes in isolated branch
curl -X POST http://localhost:8080/memories \
  -H "Content-Type: application/json" \
  -d '{
    "memory_type": "Procedural",
    "content": "When refactoring, always run tests in Docker first",
    "tags": ["deployment", "testing"]
  }'

# If changes cause issues, rollback to snapshot
curl -X POST http://localhost:8080/snapshots/before-refactor/rollback

The hybrid search architecture addresses the semantic-lexical gap that pure vector databases miss. Memoria queries both vector similarity (using MatrixOne's built-in vector index) and full-text search simultaneously, ranking results by a weighted score. This means agents can find memories by meaning ('deployment preferences') but also exact phrases ('GOAL ACTIVE' for lifecycle management).

The steering rules system is where Memoria transcends being just a database client. Rules are markdown documents that get injected into agent contexts, teaching operational memory patterns:

# Memory Bootstrap Protocol

At conversation start:
1. Call `memory_retrieve` with query "user profile" to load preferences
2. Call `memory_retrieve` with query "active goals" to resume tasks
3. Only proceed with user request after memory context is loaded

# Snapshot Safety Protocol

Before any operation marked HIGH_RISK:
1. Call `snapshot_create` with descriptive name
2. Perform operation
3. If user reports issues, call `snapshot_rollback`

HIGH_RISK operations:
- Codebase refactoring (>100 lines changed)
- Database schema migrations
- Changing core procedural memories

These rules transform memory from implicit LLM behavior (hoping Claude remembers to check context) into explicit agent protocols (Claude follows documented procedures). The system doesn't just provide memory tools—it teaches when and how to use them.

Governance runs as a background process, detecting contradictions via embedding similarity and metadata comparison. If two memories have high vector similarity (cosine distance < 0.15) but conflicting tags or confidence scores, the lower-confidence entry gets quarantined:

-- Simplified contradiction detection query
SELECT m1.id, m2.id, 
       vector_cosine_distance(m1.embedding, m2.embedding) AS similarity
FROM memories m1
JOIN memories m2 ON m1.id < m2.id
WHERE m1.memory_type = m2.memory_type
  AND vector_cosine_distance(m1.embedding, m2.embedding) < 0.15
  AND m1.tags && m2.tags  -- Overlapping tags
  AND m1.confidence < 0.7  -- Low confidence threshold

Quarantined memories don't appear in retrieval results but remain in the database for human review. This prevents memory drift without requiring constant manual oversight—agents self-heal by recognizing their own contradictions.

Gotcha

MatrixOne is both Memoria's superpower and its Achilles heel. The CoW engine enables genuine zero-cost snapshots, but you're committing to running a distributed HTAP database for what could otherwise be a SQLite file. The Docker Compose setup is non-negotiable—there's no embedded mode, no lightweight fallback. For solo developers wanting to experiment with agent memory versioning, spinning up MatrixOne is substantial friction. Production deployments inherit MatrixOne's operational complexity: cluster management, replication topology, backup strategies. If your team isn't already running distributed databases, this is a significant infrastructure addition.

Snapshot explosion becomes a real problem at scale. Every rollback creates a new snapshot. Every experimental branch proliferates versions. Unlike Git where developers manually prune old branches, Memoria has no automated cleanup policy. Long-running agents accumulating months of memory will balloon storage unless operators manually delete snapshots—and the documentation doesn't prescribe when or how to do this safely. The steering rules don't cover snapshot hygiene, so it's entirely on the operator to build pruning logic. Contradiction detection also uses naive similarity thresholds that generate false positives. Two memories like 'prefers Python for scripting' and 'prefers Rust for systems code' might trigger quarantine despite being valid nuance, creating manual triage overhead.

Verdict

Use if: You're building long-lived AI agents where memory corruption is catastrophic—coding assistants that refactor codebases, research agents synthesizing across hundreds of sources, autonomous systems executing high-stakes operations. The Git-for-data model genuinely solves the rollback problem, and steering rules encode operational patterns that turn memory management from art into protocol. If your team already runs distributed databases or the agent's value justifies infrastructure investment, Memoria's transactional safety is worth MatrixOne's complexity.

Skip if: You're prototyping with ephemeral agents, need multi-tenant isolation out-of-the-box, or can't operationalize MatrixOne. Solo developers and small teams should use Letta (Python library with zero infrastructure) or Mem0 (managed service) instead. If your agents have short-lived conversations or memory mistakes aren't catastrophic, the standard RAG pattern with Pinecone plus LangChain gives you 80% of the value with 20% of the operational burden. Choose Memoria when branching and rollback justify running a database cluster for your agent's brain.