LightVelaドキュメント

概要

**USER.mdとMEMORY.mdはHermes Agentの長期記憶の背後にある2つの個人用ノートであり、それらを統合できない理由は3つの厳格な制約で説明できます。まず、容量は独立しており（USER.mdは約1,375文字／500トークン、MEMORY.mdは約2,200文字／800トークン）、どちらも他方を圧迫しません。第二に、読み込みの意味が異なります：両方とも各セッションで読み込まれますが、その役割は完全に異なります — 一方は「あなたが誰であるか」を安定して記述し、もう一方は「これまでに行ったこと」を頻繁に記録します。第三に、更新の意味が異なります：USER.mdの優先フィールドは主に古い値を上書きするのに対し、MEMORY.mdは主に必要に応じて追記および統合します。それらを1つに統合するとNOTES.md は3つの制約を同時に破ることになる ― 「見た目は単純だが、実際の動作は悪い」の教科書的な例です。

まずは妥当な質問から始めましょう

Hermes の階層型メモリ全体で、USER.md と MEMORY.md は合計でわずか 約3,575文字 / 約1,300トークン です ― 6桁のコンテキストウィンドウが一般的な時代にしては驚くほど控えめです。

だからほとんどの人の最初の反応は次の3つの質問です：

なぜそれらを1つのNOTES.md に統合しないのですか？
なぜ数万バイト規模に拡大しないのですか？
なぜ2つのファイルは異なる上限（2,200対1,375）を持っているのですか？

3つとも同じ答えを指しています：USER.mdとMEMORY.mdは二種類の異なるメモリであり、一緒に詰め込むと両方とも悪化します。 以下では、その設計原則を3層に分けて説明します。

1. `USER.md`: 安定した構造化されたユーザープロファイル

USER.mdはあなたの安定した記述です：

アイデンティティ: 名前、役職、所在地。
好み: コミュニケーションスタイル、通常の技術スタック。
制約: スケジュール、言語、避けるべきトピック。
作業スタイル: 結論優先かプロセス優先か。
長期目標：あなたが目指しているもの。

その主要な特徴：

安定している：数日または数週間ごとに更新される。
構造化されている：セクション分け、項目化、フィールドベース。
常にロードされる：各セッションの開始時にシステムプロンプトに注入される。
ハード上限：約1,375文字 / 約500トークン。

USER.mdをエージェントのモニターベゼルに貼られた付箋のように考えてください — 内容は多くないが、常に目に入り、常に役立つ。

2. `MEMORY.md`：成長する、オンデマンドの事実アーカイブ

MEMORY.md は、あなたとエージェントが一緒に行ったことを保存します：

プロジェクトの状態：エージェントデモのフロントエンドはローカル開発ポートで実行されています。
決定事項：先週、ヒーローセクションはアニメーション付きグラデーションに変更されました。
具体的な出来事：チームAとQ4にXを出荷することで合意しました。
具体的な知識：このAPIは公開エンドポイントではなく、内部SDKを通じて認証されます。

その主要な特徴：

動的：ほぼすべての実質的なセッションで1～2件のエントリが書き込まれます。
項目別：簡単に思い出せるように、エントリごとに追加されます。
常に読み込まれるものとオンデマンドのFTS5マッチング: 一般的なエントリーは毎回のセッションで読み込まれ、過去のエントリーはFTS5のマッチによって引き出されます。
通常8〜15エントリー: 合計約2,200文字／約800トークンを目安に、8〜15エントリーを目標とします。

MEMORY.mdは机の上のジャーナルのようなものと考えてください — 付箋より多いですが、それでも素早く目を通せるよう控えめに書かれています。

3. 「なぜそれらを1つのNOTES.mdに統合しないのか？」 — 3つの厳しい制約

誰かが必ず尋ねるでしょう: 両方とも毎回のセッションで読み込まれるMarkdownなので、なぜ統合しないのか？

ここに、各々がアイデアを破綻させるほど独立して強力な3つの厳しい制約があります。

制約1: 独立した容量、相互圧迫なし

USER.mdは500トークン、MEMORY.mdは800トークンを持っています。統合後、1,300トークンのNOTES.mdは直ちに問題に直面します: メモリがほぼ満杯のとき、エージェントは「ユーザーが誰であるか」に関する行を削除して、もう1つのイベントを記録するのでしょうか？

明らかにすべきではない — しかし一度マージされると、その決定は下さなければならず、すべての書き込みごとに行われる必要があります。分けて保持される場合、2つのプールは独立して進化します：MEMORY.mdがいっぱいになると、それは自分自身だけを圧縮し、プロファイルを汚染することはありません。

制約 2：異なるロードの意味

両方のファイルは実際にすべてのセッションでロードされますが、システムプロンプトにおける役割はまったく異なります：

USER.mdセクションは「誰と対話しているのか」に答え、エージェントの口調、詳細レベル、スタックの前提を設定します。
MEMORY.md セクションは「あなたたちが一緒に行ったこと」に答え、エージェントに事実上の手がかりを提供します。

これらを統合すると、互いに希釈されてしまう — エージェントはもはや「これは従うべきコミュニケーションスタイルか、それとも引用すべき過去の事実か」をすぐに判断できなくなります。

