What is Open Context?

Open Context (OCTX) is an open context standard built on Google Open Knowledge Format (OKF). It packages readable Markdown, stable identities, versions, integrity information, and optional chunks, events, entities, relations, and vectors into a portable .octx Package.

Open Context is compatible with the Chunk-Event-Entity hypergraph data structure used by SAG, but neither the specification nor the reference tools depend on SAG, zleap-sag, a particular database, or a vector backend.

Reading Order

1. OCTX v0.1 Specification (spec-v0.1.md): the container, manifest, knowledge documents, identities, digests, versions, and extension rules.
2. What Is SAG? (sag.md): the SAG application, retrieval architecture, zleap-sag, and their relationship to OCTX.
3. SAG-Structured v0.1 Capability (sag-structured-v0.1.md): complete chunks, events, entities, relations, and optional vectors.
4. Tooling Overview (tooling-lifecycle.md): tool layers and core objects such as Asset, Release, Package, and Installation.
5. Build and Integration: creating-octx.md, opening-validating-octx.md, importing-octx.md, and exporting-octx.md cover creation, validation, import, and export respectively.
6. Python API (api/overview.md): separate documentation for creation, reading, validation, safe extraction, and the CLI.
7. Machine-Readable Schemas (schemas/README.md): JSON Schema Draft 2020-12 and the boundary of semantic validation.
8. Domain Glossary (GLOSSARY.md): shared terminology for OCTX, SAG, and zleap-sag.

Python Quick Start

Python 3.11 or later is required:

python -m pip install octx

Create a Package from a Markdown directory, then open and validate it:

from octx import create_octx, open_octx, validate_octx

result = create_octx(
    "./.octx-workspace",
    source="./knowledge",
    name="Product Guide",
    output="./product-guide.octx",
)

with open_octx(result.output) as package:
    for document in package.iter_documents():
        print(document.path, document.metadata["title"])

report = validate_octx(result.output)
assert report.valid

source is never modified. Reusing the same workspace preserves stable Asset, Document, and Release identities. Reading vectors requires octx[vectors]. See api/overview.md for the complete interface.

An unpacked external Package can be repacked losslessly if it has not been modified. After modifying or enriching it, use create_octx(..., derive=True) to create a new Asset with asset.derived_from, rather than impersonating a later version from the original publisher.

CLI Quick Start

octx create ./.octx-workspace --from ./knowledge --name "Product Guide" -o ./product-guide.octx
octx inspect ./product-guide.octx
octx validate ./product-guide.octx
octx unpack ./product-guide.octx ./product-guide-expanded

inspect reads only a summary and does not replace full validation. validate exits with 0 for a valid Package and 1 for an invalid Package; every command supports --json.

Website and Documentation

The official website is opencontext.wiki. Its standalone source is in site/. It publishes the complete specification, Python API, schemas, and glossary from this directory without depending on the SAG application codebase.

v0.1 Highlights

• Published files use the .octx extension and ZIP / ZIP64 as the outer container.
• Every Package contains at least one OKF Concept Markdown document.
• OCTX knowledge/ is an OKF v0.1-compliant knowledge layer. A complete OCTX Package additionally requires a manifest, asset identity, Release, digests, and optional derived data. A regular OKF Bundle is not an OCTX Package.
• An OCTX Package may contain only Markdown; chunks, events, entities, and vectors do not have to be generated in advance.
• sag-structured/0.1 is one explicit Capability that includes chunks, events, entities, and relations as a whole. It cannot be inferred automatically from the presence of files.
• An .octx file is an immutable complete snapshot, not a database backup, incremental package, or synchronization protocol.
• OCTX does not define a search API, retrieval algorithm, Agent protocol, or vector database.

Reference Implementation Boundary

The standalone octx package provides:

• create_octx()
• open_octx()
• validate_octx()
• unpack_octx()
• octx create / inspect / validate / unpack

zleap-sag depends on and re-exports these entry points, and adds:

• import_octx()
• export_octx()

Other knowledge systems can use octx directly and implement their own adapter layer.