> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# メモリ

Qoder CLI はセッションごとに context を組み立て直します。セッションをまたいで残したい知識は、主に2種類のメモリから渡されます。

* 静的メモリ：ユーザーまたはチームが管理する永続的な指示です。`AGENTS.md` と rules を含み、コーディング規約、プロジェクト構造、コマンド、共同作業ルールに向いています。
* 自動メモリ：機能が有効な場合に Qoder CLI がローカルに保存する Markdown メモリ。好み、フィードバック、プロジェクト背景、外部参照など、後のセッションでも使いたい情報に向いています。

メモリは context であり、強制実行されるポリシーではありません。コマンド、ツール、パスを確実に制御したい場合は、権限設定または Hooks を使ってください。

## メモリの種類

| 仕組み   | 書く人        | 主な用途                                                               | スコープ                           | 確認方法                                                             |
| ----- | ---------- | ------------------------------------------------------------------ | ------------------------------ | ---------------------------------------------------------------- |
| 静的メモリ | ユーザーまたはチーム | 毎回適用したい明示的で安定した指示。`AGENTS.md` は全体方針、rules はトピック別またはファイル範囲別の指示に使います | ユーザー、プロジェクト、ローカルプロジェクト、プラグイン提供 | `/memory`                                                        |
| 自動メモリ | Qoder CLI  | 会話から得た再利用可能な情報。好み、フィードバック、プロジェクト背景、参照先など                           | プロジェクト。任意でユーザースコープ             | `/memory` で auto-memory folder を開く。`/memory manage` でトピックファイルを管理 |

## 静的メモリ

静的メモリは、ユーザーまたはチームが明示的に書いて管理します。`AGENTS.md` はプロジェクト全体の説明や安定した約束に向き、rules は関連する指示をトピック別またはファイル範囲別の Markdown ファイルに分ける用途に向いています。

### 静的メモリファイル

`AGENTS.md` は Qoder CLI の既定の context ファイル名で、rules は `rules/` ディレクトリ配下に置く Markdown ルールファイルです。メモリの読み込みまたは更新時に、Qoder CLI は利用可能な静的メモリファイルを読み取り、一致した内容をセッション context として注入します。

#### よく使う場所

```text theme={null}
~/.qoder/AGENTS.md
<project>/AGENTS.md
<project>/AGENTS.local.md
<project>/.qoder/rules/*.md
```

| 場所                            | 用途                                     | コミット対象 |
| ----------------------------- | -------------------------------------- | ------ |
| `~/.qoder/AGENTS.md`          | 現在のユーザーのプロジェクト横断の好みや作業習慣               | いいえ    |
| `<project>/AGENTS.md`         | チーム共有のプロジェクトルール、アーキテクチャメモ、共通コマンド       | はい     |
| `<project>/AGENTS.local.md`   | このマシンだけのプロジェクトメモ。ローカル URL や個人用テストデータなど | いいえ    |
| `<project>/.qoder/rules/*.md` | トピックやファイル範囲ごとに分けたプロジェクトルール             | はい     |

高度な設定では、`context.fileName` でファイル名を変更できます。単一の文字列または文字列配列を指定できます。既定値は `AGENTS.md` です。

#### 読み込みロジック

メモリの読み込みまたは更新時、Qoder CLI のプロジェクトメモリは上方向に探索し、各階層のプロジェクトルールディレクトリも確認します。

* ユーザーメモリ：ユーザー設定ディレクトリの `AGENTS.md` を読み込みます。
* プロジェクトおよびローカルプロジェクトメモリ：信頼済みワークスペースでは、現在のワークスペースディレクトリから親ディレクトリへ向かって `AGENTS.md`、`AGENTS.local.md`、`.qoder/rules/**/*.md` を探します。既定では `.git` があるディレクトリで停止します。
* ルールの frontmatter が読み込み方法を決めます。常時適用のルールは周囲のプロジェクトメモリと一緒に読み込まれます。ファイルスコープのルールは、Qoder CLI が一致するファイルにアクセスした後にオンデマンドで読み込まれます。手動ルールとモデル判断ルールは、起動時に本文を注入しません。
* サブディレクトリメモリ：起動時には先読みしません。Qoder CLI がサブディレクトリ内のファイルを正常に読み取った後、そのファイルのディレクトリから上方向に探索し、まだ読み込まれていない `AGENTS.md`、`AGENTS.local.md`、または一致する `.qoder/rules/**/*.md` を追加で読み込みます。このオンデマンドの内容は以後の context に入り、`/memory` にも表示されます。

たとえば `/repo/packages/app` で起動した場合、次を確認します。

