knowl

ローカルファースト。型付き。そして、それが真実でなくなった瞬間に引退します。

クイックスタート · なぜ supersession か · 保存されるもの · 機能 · エージェント設定 · ビューアー · 要件 · 完全リファレンス →

コーディングエージェントは毎回白紙の状態でセッションを開始するため、チームはメモを書き残します — そしてそれらのメモは増え続ける一方です。半年後、ストアは昨年春に移行したはずのデータベースをまだ報告しています。なぜなら、その決定が終わったことを伝えるものが何もなかったからです。

Knowl は Claude Code、Cursor、Codex 向けのセッションを超えた永続メモリです。リポジトリローカルに保存される型付き知識アトム — 決定、制約、アーキテクチャ、事実、目標、状態、スキル — を MCP メモリサーバーまたは knowl CLI 経由で読み書きします。ここでは置き換えが書き込み時に先行するものを引退させ、隣に置き続けることはありません。

クイックスタート

Node.js 22 以降が必要です。

npm install -g @dat999zx/knowl
cd your-project
knowl init

knowl init は .knowl/ を作成し、プロジェクトガイダンスファイルをインストールし、.gitignore を更新し、検出されたエージェント（Claude Code、Codex、Cursor、Gemini CLI、Claude Desktop）向けの MCP およびライフサイクル設定を提供します。また、ローカルの埋め込みモデルをウォームアップしますが、そのダウンロードの成功に依存することはありません。

保存する価値のあるものを記録します：

knowl decide "Use SQLite" "Use SQLite for local project memory." \
  --reasoning "Keeps storage repository-local and simple to operate." \
  --alternatives PostgreSQL MongoDB \
  --tags database local-first

CLI または接続された任意のエージェントから読み戻します：

knowl query "why sqlite"     # search project memory
knowl state                  # the active memory, as a hierarchy
knowl status                 # repository, memory, AI, and workspace status
knowl doctor                 # check setup, retrieval, and agent registration

その後、新しいエージェントセッションを開始して、ホストがガイダンスと MCP 登録を認識できるようにします。CLI と knowl_query は、同じガバナンスルールの下で同じストアを読み取ります。

Related MCP server: Mnemoverse Memory

アイデア：自己引退するメモリ

ほとんどのメモリシステムは追記専用です。「SQLite に移行しました」と保存しても、「PostgreSQL を使用しています」がアクティブで検索可能なまま残るため、エージェントは両方を取得してランクで選択します。Knowl は同じ主題への書き込みを修正として扱います：先行するものは superseded とマークされ、通常の検索から外れ、knowl timeline を通じてクエリ可能なまま残ります。

この単一の動作が、精度の差の大部分を占めています。MemoryAgentBench 競合解決コーパス — 455 の事実、どの事実が最新かに関する 100 の質問、トップ 5 検索、LLM リーダーなし：

同じコーパス、同じランカー、同じクエリパス。唯一の変数は、古い事実がまだアクティブかどうかです。これは Knowl 自身のハーネスでの検索レベルの測定であり、モデルを介さずに現在の事実が最初に返ってくるかどうかを問います。

ベンチマーク自身のハーネスでエンドツーエンド検証済み

自分でスコアを付けた数値は他人がスコアを付けたものより価値が低いため、同じ主張を MemoryAgentBench のハーネス内で、そのコードによってスコアリングして再実行し、Knowl が返したものを LLM が読み取るようにしました — より難しい、完全なエンドツーエンドの設定で、タスクが提供する最大のコンテキストで行いました：

18,332 の事実、100 の質問、部分文字列完全一致。すべての行がリーダーとして gpt-4o-mini を使用しており、Knowl も含まれています — 論文ではすべての RAG およびメモリエージェントについてそれが明記されているため、これらは同等の比較です。Knowl の数値はここで測定されました。他のすべての数値は MemoryAgentBench 論文の表 2 からのものです。論文がこのタスクで評価していないシステムはリストされていません。

同じハーネスで supersession をオフにすると、Knowl は 73 に低下し、その差はコーパスサイズが 40 倍変化しても維持されます：

