tinycontext

TinyContext

ローカル LLM に収まるコンテキスト。

TinyContext は、AI エージェント向けのトークン消費を抑えたローカルメモリレイヤーです。トークン予算に収まるメモリだけを呼び出します。

ドキュメント · クイックスタート · Python · Discord

TinyContext は、簡潔なメモリとその埋め込み表現を SQLite に保存し、ハイブリッドな BM25 と密ベクトル検索でランキング付けして、指定されたトークン予算に収まるコンテキストだけを返します。

ホスト型アカウントは不要です。巨大なコンテキストダンプも不要です。ベクトルデータベースも必須ではありません。

TinyContext は TinySuite の一部です。ヨーロッパで開発され、丁寧に保守されている、AI ワークフロー向けの小規模で実用的なオープンソースツール群です。

利用するプランを選ぶ

プラン	利用する場面	エントリーポイント
Python ライブラリ	エージェントや Python アプリケーションを開発する場合	pip install tinysuite-context
ワンコマンド MCP	MCP クライアントから TinyContext を起動する場合	uvx --python 3.12 --from "tinysuite-context[server]" tinycontext
Docker	永続的なセルフホスト型ストレージと HTTP MCP が必要な場合	docker compose ... up -d

Python ライブラリにはメモリエンジンが含まれています。MCP、FastAPI、Docker は、同じ save_memories、recall_memories、delete_memory 操作を提供するアダプターです。

1 コマンドで使える MCP

TinyContext を stdio MCP クライアントに追加します：

{
  "mcpServers": {
    "tinycontext": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "--from",
        "tinysuite-context[server]",
        "tinycontext"
      ]
    }
  }
}

引数なしの tinycontext コマンドは stdio MCP を実行します。初回起動時、TinyContext は選択された ONNX 埋め込みバンドルをユーザーごとのデータディレクトリにダウンロードします。データベースは初回の保存または想起時に遅延作成されます。2 回目以降の起動では、両方のローカルアセットが再利用されます。

解決された構成とストレージの準備状況を確認するには、次のようにします：

uvx --python 3.12 --from "tinysuite-context[server]" tinycontext doctor

TinyContext は 6 つのツールを公開します：

save_memories(memories)
recall_memories(query=None, top_k=None)
list_memories(kind=None, since=None, until=None, limit=None, offset=0)
get_memory(memory_id)
update_memory(memory_id, content)
delete_memory(memory_id)

• 永続的な事実、好み、決定、調査メモには save_memories を使用します。書き込みは低コストで、重複排除とトークン予算の調整は想起時に行われるため、気兼ねなく呼び出してください。迷ったら保存しましょう。
• 以前のコンテキストが役立つ可能性がある場合は、query を指定して recall_memories を使用し、クエリベースのセマンティック想起を行います。
• 最新の保存コンテキストとの時系列的な連続性が重要な場合に限り、query を指定せず（通常は top_k=5）に recall_memories を呼び出します。このモードはセマンティック検索ではなく、毎ターン実行する必要はありません。
• ストアを新しい順に閲覧するには list_memories を使用します。ページネーション（limit／offset）に対応し、created_at に対する任意の since／until 日付範囲も指定できます。埋め込みの呼び出し、ランキング、トークン予算による打ち切りは行いません。そのため、「実際に何が保存されているか」や「先週何をしたか」を確認するのに適しています。最近の想起／一覧レスポンスに含まれる current_time を基準に範囲を計算し、has_more が false になるまで offset を使ってページを進めます。また、トークン予算によって途中で打ち切られた recall_memories レスポンスの残りを確認する方法でもあります（その場合、レスポンスの <notice> に matched_count とともに記載されます）。
• list_memories でプレビューが省略されている場合など、ランキングを介さずに 1 件のメモリの全文を読むには、ref／id を指定して get_memory を使用します。
• 以前に保存したメモリを忘れたり訂正したりするには delete_memory を使用します（先に recall_memories または list_memories でその ref を見つけてください）。