```text theme={null}
/repo/packages/app/AGENTS.md
/repo/packages/app/.qoder/rules/*.md
/repo/packages/AGENTS.md
/repo/packages/.qoder/rules/*.md
/repo/AGENTS.md
/repo/.qoder/rules/*.md
```

`/repo` で起動しただけでは `/repo/packages/app/AGENTS.md` や `/repo/packages/app/.qoder/rules/*.md` は先読みされません。`packages/app` 配下のファイルにアクセスした後、必要に応じて読み込まれます。

### ルール（Rules）

ルールは、肥大化した単一の `AGENTS.md` の代わりに、`rules/` ディレクトリ配下へ分割して置く指示の Markdown ファイルです。トピック（テスト、API、セキュリティ）ごと、または対象とするコード領域ごとに分割します。各ルールは単なる Markdown ファイルで、任意の frontmatter が適用タイミングを制御します。

Qoder CLI の rules frontmatter は、Qoder Desktop で設定した rules と互換性があります。Qoder Desktop から同期またはコピーしたルールは、既存のトリガー設定をそのまま使用できます。

#### 配置場所

ルールには 2 つのスコープがあります。

| スコープ   | 場所                               | 適用範囲                 | コミット |
| ------ | -------------------------------- | -------------------- | ---- |
| プロジェクト | `<project>/.qoder/rules/**/*.md` | ファイルがあるプロジェクト。チームで共有 | する   |
| ユーザー   | `~/.qoder/rules/**/*.md`         | 開くすべてのプロジェクト。マシン個人用  | しない  |

プロジェクトルールはワークスペースの任意の階層（ネストしたサブディレクトリを含む）に置け、作業ディレクトリから上方向に探索して見つけられます。ユーザールールはユーザー設定ディレクトリから読み込まれ、すべてのプロジェクトに適用されます。

#### 対応する適用方式

Qoder CLI は 4 種類の rules 適用方式をサポートします。読み込み関連の frontmatter がない場合、ルールは既定で常時適用になります。`trigger` がある場合は `alwaysApply` より優先されます。

| 適用方式     | 向いている用途                    | 設定方法                                                             | 読み込み動作                                           |
| -------- | -------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ |
| 常時適用     | すべてのセッションで適用したい汎用ルール       | 読み込み frontmatter なし、`trigger: always_on`、または `alwaysApply: true` | メモリの読み込みまたは更新時にルール本文を読み込みます。                     |
| 手動       | 明示的に使うときだけ必要なルール           | `trigger: manual` または `alwaysApply: false`                       | ルール本文を自動注入しません。                                  |
| モデル判断    | 短い説明から現在のタスクとの関連性を判断できるルール | `trigger: model_decision` + 空でない `description`                   | ルールのパスと説明だけを注入し、関連すると判断したときにルール本文を読み込みます。        |
| ファイルスコープ | 特定のファイルやディレクトリだけに適用するルール   | `trigger: glob` + `glob`、または `paths`                             | Qoder CLI が一致するファイルにアクセスした後、ルール本文をオンデマンドで読み込みます。 |

`trigger: model_decision` には空でない `description`、`trigger: glob` には有効な `glob` が必要です。必須フィールドがない場合、ルール本文は自動注入されません。

#### 設定例

常時適用のルールは frontmatter を省略することも、明示的に設定することもできます。

```markdown theme={null}
---
trigger: always_on
---

# プロジェクト共通ルール

- 変更を提出する前にテストを実行します。
- 公開 API を変更した場合はドキュメントも更新します。
```

手動ルールは context に自動注入されません。

```markdown theme={null}
---
trigger: manual
---

# リリースチェックリスト

- バージョン番号が更新されていることを確認します。
- changelog が補足されていることを確認します。
```

モデル判断ルールには、ルール本文を読むべきか判断するための `description` が必要です。

```markdown theme={null}
---
trigger: model_decision
description: API handler、schema、エラーエンベロープを変更するときに使用します。
---

# API ルール

- リクエストボディは `src/api/schema/` の共有スキーマで検証します。
- すべてのハンドラーは標準のエラーエンベロープを返します。
```

ファイルスコープのルールには、`trigger: glob` + `glob` を使用できます。

```markdown theme={null}
---
trigger: glob
glob:
  - src/api/**
  - "**/*.test.ts"
---

# API ルール

- リクエストボディは `src/api/schema/` の共有スキーマで検証します。
- すべてのハンドラーは標準のエラーエンベロープを返します。
```

パススコープのルールには、`paths` を直接使うこともできます。

```markdown theme={null}
---
paths:
  - src/api/**
  - "**/*.test.ts"
---
```

#### Frontmatter 設定

