mnemex

CortexGraph：AI のための時間的メモリ

AI アシスタントに人間のような記憶の動態を提供する Model Context Protocol（MCP）サーバーです。記憶は、エビングハウスの忘却曲線を模倣し、使用によって強化されない限り、時間の経過とともに自然に薄れていきます。

メモ

名前とバージョンについて

このプロジェクトは当初 mnemex として開発されていました（PyPI では v0.6.0 まで公開）。2025 年 11 月に Prefrontal Systems に移管され、AI システム向けのより広範な認知アーキテクチャにおける役割をより適切に表すため、CortexGraph に改名されました。

cortexgraph パッケージのバージョン番号は 0.1.0 から開始し、新しい名前での新たなスタートを示しています。同時に、mnemex から引き継いだ成熟した、十分にテストされたコードベース（791 件のテスト、98% 以上のカバレッジ）であることも示しています。mnemex パッケージは PyPI で v0.6.0 のまま更新されません。

このバージョン方式には、次の意図があります。

• cortexgraph を知った PyPI ユーザーに「新しいパッケージ」であることを示す
• 1.0 より前に、ブランド、API、組織への統合を進化させる余地を確保する
• 継続性を保つ。ユーザーは pip install mnemex から pip install cortexgraph に移行できます
• コードは成熟している一方で、cortexgraph というアイデンティティは始まったばかりであることを反映する

重要

🔬 研究成果物 — 本番環境での使用を目的としていません

このソフトウェアは、研究目的の**概念実証（PoC）**であり、リファレンス実装です。認知アーキテクチャと AI セーフティにおける理論的なフレームワーク（特に STOPPER Protocol と CortexGraph）を検証するために存在します。

商用製品ではありません。 一般的な本番環境での使用を想定した保守は行われておらず、互換性を損なう変更が含まれる場合があり、安定性やサポートは保証されません。概念の研究にはご利用いただけますが、本番環境向けの実装はご自身で構築してください。

📖 このプロジェクトを初めてご覧になる方へ： このツールの機能と使い方を簡単に説明した ELI5 ガイドからお読みください。

CortexGraph とは？

CortexGraph は、Claude のような AI アシスタントに人間のような記憶システムを提供します。

課題

Claude とチャットしていると、会話が終わるたびにすべてを忘れてしまいます。「TypeScript が好みです」や「ピーナッツアレルギーがあります」と伝えても、3 日後にはもう一度説明しなければなりません。これは不便で、時間の無駄になります。

CortexGraph ができること

CortexGraph は、人間の記憶のように、AI アシスタントが物事を自然に記憶できるようにします。

• 🧠 大切なことを記憶 — 好み、決定事項、重要な事実
• ⏰ 自然に忘却 — 古くて使われていない情報は、時間の経過とともに薄れていきます（エビングハウスの忘却曲線のように）
• 💪 使うほど強化 — 何かを参照するほど、より長く記憶されます
• 📦 重要なことを永久に保存 — 頻繁に使われる記憶は、長期保存へ昇格します

仕組み（簡易版）

1. 自然に話しかけます - 「すべてのアプリでダークモードを使いたいです」
2. メモリが自動的に保存されます - 特別なコマンドは必要ありません
3. 時間が経過します - 使わないメモリは徐々に薄れていきます
4. もう一度参照します - 「このアプリをダークモードにして」
5. メモリが強化されます - これで、さらに長く残ります
6. 重要なメモリが昇格します - 5 回以上使いましたか？Obsidian の保管庫に永久保存されます

フラッシュカードはありません。明示的な復習もありません。自然な会話だけです。

他との違い

多くのメモリシステムは単純です：

• ❌ 「7 日後に削除」（100 回使ったかどうかは考慮されません）
• ❌ 「直近 100 件を保持」（古いというだけで重要なものまで捨ててしまいます）

CortexGraph は賢く動作します：