2 つのセクションは異なるものを測定しており、互いに比較できません：98% はリーダーなしの 6K での検索トップ 1、90 はリーダーありの 262K でのエンドツーエンド精度です。上記の公開システムと比較できるのは 2 番目だけです。プロトコル、チェックインされた結果、およびタスクがカバーしない内容（マルチホップを含む — Knowl は 14 ポイントの検索上限に対して 7 をスコア）については、ベンチマークを参照してください。

Supersession は削除ではなく修正です：アイテム、そのアサーション、およびその履歴はすべて残ります。

モックアップではありません — 公開 CLI に対する同じシーケンスを demo.tape から録画したものです：

保存されるもの

すべてのアトムは、7 つのカテゴリのうち正確に 1 つを持ちます：

コンテンツに加えて、各アトムはステータス（active、deprecated、rejected、archived、superseded）、鮮度フラグ、信頼度、タグ、ソースコミット、影響を受けるパス、およびファイル、コミット、テスト、コマンド、URL、またはインデックス化されたコードシンボルを指すオプションのエビデンスを保持します。ファイルとシンボルのエビデンスは、コードが移動すると自動的に古くなります。これにより、アトムはもはや存在しないリポジトリのバージョンを主張するのではなく、自分が古くなっている可能性があることを認めることができます。

Knowl が意図的に保存しないものは、あなたの会話です。ライフサイクルキャプチャは、限定されたイベントと要約を記録します — プロンプト、トランスクリプト、標準出力、環境変数は決して記録しません。生のトランスクリプト検索は、ホストがすでに書き込んだファイルに対するオプトイン、デフォルトオフのインデックスとして存在します。

→ 知識モデルリファレンス

エージェントの接続

knowl serve はストアを stdio MCP 経由で公開します。knowl init がそれを登録します。インストールされたガイダンスがエージェントに従うよう求めるワークフローは短いものです：

1. リポジトリファイルを読む前に、主題を表す言葉でメモリをクエリします。

2. アクティブなヒットを直接使用します。ミス、競合、または古い結果の場合にのみファイルを検査します。

3. 進行中に耐久性のある発見、表明された目標、繰り返し発生する診断を保存し、矛盾したメモリを複製するのではなく修正します。

実際には次のようになります — 新しいセッション、コンテキストなし、何も貼り付けられていません：

You     why did we pick SQLite over Postgres?

Agent   → knowl_query "sqlite postgres database choice"
        ← decision · Use SQLite · active · fresh
          "Keeps storage repository-local and simple to operate."
          alternatives: PostgreSQL, MongoDB
          tags: database, local-first

        SQLite keeps the store repository-local and simple to operate.
        Postgres and MongoDB were both considered and rejected on that
        basis.

エージェントはファイルを1つも開く前に回答し、あなたが却下した選択肢を知っていました — コードはそれを伝えることができません。なぜなら、却下された代替案はコードベースに痕跡を残さないからです。

フックが利用可能な場合、フックがセッションライフサイクルを管理します：ブートストラップコンテキスト、キャプチャ、チェックポイント、ファイナライゼーションがエージェントに要求されることなく行われます。利用できない場合、knowl task run、task start、task checkpoint、task finish が同じ範囲を手動でカバーします。

knowl init は検出したすべてのホストに対してMCP登録を書き込みます。手動で接続する場合、エントリはどこでも同じです：

{
  "mcpServers": {
    "knowl": { "command": "knowl", "args": ["serve"] }
  }
}

Windowsではコマンドとして knowl.cmd を使用します。Codexは mcp_servers の下で同じエントリを読み取ります。

→ MCPツールとリソース · ライフサイクルリファレンス

Knowlの目的

Knowlは1つの仕事をします：リポジトリのエンジニアリングの真実を、それに取り組むエージェントに対して正確に保つこと。ユーザーの好みでもチャット履歴でもなく — コードベースの決定、制約、アーキテクチャ、そしてそれらのうちどれが今日も真実であるか。

そこから3つの選択が導かれます：

• 型付けされ、自由テキストではない。 決定は推論とあなたが却下した代替案を伴います。制約は保持され続けなければならないルールです。state アトムは期限切れになることが予想されます。検索はそれらの違いに基づいてランク付けできますが、ノートファイルの段落に基づいてランク付けすることはできません。