| 設定項目          | 値                                            | 説明                                                                                                                    |
| ------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `trigger`     | `always_on`、`manual`、`model_decision`、`glob` | 適用方式。`always_on` は常時適用、`manual` は手動、`model_decision` はモデル判断で空でない `description` が必要、`glob` はファイルスコープで有効な `glob` が必要です。 |
| `alwaysApply` | `true`、`false`                               | 互換設定です。`true` は `trigger: always_on`、`false` は `trigger: manual` と同等です。                                               |
| `description` | 文字列                                          | モデル判断ルールの説明です。ルール本文を読むべきか判断するために使われます。                                                                                |
| `glob`        | 1 つの glob または glob のリスト                      | `trigger: glob` と組み合わせ、ルールが適用されるファイル範囲を指定します。                                                                         |
| `paths`       | 1 つの glob または glob のリスト                      | ルールが適用されるファイル範囲を指定します。`trigger: glob` + `glob` と同等です。                                                                 |

`glob` と `paths` についての注意：

* glob パターンのリストです。プロジェクトルールの glob は `.qoder/` フォルダーを含むディレクトリを基準に、ユーザールールの glob は現在のプロジェクトルートを基準に一致判定されます。
* 内部のルーティングメタデータです。適用タイミングを決めるだけで、ルール本文と一緒にモデルの context へ注入されません。

パターンは gitignore 形式で一致判定されます。よくある例：

| パターン                   | 一致対象                                |
| ---------------------- | ----------------------------------- |
| `**/*.ts`              | 任意のディレクトリのすべての TypeScript ファイル      |
| `src/**/*`             | `src/` 配下の任意の深さのすべてのファイル            |
| `*.md`                 | 任意のディレクトリの Markdown ファイル            |
| `/*.md`                | プロジェクトルートの Markdown ファイルのみ          |
| `src/components/*.tsx` | `src/components/` 直下のファイル（ネストは含まない） |

#### セッション中のルール更新

ルールが読み込まれた後、Qoder CLI はそのセッションの残りの間ファイルを監視し続けます。読み込み済みのルールは、読み込まれた方法やプロジェクト・ユーザースコープに関係なく、編集すると次のターンで検知されます。そのため、再起動せずにルールを調整し、新しい版に従わせることができます。パススコープのルールは、アクセスされたファイルに初めて一致したときも監視対象になります。

### よい指示の書き方

`AGENTS.md` には「次のセッションでも重要な事実と約束」を書きます。適した内容：

* ビルド、テスト、フォーマット、リリースコマンド
* プロジェクト構成と重要なモジュール境界
* コードスタイル、命名、レビュー要件
* コミット、ブランチ、テストデータなどのチームワークフロー
* このリポジトリに長期的に有効なセキュリティやコンプライアンス上の注意

避ける内容：

* 現在のタスクだけに必要な一時状態
* すぐ変わる予定や進捗
* コードや README から直接読める長い重複説明
* 必ず強制したいポリシー。強制には権限設定または Hooks を使ってください

具体的で検証可能な指示ほど安定します。

```markdown theme={null}
# Development

- Use `pnpm test` before committing changes.
- API handlers live in `src/api/handlers/`.
- Do not modify generated files under `src/generated/`.
```

### 他のファイルを取り込む

`AGENTS.md` では `@path/to/file` で別ファイルを取り込めます。相対パスは、その import を含むファイルの場所を基準に解決されます。

```markdown theme={null}
# Project Notes

See @README.md for the high-level architecture.
Use @docs/testing.md for test data setup.
```

`import` の動作:

* 相対パス、絶対パス、`~/` パスを利用できます。
* Markdown のインラインコードや fenced code block 内の `@...` は無視されます。
* プロジェクトおよびローカルプロジェクトのメモリは、既定ではプロジェクト境界内のファイルを import できます。境界外の import には明示的な承認またはセキュリティ設定が必要です。
* import は再帰的に展開されますが、循環を避けるため深さ制限があります。

文字列として `@README.md` と書きたいだけなら、`` `@README.md` `` のようにバッククォートで囲んでください。

## 自動メモリ

自動メモリが有効な場合、Qoder CLI は作業中に、セッションをまたいで役立つ情報をローカル Markdown ファイルとして保存します。すべての会話ターンを保存するのではなく、将来のセッションで使う価値があるかを判断します。

### 保存に向いている内容

自動メモリには4種類の内容があります。

| 種類          | 用途                            |
| ----------- | ----------------------------- |
| `user`      | ユーザーの役割、長期的な好み、プロジェクト横断の習慣    |
| `feedback`  | Qoder CLI の作業方法に関する修正や確認      |
| `project`   | コードから直接導けないプロジェクト背景、制約、意思決定理由 |
| `reference` | 外部システム、ボード、ダッシュボード、ドキュメントの場所  |

