メインコンテンツまでスキップ

memory の 3 層

Claude Code のセッションは、終われば文脈を失います。だからこそ、残すべき学びを永続化する仕組みが要ります。この環境では用途の違う 3 層で使い分けています。

3 層の使い分け​

層置き場所何を残すか入口区分
learnings~/.claude/learnings/{core,frontend-vue,...}/技術 Tips・ハマりどころ（横断的に効く知見）/learn🔧
プロジェクト memory~/.claude/projects/.../memory/そのリポジトリ固有の事実・経緯自動 / 明示依頼📦
handoff context~/.claude/context/セッション間の引き継ぎ/smart-handoff / /smart-pickup🔧

3 層のうち、Claude Code 標準（📦）なのはプロジェクト memory だけです。learnings のカテゴリ設計と /learn、handoff の /smart-handoff / /smart-pickup は、標準の memory だけでは足りなかった用途（プロジェクト横断の知見、セッション間の作業引き継ぎ）を補うために筆者が組んだ仕掛け（🔧）です。なお、プロジェクト memory（auto memory）は Claude Code v2.1.59 以降でデフォルト有効です。

learnings — 横断的な知見​

learnings/ は、技術 Tips やハマりどころをカテゴリ別（core / frontend-vue / frontend-react / infra）に蓄積する場所です。どのプロジェクトでも効く知見が対象です。/debug でいえば、Generalize で見つけた「同パターンのバグ」や再発防止の気づきを、ここに /learn で書き残します。

learnings はゴールではありません。規範化に値すると判断されたら、rules/ の正式な規範や hook へ「昇格」します。この昇格の流れが Ratchet の Ratchet です。

プロジェクト memory — リポジトリ固有の事実​

プロジェクト memory は、そのリポジトリでしか意味を持たない事実を、1 ファイル 1 事実で残す場所です。コードや git 履歴を読めば分かることは残さず、「読んでも分からない経緯・制約」だけを書きます。

各 memory にはフロントマターが付き、MEMORY.md という索引ファイルに 1 行のポインタを足します。この索引はセッション開始時に読み込まれるので、過去に学んだ事実がすぐ呼び戻せます。フロントマターの形式・索引・自動ロードはすべて標準機構（📦）で、筆者側にあるのは「何を残し、何を残さないか」の運用判断だけです。

プロジェクト memory の例（このサイトの運用知・形式は簡略化）
---
name: tech-notes-docs-index-slug
description: index.md に slug を書くと URL 二重化、書かず自動 de-dup に任せる
metadata:
  type: project
---

実物のフロントマターには、このほか node_type や生成元セッション ID といったフィールドも自動で付きます。

このガイド自体、memory に助けられている

じつはこのガイドを書く際にも、過去のハマりどころが memory から呼び戻されました。「index.md に slug を書かない」「ガイドのカテゴリ名と扉ページ名が重複しないよう sidebar_label で別名化する」といった知見です。一度踏んだ落とし穴を二度踏まないための、生きた記録です。

handoff — セッションの引き継ぎ​

長いタスクを途中で区切るとき、/smart-handoff で現在の文脈を context/ に保存します。次のセッションで /smart-pickup すると、そこから再開できます。コンテキストが圧縮される直前には precompact-snapshot.sh（hooks の仕組み の PreCompact hook）も状態を退避します。

残すべきもの・残さないもの​

memory は何でも書けばよいわけではありません。判断の軸はシンプルです。

  • 残す: コードを読んでも分からない経緯・制約・設計判断の理由、ユーザーの好み、再発しうるハマりどころ
  • 残さない: コード構造・git 履歴・過去の修正など、リポジトリを見れば分かること（重複は混乱のもと）
この章のまとめ

要点は次のとおりです。

  • 永続化は learnings（横断知見）・プロジェクト memory（固有の事実）・handoff（引き継ぎ）の 3 層
  • 標準（📦）はプロジェクト memory だけで、learnings と handoff は標準を補う筆者の自作（🔧）
  • learnings は規範化に値すれば rules / hook へ昇格する（後述の Ratchet）
  • プロジェクト memory は 1 ファイル 1 事実 + MEMORY.md 索引で、開始時に呼び戻される
  • 「コードを読めば分かること」は残さない

ここまでで各レイヤの仕組みが揃いました。Ratchet では、これらを使って「学びを仕組みに変える」流れを見ます。