Exocortex

A semantic knowledge management system built on RDF, SPARQL, and ontology-driven architecture. Runs as an Obsidian plugin, CLI tool, or TypeScript library.

---

What It Does

• Semantic knowledge graph — every piece of knowledge is an Asset with UUID, class, properties, and relationships stored as RDF triples
• SPARQL queries — ask complex questions across your entire knowledge base
• Modular ontologies — IMS (concepts, notes, people), EMS (tasks, projects, meetings), ZTLK (zettelkasten)
• Vault-driven architecture — commands, workflows, property schemas, and prototype chains defined as vault assets, not hardcoded
• Ontology plugins — extend the system with installable ontology packages (e.g. GTD + Jedi Techniques)
• Local-first — all data stays on your device, no cloud required

---

Quick Start

Option 1: Obsidian Plugin (via BRAT)

Best for: Visual knowledge management, daily planning, interactive exploration.

1. Install BRAT plugin from Obsidian Community Plugins
2. Open BRAT settings → Add Beta Plugin
3. Enter repository: kitelev/exocortex
4. Click Add Plugin and enable Exocortex in Community plugins

BRAT will automatically keep the plugin updated with new releases.

Option 2: CLI

Best for: Automation, AI agents, batch operations.

npm install -g @kitelev/exocortex-cli

# Query your knowledge graph
exocortex-cli sparql query "
PREFIX exo: <https://exocortex.my/ontology/exo#>
PREFIX ems: <https://exocortex.my/ontology/ems#>
SELECT ?task ?label WHERE {
  ?task exo:Instance_class ems:Task .
  ?task exo:Asset_label ?label
}" --vault ~/vault

# Complete a task
exocortex-cli command complete "tasks/my-task.md" --vault ~/vault

Option 3: Core Library

Best for: Building custom applications.

import { SparqlService, NodeFsAdapter } from "exocortex";

const sparql = new SparqlService(new NodeFsAdapter("/path/to/vault"));
const results = await sparql.query(`
  PREFIX exo: <https://exocortex.my/ontology/exo#>
  PREFIX ims: <https://exocortex.my/ontology/ims#>
  SELECT ?concept ?definition
  WHERE {
    ?concept exo:Instance_class ims:Concept .
    ?concept ims:Concept_definition ?definition .
  }
`);

---

Key Features

Asset — The Unit of Knowledge

Every piece of knowledge is a Markdown file with YAML frontmatter:

---
exo__Asset_uid: 965fd5c2-808e-4c7e-8242-e2e5d85bd996
exo__Instance_class: ims__Concept
exo__Asset_label: "Exocortex"
exo__Asset_relates:
  - "[[PKM]]"
  - "[[Semantic Web]]"
---
Knowledge content in Markdown...

Assets are connected through typed relationships. Individual assets are information; connected assets become knowledge.

SPARQL Queries

Ask complex questions about your knowledge:

# Find all tasks related to a specific concept
PREFIX exo: <https://exocortex.my/ontology/exo#>
PREFIX ems: <https://exocortex.my/ontology/ems#>
SELECT ?task ?label WHERE {
  ?task exo:Instance_class ems:Task .
  ?task exo:Asset_label ?label .
  ?task exo:Asset_relates ?concept .
  ?concept exo:Asset_label "Machine Learning" .
}

Effort Lifecycle

Complete workflow from idea to completion with automatic timestamp tracking:

Draft → Backlog → Analysis → ToDo → Doing → Done
                     ↓
                  Trashed

Workflow Customization

Define custom status lifecycles for your tasks and projects — all using regular vault assets:

exocortex-cli workflow list --vault ~/vault
exocortex-cli workflow validate <uid> --vault ~/vault

See Workflow Customization Guide for details.

Ontology-Driven Forms

Create assets with forms generated from your RDF ontology — fields appear based on rdfs:domain, types detected from rdfs:range.

Layout Code Blocks

Embed Layout definitions directly in your notes:

```exo-layout
[[emslayout__UpcomingTasksLayout]]
```

Features: wikilink syntax, loading state, error handling, auto-refresh, interactive sortable tables with inline editing.

Ontology Plugins

Install community ontology packages to extend your knowledge graph:

exocortex-cli assetspace add @kitelev/gtd-jedi@^0.1

---

Architecture

Monorepo with four packages sharing Clean Architecture core:

┌─────────────────────────────────────────────────────────────┐
│                      Exocortex System                        │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│   │   Obsidian   │  │     CLI      │  │  Core Library │      │
│   │   Plugin     │  │              │  │  (TypeScript) │      │
│   └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│          └─────────────────┼─────────────────┘               │
│                            │                                  │
│               ┌────────────▼────────────┐                     │
│               │     @exocortex/core     │                     │
│               │                         │                     │
│               │  • Domain models        │                     │
│               │  • SPARQL engine        │                     │
│               │  • Inference rules      │                     │
│               │  • Storage adapters     │                     │
│               └─────────────────────────┘                     │
│                                                               │
└─────────────────────────────────────────────────────────────┘

Packages

| Package | npm | Purpose | | ------------------------------ | ------------------------- | --------------------------------------------------------------------------- | | exocortex | Private | Core business logic, domain models, SPARQL engine, 35+ services | | @exocortex/obsidian-plugin | Private | Interactive UI: 24+ components, 6 renderers, 34+ commands, 11 modals | | @kitelev/exocortex-cli | @kitelev/exocortex-cli | CLI for automation, archive/unarchive, SPARQL queries, AI agent integration | | @exocortex/test-utils | Private | Shared test utilities, mock factories, flaky test reporter |

Technical Standards

• Clean Architecture — clear layer separation (presentation, application, domain, infrastructure)
• SOLID Principles — especially Single Responsibility
• Domain-Driven Design — knowledge domain as system center
• Semantic Web — RDF, SPARQL 1.2, OWL, RDF-Star
• Local-first — your data stays local, cloud is optional

SPARQL 1.2 Support

| Feature | Description | | ----------------------------- | ---------------------------------------------------- | | LATERAL Joins | Correlated subqueries for "top N per group" patterns | | PREFIX* | Auto-import prefixes from well-known vocabularies | | DESCRIBE Options | DEPTH and SYMMETRIC control for DESCRIBE queries | | Directional Language Tags | RTL/LTR text direction support (@ar--rtl) | | DateTime Arithmetic | Native date/time subtraction and duration operations | | NORMALIZE/FOLD | Unicode normalization and case folding |

See SPARQL 1.2 Features for complete documentation.

---

Documentation

Getting Started

• Installation Guide — Step-by-step setup

By Interface

Obsidian Plugin:

• Plugin Commands — All 34+ commands documented

CLI:

• CLI Command Reference — Complete syntax
• Scripting Patterns — Automation examples

Core Library:

• Core API Reference — TypeScript API
• Architecture Guide — Clean Architecture patterns

SPARQL & Semantic Queries

• SPARQL User Guide — Tutorial from basics to advanced
• Query Examples — 30+ ready-to-use patterns
• SPARQL 1.2 Features — LATERAL, PREFIX*, directionality, and more
• SPARQL 1.2 Migration — Upgrading from SPARQL 1.1
• ExoQL Specification — Full query language specification

---

Development

git clone https://github.com/kitelev/exocortex
cd exocortex
npm install
npm run build
npm run test:all

This project is developed primarily by AI agents (Claude Code, GitHub Copilot) following documented patterns. Human contributions welcome!

AI Development Resources

| Document | Purpose | | ---------------------------------------------------------------- | ------------------------------