agience-core
# Agience **The operating system that AI workflows trust.** Agience turns AI-generated output into durable, governed knowledge artifacts with identity, provenance, and version history so humans and agents can safely collaborate on the same information substrate. --- ## Why Agience AI generates output. It doesn't create trust. Any LLM can produce summaries, drafts, and decisions at scale — but without identity and provenance, those outputs have no chain of custody and no reason for anyone downstream to build on them. Agience is what turns AI output into something an organization can actually rely on. When an agent ingests a transcript, the result is a set of typed artifact objects — decisions, actions, constraints — committed into versioned collections under human review. The same object a human edits in the UI is the object an agent reads over MCP. Accountability follows from the architecture, not from policies or prompts. --- ## Core Properties **Artifacts, not files.** Every object — document, transcript, agent config, MCP server registration, collection entry — is an artifact. Typed content, structured context, stable ID, full version history, and a record of what produced it. **Human-in-the-loop is structural.** Approval gates are first-class operators in any workflow, not a policy layer you bolt on later. The architecture enforces the boundary; it does not rely on prompts. **MCP-native throughout.** Agience is both an MCP server (exposing tools to VS Code, Claude Desktop, Cursor, or any compatible client) and an MCP client (consuming GitHub, Slack, filesystem, and other vendor MCP servers). **Trust is declared, not assumed.** Scoped API keys define exactly what each agent or server can read, write, or invoke. Identity comes from the auth token, never the request body. Delegated operations carry a record of who authorized them. **Provenance is infrastructure.** Like a filesystem journal, provenance in Agience is structural. Committed artifacts carry records of what produced them, from what inputs, under whose authority. Not a premium feature — a consequence of how the system is built. **Composable agent servers.** The platform ships with eight purpose-built MCP servers covering ingestion, retrieval, reasoning, output, networking, security, governance, and finance. Each is a standalone FastMCP service. Deploy the ones you need, replace the ones you don't. --- ## The OS Analogy | OS Concept | Agience | |---|---| | File records / inodes | Artifacts | | Windows / explorer views | Cards (UI layer) | | File extensions | MIME content types | | Working directory | Workspace | | Published filesystem | Collection | | Save / publish | Commit | | Kernel services | Core platform | | Peripheral drivers | Agent persona servers | | Third-party applications | External MCP servers | | Processes / jobs | Agents / Operators | | System calls | MCP tool calls | | Filesystem indexer | MANTLE encrypted search (BM25 + IVF) | | Capability-based access | Scoped API keys | | Change journal | Provenance chain | --- ## What Ships Today - **Artifact model** — typed, versioned objects with stable IDs, full history, and graph relationships - **ArangoDB architecture** — all artifact storage in ArangoDB; workspaces for ephemeral drafts, collections for committed versions - **Commit flow** — explicit workspace → collection promotion; nothing published silently - **Encrypted hybrid search** — MANTLE-SSE blind-token BM25 + MANTLE encrypted IVF vector search, fused via RRF; all posting lists and embeddings AES-256-GCM at rest in S3 - **Multi-provider OAuth2** — Google, Microsoft Entra, Auth0, custom OIDC, username/password; RS256 JWT + scoped API keys - **MCP server** — universal gateway in Chorus at `/{server_id}/mcp`; advertised via `/.well-known/mcp`; works in VS Code, Claude Desktop, Cursor - **Agentic chat loop** — chat artifacts with an 8-tool surface and multi-turn LLM loop - **Live stream ingestion** — OBS → SRS → real-time AWS Transcribe; transcript artifacts committed on stream end - **S3/CloudFront media handling** — direct browser-to-S3 presigned upload, signed CDN delivery, orphan cleanup - **Eight agent persona servers** — Astra (ingestion), Sage (retrieval), Verso (reasoning), Aria (output), Iris (comms), Mantle (governance), Seraph (security), Ophan (finance) See [ROADMAP.md](ROADMAP.md) for the full capability inventory and what's coming next. --- ## Getting Started ### Run Agience at Home (stable build) No git clone needed. One command installs the full platform on your machine. Runs at `https://home.agience.ai` — that domain always resolves to `127.0.0.1`, so traffic never leaves your machine. Caddy fetches the TLS certificate automatically. **Windows (PowerShell):** ```powershell irm https://get.agience.ai/install.ps1 | iex ``` **Linux / macOS:** ```bash curl -fsSL https://get.agience.ai/install.sh | sh ``` After that: `agience up` / `agience down` / `agience update`. > **On a restricted network or prefer plain HTTP?** > The plain mode runs at `http://localhost:8080` with no domain or certificate required. > ```powershell > irm https://get.agience.ai/install.ps1 | iex -Mode plain > ``` > ```bash > curl -fsSL https://get.agience.ai/install.sh | sh -s -- --mode plain > ``` ### Developer Setup (build from source) For contributors and developers who want to modify the platform: ```bash git clone https://github.com/Agience/agience-core.git cd agience-core ``` **Windows:** ``` agience dev -f --build ``` **Linux / macOS:** ```bash ./agience dev -f --build ``` This starts the support containers (Arango / Postgres / MinIO) in Docker, installs Python dependencies into a `.venv`, and launches Origin / Mantle / Chorus / Facet locally. The setup wizard handles OAuth and LLM configuration on first boot — no manual `.env` file required. Full developer guide: [`docs/getting-started/local-development.md`](docs/getting-started/local-development.md) ### Hosted Sign up at [agience.ai](https://agience.ai) — no setup required. ### Edge builds (contributors and testers) Published on every merge to `main`. Not for production use. **Windows (PowerShell):** ```powershell irm https://get.agience.ai/install.ps1 | iex -Channel edge ``` **Linux / macOS:** ```bash curl -fsSL https://get.agience.ai/install.sh | sh -s -- --channel edge ``` --- ## Architecture Four containers; the platform deploys as four named images plus three support services (`init`, `graph` / Arango, `sql` / Postgres, `content` / MinIO, `stream` / SRS) wired together by `docker compose`. ``` ┌─────────────────────────────────────┐ │ Facet (React / Vite) │ Cards, grid, windows, navigation └─────────────────────────────────────┘ │ ┌─────────────────────────────────────┐ │ Chorus (FastMCP unified host) │ Aria · Astra · Sage │ Universal MCP gateway, persona │ Iris · Ophan · Seraph · Verso │ servers, ui:// viewers │ + relay WebSocket for desktop hosts └─────────────────────────────────────┘ │ HTTP JSON-RPC + REST ┌─────────────────────────────────────┐ ┌─────────────────────────────┐ │ Mantle (FastAPI artifact kernel) │ │ Origin (FastAPI identity) │ │ Type-blind CRUD + commit + events │ │ OIDC · grants · passkeys │ │ Encrypted MANTLE+SSE search (S3) │ │ Scoped API keys · setup │ │ ArangoDB · MinIO · S3 │ │ Postgres │ └─────────────────────────────────────┘ └─────────────────────────────┘ ``` Architecture spec: [`.dev/features/four-container-architecture.md`](.dev/features/four-container-architecture.md) · [`.dev/features/layered-architecture.md`](.dev/features/layered-architecture.md) ### Repo layout ``` src/origin/ Identity service (FastAPI + Postgres) src/mantle/ Artifact kernel (FastAPI + Arango + encrypted search) src/chorus/ Persona MCP servers + universal gateway (FastMCP) src/facet/ React + Vite + Tailwind UI src/kernel/ Shared Python (config, key_manager, scopes, embeddings) package/types/ Builtin MIME type definitions (cross-service) package/docker/ Compose files + per-service Dockerfiles package/install/ Unified install.sh / install.ps1 + home + plain compose package/seeds/ Declarative bootstrap artifacts package/hosts/ Desktop companion relay runtime docs/ Public-facing documentation .dev/features/ Internal design specs and migration plans ``` --- ## Documentation | | | |---|---| | [Platform Overview](docs/overview/platform-overview.md) | What ships and how it fits together | | [Self-Hosting Guide](docs/getting-started/self-hosting.md) | Deploy on your own infrastructure | | [MCP Setup](docs/mcp/client-setup.md) | Connect VS Code, Claude Desktop, Cursor | | [Search Query Language](docs/reference/search-query-language.md) | `+required`, `~semantic`, `type:`, `tag:` operators | | [MCP Overview](docs/mcp/overview.md) | Full MCP server and client architecture | | [ROADMAP.md](ROADMAP.md) | Shipped and in-progress capabilities | | [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution guidelines and CLA | --- ## Contributing Bug reports, documentation improvements, new agent tools, and thoughtful feature proposals are welcome. 1. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [CLA.md](CLA.md) 2. Open an issue before writing code for new features 3. Security issues → **[email protected]** (do not open a public issue) --- ## License Agience Core is licensed under the **GNU Affero General Public License v3.0** (AGPL-3.0-only). - **Free use**: open-source and AGPL-compliant deployments, including network-accessible services that share source - **Commercial license required**: proprietary/closed-source use, managed services without source disclosure, OEM/embedded distribution, white-label use See [LICENSE.md](LICENSE.md).