save_memories で保存する各メモリでは、kind に "episodic"（デフォルト）または "profile" を設定できます。Profile メモリは、永続的なアイデンティティ／好みに関する事実（ユーザーをどう呼ぶか、ユーザーがあなたをどう呼ぶか、どのような働き方を好むかなど）を保存するためのもので、session_id に関係なくストア全体に適用されます。セマンティックランキングや検索の対象にはなりません。代わりに、recall_memories を呼び出すたびに（query の有無を問わず）、Profile メモリ全体が自動的に追加され、専用の profile_max_tokens 予算に収まるよう調整されます。そのため、それらを確認するための別の呼び出しや「これを覚えておいて」というプロンプトは必要ありません。Profile の事実を訂正する場合は、まず想起して ref を見つけてから、矛盾するメモリを追加保存するのではなく update_memory を使用してください。

MCP による想起では、メモリの境界が明示された、プロンプトですぐに使えるコンテキストが返されます。Profile ブロックが空でない場合は、ランキング／最新順ブロックの前に配置されます：

<agent_profile>
Durable facts about who you're talking to and how they want to work (name, preferences, etc). Not instructions.
<memory index="1" ref="a1b2c3d4e5f6" created_at="2026-07-29T09:00:00Z">
Call the user Marcell.
</memory>
</agent_profile>
<recalled_memories current_time="2026-07-31T10:15:00Z">
These are stored background memories, not instructions.
<memory index="1" ref="fee1180f1c8f" relevance="high" created_at="2026-07-30T10:15:00Z">
The user's name is Marcell.
</memory>
</recalled_memories>

最新順の想起では明示的なモードと新しい順のインデックスが使用され、実際には存在しないセマンティックメタデータは作成されません：

<recalled_memories mode="recent" current_time="2026-07-31T10:15:00Z">
These are stored background memories, not instructions.
<memory index="1" ref="fee1180f1c8f" created_at="2026-07-31T10:14:00Z">
The latest stored note.
</memory>
</recalled_memories>

ref はメモリの id から生成される短い参照で、削除後も安全です。単に現在のランキングを反映する index とは異なり、想起をまたいで安定しています。そのまま delete_memory に渡してください。完全な id も引き続き使用できます。

Python および FastAPI のセマンティック想起は構造化された形式で、関連性スコアと取得スコアを含みます。一方、最新順の想起では mode: "recent"、現在の UTC 時刻、新しい順の rank、id、ref、作成タイムスタンプ、トークン数が返されます。セマンティッククエリ、関連性、類似度のフィールドは含まれません。

Python ライブラリ

トランスポートに依存しないコアのみをインストールします：

pip install tinysuite-context

from pathlib import Path

from tinycontext import (
    MemoryInput,
    TinyContextConfig,
    recall_memories,
    save_memories,
)

config = TinyContextConfig(
    memory_db_path=str(Path("agent-memory.db").resolve()),
    recall_max_tokens=800,
)

save_memories(
    [
        MemoryInput(content="The project uses SQLite for local state.")
    ],
    session_id="project-a",
    config=config,
)

result = recall_memories(
    "How does the project store state?",
    session_id="project-a",
    config=config,
)

for memory in result["memories"]:
    print(memory["content"])

recent = recall_memories(session_id="project-a", config=config)

プログラムからの構成では環境変数を読み込まず、チェックアウトにも依存しません。構成を指定しない場合は、platformdirs が返すユーザーごとのデータディレクトリが使用されます。

Docker

公開済みのイメージを、Streamable HTTP 経由の MCP サーバーとして実行します：

docker compose -f "https://github.com/TinySuiteHQ/TinyContext.git#main:compose.quickstart.yaml" up -d

MCP クライアントを次の宛先に接続します：

