Emerald

Emerald

チャットの下にあるデータベース。 あなたとAIモデルが一緒にデータを入力する、ローカルのファイルベースのデータベースです。すべてのテーブルに実際の型と制約があるため、整理した内容が正しく保たれます。フリーソフトウェア、AGPL-3.0。デスクトップ専用で、サーバーもアカウントも不要です。getemerald.dev

Emeraldとは

• ドキュメントはファイルです。 .emd はディスク上に保存される実際のSQLiteデータベースで、SQLiteのバイト形式またはテキスト形式からファイルごとに選べます。sqlite3 で開くことができ、スキーマは文書化されており、通常のツールですべてのテーブルを読み取れます。自分で宣言したテーブルも含まれます。
• 記録するものには何でもテーブルを宣言できます：請求、給与、書籍、マイルストーンなど。これはフォーマットです。テンプレートではなく、実際の型を持ち、指定したルールごとにCHECKが付いた本物のテーブルです。条件に合わない値は、後から見つかるのではなく、書き込む時点で拒否されます。
• フォーマット同士をリンクでき、それらをまたいで数値を算出できます。開始時刻と終了時刻からの時間や、ここを参照している行の合計などです。読み取れない行があっても、合計から黙って除外されることはありません。
• 主張とは、成立していなければならないルールです。レシートの合計がカードの請求額と一致する、すべての時間に賃金が支払われている、などです。それぞれが証明済み、失敗、未確認のいずれかとなり、未確認の場合は理由が示されます。
• ファイルをフォーマットに読み込みます：スプレッドシート、CSV、行データのJSONファイル、Markdownのメモ、またはそれらが入ったフォルダーを読み込めます。列の割り当ては一度だけ行い、リーダーとして保存して、毎回チェックします。モデルが提示できるのは対応付けや位置であり、値ではありません。
• モデルはMCP経由で利用します。 サーバーはドキュメントを直接読み書きし、汎用クエリではなく、構造化されたツールを使います。あらゆるドキュメント向けに28個、台帳を使う場合は85個です。コミットを指示するまで、すべての書き込みはドライランです。書き込みの前にはドキュメントの隣にコピーが保存されます。サーバーのスキーマより古いドキュメントが移行されることはなく、報告のみが行われます。
• 会話の中に描画します。 シート、ボード、ロードマップを見せるよう頼むと、MCP Appsに対応したホストではアプリと同じようにサーバーが描画します（ClaudeデスクトップアプリのCodeタブとVS CodeのCopilot Chatで確認済み）。それ以外の場所では、同じ内容がテキストで返されます。
• パックは、誰かがすでに作成したフォーマットとそのビューです。Emeraldには台帳と開発パックの2つが付属しています。独自のパックの作成と共有は今後の予定です。
• インターネット接続もログインも不要です。 アプリはAIのためにもテレメトリーのためにも、自身からネットワークに接続しません。接続が発生するとテストが失敗します。例外は、オフが初期設定で、利用者が選べるアップデート確認です。有効にすると、1日1回GitHubに最新バージョン番号を問い合わせ、WindowsではGitHubのリリースから新しいバージョンをダウンロードします。「ヘルプ」→「今すぐアップデートを確認」では1回だけ問い合わせます。このマシン上のローカルモデルランタイムを利用でき、検索はクリックしたときに限り、ループバック経由で行われます。

台帳

• お金に管理されるのではなく、自分のお金を管理したい人のために、持っているものすべてを自分のものとして1か所にまとめます。
• すでに受け取っているファイルを読み込みます：カードの利用明細、銀行のエクスポート、給与明細、ファンドのレポート。
• すべての請求を記録し、振替と支出、毎月の請求と一度限りの請求を区別します。
• すべての合計から、その計算に使われた行を開けます。
• 1年分の学習基金レポートを読み込んだところ、給与明細には控除が記載されているのに、基金が何も受け取っていない月が見つかりました。
• 銀行には何も接続しません。ファイルは自分で渡します。

開発パック

• プロジェクトの記憶を行として記録します。マイルストーン、ユニット、決定事項、未解決の質問、受信箱が含まれます。

• セッションは、チャットの要約ではなく行をもとに開始します。すでに下された決定に反する依頼には、その決定を回答します。

• あるプロジェクトのセッションが別のプロジェクトの受信箱にメモを残し、次のセッションはそこでそのメモを確認して開始します。

