project
Astra
The companion that knows you. A personal AI companion that runs on your hardware: coherent, accountable, and private by default.
open source
Python 3.12+
The companion that knows you. A personal AI companion that runs on your hardware: coherent, accountable, and private by default.
Most AI agents are someone else's cloud, someone else's memory, someone else's rules. Astra is yours. It runs locally, remembers durably, and separates five concerns that most agents collapse together: persona (who it is), memory (what it knows), conversation (what you're asking), tools (what it can do), and policy (what's allowed). That separation is the source of everything else.
Astra runs as one single-user FastAPI daemon: OpenAI-compatible Chat Completions and Responses APIs, streaming, model aliases, durable jobs, and a tool-using agent loop. MariaDB, Qdrant, local model services, and the chosen model provider remain independent services managed by the owner.
Astra separates authored persona, pinned facts, approved memory, current conversation, stance, skills, and revisable cognitive state. Each turn receives a frozen, bounded context snapshot rather than an unbounded transcript.
Astra stores conversations, memory provenance, persona versions, durable work, and cognitive state in MariaDB. Qdrant is a retrieval index, never the authority. Raw input is committed before optional downstream processing, so model, embedding, or index failure does not erase the conversation that caused it.
A scheduled reflection loop maintains bounded, revisable beliefs, goals, commitments, relationship state, and persona dimensions. It reads a structured snapshot, proposes typed changes, and application code validates and commits them atomically. Reflection is not a second agent with ambient tool access.
Astra is not a distant dashboard or an abstract glow. She is designed as a present working intelligence: attentive to the ongoing thread, able to remember the important details, and deliberate about what she acts on.
Every memory has source provenance. You can inspect, promote, reject, replace, and delete records. Candidates stay excluded until approved. Contradictions replace priors atomically — no silent drift. MariaDB is always the authorization authority; Qdrant only ranks what's already authorized.
astra-core is a single Python process. No Docker, no containers, no cloud dependency. Install it on macOS or Linux, point it at your MariaDB instance, and you're running. Your data never leaves your machine unless you choose to send it to a model provider.
The authored persona core is versioned, auditable, and immune to automatic memory modification. Learned adaptations are attributable, inspectable, and reversible. Your agent stays who you designed it to be — not whoever the last conversation made it.
Raw messages persist before any optional processing. If memory extraction, Qdrant sync, or anything downstream fails, your input remains durable. Conversation latency is independent of local-model or vector database availability.
Persona and memory are compiled into a bounded briefing — not an ever-growing transcript. This reduces model cost, improves coherence, and keeps sensitive context contained. Every pinned memory is included; ranked recall fills the remainder up to a hard budget.
Filesystem-backed skills are progressively disclosed instead of flooding every prompt. Astra can use built-in filesystem, shell, process, HTTP, web search, memory, and conversation-search tools alongside explicitly configured MCP servers.
Raw input is persisted immediately — before any processing. If anything fails downstream, your message is never lost.
A bounded context briefing is assembled from the stable persona contract, authorized memory records (MariaDB), and conversation history — not an ever-growing prompt.
The main model (OpenRouter) receives the compiled briefing. The agent reasons, decides what tools to invoke, and executes them directly on the host — no delegation control plane.
Built-in and MCP tools execute from the local daemon. Long-running commands have persisted lifecycle state, bounded output, and a tool-free completion follow-up in the original conversation.
Tool results — with provenance — are compiled into the final response. Memory extraction and indexing happen asynchronously after the response is sent, so conversation latency stays low.
Source message, extraction event, and lifecycle transitions are all recorded. You can trace why a memory exists — or who deleted it.
Candidates are excluded until promoted or explicitly high-confidence. You can inspect, reject, replace, and delete records. Contradictions atomically replace priors — no silent drift.
Qdrant ranks memories but never authorizes them. Deleted records are immediately unauthorized even if vectors remain stale. This is true in both astra-core and astra-agent.
The authored persona core is versioned, auditable, and immune to automatic memory modification. Learned adaptations are attributable, inspectable, and reversible.
| Concern | Prompt-centric agent | Vector-memory chatbot | Astra |
|---|---|---|---|
| Persona | Large mutable prompt | Prompt text | Structured stable kernel |
| Memory | Transcript / history | Nearest chunks | Structured records + provenance |
| Memory control | Delete history | Often coarse | Inspect, review, replace, delete |
| Retrieval auth | Application-dependent | Vector filters | MariaDB authority + vector intersection |
| Runs locally | Usually cloud | Usually cloud | Single process, no Docker |
| Context cost | Grows with history | Chunk injection | Bounded compiled briefing |
| Continuity | Per-session | Retrieved fragments | Durable jobs, processes, and reflection |
| Integrations | Ad hoc plugins | Usually webhooks | Hash-pinned sandboxed WASM |
| Ownership | Often multi-tenant SaaS | Often hosted | Single owner, local daemon |
FastAPI · Python 3.12+ · OpenRouter (main model) · local models (memory extraction, reranking) · MariaDB (canonical state) · Qdrant (semantic retrieval) · Alembic migrations · OpenAI-compatible Chat & Responses endpoints
Approved memory · hybrid recall · immutable turn snapshots · pinned-memory coverage · versioned persona · scheduled cognitive reflection
Durable cron and one-shot automations · managed background processes · MCP · Teams presence and chat · Outlook review and threaded email · proactive delivery
A delegated-user channel that polls a private chat, keeps a renewing availability presence, ingests supported inline media, replies in-thread, and can receive proactive delivery.
A delegated inbox channel with raw-MIME authentication checks, an authorized-sender allowlist, threaded replies, review-only handling for untrusted mail, proactive email, and bounded attachments.
Integrations are hash-pinned, import-free WebAssembly state machines. They have no direct filesystem, environment, database, process, socket, clock, or tool access; narrowly granted host brokers do the work.
Astra is a single-owner system, not a hosted multi-tenant platform. Its main local tools run with the daemon user's permissions: there is currently no universal command allowlist, approval workflow, capability policy, or container sandbox. Run it under a dedicated account and decide deliberately what that account may reach.
The older astra-agent repository remains an open-source research prototype for a future distributed, multi-tenant architecture. It is not the current product, should not be treated as a supported installation, and its mTLS, remote-agent, Vault, and tenant-isolation claims do not describe Astra today.