自動メモリファイルはこのマシン上のローカルファイルです。コードをコミットしても、他のマシンへ自動共有されるわけではありません。また、メモリは古くなることがあります。ファイル、関数、設定、外部状態に関するメモリを使うときは、Qoder CLI は現在の事実を確認してから行動するべきです。

### 自動メモリを有効にする

自動メモリは対話型セッションでのみ動作します。現在の実装では、実効スイッチは環境変数です。

```bash theme={null}
QODER_MEMORY=1 qodercli
```

プロジェクトをまたぐユーザースコープの自動メモリも有効にする場合：

```bash theme={null}
QODER_MEMORY=1 QODER_MEMORY_USER=1 qodercli
```

`QODER_MEMORY_USER` は `QODER_MEMORY` が有効な場合だけ効果があります。自動メモリが無効でも、`/memory` で `AGENTS.md` ファイルは管理できます。`/memory manage` は自動メモリが利用できないことを表示します。

### 自動メモリの保存場所

プロジェクトスコープの自動メモリは、Qoder のプロジェクト設定ディレクトリ配下に保存されます。

```text theme={null}
~/.qoder/projects/<project>/memory/
```

ユーザースコープの自動メモリを有効にした場合は、次も使われます。

```text theme={null}
~/.qoder/memory/
```

各自動メモリディレクトリには `MEMORY.md` の索引と任意のトピックファイルがあります。

```text theme={null}
memory/
├── MEMORY.md
├── user-preferences.md
├── feedback-testing.md
└── project-release-context.md
```

`MEMORY.md` は索引であり、長い本文を書く場所ではありません。起動時に Qoder CLI は各有効な自動メモリ root の `MEMORY.md` を読み込みます。読み込むのは最大で先頭 200 行または約 25KB です。詳細なメモは索引から参照されるトピックファイルに分けてください。

## 表示と管理

TUI で次を実行します。

```text theme={null}
/memory
```

`/memory` はメモリ概要を開きます。ユーザー、プロジェクト、ローカルプロジェクトのメモリファイルを表示し、自動メモリが有効な場合は `Open auto-memory folder` 入口も表示します。この入口を選ぶと、対応する auto-memory folder がシステムのファイルマネージャーで開きます。

TUI 内で自動メモリのトピックファイルを管理するには：

```text theme={null}
/memory manage
```

`/memory manage` は自動メモリ管理画面を開きます。管理画面では、自動メモリのトピックファイルを表示、開く、編集、削除できます。トピックファイルを削除すると、Qoder CLI は対応する `MEMORY.md` 索引行も削除します。

### 覚える・忘れる

自然言語で依頼できます。

```text theme={null}
Remember that this project's integration tests require local Redis first.
```

または：

```text theme={null}
Forget the old deployment-script memory.
```

チームルールやプロジェクト指示に近い内容なら、`AGENTS.md` に書くよう明示してください。

```text theme={null}
Add this testing rule to the project AGENTS.md.
```

## トラブルシューティング

### Qoder CLI が `AGENTS.md` に従わない

* `/memory` を実行し、対象ファイルが表示されているか確認します。
* 現在のディレクトリが信頼済みか確認します。信頼されていないフォルダでは、プロジェクト設定、Hooks、MCP、`AGENTS.md` は適用されません。
* ユーザー、プロジェクト、ローカルプロジェクトの各ファイル間で矛盾する指示がないか確認します。
* `agentsMdExcludes` が対象ファイルを除外していないか確認します。
* 曖昧な指示を、より具体的で検証可能なルールにします。

### `@` import が読み込まれない

* パスが存在し、Markdown のインラインコードや fenced code block 内にないことを確認します。
* プロジェクト境界外の import は既定でブロックされます。外部 import を承認するか、セキュリティ設定を調整してください。
* npm パッケージ名、メンション、単なる `@word` はファイル import として扱われません。

### 自動メモリが表示されない

* TUI の対話型セッションであることを確認します。
* `QODER_MEMORY=1` 付きで起動したことを確認します。
* `/memory` を実行し、auto-memory folder 入口が表示されるか確認します。または `/memory manage` を実行し、自動メモリ管理画面が利用可能か確認します。
* 自動メモリは毎ターン保存するわけではありません。再利用できる情報が見つからなければ、0 件の作成は正常です。

### メモリが古い

メモリは書かれた時点の情報です。現在のコード、設定、外部システムについては、まず現在のファイルやシステムを信頼してください。古いメモリを見つけたら、更新または削除します。