# N3MemoryCore (N3MC)
> A NeuralNexusNote™ product

🛡️ AI-Native Development Policy
本プロジェクトは静的コードよりも指示書を優先します。AIに実行環境を生成させる理由については [開発理念](./PHILOSOPHY.md) をご覧ください。

> 🇺🇸 **[Click here for the English Documentation](./README.md)**
> 🛡️ **[開発理念 & AI-Native Policy](./PHILOSOPHY.md)**

> Java や C# は読めますが、Python はまったく触ったことがありませんでした。
> Claude Codeが作ったコードを、理解しきれないまま完成させました。
>
> それでも、動作確認をして、指示書を直して、また作り直して、
> 日本語版と英語版、Free版とPro版、全部完成させました。
>
> コードが書けなくても、使えるものを作りたい人のために。
>
> 最初の指示書を書いたのは Copilot です。
> Claude Code がコードに変え、Gemini がレビューしました。
> 3つの AI を渡り歩きながら育てた指示書、それが N3MemoryCore です。

N3MemoryCoreは、Claude Codeに長期記憶を与える仕組みです。
**2 つの導入経路をサポート**: 仕様書を Claude Code に渡して実装させるか、`pip install` でリファレンス実装をそのまま使い `n3mc --init` を実行するか。どちらの経路でもフック設定は手動編集不要です。（詳細は[セットアップ](#セットアップ)参照）

---

## 特徴

- 💾 **完全ローカル** — 会話データは自分のPCに保存。クラウドに送りません
- 🔍 **意味で検索** — キーワードが違っても、関連する過去の会話を引き出します。デフォルトで多言語対応（`intfloat/multilingual-e5-base`）— 日本語・英語・中国語・韓国語など約 100 言語に箱出しで対応します。単一言語で高精度を出したい場合は `config.json` で言語特化モデルへ差し替え可能
- 🔄 **セッションをまたいで記憶** — 翌日開いても、先週の続きから話せます
- ⚡ **自動で動く** — 保存も検索もすべて自動。ユーザーの指示は不要です
- 🤖 **マルチエージェント対応** — 複数のAIエージェントが1つの記憶DBを共有。自分の記憶を優先しつつ、他のエージェントの知識も検索できます
- 🏢 **チーム・組織にも対応** — サーバーをネットワークに配置すれば、チーム全員で記憶を共有できます
- 🔗 **DB統合が可能** — 同じ指示書から構築したDBは完全互換。引継ぎ時のナレッジ移行や、他の環境で蓄積した記憶の取り込みがシームレスに行える、統合を前提としたDB設計です
- 💰 **トークン消費を削減** — 過去の文脈を再説明する必要がなくなります。記憶検索はローカルembeddingで行うためClaudeのトークンを消費せず、的確な文脈注入により修正のやり取りも減少します

## 仕組み

```
ユーザーの発言
    │
    ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  1. 自動保存  │────▶│  2. 意味検索  │────▶│ 3. コンテキスト│
│  前回の回答を │     │  関連する過去 │     │    注入       │
│  DBに保存    │     │  の記憶を取得 │     │  Claudeに渡す │
└──────────────┘     └──────────────┘     └──────────────┘
                                                 │
                                                 ▼
                                          Claudeが過去の
                                          文脈を踏まえて回答
```

Claude Codeのフック機能を利用し、すべて自動で行われます。ユーザーが意識する必要はありません。

### Claude標準のauto-memoryとの違い

Claude Codeには標準のauto-memory機能（`~/.claude/projects/.../memory/`）があります。N3MemoryCoreはこれと**競合せず、補完し合います**。

| | Claude auto-memory | N3MemoryCore RAG |
|---|---|---|
| **得意なこと** | 確実・毎回ロード・固定情報 | 過去の会話の文脈・詳細な経緯 |
| **苦手なこと** | 会話の流れや文脈は持てない | 検索精度に依存・確実性がない |
| **用途** | ユーザープロフィール、フォルダパス等 | 会話の詳細、議論の経緯 |

**推奨の使い分け：**
- **毎回必要な固定情報**（開発フォルダのパス、ユーザーの好みなど）→ auto-memoryに保存
- **会話の文脈・経緯**（議論の流れ、過去の決定理由など）→ N3MemoryCoreが自動で蓄積

## Free版とPro版

| | Free | Pro |
|---|---|---|
| 基本機能（保存・検索・自動動作） | ✅ | ✅ |
| 重複更新（Refresh） | - | ✅ 古い記憶を最新版に自動置換 |
| セッション/環境バイアス | - | ✅ 直近の会話・自環境を優先 |
| GC（ガベージコレクション） | - | ✅ 古い記憶の自動整理 |
| インポート/エクスポート | - | ✅ データの移行・共有 |
| 削除機能 | - | ✅ 個別レコードの削除 |

**迷ったらFree版から。** 後からPro版にアップグレードできます（Upgrade版の指示書を使用）。

## 指示書一覧

| ファイル | 内容 |
|---|---|
| `N3MemoryCore_v1.3.2_Free_JP.md` | Free版（日本語） |
| `N3MemoryCore_v1.3.2_Free_EN.md` | Free版（英語） |

> 💡 **指示書内の「注釈」について**
> 指示書（Markdown）内の各所に、AIの挙動を厳格に制御するための「設計意図」を注釈として記しています。コードを生成する前に、ぜひ一度この注釈に目を通してください。そこには、単なるコード以上の「AIを使いこなすための論理」が詰まっています。

## セットアップ

導入経路は以下の 2 通りをサポートします。お好みのスタイルでお選びください。

### 経路 A — AI ネイティブセットアップ（プロジェクト本来のフロー）

1. 上の表から指示書を1つ選ぶ
2. Claude Codeのプロンプトにファイルをドロップする
3. 「指示書通りに実装してください」と伝える

これだけです。コードの記述、フックの設定、初期設定のすべてをClaude Codeが行います。
セットアップには約15〜30分かかります（環境やモデルにより異なります）。
次のセッションから記憶が有効になります。

### 経路 B — `pip` で素早く導入する

AI による実装ステップを省略してリファレンスビルドをそのまま使いたい場合：

#### 1. インストール

最も簡単な方法 — PyPI から直接インストール (clone 不要):

```bash
pip install n3memorycore-free
```

ローカルにコードを取得してカスタマイズしたい場合:

```bash
git clone https://github.com/NeuralNexusNote/n3mc-free.git
cd n3mc-free
pip install -e .          # editable install
```

要件: Python 3.10+。サーバー初回起動時に埋め込みモデル（`intfloat/multilingual-e5-base`、約 470 MB）が初回ダウンロードされるため、2〜10 分の一回限りの遅延が発生します。

#### 2. Claude Code に接続する

```bash
n3mc --init
```

このコマンド一発で、N3MC を Claude Code に接続するために必要な処理を**すべて**実施します:

- `~/.n3mc/` を作成（DB・設定・監査ログ・PID ファイルがここに集約）
- `~/.n3mc/config.json` に `owner_id` / `local_id` を自動生成して書き込み
- **ユーザーグローバル**の `~/.claude/settings.json` に `UserPromptSubmit` と `Stop` フックを登録（インストール済みの `n3mc-hook` / `n3mc-stop-hook` エントリポイントの絶対パスを指す）。「ユーザーグローバル」が重要 — リポジトリ内に限らず**どのプロジェクトディレクトリ**で起動した Claude Code セッションでもフックが発火する

このコマンドは冪等です。再実行しても重複登録されません。

#### 3. フック登録を検証する

以下のワンライナーを実行 — `OK` が出力されれば成功:

```bash
python -c "import json,os; s=json.load(open(os.path.expanduser('~/.claude/settings.json'))); h=s.get('hooks',{}); assert any('n3mc' in c.get('command','').lower() for e in h.get('UserPromptSubmit',[]) for c in e.get('hooks',[])), 'UserPromptSubmit hook missing'; assert any('n3mc' in c.get('command','').lower() for e in h.get('Stop',[]) for c in e.get('hooks',[])), 'Stop hook missing'; print('OK')"
```

`OK` が出力されればフックは正しく登録されています。`AssertionError` が出る場合は `n3mc --init` を再実行してください。

#### 4. Claude Code を再起動する

実行中の Claude Code セッションを**すべて**閉じて（ターミナル CLI ウィンドウ、VS Code 等の IDE 拡張の "Claude Code" パネル、その他すべて）、新しいセッションを起動してください。フックはセッション起動時に読み込まれるため、`n3mc --init` の前から開いていたセッションには反映されません。

#### 5. 動作確認

新しい Claude Code セッションで何かメッセージを送信し、Claude が応答したあと以下を実行:

```bash
n3mc --list
```

最低 2 件のレコードが表示されるはずです — `[user]` プレフィックス（あなたのメッセージ）と `[claude]` プレフィックス（Claude の応答）。リストが空の場合は下の **トラブルシューティング** へ。

#### オプション: データ位置の変更

`n3mc --init` の前に `N3MC_HOME=/path/to/dir` を設定するとデータ保存先を変更できます（その install ではこの位置が永続化されます）。

---

### トラブルシューティング（経路 B）

**`pip install` 後に `n3mc: command not found`**
Python の `Scripts/`（Windows）または `bin/`（macOS/Linux）ディレクトリが `PATH` に通っていません。`PATH` に追加するか、代替として `python -m n3memorycore.n3memory --init` を使用してください。

**実際に会話したのに `--list` が 0 件**
`n3mc --init` を実行する**前から**開いていた Claude Code セッションを使っています。完全に閉じて新規セッションを起動してください — フックはセッション起動時に読み込まれます。

**フックは登録されているのに何も保存されない**
監査ログを確認してください:
```bash
cat ~/.n3mc/.memory/audit.log | tail -3
```
ユーザープロンプトごとに 1 行 JSON が追加されているはずです。空ならフックが発火していません — Step 3 の検証コマンドが `OK` を返すか、また編集対象が**ユーザーグローバル**の `~/.claude/settings.json`（プロジェクトローカルの `.claude/settings.json` ではない）になっているかを確認してください。

**初回 `n3mc --search` が空を返すが、その後は動く**
`intfloat/multilingual-e5-base` モデル（約 470 MB）が初回呼び出し時にダウンロード中です。2〜10 分待ってからリトライしてください。

### セットアップ後の体験

セットアップが完了すると、次のセッションから自動的に動作します：
- あなたの発言に関連する過去の会話が、自動で検索・注入されます
- Claudeは過去の文脈を踏まえて回答します（「前回話した○○ですが…」）
- 保存も検索もバックグラウンドで行われるため、操作は不要です

### バックアップと復元

記憶を別の環境に移行する場合や、安全のためにバックアップする場合は `~/.n3mc/` 配下の以下の 2 ファイルを保管してください：
- `.memory/n3memory.db` — 記憶データ本体
- `config.json` — `owner_id`・`local_id` のUUIDv4キー

この2ファイルはセットで保管する必要があります。キーが一致しないと記憶の所有者検証が正しく機能しません。

### アンインストール

```bash
pip uninstall n3memorycore-free
rm -rf ~/.n3mc/                                      # データ削除（不可逆）
# 続いて ~/.claude/settings.json からフックエントリを手動で削除してください。
```

経路 A で導入した場合は、Claude Code に「N3MemoryCore を削除してください」と依頼すれば、フック設定の解除も含めて安全に処理されます。

## ID 階層構造

N3MemoryCore は 5 つの ID フィールドで各レコードの出所と文脈を識別します：

| ID | 保存場所 | 生成タイミング | 粒度 | 用途 |
|---|---|---|---|---|
| `id` (PK) | DB レコード | レコード作成時 (UUIDv7, 時系列順) | **1 レコード** | 各記憶の一意識別子 — 削除・重複検出に使用 |
| `owner_id` | `config.json` | 初回起動時 (UUIDv4) | **所有者 / N3MC サーバー** | データの所有者識別 — 共有・マルチユーザーシナリオ・インポート由来の記録に使用 |
| `session_id` | メモリ内またはホストから供給 | タスク／プロジェクト／会話ごと (UUIDv4) | **タスク／プロジェクト／会話** | 同じタスク・プロジェクト・会話に属する記憶をまとめて浮上させる。Free 版では `b_session` ランキングバイアス（一致=1.0、不一致=0.6）を駆動し、進行中の会話を関連無関係なセッションより優先する |
| `local_id` (agent_id) | `config.json` / API | 初回起動時 (UUIDv4)、またはリクエスト毎 | **エージェント / インストール** | 発話エージェントの UUIDv4 識別子。マルチエージェント時は各エージェント固有の UUID を指定（Free 版ではレコードに保存されるがランキングには使用されない；`b_local` は Pro 機能） |
| `agent_name` | DB レコード | バッファ呼び出し時 (任意文字列) | **エージェント表示名** | エージェントの人間可読なラベル（例：`"claude-code"`） |

```
owner_id  (1 つの N3MC サーバ／データ所有者)
  └── session_id  (1 つのタスク／プロジェクト／会話)
        └── local_id  (そのセッション内で発話するエージェント)
              ├── agent_name  (その表示名: "claude-code" 等)
              └── id  (1 件の記憶レコード)
```

## 動作環境

- **Claude Code**（必須）
- **Python 3.10+**
- **OS**: Windows 11（動作確認済み） / macOS・Linux（対応設計だが未検証）

> Pythonが入っているか確認するには、ターミナルで `python --version` を実行してください。
> 未インストールの場合、セットアップ時にClaude Codeが案内します。

## 拡張性

N3MemoryCoreは指示書（仕様書）を読ませて作るため、拡張もClaude Codeに相談するだけで対応できます。

- **MCPサーバー化** — N3MCをMCPサーバーとして公開し、他のAIツールから記憶にアクセス
- **PostgreSQL移行** — SQLiteからPostgreSQL + pgvectorへ。チーム規模の運用に
- **カスタム検索ロジック** — バイアス係数やランキング式の調整
- **他のembeddingモデル** — 用途に合わせたモデルへの差し替え
- **ID階層の拡張** — `project_id`や`tag`など、分類フィールドを自由に追加
- **PDF取込** — PDFからテキストを抽出し、検索可能な記憶として保存
- **ハッシュタグ対応** — Claudeが記憶に `#タグ` を自動付与して絞り込み検索（例: `--search "#AWS"`）。既存のFTSで動作し、DB変更不要

指示書をClaude Codeに読ませて「○○を追加して」と伝えるだけです。

## ⚠️ ご利用にあたって

- **ノーサポート・ノークレーム**: 本プロジェクトはサポートを提供していません。動作に関する問い合わせ・不具合報告・機能要望への対応は保証されません。すべて自己責任のもとでご利用ください。
- **自己責任**: 本システムはAIが生成したコードで動作します。導入によるデータの変化や不具合については、製作者は責任を負いかねます。
- **バックアップ**: 大切なプロジェクトで実行する前に、必ず現在の環境をバックアップしてください。

---

Apache License 2.0 — Copyright (C) 2026 NeuralNexusNote™ / ArnolfJp019
詳細は [LICENSE](./LICENSE) をご覧ください。