nan-forget

NaN Forget

AI コーディングツール向けの長期記憶。

セッションが終了すると、AI はすべてを忘れてしまいます。NaN Forget はそれを解決します。

---

インストール（3 ステップ）

npx nan-forget setup

これで完了です。ウィザードが Ollama、埋め込み、Claude フック、MCP 設定、そして Codex スタイルのエージェント向けプロジェクト AGENTS.md をインストールします。Claude Code を再起動するか、Codex を開き直してください。これで AI が記憶できるようになります。

API キーは不要です。Docker も不要です。ローカルで動作します。ずっと無料です。

---

仕組み

flowchart LR
    A["You talk to your AI tool"] --> B["It learns things"]
    B --> C["nan-forget saves to SQLite"]
    C --> D["Session ends"]
    D --> E["New session starts"]
    E --> F["nan-forget loads context"]
    F --> G["Your AI remembers"]

1. 通常どおり作業します。 作業を進める中で、エージェントが判断、好み、事実をローカルの SQLite メモリデータベースに保存します。
2. セッションが終了します。 記憶は ~/.nan-forget/memories.db に保持されます。古くなった記憶は自動的に長期エントリーへと統合されます。
3. 新しいセッションが始まります。 nan-forget が過去のセッションからコンテキストを読み込みます。3 か月前にプロジェクト A で行った認証の判断が、今日プロジェクト B で作業するときに呼び起こされます。

---

自動メモリ処理

手動で保存や検索を行う必要はありません。裏側では次の処理が行われます。

Claude Code（完全自動）

イベント	実行されるもの	処理内容
セッション開始	memory_sync	軽量なハンドシェイクです。状態を確認し、統計を読み込み、プロジェクトを一覧表示します。負荷の高い検索は行いません。
メッセージ送信	UserPromptSubmit フック	nan-forget recall が関連するコンテキストをメモリから自動検索し、会話に挿入します。
トピックについて話し合う	memory_search	関連するコンテキストが存在する可能性があるとき、Claude は必要に応じてデータベースを動的に検索します。必要なときに記憶を呼び起こす方法と同じです。
Claude が何かを学ぶ	memory_save	Claude は判断、好み、事実をすぐに保存します。ツールの説明で「必ず呼び出す」よう Claude に指示します。
Claude が .md ファイルを書き込む	PostToolUse フック	memory-sync.js が書き込みを捕捉し、フロントマターを解析して、nan-forget add を介して SQLite に自動保存します。
セッション終了	SessionEnd フック	session-end.js が会話のトランスクリプトを調べ、未保存の判断や事実を見つけて、上位 5 件をデータベースに保存します。
10 回保存するごと、または 24 時間ごと	自動統合	古くなった記憶をクラスタリングし、長期エントリーに統合します。元の記憶はアーカイブされます。

記憶を失わないよう、4 層の保護を設けています。

1. すべてのメッセージで自動的に記憶を呼び出す（UserPromptSubmit フック）
2. Claude が先回りして保存する（指示を含むツールの説明）
3. フックが .md の書き込みを捕捉する（PostToolUse による捕捉）
4. セッション終了時の確認（SessionEnd によるトランスクリプトのスキャン）

Codex、Cursor、その他のツール

Codex などのエージェントは nan-forget と適切に連携しますが、通常は Claude のフックモデルではなく、指示ファイルまたはシェル／API による代替手段が必要です。

1. セットアップを実行します：npx nan-forget setup
2. リポジトリに生成された AGENTS.md を使用します。 Codex スタイルのエージェントに、sync、search、save、checkpoint を自動的に実行するよう指示します。
3. 会話中に REST または CLI の代替手段を使用します。 エージェントは localhost:3456 の REST API や、nan-forget sync、nan-forget search、nan-forget add、nan-forget checkpoint などのローカルコマンドを呼び出せます。

REST API と CLI は、Claude が保存した記憶を Codex から、またその逆からも検索できるよう、重要なメモリワークフローを十分に反映しています。

# Start the REST API
nan-forget api

# The system prompt tells your agent exactly what endpoints to call
nan-forget prompt

---