• ✅ 新しさ（いつ？）、頻度（どのくらいの頻度で？）、重要度（どれほど重要？）を組み合わせます
• ✅ メモリは人間の記憶のように自然に薄れていきます
• ✅ よく使うメモリは、より長く残ります
• ✅ 重要な項目を「絶対に忘れない」ように設定できます

技術概要

このリポジトリには、次の要素を組み合わせた短期記憶システムの研究、設計、完全な実装が含まれています：

• 認知科学に基づく新しい時間減衰アルゴリズム
• 利用パターンを通じた強化学習
• 作業記憶と永続記憶のための 2 層アーキテクチャ（STM + LTM）
• 自然な LLM 統合のためのスマートなプロンプトパターン
• 人間が読みやすい JSONL による Git 親和性の高いストレージ
• エンティティと関係を備えたナレッジグラフ

モジュール構成

CortexGraph はモジュール式アーキテクチャを採用しています：

• cortexgraph.core：基盤となるアルゴリズム（減衰、類似性、クラスタリング、統合、検索の検証）
• cortexgraph.agents：マルチエージェント統合パイプラインとストレージユーティリティ
• cortexgraph.storage：一括操作に対応した JSONL および SQLite ストレージバックエンド
• cortexgraph.tools：MCP ツールの実装

CortexGraph を選ぶ理由

🔒 プライバシーと透明性

すべてのデータはお使いのマシンにローカル保存されます - クラウドサービス、追跡、データ共有はありません。

• 短期記憶：

  • JSONL（デフォルト）：人間が読みやすく、Git と親和性の高いファイル（~/.config/cortexgraph/jsonl/）
  • SQLite：大規模なデータセットに対応する堅牢なデータベースストレージ（~/.config/cortexgraph/cortexgraph.db）

• 長期記憶：Obsidian 向けに最適化された Markdown ファイル

  • メタデータを含む YAML フロントマター
  • 関連付けのための Wiki リンク
  • 自分で管理できる永続ストレージ

• エクスポート：メモリを Markdown にエクスポートして持ち運べる、組み込みユーティリティ。

データはあなたのものです。特別なツールを使わずに、読み取り、編集、削除、バージョン管理ができます。

コアアルゴリズム

時間減衰スコアリング関数：

$$ \Large \text{score}(t) = (n_{\text{use}})^\beta \cdot e^{-\lambda \cdot \Delta t} \cdot s $$

ここで：

• $\large n_{\text{use}}$ - 使用回数（アクセス回数）
• $\large \beta$（ベータ） - 使用回数に対する劣線形の重み付け（デフォルト：0.6）
• $\large \lambda = \frac{\ln(2)}{t_{1/2}}$（ラムダ） - 減衰定数。半減期で設定します（デフォルト：3 日）
• $\large \Delta t$ - 最終アクセスからの経過時間（秒）
• $\large s$ - 強度パラメーター $\in [0, 2]$（重要度の倍率）

しきい値：

• $\large \tau_{\text{forget}}$（デフォルト 0.05）— スコアがこの値未満の場合、忘却します
• $\large \tau_{\text{promote}}$（デフォルト 0.65）— スコアがこの値以上の場合、昇格します（または 14 日間で $\large n_{\text{use}}\ge5$ の場合）

減衰モデル：

• Power‑Law（デフォルト）：裾が長く、人間の記憶に最も近い保持特性
• Exponential：裾が短く、より早く忘却します
• Two‑Component：初期の急速な忘却と、より長い裾を組み合わせたモデル

パラメーターの詳細、モデルの選択、計算例については、docs/scoring_algorithm.md を参照してください。

チューニングの早見表

• バランス型（デフォルト）
  • 半減期：3 日（λ ≈ 2.67e-6）
  • β = 0.6、τ_forget = 0.05、τ_promote = 0.65、14 日間で use_count≥5
  • 強度：1.0（重要な項目は 1.3～2.0 に引き上げます）