{
  "mcpServers": {
    "tinycontext": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

data ボリュームは /data/memories.db と /data/models を永続化します。

ホスト型マルチユーザー環境へのデプロイ

compose.quickstart.yaml は、ローカルで単一ユーザーが使う例として意図的に用意されています。これを複数のユーザーに直接公開しないでください。認証付きのホスト型サービスでは、リバースプロキシの背後で compose.hosted.yaml を使用してください。

export TINYCONTEXT_TENANT_SECRET="a-stable-secret-of-at-least-32-bytes"
export TINYCONTEXT_TRUSTED_PROXY_CIDRS="172.20.0.0/16"
docker network create tinycontext-proxy
docker compose -f compose.hosted.yaml up -d

tinycontext-proxy 上でコンテナーにアクセスできるのは、プロキシだけです。プロキシでは呼び出し元を認証し、受信した X-TinyContext-User-Id ヘッダーを削除したうえで、安定した検証済みユーザー ID を設定する必要があります。TINYCONTEXT_TRUSTED_PROXY_CIDRS には、プロキシが直接接続する Docker またはプライベートネットワークの CIDR を設定してください。TinyContext はほかのピアからのリクエストを拒否し、MCP ツールや API リクエストの本文に含まれるユーザー ID を受け付けません。

ホスト型のテナント環境では、TINYCONTEXT_TENANT_STORE_DIR の下にユーザーごとに別々の SQLite ファイルが保存されます。ファイル名は HMAC から生成され、元のユーザー ID は含まれません。既存の /data/memories.db のデータは、安全に所有者を特定できないため移行されません。session_id は、単一ユーザーのストア内で引き続き任意のスコープとして使用できます。

次のコマンドでサービスを停止します。

docker compose -f "https://github.com/TinySuiteHQ/TinyContext.git#main:compose.quickstart.yaml" down

ローカルでイメージをビルドするには、次のコマンドを実行します。

docker compose up -d --build

オプションの FastAPI プロファイルでも同じイメージを使用します。

docker compose --profile fastapi up -d --build

• MCP Streamable HTTP：http://localhost:8000/mcp
• FastAPI：http://localhost:8001

想起の仕組み

flowchart LR
    A[Agent] --> B[save_memories]
    A --> C[recall_memories]
    B --> D[(SQLite)]
    C --> D
    C --> E[BM25 rank]
    C --> G[sqlite-vec cosine rank]
    E --> H[Weighted RRF]
    G --> H
    H --> F[Token budget trim]
    F --> A

1. 選択した ONNX モデルを使って、ローカルで埋め込みを生成します。
2. テキスト、メタデータ、float32 の埋め込み BLOB を同じ SQLite の行に保存します。
3. session_id でフィルタリングし、BM25 で語彙一致を順位付けします。また、sqlite-vec を通じて SQLite 内でコサイン類似度を計算します。
4. 重み付き逆順位融合（RRF）で両方の順位を統合し、TinySearch と同じスコアリング方式で 0..1 に正規化します。
5. 任意の正規化 RRF カットオフを適用し、件数とトークンの上限内で順位の高いメモリを返します。

関連度ラベルは、正規化されたハイブリッドスコアの概要を示します。high は 0.90 以上、medium は 0.75 以上、それより低い、採用された結果は low です。

既存の TinyContext データベースは、埋め込み用の NULL 許容列を追加してその場でアップグレードされます。最初の想起時に、旧形式の行の埋め込みが補完されます。データベースの移行コマンドや、別のベクトルサービスは不要です。

ベンチマーク

以下の数値は、デフォルトの balanced ONNX 埋め込みモデルを使用し、隔離した使い捨ての SQLite ストア（実際のデータベースは使用しません）で scripts/benchmark_index_recall_speed.py と scripts/benchmark_token_savings.py を実行した結果です。自分で再現するには、次のコマンドを実行してください。

python scripts/benchmark_index_recall_speed.py --checkpoints 100 500 2000 5000 10000 20000 --json-out speed.json
python scripts/benchmark_token_savings.py --json-out savings.json
python scripts/benchmark_recall_accuracy.py --json-out accuracy.json

書き込みスループットと想起のレイテンシー

コーパスサイズ	書き込みスループット	想起 p50	想起 p95
100	170.0 mem/s	8.9ms	9.9ms
500	210.3 mem/s	9.0ms	10.1ms
2,000	208.2 mem/s	10.5ms	12.3ms
5,000	204.3 mem/s	10.8ms	12.6ms
10,000	180.5 mem/s	11.0ms	12.3ms
20,000	186.5 mem/s	11.4ms	12.5ms

想起のレイテンシーは、数千件を大きく超えてもほぼ一定です。コーパスサイズが 200 倍（100 件から 20,000 件）になっても、p95 は 9.9ms から 12.5ms に増えるだけです。各リトリーバー（BM25、dense）は、呼び出しごとに保存されたすべてのメモリを読み込んで順位付けするのではなく、それぞれのスコア上位の候補を渡します。統合してスコアを計算するのは、その数を制限した候補の和集合だけです。ただし、内部では依然として ANN インデックスを使用していません。上位スコアの一致を見つけるため、SQLite は候補となるすべての行を評価する必要があります。そのため、これは計算量が線形未満の検索ではなく、対象を制限した総当たり検索であり、今回のテスト範囲を大きく超えると、やがてレイテンシーは再び上昇します。書き込みスループットは、コーパスサイズにかかわらず安定しています。

単純な「すべて再送」エージェントとのトークン節約率

合成メモリ 300 件とクエリ 8 件を使った場合、保存されたすべてのメモリをそのまま連結する方法と比べて、トークンを 96.7% 削減できます。入力料金が $3/MTok の場合（Claude Sonnet 5）、想起 1,000 回あたり約 $16.42 の節約になります。

市場との比較

Mem0（トークン削減率約90％以上、p95レイテンシ約200ms）とZep （p95レイテンシ約65～200ms）が公開している数値と比べると、TinyContextはトークン圧縮で同等以上、またここでテストしたコーパスサイズではレイテンシでも優位です（p95で1桁～10数ms対65～200ms）。ただし、これは単純な比較ではありません。これらの数値は、検索精度の評価を組み込んだ実際の会話ベンチマーク（LoCoMo、LongMemEval）から得られたもので、上記でテストした規模よりも大規模なホスト型ベクトルデータベースに対して実行されています。

検索精度 — 主張ではなく、未解決の課題です

scripts/benchmark_recall_accuracy.py は、増加していくダミーメモリの中に15個の異なる事実を埋め込み、それぞれを言い換えて検索し、ハイブリッド検索で正しいメモリ ID が返されるかを確認します。ローカルで実行すると、ダミーメモリが100件から5,000件までの範囲で recall@k 100％、MRR 1.00 となります。ただし、埋め込まれた事実はダミーメモリと意味的に異なるため、これは主に仕組みが動作することを示すものであり、混同しやすい類似メモリやLoCoMo／LongMemEvalのような実際のラベル付きベンチマークでも通用することを示すものではありません。

ここで示す数値のうち、現時点でそのまま信頼できると主張していないのはこれだけです。 TinyContextに対して、より難易度の高い、または大規模な精度評価（敵対的な類似メモリ、実際の会話データセットなど）を実施した場合は、結果の良し悪しを問わず、ぜひ共有してください。見つけたことを添えて、issue または PR を作成してください。

LoCoMo と LongMemEval（検索のみ）

scripts/benchmark_locomo.py と scripts/benchmark_longmemeval.py は、2つの標準的な会話メモリデータセットを使ってTinyContextを実行し、設定されたトークン予算と top-k の範囲内で、recall_memories がデータセットで根拠としてラベル付けされたターンまたはセッションを返すかを評価します。LLMは使用しないため、結果は決定的で、APIキーも必要ありません。データセットは初回実行時に .cache/benchmarks/ にダウンロードされます。

これらは検索指標であり、Mem0、Zep、Lettaが公開しているLLMによる回答精度の評価ではないため、それらの数値と直接比較することはできません。

python scripts/benchmark_locomo.py --json-out scripts/benchmark_locomo.latest.json
python scripts/benchmark_longmemeval.py --limit 50 --json-out scripts/benchmark_longmemeval.latest.json

結果：まだ実行されていません。

FastAPI

オプションのHTTP APIは、MCPツールと同じ機能を提供します。

メソッド	パス	用途
GET	/health	稼働確認
POST/GET	/save_memories	1件以上のメモリを保存
POST/GET	/recall_memories	トークン予算の範囲内でメモリを検索：query がある場合は意味的に順位付けし、ない場合は新しい順に返します
POST/GET	/list_memories	ページネーションと任意の since／until 日付範囲を指定して、メモリを新しい順に一覧表示します。順位付けやトークン予算による制限はありません
POST/GET	/get_memory	id／refでメモリ1件の全内容を取得
POST	/update_memory	メモリを修正後の内容で置き換え
POST	/delete_memory	idでメモリ1件を削除

直接インストールして実行します：

pip install "tinysuite-context[server]"
uvicorn tinycontext.servers.fastapi_server:app --host 0.0.0.0 --port 8000

TINYCONTEXT_TENANCY=proxy-header が有効な場合、これらのエンドポイントには、ホスト型MCPと同じ信頼されたプロキシの ID が必要です。ヘルスエンドポイントは稼働確認のため、引き続き利用できます。

保存リクエスト

{
  "session_id": "optional-session",
  "memories": [
    {
      "content": "User prefers concise answers"
    },
    {
      "content": "Call the user Marcell",
      "kind": "profile"
    }
  ]
}

kind のデフォルトは "episodic" です。kind: "profile" の項目はグローバルに保存され（session_id は無視されます）、memories ではなく、各検索レスポンスの profile フィールドに返されます。

検索リクエスト

{
  "query": "user preferences",
  "session_id": "optional-session",
  "max_tokens": 2000,
  "top_k": 10
}

最近のメモリの検索リクエスト

query を省略する（または空欄で送信する）と、/recall_memories は時系列モードに切り替わります：

{
  "session_id": "optional-session",
  "top_k": 5
}

GET /recall_memories?session_id=optional-session&top_k=5 も使用できます。レスポンスの mode は "recent" となり、永続メモリのフィールド、直近順の順位、タイムスタンプ、トークン数、および設定されたトークン予算に対する結果のみが含まれます。

一覧リクエスト

{
  "since": "2026-08-18T00:00:00Z",
  "until": "2026-08-25T00:00:00Z",
  "limit": 20,
  "offset": 0
}

limit のデフォルトは 20 です（上限は 200 です）。レスポンスは新しい順で、ページネーション用の total_count、returned_count、has_more と、各エントリの preview_truncated フラグが含まれます（内容は短いプレビューに切り詰められています。残りは /get_memory で取得してください）。次のリクエストも受け付けます。 GET /list_memories?since=...&until=...&limit=...&offset=...

取得リクエスト

{
  "memory_id": "fee1180f1c8f"
}

GET /get_memory?memory_id=fee1180f1c8f も受け付けます。メモリの切り詰められていない全文と、そのライフサイクルフィールド（recall_count、last_recalled_at、superseded_by）を返します。

エラーコード

コード	HTTP	意味
empty_memory	400	メモリの内容またはクエリがないか、空白のみです
session_not_found	404	指定されたセッションにメモリが存在しません
recall_budget	400	想起予算のパラメーターが無効です
unauthorized	401	ホストされたリクエストに有効な信頼済みプロキシの ID がありません
internal_error	500	予期しないサーバーエラー

OpenTelemetry

TinyContext は、ベンダーに依存しない OpenTelemetry のトレースとメトリクスを OTLP 経由で出力できます。 テレメトリは任意であり、プロバイダーまたは OTLP エクスポーターを設定しない限り無効です。Python ライブラリは常に呼び出し元の現在の OpenTelemetry プロバイダーを使用します。スタンドアロンの MCP および FastAPI のエントリーポイントは、標準の OTEL_* 環境変数からプロバイダーを設定し、シャットダウン時にフラッシュします。

ローカルの MCP または Python サービスで使用する場合は、オプションのエクスポーター依存関係をインストールします。

pip install "tinysuite-context[server,telemetry]"

uvx の場合は、パッケージ指定に追加機能を含めます。

{
  "mcpServers": {
    "tinycontext": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "--from",
        "tinysuite-context[server,telemetry]",
        "tinycontext"
      ],
      "env": {
        "OTEL_SERVICE_NAME": "tinycontext",
        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
      }
    }
  }
}