• 管理され、追記専用ではない。 ステータス、鮮度、出所、競合識別、および置き換えにより、ストアは何かが真実でなくなったことを伝えることができます。それがメモリと増え続けるノートの山との違いのすべてです。

• リポジトリローカルであり、サービスではない。 データベースはそれが記述するコードの隣にあります。アカウントも、外部送信も、ベンダーも、あなたとあなた自身のプロジェクト履歴の間にはありません。

Knowlは意図的にパーソナライゼーションレイヤーではありません。ユーザーについての意見はなく、自身のトランスクリプトも保持しません。

機能

以下はすべて、CLIおよびMCP接続された任意のエージェントから、同じローカルデータベースに対して機能します。アカウントも、サーバーも、APIキーも不要です。各項目は詳細と制限について完全なリファレンスにリンクしています。

♻️ 自己修正する知識

7つの型付けされたアトムタイプ。同じ主題への書き込みは、その前身を隣に置くのではなく退役させます。その1つの動作が90対73の違いです。ファイルまたはシンボルに添付されたエビデンスは、コードが移動すると自動的に古くなります。

conflicts · timeline · query --as-of · pr --since · index-code

🎯 エージェント向けに調整された検索

ベクトル優先で、制限付きBM25フォールバック、鮮度、ステータス、信頼度で再ランク付けされるため、単に類似したものではなく現在の回答が勝ちます。埋め込みモデルはローカルでオプションです — それがなくてもキーワード検索は可能で、何もマシンの外に出ません。

query · context --token-budget · config set-model · access

⏱️ セッションを超えて存続する作業

Claude Code、Codex、Cursorでは、フックがブートストラップ、キャプチャ、チェックポイント、ファイナライゼーションをエージェントに要求されることなく管理します。クリーンな終了は最大8つの耐久性のある候補を抽出します。ワークストリームをキーの下に置き、任意のセッション、任意のディレクトリから再開します。

task run · handoff · park · resume <key>

🔗 ワークスペース

APIリポジトリがフロントエンドリポジトリに必要な何かを学習しました。それらをリンクするとクエリがファンアウトしますが、各リポジトリは独自のデータベースと独自の所有権境界を保持します。共有されたピアアトムをIDで完全に開くか、呼び出しで名前を指定してここからそのリポジトリの作業を終了します。リポジトリがすでに保持している知識は、プロモートした場合にのみ共有されます。

workspace init · workspace add · workspace promote --apply

📦 再利用可能な手順

手順をそのスクリプトとともに .knowl/skills/ の下にパッケージ化し、実行前に読み取ります。複数のアトムを決定論的に1つのアーキテクチャサマリーにまとめます。AIプロバイダーは一切関与しません。

skill list · skill read · skill run · synthesize

💾 あなたのデータ、そしてそれを取り戻す

チェックサム付きJSONLエクスポートとインポート。同じアトムが2か所で変更された場合の4つの明示的なポリシーがあります。リストアは、何かに触れる前にスキーマ、サイズ、SHA-256、SQLiteの整合性を検証し、最初にリストア前のスナップショットを取得します。

export · import --on-divergence · snapshot create · gc · doctor

初日に知っておくべきコマンド：

knowl query "auth design"              # search project memory
knowl state                            # the active memory, as a hierarchy
knowl conflicts                        # items that contradict each other
knowl timeline <item-id>               # every version an atom ever had
knowl context --token-budget 1500      # a fixed-size briefing for an agent
knowl pr --since origin/main           # knowledge your diff may invalidate
knowl doctor                           # setup, retrieval, and registration

• 7つのアトムタイプ — 上記にリスト。1つの成長するノートファイルではなく構造化。

• 自動置き換え — 同じ主題への書き込みはその前身を退役させます。これが上記の90対73の違いです。

• 競合識別 — アトムを排他的にマークすると、Knowlは同じ質問に対する2番目のアクティブな回答を静かに両方を保持するのではなく拒否します。knowl conflicts

• 完全な履歴 — アトムがかつて持っていたすべてのバージョンが不変のアサーションとして存続します。knowl timeline <item-id>

