📜 Litopys

あなたのAIのための生きた記録。

セッションやクライアントをまたいで存続する、永続的なグラフベースのメモリです。 Claude Code、Claude Desktop、およびMCP互換のあらゆるエージェント向けに構築されています。

litopys-dev.github.io/litopys — インストール、スクリーンショット、クイックスタート

🇺🇦 Читати українською

Litopysとは？

現在のAIエージェント向けメモリシステムには、トレードオフが存在します。サブプロセスによるメモリリークや約500MBのRAMを消費する重いベクトルデータベースか、数十件のノートを超えるとスケールしないフラットなMarkdownファイルかの二択です。

Litopysは第3の道を選択しました： プレーンなMarkdownに保存され、軽量なMCPレイヤー（約75MBのRAM）を通じて提供される型付き知識グラフです。手動で編集可能で、キーワードと構造の両方でクエリを実行できます。Litopysはウクライナ語で「年代記」を意味します。まさにAIのメモリとは、AIがあなたについて何を、いつ、なぜ学んだのかという生きた記録であるべきだからです。

Related MCP server: auxly-memory-cli

特徴

• 🧠 型付きグラフ — 6つのノードタイプ（人物、プロジェクト、システム、概念、イベント、レッスン）と11の主要な関係性

• 🔌 MCPネイティブ — Claude Code、Claude Desktop、Cursor、Cline、または任意のMCPクライアントで動作します（docs/integrationsを参照）

• 📝 Markdownファースト — すべてのノードはYAMLフロントマターを含むプレーンな .md ファイルです。手動編集可能で、grep可能、gitによるバージョン管理が可能です

• 🤖 モデル非依存の抽出器 — Anthropic、OpenAI、またはローカルのOllamaを選択可能。リソースやコストの予算に合わせて選べます（以下のリソースフットプリントを参照）。事実は検疫（quarantine）を通るため、未確認の情報が勝手に保存されることはありません

• 🌐 Webダッシュボード — http://localhost:3999 でグラフの閲覧、検索、編集、可視化、検疫の確認が可能です

• 🔐 ローカル完結 — グラフは ~/.litopys/graph/ にファイルとして保存されます。サーバーはデフォルトで 127.0.0.1 にバインドされ、テレメトリは一切ありません

ダッシュボード

スクリーンショットは docs/screenshots/ に同梱されている合成デモグラフに対して撮影されたものであり、著者の個人的なメモではありません。

ステータス

v0.1.2 がリリースされました — Linux / macOS / Windows (x64 + arm64) 用のビルド済みバイナリが利用可能です。SHA-256チェックサムは install.sh で検証されます。v0.1.1安定版に対するセキュリティリリースです。詳細は CHANGELOG を参照してください。公開インターフェース（MCPツール、CLI、JSONエクスポート schemaVersion: 1、ディスク上のMarkdownレイアウト）は固定されており、破壊的変更は 0.2.x としてリリースされます。

コアグラフ、MCPサーバー（5ツール、stdio + HTTP/SSE）、抽出器 + 検疫 + 週次ダイジェスト、タイマーデーモン、ダッシュボード（読み取り + 書き込み + グラフ可視化 + 検疫確認）、アイデンティティ解決のガードレール、シングルバイナリビルド、ワンライナーインストーラー、クライアントごとの統合ドキュメント — すべて実装済みです。今後の予定についてはWhat's nextを参照してください。

リソースフットプリント

著者の環境（Ubuntu, Bun 1.x）での実測値です。MCPサーバーは軽量ですが、抽出器は使用するアダプターによってコストが変わります。

最小の常駐コストはMCPサーバーの約75MBです。抽出はオプションであり、エージェントから読み取り/書き込み専用でLitopysを使用し、デーモンを起動しないことも可能です。抽出を有効にする場合、ローカルのOllamaはRAMを消費し、Anthropic/OpenAIはセッションごとの料金を消費します。Ollamaの keep_alive により、3B/7Bモデルのメモリ消費は一時的なものであり、チック終了後数分でRAMから解放されます。

クイックスタート

ワンライナーインストール（Linux / macOS）:

curl -fsSL https://raw.githubusercontent.com/litopys-dev/litopys/main/install.sh | sh

これにより、約100MBのバイナリが ~/.local/bin/litopys にダウンロードされ、必要なサブディレクトリとともに ~/.litopys/graph/ が初期化され、MCP登録のヒントが表示されます。

特定のバージョンを指定するには、パイプの後に代入を記述します。curl の前に設定された環境変数は curl 自体にのみ適用され、パイプ先のシェルには適用されないためです：

curl -fsSL https://raw.githubusercontent.com/litopys-dev/litopys/main/install.sh | LITOPYS_VERSION=v0.1.2 sh

次に、クライアントにMCPサーバーを登録します：

# Claude Code
claude mcp add litopys -- ~/.local/bin/litopys mcp stdio

// Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "litopys": {
      "command": "/home/you/.local/bin/litopys",
      "args": ["mcp", "stdio"]
    }
  }
}

クライアントを再起動します。litopys://startup-context リソースは、新しいセッションごとにオーナープロファイル、アクティブなプロジェクト、最近のイベント、重要なレッスンを自動的に読み込みます。エージェントは5つのMCPツール（litopys_search、litopys_get、litopys_related、litopys_create、litopys_link）を通じて読み書きを行います。

クライアントごとの詳細なレシピは docs/integrations/ にあります（Claude Code、Claude Desktop、Cursor、Cline、ChatGPT Connectors、Gemini）。

リモート (HTTP/SSE) モード

リモートクライアント（Claude Desktopコネクタ、ブラウザベースのMCPホスト）の場合：