制約 3: 更新のセマンティクスが異なる

USER.md の設定項目はほとんど上書きされる: ユーザーが「これ以降、要約をやめて」と言った場合、該当する設定行が直接上書きされます。
MEMORY.md は主に要求に応じて追加および統合します: イベントは時系列であるため、履歴を軽々しく消去することはできません。容量がいっぱいになると、次のエラー応答がアクティブな統合を引き起こします:

{
  "success": false,
  "error": "Memory at 2,100/2,200 chars. Consolidate now...",
  "current_entries": [...],
  "usage": "2,100/2,200"
}

マージ後、add / replace / remove はすべて同じファイル上で共存する必要があり、実装もユーザーの頭の中のモデルも同時に悪化します。

4. 具体的な例

あなたがエージェントに次のように伝えたとします:

「私はフロントエンドエンジニアのジャスミンで、結論先行のコミュニケーションが好きです。現在、Next.jsと一緒にエージェントデモ（AIエージェントアプリ）のグローバルサイトに取り組んでいます。先週、ヒーローセクションをアニメーション付きグラデーションに変更しました。」

よく訓練されたHermes Agentはこれを次のように分割します：

USER.md向けに書かれた内容：

## Identity
- Name: Jasmin
- Role: Frontend engineer

## Preferences
- Communication style: conclusion first
- Usual stack: Next.js

MEMORY.md向けに書かれた内容：

- [2026-07-30] agent-demo: hero section on the global site changed to an animated gradient.
- Related project: agent-demo / global site (global region)

違いがわかりますか？

「どんな人か」はプロフィールに、「一緒にしたこと」はアーカイブに入ります。
前者はあなたが変わったとき（新しい仕事、新しいチーム）にしか変わりません。後者は会話の毎日とともに成長します。
それぞれが独自に進化できるのは、別々のファイルがあるおかげです。

5. 5項目のスキップリスト

HermesはすべてをUSER.mdに押し込むわけではありません。スキップリストを維持しています：

一時的な気分：「今日は頭が痛い」— 安定した属性ではありません。
一時的なタスクパラメータ：「このタイトルをXに変更してほしい」— 使い捨てです。
あいまいな態度：「もう少し簡潔な方がいいと思います」— 再利用には十分ではない（条件を付けるか、スキップしてください）。
ライブ会話の文脈から推測できること — 保存する必要はありません。
機密情報（ユーザーが明示的に確認していないメール、パスワード、住所など）— プライバシーに関する内容は、デフォルトでは記載されません。

このスキップリストによって、USER.md が「500トークンで高密度」の状態に保たれています。

6. これが製品に意味すること

エージェント製品において、USER.md と MEMORY.md の分割は単なる技術的な詳細ではありません。それは三つのことを決定します：

ユーザーに「私があなたについてどう思っているか」を表示できるかどうか — それには安定して読みやすく、編集可能なプロファイル（USER.md のセマンティクス）が必要です。
エージェントが長期的に健忘を避けられるかどうか — それには増え続ける、呼び出し可能な事実のアーカイブ（MEMORY.md のセマンティクス）が必要です。
コストが制御可能なままであるかどうか — 「あなたが誰かを知る」と同時に全コンテキストを消費しないためには、階層的なロードのみが可能です。

7. LightVela: これら二つの台帳を製品に変える

LightVelaの内部エージェントメモリ設計はまさにこの階層的な考え方を取り入れています。HermesのUSER.mdとMEMORY.mdは開発者向けに書かれたMarkdownファイルです；LightVelaはそれらを通常のユーザーが直接操作できる二つのものに変換します：

可視化されたプロファイル層：ユーザーはエージェントが覚えているプロファイル事実と、それぞれがどの会話から来たかを確認でき、ワンクリックで修正できます。プロファイルはもはやブラックボックスのUSER.mdではありません。
整理可能な事実レイヤー：事実の記憶は単なるエントリーの積み重ねではありません — プロジェクト、タスク、時間でタグ付けすることで、より簡単に呼び出しや整理ができます。チームの場面では、チームの記憶と個人の記憶を別々のレイヤーとして管理することができます。
最短ルート：もしレイヤードメモリのアイデアに興味があるが、~/.hermes/USER.mdを編集したり、FTS5を維持したり、SQLiteをバックアップしたりしたくない場合、LightVelaはそのアイデアを完成品として最短で体験できる方法です。

一言で言えば：Hermesはレイヤードメモリのエンジニアリング設計図を提供し、LightVelaはそれを誰でも使える製品体験に変えます。

重要なポイント

USER.md: 毎回のセッションで読み込まれる安定した構造化されたユーザープロフィール（約500トークン、8～15のプロフィールフィールド）。
MEMORY.md: 成長し、オンデマンドでアクセスされる事実アーカイブ（約800トークン、8～15のイベントエントリ）。
3つの厳格な制約により、それらは互いに分離されている：独立した容量／異なる読み込み意味論／異なる更新意味論。
レイヤリングは優れたエージェント記憶の基盤となる能力であり、LightVelaで記憶を製品化する出発点である。

LightVelaドキュメント

このページの内容