# Telys

## Telys

- [Overview](https://docs.telys.ai/readme.md): The on-device, offline-first vector-memory engine — a thin Python SDK over a signed native runtime. Install, sign in, and build your first collection here.
- [What is Telys](https://docs.telys.ai/start-here/what-is-telys.md): How Telys gives apps and agents durable, private semantic memory on-device — a thin public SDK over a closed, signed native runtime, with nothing leaving the machine.
- [Install](https://docs.telys.ai/start-here/install.md): Install the Telys SDK with pipx or pip on Python 3.10+, then provision the signed native runtime for your platform with a single telys login.
- [Sign in](https://docs.telys.ai/start-here/sign-in.md): Run telys login to complete the device-code browser flow (or pass a token for CI), activate a license, and provision the signed runtime for your platform.
- [Verify install](https://docs.telys.ai/start-here/verify-install.md): Confirm a healthy Telys install offline — check the SDK version, runtime readiness, and the release-signature and license verification that gate every native call.
- [First collection](https://docs.telys.ai/quickstarts/quickstart-first-collection.md): Install Telys, sign in, then create a collection, add text, search it, and persist it to disk — end to end in a few minutes.
- [Semantic search](https://docs.telys.ai/quickstarts/quickstart-semantic-search.md): Build a small searchable text index with the on-device lexical embedder, run text queries, filter results with Eq, and read the scores.
- [Agent memory](https://docs.telys.ai/quickstarts/quickstart-agent-memory.md): Give an AI agent durable, on-device memory — partition per user and session with scope\_key, store conversation turns, and recall them on demand.
- [How it works](https://docs.telys.ai/understand-telys/how-telys-works.md): The architecture of Telys — a thin public Python SDK that orchestrates a signed, closed native runtime, entirely on your machine.
- [Collections](https://docs.telys.ai/understand-telys/collections.md): What a Telys collection is — a named, partitioned vector store bound to a single embedding space — and its create → use → save → reopen lifecycle.
- [Records & IDs](https://docs.telys.ai/understand-telys/records-ids-payloads.md): Anatomy of a Telys record — your external id, a vector, an optional metadata payload, and a partition key — plus add vs upsert vs update semantics.
- [Partitions & scopes](https://docs.telys.ai/understand-telys/partitions-scope-key.md): How Telys partitions a collection by a single key column, why partition\_by is never composite, and how scope\_key composes one string key from several parts.
- [Embeddings & spaces](https://docs.telys.ai/understand-telys/embeddings-and-spaces.md): How an embedder maps text to vectors in a space identified by EmbeddingProfile.space\_id(), and how a collection is bound to exactly one space.
- [Lexical vs dense](https://docs.telys.ai/understand-telys/lexical-vs-dense.md): When to use Telys's built-in on-device lexical embedders versus bring-your-own dense embeddings, and the privacy, latency, and recall tradeoffs of each.
- [Search internals](https://docs.telys.ai/understand-telys/search-internals-ivf.md): How Telys searches — exact brute force for small collections, an inverted-file (IVF) index for scale, and the target\_recall knob that trades recall for latency.
- [Metadata & filtering](https://docs.telys.ai/understand-telys/metadata-and-filtering.md): Attach metadata to records, declare filter\_columns, and narrow results with Eq — the single equality filter Telys supports across search and ids.
- [Versioning & compaction](https://docs.telys.ai/understand-telys/versioning-soft-delete-compaction.md): How Telys layers versioned updates and deletes over a sealed base image, why deletes are logical until you compact, and what save() commits.
- [Tuning & tradeoffs](https://docs.telys.ai/understand-telys/tuning-tradeoffs.md): The recall / latency / memory tradeoff behind Telys search, how exact-crossover and IVF knobs move it, and how a Tuner turns a workload into an applied TuningPlan.
- [Signed runtime & trust](https://docs.telys.ai/understand-telys/signed-runtime-trust.md): How Telys verifies a signed release manifest, hashes every runtime artifact, and checks an offline license before activating the native engine — fail-closed, native-only.
- [On-device & offline](https://docs.telys.ai/understand-telys/on-device-offline.md): Why every Telys collection, embedding, and search runs on your machine, the short list of things that ever use the network, and how it works fully offline after first login.
- [Local vs remote](https://docs.telys.ai/understand-telys/local-vs-remote.md): When to run Telys in-process versus behind a shared server — and how RemoteCollection differs as a strict subset of the local Collection API.
- [Create a collection](https://docs.telys.ai/working-with-data/create-a-collection.md): Create a Telys collection with a fixed dimension, a partition key, and an optional embedder, then commit it to disk with save().
- [Add & upsert](https://docs.telys.ai/working-with-data/add-and-upsert.md): Insert records into a Telys collection with add / add\_texts for new rows, or upsert / upsert\_texts to insert-or-replace, then persist with save().
- [Text vs vectors](https://docs.telys.ai/working-with-data/add-text-vs-vectors.md): Decide between the text ingest/search path (needs an embedder) and the raw-vector path (bring your own precomputed float32 vectors) in Telys.
- [Search by vector](https://docs.telys.ai/working-with-data/search-by-vector.md): Query a Telys collection with a precomputed query vector using search(), and read back ids, scores, optional metadata, and an explain trace.
- [Search by text](https://docs.telys.ai/working-with-data/search-by-text.md): Query a Telys collection with a plain string using search\_text(), which embeds your query with the collection's embedder and returns the nearest records.
- [Filter results](https://docs.telys.ai/working-with-data/filter-results.md): Constrain Telys searches and id listings to a partition or filter column using Eq or a single-key dict — the only filter Telys supports.
- [List & fetch by ID](https://docs.telys.ai/working-with-data/list-and-fetch-by-id.md): List the live external IDs in a Telys collection, count rows, test membership, and page through one partition with a scoped search.
- [Update records](https://docs.telys.ai/working-with-data/update-records.md): Replace the contents of existing records with update\_texts, and understand how it differs from add\_texts and upsert\_texts.
- [Delete & compact](https://docs.telys.ai/working-with-data/delete-and-compact.md): Remove records with delete, reclaim their space with compact, and commit the result to disk with save.
- [Save & snapshots](https://docs.telys.ai/working-with-data/snapshots-and-persistence.md): Persist a collection to disk with save, take a point-in-time copy with snapshot, and reopen it with open\_collection.
- [Export a compact artifact](https://docs.telys.ai/working-with-data/export-compact-artifact.md): Export a collection as an ultra-small read-only serve artifact (quantized slab + provenance) and open it on any device.
- [Build IVF index](https://docs.telys.ai/working-with-data/build-ivf-index.md): Switch a large collection from exact to approximate IVF search with build\_ivf, and confirm the change in the stats output.
- [Build a lexical index](https://docs.telys.ai/working-with-data/build-lexical-index.md): Add an on-device BM25 code index to a collection with lexical=True + build\_lexical, then query it with search\_text(mode="lexical") — keyword/code search, no model, scoped by partition.
- [Inspect stats](https://docs.telys.ai/working-with-data/inspect-stats.md): Read row counts, index state, and partitions from a collection's stats, alongside its name, key column, and external IDs.
- [Choosing an embedder](https://docs.telys.ai/embeddings/choosing-an-embedder.md): Compare the on-device lexical embedders against the bring-your-own dense path and pick the right vector space for your collection.
- [Bigram embedder](https://docs.telys.ai/embeddings/bigram.md): Reference for AlgentaBigramEmbedder — the compact on-device lexical bigram-hash embedder in telys.embedding.
- [Multigram embedder](https://docs.telys.ai/embeddings/multigram.md): Reference for AlgentaMultigramEmbedder — the richer on-device lexical embedder and the default used by the Telys MCP server.
- [Pooled embedder](https://docs.telys.ai/embeddings/pooled.md): Reference for AlgentaPooledEmbedder — a runtime-only embedder that resolves lazily from the closed native runtime and is absent in a runtime-free install.
- [Bring your own](https://docs.telys.ai/embeddings/callable-byo.md): Reference for CallableEmbedder — wrap any embedding function (OpenAI, BGE, a local model) into a Telys embedder with a matching EmbeddingProfile.
- [Embedding profiles](https://docs.telys.ai/embeddings/embedding-profile.md): Reference for EmbeddingProfile — the frozen record that names a vector space and, via space\_id(), gates which embedder can reopen or attach to a collection.
- [OpenAI recipe](https://docs.telys.ai/embeddings/recipe-openai.md): Integration recipe — wrap OpenAI text-embedding-3-small in a CallableEmbedder with a matching EmbeddingProfile, then create a collection, add text, and search.
- [BGE recipe](https://docs.telys.ai/embeddings/recipe-bge.md): Integration recipe — wrap a local BGE / sentence-transformers model in a CallableEmbedder for fully offline dense search, with no API keys and no network.
- [Dimensions & spaces](https://docs.telys.ai/embeddings/dimensions-and-space-id.md): How a collection's dimension and space\_id lock it to one embedder — why changing model or dimension needs a new collection, and how to migrate by re-embedding.
- [Why tune](https://docs.telys.ai/tuning/why-tune.md): Why and when to tune a Telys collection — trading recall, latency, and memory as it grows past a few tens of thousands of rows.
- [Tuner & plans](https://docs.telys.ai/tuning/tuner-and-plan.md): Reference for the Tuner base class, the bundled HeuristicTuner and AlgentaTuner, and every field and method of the TuningPlan dataclass.
- [Run a pass](https://docs.telys.ai/tuning/running-a-pass.md): Run col.tune() to produce a TuningPlan, and control whether the pass applies its result with the dry\_run flag.
- [Apply & save](https://docs.telys.ai/tuning/apply-and-save.md): Apply a TuningPlan with col.apply\_tuning() to configure recall, crossover, and IVF, then persist the result with col.save().
- [Interpret results](https://docs.telys.ai/tuning/interpreting-results.md): Read a TuningPlan's expected metrics and decision trace, then verify them against real searches with stats() and explain=True.
- [Overview](https://docs.telys.ai/cli/overview.md): The telys command tree — login, version, runtime, serve, mcp, and mem — with global behavior and links to every subcommand reference.
- [telys login](https://docs.telys.ai/cli/login.md): Reference for telys login — the device-code sign-in that caches your credentials and installs the signed runtime, with interactive and CI examples.
- [telys version](https://docs.telys.ai/cli/version.md): Reference for telys version — how it prints the installed SDK version and the on-disk format version, and how to read each part.
- [telys runtime](https://docs.telys.ai/cli/runtime.md): Reference for telys runtime — check status, install (offline or hosted), and verify the signed native runtime. telys runtime update is a stub.
- [telys serve](https://docs.telys.ai/cli/serve.md): Reference for telys serve — expose a collection path over a trusted Unix socket or an authenticated TCP endpoint for RemoteTelys clients.
- [telys mcp](https://docs.telys.ai/cli/mcp.md): Reference for telys mcp — run the stdio MCP server (with optional traffic auditing), or install, uninstall, and inspect its configuration in Claude, Cursor, Codex, Claude Desktop, and Qwen Code.
- [telys mem](https://docs.telys.ai/cli/mem.md): Reference for telys mem — an advanced, scriptable wrapper over a single local collection to create, add, search, list, and inspect it from the shell.
- [Environment & exit codes](https://docs.telys.ai/cli/environment-and-exit-codes.md): Reference for the environment variables the telys CLI honors and the exit codes every command returns — 0 ok, 1 not-ready, 2 usage or not-implemented.
- [Overview](https://docs.telys.ai/mcp/overview.md): Run Telys as a Model Context Protocol server so AI clients like Claude Desktop and Cursor can search and write on-device memory through 19 tools covering the full memory surface.
- [Install the server](https://docs.telys.ai/mcp/install-server.md): Wire the Telys MCP server into Claude Desktop, Cursor, Codex, Qwen Code, and other clients with one telys mcp install command, or configure it by hand.
- [Claude Desktop](https://docs.telys.ai/mcp/client-claude-desktop.md): Add the Telys MCP server to Claude Desktop on macOS or Windows so Claude gains an on-device memory it can search and add to.
- [Cursor & VS Code](https://docs.telys.ai/mcp/client-cursor-vscode.md): Add the Telys MCP server to Cursor or VS Code so the editor's AI agent can search and write on-device memory while you work.
- [Other clients](https://docs.telys.ai/mcp/client-other.md): Connect Codex or any MCP client to Telys with a generic stdio server config, and verify the server starts before wiring it into a client.
- [telys\_search](https://docs.telys.ai/mcp/tool-search.md): Reference for the telys\_search MCP tool — semantic and lexical search over a Telys memory collection, with an optional single-key equality filter.
- [telys\_add](https://docs.telys.ai/mcp/tool-add.md): Reference for the telys\_add MCP tool — add text documents to a Telys memory collection, auto-creating and saving it when the collection does not exist.
- [telys\_create\_collection](https://docs.telys.ai/mcp/tool-create-collection.md): Reference for the telys\_create\_collection MCP tool — create a named Telys memory collection, partitioned by scope, in the active memory store.
- [telys\_list\_collections](https://docs.telys.ai/mcp/tool-list-collections.md): Reference for the telys\_list\_collections MCP tool — list the saved Telys memory collections in the active memory store.
- [telys\_stats](https://docs.telys.ai/mcp/tool-stats.md): Reference for the telys\_stats MCP tool — report row counts and index state for a Telys memory collection in the active store.
- [Config & scoping](https://docs.telys.ai/mcp/configuration-and-scoping.md): Reference for the Telys MCP server — environment configuration, user vs project install scope, result wrapping, the error shape, and the exact tool set.
- [Overview](https://docs.telys.ai/self-hosting/overview.md): Run Telys as a local server so several processes or hosts share one memory store over a Unix socket or an access-token-protected TCP port.
- [Run a server](https://docs.telys.ai/self-hosting/running-a-server.md): Start a long-lived Telys server on a Unix socket or an access-token-protected TCP port, from the CLI or from Python, with durability and supervision options.
- [Connect remotely](https://docs.telys.ai/self-hosting/connecting-remote.md): Connect to a running Telys server with connect() / RemoteTelys, create and open collections remotely, and ingest and search over the length-prefixed socket protocol.
- [Auth & network](https://docs.telys.ai/self-hosting/auth-and-network.md): How a Telys server decides who may connect — trusted Unix sockets, token-gated TCP with constant-time comparison, the length-prefixed JSON wire protocol, and the offline license gate.
- [Deployment](https://docs.telys.ai/self-hosting/deployment.md): Run a Telys server durably in production — private networking, systemd or supervisor management, auto-restart, timed saves, and store backups on the self-host Team tier.
- [Agent long-term memory](https://docs.telys.ai/recipes/agent-long-term-memory.md): Give an AI agent durable, per-user memory with Telys — partition by user, write observations, and recall relevant history before every turn.
- [RAG over a codebase](https://docs.telys.ai/recipes/rag-over-a-codebase.md): Index a codebase into Telys — chunk files, add them with path and line metadata, retrieve with natural-language search, and hand the results to an LLM.
- [Chat memory](https://docs.telys.ai/recipes/chat-memory.md): Store chat turns in Telys, recall the most relevant history for the current message, and prune old turns with delete and compact to keep sessions bounded.
- [Batch ingestion](https://docs.telys.ai/recipes/batch-ingestion.md): Load large corpora into Telys efficiently — batch add\_texts, precompute vectors with add for BYO models, build the IVF index after load, and save once.
- [OpenAI & Anthropic](https://docs.telys.ai/recipes/with-openai-anthropic.md): Pair Telys retrieval with an OpenAI or Anthropic chat model — embed with CallableEmbedder or a local Algenta embedder, retrieve, and augment the prompt.
- [Framework bridge](https://docs.telys.ai/recipes/framework-bridge.md): Build your own thin adapter to use Telys as a retriever or vector store inside LangChain or LlamaIndex, using only the public SDK and CallableEmbedder.
- [Plans & licensing](https://docs.telys.ai/licensing/tiers-and-pricing.md): The four Telys tiers — developer, pro, team, and enterprise — what each unlocks, how to activate it, and where to see current prices and sign up.
- [Device-code sign-in](https://docs.telys.ai/licensing/device-code-sign-in.md): How telys login uses the RFC 8628 device-code flow to sign you in, register a device key, and fetch your offline license — with a headless path for CI.
- [Offline licenses](https://docs.telys.ai/licensing/offline-licenses.md): The Telys license is a signed, offline-verifiable JWT — this page explains its claims, how telys.verify and telys runtime verify check it locally, and why it works with no network.
- [Manage subscription](https://docs.telys.ai/licensing/managing-subscription.md): Upgrade, downgrade, cancel, and manage devices for your Telys plan in the accounts.thyn.ai portal, then refresh the license on your machine.
- [Seats & devices](https://docs.telys.ai/licensing/seats-and-devices.md): How Telys counts seats and devices — one device on the free plan, per-seat devices on pro and team, each with its own key and id — and how to sign in on a new machine.
- [Overview](https://docs.telys.ai/security/overview.md): Telys's security posture at a docs level — on-device and offline-first, three cryptographic trust anchors, a precise list of what leaves the machine, and the threat model.
- [Trust anchors](https://docs.telys.ai/security/trust-anchors.md): The three cryptographic checks Telys runs before activating the native runtime — a signed release manifest, per-artifact SHA-256 hashes, and a strict offline license.
- [What leaves the machine](https://docs.telys.ai/security/what-leaves-the-machine.md): A precise accounting of every byte Telys sends over the network — login, control plane, and runtime download — and confirmation that vectors, text, and queries never leave.
- [Verify the runtime](https://docs.telys.ai/security/runtime-signature-verification.md): Verify a Telys install offline — run telys runtime verify, then reproduce the release-manifest, artifact-hash, and license checks yourself with the telys.verify API.
- [Data residency](https://docs.telys.ai/security/data-residency-privacy.md): Where Telys keeps your data — on your own disk under $TELYS\_HOME, with no content telemetry — and why that makes it suitable for regulated and air-gapped deployments.
- [Environment variables](https://docs.telys.ai/operations/environment-variables.md): Reference for every Telys environment variable — defaults, effects, precedence, and which commands read them.
- [On-disk layout](https://docs.telys.ai/operations/on-disk-layout.md): Reference map of everything Telys stores under $TELYS\_HOME — credentials, the verified runtime, and per-collection files.
- [Supported platforms](https://docs.telys.ai/operations/supported-platforms.md): Reference for the platforms the Telys signed runtime supports, plus the reach of the pure-Python SDK.
- [Python support](https://docs.telys.ai/operations/python-version-support.md): Reference for the Python versions Telys supports (3.10+), why the pure-Python wheel runs on newer ones, and how to install.
- [Upgrade](https://docs.telys.ai/operations/upgrading.md): Upgrade the Telys SDK with pipx or pip, re-verify the signed runtime, and confirm the new version.
- [Uninstall](https://docs.telys.ai/operations/uninstalling.md): Remove the Telys package and, optionally, clear all on-disk state under ~/.telys.
- [Overview](https://docs.telys.ai/troubleshooting/overview.md): Start here when something breaks — a 60-second triage with telys runtime status, telys runtime verify, and telys version, then jump to the page for your problem.
- [Install & runtime](https://docs.telys.ai/troubleshooting/install-and-runtime.md): Fix RuntimeNotInstalled, a missing or undownloaded signed runtime, an unsupported platform, and native-kernel-not-found (TELYS\_KERNEL) errors.
- [License & login](https://docs.telys.ai/troubleshooting/license-and-login.md): Fix a failed telys login, an expired or invalid license, a wrong-plan account, and headless sign-in with --token in CI or over SSH.
- [Signature verification](https://docs.telys.ai/troubleshooting/signature-verification.md): Fix VerificationError — runtime manifest or artifact hash mismatches and license claim failures (iss / aud / exp / ver) — including trusted key overrides.
- [No results / recall](https://docs.telys.ai/troubleshooting/search-and-recall.md): Fix empty search results (unsaved data, wrong partition or where filter, no embedder) and poor recall (wrong embedder, missing IVF, or a low target\_recall).
- [Dimension mismatches](https://docs.telys.ai/troubleshooting/dimension-mismatches.md): Fix embedding dimension errors — dim vs profile.dimension at create, query length vs dim at search, and space\_id incompatibility after changing models.
- [MCP client](https://docs.telys.ai/troubleshooting/mcp-client.md): Fix an MCP client that won't connect to Telys — server not detected on PATH, env block not delivered, tools missing, or a stale virtualenv.
- [Platform-specific](https://docs.telys.ai/troubleshooting/platform-specific.md): Fix platform-specific issues — macOS Gatekeeper and PATH for GUI clients, experimental Linux arm64, Windows via WSL2, and unsupported Intel Mac.
- [SDK API index](https://docs.telys.ai/reference/sdk-api-index.md): Complete index of the public Telys API — the Telys facade, every Collection method with its signature, scope\_key, and the top-level exports.
- [TypeScript SDK](https://docs.telys.ai/reference/typescript-sdk.md): Reference for the TypeScript SDK (npm \`telys-ai\`) — the encapsulated in-process runtime, the Telys/Collection surface, Eq filters, persistence shared with Python, and the runtime ops.
- [Filters (Eq)](https://docs.telys.ai/reference/filters.md): Reference for Eq — the single equality filter Telys supports on search, search\_text, and ids, and how it maps to the single-key dict at the MCP boundary.
- [Embedders](https://docs.telys.ai/reference/embedders-api.md): Reference for telys.embedding — the EmbeddingProvider base class, EmbeddingProfile, CallableEmbedder, and the Algenta bigram/multigram/pooled embedders.
- [Tuner & plans](https://docs.telys.ai/reference/tuner-api.md): Reference for Tuner, TuningPlan, and the runtime-only HeuristicTuner — the objects that produce, describe, and apply a collection's index tuning.
- [Runtime](https://docs.telys.ai/reference/runtime-api.md): Reference for telys.runtime — load\_runtime, runtime\_available, the RuntimeHandle interface, FORMAT\_VERSION, RuntimeNotInstalled, and the TELYS\_RUNTIME switch.
- [Remote](https://docs.telys.ai/reference/remote-api.md): Reference for the remote surface — connect and RemoteTelys, the RemoteCollection subset, serve and TelysServer, address forms, and the wire protocol.
- [Exceptions & errors](https://docs.telys.ai/reference/exceptions-and-errors.md): Reference for the exceptions Telys raises across the SDK, server, and verify APIs, plus what each CLI exit code means.
- [Glossary](https://docs.telys.ai/reference/glossary.md): One-line definitions of the core Telys terms — collection, partition, scope\_key, embedder, space\_id, IVF, nprobe, target\_recall, runtime, kernel, license, and more.
- [Design principles](https://docs.telys.ai/resources/design-principles.md): The constraints that shape Telys — on-device first, private by default, signed and verifiable, a thin SDK over a closed runtime, deterministic lexical, one space per collection.
- [Changelog](https://docs.telys.ai/resources/changelog.md): Release history for the public Telys SDK — every shipped version, what changed, and the compatibility facts that go with it.
- [FAQ](https://docs.telys.ai/resources/faq.md): Short, direct answers to the questions people ask most about Telys — privacy, offline use, GPUs and model downloads, bring-your-own embeddings, Windows, and pricing.
- [Support](https://docs.telys.ai/resources/support.md): Where to get help with Telys — the contact form, the accounts portal, and this documentation site — plus what to include so we can help fast.
- [Links](https://docs.telys.ai/resources/resources.md): Every official Telys link in one place — the product site, pricing, the accounts portal, the PyPI package, and the MCP registry listing.