LITOPYS_MCP_TOKEN=your-secret litopys mcp http
# listens on 127.0.0.1:7777 by default
# set LITOPYS_MCP_BIND_ADDR=0.0.0.0 + TLS proxy for remote exposure
# set LITOPYS_MCP_CORS_ORIGIN=https://your-client to enable CORS

開発インストール（ソースから）

git clone https://github.com/litopys-dev/litopys.git
cd litopys
bun install
bun run build:binary       # produces dist/litopys

オプション — 長時間実行されるトランスクリプト用デーモン

cp packages/daemon/systemd/litopys-daemon.{service,timer} ~/.config/systemd/user/
systemctl --user enable --now litopys-daemon.timer

オプション — Webダッシュボードの自動起動

ダッシュボード（litopys viewer）はsystemdユーザーサービスとして実行でき、再起動後に自動的に復帰します。

litopys viewer install        # generates token, writes unit, enables service
litopys viewer install --lan  # same + binds to 0.0.0.0 for LAN access
systemctl --user status litopys-viewer

# Remove:
litopys viewer uninstall

アクセストークン。 viewer install は自動的にランダムなトークンを生成し、~/.litopys/viewer.token に保存します。インストール出力には、トークンが埋め込まれたすぐに使えるURLが表示されます：

✓ litopys-viewer installed

  Open dashboard:    http://localhost:3999/?token=<token>
  Share with others: http://192.168.1.x:3999/?token=<token>   # --lan only

  Opening the link once saves the token — no re-entry needed.
  Retrieve token later: cat ~/.litopys/viewer.token

URLを一度開くとトークンが localStorage に保存され、以降のプロンプトは不要になります。書き込み権限を共有するには、?token=… を含むURLを送信してください。トークンをいつでも取得するには：cat ~/.litopys/viewer.token。

GETエンドポイント（閲覧、検索、グラフ表示）は常に公開されています。変更用エンドポイント（ノードの作成/編集/削除、検疫の承認/拒否）にはトークンが必要です。

または、install.sh 実行時に LITOPYS_ENABLE_VIEWER=1 を設定してインストールの一部として有効にすることもできます。ダッシュボードをログアウト後も維持したい場合は loginctl enable-linger $USER が必要です。

整合性チェック

litopys check           # human-readable report, grouped by error kind
litopys check --json    # { nodeCount, edgeCount, errorCount, errors[] } for CI

グラフ全体を読み込んで解決し、壊れた参照、重複ID、誤った型の関係、解析/検証エラーをフラグ立てします。問題が見つかると非ゼロで終了するため、gitのpre-pushフックやCIステップに組み込むことで、不整合が静かに蓄積されるのを防げます。

グラフのバックアップ

Litopysはすべてを ~/.litopys/graph/ にプレーンなMarkdownとして保存するため、ファイルバージョン管理ツールがそのまま使えます。一般的な2つのアプローチ：

Git + プライベートリモート（増分履歴、オフサイト、無料）：

cd ~/.litopys
git init
git add graph/ .gitignore README.md
git commit -m "baseline"
gh repo create my-litopys-graph --private --source=. --push

以降、セッション終了時のフックや手動承認のたびにワーキングツリーが変更されます。定期的に git add -A && git commit -m "sync" && git push を実行してバックアップを最新に保ってください。グラフには個人的な事実が含まれるため、リモートは必ずプライベートにしてください。

JSONスナップショット（ポータブル、差分可能、ツールフレンドリー）：

litopys export > graph.json              # compact
litopys export --pretty > graph.json     # indented, VCS-friendly
litopys export --no-body > meta.json     # metadata only, strip markdown bodies

ダンプには meta（エクスポート日時、カウント、スキーマバージョン）に加え、ID順にソートされたノードと (from, relation, to) 順にソートされたエッジが含まれます。実行間で決定論的であるため、diff graph-yesterday.json graph-today.json でLLMやデーモンが何を追加したかを正確に把握できます。分析ツールへの入力、ホスト間の移行、コードと一緒にコミットする用途に適しています。

新しいホスト（または再インストール後）でスナップショットから復元：

litopys import graph.json --dry-run   # preview the plan
litopys import graph.json             # create new nodes, skip existing ones
litopys import graph.json --force     # also overwrite existing ids

デフォルトは保守的で、--force を渡さない限り既存のノードは変更されません。すべてのノードは事前にスキーマに対して検証されるため、破損したスナップショットはディスクに書き込まれる前に中止されます。

リリース履歴

CHANGELOG.md を参照してください。今後の作業は実際のユーザーフィードバックに基づいて決定されます。何か問題があればIssueを立ててください。

設計原則

• エージェント非依存。 LLMベンダーやクライアントへの強い依存関係はありません。MCPが唯一の統合ポイントです。Ollamaがデフォルトの抽出器ですが、Anthropic/OpenAIはオプションのアダプターです。

• ポータブルデータ。 グラフはディスク上でプレーンなMarkdown + YAMLフロントマターとして保存されます。どのエディタでも読み取り可能で、gitでバージョン管理でき、シェルからgrep可能です。

• 軽量ランタイム。 MCPサーバーのRAM消費は約75MB。抽出器はプロセス外で実行され、リクエストごとではなくスケジュールに基づいて動作します。アダプターごとのコスト内訳はリソースフットプリントを参照してください。

• オプトイン統合。 クライアント固有のヘルパー（フック、設定スニペット）は docs/integrations/ にあります。これらを使わずにLitopysを利用することも可能です。

ライセンス

MIT © 2026 Denis Blashchytsia and Litopys contributors.