スラッシュコマンド

Claude Code で次のコマンドを入力します。

コマンド	処理内容
/nan-forget	過去のセッションからコンテキストを読み込む
/nan-forget stats	メモリの状態を表示する
/nan-forget clean	ガベージコレクションを実行する
/nan-forget compact	メモリの統合を強制的に実行する
/nan-forget health	サービスが稼働しているか確認する
/nan-forget start	すべてのサービスを起動する

---

あらゆる LLM に対応

Claude は MCP を使用します。Codex は AGENTS.md と CLI／REST による代替手段を使用できます。

# Start the API
nan-forget api

# Get the system prompt for your agent
nan-forget prompt

Codex、Cursor、Claude はすべて、同じメモリデータベースを共有します。

curl http://localhost:3456/memories/search?q=auth
curl -X POST http://localhost:3456/memories/sync -d '{"project":"my-app"}'
curl -X POST http://localhost:3456/memories/checkpoint \
  -H 'content-type: application/json' \
  -d '{"task_summary":"Fixed auth regression","problem":"Expired tokens were not refreshed","solution":"Added refresh handling in middleware","files":["src/auth.ts"],"concepts":["auth","jwt"],"project":"my-app"}'

---

クイックスタート（CLI）

nan-forget add "We use FastAPI, not Django. Railway deploys faster."
nan-forget add --type decision "Auth is Clerk, not custom JWT"
nan-forget search "what auth system"
nan-forget stats

---

アーキテクチャ（エキスパート向け）

以下はすべて、nan-forget の内部の仕組みを理解したい開発者向けです。

---

問題

LLM にはセッション間の記憶がありません。会話のたびにゼロから始まります。技術スタックを毎回説明し直し、Claude は先月決めた方針と矛盾することを言い、セッションが終了するとコンテキストが消えてしまいます。

既存のソリューション（Mem0）は、メモリを製品に組み込むアプリ開発者を対象としています。私たちが対象とするのは、AI ツールを毎日使い、ただ覚えていてくれる AI を求めているあなた、つまり開発者です。

設計：脳に着想を得た2層メモリ

flowchart TB
    subgraph Short["Short-Term Memory"]
        MD[".md files<br/>Current session context<br/>Disposable scratch paper"]
    end
    subgraph Long["Long-Term Memory"]
        DB["SQLite + sqlite-vec<br/>~/.nan-forget/memories.db<br/>Semantic search + decay"]
    end
    subgraph Auto["Automatic Processes"]
        Hook["Hooks (3)<br/>PostToolUse: .md → DB<br/>UserPromptSubmit: auto-recall<br/>SessionEnd: transcript sweep"]
        Consolidate["Consolidation Engine<br/>Clusters + summarizes aging memories"]
        GC["Garbage Collection<br/>Decay, dedup, expiry"]
    end
    MD -->|"hook intercepts"| Hook
    Hook -->|"nan-forget add"| DB
    DB --> Consolidate
    Consolidate --> DB
    DB --> GC

短期メモリ = Claude に組み込まれている .md ファイルです。使い捨てで、現在のセッションのみを対象とします。

長期メモリ = sqlite-vec のベクトル検索を備えた SQLite データベースです。単一のファイルで、永続的に保存されます。すべてのセッション、すべてのプロジェクト、すべての LLM ツールを横断して検索できます。

3つのフックがメモリを自動的に処理します。

• PostToolUse は .md ファイルへの書き込みを検知し、DB に保存します。
• UserPromptSubmit はユーザーのメッセージごとに nan-forget recall を実行し、関連するコンテキストをメモリから自動検索します。
• SessionEnd は会話のトランスクリプトをスキャンして未保存の決定事項を探し、上位5件を保存します。

3段階の検索パイプライン

メモリ検索は、人間の想起と同じ流れに従います。

flowchart LR
    Q["Query"] --> S1["Stage 1: Recognition<br/>Fast vector match<br/>Returns summaries only"]
    S1 --> S2["Stage 2: Recall<br/>Full content fetch<br/>Cross-project expansion"]
    S2 --> S3["Stage 3: Association<br/>Spreading activation<br/>Related memories surface"]
    S3 --> R["Results ranked by<br/>similarity x decay x frequency x confidence"]

