memharness

memharness

AI エージェント向けの、来歴情報を保持する二時点メモリプリミティブです。 SQLite ファイルは 1 つだけです。ストレージ層で LLM やネットワークへの呼び出しは行いません。MCP を介してあらゆるエージェントから利用できます。

多くのエージェントのメモリは、単なる文字列の寄せ集めです。memharness は事実を保存し、既存の仕組みでは個別に扱われがちな 3 つのセマンティクスを組み合わせます。

1. 二時点管理：各事実について、現実世界でその事実が有効になった時点（valid_from/valid_to）と、エージェントがそれを知った時点（tx_at）を分けて記録します。そのため、*「3 月 1 日時点で何を信じていましたか？」*と質問できます。
2. 削除せず、後継に置き換える：訂正時には古い事実を閉じ、後継の事実にリンクします。*「訂正する前は何を考えていましたか？」*という質問にも答えられます。
3. 事実ごとの来歴情報：すべてのメモリに、誰が、どこで、いつ話したかを記録します。*「なぜそう信じているのですか？」という質問にも答えられます。「そのセッションの内容をすべて忘れてください」*にも対応できます。

ストレージ層は決定論的です。LLM もネットワークもバックグラウンドデーモンも使いません。通常の SQLite なので、任意のクライアントでファイルを開けます。

ご自身で試す場合：cd examples && npm install && npm run demo

使いどころ（および使わないほうがよい場合）

memharness は正確さを魔法のように向上させるものではなく、その点を正直に示しています。エージェントのメモリが小さく静的で、コンテキストウィンドウに余裕をもって収まるなら、CLAUDE.md ファイル（または履歴をそのままプロンプトに詰め込むだけ）のほうがシンプルです。また、履歴が短い場合は、完全なコンテキストを与えることで、どのような外部メモリシステムにも匹敵するか、それを上回ることができます。

次のような場合は memharness をご検討ください。

• 履歴がウィンドウに収まらなくなる：数か月分の事実や多数の対象があり、すべてのプロンプトに貼り付けるには多すぎる（または不可能な）場合。
• 監査証跡が必要：「この判断をしたとき、エージェントは何を信じていたか？」（as_of）、「月曜日以降に何が変わったか？」（diff）、「なぜこれを信じているのか？」（why）を確認したい場合。こうした質問には、文字列の寄せ集めでは答えられません。
• 来歴情報に基づいた削除が必要：*「そのセッション／ファイル／ソースの内容をすべて忘れて」*という操作を 1 回の呼び出しで行いたい場合（文字列検索ではなく、GDPR を想定した設計です）。
• 信念が時間とともに変化する：訂正は黙って上書きするのではなく、後継に置き換えることで、以前の推論も説明可能な状態に保つ必要がある場合。

比較

memharness が実際に異なる点に焦点を当て、率直に比較します。memharness は情報抽出サービスではなく、決定論的で監査可能なストレージ層です。

	ストレージ	書き込み時の LLM 呼び出し	as_of / diff / why	埋め込み可能 / セルフホスト
memharness	SQLite ファイル 1 つ	なし	はい：二時点管理 + 来歴情報	はい、ライブラリです
mem0	ホスト型 / OSS サービス	はい（抽出パイプライン）	部分的 / なし	部分的
Zep / Graphiti	ホスト型グラフ	はい（LLM による取り込み）	二時点管理。ただし LLM が構築	部分的
Letta / MemGPT	エージェントフレームワーク + DB	はい（エージェントが管理）	なし	はい
Anthropic memory tool	クライアント側のファイル	モデルがファイルを編集	なし（モデルが選択）	はい
通常の CLAUDE.md / ファイル	テキストファイル	なし	なし	はい

他の仕組みが明確に優れている点もあります。mem0 と Zep は会話の生データから事実を自動抽出しますが、memharness は意図的にそれを行いません（書き込み処理はモデルに依存せず、何を記憶する価値があるかはクライアントやスキルが判断します）。通常の CLAUDE.md はインストールすら不要です。memharness が役立つのは、他の仕組みでは提供されない時間や来歴情報に関するクエリが必要な場合です。

パッケージ

パッケージ	内容
@memharness/core	TypeScript ライブラリ：スキーマ、マイグレーション、書き込み処理、リコールのランキング。モデルもネットワークも使用しません。
@memharness/mcp	MCP サーバー（stdio）。7 つのツールをあらゆる MCP クライアントに公開します。
@memharness/embed	オプション。ハイブリッド（セマンティック）リコール用のローカル埋め込みモデルです。デフォルトではインストールされません。

クイックスタート（MCP）

