Semiont

Semiont is an open, source-grounded semantic knowledge platform for building and maintaining trusted AI knowledge bases and context layers. It gives humans and AI agents a shared workspace and architecture to annotate, connect, enrich, and govern domain knowledge for accurate applications, agents, and workflows.

Quick Start

0. Prerequisites

You'll need a container runtime — Apple Container, Docker, or Podman, auto-detected.

1. Install

The semiont launcher is a single static binary — no npm, no Node.js:

brew install the-ai-alliance/semiont/semiont

Homebrew serves macOS and Linux. On Windows, the GitHub Release carries a zip holding semiont.exe — see Semiont on Windows.

2. Configure Settings

Name your vault. By default the secrets the launcher generates for a knowledge base are plain files, which are not secure and are for development only. To keep every new knowledge base's in 1Password, set that before creating one:

semiont settings secret-store --default op://YourVaultName

Then register your Anthropic key once, as a pointer into that vault — only the pointer is stored, read fresh on every start and passed to the containers, written nowhere:

semiont settings secret set ANTHROPIC_API_KEY op://YourVaultName/Anthropic/credential

A local model needs no secret: Ollama runs a small one on your own machine, selected in the next step, and no content leaves your machine.

semiont settings lists every setting the launcher keeps, with its value and where it came from.

3. Create a knowledge base

semiont init creates a KB in place, synthesizing a config it validates before writing:

mkdir my-kb && cd my-kb
semiont init --yes --domain example.com:my-kb --inference anthropic

Change --domain — it is the KB's permanent identity, stamped into the committed event log, and has no default. Use --inference ollama instead if you chose the local model above.

Every step below runs from inside the knowledge base — not from this repo.

4. Start it

One command starts the whole stack and ensures the Semiont browser is running at http://localhost:3000:

semiont start

semiont status reports each service's state and health, semiont logs follows it, semiont stop tears it down, and semiont start --help lists the options.

5. Create a user

A fresh stack has no users. The account is created at the knowledge base's identity provider, which is what Semiont trusts to authenticate people:

semiont useradd --email admin@example.com   # prompts for the password

6. Sign in

Open http://localhost:3000. The Semiont browser's Knowledge Bases panel discovers launcher-managed stacks automatically — pick yours and sign in with the email and password you just created. Sign-in happens at the identity provider, not at Semiont, so you'll be handed to its page and back, and it asks for your name on first use.

Sign the launcher in as well — it holds a session of its own, which the next step needs:

semiont login          # approve in a browser; only tokens come back

No password reaches the launcher, and the session renews itself; semiont logout ends it. It is the CLI's own session — an SDK app signs in separately.

For local-network access notes, supply-chain verification, and the native desktop app alternative, see docs/browser/.

7. Ingest content

Pull down a well-known paper and upload it with the session from step 6. The storage URI is repo-relative, so the file has to land under the KB root first:

mkdir -p papers
curl -L -o papers/attention-is-all-you-need.pdf https://arxiv.org/pdf/1706.03762
semiont yield --upload papers/attention-is-all-you-need.pdf

8. Annotate

Open the document you just ingested and start marking it up — highlight a passage, tag an entity, link a claim to the source that supports it. You are not doing it alone: AI agents reach the same document over the same bus, proposing references and entity types for you to accept, refine, or throw out. Every annotation records who made it, human or agent, and the two are the same kind of participant here.

The CLI asks for the same work. This has the stack detect references to concepts, given the resource id that step 7 printed:

semiont mark --delegate <resourceId> --motivation linking --entity-type Concept

Automate

Everything the Semiont browser does travels over one event bus, spoken as eight verbs: browse, bind, yield, mark, frame, gather, match, beckon. You have been speaking them already — semiont yield was one. The launcher speaks all eight (semiont browse --help, and so on), and so does your code.

The Semiont SDK is how your code speaks the same bus — a type-safe client whose namespaces are those eight verbs. It comes in TypeScript (@semiont/sdk) and Rust (semiont), full peers held to the same conformance suite. Your app never calls the gateway's HTTP API directly; the SDK is the boundary.

TypeScript:

npm install @semiont/sdk

Rust:

cargo add semiont
cargo add semiont-http-transport --features sign-in    # the transport over a gateway

Built on the SDK: @semiont/react-ui embeds the resource viewer and annotation UI in your own app, and Agent Skills are ready-made definitions for agentic coding assistants. The contract both SDKs speak is specified independently of either in docs/protocol/.

Demo and Community KBs

Rather than starting empty, clone a knowledge base that already carries content. semiont-gutenberg-kb holds public-domain literature from Project Gutenberg:

git clone https://github.com/The-AI-Alliance/semiont-gutenberg-kb.git
cd semiont-gutenberg-kb

It arrives with its identity and configs already set, so skip step 3. A plain semiont start runs its local Ollama config; semiont start --config anthropic runs on the key from step 2 instead. It ships with content, so step 7 is optional.

The full catalog — seven demo KBs across different domains, plus community knowledge bases and the empty template — is in docs/KNOWLEDGE-BASES.md.

Contributing

⚠️ Alpha. API and package surface are not yet stable; breaking changes between 0.x releases are expected.

New here? The SDK's INTRODUCTION is the orientation chapter — read it first, then the Developer Guide to build, with Usage open as the reference.

• Development docs — codebase layout, build status badges, Codespaces shortcut, where to read next.
• System architecture — actor model, knowledge system, container topology, package architecture.
• Browser development — running the Browser from source against a stack.
• CONTRIBUTING.md — branch/PR workflow, commit conventions, platform-contribution playbook.

📜 License

Apache 2.0 - See LICENSE for details.