Korely Memory

Korely Memory

AI エージェントのための、今も真実であることを把握するメモリーです。

Korely は、エージェントが学んだことを有効期間付きの型付き事実として保存します。何かが変わると、古い事実は上書きされず、新しい事実に置き換えられます。エージェントは現在の真実を読み取り、過去の任意の日付に何が真実だったかを尋ねることもできます。

import time
from korely_memory import Korely

korely = Korely()  # reads KORELY_API_KEY from the environment

korely.add("Maria is on the Pro plan, billed yearly.", user_id="maria")
korely.add("Maria downgraded to Free.", user_id="maria")

time.sleep(10)  # facts are extracted server-side; see "Writes settle asynchronously"

ctx = korely.get_context(query="what plan is Maria on?", user_id="maria")
print(ctx.context)
# ## Known facts
# - Maria downgraded_to Free (since 2026-09-08)
# - Maria billing_frequency yearly (since 2026-09-08)
#
# Pro is gone from the current facts. It was superseded, not deleted.

正確な述語は抽出器が選ぶため、ここでの downgraded_to は、実行時には subscribes_to や plan になることがあります。保証されるのは動作です。古い値は 現在の集合から外れ、invalid_at を持つ状態で引き続き取得できます。

何も削除されていません。Pro の事実は invalid_at と、置き換えた事実へのポインターを保持したまま残っています。

korely.get_facts(user_id="maria", include_invalidated=True)
# Maria downgraded_to Free    valid_from=... invalid_at=None
# Maria plan Pro              valid_from=... invalid_at=2026-09-08T08:31:09Z

実際の日付をさかのぼる

イベントが過去に起きた場合は timestamp を渡すと、事実はその値を valid_from として引き継ぎます。すると as_of は取り込み順ではなく、 世界の時間軸に基づいて回答します。

korely.add("Franco signed up on the Pro plan.", user_id="franco", timestamp="2026-01-15")
korely.add("Franco downgraded to Free.",        user_id="franco", timestamp="2026-06-20")

korely.get_facts(user_id="franco", as_of="2026-03-01")   # subscribes_to -> Pro plan
korely.get_facts(user_id="franco", as_of="2026-08-01")   # subscribes_to -> Free
korely.get_facts(user_id="franco")                       # subscribes_to -> Free

timestamp がない場合、事実は書き込んだ瞬間から真実となるため、それより前の日付を指定した as_of は何も返しません。これは正しい動作ですが、履歴をインポートする場合には通常、望ましくありません。

as_of は、ストアが今日把握している情報に基づいて、その日に何が真実だったかを回答します。 known_as_of（Korely Agent 0.1.26）は別の問い、つまりストアがその日に何を知っていたかに回答します。変更が遅れて伝えられた場合、両者の回答は異なります。エージェントが、顧客が 9 月 1 日に引っ越したことを 10 月 5 日に知ったとします。

korely.get_facts(user_id="maria", as_of="2026-09-20")        # lives_in -> Turin
korely.get_facts(user_id="maria", known_as_of="2026-09-20")  # lives_in -> Milan

9 月 20 日には引っ越しはすでに起きていましたが、ストアはまだそれを知りませんでした。 known_as_of は get_facts、get_profile、get_context で利用できます。get_context は、その時点でストアが組み立てられた場合と同じようにブロックを再構築します。つまり、エージェントが判断を下した時点で知り得たことを返します。各事実には、ストアがその事実の終了を知った時点を示す closed_known_at が含まれます。

書き込みは非同期で処理されます

add() はメモリーが保存されるとすぐに戻り、その後、サーバー側で抽出が実行されます。つまり、次のようになります。

呼び出し	利用可能になるタイミング
生のメモリーに対する search()	すぐ
型付き事実を取得する get_facts() と get_context()	数秒後

上記の time.sleep(10) は、スニペットを貼り付けて実行できるようにするためだけのものです。本番環境では必要ありません。エージェントはあるターンの最後に書き込み、次のターンの最初に読み取ります。その頃には事実が利用可能になっています。

正確なタイミングを知る必要がある場合は、推測せずに確認してください。すべてのメモリーには processing、ready、error のいずれかの status があり、events() は処理中の内容を報告します。

page = korely.events()
page.processing  # 0
page.events[0]   # MemoryEvent(memory_id='mem_...', status='ready', ...)

processing == 0 は、プロジェクトの書き込みがいくつあっても（user_id を渡した場合はそのスコープ内で）、抽出中のものがないことを意味します。そのため、スクリプトはすべての ID を確認せず、この 1 つの数値を待つことができます。batch() でインポートした後は、まず batch_status() が完了するのを待ってください。ジョブがまだ保存していないメモリーはカウントされません。

通知方法はポーリングのみです。抽出の完了時にウェブフックは発火しません。ウェブフックイベントは memory.created、fact.invalidated、quota.warning です。

インストール

pip install korely-memory      # Python, plus the `korely` CLI
npm install korely-memory      # Node / TypeScript

どちらのクライアントにも実行時依存関係はありません。

LangGraph では、オプションの pip install 'korely-memory[langgraph]' により、ストア、メモリーツール、コンテキストヘルパーが追加されます。詳細は python/README.md を参照してください。

キーを取得する

ホビーティアは無料で、登録フォームも必要ありません。

curl -X POST https://api.korely.ai/v1/agents/init \
  -H 'Content-Type: application/json' \
  -d '{"agent_caller": "your-name-here"}'

レスポンスには kor_live_ キーが含まれています。これを KORELY_API_KEY として設定すると、SDK、CLI、REST API のすべてで認証に使用されます。コードからは、Korely.init_agent()（Python）と Korely.initAgent()（JS）が同じ呼び出しを行います。

