Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

On-disk layout

Reference map of everything Telys stores under $TELYS_HOME — credentials, the verified runtime, and per-collection files.

Telys persists everything under one root, $TELYS_HOME (default ~/.telys): cached credentials from telys login, the verified native runtime, and the default memory directory for the MCP server and telys mem. Collections you create in Python live wherever you point Telys(path), with the same directory structure everywhere.

These are plain files — inspect, back up, and delete them directly.

The $TELYS_HOME tree

~/.telys/                       # $TELYS_HOME — root of all state
├── token                       # cached control-plane token
├── api_key                     # cached Telys API key
├── device_key.pem              # Ed25519 device key (mode 0600)
├── device_id                   # this device's id (uuid4 hex)
├── login_license.jwt           # license issued by `telys login`
├── memory/                     # default MCP / `telys mem` engine dir
│   └── <collection>/           # one directory per saved collection
│       ├── collection.json     # manifest + commit point
│       ├── id_map.npy          # external-id ↔ internal-row map
│       └── <slab files>        # runtime vector slabs
└── runtime/
    └── macos-arm64/            # platform_tag(): <os>-<arch>
        ├── libty_runtime.dylib # closed engine runtime
        ├── libame_kernel.dylib # native embedding kernel
        ├── telys_manifest.json # signed manifest of this install
        ├── telys_manifest.sig  # RS256 signature over the manifest
        ├── license.jwt         # runtime license
        ├── installed.json      # install metadata / provenance
        └── pysite/             # prepended to sys.path on `import telys`

Root-level files

Written by telys login and the control-plane client:

File
Contents

token

Cached control-plane auth token.

api_key

Cached Telys API key.

device_key.pem

Ed25519 private key identifying this device (mode 0600).

device_id

The device id, a uuid4 in hex.

login_license.jwt

The license token returned by device-code sign-in.

The runtime directory

telys runtime install writes a verified install under runtime/<platform>/, where <platform> is platform_tag() — <os>-<arch>, for example macos-arm64 or linux-x86_64. The library extension follows the OS: .dylib (macOS), .so (Linux), .dll (Windows).

File
Role

libty_runtime.<ext>

The closed engine runtime loaded via ctypes.

libame_kernel.<ext>

Native kernel that backs the Algenta* embedders.

telys_manifest.json

Signed manifest listing artifacts and their SHA-256 hashes.

telys_manifest.sig

RS256 signature over the manifest, checked against the release key.

license.jwt

Runtime license verified offline at load time.

installed.json

Install metadata (version, provenance).

pysite/

Python site directory prepended to sys.path when a verified install is active.

On import telys, a present verified install has its pysite/ prepended to sys.path, making the runtime importable; without one, this is a silent no-op. telys runtime verify re-checks the manifest signature and every artifact hash.

Per-collection files

Each collection is a directory. Under the default MCP store it lives at memory/<name>/; the same shape appears under any path you pass to Telys(path).

File
Role

collection.json

The manifest and the commit point — written last on save().

id_map.npy

Sidecar mapping external ids to internal rows.

slab files

Runtime-managed vector slabs holding the actual vectors.

Collection.save() writes the id_map.npy sidecar first, then collection.json last. Because the manifest is the final write, a collection counts as saved only once it exists: a half-written save leaves no valid collection.json, and collections() lists only directories that contain one.

collection.json records name, dim, dtype, key_name, filter_columns, the id-map sidecar reference, telys_version, default_target_recall, the applied tuner, lexical, and the embedder profile. The profile lets open_collection() re-attach the right embedder from your provider registry by its space id.

create_collection() builds and caches a collection in memory but writes nothing to disk until save(). If a process exits first, the collection is gone. See Snapshots & persistence.

Platform tags and extensions

OS

platform_tag() arch

lib_ext

macOS (Apple Silicon)

macos-arm64

dylib

Linux x86-64

linux-x86_64

so

Linux ARM64

linux-arm64

so

Windows

(via WSL2)

dll

See also

Last updated

Was this helpful?