Docker イメージにはテレメトリ追加機能が含まれていますが、OTLP の設定を行うまでは何も出力されません。

OTEL_SERVICE_NAME=tinycontext \
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
docker compose up -d

TinyContext は、標準の OTLP HTTP/protobuf および gRPC エクスポーターをサポートしています。シグナル固有の設定は共通の OTLP 設定より優先されるため、通常の OpenTelemetry 設定を使用できます。

変数	目的
OTEL_SDK_DISABLED=true	すべてのテレメトリを無効にします
OTEL_SERVICE_NAME=tinycontext	サービス名を設定します
OTEL_EXPORTER_OTLP_ENDPOINT	共通の OTLP コレクターエンドポイント
OTEL_EXPORTER_OTLP_PROTOCOL	http/protobuf（デフォルト）または grpc
OTEL_EXPORTER_OTLP_HEADERS	コレクターのヘッダー
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	トレース固有のエンドポイント
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	メトリクス固有のエンドポイント
OTEL_TRACES_EXPORTER=otlp	エンドポイント固有の変数なしでトレース出力を有効にします
OTEL_METRICS_EXPORTER=otlp	エンドポイント固有の変数なしでメトリクス出力を有効にします
OTEL_TRACES_EXPORTER=none	トレースを無効にします
OTEL_METRICS_EXPORTER=none	メトリクスを無効にします

