MIRA OS
A self-hosted personal assistant built for persistent memory, continuous conversation, and on-demand tool use.
Per-dimension scores and reasoning
The README says credentials are separated from tool implementations, Vault is initialized, stable documents are encrypted, and nonessential tools can be enabled ephemerally. The SSRF tests concretely cover DNS pinning, private addresses, and IPv6 transition-address bypasses, supporting some network and sensitive-data safeguards. Deductions reflect mostly unpinned dependencies, a one-line installer that installs dependencies and initializes several services, and externally consequential email, home-automation, reminder, and federation tools without demonstrated per-action authorization, confirmation thresholds, permission scopes, or audit policy. Document version history offers only localized recovery; no system-wide rollback is documented. Authorship, licensing, and MemGPT inspiration are attributed, but third-party attribution is incomplete.
The FastAPI, PostgreSQL, Valkey, Vault, provider, tooling, and NLP descriptions broadly agree with requirements.txt, while the security tests fit the stated HTTP-tool surface. Deductions reflect many dependencies without exact pins or upper bounds, an optional non-PyPI Lattice service requiring a separate daemon, and reliance on external APIs, model downloads, and infrastructure. The materials say installation verifies services and provider dialects handle failures, but show no concrete user-facing error messages, recovery guidance, or operational troubleshooting examples.
The materials cover local, Docker, hosted, interactive, and headless deployment and describe multiple providers, optional tools, the permanent-thread constraint, and some optional-dependency fallbacks. Triggers are unusually specific: retrieval each turn, observation every five turns, synthesis every seven use-days, timeout scans every five minutes, and on-demand tool activation. Deductions reflect an unclear target-user and production-resource baseline, semantic rather than enforceable conditions for autonomous tool activation and initiative, and no Linux distribution, hardware-sizing, or compatibility matrix.
The README is organized around memory, tools, architecture, licensing, and installation, with generally coherent terminology. Local, migration, and Docker instructions are concrete enough for full install-notes credit. AGPL-3.0 metadata, the README declaration, and license.txt agree. Deductions reflect the absence of a systematic FAQ, troubleshooting guide, compatibility table, formal limitations list, release policy, and changelog; MIRA, Mira, and anthropomorphic pronouns are used inconsistently. The author promises continued maintenance and invites contributions, but no team structure, response policy, security contact, or succession path is identified.
The product exposes web/API conversation, persistent memory, editable versioned documents, automatic retrieval, and on-demand tools, making outputs potentially usable for sustained knowledge work. Memory decay, live compaction, modular prompt composition, and metacognitive observation provide plausible marginal value. Deductions reflect that effectiveness is primarily asserted in the README without static output examples, benchmarks, or quality comparisons. Operation requires a database, cache, Vault, several models, and potentially paid external APIs, while resource use, latency, token savings, and hosted costs are not quantified.
Important architecture claims identify modules, events, intervals, dependencies, and a specific SQL formula path. requirements.txt and the two SSRF/DNS-pinning test files corroborate portions of the dependency and network-safety narrative. Deductions reflect the absence of core implementation files, a complete test inventory, release records, or design evidence for most memory and autonomous-agent claims. The README also mixes testable mechanism descriptions with promotional judgments such as a continuous digital entity or elegant brain-in-a-box, without consistently separating fact, inference, and author opinion.
- The installation command downloads and executes a script from the main branch rather than the reviewed revision; inspect it and pin a commit or verified hash before use.
- Most requirements are not exactly pinned. Produce a lockfile, scan dependencies for vulnerabilities, and document upgrade and remediation policy.
- Email, home automation, reminders, web access, and cross-server messaging can create real external effects; verify permission scopes, user confirmation, auditing, and revocation for every tool.
- Vault and encryption claims do not replace a key-lifecycle specification. Verify credential storage, log redaction, backups, deletion, rotation, and hosted-service data flows.
- The permanent conversation and synthesized user model may retain inferred personal information for long periods; confirm controls for inspection, correction, export, deletion, and opt-out.
- The supplied static evidence cannot establish runtime correctness, reproducible tests, or the absence of additional security defects.
What does this agent do, and when should you use it?
MIRA OS is a self-hosted digital assistant organized around one permanent conversation thread rather than disposable chats. Its working_memory module composes the system prompt from modular trinkets, while Subcortical retrieves relevant information, resolves entities, and assesses reasoning needs before each response. Older conversation segments become first-person memories, and PostgreSQL-backed long-term memory uses pgvector, semantic similarity, entity links, traversal, filtering, reranking, and use-day-based decay. The system also includes non-decaying encrypted Domaindocs, filesystem-discovered tools, and a Peanut Gallery process that periodically checks completed turns for measurable conversational problems. Users can access MIRA through its local web chat or API and deploy it with the local installer, Docker, or the hosted web and macOS experience at miraos.org. It is a strong fit for people who value continuity and self-hosted control, but its permanent single-thread model and multi-service runtime are meaningful adoption constraints.
On every user turn, Subcortical reads the current message, recent conversation, and memories already in context. It converts pronouns and fragmented references into concrete search phrases, extracts named entities, decides which older memories remain relevant, and classifies the reasoning load. The primary model then receives context assembled by working_memory trinkets, which can contribute memories, Domaindocs, reminders, time, and metacognitive guidance. Most memories are loaded before generation through semantic similarity, entity hubs, traversal, filtering, and reranking; memory_tool also supports explicit searching, creation, and linking. domaindoc_tool manages stable encrypted documents with section-level history, sharing, pinned and nested sections, and autonomous expansion or collapse. At startup, MIRA discovers tools in tools/; invokeother_tool catalogs their simple_description values and enables a tool ephemerally or pins it for the session. Every five minutes, a scheduled job finds conversation segments idle for 60 minutes and emits SegmentTimeoutEvent; SegmentCollapseHandler then creates the first-person summary, collapses the segment sentinel, invalidates caches, starts long-term memory extraction, processes user-model feedback, and publishes follow-up events. Every seven use-days, the Text-Based LoRA pipeline synthesizes accumulated behavioral evidence into a critic-checked user model. The resulting assistant streams conversational answers and can invoke bundled capabilities including contacts, email, weather, maps, reminders, web search, image generation, and Home Assistant.
- An individual who wants an assistant to retain preferences, project history, and prior decisions over a long-running relationship and accepts a permanent conversation thread.
- A technical team that wants to keep assistant data, credentials, and long-term memory on its own infrastructure while exposing a local web interface or API.
- A user collaborating with an assistant on large, structured reference material that should remain stable rather than participate in memory decay can use Domaindocs.
- A developer who wants email, weather, maps, reminders, Home Assistant, or custom capabilities loaded only when needed instead of keeping every tool definition in context.
- A long-term user willing to let the assistant adapt its behavioral prompt from accumulated evidence of successful, unsuccessful, and friction-heavy interactions.
What are this agent's strengths and limitations?
- Conversation collapse produces absolute-time, first-person memories and gives each new summary the previous five summaries for a deliberately continuous personal narrative.
- Memory decays by active use-days rather than calendar time and can earn retention through access, explicit references, entity or memory links, and temporal relevance.
- Filesystem discovery plus invokeother_tool permits ephemeral or session-pinned tool loading, reducing persistent context devoted to irrelevant tool schemas.
- Encrypted, versioned, collapsible Domaindocs provide a distinct home for durable long-form information that should not decay like synthesized memories.
- A provider-neutral dialect boundary is paired with local-script, Docker, and hosted deployment options.
- There is no new-chat function: one permanent conversation thread is an explicit architectural rule and may not suit workflows requiring hard separation between projects or clients.
- Self-hosting involves Python, PostgreSQL, Valkey, HashiCorp Vault, model downloads, and optional browser-automation assets, creating a larger operational footprint than a lightweight chat client.
- The supplied documentation does not give a concrete API endpoint, payload schema, or copyable first cURL request, so API adopters must inspect the implementation.
- Memory synthesis, decay decisions, metacognitive intervention, and behavioral adaptation depend on model-generated judgments, with no accuracy, latency, or recovery benchmarks provided.
- Hosted pricing is not specified beyond a credit and billing system, while self-hosted use may still incur charges from external model providers.
How do you install or deploy this agent?
For a local macOS or Linux installation, run:
curl -fsSL https://raw.githubusercontent.com/taylorsatula/mira-OSS/refs/heads/main/deploy/deploy.sh -o deploy.sh && chmod +x deploy.sh && ./deploy.shAnswer the on-screen configuration questions and provide credentials for the chosen model provider or local-provider settings. The installer handles dependency setup, a Python virtual environment, requirements, NLP and embedding model downloads, HashiCorp Vault initialization, creation of the mira_service database, and checks for PostgreSQL, Valkey, and Vault. Existing installations can run:
./deploy/deploy.sh --migrateFor Docker, build the base and application layers:
docker build -t mira-base:latest -f deploy/docker/Dockerfile.base .
docker build -t mira:latest -f deploy/docker/Dockerfile .
Start the interactive setup wizard with:
docker run -it -v mira-data:/opt/vault -p 1993:1993 mira:latestA documented headless example is:
docker run -e MIRA_ANTHROPIC_KEY=sk-ant-xxx -e MIRA_PROVIDER_KEY=gsk_xxx -v mira-data:/opt/vault -p 1993:1993 mira:latestVault state persists in mira-data; PostgreSQL and Valkey use container volumes.
How do you use this agent?
After installation, complete the setup wizard, select a model provider, and enter the applicable credentials or local-provider settings. Then use the bundled local web chat to begin the single continuous conversation; the Docker example publishes port 1993. The repository description says MIRA can also receive cURL requests, but the supplied material does not document a verifiable endpoint, request body, or copyable first API call. To add a capability, follow tools/HOW_TO_BUILD_A_TOOL.md and the existing Tool base class, stop MIRA, and restart it so startup discovery can register the new tool. Users who do not want to install the stack can create an account at miraos.org or use its downloadable macOS application; hosted usage is governed by that service's credit and billing system.
How does this agent compare with similar options?
MIRA explicitly credits Letta and MemGPT for the idea of allowing models to manage their own context windows. It describes additional mechanisms of its own, including a permanent thread, first-person segment collapse, use-day memory decay, Subcortical, Peanut Gallery, and Text-Based LoRA. The source provides no direct feature, performance, or cost comparison, so it does not support a winner-and-loser assessment.