デフォルトのインストールは小規模です（SQLite と MCP SDK）。埋め込みモデルは オプションです。詳しくは［ハイブリッド検索］(#optional-hybrid-recall)をご覧ください。

Claude Code：

claude mcp add memharness -- npx -y @memharness/mcp

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json） および Cursor（~/.cursor/mcp.json）では、同じ JSON 形式を使用します。

{
  "mcpServers": {
    "memharness": { "command": "npx", "args": ["-y", "@memharness/mcp"] }
  }
}

Codex（~/.codex/config.toml）では、JSON ではなく TOML を使用します。

[mcp_servers.memharness]
command = "npx"
args = ["-y", "@memharness/mcp"]

データベースは ~/.memharness/memory.db に保存されます（MEMHARNESS_DB で変更できます。 Linux では XDG_DATA_HOME が尊重されます）。オプションの［デバッグログ］(#optional-local-usage-log)を 有効にしない限り、ほかには何も書き込まれません。

初回実行

1. 上記のコマンドのいずれかを使ってサーバーを追加し、新しい MCP サーバーを 読み込ませるためにクライアントを再起動します。
2. 会話の中で、エージェントに「このプロジェクトは Fly.io でデプロイすることを 覚えておいてください」のような、長期的に保持する事実を伝えます。エージェントは remember を呼び出します。
3. 後で（または新しいセッションで）「私のデプロイ方法について何を知っていますか？」と 尋ねます。エージェントは recall を呼び出し、記憶から回答します。内容を訂正すると、 revise を呼び出します。古い認識は履歴になり、as_of／why／diff で照会できます。

API キーも登録もネットワークも不要です。最初の remember で SQLite ファイルが 作成され、それでセットアップは完了です。エージェントなしでツールの一連の動作を 確認するには、デモを実行します：cd examples && npm install && npm run demo。

オプション：検索を自動化する

デフォルトでは、エージェントが recall を呼び出すタイミングを判断します。モデルが 検索を覚えていることに期待するより確実な方法として、代わりに各セッションの開始時に 関連する記憶を自動的に渡すには、バンドルされている memharness-context ツールを 実行する Claude Code のSessionStart フックを追加します。標準出力はコンテキストに 注入されます。

{
  "hooks": {
    "SessionStart": [
      { "hooks": [ { "type": "command",
        "command": "npx -y -p @memharness/mcp memharness-context --subject user" } ] }
    ]
  }
}

最も関連性の高い現在の認識を簡潔に出力します（まだ何もなければ何も表示せずに終了します）。 そのため、エージェントは各セッションの開始時点で、長期的に保持する事実をすでに把握しています。 複数のエンティティを注入するには、--subject を複数回指定します。

7 つのツール

ツール	機能	検証する考え方
remember	確信度と出典情報を付けて、1 件の事実を保存します	事実 > かたまり
recall	現在の認識を順位付けして返します。as_of では過去の時点における認識を返します	双時制
revise	認識を置き換え、履歴を保持します	置き換え > 削除
diff	日付以降の変更（学習／修正／撤回）を示します	監査デモ
why	事実の出典情報と完全な改訂履歴を示します	信頼／監査
forget	ID または出典（出典情報に基づく削除）で論理削除します	GDPR を意識した設計
stats	件数、対象、スキーマバージョンを示します	—

ライブラリとしての使用

import { Memharness } from "@memharness/core";

const mem = Memharness.open(); // ~/.memharness/memory.db

// Learn something now, then learn it was actually true earlier.
const { id } = mem.remember({
  subject: "user",
  fact: "lives in Osaka",
  sourceRef: "session-2026-06-09",
});
mem.revise({ oldFactId: id, newFact: "lives in Tokyo", validFrom: "2026-05-01" });

mem.recall({ query: "lives" }).facts[0].fact;   // "lives in Tokyo" (current belief)
mem.diff({ since: "2026-06-01" });               // { learned, revised, retracted }
mem.why(id);                                     // { fact, ancestors, descendants }

recall は文字列そのものではなく、RecallResult（{ facts: ScoredFact[]; asOf; truncated; usedFallback }）を返します。asOf は過去の時点を指定します。mem.recall({ query: "lives", asOf: "2026-04-15" }) は、その日付時点で信じられていた内容を返します。 これはトランザクション時刻を考慮するため、今日学習した事実が過去についてのクエリに 表示されることはありません。

検索順位は、FTS5 BM25（［ハイブリッド検索］(#optional-hybrid-recall)が有効な場合は ベクトル順位も含む）による相互順位融合に、確信度と再鮮度の減衰（半減期は 90 日、 変更可能）を掛け合わせて、SQL でスコアリングします。オプションの maxTokens 予算で、 コンテキストウィンドウ向けの出力上限を設定できます。FTS のみのモードとハイブリッド モードのどちらでも、部分的な単語や誤字を拾う部分文字列フォールバックが機能します。

オプション：ハイブリッド検索

デフォルトでは、検索はFTS5キーワード検索に、最新性と確信度による順位付けを組み合わせたものです。モデルは不要で、完全にオフラインで動作します。ハイブリッド検索では、ローカルの埋め込みモデル（BGE-small、約130MB）を使ったセマンティック検索を追加します。モデルはHuggingFace hubから一度ダウンロードされ、その後は完全にオフラインで動作します。APIキーも、クエリごとのネットワーク通信も不要です。次の2つの手順で有効にします。

1. サーバーと一緒にオプションの埋め込みパッケージをインストールします。npxを使う場合：

   npx -y -p @memharness/mcp -p @memharness/embed memharness-mcp
   

   （または、グローバルインストールにはnpm i -g @memharness/embedを使います）。

2. サーバーの環境変数にMEMHARNESS_HYBRID=1を設定します。

すると、サーバーは保存済みのファクトを自動的にベクトル化します。rememberしたファクトは、別途バックフィルの手順を行わなくても、次回のrecallからセマンティック検索の対象になります。初回のハイブリッド検索では、モデルの読み込み中にダウンロードの進行状況がstderrに表示されます。パッケージがインストールされていない場合はその旨を表示し、FTSのみの状態で動作し続けます。フェイルクローズすることはありません。

ライブラリレベルでは、検索は埋め込みプロバイダーに依存しません。任意のモデルで生成したクエリベクトルをrecall({ queryVector })に渡し、ドキュメントのベクトルをsetEmbedding(...)で設定できます。

使用例

数週間離れた2つのセッションです。エージェントが好みを学習し、後でユーザーがそれを訂正します。その後の質問では、エージェントが当時何を信じていたかを尋ねます。

// June 9: the agent learns a deploy target and acts on it.
const { id } = mem.remember({
  subject: "project:acme",
  fact: "deploys via Heroku",
  sourceRef: "session-2026-06-09",
});

// June 16: turns out the team moved to Fly back on June 1.
mem.revise({
  oldFactId: id,
  newFact: "deploys via Fly.io",
  validFrom: "2026-06-01",
  sourceRef: "session-2026-06-16",
});

mem.recall({ subject: "project:acme" }).facts[0].fact; // "deploys via Fly.io"

// "Why did the CI config you wrote on June 9 target Heroku?"
mem.recall({ subject: "project:acme", asOf: "2026-06-09" }).facts[0].fact;
//   "deploys via Heroku": what the agent honestly believed that day.

mem.why(id);   // the full chain: Heroku, superseded by Fly.io, with sources.
mem.diff({ since: "2026-06-15" });  // surfaces the Heroku -> Fly.io revision.

文字列の集合を記憶するだけでは、as_ofの質問に答えられません。Fly.ioを学習した時点で、Herokuを上書きしてしまうためです。

正確性

プロパティテストのスイートは、このプロジェクトの中核です。remember／revise／forgetのランダムなシーケンスに対し、recall({asOf: T})は、イベントログをSQLを使わずに再生する素朴な方法で生成された信念の集合と一致する必要があります。検証は各イベントのタイムスタンプの±1msで行います。mainへのプッシュごとに10,000ケースを実行します。

開発者向けノートPC（Apple Silicon）で、10万件のファクト（改訂チェーンが10％、取り消しが2％）を対象にベンチマークを実施しました。4種類のクエリ形状（2語のキーワード、キーワード＋サブジェクト、サブジェクトのみ、as_of＋キーワード）全体で、検索のp95は約1.3msとなり、予算の10msを下回りました。pnpm benchはデータベースにデータを投入して予算を満たすことを検証するため、この数値は再現可能であり、単なる引用値ではありません。

元のプロトタイプから意図的に変更した点が1つあります。取り消しはフラグではなくタイムスタンプ（retracted_at）を保存します。そのため、取り消し前の時点を指定したas_ofクエリでは履歴を引き続き参照できます。これはプロトタイプのドキュメントで約束されていたものの、SQLでは実現されていなかった動作です。

開発

pnpm install
pnpm test            # unit + behavior suites (property tests at 200 runs)
pnpm test:property   # 10k randomized property cases
pnpm bench           # seed 100k facts, assert recall p95 < 10ms

スキーマのマイグレーションは前方のみで、PRAGMA user_versionによって管理されます。行は削除されず（forgetはトゥームストーンを作成します）、そのためfacts.idは挿入順序も兼ねます。すべてのタイムスタンプは固定幅の標準UTC ISO 8601形式であり、辞書順で時系列に比較できます。

オプション：ローカル使用ログ

デバッグや自身の使用状況の測定には、MEMHARNESS_DEBUG=1を設定します。サーバーは、操作名とタイムスタンプ（ファクトの内容は記録しません）を1行ずつ、データベースの隣にあるusage.logに追記します。デフォルトでは無効で、完全にローカルで動作し、ネットワーク通信は行いません。

ライセンス

Apache-2.0