Introduction

Gnostikon is the canonical knowledge layer for teams who want their tools to remember — not just retrieve. Every gnosis is recorded with provenance, governed by an explicit ethos contract, and carries a banded confidence so downstream agents can act with the right amount of doubt.

This guide covers the conceptual model, the SDK quickstart, and the day-two operations you'll need once a workspace is in production.

What is Gnostikon?

Gnostikon turns scattered notes, transcripts, and decisions into gnoses — small, validated knowledge units that compose into a queryable canonical contract. The backend is an offline-friendly FastAPI service; the mobile client is offline-first by construction (WatermelonDB).

The design rests on three primitives:

• Gnosis — a validated knowledge unit with author, source, and confidence band.
• Ethos — a versioned, reviewable governance contract pinned to an agent or scope.
• Selection — a ranking that blends similarity, ethos compliance, recency, and conflict density.

Install the SDK

npm install @gnostikon/sdk

pip install gnostikon

Quickstart

Create a workspace, record your first gnosis, and retrieve it back with full provenance.

import { Gnostikon } from '@gnostikon/sdk';

const gn = new Gnostikon({ apiKey: process.env.GNOSTIKON_KEY });

const gnosis = await gn.gnoses.create({
  text: 'CPU spikes correlate with the nightly ETL job at 02:30 UTC.',
  source: { kind: 'incident', id: 'INC-2031' },
  confidence: 'high',
});

const matches = await gn.retrieve({
  query: 'why does CPU spike at night?',
  scope: 'platform-team',
});

note

confidence is a band, not a scalar. Acceptable values are low, medium, high. We dropped scalar scoring after a year of post-hoc analysis showed banded confidence drove conflict resolution up by 38%.

Architecture overview

The canonical layer is one logical service with two runtime profiles:

Surface	Runtime	Storage
Backend	FastAPI / Cloud Run	Postgres + pgvector
Client	Expo / React Native	WatermelonDB

Both speak the same /api/* contract. The mobile client is offline-first; it sync-merges to the backend whenever connectivity returns.

Offline & sync

The client never assumes online sync. Every mutation is queued locally, stamped with a vector clock, and replayed against the backend when the device reconnects. Conflicts resolve via the ethos contract — not by last-write-wins.

tip

Sync state is observable as a first-class field. Build UI that surfaces it rather than hiding it behind a spinner.

Governance & ethos

Ethos is a versioned YAML contract. Pinning ethos to an agent makes the agent's mandate explicit and reviewable; agents that operate outside their mandate fail closed, not open.

Next steps

• Read the API reference for the full contract.
• Browse Use Cases for patterns we've seen in production.
• Read the Blog for engineering posts and field reports.

Admonition demo

The six admonition types available in this site, used as authoring primitives in any docs or blog MDX.

note

A note carries supporting context that is not load-bearing for the surrounding paragraph.

tip

A tip is a small piece of operational advice that improves the reader's odds.

warning

A warning flags behavior that is supported but easy to misuse.

danger

A danger callout marks an irreversible operation or a security-relevant footgun.

Aletheia

An aletheia callout carries evidence — a citation, a measurement, or a reproducible observation that grounds a claim.

Ethos

An ethos callout names a governance constraint — a policy, an explicit value, or an operating principle that bounds the surrounding behavior.

Code blocks demo

A standalone fenced block, with the line-highlight syntax to confirm the upstream feature survives the swizzle:

client = Gnostikon(api_key="…")
result = client.search(q="why does CPU spike at night?")
print(result.first.text)

The same example expressed in three languages, grouped by groupId so a reader's tab choice persists across pages and browser tabs:

curl

curl -sS "https://api.gnostikon.ai/v1/search?q=why+does+CPU+spike+at+night"

Python

from gnostikon import Gnostikon

client = Gnostikon(api_key="…")
client.search(q="why does CPU spike at night?")

TypeScript

import { Gnostikon } from '@gnostikon/sdk';

const client = new Gnostikon({ apiKey: '…' });
await client.search({ q: 'why does CPU spike at night?' });