段階	処理内容	コスト
認識（ぼんやり）	50件の候補を事前取得し、上位5件の要約を返します。低コストです。	ベクトル検索1回
想起（明瞭）	全文を取得します。検索範囲をプロジェクト横断に拡大します（プロジェクトのフィルターなし）。	N件のポイント検索
連想	sqlite-vec で重心ベースの関連メモリ検索を行います。正の ID を起点に活性化を広げます。	ベクトル検索1回

スコアリング式：

final_score = vector_similarity * decay_weight * frequency_boost * confidence_boost
decay_weight = (0.5 ^ (days / 30)) ^ (1 - confidence)
frequency_boost = log2(access_count + 1) / 10 + 1
confidence_boost = 0.5 + 0.5 * confidence

信頼度の高いメモリ（議論で検証済み、人間が承認済み）は、減衰が大幅に遅く、上位にランクされます。信頼度0.85のコアメモリは通常の約15％の速度で減衰するため、置き換えられない限り事実上永続します。プロジェクト横断検索により、プロジェクトAでの認証に関する決定事項が、プロジェクトBで作業するときにも表示されます。

統合エンジン

古くなったメモリは削除されるだけではなく、長期エントリにまとめられます。

flowchart TB
    A["10+ aging memories<br/>about the same topic"] --> B["Cluster by project + type<br/>+ vector similarity > 0.8"]
    B --> C{"OpenAI key<br/>available?"}
    C -->|"Yes"| D["LLM summarizes cluster<br/>into 1-2 sentences"]
    C -->|"No"| E["Deterministic merge<br/>concatenate + deduplicate"]
    D --> F["Save consolidated entry<br/>with fresh vector embedding"]
    E --> F
    F --> G["Archive originals<br/>with backlink"]

保存が10回行われるごと、または24時間ごとに自動的に起動します。 ユーザーによる操作は不要です。

13個の MCP ツール

ツール	用途
memory_sync	軽量なセッションハンドシェイク：ヘルスチェック＋統計＋プロジェクト一覧
memory_save	メモリを保存します（Claude が自発的に自動呼び出し）
memory_search	3段階の検索によるセマンティック検索（深度1～3）
memory_get	ID を指定して特定のメモリを取得します
memory_update	内容、種類、タグを変更します
memory_archive	論理削除します（検索結果には表示されませんが、完全には削除されません）
memory_consolidate	古くなったメモリの統合を強制実行します
memory_clean	ガベージコレクションを実行します（減衰、重複排除、期限切れ、MEMORY.md の同期）
memory_stats	メモリのヘルスダッシュボード
memory_health	Ollama、REST API が稼働しているか確認します
memory_start	Ollama ＋ REST API を起動します
memory_checkpoint	タスクの完了後に、問題から解決策までのコンテキスト全体を保存します
memory_compress	永続化された .md メモリファイルを最小限のスタブに圧縮します

構造化メモリ

memory_save は、ベクトル表現をより豊かにするための構造化フィールドを受け付けます。

フィールド	型	用途
content	string	説明全文（必須）
type	string	fact、decision、preference、task、context
project	string	プロジェクト名
problem	string	どのような課題だったか
solution	string	どのように解決したか
concepts	string[]	検索可能なタグ（["auth", "jwt", "middleware"]）
files	string[]	関連するファイル（["src/auth.ts"]）
confidence	number	信頼レベル 0.0～1.0（デフォルト値は情報源に基づいて設定）
provenance	string	save、checkpoint、debate、human
tier	string	regular または core（情報源に基づいて自動判定）

すべてのフィールドは、単一のベクトルにまとめて埋め込まれます。「JWT auth bug」を検索すると、本文にその語句が文字どおり含まれていなくても、それらの概念がタグ付けされたメモリが見つかります。

メモリ階層

すべてのメモリが同等というわけではありません。議論で検証され、人間が承認したメモリはコアです。減衰が遅く、検索時の順位が高く、ガベージコレクション後も長く保持されます。

