The agent that knows you. A personal AI companion that runs on your hardware — coherent, accountable, and private by default. One project, two repos: the foundation that ships today, and the architecture we're building toward.
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.
The foundation that actually runs. A single-user, local daemon with durable MariaDB-backed memory, adaptive context assembly, and a consistent persona. No Docker required. One process, direct host tools, OpenAI-compatible endpoints. This is what powers Astra right now — the agent that knows you, on your machine.
The full multi-tenant D.E.P.A. architecture. A hosted control plane with mTLS-authenticated remote agents (ARAs), bounded capability leases, Keycloak OIDC, Vault PKI, and tenant isolation. Under active development — this is where astra-core is heading, with the lessons learned from shipping the simple version first.
→ astra-agent on GitHub ↗astra-agent was the original vision: a multi-tenant D.E.P.A. with mTLS, remote agents, OIDC, Vault PKI, and full tenant isolation — a platform, not just a program. It was also a six-container Docker stack before it answered a single message.
So we made a deliberate call: ship the simple thing that works, learn from it, then build up. astra-core was born from that decision — one Python process, no Docker, direct execution. It runs today. It ships with durable memory, a consistent persona, and the same principles that will eventually power astra-agent.
The D.E.P.A. architecture isn't abandoned. It's the north star. But the foundation underneath it had to be real first — and now it is.
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.
Every durable entity is tenant-scoped. MariaDB enforces ownership. Qdrant payload filters include tenant metadata as defense-in-depth. ARA certificates encode tenant identity. Cross-tenant isolation is an architectural guarantee, not a prompt convention.
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.
In astra-core, tools run directly on the host: filesystem access, shell commands, web requests. In astra-agent, this step delegates to an mTLS-authenticated ARA with a bounded, capability-scoped lease.
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 |
| Multi-tenant | Rarely | Rarely | astra-agent: architectural guarantee |
| Remote execution | Ambient process | Usually none | astra-agent: mTLS ARA + capabilities |
| Audit | Logs | Chat history | astra-agent: append-only domain events |
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
FastAPI · Python 3.12+ · uv monorepo · OpenRouter · MariaDB + Qdrant + S3/MinIO · Keycloak OIDC · Vault PKI · mTLS ARA identity · nginx ingress · Docker Compose · Textual TUI
Structured extraction (local model) · MariaDB-authorized recall · Qdrant semantic ranking · deterministic compiler fallback · hard context budget with pinned-memory priority
astra-core: direct host tools (filesystem, shell, web) · astra-agent: ARA SDK with capability-scoped leases, read-only repository agent, sandboxed workspace commands, privileged host ARA
# Clone and run (no Docker required) git clone https://github.com/jcplaboratory/astra-core.git cd astra-core # Set up MariaDB and install dependencies # See docs/operations.md for full macOS/Linux instructions uv sync export ASTRA_DATABASE_URL='mysql+aiomysql://user:[email protected]:3306/astra?charset=utf8mb4' uv run alembic upgrade head uv run astra-core # API at http://127.0.0.1:8000 # OpenAI-compatible endpoint at http://127.0.0.1:8000/v1/chat/completions
# Clone and sync the monorepo git clone https://github.com/jcplaboratory/astra-agent.git cd astra-agent uv sync --all-packages # Development mode (in-memory, no Docker) uv run astra-agent # Full secure stack (Docker + Keycloak + mTLS) bash install.sh # TUI in another terminal uv run astra-tui
Start with astra-core for a working agent today. Explore astra-agent for the multi-tenant future. Both are open source and under active development.
astra-core and astra-agent converge. The durable memory, context assembly, and persona consistency proven in astra-core become the foundation layer for astra-agent's multi-tenant control plane. Remote agents (ARAs) with mTLS, capability leases, and append-only audit trails graduate from development to production. One codebase, one architecture — the agent that knows you, running wherever you need it.
jcplaboratory/astra-agent ↗