• タイムトラベル — 過去の日付にプロジェクトが何を信じていたかを尋ねる：knowl query "auth design" --as-of 2026-01-01T00:00:00Z

• エビデンス — ファイル、シンボル、コミット、テスト、コマンド、またはURLをアトムに添付します。ファイルとシンボルのエビデンスは、コードが移動すると自動的に古くなります。

• ドリフト検出 — knowl pr --since origin/main は、マージする前に、差分が無効にした可能性のある知識にフラグを立てます。

• コードインテリジェンス — .ts / .tsx / .js / .jsx に対するインクリメンタルなTree-sitterインデックス。これにより、エビデンスは行番号だけでなく symbol:// ロケーターを指すことができます。knowl index-code

• シークレットセーフな書き込み — すべての書き込みは、着地する前に検出されたシークレット、機密パス、および過大なコンテンツについてスクリーニングされます。長期メモリは、資格情報が最終的にあるべき最後の場所です。

→ 知識モデル · エビデンスとドリフト

• ベクトル優先ランキング。制限付きBM25フォールバック、鮮度、ステータス、信頼度、最近性で再ランク付け — そのため、単に類似したものではなく現在の回答が勝ちます。（これはエージェント/MCPパスです。CLIからの単一リポジトリの knowl query は字句的です。）

• オフラインで動作。 埋め込みモデルはローカルでオプションです。それがなくてもキーワード検索は可能です。検索はクエリをどこにも送信しません。

• 5つのバンドルされた埋め込みプリセット。200以上の言語をカバーする多言語プリセットを含み、さらに独自のONNXモデル用の custom があります。knowl config set-model <model>

• 正確な識別子のサポート — ファイル名、アイテムID、symbol:// ロケーターは、セマンティック類似性が弱い場合でもヒットします。

• トークンバジェット付きコンテキストパック — エージェントに、制約を最初に固定した固定サイズのブリーフィングを渡します。これにより、交渉不可能なルールが切り捨てられることはありません：knowl context --query "auth rollout" --token-budget 1500

• 使用状況フィードバック — エージェントは結果が役立ったかどうかを報告し、knowl access は何が頻繁に使用されているか、何が古いか、何が修正を引き起こし続けているかを示します。

→ 検索とコンテキスト

• 自動ライフサイクル — Claude Code、Codex、Cursorでは、ブートストラップ、キャプチャ、チェックポイント、ファイナライゼーションがフックを通じてエージェントに要求されることなく行われます。

• ワークループ — その他すべてに対して、knowl task start、checkpoint、finish、または単一のコマンドを knowl task run "Run tests" -- npm test でラップします。

• セッション終了時のプロモーション — クリーンな終了はセッションから最大8つの耐久性のある候補を抽出し、3回成功したコマンドはそれを説明する skill アトムになります。

• ハンドオフ — このリポジトリの次のセッションのために1つのバトンを残します。一度配信されると、アーカイブされます。

• 再開キー — ワークストリームを保持する短いキーの下に置き、後で任意のセッション、任意のディレクトリから何度でも再開します。knowl resume <key>

• オプションのトランスクリプト検索 — デフォルトではオフで、オフはディスク上に何も存在しないことを意味します。オンにすると、過去のセッションの散文が検索可能になり、メモリミスは記憶喪失ではなく低速なルックアップに低下します。

→ タスク、セッション、ライフサイクル

APIリポジトリがフロントエンドリポジトリに必要な何かを学習しました。それらをリンクするとクエリがファンアウトします — 各リポジトリは独自のデータベースと独自の所有権境界を保持します。

knowl workspace init product      # create the workspace
knowl workspace add product       # run inside each repo that joins it
                                  # ...or --default-visibility repo to keep its writes private

knowl workspace promote                               # pick what to share from a list
knowl workspace promote --category decision --apply   # or name it outright

ワークスペースに参加すると、リポジトリがそれ以降に書き込むものが共有され、その際にその旨が通知されます。--default-visibility repo を渡すと拒否できます。リポジトリがすでに知っていることは、プロモートした場合にのみ共有されます。ピアの結果はそれを所有するリポジトリでラベル付けされ、共有されたものはIDで完全に開くことができます — ただし、その affectedPaths やエビデンスは除きます。これらはあなたが立っていないチェックアウトに対して解決されます。欠落しているか読み取り不可能なピアはスキップされて開示され、ローカル検索が失敗する理由にはなりません。