• 高速変化するコンテキスト（一時的なメモ、頻繁な切り替え）
  • 半減期：12～24 時間（λ ≈ 1.60e-5～8.02e-6）
  • β = 0.8～0.9、τ_forget = 0.10～0.15、τ_promote = 0.70～0.75
• 長期保持（研究／アーカイブ）
  • 半減期：7～14 日（λ ≈ 1.15e-6～5.73e-7）
  • β = 0.3～0.5、τ_forget = 0.02～0.05、τ_promote = 0.50～0.60
• 好み／判断を重視するアシスタント
  • 半減期：3～7 日、β = 0.6～0.8
  • 強度のデフォルト値：好みは 1.3～1.5、判断は 1.8～2.0
• 積極的な容量管理
  • τ_forget を 0.08～0.12 に引き上げる、または半減期を短縮します。GC は毎週スケジュールします。
• 環境変数のテンプレート
  • CORTEXGRAPH_DECAY_LAMBDA=2.673e-6, CORTEXGRAPH_DECAY_BETA=0.6
  • CORTEXGRAPH_FORGET_THRESHOLD=0.05, CORTEXGRAPH_PROMOTE_THRESHOLD=0.65
  • CORTEXGRAPH_PROMOTE_USE_COUNT=5, CORTEXGRAPH_PROMOTE_TIME_WINDOW=14

判断のしきい値：

• 忘却：$\text{score} < 0.05$ → メモリーを削除
• 昇格：$\text{score} \geq 0.65$ または 14 日以内に $n_{\text{use}} \geq 5$ → LTM に移動

主な革新点

1. 強化を伴う時間的減衰

従来のキャッシュ（TTL、LRU）とは異なり、Mnemex は新しさ（指数関数的減衰）、頻度（サブリニアな使用回数）、重要度（調整可能な強度）を組み合わせて、メモリーを継続的にスコアリングします。数式についてはコアアルゴリズムを参照してください。これにより、人間の認知に近いメモリーの動態が生まれます。

2. スマートなプロンプトシステム＋自然言語による起動（v0.6.0 以降）

AI アシスタントが自然にメモリーを使うためのパターンが、エンティティの自動抽出と重要度スコアリングによって強化されました。

自動拡充（v0.6.0 の新機能）

メモリーを保存すると、CortexGraph は自動的に以下を行います。

• spaCy NER を使ってエンティティ（人物、テクノロジー、組織）を抽出します
• コンテンツ内のマーカーに基づいて重要度／強度を計算します
• 自然言語のフレーズから保存／想起の意図を検出します

# Before v0.6.0 - manual entity specification
save_memory(content="Use JWT for auth", entities=["JWT", "auth"])

# v0.6.0+ - automatic extraction
save_memory(content="Use JWT for auth")
# Entities auto-extracted: ["jwt", "auth"]
# Strength auto-calculated based on content

自動保存

User: "Remember: I prefer TypeScript over JavaScript"
→ Detected save phrase: "Remember"
→ Automatically saved with:
   - Entities: [typescript, javascript]
   - Strength: 1.5 (importance marker detected)
   - Tags: [preferences, programming]

自動想起

User: "What did I say about TypeScript?"
→ Detected recall phrase: "what did I say about"
→ Automatically searches for TypeScript memories
→ Retrieves preferences and conventions

自動強化

User: "Yes, still using TypeScript"
→ Memory strength increased, decay slowed

判断支援ツール（v0.6.0 以降）

Claude が保存／想起のタイミングを判断するための新しいツールが 2 つあります。

• analyze_message - メモリーに保存する価値のある内容を検出し、エンティティと強度を提案します
• analyze_for_recall - 想起の意図を検出し、検索クエリを提案します

明示的なメモリーコマンドは必要ありません。自然に会話するだけです。

3. 自然な間隔反復

さまざまな文脈で概念が自然に強化される仕組みに着想を得ています（「マズロー効果」――マズローの欲求階層説が歴史、経済学、社会学の授業に登場すると、よりよく記憶できる現象）。

フラッシュカードは不要です。明示的な復習セッションも不要です。自然な会話だけで実現します。

