9 月 13 日、壁紙アプリの運用で使っている Cowork のプロジェクトで、メモリの整理を頼んだ日のことです。メモリの索引(MEMORY.md)とフォルダの中身を突き合わせてもらうと、両者がまったく合っていませんでした。
数えてみると、索引から辿れないメモリが 78 本 ありました。どれも消したつもりはなく、整理のたびに索引から外しただけのものです。索引を短くすれば片付いたことになる——そう思い込んでいたのは私のほうでした。
その日から 10 月初めまでに行った退役の手順と、いま手元で回している 3 本のスクリプトを書き残します。数値はすべて私自身の個人開発のプロジェクトで実際に数えたもので、スクリプトは同じ構成のダミーのフォルダで動かし直して、出力が本文のとおりになることを確かめました。
何が残っていたのか——78 本の内訳
退役させたファイルは、のちに全文をアプリの文書フォルダへ控えとして移しました。その控え(74 本が読める状態で残っています)を数え直すと、次のような顔ぶれでした。
最初にお伝えしたいのは、溜まっていたのは「覚えておくべきこと」ではなく「終わった仕事の記録」だった という点です。日付つきの診断メモは、書いた日には確かに大事でした。ただ、結論が出たあとは、結論の 1 行だけが要るのであって、途中の数字や経緯は毎回の前提に乗せる必要がありません。
もう一つ、抜け殻の 5 本には手が止まりました。統合のときに「中身は向こうへ移した」と description を書き換え、索引からも外したのに、ファイルそのものはフォルダに残っていたのです。索引から外すことと、退役させることは、別の作業でした。
失敗——索引から外せば片付く、と思っていた
いま思えば、整理のたびに私がしていたのは「索引の行を消す」ことだけでした。索引が短くなると、肩の荷を下ろしたような気持ちになります。けれど、索引から外れたファイルがその後どう扱われるかは、私の環境では確かめていません(未確認です)。確かめていない以上、「残っていても害はない」と考える根拠もありませんでした。
加えて、当時のセッションからはメモリのフォルダが読み取り専用で、Claude にファイルを動かしてもらうことができませんでした。そこで、移動の命令を並べたシェルスクリプトを Claude に書いてもらい、中身を読んでから私が Terminal で実行する、という分担にしました。結果として、この分担がいちばん安心できるかたちでした。
ここで決めた線引きは一つです。
判断の中身は文書に、メモリには道順だけを。
メモリに残すのは「何を正とするか」の 1 行と、正本の文書の番号や節だけにします。経緯・数値・途中の仮説は、文書の側に置きます。
スクリプト 1: 索引外のメモリを洗い出す(読むだけ)
最初の一本は、何も動かさずに一覧だけを出すものです。索引から [タイトル](name.md) と [[name]] の両方の書き方を拾い、フォルダの .md と突き合わせます。日付つきの名前と、「統合済み」などを含む description には印を付けます。
#!/usr/bin/env python3
"""MEMORY.md の索引に載っていないメモリファイルを洗い出す(読むだけ・何も動かさない)。
使い方: python3 memory_orphans.py <memory フォルダ> > orphans.tsv
"""
import re
import sys
from pathlib import Path
DATE_IN_NAME = re.compile( r "20 \d {2} [ _- ]\d {2} [ _- ]\d {2} " )
RETIRED_WORDS = ( "統合済み" , "退役" , "失効" , "superseded" , "merged into" )
def indexed_names (index_text: str ) -> set[ str ]:
"""索引から参照されているファイル名(拡張子なし)を集める。
[タイトル](name.md) と [[name]] の両方を拾う。"""
names = set (re.findall( r " \]\( ([ ^ )# \s] +? ) \. md \) " , index_text))
names |= set (re.findall( r " \[\[ ([ ^ \] |# ] + ) " , index_text))
return {Path(n).name for n in names}
def description_of (path: Path) -> str :
# フロントマターの description だけを読む。壊れたファイルでも止まらない
try :
head = path.read_text( encoding = "utf-8" , errors = "replace" )[: 2000 ]
except OSError as e:
return f "(読めません: { e } )"
m = re.search( r " ^ description: \s * (. + )$ " , head, re.M)
return m.group( 1 ).strip().strip( '"' ) if m else ""
def main () -> int :
if len (sys.argv) != 2 :
print ( __doc__ , file = sys.stderr)
return 2
root = Path(sys.argv[ 1 ])
index = root / "MEMORY.md"
if not index.is_file():
print ( f "MEMORY.md がありません: { index } " , file = sys.stderr)
return 1
listed = indexed_names(index.read_text( encoding = "utf-8" ))
rows = []
for p in sorted (root.glob( "*.md" )):
if p.name == "MEMORY.md" or p.stem in listed:
continue
desc = description_of(p)
dated = "dated" if DATE_IN_NAME .search(p.stem) else "-"
tomb = "tombstone" if any (w in desc for w in RETIRED_WORDS ) else "-"
rows.append((p.name, dated, tomb, p.stat().st_size, desc[: 60 ]))
print ( "file \t dated \t tombstone \t bytes \t description" )
for r in rows:
print ( " \t " .join( map ( str , r)))
total = len ( list (root.glob( "*.md" ))) - 1
print ( f "# 索引外 { len (rows) } 本 / 全 { total } 本"
f "(日付つき { sum (r[ 1 ] == 'dated' for r in rows) } ・"
f "統合済みの抜け殻 { sum (r[ 2 ] == 'tombstone' for r in rows) } )" , file = sys.stderr)
return 0
if __name__ == "__main__" :
sys.exit(main())
ダミーのフォルダ(索引に 3 本、索引外に 3 本)で動かすと、標準エラーに # 索引外 3 本 / 全 6 本(日付つき 2・統合済みの抜け殻 1) と出て、TSV に 3 行が並びました。空白を含むファイル名も拾えています。
読むだけにしてあるのには理由があります。一覧を見て「これは残す」と私が判断する時間を、必ず挟みたい のです。日付つきでも、たとえば広告のフォーマットごとの方針のように、いまも生きている判断が混ざっていました。そうしたものはメモリから外したうえで、方針の文書として残し直しています。
スクリプト 2: 退役と戻しを、対で書き出す
9 月の時点で Claude に書いてもらったスクリプトは、[ -f 名前 ] && mv 名前 _retired/ を 78 行並べたもので、戻し方はコメントに「親フォルダへ戻すだけ」と一言あるだけでした。動きはしましたが、いま同じことをするなら、戻しのスクリプトも同時に書き出しておきます。
#!/usr/bin/env python3
"""orphans.tsv から「退役スクリプト」と「戻しスクリプト」を書き出す。
自分では動かさない。人が中身を読んでから実行する前提。
使い方: python3 make_retire_script.py orphans.tsv <memory フォルダの絶対パス> <出力フォルダ>
"""
import shlex
import sys
from datetime import date
from pathlib import Path
def main () -> int :
if len (sys.argv) != 4 :
print ( __doc__ , file = sys.stderr)
return 2
tsv, mem_dir, out_dir = Path(sys.argv[ 1 ]), sys.argv[ 2 ], Path(sys.argv[ 3 ])
names = [line.split( " \t " , 1 )[ 0 ] for line in tsv.read_text( encoding = "utf-8" ).splitlines()
if line and not line.startswith(( "file \t " , "#" ))]
if not names:
print ( "退役候補がありません" , file = sys.stderr)
return 1
out_dir.mkdir( parents = True , exist_ok = True )
stamp = date.today().isoformat()
q = shlex.quote(mem_dir)
head = [ "#!/bin/bash" , "set -e" , f "cd { q } " , "mkdir -p _retired" , "n=0" ]
retire = head + [ f "[ -f { shlex.quote(n) } ] && mv -n { shlex.quote(n) } _retired/ && n=$((n+1))"
for n in names]
retire += [ 'echo "moved: $n files -> _retired/"' , 'ls *.md | wc -l | xargs echo "remaining:"' ]
restore = head[: 3 ] + [ "n=0" ] + [
f "[ -f _retired/ { shlex.quote(n) } ] && mv -n _retired/ { shlex.quote(n) } . && n=$((n+1))"
for n in names]
restore += [ 'echo "restored: $n files"' ]
r = out_dir / f "memory_retire_ { stamp } .sh"
b = out_dir / f "memory_restore_ { stamp } .sh"
r.write_text( " \n " .join(retire) + " \n " , encoding = "utf-8" )
b.write_text( " \n " .join(restore) + " \n " , encoding = "utf-8" )
print ( f " { len (names) } 本分: { r } / { b } " )
return 0
if __name__ == "__main__" :
sys.exit(main())
ダミーで退役を流すと moved: 3 files -> _retired/・remaining: 4(索引の MEMORY.md を含む数です)、戻しを流すと restored: 3 files で元の 7 ファイルに戻りました。
なぜこう書くのか、3 点だけ添えます。
mv -n : _retired/ に同じ名前が既にあっても上書きしません。2 回目の整理で古い控えを潰さないためです
shlex.quote : 空白や記号を含むファイル名でも、命令が途中で割れません
[ -f … ] && の連鎖 : 途中で一部のファイルが無くても止まらず、動かした数だけを数えます
「消す」ではなく「横へ退ける」にしておくと、判断を誤ったときにいつでも戻せます。戻せると分かっていたので、78 本を一度に動かすことにも胃が痛くなりませんでした。
スクリプト 3: 索引の1行ルールを検査する
退役のあとに残ったメモリが、また膨らんでいかないための見張りです。索引の各行について、長すぎないか、正本への番号(#123・§3・xxx.md のどれか)を含んでいるかを確かめます。
#!/usr/bin/env python3
"""MEMORY.md の1行1件ルールを検査する。長すぎる行と、正本への番号がない行を出す。
使い方: python3 index_lint.py MEMORY.md [--max 150]
"""
import re
import sys
POINTER = re.compile( r " ( # \d +| § \s ? \d +| \S + \. md \b) " ) # 番号・節・正本ファイル名のどれか
def main () -> int :
args = sys.argv[ 1 :]
if not args:
print ( __doc__ , file = sys.stderr)
return 2
limit = int (args[args.index( "--max" ) + 1 ]) if "--max" in args else 150
bad = 0
with open (args[ 0 ], encoding = "utf-8" ) as f:
for no, line in enumerate (f, 1 ):
line = line.rstrip( " \n " )
if not line.startswith( "- " ):
continue # 見出しや空行は対象外
body = re.sub( r " \]\( [ ^ ) ] * \) " , "]" , line) # リンク先は字数に数えない
problems = []
if len (body) > limit:
problems.append( f " { len (body) } 字" )
if not POINTER .search(line):
problems.append( "正本への番号なし" )
if problems:
bad += 1
print ( f "L { no } : { ' / ' .join(problems) } : { body[: 70 ] } " )
print ( f "# 要確認 { bad } 行" , file = sys.stderr)
return 1 if bad else 0
if __name__ == "__main__" :
sys.exit(main())
ダミーの索引では、[[feedback_tone]] だけの行と、経緯をそのまま書き込んだ長い行の 2 行が「正本への番号なし」として出て、終了コードは 1 でした。--max 100 にすると、長い行には字数の指摘も重なります。
字数の上限は、目安で構いません。大切なのは数字そのものより、1 行に収まらない話は、そもそもメモリに書く話ではない と気づかせてくれることです。
10 月の 2 回目——統合して、残すのは結論 1 行
9 月の退役から 3 週間ほどした 10 月 5 日に、2 回目の整理をしました。今度は索引に載っているメモリの中から、終結・重複したものを 10 本選びました。
版の準備から公開までを 1 本ずつ記録していた連鎖の 7 本は、1 本の「その版の記録」へ統合しました
同じ不具合を別の名前で書いていた重複 1 本は、そちらへ吸収しました
解決済みの手続き 1 本は削除し、要点と操作メモだけを控えに残しました
このときは、退役させる前の本文を日付つきのフォルダへ控え、その控えの README に「何をどこへ統合したか」を 3 行で書きました。控えは読まない前提 です。必要になったら grep で当たるだけにしています。
そして、アプリの文書フォルダの索引(README)に運用ルールを 3 行足しました。
定例の成果物は日付つきで置き、同種の古い回は次回の実行時に _archive/ へ移します
診断の文書は結論が出たら _archive/ へ移し、結論 1 行を README に足します
直下に残すのは、いまも生きている方針と固定の手順だけにします
メモリに残る 1 行は、この README の結論 1 行や、つまずき集の番号を指す道しるべです。正本はあくまで文書で、メモリはそこへの近道に過ぎません。
落とし穴——やってみて分かった 4 つのこと
抜け殻は、統合のたびに生まれる : 中身を移したら、元のファイルも同じ手順で _retired/ へ。description を書き換えるだけでは、フォルダには残り続けます
日付つき=不要、ではない : 日付つきの名前でも、いまも生きている方針が混ざっていました。一覧を見て人が選ぶ工程は省けません
セッションから動かせない場所がある : 当時の私の環境では、メモリのフォルダはセッションから読み取り専用でした。Claude には「動かす命令を書く」まで、実行は私、と分けると迷いません
控えは読まないと決めておく : 退役分の全文を控えると、つい読み返して前提に戻したくなります。戻すなら、その内容を文書の側へ書き直してからにしています
サブフォルダの CLAUDE.md が長すぎて後半が効かなかった件と同じく、「書いたものが効いているか」は、量が増えるほど見えにくくなります。そちらの話は「サブフォルダの CLAUDE.md の後半だけが効かないとき、数えるのは容量ではなく文字数でした 」に書きました。
次の一歩
まずはスクリプト 1 を、ご自分のプロジェクトのメモリのフォルダに対して一度だけ流してみていただければと思います。何も動かしませんので、索引外が何本あり、そのうち日付つきと抜け殻が何本あるかを眺めるだけで、次に何を文書へ寄せるべきかが見えてくるはずです。
私自身、メモリを「覚えておく場所」ではなく「正本への道しるべ」として扱うようになってから、整理のたびに迷う箇所が一つ減りました。何を文書に移すかだけを考えればよくなったからです。判断の重みは文書に、メモリには道順だけ——この線引きは、これからも守っていくつもりです。