A post-symbolic multi-layer epistemic operating system for AI agents and autonomous systems. Deterministic, content-addressed, fail-closed by construction.

Two-layer architecture notice. This repository contains two layers of the same post-symbolic paradigm, pointed at two different streams — and, since the empirical validation gate passed (147/147 eval scenarios), connected:

Layer	Crates	Stream	Documentation
PSE cognition system	pse-*	world data (sensors, logs, markets, text) → epistemic memory	This file + docs/OVERVIEW.md
Kosmocrates production substrate	kosmo-*	software itself (workspaces, topology, intent) → structural memory + governed action	SUBSTRATE.md, docs/WISH_TO_SYSTEM.md

The dependency direction is strict: no kosmo-* crate imports pse-*. The single sanctioned crossing is kosmo-pse-bridge → adapters/pse-adapter-kosmo → the PSE engine, which alone decides crystallization. Certified structural crystals from the substrate are offered to the cognition system via the kosmo-promote CLI — fail-closed, evidence-bound, policy-gated. The substrate layer is tested independently (1162 tests, 0 failures; 147/147 eval scenarios as of 2026-06-10).

Kosmocrates turns stateless LLM and agent interactions into persistent, verifiable, topology-aware knowledge structures: content-addressed crystals, ledgered evidence, causal retrieval paths, QTIC conformance certificates, and self-maintaining epistemic health signals.

It is not another vector store, prompt wrapper, or RAG convenience layer. It is an execution substrate for deciding what may become memory, why it was allowed to persist, how it can be replayed, where it sits in a causal knowledge graph, and what must be repaired before the knowledge base can move toward closure.

For the full architecture, theory background, and feature reference, see docs/OVERVIEW.md.

• Persistent memory across sessions, runs, and model versions.
• Content-addressed evidence for everything processed and committed.
• Deterministic replay: byte-identical inputs produce byte-identical outputs.
• Fail-closed crystallization: unstable patterns emit no persistent memory.
• Topology-aware knowledge instead of flat chunks or unverified embeddings.
• Causal retrieval over ancestors, descendants, refinements, and related crystals.
• QTIC conformance certificates classifying committed knowledge from Q0 to Q5.
• Constitutional pre-commit checks for blocking, required, and advisory rules.
• Lifecycle management for stale, redundant, aging, and vital crystals.

# Prerequisites: Rust >= 1.82  →  https://rustup.rs
git clone https://github.com/LashSesh/kosmocrates
cd kosmocrates
bash install.sh          # installs kosmo-substrate + kosmo-server

# Analyse any Rust workspace
kosmo-substrate .

# Interactive terminal dashboard
cargo run -p kosmo-tui -- .

# Browser UI
kosmo-server --open      # opens http://localhost:7777

Or via Docker:

docker build -f docker/Dockerfile.kosmo -t kosmo-substrate .
docker run --rm -v $(pwd):/workspace kosmo-substrate /workspace
# Browser UI:
docker run --rm -p 7777:7777 --entrypoint kosmo-server kosmo-substrate --host 0.0.0.0

For the full getting-started guide — all four entry points, flag reference, crystal store persistence, and CI integration — see SUBSTRATE.md.

# 30-second engine smoke test
cargo run --release -p pse-demo

# Minimal end-to-end Rust example using the umbrella crate
cargo run --release -p pse --example quickstart

Or run the PSE server in a container:

docker compose up
# pse-server listens on http://localhost:8765 — try `curl localhost:8765/health`

For the full three-session LLM-memory walkthrough (Rust + Cerebras API), see DEMO.md.

All layers are fail-closed: SemanticCrystal records flow only through the PSE-Bridge. No subsystem constructs or commits crystals on its own.

Kosmocrates is pre-1.0. The core API is stable enough for serious integration work but may shift between minor releases — see RELEASING.md §1 for the versioning policy and ROADMAP.md for what is gated on the 1.0.0 cut.

• 695+ workspace tests, deterministic replay test included.
• CI: format / clippy / build × 3 OS / test / doc / supply-chain.
• Single-maintainer project — see GOVERNANCE.md for what that means for response times and merge cadence.

MIT. See LICENSE. Contributions are accepted under the same licence — see CONTRIBUTING.md.