# Nacre

> A self-hosted knowledge index with fine-grained access control. Agents reach
> it over MCP, applications over a REST API. The access filter runs inside the
> index traversal rather than after it, so a request for the top k results
> returns k results the caller is permitted to see — not k minus whatever was
> stripped out afterwards.

Nacre is infrastructure, not an assistant. There is no chat interface and no
company bot; it is the context layer underneath them. It runs inside your
network via Docker Compose and does not phone home. The core is Apache 2.0;
commercial modules live in a separate private repository.

The thing that distinguishes it is the permission model, and the six invariants
below are treated as security incidents rather than bugs if broken:

1. The organization comes from the token — never from a request body, path, or
   header, not even as an administrator override.
2. Access filtering is a pre-filter, never a post-filter.
3. A failure to evaluate permissions denies access.
4. "No permission" and "no such object" are indistinguishable: 404, never 403,
   including the wording of the message.
5. A deleted document is never returned, including before garbage collection
   has taken its vectors.
6. `write` does not imply `read`. `admin` implies both. This is the opposite of
   most permission systems and is deliberate.

Current state: early, and it runs. Ingest, search, delete, grant and revoke, and
both MCP transports work end to end against a real PostgreSQL and a real Qdrant.
Deleting a document takes it out of results immediately — the vectors are
flagged, not waited on — and a background collector reclaims them afterwards. A
worker that dies mid-document has its work reclaimed by a lease rather than
leaving the document stuck.

Sign-in is email and password, with refresh tokens that rotate and revoke the
whole session if one is replayed. Search is reranked by a cross-encoder when a
deployment configures one. Rate limiting, idempotency keys and cursor pagination
are in, as are the TypeScript SDK and the admin UI.

Not built: reindexing a layer onto a different model, reading the audit log back
over the API, OAuth discovery and dynamic client registration, and multipart
upload on ingest.

The commercial modules — multi-tenancy, SSO and SCIM, document-level deny rules,
enterprise-managed authorization, SIEM export — are planned and none of them is
written. There is nothing to buy today; the whole of what exists is Apache 2.0.

## Documentation

- [Permission model](https://github.com/nacre-work/nacre/blob/main/docs/authz.md): the authorization algorithm, the six invariants, and the T1–T15 leak test plan. Read this first; everything else depends on it.
- [Quickstart](https://github.com/nacre-work/nacre/blob/main/docs/quickstart.md): first run, first document, first search.
- [Architecture](https://github.com/nacre-work/nacre/blob/main/docs/architecture.md): components, data flow, vector storage, reindexing, backups.
- [MCP server](https://github.com/nacre-work/nacre/blob/main/docs/mcp.md): transport, authorization, and the tool catalog.
- [REST API](https://github.com/nacre-work/nacre/blob/main/docs/api.md): conventions, status codes, pagination, idempotency.
- [OpenAPI contract](https://github.com/nacre-work/nacre/blob/main/docs/openapi.yaml): the machine-readable API description.
- [Configuration](https://github.com/nacre-work/nacre/blob/main/docs/config.md): environment variables, Compose profiles, and the metrics to alert on.
- [Audit log](https://github.com/nacre-work/nacre/blob/main/docs/audit.md): the access log schema and its guarantees.
- [Licensing](https://github.com/nacre-work/nacre/blob/main/docs/licensing.md): where the line between the open core and the commercial modules falls.

## Source

- [nacre](https://github.com/nacre-work/nacre): the core — data model, permission resolver, REST API, MCP server, indexing worker. Apache 2.0. It is the whole of the open source; the website, the brand and the commercial modules are separate repositories and closed.

## Optional

- [Trademark policy](https://github.com/nacre-work/nacre/blob/main/TRADEMARK.md): the name and mark are trademarks; referring to the project with them is fine, naming a fork Nacre is not.
- [The metaphor](https://nacre.work/): nacre is a structural material whose strength comes from how its layers stack rather than from the mineral itself, and which shimmers while staying opaque. Both map onto the product; neither appears in the API, the schema, or the logs, where the terminology is deliberately neutral.