Telys — on-device memory

telys

Telys の パブリック SDK — オンデバイスに組み込まれたメモリと検索機能です。プロセス内で動作し、クエリ時にクラウドとの往復通信はありません。

このパッケージには、開発者向けの機能一式が含まれています。Telys／Collection ファサード、クエリ／フィルター型、EmbeddingProvider インターフェース、Tuner／TuningPlan インターフェース、完全な MCP サーバー（telys/mcp.py — 19 個のツール、プロトコル 2025-06-18、stdio）、ランタイムローダー、および telys CLI です。ツールが操作する数値カーネル（libame_kernel）は、telys login（無料のコミュニティライセンス）で取得する、別途配布される署名済みオンデバイスランタイムです。これは、ホスト型または署名済みバイナリのバックエンドを提供する MCP サーバーと同じ方式です。

インストール

CLI として（推奨 — 環境が分離され、PATH 上で使え、特定の Python に固定されません）：

pipx install telys

telys login          # sign in → free device license + signed runtime; fully offline thereafter

ライブラリとして（独自のプロジェクトで import telys する場合）：

python -m venv .venv && . .venv/bin/activate
pip install telys

pip install --user telys でも問題なく動作しますが、ユーザースクリプトのディレクトリが PATH に含まれていないという警告が pip から表示される場合があります（macOS の --user に関する仕様です）。pipx を使えばこの問題を完全に回避できます。ランタイムの対応プラットフォーム：macOS arm64、Linux x86_64/arm64（Windows では WSL2 上で実行してください）。

from telys import Telys
db = Telys("./memory")
col = db.create_collection("docs", dim=768, partition_by="tenant_id")   # dim is arbitrary — 384/768/1024/1536/3072…
col.add(vectors, ids=ids, metadata=metadata)          # bring your own vectors (embedding-agnostic, any dimension)
hits = col.search(qvec, where={"tenant_id": "acme"}, top_k=10, explain=True)

ランタイムは実行に必須ですが、エンベッダーは任意です。col.add(vectors, …) と col.add_texts(…) のどちらにもランタイムが必要ですが、エンベッダーが必要なのは *_texts のみです（telys.embedding.CallableEmbedder を使って独自のものを用意するか、オンデバイスの bigram エンベッダーを使用してください）。

ローカル開発では、CLI 経由ではなくパッケージとしてランタイムをインストールしてください：

pip install "telys[runtime]"   # or: pip install telys-runtime

MCP サーバー

telys mcp は、標準入出力を介して Telys を Model Context Protocol サーバーとして実行し、19 個のツールを公開します。メモリ機能一式（CRUD、フィルター付きクエリ、字句検索、コンパクション／IVF／チューニング、リポジトリの自動インデクサー）を、あらゆる MCP クライアント（Claude Desktop/Code、Cursor、Codex、Qwen Code など）から利用できます。すべてローカルでオフライン動作します。イントロスペクション（initialize／tools/list）に認証情報は不要です。メモリツールの実行には、1 回限りの無料の telys login（デバイス認証、無料のコミュニティプラン）が必要ですが、その後は完全にオフラインで動作し、クライアント設定に API キーは不要です。

pipx install telys
telys login            # free device license + signed on-device runtime
telys runtime verify   # confirm the runtime the tools drive is present
telys mcp              # serve JSON-RPC 2.0 (protocol 2025-06-18) on stdin/stdout

手動で起動することはほとんどありません。telys mcp install でサーバーエントリをクライアントに書き込むか、次のブロックをクライアントの MCP 設定に自分で追加してください。

{
  "mcpServers": {
    "telys": {
      "command": "telys",
      "args": ["mcp"]
    }
  }
}

レジストリ：公式 MCP レジストリの io.github.thyn-ai/telys。サーバーのソース：packages/telys-sdk/telys/mcp.py。 MCP ドキュメント：docs.telys.ai/mcp。

ツール	機能	必須引数
telys_search	メモリコレクションに対するセマンティック検索と字句検索	collection、query
telys_add	テキストドキュメントを追加します（存在しない場合はコレクションを自動作成）	collection、texts
telys_create_collection	コレクションを作成します（名前とパーティションキーを事前に確定）	name
telys_list_collections	アクティブなストアに保存されているコレクションを一覧表示します	—
telys_stats	1 つのコレクションの行数とインデックス状態	collection
telys_upsert	ID をキーに行を追加または置換します（冪等な書き込み）	collection、texts、ids
telys_update	既存の ID を再埋め込み／置換します（厳密：ID が必須）	collection、texts、ids
telys_delete	ID をキーに行をトゥームストーン化します	collection、ids
telys_ids	必要に応じて where で絞り込み、現在有効な外部 ID を一覧表示します	collection
telys_count	必要に応じて where で絞り込んだ現在有効な行数	collection
telys_get	ID による完全一致の行検索（リポジトリのソース範囲を再読み込み）	collection、ids
telys_search_lexical	デバイス上での BM25 キーワード検索	collection、query
telys_compact	トゥームストーンをフラッシュし、差分をベースレイアウトにマージします	collection
telys_build_ivf	パーティションごとの IVF インデックスを構築します（再現率の下限値に合わせて調整）	collection
telys_build_lexical	BM25 字句インデックスを学習します	collection
telys_tune	チューニングプランを生成し（任意で適用も）ます	collection
telys_index_repo	リポジトリを走査、分割、取り込みし、増分更新します	—
telys_repo_search	自動インデックス化されたリポジトリを検索します（最初に再インデックス化するため、常に最新です）	query
telys_workspace_info	設定済みのワークスペース、repo_id、ファイル数を報告します	—

各ツールには、詳しい説明（機能、使用するタイミング、デフォルト値付きのパラメーター、障害モード）と静的 MCP アノテーション（readOnlyHint／destructiveHint／idempotentHint／openWorldHint）が付属します。すべてのツールで openWorldHint: false となっており、サーバーはネットワーク呼び出しを行いません。ツールの一覧表示に認証情報もランタイムも不要です。initialize と tools/list は静的なツールレジストリから応答し、実際のツール呼び出し時にのみ、署名済みランタイムが遅延読み込みされます。

ドキュメント

完全なドキュメントは docs.telys.ai にあります。

• クイックスタート：最初のコレクション
• データの操作 — 追加、アップサート、検索、フィルター、スナップショット
• 埋め込み — 組み込みの語彙ベース方式と、CallableEmbedder による独自方式の利用
• CLI リファレンス · MCP 連携 · セルフホスティング
• SDK API インデックス

リンク

• ウェブサイト：telys.ai · 料金：telys.ai/pricing
• アカウントと請求：accounts.thyn.ai
• ドキュメント：docs.telys.ai · PyPI：pypi.org/project/telys