Orvin

Backend for a voice-native memory service for voice AI agents, wired for Neon-backed Postgres, local open-source embeddings, and local Redis.

Current rebuild docs for the next architecture step live in docs/README.md. Multi-agent voice integration guidance lives in docs/voice-agent-integration.md.

The target product abstraction is channel-agnostic:

• voice agents are the core product surface
• interactions are the core runtime unit
• calls are one supported channel, not the main product definition

Stack

• FastAPI
• Python 3.12+
• Neon Postgres + pgvector
• Local Redis (working memory and context cache)
• FastEmbed with BAAI/bge-small-en-v1.5 (local open-source embeddings)
• Alembic migrations

Install

pip install orvin

Focused install surfaces are exposed as extras where they actually add dependencies:

pip install "orvin[v2]"
pip install "orvin[dev]"

For local repo testing before PyPI publish:

pip install .
pip install ".[v2]"

You can also run the operator surfaces with module entrypoints:

python -m orvin.cli --help
python -m orvin.mcp_server --help

Run

alembic upgrade head
uvicorn orvin.main:app --reload --app-dir src

For local Redis:

redis-server --daemonize yes --port 6379 --save '' --appendonly no --dir /tmp

For local-only development without auth, explicitly opt in:

$env:ORVIN_ALLOW_UNAUTHENTICATED='true'

For any shared or internet-facing deployment, configure ORVIN_API_KEYS.

Local stack with Docker

Copy .env.example to .env, then run:

docker compose up --build

This starts:

• pgvector-enabled Postgres
• Redis
• the FastAPI API service
• the outbox worker

The API will be reachable at http://localhost:8000, and GET /v1/meta exposes runtime, auth, and SDK surface metadata for tooling.

For the standalone test dashboard:

cd dashboard
npm install
npm run dev

Current status

This implementation includes:

• API scaffold
• first-party CLI commands for runtime, inspection, ingest, and seeding
• MCP stdio server with workspace-scoped read tools, resources, and opt-in ingest tools
• request/response schemas
• domain models
• Postgres repository
• SQLAlchemy models for the Postgres path
• Alembic migrations for interaction runtime fields, outbox retries, and idempotency
• local embedding pipeline via FastEmbed
• hybrid pgvector + full-text search
• Redis-backed session/context cache
• thin hot-path ingest with transactional writes and idempotency keys
• outbox-driven async jobs for memory extraction, embedding, episode creation, commitment reconciliation, and interaction consolidation
• durable-memory lifecycle handling for hypothesis promotion, supersession, repeated evidence, and tool-linked commitments
• evidence-aware context/search responses with confidence and retrieval explanations
• channel-aware retrieval policy, reactive-retrieval gating, and search caching
• debugger endpoints for memory evidence, audit trails, hot-state recovery, and runtime metrics
• issue extraction, repair history, acoustic hint memory, stale-commitment surfacing, and stronger episode summaries
• structured memory-intelligence pipeline with multilingual extraction, evidence spans, confidence calibration, interaction-level turn bundles, and optional model-backed extraction plus verification
• versioned memory history, contradiction relationships, participant event feeds, structured profile synthesis, and export/import/privacy tooling
• workspace write quota enforcement for high-volume ingest and batch import paths
• replay fixtures plus eval-oriented extraction tests and fixture-driven quality checks
• managed API key generation, revocation, and admin endpoints for distribution testing
• standalone Next.js operator dashboard for API keys, SDK snippets, MCP setup, connectors, documents, participants, and ingest playgrounds

Configuration is loaded from .env. Use .env.example as the baseline and point ORVIN_DATABASE_URL at your own Postgres instance or Neon branch.

Security

• All non-health API routes require an API key unless ORVIN_ALLOW_UNAUTHENTICATED=true is explicitly set.
• API keys are accepted via Authorization: Bearer <key> or X-API-Key: <key>.
• ORVIN_API_KEYS remains the bootstrap/admin key path.
• Managed keys created through /v1/admin/api-keys are stored by the platform and can be revoked independently.
• /v1/health and /v1/health/ready are readiness checks.
• /v1/health/live is a lightweight liveness check.

Fingerprinting

Every response includes:

• X-Orvin-Fingerprint
• X-Orvin-License
• X-Orvin-Edition
• X-Orvin-Version

This gives upstream AGPL builds an identifiable release fingerprint.

CLI and MCP

The repo now ships two operator-facing entrypoints:

• orvin for CLI operations such as health, context get, search, serve-api, and serve-worker
• orvin keys for managed API key list/create/revoke flows
• orvin-mcp for a stdio MCP server that wraps the same canonical API and local service layer
• orvin.OrvinClient as the first-party Python SDK surface
• sdks/typescript as the first-party TypeScript SDK package
• dashboard as the standalone testing UI

Remote MCP mode requires ORVIN_BASE_URL plus an API key. Local MCP mode is opt-in via --local or ORVIN_MCP_LOCAL_MODE=true.

Examples:

orvin health
orvin-mcp --local
orvin-mcp --base-url https://orvin.example --api-key $env:ORVIN_API_KEYS

By default the MCP server exposes only safe read tools and resources. Enable debug tools with --enable-debug-tools and enable mutating ingest tools with --enable-write-tools.

Examples

First-party examples live in examples/README.md.

SDK source now lives in:

• src/orvin/client.py for Python
• sdks/typescript for TypeScript

The TypeScript SDK is packaged as @orvin/sdk:

npm install @orvin/sdk

The main Track 8 examples are:

• adapter flows for LiveKit, Pipecat, browser, Deepgram, Vapi, Retell, and ElevenLabs runtimes
• CLI operator workflows in examples/cli_workflow.md
• stdio MCP client flow in examples/mcp_stdio_example.py
• document ingestion flow in examples/document_ingestion_example.py
• the direct dashboard app in dashboard/README.md

Test

$env:PYTHONPATH='src'; pytest -q

License

This project is licensed under AGPL-3.0-only. If you modify and run this server software for users over a network, the AGPL requires you to provide the corresponding source for that modified server program.