メインコンテンツへスキップ

​
パッケージ構成

Cohaku は TypeScript ESM モノレポ（Turborepo + pnpm）で、複数のパッケージから構成されています： 
packages/
├── shared/     # 型定義、インターフェース、定数 (tsc)
├── core/       # メモリエンジン、SQLite ドライバー、埋め込み、スコアリング (tsc)
├── mcp-server/ # MCP ツール登録、stdio トランスポート (tsc, private)
├── api/        # Hono HTTP API (tsc)
├── cli/        # CLI バイナリ — 唯一の公開パッケージ (tsup バンドル)
└── docs/       # Mintlify ドキュメント
依存関係は厳密に一方向です： 
shared → core → mcp-server / api → cli
cli パッケージは tsup（esbuild）を使って、すべてのワークスペース依存関係を単一の配布可能なバイナリ（npm 上の @cohaku/cli）にバンドルします。mcp-server パッケージはプライベートで個別には公開されず、CLI にバンドルされます。

​
コンポーネント

​
ストレージレイヤー

SqliteDriver は better-sqlite3 と2つの拡張機能を使ってすべての永続化を管理します：
  • sqlite-vec — ベクトル類似度検索（コサイン距離）のための仮想テーブル
  • FTS5 — BM25 ランキングと Porter ステミングによる組み込み全文検索
すべてのデータは単一の SQLite ファイル（デフォルト：~/.config/cohaku/memory.db）に保存されます。

​
埋め込み

@xenova/transformers を使って all-MiniLM-L6-v2 をローカルで実行します。以下に対して384次元の埋め込みベクトルを生成します：
  • メモリコンテンツ → vec_memories
  • エンティティ名 → vec_nodes
  • エッジのファクト → vec_edges
API キーやネットワーク通信は不要です。

​
メモリエンジン

MemoryEngine クラスがすべての操作を統括します：
  • 書き込み時に埋め込みを生成
  • クエリ時にハイブリッド検索（セマンティック + BM25）を実行
  • 4要素スコアリング（セマンティック、BM25、新しさ、重要度）を計算
  • セッション、エピソード、ナレッジグラフを管理

​
MCP サーバー

stdio トランスポート上の Model Context Protocol を通じて24のツールを公開します。各ツールは Zod バリデーション付きで MemoryEngine のメソッドにマッピングされています。 ツールは6つのカテゴリに分かれています：
カテゴリ数説明
コンテキスト1get_context — 優先度順のメモリ読み込み
メモリ6CRUD、検索、重複排除、統合
ナレッジグラフ5エンティティ、エッジ、グラフ探索検索
エピソード3時系列イベントログ
セッション4チェックポイント付き作業セッションライフサイクル
設定ファイル生成9Claude Code、Cursor、Copilot、Windsurf 等へのエクスポート
サーバーはMCP インストラクションも提供しており、接続されたエージェントにツールの効果的な使い方（セッションワークフロー、メモリレイヤーの選択等）をガイドします。

​
データモデル

memories          -- 3層メモリ（ソフトデリート対応）
memories_fts      -- BM25 検索用 FTS5 インデックス
vec_memories      -- セマンティック検索用 sqlite-vec

nodes             -- ナレッジグラフのエンティティ
vec_nodes         -- エンティティ名の埋め込み
edges             -- 双時相リレーションシップ
vec_edges         -- エッジファクトの埋め込み

episodes          -- 会話エピソード
episode_refs      -- エピソードとエンティティの参照
sessions          -- セッションライフサイクル追跡
config            -- キーバリュー設定