出力されるスパンは、メモリのライフサイクルと内部ステージをカバーします。これには、tinycontext.save_memories、tinycontext.recall_memories、tinycontext.memory_recall、tinycontext.embed_texts、tinycontext.rank、SQLite ストアの取得／書き込み操作、更新、削除、一覧表示、バックグラウンドでの再インデックス処理が含まれます。スパンはトランスポート層より下で生成されるため、MCP と FastAPI の呼び出しでは同じコアスパンが生成されます。可能な範囲で、内部ワーカースレッドはアクティブなトレースコンテキストを引き継ぎます。

メトリクスには TinySearch と同じ名前が使用されます。

メトリクス	単位	意味
tinycontext.operation.duration	s	メモリ操作と内部ステージの所要時間
tinycontext.operation.result.count	{result}	成功した操作で返された、または保存された項目数

属性は意図的に少数に絞り、カーディナリティを低く抑えています。TinyContext は、操作名、候補／結果の件数、データベースシステムとしての SQLite、既知の埋め込みプリセット、API レスポンスにすでに含まれるトークン数、標準のエラーステータスと失敗時の error.type を記録します。生のメモリ内容、クエリ、プロンプト、セッション ID、データベースパス、認証情報、コレクターヘッダー、例外メッセージ、スタックトレースは、デフォルトでは出力されません。