仕組み：

1. 復習優先度の計算 - 「危険ゾーン」（減衰スコア 0.15～0.35）にあるメモリーを最優先します
2. ドメイン横断の検出 - 異なる文脈でメモリーが使用されたことを検出します（タグの Jaccard 類似度 <30%）
3. 自動強化 - メモリーは使用時に自然に強化され、特にドメインをまたいで使用された場合に強化されます
4. ブレンド検索 - 復習候補が検索結果の 30% に表示されます（設定可能）

使用パターン：

User: "Can you help with authentication in my API?"
→ System searches, retrieves JWT preference memory
→ System uses memory to answer question
→ System calls observe_memory_usage with context tags [api, auth, backend]
→ Cross-domain usage detected (original tags: [security, jwt, preferences])
→ Memory automatically reinforced, strength boosted
→ Next search naturally surfaces memories needing review

設定：

CORTEXGRAPH_REVIEW_BLEND_RATIO=0.3           # 30% review candidates in search
CORTEXGRAPH_REVIEW_DANGER_ZONE_MIN=0.15      # Lower bound of danger zone
CORTEXGRAPH_REVIEW_DANGER_ZONE_MAX=0.35      # Upper bound of danger zone
CORTEXGRAPH_AUTO_REINFORCE=true              # Auto-reinforce on observe

自然なメモリー使用を可能にする LLM システムプロンプトのテンプレートについては、docs/prompts/ を参照してください。

4. 2 層アーキテクチャ

graph TD
    STM["<b>Short-Term Memory</b><br/>- JSONL storage<br/>- Temporal decay<br/>- Hours to weeks retention"]
    LTM["<b>LTM (Long-Term Memory)</b><br/>- Markdown files Obsidian<br/>- Permanent storage<br/>- Git version control"]
    
    STM -->|Automatic promotion| LTM
    
    style STM fill:#e1f5ff,stroke:#01579b,stroke-width:2px
    style LTM fill:#f3e5f5,stroke:#4a148c,stroke-width:2px

5. マルチエージェント統合パイプライン

5つの専門エージェントによるメモリの自動メンテナンス：

graph LR
    decay["<b>DecayAnalyzer</b><br/>Find at-risk<br/>memories"]
    cluster["<b>ClusterDetector</b><br/>Find similar<br/>groups"]
    merge["<b>SemanticMerge</b><br/>Combine<br/>similar groups"]
    promote["<b>LTMPromoter</b><br/>Promote<br/>to LTM"]
    relations["<b>RelationshipDiscovery</b><br/>Discover cross-<br/>domain links"]
    
    decay --> cluster
    cluster --> merge
    merge --> promote
    promote --> relations
    relations -.->|feedback| decay
    
    style decay fill:#ffebee,stroke:#b71c1c,stroke-width:2px
    style cluster fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style merge fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style promote fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    style relations fill:#e1f5fe,stroke:#01579b,stroke-width:2px

5つのエージェント：

エージェント	目的
DecayAnalyzer	忘れられるリスクのあるメモリを見つけます（危険ゾーン：0.15-0.35）
ClusterDetector	埋め込みの類似度を使用して、類似するメモリをグループ化します
SemanticMerge	クラスタ化されたメモリを、独自の情報を保持しながらインテリジェントに統合します
LTMPromoter	価値の高いメモリを永続的なObsidianストレージに移動します
RelationshipDiscovery	共通のエンティティを通じて、ドメインをまたぐつながりを見つけます

主な機能：

• ドライランモード：データを変更せずに変更内容をプレビューします
• レート制限：1分あたりの操作数を設定できます（デフォルト：60）
• 監査証跡：すべての判断をbeadsの課題追跡で記録します
• 人による上書き：実行前に判断内容を確認し、承認できます

使用方法：

from cortexgraph.agents import Scheduler

# Preview what would change (dry run)
scheduler = Scheduler(dry_run=True)
preview = scheduler.run_pipeline()

