MIRA OS: Persistent Memory and Text-Based LoRA in a Self-Hosted Agent

The problem MIRA OS picks: continuity without a new chat button

Most assistant frameworks treat a conversation as a disposable unit. You open a thread, you close it, and whatever the model learned about your preferences dies with it. MIRA OS takes the opposite position. The README states there is one conversation thread forever and no functionality to start a new chat. That single constraint is the whole design premise, and it forces the author to solve persistence inside a forward-pass transformer that is, by construction, ephemeral.

The intended audience is narrow. This is for someone who wants to self-host an assistant that accumulates a working relationship over months, and who is comfortable reading SQL scoring formulas and Python source to understand why a memory survived or faded. The README opens with the author describing a recipe generator that suffered 10,000 scope creeps and became, in their words, a comprehensive best-effort approximation of a continuous digital entity. That origin story matters for evaluation: this is one person's opinionated system, not a committee-designed platform. If you want a framework with a plugin marketplace and a support contract, MIRA OS is the wrong shape entirely.

How a turn actually flows: subcortical retrieval, then the primary model

Two auxiliary systems bracket the main response. The subcortical layer runs on every user turn and is an information-retrieval pass, not an answerer. According to the README, it reads the current message, the recent conversation, and the memories already in context, then resolves pronouns and fragmentary references into concrete search phrases, extracts named entities for graph lookup, decides which old memories are still relevant enough to retain, and classifies whether the turn needs heavier reasoning. Its output is invisible to the user. The point is that recall happens before generation, so the primary model does not have to first notice a gap and then decide to search.

The Peanut Gallery sits on the other side. Every five turns it asynchronously reads the recent conversation plus a compact ledger of commitments, tool calls, and tool results. Most of the time it stays silent. When the conversation has measurably drifted, it can inject a short-lived concern or coaching directive into the context window, and that guidance expires after two turns or when the segment collapses. Standard corrections are repaired silently; critical ones can authorize MIRA to break the fourth wall and admit the slip.

This split is the most interesting architectural decision in the project, and it is also the one with the least published detail. The README describes what the subcortical pass decides but not how it decides, and the classification threshold between straightforward and heavier reasoning is not specified. Treat that as a known gap rather than a hidden feature.

Memory decay runs on use-days, not calendar days

MIRA stores discrete synthesized memories rather than raw chat logs. The README links a scoring formula file at lt_memory/scoring_formula.sql, and states that memories decay unless they earn their keep through access, explicit references, links to other memories and entities, or real temporal relevance. The detail worth pausing on is the clock: decay runs on use-days, so a two-week vacation does not erase your history. That is a small implementation choice with a large behavioral consequence, and it distinguishes MIRA from systems that expire vectors on wall-clock TTLs.

Recall is mostly passive. Memories load into context through semantic similarity, entity hubs, memory traversal, filtering, and reranking. The memory_tool exists for the cases where the model needs an explicit search, wants to create or link a memory, or needs exact control over what comes back. The README is explicit that most recall happens before generation, which means the quality of the subcortical pass caps the quality of everything downstream. If retrieval picks the wrong memories, the primary model will not necessarily notice.

For document-shaped content, MIRA uses domaindocs: stable encrypted documents that do not decay, with section-level version history, sharing, pinned sections, and nested subsections. The model can expand, collapse, and subsection them autonomously. When a section is not in use, MIRA closes the drawer, so the body stops consuming context while the title, summary, and position in the tree remain visible for later reexpansion. Both the user and MIRA can edit the contents, and changes surface in the next composed context.

Text-Based LoRA: adapting prompts instead of weights

The README is blunt about the constraint: you cannot retrain an LLM's weights per user, but you can retrain its prompts. MIRA calls this Text-Based LoRA, and the loop has three stages. After each conversation segment collapses, an assessment extractor compares the conversation against MIRA's behavioral contract and records alignment, misalignment, and contextual passes along with the specific evidence and prompt section involved. Those signals accumulate in Postgres. Every seven use-days, a pattern synthesizer folds the accumulated signals into a descriptive user model covering what works, what fails, where friction appears, and what needs a check-in. A separate critic reviews the synthesis before it is loaded into the system prompt.

The synthesis is evolutionary rather than replacement. Each run builds on the previous one, and patterns can be reinforced, refined, revised, settled, or allowed to go dormant. This is a genuinely different approach from retrieval-augmented personalization, where user preferences sit in a vector store and get pulled in when similar. Here the adaptation is a written document that a critic has to approve, and it lives in the system prompt rather than in the retrieval index. The trade-off is legibility versus scale. You can read the synthesis and argue with it, which you cannot do with a fine-tuned adapter. But it also means a bad synthesis can sit in your system prompt for a full cycle before the next run corrects it, and the README does not describe a manual rollback path.

Conversation collapse and first-person memory traces

