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:
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).
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).
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.
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
Environment variables —
TELYS_HOMEandTELYS_MEMORY_PATH.Supported platforms — which
platform_tag()targets ship a runtime.Verify the runtime signature — checking the manifest and hashes.
Uninstall Telys — removing this tree cleanly.
Last updated
Was this helpful?