# Run full pipeline
scheduler = Scheduler(dry_run=False)
results = scheduler.run_pipeline()

# Run single agent
decay_results = scheduler.run_agent("decay")

CLI：

# Dry run (preview)
cortexgraph-consolidate --dry-run

# Run specific agent
cortexgraph-consolidate --agent decay --dry-run

# Scheduled execution (with interval)
cortexgraph-consolidate --scheduled --interval-hours 1

設定、beadsとの統合、トラブルシューティングなどの完全なドキュメントについては、docs/agents.mdを参照してください。

クイックスタート

インストール

推奨：UV Tool Install（PyPIから）

# Install from PyPI (recommended - fast, isolated, includes all 7 CLI commands)
uv tool install cortexgraph

これにより、cortexgraphと7つのCLIコマンドすべてが、分離された環境にインストールされます。

その他のインストール方法

# Using pipx (similar isolation to uv)
pipx install cortexgraph

# Using pip (traditional, installs in current environment)
pip install cortexgraph

# From GitHub (latest development version)
uv tool install git+https://github.com/simplemindedbot/cortexgraph.git

開発用（編集可能インストール）

# Clone and install in editable mode
git clone https://github.com/simplemindedbot/cortexgraph.git
cd cortexgraph
uv pip install -e ".[dev]"

設定

重要：設定の保存場所は、インストール方法によって異なります。

方法1：.envファイル（すべてのインストール方法で使用可能）

~/.config/cortexgraph/.envを作成します：

# Create config directory
mkdir -p ~/.config/cortexgraph

# Option A: Copy from cloned repo
cp .env.example ~/.config/cortexgraph/.env

# Option B: Download directly
curl -o ~/.config/cortexgraph/.env https://raw.githubusercontent.com/simplemindedbot/cortexgraph/main/.env.example

~/.config/cortexgraph/.envを編集し、設定を入力します：

# Storage
CORTEXGRAPH_STORAGE_PATH=~/.config/cortexgraph/jsonl

# Decay model (power_law | exponential | two_component)
CORTEXGRAPH_DECAY_MODEL=power_law

# Power-law parameters (default model)
CORTEXGRAPH_PL_ALPHA=1.1
CORTEXGRAPH_PL_HALFLIFE_DAYS=3.0

# Exponential (if selected)
# CORTEXGRAPH_DECAY_LAMBDA=2.673e-6  # 3-day half-life

# Two-component (if selected)
# CORTEXGRAPH_TC_LAMBDA_FAST=1.603e-5  # ~12h
# CORTEXGRAPH_TC_LAMBDA_SLOW=1.147e-6  # ~7d
# CORTEXGRAPH_TC_WEIGHT_FAST=0.7

# Common parameters
CORTEXGRAPH_DECAY_LAMBDA=2.673e-6
CORTEXGRAPH_DECAY_BETA=0.6

# Thresholds
CORTEXGRAPH_FORGET_THRESHOLD=0.05
CORTEXGRAPH_PROMOTE_THRESHOLD=0.65

# Long-term memory (optional)
LTM_VAULT_PATH=~/Documents/Obsidian/Vault

cortexgraphが.envファイルを検索する場所：

1. 優先：~/.config/cortexgraph/.env ← uv tool install / uvxではこちらを使用します
2. フォールバック：./.env（カレントディレクトリ）← 編集可能インストールでのみ動作します

MCPの設定

推奨：絶対パスを使用（どの環境でも動作します）

~/Library/Application Support/Claude/claude_desktop_config.jsonに追加します：

{
  "mcpServers": {
    "cortexgraph": {
      "command": "/Users/yourusername/.local/bin/cortexgraph"
    }
  }
}

実際のパスを確認します：

which cortexgraph
# Example output: /Users/yourusername/.local/bin/cortexgraph

そのパスを設定に使用します。yourusernameを実際のユーザー名に置き換えてください。

