Start with the language and graph protocol your application already uses.
Create a session with a Passkey or EIP-4361 SIWE wallet. Kotobase then issues a short-lived Biscuit constrained to one tenant, graph, holder, expiry, and permission set.
The primary API credential is a short-lived Biscuit issued only after Passkey or SIWE authentication. Request it for the exact graph and permissions you need:
POST https://auth.kotobase.net/v1/biscuit/token
{"tenantId":"...","graph":"...","permissions":["data:write"]}
Use the complete authorization value returned by the endpoint:
Authorization: Biscuit <token>
CACAO and opaque Bearer credentials remain migration-only compatibility paths.
Pass the returned authorization value directly to the TypeScript, Python, or PHP SDK:
export KOTOBASE_TOKEN="Biscuit ..." && kotobase account-status
A rejected Biscuit is never retried as CACAO or Bearer.
Install the CLI in one command:
curl -fsSL https://kotobase.net/install.sh | sh
It needs babashka and writes only to your own ~/.local.
TypeScript, Python, and PHP clients share one transport and authentication contract.
Datomic Client API, SPARQL (including RDF4J HTTP path compatibility), Cypher, Gremlin, and GraphQL are tracked through explicit capability discovery and conformance tests.
Use the MCP endpoint at
https://kotobase.net/mcp
against the same tenant graph, or run
kotobase mcp
to emit the client configuration.
Import or bidirectionally sync an Obsidian vault while preserving Markdown, frontmatter, and [[wikilinks]].
Ayatori is the query-plane composition that turns provider discovery and immutable IPLD blocks into a persistent, queryable projection.
IPNI discovery → provider block fetch → CID verification → required Arrangement ranges → persistent cursor → Datalog
Discovery is only a provider hint. Ayatori does not treat it as proof of retrieval, CID validity, or query execution.
As of 30 August 2026, the shared kotobase.net production query request path is composed on ayatori.query, and the production component lock names ayatori.
That is a change of which repository serves production, not of what it computes: ayatori.query is an alias namespace over the same bridge. IPNI provider discovery and verified remote block reads are still not performed on the request path.
| Library | Responsibility | Direct relationship | Status |
|---|---|---|---|
| ayatori | Coordinates discovery, verified remote reads, persistent cursors, and query materialization. | Uses io-ipni-specs, io-ipld, arrangement, and kotobase. | On the production request path; its discovery and remote-read planes are not |
| io-ipni-specs | Parses IPNI advertisements and delegated-routing provider results. | Returns provider candidates; it does not fetch or verify blocks. | Ayatori dependency |
| io-ipld | Encodes and decodes IPLD links and verifies blocks against requested CIDs. | Used by Ayatori and the persistent index stack. | Production component dependency |
| arrangement | Persists four covering indexes as CID-addressed snapshots and exposes cursor reads. | Uses prolly-tree, datom-source, and datalog. | Production component dependency |
| prolly-tree | Stores ordered index nodes as content-addressed DAG-CBOR blocks. | Provides lookup, prefix scan, and range scan to arrangement. | Production component dependency |
| datom-source | Defines the storage-neutral pattern cursor contract used by query paths. | Separates query evaluation from a particular storage implementation. | Production component dependency |
| datalog | Evaluates Datalog over four covering indexes; it owns no storage or network I/O. | Consumes datom sources and indexes supplied by the caller. | Production component dependency |
| kotobase-query | Compatibility bridge from the flat Kotobase store to Datalog materialization. | Its two namespaces are carried by ayatori, so callers that still name them keep resolving. | Superseded; the same namespaces now ship from ayatori |
Status labels describe the shared production query components inspected on 30 August 2026. A source pin or passing benchmark does not by itself prove that a library serves production requests.