When a segment collapses, MIRA generates a first-person summary rather than a third-person one. The README gives the example of I debugged the IndexError in process_batch.py versus a third-person paraphrase, and explains the reasoning: third-person summaries created epistemic distance, so MIRA read them as logs about someone else rather than memories of work it did. Absolute timestamps replace relative ones because relative time becomes a lie the moment the sun sets. That is a small prose decision with a real effect on how the model treats its own history.

Each new summary sees the previous five summaries as context, which lets it reference prior work with hazy continuity. The current format produces a three-to-four sentence memory trace, a two-sentence precis, a short display title, and a complexity score. The trace carries the remembering; the other fields keep the conversation manifest useful without stuffing full history back into the window. If an active conversation grows too large before it naturally collapses, MIRA compresses older messages into one rolling continuation brief while leaving the most recent turns untouched.

The failure mode here is worth naming. Summaries that see only the previous five can drift, and a drift that compounds across dozens of collapses is hard to detect from inside the system. The README does not describe a consistency check that compares a new summary against older ones beyond that five-summary window.

Getting it running: tools/ auto-configuration and the API surface

The README states that tools auto-configure when dropped into a tools/ folder, and that you load the system and send cURL requests to talk to it. That is the entire documented onboarding path in the supplied material: place a tool in tools/, start the service, and interact over HTTP. The project topics list PostgreSQL and pgvector, which means a Postgres instance with the vector extension is part of the runtime, and the Text-Based LoRA signals and memory records both live in Postgres according to the README.

I have not installed or run this project, so I cannot give you a verified startup command sequence. What the material supports is narrower: the repository is Python, the default branch is main, the homepage is miraos.org, and the latest release is v2026.06.25 with a prior release explicitly titled Security Hardening & Reliability Sync. Before you commit, read the release notes for v2026.05.21, because a release named for security hardening usually implies earlier versions had issues worth understanding.

The tools/ auto-registration design is convenient and also a boundary you should think about. Any file dropped in that folder becomes callable, so the folder is effectively a trust boundary. The README does not describe a signing step, an allowlist, or a review gate for tools placed there.

Where MIRA OS is the wrong tool

The single-thread constraint is the first disqualifier for some use cases. If you need per-customer conversation isolation, or you want to run one instance for a team where each person gets their own history, the README describes no mechanism for that. There is one conversation thread forever, and the memory model, the Text-Based LoRA synthesis, and the Peanut Gallery ledger are all built around a single continuous relationship. Multi-tenant deployment is not a configuration flag here; it would be a fork.

The second limitation is operational. Memory decay, pattern synthesis, and the collapse pipeline all run on use-days, which means the system's behavior depends on interaction volume. An instance that sits idle for a month will not have run its synthesis cycles, and the README does not describe a catch-up path. The third is that the project is explicitly one author's work, described as their TempleOS, with contributions welcome but no described governance, roadmap process, or maintainer team. That is not a criticism of the code; it is a risk statement about bus factor that you should price into adoption.

Finally, the AGPL-3.0 license is a real constraint, not a formality. If you modify MIRA and expose it to users over a network, the copyleft terms are likely to reach your modifications. I am not a lawyer and this is not legal advice; if you plan to build a commercial service on MIRA, get the license reviewed before you write code against it.

How MIRA differs from Mem0 and similar memory layers

The closest comparison in this space is Mem0, which provides a memory layer you bolt onto an existing agent: you call it, it extracts and stores facts, and you retrieve them. MIRA inverts that relationship. Memory is not a library call inside someone else's agent loop; it is the agent loop. The subcortical pass runs unconditionally on every turn, the Peanut Gallery observes on a five-turn cadence, and the Text-Based LoRA synthesis writes into the system prompt rather than into a retrieval index. You cannot drop MIRA's memory into an existing LangChain or LlamaIndex pipeline without adopting its conversation model, because the memory system assumes there is exactly one thread and that segments collapse on a schedule.

The other difference is where personalization lives. Mem0-style systems personalize through what gets retrieved. MIRA personalizes through what gets written into the prompt by a critic-approved synthesis. The first is easier to inspect per-query; the second is easier to inspect per-week. If you want to see exactly which memory influenced which answer, a retrieval-based layer gives you a cleaner audit trail. If you want to see how the assistant's disposition toward you has shifted over a month, MIRA's synthesis document is the more direct artifact. Neither approach is strictly better; they answer different questions.

Editorial conclusion

Adopt MIRA OS if you want a self-hosted, single-thread agent whose memory model and prompt adaptation you can read in the source, and you are willing to run PostgreSQL with pgvector and accept AGPL-3.0 obligations. Do not adopt it if you need multi-user chat isolation, a hosted control plane, or a project with a documented contributor governance process; the README does not describe any of those. Verify three things first: that you can stand up the Postgres and pgvector dependency, that the tools/ auto-registration path matches how you ship credentials, and that the AGPL-3.0 copyleft terms fit how you intend to distribute anything you build on top of it.

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. taylorsatula/mira-OSS on GitHub