Mirix: a multi-agent memory layer that watches your screen

The problem Mirix attacks: an assistant that forgets between sessions

Most chat assistants keep a context window and nothing else. When the window closes, the user's preferences, the half-finished task and the reason a command failed are gone. Mirix is aimed at that gap. The README describes it as a personal AI that builds memory through screen observation and natural conversation, and the repository topics list llm-memory and memory-agents alongside personal-assistant.

The intended user is a developer wiring an assistant into their own application, not an end user buying a product. Evidence for that sits in the layout: a Poetry project with pyproject.toml, a FastAPI backend, a React dashboard under dashboard/, and a samples/ directory containing langgraph_integration.py, claude_agent.py and a memory viewer. The client is published separately on PyPI as mirix-client, so the server and the calling code can be versioned apart.

The scope is deliberately narrow. Mirix does not try to be a chat UI or an agent framework. It is the storage and retrieval layer underneath one.

Six memory components and the agents that own them

The design splits memory by kind rather than dumping everything into one vector index. The README names six components: Core, Episodic, Semantic, Procedural, Resource and Knowledge Vault, each managed by a dedicated agent. A meta-agent coordinates them.

Core memory holds labelled blocks, and the README's example uses two labels, human and persona, with persona initialised to "I am a helpful assistant." That is the always-present context an assistant would read on every turn. Episodic memory is the record of what happened in a session. Semantic memory is extracted facts, which is where a statement like "The moon now has a president" would land after being added through the client. Procedural memory stores skills learned from work processes, and the README is explicit that tool errors, retries and the fix that finally worked are the distiller's strongest signals. Resource memory and Knowledge Vault cover the remaining material.

Storage is PostgreSQL with the pgvector extension, plus Redis Stack. The docker-compose.yml comment states that Postgres with pgvector handles vector similarity search and Redis Stack provides caching and high-performance vector search. Search itself is described as PostgreSQL-native BM25 full-text search with vector similarity support, which means a query can combine keyword ranking with embedding distance in one database rather than two systems. That is a real architectural choice: it keeps deployment smaller, but it also means your retrieval quality is tied to how well Postgres is tuned for the workload.

Installing Mirix with docker compose and taking a first memory

The README's quick start has three steps. First, bring up the backend and dashboard from the repository root. This pulls images rather than building them.

docker compose up -d --pull always

After that, the dashboard should answer on http://localhost:5173 and the API on http://localhost:8531. The compose file also starts PostgreSQL on port 5432 with the default user, password and database all set to mirix unless you override MIRIX_PG_USER, MIRIX_PG_PASSWORD and MIRIX_PG_DB.

Second, create an API key in the dashboard and export it as MIRIX_API_KEY. Third, install the client.

pip install mirix-client

The client package requires Python 3.10 or newer, matching requires-python in pyproject.toml. A minimal session looks like this, adapted from the README example.

from mirix import MirixClient

client = MirixClient(
    api_key="your-api-key",
    base_url="http://localhost:8531",
)

client.add(
    user_id="demo-user",
    messages=[
        {"role": "user", "content": [{"type": "text", "text": "The moon now has a president."}]},
        {"role": "assistant", "content": [{"type": "text", "text": "Noted."}]},
    ],
    session_id="sess-demo-001",
)

Before any of that works you must call initialize_meta_agent with an llm_config and an embedding_config. The README's example uses gemini-2.0-flash with model_endpoint_type google_ai, and text-embedding-004 at embedding_dim 768. Those two blocks are where an LLM provider key is supplied, so Mirix itself does not include a model.

Retrieval takes a conversation rather than a bare string, which lets the server use the surrounding turns as context.

memories = client.retrieve_with_conversation(
    user_id="demo-user",
    messages=[
        {"role": "user", "content": [{"type": "text", "text": "What did we discuss on MirixDB in last 4 days?"}]},
    ],
    limit=5,
)
print(memories)

More examples live in samples/run_client.py.

Auto-dream: the consolidation pass, and why dry_run matters

Memory systems accumulate duplicates and contradictions. Mirix exposes an auto-dream endpoint for explicit cleanup, described in the README as reviewing existing memories, merging duplicates, resolving stale or conflicting entries where possible, and writing the result back through the memory tools.

The endpoint is POST /memory/auto_dream with a user_id query parameter and a JSON body carrying mode and dry_run. Modes map to components: core, episodic, semantic, resource, procedural, knowledge, and experience, which the README says reviews episodic, semantic and Knowledge Vault memories together. Procedural mode additionally takes a meta_agent_id and an optional last_n_sessions to distill recent sessions.

result = client.auto_dream(
    user_id="demo-user",
    mode="procedural",
    meta_agent_id=meta_agent.id,
    last_n_sessions=3,
    dry_run=False,
)
print(result)