出所	デフォルトの信頼度	自動階層	減衰率
save	0.5	通常	標準（半減期30日）
checkpoint	0.65	通常	約35％遅い
debate	0.85	コア	約85％遅い
human	0.95	コア	約95％遅い

コアメモリは、今後導入予定のnan-debateシステム向けに設計されています。人間の承認によって検証された複数AIによる議論の結果は、ほとんど失われることのない、信頼性の高い知識として永続化されます。

チェックポイントのワークフロー

タスクを完了したら、task_summary、problem、solution、files、concepts、projectを指定してmemory_checkpointを呼び出します。問題から解決策に至るまでのコンテキスト全体が長期メモリに保存されます。完了したタスクごとに、チェックポイントを1つ作成します。

メモリの圧縮

memory_compressは、.claude/projects/*/memory/内にある、すでにDBに永続化された.mdファイルをスキャンします。永続化済みのファイルは、最小限のスタブに置き換えられます。これにより、コンテキストウィンドウの肥大化を抑えます。

REST API（MCP 以外の LLM 向け）

MCP サーバーと同じSQLiteデータベースを共有するため、Claudeが保存したメモリはCodexからも検索でき、その逆も可能です。

POST   /memories              — Save a memory (supports problem/solution/files/concepts)
POST   /memories/checkpoint   — Save completed-task context
POST   /memories/sync         — Lightweight session handshake
GET    /memories/search?q=... — Semantic search
GET    /memories/:id          — Get by ID
PATCH  /memories/:id          — Update
DELETE /memories/:id          — Archive
POST   /memories/consolidate  — Compact aging memories
POST   /memories/clean        — Garbage collection
GET    /memories/stats        — Memory health
GET    /memories/instructions — System prompt for LLMs

任意のLLM向けのシステムプロンプトを取得します。

nan-forget prompt
# or
curl http://localhost:3456/memories/instructions

埋め込み

プロバイダー	モデル	次元数	コスト
Ollama（デフォルト）	nomic-embed-text	768	無料、ローカル
OpenAI	text-embedding-3-small	1536	ご自身のAPIキー

自動検出：Ollamaが起動中なら使用します。起動していない場合は、OPENAI_API_KEYを確認します。設定は不要です。

データストレージ

すべてのデータは、~/.nan-forget/memories.dbにある1つのSQLiteファイルに保存されます。Dockerやサービスは不要で、アップデートによるデータ損失もありません。

• ベクトル検索：sqlite-vec拡張機能（コサイン距離、プロセス内に組み込み）
• メタデータ：user_id、status、project、typeにインデックスを設定した標準SQLテーブル
• バックアップ：ファイルを1つコピーします。復元：ファイルを元の場所に戻します。
• エクスポート：nan-forget exportですべてのメモリをJSONとして出力します。

メモリのライフサイクル

flowchart TB
    A["New memory saved"] --> B["Active in SQLite<br/>Searchable, scored"]
    B --> C{"Accessed<br/>recently?"}
    C -->|"Yes"| D["Score stays high<br/>frequency_boost increases"]
    C -->|"No"| E["Decay weight drops<br/>0.5^(days/30)"]
    E --> F{"Decay < 0.3?"}
    F -->|"Yes"| G["Consolidation candidate<br/>Clustered + summarized"]
    F -->|"No"| B
    G --> H["New consolidated entry<br/>Originals archived"]
    D --> B
    E --> I{"Decay < 0.1?"}
    I -->|"Yes"| J["Archived by GC"]
    I -->|"No"| F

ガベージコレクション（LLMコストゼロ）

クリーンアップはすべて決定論的に行われます。API呼び出しはなく、LLM推論も行いません。

• 減衰GC：減衰ウェイトが0.1未満のメモリをアーカイブします（通常は約100日、コアは約600日以上）
• 有効期限：expires_atの日付を過ぎたメモリをアーカイブします
• 干渉の解決：類似度が0.95を超える一致を重複排除し、アクセス回数の多い方を残します
• MEMORY.mdの同期：プロジェクトごとに、スコア上位5件のメモリでワーキングメモリを更新します

コアメモリ（信頼度 ≥ 0.85）は、減衰式で時間要因が抑制されるため、通常のメモリよりはるかに長くGCを生き延びます：decay^(1 - confidence)。信頼度0.85のメモリは、200日経過しても減衰ウェイトが0.1を上回ります。

設計理念

NaN Forgetは、軽量、自動、ローカルという3つの原則を中心に構築されています。

軽量

Dockerは不要です。クラウドサービスも、RAMを消費するバックグラウンドプロセスもありません。ストレージ層全体は、1つのSQLiteファイル（約3 MB）です。埋め込みには、すでに利用している可能性の高いOllamaを使用します。メモリ操作（保存、検索、重複排除、GC）ではLLM呼び出しを一切使わず、すべて決定論的に処理されます。

自動

4つのフックがセッションの各段階でコンテキストを取得するため、手動で保存を呼び出す必要はありません。

1. UserPromptSubmit：メッセージを送信するたびにメモリを検索します
2. ツールの説明：決定事項や事実が生じた時点で保存するようClaudeに指示します
3. PostToolUse：.mdファイルへの書き込みを検知して永続化します
4. SessionEnd：見落とした内容がないか、トランスクリプトを確認します

古くなったメモリは自動的に統合されます。重複はマージされます。使われていないメモリは、半減期30日で減衰します。メンテナンスは不要です。

ローカル

データは ~/.nan-forget/memories.db に保存され、マシンの外に出ることはありません。アカウントも API キーも不要です（Ollama は無料でローカルに動作します）。テレメトリーもありません。バックアップはファイルを 1 つコピーするだけです。Claude Code（MCP）、Codex/Cursor（REST API）、ターミナル（CLI）で動作し、同じデータベースと同じメモリーを使用します。

他のメモリーツールとの違い

多くの AI メモリーソリューション（Mem0、claude-mem）は、製品にメモリー機能を組み込むアプリ開発者向けに設計されているか、実行に Docker やクラウドサービスが必要です。NaN Forget は、インフラストラクチャを管理することなく、セッションをまたいでコンテキストを維持したい、AI ツールを毎日使うあなたのために設計されています。

設計上の主な違いは次のとおりです。

• 検索：単純なベクトル検索ではなく、減衰率を加味したスコアリングを用いる 3 段階のパイプライン（認識 → 想起 → 拡散活性化）
• 構造：メモリーには problem、solution、concepts、files の各フィールドが含まれるため、キーワードが一致しなくても関連するコンテキストを検索できます
• コスト：メモリー操作（保存、検索、重複排除、統合、GC）はすべて決定論的で、LLM の呼び出しも API コストもありません
• セットアップ：コマンド 1 つ（npx nan-forget setup）で完了します。Docker、コンテナー、管理が必要なサービスはありません

ソース構成

src/
  sqlite.ts         SQLite + sqlite-vec storage layer (schema, CRUD, vector search)
  embeddings.ts     OpenAI / Ollama abstraction
  writer.ts         Memory writer with dedup (>0.92 = merge)
  retriever.ts      Three-stage retrieval pipeline
  consolidator.ts   LLM summarization + deterministic fallback
  cleaner.ts        GC: decay, expiry, dedup, MEMORY.md sync
  services.ts       Service management (Ollama, REST API)
  memory-md.ts      MEMORY.md manager
  types.ts          Shared types (Memory, MemoryType, etc.)
  mcp/server.ts     MCP server, 13 tools
  api/server.ts     REST API server
  cli/index.ts      CLI commands + hook helpers
  setup/index.ts    Setup wizard (Ollama, hooks, MCP config)

.claude/
  commands/nan-forget.md   Slash command for manual control
  hooks/memory-sync.js     PostToolUse hook (auto-saves .md → SQLite)
  hooks/session-end.js     SessionEnd hook (transcript sweep for unsaved memories)
  settings.json            Hook config (PostToolUse + SessionEnd + UserPromptSubmit)

---

NaN Logic LLC による開発

• NaN Mesh — AI エージェントのための信頼ネットワーク
• NaN Forget — あらゆる LLM に対応する長期メモリー

MIT ライセンス。