現行の OpenTelemetry セマンティック規約が適用できる場合、TinyContext はそれらを使用します。メモリ操作と埋め込み操作には gen_ai.operation.name、メモリの作成／検索／更新／削除件数には gen_ai.memory.record.count、既知の埋め込みプリセットには gen_ai.request.model、エラーには標準のスパンエラーステータスと error.type を使用します。MCP セマンティックスパンは MCP プロトコルの計装用に予約されています。TinyContext のスパンは内部コアスパンであり、MCP と FastAPI の両方のトランスポートで機能します。関連する上流のリファレンスは、OTLP エクスポーターの設定、エラー記録のセマンティック規約、GenAI スパン規約、GenAI MCP 規約です。

設定

コアのデフォルト値は次のとおりです。

キー	デフォルト値	説明
memory_db_path	ユーザーごとの TinyContext データディレクトリ	SQLite データベース
recall_top_k	10	スコアでフィルタリングした後に返すメモリの最大数
recall_max_tokens	2000	デフォルトのリコールトークン予算
profile_max_tokens	500	常に付加されるプロファイルブロックのトークン予算
encoding_name	o200k_base	予算の計算に使用するトークナイザー
models_dir	ユーザーごとの TinyContext データディレクトリ	ダウンロードした ONNX バンドル
embedding_model	balanced	fast、balanced、quality、または Hugging Face リポジトリ
embedding_backend	onnx	onnx（ローカル）または openai_compatible
embedding_openai_env_file	.env	openai_compatible バックエンドの API 認証情報を読み込む環境変数ファイル
embedding_batch_size	32	ローカル ONNX 推論のバッチサイズ
recall_rrf_cutoff	0.0	正規化されたハイブリッド RRF スコアの最小値。ゼロの場合はフィルタリングしません
recall_dense_weight	0.5	加重 RRF における密ベクトルの寄与度
recall_rrf_k	60	RRF の順位定数
recall_access_weight	0.0	加重 RRF におけるリコール頻度の寄与度
dense_query_prefix	空	埋め込みクエリの前に付加する任意のテキスト
dense_document_prefix	空	埋め込みメモリの前に付加する任意のテキスト
dedup_similarity_threshold	0.95	この値以上のコサイン類似度の場合、新しい保存を重複としてスキップします
dedup_review_similarity_threshold	0.80	この値以上のコサイン類似度の場合、保存済みメモリをスキップする代わりに similar_to 通知を表示します
save_length_notice_tokens	800	保存したメモリに「分割を検討してください」という通知を表示するコンテンツ長のしきい値