絶対パスを使用する理由：Claude DesktopのようなGUIアプリは、シェルのPATH設定（.zshrc、.bashrc）を引き継ぎません。フルパスを使用すると、常に動作するようになります。

開発用（編集可能インストール）：

{
  "mcpServers": {
    "cortexgraph": {
      "command": "uv",
      "args": ["--directory", "/path/to/cortexgraph", "run", "cortexgraph"],
      "env": {"PYTHONPATH": "/path/to/cortexgraph/src"}
    }
  }
}

設定は、プロジェクトディレクトリ内の./.envまたは~/.config/cortexgraph/.envから読み込めます。

トラブルシューティング：コマンドが見つからない

Claude Desktopにspawn cortexgraph ENOENTエラーが表示される場合、cortexgraphコマンドがClaude DesktopのPATHにありません。

macOS/Linux：GUIアプリはシェルのPATHを引き継ぎません

macOSとLinuxのGUIアプリケーションからは、シェルのPATH設定（.zshrc、.bashrcなど）を参照できません。Claude Desktopが検索する場所は次のとおりです。

• /usr/local/bin
• /opt/homebrew/bin（macOS）
• /usr/bin
• /bin
• /usr/sbin
• /sbin

uv tool installによってcortexgraphが~/.local/bin/やその他のカスタム場所に配置されている場合、Claude Desktopは見つけられません。

解決方法：絶対パスを使用する

# Find where cortexgraph is installed
which cortexgraph
# Example output: /Users/username/.local/bin/cortexgraph

Claudeの設定を絶対パスで更新します：

{
  "mcpServers": {
    "cortexgraph": {
      "command": "/Users/username/.local/bin/cortexgraph"
    }
  }
}

/Users/username/.local/bin/cortexgraphを、which cortexgraphで確認した実際のパスに置き換えてください。

メンテナンス

メンテナンスCLIを使って、JSONLストレージを検査および圧縮します：

# Show storage stats (active counts, file sizes, compaction hints)
cortexgraph-maintenance stats

# Compact JSONL (rewrite without tombstones/duplicates)
cortexgraph-maintenance compact

UV Tool Installへの移行

現在、編集可能インストール（uv pip install -e .）を使用している場合は、より簡単なUV Tool Installに切り替えられます：

# 1. Uninstall editable version
uv pip uninstall cortexgraph

# 2. Install as UV tool
uv tool install git+https://github.com/simplemindedbot/cortexgraph.git

# 3. Update Claude Desktop config to just:
#    {"command": "cortexgraph"}
#    Remove the --directory, run, and PYTHONPATH settings

データは安全です！ 変更されるのは、コマンドのインストール方法だけです。~/.config/cortexgraph/内のメモリには影響しません。

CLIコマンド

このサーバーには、7つのコマンドラインツールが含まれています：

cortexgraph                  # Run MCP server
cortexgraph-migrate          # Migrate from old STM setup
cortexgraph-index-ltm        # Index Obsidian vault
cortexgraph-backup           # Git backup operations
cortexgraph-vault            # Vault markdown operations
cortexgraph-search           # Unified STM+LTM search
cortexgraph-maintenance      # JSONL storage stats and compaction

可視化

PyVis を使用したインタラクティブなグラフ可視化：

# Install visualization dependencies
pip install "cortexgraph[visualization]"
# or with uv
uv pip install "cortexgraph[visualization]"

# Or install dependencies manually
pip install pyvis networkx

# Generate interactive HTML visualization
python scripts/visualize_graph.py

# Custom output location
python scripts/visualize_graph.py --output ~/Desktop/memory_graph.html

# Custom data paths
python scripts/visualize_graph.py --memories ~/data/memories.jsonl --relations ~/data/relations.jsonl

機能：

• パン／ズームに対応したインタラクティブなネットワークグラフ
• ステータスに応じたノードの色分け（active＝青、promoted＝緑、archived＝灰色）
• 使用回数に基づくノードサイズ
• 関係の種類に応じたエッジの色分け
• 全文、タグ、エンティティを表示するホバーツールチップ
• レイアウトを調整する物理演算コントロール

