SCOPE

This file helps agents and humans quickly understand what this repository is about, when it is relevant, and when it is not.

One-liner

AI-first, headless knowledge engine that makes structured knowledge persistent, queryable, orchestratable, and operable across formats.

Core Idea

kontextual-engine is the system-layer successor to the platform portions of markitect-main. It should preserve the useful ideas around infospaces, knowledge artifacts, relationships, retrieval, workflow execution, and agent context, while avoiding the old repo's mixed ownership of markdown primitives, UI, provider integrations, and project/domain content.

The engine owns the runtime contract for persistent knowledge systems. Lower level syntax operations belong in markitect-tool; concrete domain workspaces belong in infospace-bench.

In Scope

Persistent storage and lifecycle management for knowledge artifacts.
Collections/domains, metadata, and relationships between artifacts.
Multi-format ingestion interfaces and normalized internal representations.
Query, retrieval, indexing, and composition APIs.
Workflow orchestration for transformation, generation, and analysis.
Agent-facing context continuity and operation surfaces.
Integration adapters for lower-layer tools such as markitect-tool.
Structured errors, deterministic behavior where applicable, and auditable state transitions.

Out of Scope

Low-level markdown parsing, schema primitives, document transforms, or CLI tooling that belongs in markitect-tool.
Visual UI applications, rendering plugins, or WYSIWYG editing.
Domain-specific infospace content or benchmark corpora that belong in infospace-bench.
Direct ownership of LLM provider adapters; use llm-connect or equivalent.
Finance, issue tracking, profile management, release tooling, and other legacy markitect-main utilities unrelated to the engine contract.
A CLI-first product posture; any CLI should remain an administrative or development convenience over service/programmatic APIs.

Relevant When

A project needs durable knowledge artifacts instead of one-off file parsing.
Agents need stable context and retrievable state across sessions.
Workflows must ingest, normalize, transform, compose, and query knowledge.
Multiple formats and external tooling need a common runtime layer.
A higher-level application needs a headless knowledge service.

Not Relevant When

The task is only markdown syntax manipulation or schema validation.
The primary need is an end-user visual application.
The work is domain-specific corpus curation without runtime needs.
Provider-specific LLM client behavior is the main concern.

Current State

Status: scoping / foundation.
Implementation: documentation and workplans only.
Stability: evolving.
Usage: successor planning for the in-scope system-layer parts of markitect-main.

How It Fits

Upstream dependencies: markitect-tool for syntax-layer primitives, llm-connect for provider-neutral LLM access, storage backends to be chosen.
Downstream consumers: infospace-bench, future knowledge services, agents, and automation systems.
Often used with: State Hub for planning/coordination, markitect ecosystem repos for adjacent responsibilities.

Terminology

Preferred terms: knowledge artifact, collection, relationship, ingestion, normalization, workflow, context, operation.
Also known as: Kontextual Engine, knowledge runtime, headless knowledge engine.
Potentially confusing terms: "infospace" is a conceptual collection pattern inherited from markitect-main, not necessarily a project directory or a UI-facing workspace.

markitect-main — legacy mixed platform; source for candidate behavior and tests, not the target architecture.
markitect-tool — syntax layer for markdown and structured document primitives.
infospace-bench — application/project layer for concrete knowledge spaces.
llm-connect — LLM provider abstraction that this repo may call but should not replace.
the-custodian/state-hub — coordination and repo/workplan index.

Getting Oriented

Start with: INTENT.md, wiki/ProductRequirementsDocument.md, wiki/FunctionalRequirementsSpecification.md.
Key files / directories: docs/, workplans/, SCOPE.md, CLAUDE.md.
Entry points: none yet; implementation starts from the workplans.

Provided Capabilities

type: service
title: Persistent knowledge runtime
description: Provides the planned system layer for storing, querying, transforming, and orchestrating structured knowledge artifacts across formats.
keywords: [knowledge, runtime, persistence, orchestration, retrieval]

type: automation
title: Agent-operable knowledge workflows
description: Provides planned APIs and workflow surfaces that let agents access context, trigger transformations, and operate over durable knowledge state.
keywords: [agent, workflow, context, automation, knowledge]

5.1 KiB Raw Blame History