• Emerald はこの仕組みを使って開発されています。docs/memory.emd はこのプロジェクトの記憶であり、このリポジトリでのすべてのセッションは、まずこれを確認することから始まります。

• リポジトリのセットアップは、そのフォルダー内で実行する1つのコマンドで完了します（0.2.0以降）：

  npx -y emerald-mcp init [path/to/document.emd]
  

  開発パックを含むドキュメントを作成します（名前を指定しない場合は docs/memory.emd。リポジトリ内にテキストとして保存されるため、コミットされ、差分を確認できます）。セッションの開始時に確認する質問と各形式の列を記載した、CLAUDE.md のマーク付きセクションを書き込みます。また、Claude Code プラグインがインストールされていない場合は、セッションに start_here と受信箱を表示する2つのフックも設定します。2回目以降の実行では何も変更されません。形式に変更があった場合は、そのセクションだけを書き換えます。

インストール方法

現在利用できる方法は3つです：

• デスクトップアプリ：Windows および macOS 対応です。最新リリースから入手できます。 .emd ドキュメントには専用のアイコンが付き、ダブルクリックで開けます。コード署名はされていません。Windows では 「Windows によって PC が保護されました」 と表示されます（詳細情報をクリックし、続いて 実行 をクリックしてください。インストーラーはユーザーごとにインストールされ、管理者パスワードは必要ありません）。macOS では Apple が検証できなかったと表示されます（完了をクリックし、続いて システム設定 → プライバシーとセキュリティで このまま開くをクリックしてください）。0.1.2以前の Mac 版では、代わりに 「Emerald は壊れているため開けません」 と表示され、「このまま開く」もありません。ターミナルで xattr -cr /Applications/Emerald.app を一度実行するか、新しい版をダウンロードしてください。各リリースは、このリポジトリのリリースワークフローによってタグからビルドされ、SHA256SUMS ファイルとともにアテステーションが付与されます。gh attestation verify <file> --repo kfireliyahu/emerald-emd を実行すると、そのファイルがワークフローでビルドされたものかどうかを GitHub に確認できます。インストーラーの名前にはバージョンが含まれないため（Emerald-Setup.exe、Emerald-arm64.dmg、Emerald-x64.dmg）、releases/latest/download/<name> から常に最新のものを入手できます。更新はデフォルトでオフです。概要でオンにすると、アプリが1日1回 GitHub に新しいバージョンがあるか確認します。Windows ではその後、バックグラウンドでダウンロードし、リリースで公開されたチェックサムと照合して、ウィンドウ上部に目立たない形で 準備完了 と表示します。インストールして再起動を押したときにのみインストールされ、開いていたドキュメントが再び表示されます。Mac では更新があることを知らせ、ダウンロードをクリックするとリリースページが開きます（Mac のアップデーターには署名済みアプリが必要です）。0.1.2以降は自動で更新されます。それより古いバージョンをお使いの場合は、新しい版を一度手動でダウンロードしてください。

• MCP サーバー：npm パッケージ emerald-mcp として提供されます。どのドキュメントでも、アシスタントの MCP 設定に1行追加するだけです。台帳のツールも使う場合は、--engine-only を付けないでください：

  claude mcp add emerald -- npx -y emerald-mcp --engine-only
  

• Claude Code プラグイン：サーバー、会話内に描画されるビュー、人と一緒に形式を宣言するスキル、プロジェクトの start_here と受信箱をセッションに取り込むフックが含まれています（実行内容）：

  /plugin marketplace add kfireliyahu/emerald-emd
  /plugin install emerald@emerald-emd
  

リポジトリ

ビルドと実行

git clone https://github.com/kfireliyahu/emerald-emd.git
cd emerald-emd
npm ci                 # npm install works too; this is the reproducible form
npm run dev            # the app, in a browser tab
npm run test           # the whole suite
npm run build          # the app -> dist/, what the desktop shell serves
npm run desktop        # build everything and open the desktop window
npm run build:plugin   # the MCP server -> dist-plugin/server.mjs
npm run build:demo     # Emerald's page and the tours -> dist-demo/
npm run dist:win       # the Windows installer -> release/
npm run dist:mac       # the macOS disk image -> release/   (needs a Mac)