可視化機能は JSONL ファイルを直接読み込み、任意のブラウザーで開けるスタンドアロンの HTML ファイルを作成します。

MCP ツール

AI アシスタントがメモリを管理するための13個のツール：

ツール	用途
save_memory	タグとエンティティを付けて新しいメモリを保存（v0.6.0以降は自動拡張）
search_memory	フィルターとスコアリングを使って検索（レビュー候補を含む）
search_unified	STM と LTM を横断した統合検索
touch_memory	メモリを強化（強度を上げる）
observe_memory_usage	自然な間隔反復のためにメモリの使用状況を記録
analyze_message	✨ NEW v0.6.0 - メモリに値する内容を検出し、エンティティ／強度を提案
analyze_for_recall	✨ NEW v0.6.0 - 想起の意図を検出し、検索クエリを提案
gc	スコアの低いメモリをガベージコレクション
promote_memory	長期ストレージへ移動
cluster_memories	類似したメモリを検索
consolidate_memories	類似したメモリを統合（アルゴリズムによる処理）
read_graph	ナレッジグラフ全体を取得
open_memories	指定したメモリを取得
create_relation	メモリ間の関係を明示的に作成

例：統合検索

CLI を使って STM と LTM を横断検索します：

cortexgraph-search "typescript preferences" --tags preferences --limit 5 --verbose

例：メモリの強化（タッチ）

メモリの新しさ／使用回数を増やし、減衰を遅らせます：

{
  "memory_id": "mem-123",
  "boost_strength": true
}

応答例：

{
  "success": true,
  "memory_id": "mem-123",
  "old_score": 0.41,
  "new_score": 0.78,
  "use_count": 5,
  "strength": 1.1
}

例：メモリの昇格

価値の高いメモリを提案し、Obsidian ボルトへ昇格します。

自動検出（ドライラン）：

{
  "auto_detect": true,
  "dry_run": true
}

特定のメモリを昇格：

{
  "memory_id": "mem-123",
  "dry_run": false,
  "target": "obsidian"
}

MCP ツールとして使用（リクエスト本文）：

{
  "query": "typescript preferences",
  "tags": ["preferences"],
  "limit": 5,
  "verbose": true
}

例：類似メモリの統合

重複または非常に類似したメモリを検索・統合し、乱雑さを軽減します：

候補を自動検出（プレビュー）：

{
  "auto_detect": true,
  "mode": "preview",
  "cohesion_threshold": 0.75
}

検出されたクラスターに統合を適用：

{
  "auto_detect": true,
  "mode": "apply",
  "cohesion_threshold": 0.80
}

このツールは次の処理を行います：

• 内容を適切に統合します（一意の情報を保持）
• タグとエンティティを結合します（和集合）
• クラスターの凝集度に基づいて強度を算出します
• 最も古い created_at と最新の last_used のタイムスタンプを保持します
• 統合履歴を示す追跡用の関係を作成します

数学的詳細

減衰曲線

$n_{\text{use}}=1$、$s=1.0$、$\lambda = 2.673 \times 10^{-6}$（半減期3日）のメモリの場合：

時間	スコア	状態
0時間	1.000	新鮮
12時間	0.917	アクティブ
1日	0.841	アクティブ
3日	0.500	半減期
7日	0.210	減衰中
14日	0.044	忘却寸前
30日	0.001	忘却済み

使用回数の影響

$\beta = 0.6$（劣線形の重み付け）の場合：

使用回数	ブースト係数
1	1.0×
5	2.6×
10	4.0×
50	11.4×

頻繁にアクセスすると、保持期間が大幅に延びます。

ドキュメント