兄弟への書き込みは偶発的ではなく意図的です。エージェントは呼び出しでリポジトリを指定し、その1回の呼び出しはそのリポジトリとして実行されます — そのストア、その設定、その所有権ルール、それ自身のものとしてスタンプされます — まさに cd でそこに移動することがCLIで常に動作してきたのと同じです。何も指定しないと、外部IDは以前と同様に拒否されます。どちらにせよ、リポジトリのプライベート知識はプロモートされるまでプライベートのままです。

→ ワークスペース

• ファイルベースのスキル — .knowl/skills/ 配下に手順とスクリプトをまとめ、実行前に検査できます。knowl skill list · read · run

• 決定論的合成 — AIプロバイダを介さずに複数のアトムを1つのアーキテクチャサマリにまとめる: knowl synthesize --scope storage

→ スキルと合成

• ポータブルなエクスポート/インポート — チェックサム付きJSONL。同一のアトムが2箇所で変更された場合に備え、4つの明確な発散ポリシーを提供。knowl export · knowl import --on-divergence newer

• 検証済みスナップショット — knowl snapshot create はチェックサムマニフェストを書き込み、リストア時には何にも触れる前にスキーマバージョン、サイズ、SHA-256、SQLite整合性を検証し、まずリストア前のスナップショットを取得します。

• デフォルトでプレビュー表示し、最近使用されたものは保護するガベージコレクション。 knowl gc

• knowl doctor — セットアップ、設定、整合性、スキーマ、検索、ベクターカバレッジ、エージェント登録、ワークスペースの健全性をチェックする単一のコマンド。

• オプションのAI — knowl ask と生テキスト取り込み用のプロバイダを設定。上記の全機能はAIなしでも動作します。

→ 移植性とメンテナンス · オプションのAI

実際に見る：ローカルビューア

knowl view は起動ごとに新しいアクセストークンとともに 127.0.0.1 上で読み取り専用のインスペクタを起動します。ポートを知っているだけでは何も読めません。

knowl view

カテゴリで検索・フィルタリング、古くなったリングの発見、近傍のフォーカス、任意のアトムを開いて証拠とタイムラインを読むことができます。グラフは共有タグとカテゴリ由来のエッジでアトムをリンクします。これはナビゲーション支援であり、因果関係や証拠のグラフではありません。すべてのステータスにわたって完全なローカルコンテンツを表示するため、ループバックバインディングがプライバシーの境界となります。パブリックプロキシやトンネルの背後に配置しないでください。

→ ローカルビューア

その他すべて

27個のMCPツール（議事録検索がオンの場合は3個追加、クラウドワークスペースに接続時は1個、ローカルワークスペースにリンク時は1個、変更影響がオンの場合は1個）

2つのリソースURI · 完全なCLI（knowl status から knowl audit まで）· 読み取り専用の整合性監査 · チェックインされたガバナンスと500ケースの回帰テストスイートを使って knowl eval で自分で実行できる検索評価

→ CLIリファレンス · MCPツール · ベンチマーク

要件とローカルデータ

Node.js 22 以降。Knowlがプロジェクトに書き込むすべてのデータは .knowl/ 以下に保存され、knowl init によって .gitignore に追加されます。

ワークスペースマニフェストはメンバーリポジトリの外部に存在します。チェックアウトパスはマシンローカルだからです。エクスポートとスナップショットは要求があった場合のみ書き込まれます。

ドキュメント

上記はすべて概要です。完全リファレンス はすべてのサブシステムを深くカバーする一つのドキュメントです。意図的に制限されている部分も含まれており、それが通常、実際に知る必要があることです。

コントリビューション

セットアップ、プルリクエスト前に実行すべきチェック、このコードベースが従う規約については CONTRIBUTING.md を参照してください。コントリビューターは最初のプルリクエストの際に コントリビューターライセンス契約 に一度同意する必要があります。

ライセンス

Knowl は Apache License 2.0 の下でライセンスされています。Apache-2.0 は商標権を付与しません。