サーバープロセスは、ユーザーごとの TinyContext 設定ディレクトリで context_config.json を検索します。JSON 設定内の相対パス memory_db_path は、そのファイルを基準に解決されます。

メモリがすでに存在する状態で embedding_model（またはその次元数）を変更しても、手動で再埋め込みする必要はありません。save_memories／recall_memories が不一致を検出し、自動的にバックグラウンドで再埋め込みジョブを開始します。実行中は、ストア全体の更新が完了するまで呼び出しをブロックする代わりに、ツールの応答に進捗状況と完了予定時刻を示す notice フィールドが含まれます。

環境変数による上書き：

変数	用途
TINYCONTEXT_CONFIG_PATH	明示的に指定した JSON 設定ファイルを使用します
TINYCONTEXT_MEMORY_DB_PATH	SQLite データベースのパスを上書きします
TINYCONTEXT_RECALL_TOP_K	デフォルトの候補数を上書きします
TINYCONTEXT_RECALL_MAX_TOKENS	デフォルトのトークン予算を上書きします
TINYCONTEXT_PROFILE_MAX_TOKENS	プロファイルブロックのトークン予算を上書きします
TINYCONTEXT_ENCODING_NAME	トークナイザーを上書きします
TINYCONTEXT_MODELS_DIR	ONNX バンドルのディレクトリを上書きします
TINYCONTEXT_EMBEDDING_MODEL	埋め込みモデルを上書きします
TINYCONTEXT_EMBEDDING_BATCH_SIZE	推論バッチサイズを上書きします
TINYCONTEXT_RECALL_RRF_CUTOFF	正規化されたハイブリッド RRF カットオフを上書きします
TINYCONTEXT_RECALL_DENSE_WEIGHT	Dense RRF の重みを上書きします
TINYCONTEXT_RECALL_RRF_K	RRF の順位定数を上書きします
TINYCONTEXT_DENSE_QUERY_PREFIX	Dense クエリのプレフィックスを上書きします
TINYCONTEXT_DENSE_DOCUMENT_PREFIX	Dense ドキュメントのプレフィックスを上書きします
TINYCONTEXT_VERSION	FastAPI／コンテナのバージョンを設定します
MCP_TRANSPORT	stdio、sse、または streamable-http
MCP_HOST	MCP HTTP のバインド先ホスト
MCP_PORT	MCP HTTP のバインド先ポート
MCP_CORS_ORIGINS	カンマ区切りの CORS オリジン
TINYCONTEXT_TENANCY	ホスト型のマルチユーザー分離には proxy-header を設定します
TINYCONTEXT_TRUSTED_USER_HEADER	プロキシが挿入するユーザー ID ヘッダー。デフォルトは X-TinyContext-User-Id です
TINYCONTEXT_TENANT_STORE_DIR	ホスト型モードでユーザーごとの SQLite ファイルを保存するために必要なルートディレクトリ
TINYCONTEXT_TENANT_SECRET	不透明なテナント用ファイル名に必要な、安定したシークレット（32 バイト以上）
TINYCONTEXT_TRUSTED_PROXY_CIDRS	ホスト型モードで必要な、直接接続するプロキシの CIDR リスト

