thecodacus/understory

understory – LLMエージェント向けの自己接続型マークダウン知識ベース

概要

• エージェントが読み取り、書き込み、クエリを実行できる軽量なファイルベースの「メモリ」。メモリは、Open Knowledge Format (OKF) v0.1 に準拠したプレーンなマークダウンファイルのコレクションとして存在し、各コンセプトは小さなYAMLフロントマター（type など）を持つマークダウンファイルです。
• リポジトリには、このバンドルをツール呼び出しインターフェース（MCP）でラップするサーバー、React Web UI、およびCLIが含まれています。サーバーはローカル（Dockerまたはソースから）で実行でき、OpenAI互換またはAnthropic互換のLLMエンドポイントと通信します。

主要なアイデア

1. 決定的なバンドルレイヤー – LLMプロンプトではなくコードが、すべての変更が有効なOKFバンドル（フロントマターの存在、インデックスファイルの再生成、ログの追加、パスのサンドボックス化）を生成することを保証します。
2. エージェント駆動の更新 – LLMには何を変更するかが求められ、サーバーが変更を安全に適用します。
3. グラフビューとトレース – コンセプトはフォース指向グラフ（Obsidianスタイル）として視覚化され、すべてのエージェントとのやり取りは、グラフ上で再生できるトレースとして記録されます。
4. プロファイル – 単一のサーバーで、独自のAPIキーによって選択される、分離された複数のメモリをホストできます。
5. メンテナンスツール – memory_maintain は、孤立したコンセプトや壊れたリンクがないかグラフをリントし、内部エージェントに修復を依頼します。

操作方法

インターフェース	機能
MCPサーバー (/mcp または stdio)	ツールセット memory_query、memory_add、memory_update、memory_status、memory_maintain を提供します。呼び出しはストリーミングされるため、LLMはツールの結果をリアルタイムで確認できます。
Web UI (http://localhost:3800)	バンドルツリーの閲覧、ライブグラフの表示、更新ログの表示、同じエージェントとのチャットが可能です。ツール呼び出しはインラインで表示され、トレースを再生できます。
CLI (pnpm agent:query …、pnpm agent:mutate …)	テストやスクリプト用のクイックコマンドラインアクセス。
プロファイルCLI (`profiles create	list

クイックスタート (Docker)

services:
  understory:
    image: ghcr.io/thecodacus/understory:latest
    ports: ["3800:3800"]
    extra_hosts: ["host.docker.internal:host-gateway"]
    volumes:
      - understory-memory:/bundle   # マークダウンバンドルはここに配置
    environment:
      BUNDLE_ROOT: /bundle
      LLM_API_BASE_URL: ${LLM_API_BASE_URL}
      LLM_API_KEY: ${LLM_API_KEY}
      LLM_API_FORMAT: openai   # または "anthropic"
      LLM_MODEL: ${LLM_MODEL:-}

docker compose up -d   # UI: http://localhost:3800, MCP: http://localhost:3800/mcp

サーバーは任意のOKFバンドル（ローカルフォルダー、名前付きボリューム、バインドマウント）を指すことができます。LLMエンドポイントは、OpenAI、DeepSeek、Anthropic、Groq、またはローカルで実行される llama.cpp サーバーにできます。

典型的なワークフロー

1. セッションを開始 – サーバーは、現在の知識ベースの簡潔な概要をLLMのシステムプロンプトと memory_query ツールの説明に挿入します。
2. エージェントに質問 – 例: memory_query "What is our deployment schedule?"。
3. 新しい事実を追加 – memory_add "We deploy on Fridays, never Mondays"。エージェントはマークダウンのコンセプトを作成し、バックリンクを更新し、UIに新しいノードが即座に表示されます。
4. メンテナンス – memory_maintain を定期的に（またはスケジュールして）実行し、孤立したノードや壊れたリンクを自動修復します。
5. 再生 – UIでトレースを開き、やり取り中に読み書きされたコンセプトを正確に確認します。

なぜ使うのか？

• 人間が読めて、バージョン管理可能 – メモリはプレーンなマークダウンで保存され、Gitで差分を確認できるため、変更を監査したりロールバックしたりできます。
• モデルに依存しない – ツール呼び出しをサポートする任意のLLMで動作し、サーバーが重い処理を担当します。
• 自己整理 – 内部エージェントがグラフを整理し、知識ベースが成長するにつれてドリフトを減らします。
• マルチテナント – プロファイルを使用すると、同じホスト上で個別の知識グラフ（仕事、健康、サイドプロジェクト）を維持できます。

制限事項 / 現在の範囲

• 検索は単純な線形スキャンで、数千のコンセプトまで対応できますが、まだ全文インデックスや埋め込みベースの検索ではありません。
• UIはシングルページのReactアプリで、ベアラートークン以外の認証はありません（LANでの使用のみ推奨）。
• グラフレベルのスキーマ（型付きエンティティ、リッチなリレーションシップ）は計画されていますが、実装されていません。

参加方法

• pnpm install && pnpm build でソースからリポジトリを実行します。モノレポには core、server、web パッケージが含まれています。
• テスト（pnpm test）は、バンドル検証、並行性、MCPラウンドトリップをカバーしています。
• GitHubのissue/PRで貢献できます。プロジェクトはMITライセンスであり、拡張（例: FTS5/埋め込み検索、カスタムページタイプスキーマ）を歓迎します。

---

Understory を使用すると、LLMエージェントに、プレーンなマークダウンで存在する永続的で編集可能なビジュアル知識グラフを提供できます。独自のプロプライエタリデータベースにロックされることなく「成長するメモリ」を実現します。