• Node 24 でビルドおよびテストしています。npm ci は監査に関する警告を出力します（MCP SDK とルーターに関するもので、記録されています）。デスクトップウィンドウを開くものを初めて実行すると、Electron のバイナリが一度ダウンロードされます。ビルドでネットワークが必要になるのはこのときだけです。
• 画面は幅広のデータ向けで、カラムマッパー、インポートの確認画面、入金のテーブルがあります。スマートフォン向けレイアウトは意図的に用意していません。ブラウザーでは、Chrome と Edge は File System Access API を使ってサイレントに保存し、Safari と Firefox はダウンロードで保存します。デスクトップアプリはどこでもサイレントに保存します。

このチェックアウトの MCP サーバー

.mcp.json は dist-plugin/server.mjs を --engine-only 付きで指定しているため、このディレクトリで起動した Claude Code セッションはこれを検出し、1 回だけ承認を求めます。それ以外の場所から使う場合：

claude mcp add emerald -- node /absolute/path/to/dist-plugin/server.mjs --engine-only

台帳のツールも使う場合は、--engine-only を付けないでください。ビルド済みフォルダーは自己完結しており、すべてのパッケージが同梱され、現在の npm パッケージそのものになっているため、Node が動作する場所ならどこでも実行できます。docs/plugin.md には、ツールの一覧、試したホスト、ルールが記載されています。

各要素の場所

• docs/：仕様、アーキテクチャ、データモデル、エンジン、各領域についてのメモです。docs/09-decision-log.md には設計の理由が記録されており、docs/memory.emd にはビルドの状況が行ごとに記載されています。
• docs/demo.md：ページ、ツアー、別のページに埋め込む方法です。
• src/domain/ はエンジンで、React、SQLite、DOM からは何もインポートしません。src/data/ はストレージ、src/ui/ はアプリ、src/plugin/ は MCP サーバー、electron/ はデスクトップシェル、src/data/packs/ は 2 つのパックです。

イシューと貢献

• イシューやディスカッションを歓迎します。
• コードの貢献にはコントリビューター契約が必要です。LICENSING.md にその理由が記載されています。受け入れを開始した際に、特に貢献が役立つのは、各形式を日常的に扱っている方によるインポートマッピングとロケールパックです。
• 実際の明細ファイルは絶対に含めないでください。 フィクスチャは合成データであり、それ以外のデータを拒否するテストがあります。

免責事項

• 計算はしますが、助言はしません。 Emerald が表示する内容は、金融、税務、法律、投資に関する助言ではありません。入力された内容を合計し、合わない場合にそれを示します。どう対応するかは、いつも相談している相手と相談するなどして、ご自身で判断してください。
• 読み取った内容を確認してください。 給与明細、明細書、ファンドレポート、領収書から読み取られた数値は、コードまたはモデルによるその文書の読み取り結果であり、どちらも間違う可能性があります。正しい情報は文書にあります。Emerald は比較できるよう、読み取り結果を文書の横に保存します。
• モデルの発言はモデルによるものです。 アシスタントが MCP を通じて文書を扱うとき、その発言や書き込みの要求は、このプロジェクトではなく、利用条件に基づいたアシスタントとそのプロバイダーによるものです。Emerald の役割は、適合しないものを拒否し、書き込みが行われる前にすべてを表示することです。
• ファイルはあなたのものです。 Emerald は開いた文書に書き込み、その横にコピーを保存します。それ以外の場所にコピーを作ることはありません。他のファイルと同じようにバックアップしてください。失われたファイルをここで復元することはできません。
• 提携関係はありません。 Emerald は、銀行、カード発行会社、ファンド、雇用主、給与処理サービス、AI プロバイダーと提携、推奨、代理する関係にはありません。台帳は、それらの機関が提供するファイルを、どのようなレイアウトであっても読み取ります。
• 現状のまま提供します。 ソフトウェアは、AGPL-3.0 の第 15 条および第 16 条に全文が記載されているとおり、いかなる保証もなく提供されます。デスクトップ版は署名されておらず、このリポジトリのワークフローによってビルドされています。使用するか、ソースからビルドするかは、ご自身の判断で行ってください。

プライバシー

Emerald は何も収集しません。ポリシーの全文は PRIVACY.md をご覧ください。

ライセンス

コードは AGPL-3.0-only（LICENSE）、ノートとエッセイは CC BY 4.0、フォーマット宣言、パック、合成フィクスチャは CC0 です。LICENSING.md には、それぞれのライセンスの適用対象、名称とマークの対象外となるもの、商用ライセンスの取得方法が記載されています。デスクトップアプリの「About」にも同じ内容が記載されており、バンドルされているすべてのサードパーティー製ソフトウェアの告知は、ヘルプからワンクリックで確認できます。