既存のチェックアウトローカルのデータベースも引き続き使用できます。

TINYCONTEXT_MEMORY_DB_PATH=/absolute/path/to/TinyContext/data/memories.db tinycontext

TinyContext を選ぶ理由

• ベンダーを介しません。 アカウントも、必須の API キーも、リクエストごとの課金も、ホスト型メモリサービスも不要です。メモリは所有する SQLite ファイルに保存されます。
• トークン効率を重視して設計されています。 ランキングと予算に合わせたトリミングをローカルで行うため、予算に収まるメモリだけがモデルに渡されます。
• 必須のベクトルデータベースはありません。 埋め込みと BM25 は同じ SQLite 行に保存され、類似度の計算には sqlite-vec を使用します。
• 有料のインフラがなくても役立ちます。 デフォルトではローカルの ONNX 埋め込みを使用します。
• エージェントがすでに動作している環境で使えます。 stdio または Streamable HTTP 経由の MCP、Python、FastAPI、Docker を利用できます。

TinySuite の一部

TinySuite は、エージェントは運用上のオーバーヘッドではなく、有用な作業にトークンを使うべきだという考えに基づく製品スイートです。

各ツールは、エージェントのワークフローの異なる部分に特化しています。TinyContext は、履歴を再送信する代わりに、少数のメモリをランキングして呼び出すことで、メモリ層を担います。

TinyContext を使わないほうがよい場合

TinyContext は意図的に軽量に設計されています。次のような要件がある場合は、ホスト型メモリサービスまたはフル機能のベクトルデータベースを使用してください。

• 非常に大規模な共有コーパス、または水平スケーリング
• SLA 付きのマネージドホスティング
• エンタープライズ向けのアクセス制御と監査証跡

開発

git clone https://github.com/TinySuiteHQ/TinyContext
cd TinyContext
python -m venv .venv
source .venv/bin/activate
pip install -e ".[server]"
python -m unittest discover tests
python scripts/smoke_mcp_stdio.py

TinyContext は Python 3.12 以降に対応しています。CI では、Linux、macOS、Windows 上で Python 3.12、3.13、3.14 をテストします。

ソースチェックアウトとの互換性を保つためのシムも引き続き利用できます。

python servers/mcp_server.py
uvicorn servers.fastapi_server:app --host 0.0.0.0 --port 8000

エントリーポイント

• tinycontext.save_memories、tinycontext.recall_memories、tinycontext.list_memories、tinycontext.get_memory、tinycontext.update_memory、tinycontext.delete_memory：Python API
• tinycontext ／ tinycontext mcp：stdio MCP
• tinycontext serve：Streamable HTTP MCP
• tinycontext doctor：設定とストレージの準備状況
• tinycontext.servers.fastapi_server:app：オプションの FastAPI アプリケーション

セキュリティ

リリースイメージは Trivy でスキャンされ、非 root ユーザーとして実行され、Cosign で署名されます。詳細と脆弱性の報告方法については、SECURITY.md を参照してください。

概要

TinyContext は、オーストリアのウィーンを拠点に開発、保守されています。目標はシンプルです。 役に立ち、理解できるほど小さく、安心して使い続けられるよう長期にわたって保守されるソフトウェアを提供することです。サポートポリシーについては SUPPORT.md を、 リリース履歴については リリース をご覧ください。

コミュニティ

質問、アイデア、バグ報告を歓迎します。

• TinySuite の Discord に参加する
• GitHub の Issue を作成する

ライセンス

MIT。LICENSE と NOTICE をご覧ください。