• MCP ツールリファレンス - 18個すべての MCP ツールに関する包括的なドキュメント
• API クイックリファレンス - 最小限のツールシグネチャと使用例
• スコアリングアルゴリズム - LaTeX 数式を含む完全な数学モデル
• スマートプロンプト - LLM を自然に統合するためのパターン
• アーキテクチャ - システム設計と実装
• マルチエージェントシステム - 統合エージェントとパイプラインアーキテクチャ
• Bear 連携 - Bear アプリを LTM ストアとして使用する方法
• グラフ機能 - ナレッジグラフの使用方法

ユースケース

パーソナルアシスタント（バランス型）

• 半減期3日
• 好みや決定事項を記憶
• 頻繁に参照される情報を自動昇格

開発環境（積極的）

• 半減期：1日
• コンテキストをすばやく切り替えます
• 古いコンテキストを積極的に忘却します

研究／アーカイブ（保守的）

• 半減期：14日
• 長期保持
• 包括的に知識を保存します

ライセンス

AGPL-3.0 ライセンス - 詳細は LICENSE を参照してください。

このプロジェクトでは GNU Affero General Public License v3.0 を使用しています。このライセンスでは、ネットワークサービスの提供にこのソフトウェアを使用する場合、ソフトウェアへの変更をソースコードとして公開する必要があります。

関連プロジェクト

• Model Context Protocol - MCP 仕様
• Ebbinghaus Forgetting Curve - 認知科学の基礎
• Basic Memory - 統合レイヤーの主な着想元です。CortexGraph は、エビングハウスの忘却曲線、時間減衰アルゴリズム、JSONL ストレージによる短期記憶、自然な間隔反復を追加し、この概念を拡張しています。
• そのほか、mem0、Neo4j Graph Memory に着想を得た研究

引用

この成果を研究で使用する場合は、以下のとおり引用してください。

@software{cortexgraph_2025,
  title = {Mnemex: Temporal Memory for AI},
  author = {simplemindedbot},
  year = {2025},
  url = {https://github.com/simplemindedbot/cortexgraph},
  version = {0.5.3}
}

貢献

貢献を歓迎します！詳しい手順は CONTRIBUTING.md を参照してください。

🚨 Windows と Linux のテスターを募集中です！

私は macOS で開発しているため、Windows と Linux でのテストにご協力いただける方を探しています。これらのプラットフォームをお使いの場合は、以下をお願いします。

• インストール手順を試す
• テストスイートを実行する
• 動作する点と動作しない点を報告する

詳細は CONTRIBUTING.md の ご協力のお願いのセクション を参照してください。

一般的な貢献

すべてのコントリビューター向けの情報は、CONTRIBUTING.md を参照してください。

• プラットフォームごとのセットアップ（Windows、Linux、macOS）
• 開発ワークフロー
• テストガイドライン
• コードスタイルの要件
• プルリクエストの手順

クイックスタート：

1. プラットフォームごとのセットアップについて、CONTRIBUTING.md を読む
2. アーキテクチャのドキュメントを確認する
3. スコアリングアルゴリズムを確認する
4. 既存のコードパターンに従う
5. 新機能のテストを追加する
6. ドキュメントを更新する

ステータス

バージョン： 1.0.0 ステータス： 研究実装 — 機能しますが、開発中です

フェーズ 1（完了）✅

• 14 個の MCP ツール
• 時間減衰アルゴリズム
• ナレッジグラフ

フェーズ 2（完了）✅

• JSONL ストレージ
• LTM インデックス
• Git 統合
• スマートプロンプトのドキュメント
• メンテナンス CLI
• メモリの統合（アルゴリズムによるマージ）

フェーズ 3（完了）✅

• マルチエージェント統合パイプライン
  • DecayAnalyzer、ClusterDetector、SemanticMerge、LTMPromoter、RelationshipDiscovery
  • オーケストレーション用スケジューラー
  • Beads イシュートラッキングとの統合
  • ドライランとレート制限に対応
• 自然言語による起動（v0.6.0 以降）
• エンティティ抽出の自動拡充

今後の作業

• 適応型減衰パラメーター
• パフォーマンスベンチマーク
• LLM による統合支援（任意の拡張機能）

---

開発に使用：Claude Code 🤖