AGENTS.md
This page helps AI agents navigate the Unbound documentation. Copy it into your repository to give AI coding assistants full context on the Unbound API and data model.
Key Concepts
Six canonical entities. All personal data normalizes into: Person, PlatformIdentity, Conversation, Message, Event, Document (plus Attachment as a sub-entity of Message).
Two-tier identity. PlatformIdentity represents a person on a specific platform (a phone number, email, Slack handle). Person is the resolved real-world identity that one or more PlatformIdentities link to.
WriteStore / ReadStore. Writes go to an append-only versioned store. A Projector asynchronously builds denormalized read-optimized representations. Reads never touch WriteStore.
QueryScope. Every Store method requires a QueryScope (tenant ID + optional data scope filters). This is a compile-time enforcement of tenant isolation.
Connectors. Platform integrations (iMessage, Slack, Gmail, etc.) that consume the same write API as external applications. They are API consumers, not special internal components.
Provenance. Every relationship carries metadata indicating how it was established: platform_reported, exact_match, user_confirmed, heuristic, ai_suggested. Consumers decide what to trust.
Navigation by Question
| Question | Document |
|---|---|
| What entities does the system store? | Data Model |
| How does data get into the system? | Ingestion |
| How are identities linked across platforms? | Entity Resolution |
| What queries and mutations does the API support? | API |
| What is the system architecture? | Architecture |
| How is the GraphQL API implemented? | API Implementation |
| How does search work? | Search & Indexing |
| How is security and privacy handled? | Security & Privacy |
| What problem does this solve and why? | Project Vision |
| How does tenant isolation work? | Security & Privacy — QueryScope section |
| How does the write path work end-to-end? | Architecture — Data Flow section |
| What platforms are supported for ingestion? | Ingestion — Data Source Coverage section |
Reading Order
For full system understanding, read in this order:
- Project Vision — why this exists
- Data Model — what the system stores
- Ingestion — how data gets in
- Entity Resolution — how identities are linked
- API — how data is queried and written
- Architecture — how the system is structured
- Security & Privacy — how data is protected
- Remaining technical specs as needed for implementation context
Conventions
- API transport: GraphQL primary (gqlgen, schema-first), minimal REST
- IDs: UUIDv7 (timestamp-prefixed, lexicographically sortable)
- Tenant isolation: Scope required on every Store method — compile-time, not runtime
- Privacy: Self-hosted default. No telemetry, no external calls. Connector credentials encrypted with per-tenant keys (AES-256-GCM envelope encryption)