Vaelii

A contextualized common-sense knowledge base: an in-memory or on-disk store of sentexes (sentence + context), indexed by a count-aware trie, with forward/backward inference and JTMS truth maintenance.

Requirements

• JDK 21+, Leiningen 2.10+ — no external services
• macOS and Linux; Windows is not supported (why)

Quick start

As a dependency — Leiningen [com.vaelii/vaelii "0.3.0"], or deps.edn com.vaelii/vaelii {:mvn/version "0.3.0"} — from Clojars. To work on it instead:

lein deps
lein test          # integration tests
lein repl          # loads namespace vaelii.core

Conventions: predicates are camelCase, individuals CapitalCamelCase, types snake_case (unary predicates, e.g. (dog Fido)), contexts end with Context.

(require '[vaelii.core :as v] '[vaelii.starter :as starter])

(def kb (v/open-kb {}))                            ; in-memory records + index
                                                   ; {:backend :disk :dir "/path"} to persist

;; a read sees what its context sees, up the genlContext cone — so say that the
;; world context reads the general one, or the rules below are invisible from it
(v/assert kb '(genlContext NaturalWorldContext UniverseContext) 'UniverseContext)

;; a type hierarchy + a typed individual; genl is transitive and cached
(v/assert kb '(genl dog animal) 'UniverseContext)
(v/assert kb '(genl animal thing) 'UniverseContext)
(v/assert kb '(dog Fido) 'NaturalWorldContext)
(v/isa?    kb 'Fido 'animal)                       ;=> true (via genl)

;; a rule is a sentex; forward chaining + truth maintenance
(v/assert-rule kb '[(parentOf ?x ?y) (parentOf ?y ?z)] '(grandparentOf ?x ?z) 'UniverseContext)
(v/assert kb '(parentOf Tom Bob) 'NaturalWorldContext)
(v/assert kb '(parentOf Bob Ann) 'NaturalWorldContext)
(v/sentexes-matching   kb '(grandparentOf Tom Ann) 'NaturalWorldContext)  ;=> derived, placed in NaturalWorldContext

(let [bob (:id (first (v/sentexes-matching kb '(parentOf Tom Bob) 'NaturalWorldContext)))]
  (v/retract! kb bob))                             ;=> tears down what it solely supported

;; or skip all of the above: the bundled starter ontology, on its own stores
(starter/load-into (v/open-kb {:record-space 2 :index-space 3}))

Web browser

lein run -m vaelii.web    # serves a starter-loaded KB on http://localhost:3000

Browse the upper ontology, any term (every sentex containing it), a sentex (its supporting justifications and dependents), or a justification (its arguments and conclusion) — all cross-linked.

Loading a bigger KB

The browser loads more than the starter: the core vocabulary alone, a generated corpus of a chosen shape, a vaelii export dump, an on-disk store, or a translated OpenCyc KB. Drop one under ~/.vaelii/kbs/ and it appears on the /kbs page with no restart, loading in the background and browsable before it finishes.

OpenCyc needs the reader plugin, which ships separately as vaelii-foreign. The whole route — from one dependency to a 1.2M-sentex KB, and the small vendored fixture to try it on first — is docs/kbs.md.

CLI & daemon

Drive a KB from the shell, or serve it over the network — both drive vaelii.core and add nothing to it. See docs/operations.md.

# command line (--dir persists via the disk backend, recovered on open)
lein cli assert '(dog Fido)' NaturalWorldContext --dir /var/lib/vaelii
lein cli match  '(dog ?x)'   NaturalWorldContext --dir /var/lib/vaelii   # => [(dog Fido)]
lein cli repl --starter                                                   # interactive

# headless daemon: one process owns one KB, serves it as EDN over HTTP
lein serve 4200 /var/lib/vaelii

;; a thin client (zero-dependency java.net.http), conn threaded explicitly
(require '[vaelii.client :as c])
(def conn (c/client "localhost" 4200))
(c/assert  conn '(dog Fido) 'NaturalWorldContext)
(c/query   conn '(dog ?x)   'NaturalWorldContext)

See docs/index.md for the architecture — the grouped map of every per-subsystem note, starting from docs/api.md and docs/glossary.md.

Contributing

CONTRIBUTING.md — the build, the conventions, and the contributor terms. Commits are signed off under the DCO, and a first pull request prompts for the CLA. Security reports go through .github/SECURITY.md rather than the issue tracker.

License

Server Side Public License, version 1 (LICENSE).

Copyright © 2026 Vaelii LLC and the Vaelii contributors.

The SSPL is source-available rather than OSI-approved. The project intends to move to an OSI-approved license; the contributor license agreement is what makes that possible without re-collecting permission from every contributor.

Cyc and Cycorp are registered trademarks of Cycorp, Inc. Vaelii is not affiliated with, endorsed by, or derived from Cycorp — it reads the published OpenCyc distribution through a separate plugin, and ships none of it.