Semiont

Semiont is an open-source semantic wiki where humans and AI agents collaboratively annotate, link, and extend a shared corpus of documents.

Install one of Apple Container, Docker, or Podman if you don't already have one.

Run the published frontend container image (substitute docker or podman for container as needed):

container run --publish 3000:3000 -it ghcr.io/the-ai-alliance/semiont-frontend:latest

Also available as a desktop app (macOS, Linux). See Frontend setup for details.

Point your web browser to the Semiont browser running at http://localhost:3000.

Clone a knowledge base and follow its README. Each KB repo contains configuration, container definitions, and startup scripts under .semiont/.

In the Semiont browser's Knowledge Bases panel, enter host localhost, port 4000, and the email and password you provided when starting the backend.

Every operation in the GUI is available programmatically. The same seven flows — yield, mark, match, bind, gather, browse, beckon — work identically whether driven by a human, a script, or an AI agent.

Semiont CLI — pipe the full annotation pipeline from the terminal:

semiont mark doc-123 --delegate --motivation linking --entity-type Person --entity-type Organization
semiont gather annotation doc-123 ann-456
semiont match doc-123 ann-456
semiont bind doc-123 ann-456 target-789

API Client — type-safe TypeScript SDK organized by the seven verbs:

const semiont = new SemiontApiClient({ baseUrl, eventBus, getToken });

await semiont.mark.assist(resourceId, 'linking', { entityTypes: ['Person'] });
const context = await firstValueFrom(semiont.gather.annotation(annId, resourceId));
const results = await firstValueFrom(semiont.match.search(resourceId, refId, context));
await semiont.bind.body(resourceId, annId, [{ op: 'add', item: { type: 'SpecificResource', source: targetId } }]);

Agent Skills — ready-made skill definitions that agentic coding assistants like Claude Code can use to drive the full pipeline without writing integration code.

See the Local Semiont Overview for alternative setup paths.

Built on the W3C Web Annotation standard, Semiont transforms unstructured content into interconnected semantic networks — all stored as portable, interoperable annotations. Self-hosted, so your data stays on your infrastructure. Inference runs on Anthropic (cloud) or Ollama (local) — mix providers per worker to balance cost, capability, and privacy.

Eliminate Cold Starts — Import a set of documents and the seven flows immediately begin producing value: AI agents detect entity mentions, propose annotations, and generate linked resources while humans review, correct, and extend the results. The knowledge graph grows as a byproduct of annotation — no upfront schema design, manual data entry, or batch ETL pipeline required.

Calibrate the Human–AI Mix — Because humans and AI agents share identical interfaces, organizations can dial the mix to fit their constraints. A domain with abundant expert availability and a high accuracy bar can run human-primary workflows with AI suggestions; a domain rich in GPU capacity but short on specialists can run agent-primary pipelines with human spot-checks. Supervision depth, automation ratio, and quality gates are deployment decisions — not architectural rewrites.

Peer Collaboration — Humans and AI agents are architectural equals. Every operation flows through the same API, event bus, and event-sourced storage regardless of who initiates it. Any workflow can be performed manually, automated by an agent, or done collaboratively.

Document-Grounded Knowledge — Knowledge is always anchored to source documents. Annotations point into specific passages; references link documents to each other. The knowledge graph is a projection of these grounded relationships, not a replacement for the original material.

Seven Collaborative Flows — humans and AI agents work as peers through seven composable workflows:

• Yield — Introduce new resources into the system — upload documents, load pages, or generate new content from annotated references
• Mark — Add structured metadata to resources — highlights, assessments, comments, tags, and entity references — manually or via AI-assisted detection
• Match — Search the knowledge base for candidate resources using multi-source retrieval and composite scoring — structural signals plus optional LLM re-ranking
• Bind — Resolve ambiguous references to specific resources, linking entity mentions to their correct targets in the knowledge base
• Gather — Assemble related context around a focal annotation for downstream generation or analysis
• Browse — Navigate through resources, panels, and views — structured paths for reviewing and examining content
• Beckon — Direct user focus to specific annotations or regions of interest through visual cues and coordination signals

• NPM Packages — See packages/README.md for available packages and documentation

⚠️ Early Development: Semiont is in active alpha development. The API is not yet stable and breaking changes are expected. See CONTRIBUTING.md for how to participate.

GitHub Codespaces (Recommended for quick setup):

See .devcontainer/README.md for setup details.

Local Development:

Semiont uses a CLI (semiont) to initialize projects, provision services, and manage environments. See LOCAL-DEVELOPMENT.md for installation, configuration, and running locally.

See CONTRIBUTING.md for how to participate, testing guide, and development standards.

semiont/
├── specs/                      # API specifications (spec-first architecture)
│   ├── src/                    # OpenAPI source files (tracked in git)
│   │   ├── openapi.json        # Root spec with $ref to all paths/schemas
│   │   ├── paths/              # Individual endpoint definitions
│   │   └── components/
│   │       └── schemas/        # Schema definitions
│   ├── openapi.json            # Generated bundle (gitignored, built by Redocly)
│   └── docs/                   # API and W3C annotation documentation
├── apps/                       # Application packages
│   ├── frontend/               # Vite + React frontend SPA
│   ├── backend/                # Hono backend API server
│   └── cli/                    # Semiont management CLI
├── packages/                   # Shared workspace packages (see packages/README.md)
│   ├── api-client/             # OpenAPI-generated TypeScript SDK
│   ├── core/                   # Core types and utilities
│   ├── event-sourcing/         # Event store and view storage
│   ├── content/                # Content-addressed storage
│   ├── graph/                  # Graph database abstraction
│   ├── ontology/               # Entity types and tag schemas
│   ├── inference/              # AI prompts, parsers, and text generation
│   ├── make-meaning/           # Context assembly, detection, reasoning
│   ├── jobs/                   # Job queue and worker infrastructure
│   ├── react-ui/               # React components and hooks
│   ├── mcp-server/             # Model Context Protocol server
│   └── test-utils/             # Testing utilities and mock factories
├── docs/                       # System documentation
└── scripts/                    # Build and utility scripts

See packages/README.md for detailed package documentation, architecture overview, and dependency graph.

Apache 2.0 - See LICENSE for details.