Setting dry_run to true returns counts and shows what would be processed without applying updates. That is the only inspection mechanism the README documents, and it matters because consolidation is destructive by nature: merging duplicates means one of the two records stops existing in its original form. The README does not document a rollback for an auto-dream run that resolved something incorrectly, so the dry run is the safety net rather than an undo.

Upgrading an existing database is manual, and the server enforces it

This is the sharpest constraint in the project. Fresh databases get their full schema at startup. Existing databases do not. The README states that startup creates missing tables but never adds columns to existing ones, and that if migrations are pending the server refuses to start and names the exact scripts to run.

The scripts are plain psql files under scripts/, and order matters. The README gives this sequence for the skill-based procedural memory release.

psql "$MIRIX_PG_URI" -f scripts/migrate_procedural_to_skill.sql
psql "$MIRIX_PG_URI" -f scripts/migrate_add_message_session_id.sql
psql "$MIRIX_PG_URI" -f scripts/migrate_add_message_session_id_phase2.sql
psql "$MIRIX_PG_URI" -f scripts/migrate_add_conversation_message.sql
psql "$MIRIX_PG_URI" -f scripts/migrate_add_conversation_message_phase2.sql
psql "$MIRIX_PG_URI" -f scripts/migrate_add_skill_experience.sql
psql "$MIRIX_PG_URI" -f scripts/migrate_add_agent_trigger_state.sql
psql "$MIRIX_PG_URI" -f scripts/migrate_backfill_procedural_scope.sql

Two of those, the phase2 scripts, must run outside a transaction because they use CREATE INDEX CONCURRENTLY. That is not a detail you can skip past: wrap them in a transaction and the index creation fails. The README also notes each script is idempotent where possible and documents its own preconditions in its header, which is the honest way to present this, but it still means an upgrade is an operator task with a defined order, not a version bump. If your team cannot run psql against production Postgres, this is the wrong tool regardless of how well the memory model fits.

Where Mirix is the wrong choice

Two failure modes stand out. The first is operational. Mirix expects you to run PostgreSQL with pgvector, Redis Stack, a FastAPI backend and a dashboard, and to keep them in step. The compose file mounts ./.persist/pgdata as the data volume, so the default deployment keeps state in a directory next to the compose file. The README does not document a backup or restore procedure for that volume, and it does not document rollback for a migration that fails halfway. Anyone treating this as a drop-in library will be surprised by how much infrastructure it brings.

The second is model dependency. Mirix ships no model. You supply an LLM and an embedding model through llm_config and embedding_config, and the README's example is Google AI. Embedding dimension is set explicitly at 768 in that example, which means the vector column geometry is tied to your choice. Switching embedding providers later is not described as a supported operation, and changing dimension would require reshaping stored vectors. Pick your embedding model before you accumulate memories, not after.

There is also a maturity signal worth reading plainly. The repository is not archived and its last push was on 2026-09-12. The most recent release listed is v0.1.6 from 2025-12-25, described as a brand-new release of the memory system API, and pyproject.toml classifies the project as Development Status :: 4 - Beta. The API surface has moved between v0.1.2, v0.1.3 and v0.1.6, so code written against an early client may need rework.

How Mirix differs from Mem0 and from a plain vector store

Mem0 appears in the related searches for this project, and the contrast is instructive. Mem0's model, as generally described, is a memory layer you call with add and search operations over a mostly uniform store. Mirix instead partitions memory into six named components with separate agents, and offers a consolidation pass that operates per component. The practical difference is control over what gets remembered and where. In Mirix, a fact extracted from conversation goes to semantic memory, a record of a session goes to episodic memory, and a skill distilled from a failed kubectl command goes to procedural memory. Retrieval can then be scoped, and auto-dream can clean one component without touching the others.

The cost of that structure is configuration. You choose which agents to instantiate. The README's example lists core_memory_agent with its blocks plus resource, semantic, episodic, procedural and knowledge_vault agents, and the meta-agent coordinates them. A plain vector store asks you for a collection name and an embedding function. Mirix asks you for a provider, a model, a dimension and a set of agents before the first write.

If your assistant only needs to recall snippets of text, the extra structure is overhead. If it needs to distinguish what happened from what is true from what it learned to do, the separation is the point.

Editorial conclusion

Mirix fits developers building an assistant that needs durable, queryable memory and who are comfortable running Postgres, pgvector and Redis themselves. It does not fit anyone who wants a hosted memory API, or a team unwilling to run the migration scripts by hand, since the server refuses to start when migrations are pending. Before committing, verify that the embedding model and dimension you configure match what your Postgres instance was initialised with, and confirm the scripts in scripts/ cover the version you are upgrading from.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Mirix-AI/MIRIX on GitHub
3. Project website
4. README
5. Releases