このキーに紐づくアカウントにはログイン機能がありません。キーそのものがアカウントです。アカウントを削除する唯一の方法でもあるため、大切に保管してください（korely delete-account --yes、または SDK の delete_account(confirm=True)）。

または、CLI に任せることもできます。korely init はキーを ~/.korely/config.json に保存します。また、KORELY_API_KEY が設定されていない場合、SDK はそこからキーを読み取ります。そのため、使い始めるには次の操作だけで十分です。

pip install korely-memory
korely init --agent --agent-caller your-name
python -c "from korely_memory import Korely; print(Korely().get_context(query='hi').tokens)"

TypeScript

import { Korely } from "korely-memory";

const korely = new Korely();

await korely.add("Maria downgraded to Free.", { user_id: "maria" });
const ctx = await korely.getContext({ query: "what plan is Maria on?", user_id: "maria" });

Vercel AI SDK では、korely-memory/ai-sdk の withKorelyMemory(model, { userId }) を使うと、1 行であらゆるモデルにこのメモリを追加できます。js/README.md をご覧ください。

CLI

korely add "Maria downgraded to Free." --user-id maria
korely context "what plan is Maria on?" --user-id maria
korely facts --as-of 2026-03-01 --user-id maria
korely audit --user-id maria --all --json > maria.json   # everything that touched Maria

すべてのコマンドは python/README.md に記載されています。

Korely の機能

• 型付きファクト。 サブジェクト、述語、オブジェクトをサーバー側で抽出します。ユーザー側でプロンプトエンジニアリングを行う必要はありません。
• 二時点有効性。 すべてのファクトに valid_from と invalid_at が含まれるため、ストアは「いつ真だったか」と「いつ記録されたか」を区別します。
• 矛盾の解決。 新しいファクトが古いファクトと矛盾する場合、古いファクトに取って代わり、どのファクトを置き換えたかを記録します。何も黙って削除されることはありません。
• 過去時点のクエリ。 as_of は過去の任意の日付に何が真だったかを返し、known_as_of はその日にストアが何を把握していたかを返します。
• エンティティグラフ。 エンティティと関係性は自動的に抽出され、無料プランを含むすべてのプランで利用できます。
• セマンティック検索。 メモリとファクトは意味（ベクトル類似度）に基づいてランク付けされ、ファクトはメモリで確認された時期の新しさによってもランク付けされます。
• プロンプトにすぐ使えるコンテキスト。 get_context() はトークン数とともに、システムプロンプトにそのまま貼り付けられるブロックを返します。
• EU ホスト。 ヘルシンキで稼働します。エンドユーザーは、エージェントが自分について記憶している内容を確認、修正、消去できます。

非同期処理

本番環境のエージェントは、一度に 1 回だけ呼び出すわけではありません。AsyncKorely は Korely のすべてのメソッドに対応しているため、これまでに学んだことをそのまま活用できます。

import asyncio
from korely_memory import AsyncKorely

async def main():
    korely = AsyncKorely()
    contexts = await asyncio.gather(
        korely.get_context(query="what plan?", user_id="a"),
        korely.get_context(query="what plan?", user_id="b"),
        korely.get_context(query="what plan?", user_id="c"),
    )

asyncio.run(main())

ライブ API への 6 回の呼び出しは、逐次実行で 5.6 秒、並行実行で 1.7 秒 です。

このパッケージを ランタイム依存関係ゼロ に保つ価値は、効率をわずかに高めることよりも大きいため、呼び出しは非同期 HTTP ライブラリではなくスレッドプールで実行されます。イベントループがブロックされることはなく、リクエストは実際に並行して処理されます。

使用例

examples/audit_trail.py は、このストアが解決するために存在する問いに答えます。エージェントが回答した日に、何を把握していたのか？

サポートエージェントが 3 月に顧客へ優先サポートを案内します。6 月に顧客はより安価なプランに変更します。9 月、顧客がボットの言葉を引用して苦情を申し立てます。ボットの回答は間違いだったのでしょうか、それとも当時は正しかったのでしょうか？

  What the store believed in March, when the agent answered:
      customer-4821 · subscribes_to · Business plan
      Business plan · includes · priority support

  What is true today:
      customer-4821 · subscribes_to · Standard plan
      customer-4821 · lacks · priority support

3 月の時点でも、今日でも正しいことを、どちらも証明できます。約 20 秒で実行できます。

pip install korely-memory
korely init --agent --agent-caller audit-example
python examples/audit_trail.py

消去も含め、主張するだけでなく、自らの主張を検証します。

リポジトリ構成

パス	パッケージ
python/	PyPI の korely-memory。korely CLI と MCP stdio サーバーを含みます
js/	npm の korely-memory
n8n/	セルフホスト可能な n8n 用コミュニティノード n8n-nodes-korely（README をご覧ください）

コーディングアシスタント

リポジトリ内で korely init --tool claude-code（または codex、cursor）を実行すると、そのアシスタントがリポジトリごとに 1 つのメモリに接続されます。セッション開始時にメモリが渡され、セッションの内容が保存されます。接続したすべてのアシスタントが同じメモリを共有します。Python README をご覧ください。

MCP

Korely はホスト型 MCP サーバーを運用しているため、コーディングエージェントはパッケージを使わずにメモリを読み書きできます。

claude mcp add --transport http korely https://api.korely.ai/agent/mcp \
  --header "Authorization: Bearer kor_live_..."

ドキュメント

REST の完全な仕様、概念、統合ガイド：korely.ai/agents/docs

ライセンス

MIT。このクライアントはオープンソースですが、接続先のホスト型サービスはオープンソースではありません。