#!/usr/bin/env bash
# lib/memory.sh — the single writer and reader of the .claude/memory
# registries (BDR-125 phase 4a). Sourceable; every verb takes an optional
# leading `-C
` (a dispatched agent's cwd is the session's, never the
# project's):
# add --title --body-file [--status ] [--supersedes ]
# append one entry, next ID from the headings, under the
# lock; the new ID is the only stdout line
# status append `- **Status ()**: ` to the entry;
# starts with a status word ("open, reopened by …")
# journal append `- ` under today's `## YYYY-MM-DD`
# index [] ID | Date | Title | Status, from headings and bodies;
# with a kind, an unreadable registry is rc 2; without, a
# bad registry is skipped with a stderr line, rc 0
# check [--staged] [] heading shape, unique IDs, no Index,
# no open fence in a v2 file (v1 reported, never failed);
# --staged: only NEW culprits vs HEAD, no line removed
# inside an entry, no v2 registry deleted or downgraded,
# a new entry's ID is the next free ID (registry in HEAD)
# upgrade [] v1 → v2: Index-only dates and statuses become
# body lines, `format: 2`, `## Index` removed; a missing
# frontmatter comes from the template, ` - ` / ` | date | `
# / `###` headings take the `## ID — title (date)` shape;
# a blocker the v1 reader closed but the strict one reads
# open gets a `Status (…, upgrade)` line only when its v1
# line is a Status/Statut label holding one closed word;
# an Index-row blocker or decision with no strict word takes
# its one-word v1 body label over the Index cell;
# a prose or mixed closure is named and refused (record
# it with `status`, re-run); a `## Index` that is not a
# table is refused (rc 2); the oracle (IDs, check,
# verdicts, one upgrade line per entry) runs first, else rc 2
# = decision | learning | blocker | eval. MEMORY_DATE overrides today.
# Status of an entry: the last candidate wins. A candidate is the heading's
# trailing `[tag]`, or a body line whose bold label names Status, Resolution,
# Action, UPDATE or FINAL (v1: `Status:`), holding a status word. A word in
# prose (title included) is never one (the BLK-032..034 false-open). A dated
# `**Status (YYYY-MM-DD…)**:` line reads its leading word; other lines rank
# words in _MEM_WORDS order, `open` last: "accepted, check OPEN" = accepted.
# A word negated in its clause ("not resolved yet", "never superseded") is
# not one: not|no|never|pas, at most one word before it, no `, ; . : ( ) ->`
# `→` `—` between (mem_has).
# Closed = resolved | superseded | deprecated (memory_closed).
# Lock: /memory.lock created under noclobber (flock(1) is
# absent on macOS), holding " "; released only by its token;
# a lock older than 30 s (or seen empty 10 times) is stolen by one waiter
# at a time (memory.lock.steal; dead when it holds a date over 30 s old or
# has stayed empty over 60 s). Every writer runs on a verified backup
# of its file, restored on failure or signal. Next ID = max over headings
# of any level, fenced or not. Free text reaches awk through ENVIRON,
# never `-v` (which expands backslash escapes).
# absolute before any `-C` cd: a relative $0 no longer resolves after it
_MEM_LIB_DIR="$(cd -P "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
MEM_GREP="${MEM_GREP:-/usr/bin/grep}"
MEM_FIND="${MEM_FIND:-/usr/bin/find}"
_MEM_TABLE='decision decisions BDR
learning learnings LRN
blocker blockers BLK
eval evals EVAL'
_MEM_WORDS='resolved superseded deprecated upstream accepted implemented'
_MEM_WORDS+=' shipped proposed keep correct deprecate open'
_MEM_AWK='
function mem_negated(pre, n, a) {
gsub(/[,;.:()]|->|→|—/, "\001", pre); sub(/^.*\001/, "", pre)
gsub(/[^a-z0-9]+/, " ", pre); n = split(pre, a, " ")
return (n >= 1 && a[n] ~ /^(not|no|never|pas)$/) ||
(n >= 2 && a[n - 1] ~ /^(not|no|never|pas)$/) }
function mem_has(t, w, re, off, ws) {
re = "(^|[^a-z])" w "([^a-z]|$)"; off = 0
while (match(substr(t, off + 1), re)) {
ws = off + RSTART
if (substr(t, ws, 1) != substr(w, 1, 1)) ws++
if (!mem_negated(substr(t, 1, ws - 1))) return 1
off = ws + length(w) - 1 }
return 0 }
function mem_word(s, t, i, n, w) {
t = tolower(s); n = split(MEMW, w, " ")
for (i = 1; i <= n; i++) if (mem_has(t, w[i])) return w[i]
return "" }
function mem_lead(s, v, i, n, w) {
v = s; sub(/^[^:]*\*\*: */, "", v); v = tolower(v)
sub(/[^a-z].*$/, "", v); n = split(MEMW, w, " ")
for (i = 1; i <= n; i++) if (v == w[i]) return v
return "" }
function mem_lineword(s, w) {
if (s ~ /^- \*\*Status \([0-9]/ && (w = mem_lead(s)) != "") return w
return mem_word(s) }
function mem_tag(line) {
if (!match(line, /\[[^]]*\]( \([0-9-]+\))? *$/)) return ""
line = substr(line, RSTART) # before mem_word: its match() moves RSTART
if (mem_word(line) == "") return ""
sub(/\].*$/, "]", line); return line }
function mem_cand(line, lab) {
if (line ~ /^- \*\*[^*]+\*\*/) {
lab = line; sub(/^- \*\*/, "", lab); sub(/\*\*.*/, "", lab)
if (tolower(lab) !~ /status|resolution|action|update|final/) return ""
return mem_lineword(line) }
if (line ~ /^(- )?[Ss]tatus:/) return mem_word(line)
return "" }
function mem_key(line, key, c) {
if (index(line, "## " key) != 1) return 0
c = substr(line, length(key) + 4, 1)
return c == "" || c !~ /[0-9A-Za-z]/ }
function mem_est(st, vw) { return (st != "" || vw == "mixed") ? st : vw }
function mem_want(p, c, st, w) {
w = mem_word(c)
if (w == "") return ""
if (p == "EVAL") return st == "" ? c : ""
if (p == "LRN") return c ~ /^superseded by/ ? c : ""
if (st == "" || (w ~ /^(superseded|deprecated)$/ && st != w)) return c
return "" }
'
_mem_date() { printf '%s\n' "${MEMORY_DATE:-$(date +%F)}"; }
_mem_table() { # [ ] → matching cells, rc 2 if none
# the one reader of _MEM_TABLE (1 kind, 2 registry basename, 3 prefix)
awk -v o="$1" -v c="${2:-0}" -v v="${3:-}" '
c == 0 || $c == v { print $o; f = 1 }
END { exit f ? 0 : 2 }' <<< "$_MEM_TABLE"
}
_mem_names() { _mem_table 2; } # the four registry basenames
_mem_kind() { # → ".md ", rc 2 when unknown
local file
file=$(_mem_table 2 1 "$1") || {
echo "memory: unknown kind: $1 (decision|learning|blocker|eval)" >&2
return 2; }
echo "$file.md $(_mem_table 3 1 "$1")"
}
_mem_id_file() { # → its registry path, rc 2 when the prefix is unknown
local file
[[ "$1" =~ ^[A-Z]+-[0-9][0-9][0-9]+$ ]] \
|| { echo "memory: not an entry ID: $1" >&2; return 2; }
file=$(_mem_table 2 3 "${1%%-[0-9]*}") \
|| { echo "memory: not an entry ID: $1" >&2; return 2; }
echo ".claude/memory/$file.md"
}
_mem_prefix() { # → its prefix by basename, rc 2 if none
local base="${1##*/}"
_mem_table 3 2 "${base%.md}" \
|| { echo "memory: $1: not a registry name" >&2; return 2; }
}
memory_is_v2() { # → rc 0 when the frontmatter carries `format: 2`
awk 'NR == 1 && $0 != "---" { exit }
NR > 1 && $0 == "---" { exit }
$0 == "format: 2" { v2 = 1; exit }
END { exit !v2 }' "$1"
}
_mem_has_id() { # → rc 0 when a heading carries the ID
MEM_K="$2" awk "$_MEM_AWK"'
BEGIN { k = ENVIRON["MEM_K"] }
/^```/ { fence = !fence; next }
!fence && mem_key($0, k) { found = 1; exit }
END { exit !found }' "$1"
}
_mem_next_id() { # → max heading ID + 1, zero-padded
# every heading level, fenced or not (trucks_at_work writes `### BDR-001`;
# a stray fence hides headings). check --staged replays this max in line
# order on a v2 HEAD: a new `## ` entry must be this max + 1. Holds when
# memory.sh appends the entries; a hand-inserted ID line above a new entry,
# or an ID line removed above the first entry, can refuse a valid add
awk -v p="$2" '
match($0, "^#+ *" p "-[0-9]+") {
n = substr($0, RSTART, RLENGTH); sub(/^#+ *[A-Z]+-/, "", n)
if (n + 0 > m) m = n + 0 }
END { printf "%s-%03d\n", p, m + 1 }' "$1"
}
_mem_heading_has() { # → rc 0 when a heading of any level has it
awk -v id="$2" 'match($0, "^#+ *" id "([^0-9]|$)") { f = 1; exit }
END { exit !f }' "$1"
}
_mem_fence_open() { # → rc 0 when a ``` fence is left open
awk '/^```/ { n++ } END { exit !(n % 2) }' "$1"
}
memory_entry_status() { # → the winning candidate, rc 1 if none
# a heading candidate prints its `[tag]` only, never the title
MEM_K="$2" awk -v MEMW="$_MEM_WORDS" "$_MEM_AWK"'
BEGIN { k = ENVIRON["MEM_K"] }
/^```/ { fence = !fence; next }
fence { next }
/^## / { if (on) exit
if (mem_key($0, k)) { on = 1; t = mem_tag($0)
if (t != "") last = t }
next }
on && mem_cand($0) != "" { last = $0 }
END { if (last == "") exit 1; print last }' "$1"
}
memory_status_word() { # → its status word, else its first 40 chars
MEM_L="$1" awk -v MEMW="$_MEM_WORDS" "$_MEM_AWK"'
BEGIN { s = ENVIRON["MEM_L"]; w = mem_lineword(s)
print (w != "" ? w : substr(s, 1, 40)) }'
}
memory_closed() { # → rc 0 when it closes the entry
case "$1" in resolved|superseded|deprecated) return 0 ;; esac
return 1
}
_mem_lock_path() { # → the lock file for the current repository
local d
if d=$(git rev-parse --git-common-dir 2>/dev/null); then
echo "$d/memory.lock"; return
fi
echo "${TMPDIR:-/tmp}/memory-$(pwd | cksum | cut -d' ' -f1).lock"
}
_mem_stale() { # → rc 0 when stealable
local t="${1%% *}"
if [ -z "$1" ]; then [ "$2" -ge 10 ]; return; fi
case "$t" in ''|*[!0-9]*) return 1 ;; esac
[ $(( $(date +%s) - t )) -gt 30 ]
}
_mem_steal() { # → remove a stale lock; one stealer at a time
local g="$1.steal" seen
if ! (set -C; date +%s > "$g") 2>/dev/null; then
# dead stealer: an old date, or a file left empty for over 60 s
# shortcut: check-then-rm window (a waiter may remove and a new stealer
# recreate between the read and the rm); upgrade = re-check inode/mtime
# just before the rm, content cannot tell two empty files apart
if _mem_stale "$(cat "$g" 2>/dev/null) x" 0 \
|| [ -n "$("$MEM_FIND" "$g" -prune -empty -mmin +1 2>/dev/null)" ]
then rm -f "$g"; fi
return 0
fi
seen=$(cat "$1" 2>/dev/null)
_mem_stale "$seen" 10 && rm -f "$1" # age re-read under the guard
rm -f "$g"
}
_mem_lock() { # → rc 0 held, rc 2 after MEM_LOCK_TRIES
# noclobber = open(O_EXCL) by bash itself: mkdir is not atomic under
# uutils coreutils 0.10 (two concurrent mkdir both succeed)
local lock="$1" tries=0 empty=0 t
[ -w "$(dirname "$lock")" ] \
|| { echo "memory: cannot create lock: $lock" >&2; return 2; }
until (set -C; echo "$(date +%s) $2" > "$lock") 2>/dev/null; do
t=$(cat "$lock" 2>/dev/null)
if [ -z "$t" ]; then empty=$((empty + 1)); else empty=0; fi
if _mem_stale "$t" "$empty"; then _mem_steal "$lock"; fi
tries=$((tries + 1))
[ "$tries" -lt "${MEM_LOCK_TRIES:-50}" ] \
|| { echo "memory: lock busy: $lock" >&2; return 2; }
sleep 0.2
done
}
_mem_unlock() { # → remove the lock only when it is ours
[ "$(cut -d' ' -f2 < "$1" 2>/dev/null)" = "$2" ] && rm -f "$1"
return 0
}
_mem_restore() { # → put the verified copy back if changed
[ -s "$1" ] || return 0
cmp -s "$1" "$2" && return 0
cat "$1" > "$2" && echo "memory: $2 restored" >&2
}
_mem_backed() { # [args…] → fn on a verified backup of ,
# restored when fn fails or a signal lands. Runs inside _mem_locked: the
# trap reads that frame's __mem_lock / __mem_tok (dynamic scope), and
# every name here is __-prefixed so fn's own locals never shadow it.
local __mem_bak __mem_file="$2" __mem_old __mem_rc
__mem_bak=$(mktemp) || { echo "memory: no temp file" >&2; return 2; }
if ! { cat "$2" > "$__mem_bak" && cmp -s "$2" "$__mem_bak"; }; then
rm -f "$__mem_bak"; echo "memory: backup of $2 failed, nothing written" >&2
return 2
fi
__mem_old=$(trap -p INT TERM HUP)
trap '_mem_restore "$__mem_bak" "$__mem_file"
_mem_unlock "$__mem_lock" "$__mem_tok"; exit 130' INT TERM HUP
"$@"; __mem_rc=$?
trap - INT TERM HUP; eval "$__mem_old"
[ "$__mem_rc" = 0 ] || _mem_restore "$__mem_bak" "$__mem_file"
rm -f "$__mem_bak"
return "$__mem_rc"
}
_mem_locked() { # [args…] → fn under the lock, its rc; fn's
local __mem_lock __mem_tok out rc # stdout is printed after the unlock
__mem_lock=$(_mem_lock_path); __mem_tok="$$.$RANDOM"
out=$(mktemp) || { echo "memory: no temp file" >&2; return 2; }
_mem_lock "$__mem_lock" "$__mem_tok" || { rm -f "$out"; return 2; }
_mem_backed "$@" > "$out"; rc=$?
_mem_unlock "$__mem_lock" "$__mem_tok"
cat "$out"; rm -f "$out"
return "$rc"
}
_mem_one_line() { # → rc 2 when empty or multi-line
case "$2" in
''|*$'\n'*) echo "memory: $1 must be one non-empty line" >&2; return 2 ;;
esac
}
_mem_insert() { # [exact] → line ends the section,
local tmp # rc 1 if absent; exact: the heading is `## ` alone
tmp=$(mktemp) || { echo "memory: no temp file" >&2; return 2; }
MEM_K="$2" MEM_INS="$3" MEM_X="${4:-}" awk "$_MEM_AWK"'
BEGIN { k = ENVIRON["MEM_K"]; ins = ENVIRON["MEM_INS"]
x = ENVIRON["MEM_X"] != "" }
function hit(l) { return x ? l == "## " k : mem_key(l, k) }
function flush( i) { print ins; for (i = 1; i <= n; i++) print buf[i]
n = 0; done = 1 }
/^```/ { fence = !fence }
on && !fence && /^## / { flush(); on = 0 }
!done && !on && !fence && hit($0) { on = 1; print; next }
on { if ($0 == "" || $0 == "---") { buf[++n] = $0; next }
for (i = 1; i <= n; i++) print buf[i]; n = 0; print; next }
{ print }
END { if (on) flush(); exit !done }' "$1" > "$tmp"
case $? in
0) cat "$tmp" > "$1" || {
echo "memory: write-back of $1 failed; full copy kept: $tmp" >&2
return 2; } ;;
*) rm -f "$tmp"; return 1 ;;
esac
rm -f "$tmp"
}
_mem_status_text() { # → rc 2 unless it starts with a status word
local w
w=$(tr '[:upper:]' '[:lower:]' <<< "${1%%[^A-Za-z]*}")
case " $_MEM_WORDS " in *" $w "*) [ -n "$w" ] && return 0 ;; esac
echo "memory: status text starts with a status word: $_MEM_WORDS" >&2
return 2
}
memory_status() { #
local file rc
_mem_one_line "status text" "$2" || return 2
_mem_status_text "$2" || return 2
file=$(_mem_id_file "$1") || return 2
[ -f "$file" ] || { echo "memory: no registry: $file" >&2; return 2; }
_mem_locked _mem_insert "$file" "$1" "- **Status ($(_mem_date))**: $2"
rc=$?
case "$rc" in
0) return 0 ;;
1) echo "memory: no entry $1 in $file" >&2 ;;
*) echo "memory: $1 status not written" >&2 ;;
esac
return 2
}
_mem_journal_locked() { #
local sep=$'\n' # exactly one blank line before a new heading
_mem_insert "$1" "$2" "$3" exact
case $? in
1) [ -s "$1" ] || sep=''
[ -z "$(tail -c1 "$1")" ] || sep=$'\n\n'
[ -n "$(tail -n1 "$1")" ] || sep=''
printf '%s## %s\n%s\n' "$sep" "$2" "$3" >> "$1" ;;
0) return 0 ;;
*) return 2 ;;
esac
}
memory_journal() { # → `- ` under today's heading
local file=.claude/memory/journal.md line="$1"
_mem_one_line "journal line" "$line" || return 2
[ -f "$file" ] || { echo "memory: no $file" >&2; return 2; }
case "$line" in '- '*) ;; *) line="- $line" ;; esac
_mem_locked _mem_journal_locked "$file" "$(_mem_date)" "$line" \
|| { echo "memory: journal line not written" >&2; return 2; }
}
_mem_body_heading() { # → rc 2 on an unfenced `## ` line: it
local n # would split the entry (the checks read it as a heading)
n=$(awk '/^```/ { fence = !fence; next }
!fence && /^## / { print NR; exit }' "$1")
[ -z "$n" ] || {
echo "memory: add: body line $n starts with \"## \":" \
"use \"###\" or indent it" >&2; return 2; }
}
_mem_add_valid() { #
_mem_one_line title "$2" || return 2
case "$2$4" in *'['*|*']'*|*'|'*)
echo "memory: title and status take no [ ] |" >&2; return 2 ;;
esac
[ "${#2}" -le 160 ] || { echo "memory: title over 160 chars" >&2; return 2; }
case "$4" in *$'\n'*) _mem_one_line status "$4"; return 2 ;; esac
[ -z "$4" ] || _mem_status_text "$4" || return 2
[ -s "$3" ] || { echo "memory: empty or missing body: $3" >&2; return 2; }
! _mem_fence_open "$3" \
|| { echo "memory: body leaves a code fence open" >&2; return 2; }
_mem_body_heading "$3" || return 2
if [ "$1" = BLK ] && ! "$MEM_GREP" -q '`' "$3"; then
echo "memory: a blocker body quotes ≥1 error in backticks" >&2; return 2
fi
case "$5" in ''|"$1"-[0-9]*) ;; *)
echo "memory: --supersedes takes a $1 ID: $5" >&2; return 2 ;;
esac
}
_mem_entry_text() { #
local tag="" # v1: the status is a body line (the v1 reconcile reader
[ -z "$3" ] || [ -n "$5" ] || tag=" [$3]" # never reads the heading)
printf '%s%s (%s)\n' "$1" "$tag" "$(_mem_date)"
[ -z "$3" ] || [ -z "$5" ] || printf -- '- **Status**: %s\n' "$3"
awk '{ l[NR] = $0 } END { n = NR; while (n > 0 && l[n] == "") n--
for (i = 1; i <= n; i++) print l[i] }' "$2"
[ -z "$4" ] || printf 'Supersedes [[%s]].\n' "$4"
}
_mem_add_locked() { #
local f="$1" id pre rc=0 # runs under _mem_locked: failure = restore
if _mem_fence_open "$f"; then
echo "memory: $f leaves a code fence open; fix it first" >&2; return 2
fi
id=$(_mem_next_id "$f" "$2")
if _mem_heading_has "$f" "$id"; then
echo "memory: $id already in a heading of $f" >&2; return 2
fi
pre=$(mktemp) || { echo "memory: no temp file" >&2; return 2; }
cat "$f" > "$pre"
{ printf '\n## %s — ' "$id"; cat "$3"; } >> "$f" || rc=2
if [ "$rc" = 0 ] && [ -n "$4" ]; then
_mem_insert "$f" "$4" "- **Status ($(_mem_date))**: superseded by $id" \
|| rc=2
fi
if [ "$rc" = 0 ] && memory_is_v2 "$f"; then
memory_check_file "$f" "$2" "$pre" || rc=2
fi
rm -f "$pre"
[ "$rc" = 0 ] && echo "$id"
return "$rc"
}
_mem_path_safe() { # → path, ./-prefixed when awk would take it for
# a `var=value` assignment operand and read stdin instead
if [[ "$1" =~ ^[A-Za-z_][A-Za-z0-9_]*= ]]; then
printf '%s\n' "./$1"
else
printf '%s\n' "$1"
fi
}
memory_add() { #
local spec file entry rc v1=""
set -- "$1" "$2" "$(_mem_path_safe "$3")" "$4" "$5"
spec=$(_mem_kind "$1") || return 2
file=".claude/memory/${spec% *}"
_mem_add_valid "${spec#* }" "$2" "$3" "$4" "$5" || return 2
[ -f "$file" ] || { echo "memory: no registry: $file" >&2; return 2; }
[ -z "$5" ] || _mem_has_id "$file" "$5" \
|| { echo "memory: no entry $5 in $file" >&2; return 2; }
memory_is_v2 "$file" || {
v1=1; echo "memory: v1 registry (no format: 2): $file" >&2; }
entry=$(mktemp) || { echo "memory: no temp file" >&2; return 2; }
_mem_entry_text "$2" "$3" "$4" "$5" "$v1" > "$entry"
_mem_locked _mem_add_locked "$file" "${spec#* }" "$entry" "$5"; rc=$?
rm -f "$entry"
return "$rc"
}
_mem_add_cli() { # --title t --body-file f [--status s] [--supersedes I]
local kind="${1:-}" title="" body="" st="" sup=""
[ $# -gt 0 ] && shift
while [ $# -gt 0 ]; do
[ $# -ge 2 ] || { echo "memory: add: $1 needs a value" >&2; return 2; }
case "$1" in
--title) title="$2" ;;
--body-file) body="$2" ;;
--status) st="$2" ;;
--supersedes) sup="$2" ;;
*) echo "memory: add: unknown option: $1" >&2; return 2 ;;
esac
shift 2
done
memory_add "$kind" "$title" "$body" "$st" "$sup"
}
_mem_culprits() { # → "\t" per culprit
awk -v p="$2" '
/^```/ { fence = !fence; next }
fence { next }
$0 == "## Index" { print NR "\t## Index in a v2 registry" }
!match($0, "^## " p "-[0-9]") { next }
!match($0, "^## " p "-[0-9][0-9][0-9]+ — .") {
print NR "\theading shape: " $0; next }
seen[$2]++ { print NR "\tduplicate " $2 }
END { if (fence) print NR "\tcode fence open at end of file" }' "$1"
}
memory_check_file() { # [] [] → rc 2 on a
# culprit. With a reference only culprits absent from it count (a merge
# duplicate never blocks the next append); an open fence always counts
local p="$2" ref="${3:-/dev/null}" name="${4:-$1}"
[ -s "$ref" ] || ref=/dev/null
awk -F'\t' -v f="$name" '
FILENAME == ARGV[1] { old[$2]++; next }
$2 !~ /^code fence/ && old[$2]-- > 0 { next }
{ print "memory: " f ":" $1 ": " $2; bad = 1 }
END { exit bad ? 2 : 0 }' \
<(_mem_culprits "$ref" "$p") <(_mem_culprits "$1" "$p") >&2
}
memory_check() { # [--staged] [] → rc 2 on any culprit
local staged="" dir f rc=0
[ "${1:-}" = --staged ] && { staged=1; shift; }
dir="${1:-.claude/memory}"
[ $# -le 1 ] && [ "${dir#-}" = "$dir" ] || { echo "usage: memory.sh" \
"check [--staged] [dir]" >&2; return 2; }
dir=$(_mem_path_safe "$dir")
[ -n "$staged" ] || [ -d "$dir" ] \
|| { echo "memory: no memory dir: $dir" >&2; return 2; }
case "$staged:$dir" in 1:/*|1:..|1:../*|1:*/../*|1:*/..)
echo "memory: check --staged takes a repo-relative dir: $dir" >&2
return 2 ;;
esac
for f in $(_mem_names); do
f="$dir/$f.md"
if [ -n "$staged" ]; then _mem_check_staged "$f" || rc=2; continue; fi
[ -f "$f" ] || continue
if ! memory_is_v2 "$f"; then echo "memory: v1: $f" >&2; continue; fi
memory_check_file "$f" "$(_mem_prefix "$f")" || rc=2
done
return "$rc"
}
_mem_blob() { # → rc 1 when absent, rc 2 when
# unreadable; the out file is empty on either
git cat-file -e "$1" 2>/dev/null || { : > "$2"; return 1; }
git cat-file blob "$1" > "$2" 2>/dev/null || { : > "$2"; return 2; }
}
_mem_check_next_ids() { # → rc 2
# when an unfenced new `## P-n` entry is not 1 + the max ID seen so far
# (HEAD, then the staged file above it; every level, fenced or not)
awk -v f="$1" -v p="$2" '
FNR == 1 { fence = 0 }
/^```/ { fence = !fence }
FILENAME == ARGV[1] {
if (!fence && match($0, "^## " p "-[0-9][0-9][0-9]+ — .")) {
match($0, "^## " p "-[0-9]+"); entry[substr($0, 4, RLENGTH - 3)] = 1
known = 1 }
if (match($0, "^#+ *" p "-[0-9]+")) bump()
next }
!known { exit 0 }
!fence && match($0, "^## " p "-[0-9]+") {
tok = substr($0, 4, RLENGTH - 3); n = tok; sub(/^[A-Z]+-/, "", n)
if (!(tok in entry) && n + 0 != top + 1) {
printf "memory: %s:%d: new entry %s is not the next free ID " \
"%s-%03d\n", f, FNR, tok, p, top + 1; exit 2 } }
match($0, "^#+ *" p "-[0-9]+") { bump() }
function bump( n) {
n = substr($0, RSTART, RLENGTH); sub(/^#+ *[A-Z]+-/, "", n)
if (n + 0 > top) top = n + 0 }' "$3" "$4" >&2
}
_mem_check_staged() { # → rc 2 on a new culprit or a lost v2 file
local h s rc=0 hrc src
h=$(mktemp) || { echo "memory: no temp file" >&2; return 2; }
s=$(mktemp) || { rm -f "$h"; echo "memory: no temp file" >&2; return 2; }
_mem_blob "HEAD:./$1" "$h"; hrc=$?
_mem_blob ":./$1" "$s"; src=$?
if [ "$hrc" = 2 ] || [ "$src" = 2 ]; then
echo "memory: $1: cannot read the HEAD or the staged blob" >&2; rc=2
elif [ -s "$h" ] && memory_is_v2 "$h" \
&& ! { [ -s "$s" ] && memory_is_v2 "$s"; }
then
echo "memory: $1: staged deletion, emptying or loss of format: 2" >&2
rc=2
elif [ -s "$s" ] && memory_is_v2 "$s"; then
memory_check_file "$s" "$(_mem_prefix "$1")" "$h" "$1" || rc=2
_mem_removed_lines "$1" "$h" || rc=2
[ "$hrc" = 0 ] && memory_is_v2 "$h" && ! _mem_fence_open "$h" \
&& { _mem_check_next_ids "$1" "$(_mem_prefix "$1")" "$h" "$s" || rc=2; }
fi
rm -f "$h" "$s"
return "$rc"
}
_mem_removed_lines() { # → rc 2 when a hunk removes an
local p first # entry line (an Index sits above the first entry)
[ -s "$2" ] || return 0
p=$(_mem_prefix "$1" 2>/dev/null) || return 0
first=$(awk -v p="$p" '/^```/ { fence = !fence; next }
!fence && match($0, "^## " p "-[0-9]") { print NR; exit }' "$2")
[ -n "$first" ] || return 0
git -c diff.interHunkContext=0 diff --cached --no-color --no-ext-diff \
--no-textconv -U0 -- "$1" | awk -v first="$first" -v f="$1" '
/^@@ / { split($2, a, ","); start = substr(a[1], 2) + 0
cnt = (2 in a) ? a[2] + 0 : 1
if (cnt > 0 && start + cnt - 1 >= first) {
print "memory: " f ": line " start " removed inside an entry" \
" (fix it, then commit with /commit-change)"
bad = 1 } }
END { exit bad ? 2 : 0 }' >&2
}
_mem_index_rows() { # → "| ID | date | title | word |" rows
awk -v p="$2" -v MEMW="$_MEM_WORDS" "$_MEM_AWK"'
function row() { if (id != "") print "| " id " | " d " | " t " | " s " |" }
/^```/ { fence = !fence; next }
fence { next }
/^## / { row(); id = ""
if (!match($0, "^## " p "-[0-9]+")) next
id = $2; t = $0; sub(/^## [^ ]+( — )?/, "", t); d = ""
s = mem_word(mem_tag(t))
if (match(t, / \([0-9-]+\) *$/)) {
d = substr(t, RSTART + 2, RLENGTH - 3); t = substr(t, 1, RSTART - 1) }
else if (match(t, / — [0-9][0-9][0-9][0-9]-[0-9-]+ *$/)) {
d = substr(t, RSTART); t = substr(t, 1, RSTART - 1)
sub(/^ — /, "", d) }
sub(/ \[[^]]*\] *$/, "", t); gsub(/\|/, "/", t); next }
id == "" { next }
d == "" && sub(/^- \*\*Date\*\* *: */, "") { d = substr($0, 1, 10) }
(w = mem_cand($0)) != "" { s = w }
END { row() }' "$1"
}
_mem_index_dir() { # → 1 (stderr) when .claude/memory cannot be searched
local d=.claude/memory
if [ -e "$d" ] || [ -L "$d" ]; then
{ [ -d "$d" ] && [ -x "$d" ]; } && return 0
else
[ ! -d .claude ] || [ -x .claude ] && return 0
fi
echo "memory: $d: not a searchable directory" >&2
return 1
}
_mem_index_one() { # → 0 read or absent, 1 bad (stderr)
local file=$1 rows
[ -e "$file" ] || [ -L "$file" ] || return 0
if [ ! -f "$file" ] || ! rows=$(_mem_index_rows "$file" "$2"); then
echo "memory: $file: not a readable regular file" >&2
return 1
fi
printf '%s\n\n| ID | Date | Title | Status |\n|---|---|---|---|\n' "$file"
[ -n "$rows" ] && printf '%s\n' "$rows"
echo
}
memory_index() { # [] → one table per registry
local kinds k spec strict=${1:+1}
kinds=${1:-$(awk '{ print $1 }' <<< "$_MEM_TABLE")}
if ! _mem_index_dir; then
[ -n "$strict" ] && return 2
return 0
fi
for k in $kinds; do
spec=$(_mem_kind "$k") || return 2
_mem_index_one ".claude/memory/${spec% *}" "${spec#* }" && continue
[ -n "$strict" ] && return 2
done
return 0
}
_mem_index_table() { # → "IDdatelast column" per Index row
awk '$0 == "## Index" { on = 1; next }
on && /^## / { exit }
on && /^\| *[A-Z]+-[0-9]+ *\|/ {
n = split($0, c, "|")
for (i = 2; i < n; i++) gsub(/^ +| +$/, "", c[i])
print c[2] "\t" c[3] "\t" c[n - 1] }' "$1"
}
_mem_upgrade_text() { # → the v2 text on stdout
awk -v p="$3" -v today="$(_mem_date)" -v MEMW="$_MEM_WORDS" "$_MEM_AWK"'
function clean(x) { gsub(/[[:cntrl:]]/, "?", x); return x }
function flush( i, s, w, v) {
w = mem_word(col[cur]); v = vw[cur]
if (cur != "" &&
(s = mem_want(p, col[cur], mem_est(st[cur], v))) != "")
print "- **Status (" today ", upgrade)**: " clean(s)
else if (cur != "" && st[cur] == "" && v != "" && v != "mixed") {
print "- **Status (" today ", upgrade)**: " v
if (w != "" && w != v)
print "memory: " cur ": kept body " v ", dropped Index " \
clean(col[cur]) > "/dev/stderr" }
else if (cur != "" && w != "" && p !~ /^(LRN|EVAL)$/ && w != st[cur])
print "memory: " cur ": kept body " st[cur] ", dropped Index " \
clean(col[cur]) > "/dev/stderr"
for (i = 1; i <= n; i++) print buf[i]
n = 0 }
FILENAME == ARGV[1] { split($0, r, "\t"); dt[r[1]] = r[2]
col[r[1]] = r[3]; next }
FILENAME == ARGV[2] { split($0, r, / \| /); sub(/^\| /, "", r[1])
sub(/ \|$/, "", r[4]); hd[r[1]] = r[2] != ""; st[r[1]] = r[4]
next }
FILENAME == ARGV[3] { split($0, r, "\t"); vw[r[1]] = r[2]; next }
FNR == 1 { print; print "format: 2"; next }
/^```/ { fence = !fence }
$0 == "## Index" { skip = 1; next }
skip { if (/^\|/) { tbl = 1; next }
if (tbl) { skip = 0; if ($0 == "") next }
else if ($0 ~ /^#/ || $0 == "---") skip = 0
else next }
!fence && /^## / { flush(); split($0, w, " ")
cur = (w[2] in col) ? w[2] : ""; print
if (cur != "" && !hd[cur] && dt[cur] != "") print "- **Date**: " dt[cur]
next }
cur != "" && ($0 == "" || $0 == "---") { buf[++n] = $0; next }
{ for (i = 1; i <= n; i++) print buf[i]; n = 0; print }
END { flush() }' "$1" <(_mem_index_rows "$2" "$3") \
<(_mem_v1_words "$4" "$3") "$2"
}
_mem_heading_ids() { # → the entry IDs, any heading level
"$MEM_GREP" -oE "^#+ *$2-[0-9]+" "$1" | sed 's/^#* *//'
}
_MEM_LEGACY_BLK_RE='status|RESOLVED|REVERTED|upstream|resolved|[^a-z]open'
# v1 decisions carry `**Statut** :` and `Superseded by …` lines the blocker
# selector skips; an unlabelled winner stays unreadable (_mem_v1_word)
_MEM_LEGACY_BDR_RE="$_MEM_LEGACY_BLK_RE|statut|superseded|deprecated"
memory_legacy_status() { # [] → the v1 lexical status line
# (reconcile reads it on a v1 file; `upgrade` proves its verdicts against
# it). selects the line (default: the blocker selector). The range
# is fence-aware: from `## ID` to the next heading of another ID of the
# same prefix or to `## Index`, that heading not read; a same-ID
# sub-heading (`### ID UPDATE`) continues the range, unread.
local file
file=$(_mem_path_safe "$1")
RE="${3:-$_MEM_LEGACY_BLK_RE}" END_RE="^##* *${2%%-*}-[0-9]" \
awk -v id="$2" '
/^```/ { fence = !fence; next }
!fence && $0 ~ ("^#+ *" id "( |$)") && on { next }
!fence && $0 == "## Index" { on = 0 }
!fence && $0 ~ ENVIRON["END_RE"] { on = 0 }
!fence && $0 ~ "^## " id " " { on = 1; next }
on && !fence && tolower($0) ~ tolower(ENVIRON["RE"]) { last = $0 }
END { if (last != "") print last }' "$file"
}
_mem_legacy_open() { # → rc 0 when reconcile's v1 reader
local st # lists the blocker open (its status is not RESOLVED);
# upgrade reads the entry's own range, up to a heading of any level
st=$(memory_legacy_status "$1" "$2")
case "$st" in *RESOLVED*|*resolved*) return 1 ;; esac
}
_mem_v1_words() { # → "IDword|mixed" for each Index ID
# the strict reader finds no word for, when a v1 status/statut label of
# its body (anchored: line start, ` · ` or `| `) is there; `mixed` =
# label without exactly one word. Blocker and decision selectors only.
local id re line word
case "$2" in
BLK) re=$_MEM_LEGACY_BLK_RE ;;
BDR) re=$_MEM_LEGACY_BDR_RE ;;
*) return 0 ;;
esac
while read -r id; do
line=$(memory_legacy_status "$1" "$id" "$re")
[[ "$line" =~ ^(-\ )?(\*\*)?[Ss]tatu[st]|(\ ·\ |\|\ )[Ss]tatu[st] ]] \
|| continue
word=$(_mem_v1_word "$line")
printf '%s\t%s\n' "$id" "${word:-mixed}"
done < <(awk -F'\t' 'FILENAME == ARGV[1] { ix[$1] = 1; next }
{ split($0, a, / \| /); sub(/^\| /, "", a[1]); sub(/ \|$/, "", a[4])
if (a[1] in ix && a[4] == "") print a[1] }' \
<(_mem_index_table "$1") <(_mem_index_rows "$1" "$2"))
}
_mem_index_stated() { # → IDs whose Index status upgrade
# writes into the body (mem_want): a fact the v1 reader never saw
awk -F'\t' -v p="$2" -v MEMW="$_MEM_WORDS" "$_MEM_AWK"'
FILENAME == ARGV[1] { col[$1] = $3; next }
FILENAME == ARGV[2] { vw[$1] = $2; next }
{ split($0, a, / \| /); id = a[1]; sub(/^\| /, "", id); s = a[4]
sub(/ \|$/, "", s)
if (id in col && vw[id] != "mixed" &&
mem_want(p, col[id], mem_est(s, vw[id])) != "") print id }' \
<(_mem_index_table "$1") <(_mem_v1_words "$1" "$2") \
<(_mem_index_rows "$1" "$2")
}
_mem_explicit_status() { # → rc 0 when the v1 line is a
local v1 win # dated status line written by `memory.sh status`, which
v1=$(memory_legacy_status "$1" "$3") # the strict
win=$(memory_entry_status "$2" "$3") # reader rightly wins
[ "$v1" = "$win" ] || return 1
printf '%s\n' "$v1" | "$MEM_GREP" -qE '^- \*\*Status \([0-9]' || return 1
case "$v1" in *", upgrade)"*) return 1 ;; esac
}
_mem_verdict_diff() { # → "IDword" per blocker whose open /
local id was now ix # closed verdict moved (word = the old verdict, or
ix=$(_mem_index_stated "$1" BLK) # `explicit`: a dated status line)
for id in $(_mem_heading_ids "$2" BLK | awk '!seen[$0]++'); do
printf '%s\n' "$ix" | "$MEM_GREP" -qx "$id" && continue
# the v1 reader enumerates `## ID` headings only: no verdict to keep
"$MEM_GREP" -qE "^## $id( |$)" "$1" || continue
_mem_legacy_open "$1" "$id" && was=open || was=resolved
memory_closed "$(memory_status_word "$(memory_entry_status "$2" "$id")")" \
&& now=resolved || now=open
[ "$was" = "$now" ] && continue
[ "$was" = resolved ] && _mem_explicit_status "$1" "$2" "$id" \
&& was=explicit
printf '%s\t%s\n' "$id" "$was"
done
}
_mem_v1_word() { # → the one status word of its status/statut
# label (e.g. `status: resolved`), nothing for prose or a mixed label
L="$1" MEMW="$_MEM_WORDS" awk "$_MEM_AWK"'BEGIN {
s = tolower(ENVIRON["L"]); n = split(ENVIRON["MEMW"], w, " ")
if (!match(s, /(status|statut)[^a-z:]*:[* ]*/)) exit
s = substr(s, RSTART + RLENGTH)
for (i = 1; i <= n; i++)
if (mem_has(s, w[i])) { c++; word = w[i] }
if (c == 1) print word }'
}
_mem_repair_one() { # → write the v1 closure when its line
local v1 word # names one closed word, else name the ID and refuse
v1=$(memory_legacy_status "$1" "$3")
word=$(_mem_v1_word "$v1")
# foreign bytes never reach the terminal; under a C locale UTF-8 bytes
# are not printable either and degrade to `?` in this echo only
v1=${v1//[![:print:]]/?}
if ! memory_closed "$word"; then
echo "memory: $3: v1 closed by an unlabelled, mixed or negated line," \
"status unknown: ${v1:0:100}" >&2
echo "memory: $3: record it from the project root: memory.sh status" \
"$3 \", …\" (the leading word decides), then re-run upgrade" >&2
return 0
fi
echo "memory: $3: wrote upgrade status $word from v1 line: ${v1:0:100}" >&2
_mem_insert "$2" "$3" "- **Status ($(_mem_date), upgrade)**: $word" \
|| return 2
}
_mem_upgrade_repair() { # → no blocker loses its closure
# v1 closed, strict reader open (a dialect it cannot read): a labelled v1
# line restores it, prose or a mixed label is named and left to the oracle.
# v1 open, strict closed is the BLK-032..034 fix (prose words read as
# status by the v1 reader): kept, named. The diff is read in full before
# the first insert rewrites the file under it
local id word rows
[ "$3" = BLK ] || return 0
rows=$(_mem_verdict_diff "$1" "$2")
[ -n "$rows" ] || return 0
while IFS=$'\t' read -r id word; do
case "$word" in
open) echo "memory: $id: v1 reader open, strict reader closed (kept)" \
>&2 ;;
explicit) echo "memory: $id: dated status line kept, v1 reader closed" \
"by prose" >&2 ;;
*) _mem_repair_one "$1" "$2" "$id" || return 2 ;;
esac
done <<< "$rows"
}
_mem_upgrade_oracle() { # → rc 2 on a lost fact
local o n
[ "$(_mem_heading_ids "$1" "$3")" = "$(_mem_heading_ids "$2" "$3")" ] \
|| { echo "memory: upgrade changed the entry IDs: $1" >&2; return 2; }
memory_check_file "$2" "$3" "" "$1" || return 2
o=$(_mem_index_rows "$1" "$3"); n=$(_mem_index_rows "$2" "$3")
awk -F'\t' -v p="$3" -v MEMW="$_MEM_WORDS" "$_MEM_AWK"'
function f(s, k) { split(s, a, / \| /); return a[k] }
FILENAME == ARGV[1] { dt[$1] = $2; col[$1] = $3; next }
FILENAME == ARGV[2] { vw[$1] = $2; next }
{ id = f($0, 1); sub(/^\| /, "", id) }
FILENAME == ARGV[3] { old[id] = f($0, 4); sub(/ \|$/, "", old[id]); next }
!(id in col) { next }
{ d = f($0, 2); s = f($0, 4); sub(/ \|$/, "", s)
e = mem_est(old[id], vw[id]); m = mem_want(p, col[id], e)
want = m != "" ? mem_word(m) : e
if (dt[id] != "" && d == "") bad = bad " " id ":date"
if (want != "" && p != "BLK" && s != want)
bad = bad " " id ":" s "!=" want }
END { if (bad != "") { print "memory: upgrade lost:" bad; exit 2 } }' \
<(_mem_index_table "$1") <(_mem_v1_words "$1" "$3") \
<(printf '%s\n' "$o") \
<(printf '%s\n' "$n") >&2 || return 2
o=$(_mem_verdict_diff "$1" "$2" | awk -F'\t' '$2 == "resolved" \
{ printf "%s ", $1 }')
[ -z "$o" ] || { echo "memory: upgrade moved a verdict: $o" >&2; return 2; }
_mem_upgrade_dups "$2" "$3"
}
_mem_upgrade_dups() { # → rc 2 when an entry holds two
local d # `, upgrade)` status lines
d=$(awk -v p="$2" '
/^```/ { fence = !fence }
fence { next }
$0 ~ "^## " p "-[0-9]+" { id = $2; next }
/^- \*\*Status \([^)]*, upgrade\)\*\*:/ && ++n[id] == 2 {
printf "%s:dup ", id }' "$1")
[ -z "$d" ] || { echo "memory: upgrade lost: $d" >&2; return 2; }
}
_mem_upgrade_front() { # → the file; one lacking a frontmatter gets
local t first # the template's (format: 2 is added with the rest)
IFS= read -r first < "$1"
if [ "$first" != --- ]; then
t="$_MEM_LIB_DIR/../templates/memory/${1##*/}"
[ -f "$t" ] || { echo "memory: no template for $1" >&2; return 2; }
awk 'NR > 1 && /^---$/ { print; print ""; exit }
$0 != "format: 2"' "$t"
fi
cat "$1"
}
_mem_upgrade_headings() { # → entry headings in the v2 shape
# `## ID — title` stays byte-identical; ` - ` and ` | date | ` separators
# and any other level are rewritten, the title text and the ID kept; a
# heading that would still not be v2 (`### ID amendment`) is left as is
awk -v p="$2" '
/^```/ { fence = !fence }
fence || !match($0, "^#+ *" p "-[0-9]+") { print; next }
{ lead = substr($0, 1, RLENGTH); rest = substr($0, RLENGTH + 1)
if (lead ~ /^## / && rest ~ /^ — ./) { print; next }
sub(/^#+ */, "", lead); d = ""
if (rest ~ /^ [|] /) { rest = substr(rest, 4)
if (match(rest, "^[0-9][0-9/-]* [|] ")) {
d = substr(rest, 1, RLENGTH - 3); rest = substr(rest, RLENGTH + 1) }
rest = " — " rest (d != "" ? " (" d ")" : "") }
else if (rest ~ /^ - /) rest = " — " substr(rest, 4)
cand = "## " lead rest
print (cand ~ "^## " p "-[0-9][0-9][0-9]+ — ." ? cand : $0) }' "$1"
}
_mem_upgrade_build() { # → the v2 text, blocker
local front src rows rc=0 # verdicts kept
front=$(mktemp); src=$(mktemp); rows=$(mktemp)
[ -n "$front" ] && [ -n "$src" ] && [ -n "$rows" ] \
|| { rm -f "$front" "$src" "$rows"; echo "memory: no temp file" >&2
return 2; }
{ _mem_upgrade_front "$1" > "$front" \
&& _mem_upgrade_headings "$front" "$2" > "$src" \
&& _mem_index_table "$src" > "$rows" \
&& _mem_upgrade_text "$rows" "$src" "$2" "$1" > "$3" \
&& _mem_upgrade_repair "$1" "$3" "$2"; } || rc=2
rm -f "$front" "$src" "$rows"
return "$rc"
}
_mem_index_only_table() { # → rc 1 when ## Index holds a non-table
awk '$0 == "## Index" { on = 1; next } # line outside a comment
!on { next }
cm { if (/-->/) cm = 0; next }
/^/) cm = 1; next }
/^\|/ { tbl = 1; next }
/^#/ || /^---$/ || (tbl && /^$/) { exit }
/^$/ { next }
{ bad = 1; exit }
END { exit bad }' "$1"
}
_mem_upgrade_ready() { # → rc 0 upgradable, 1 already v2, 2 refused
memory_is_v2 "$1" && { echo "memory: $1 already v2" >&2; return 1; }
_mem_index_only_table "$1" || { echo "memory: $1: ## Index is not a" \
"table, not upgraded" >&2; return 2; }
_mem_prefix "$1" > /dev/null
}
_mem_upgrade_file() { # → rc 0 upgraded or already v2, rc 2 refused
local p new rc=0
_mem_upgrade_ready "$1"; rc=$?
[ "$rc" = 1 ] && return 0
[ "$rc" = 0 ] || return 2
p=$(_mem_prefix "$1") || return 2
new=$(mktemp) || { echo "memory: no temp file" >&2; return 2; }
{ _mem_upgrade_build "$1" "$p" "$new" \
&& _mem_upgrade_oracle "$1" "$new" "$p" \
&& cat "$new" > "$1"; } || rc=2
rm -f "$new"
[ "$rc" = 0 ] && echo "memory: upgraded $1"
[ "$rc" = 0 ] || echo "memory: $1 left as it was" >&2
return "$rc"
}
memory_upgrade() { # [] → every template-born registry to v2
local dir="${1:-.claude/memory}" f rc=0
dir=$(_mem_path_safe "$dir")
for f in $(_mem_names); do
[ -f "$dir/$f.md" ] || continue
_mem_locked _mem_upgrade_file "$dir/$f.md" || rc=2
done
return "$rc"
}
_memory_main() {
set -uo pipefail
if [ "${1:-}" = "-C" ]; then
cd "${2:-}" 2>/dev/null \
|| { echo "memory: no dir ${2:-}" >&2; return 2; }
shift 2
fi
case "${1:-}:$#" in
add:*) shift; _mem_add_cli "$@" ;;
status:3) memory_status "$2" "$3" ;;
journal:2) memory_journal "$2" ;;
index:[12]) memory_index "${2:-}" ;;
check:*) shift; memory_check "$@" ;;
upgrade:[12]) memory_upgrade "${2:-}" ;;
*) echo "usage: memory.sh [-C dir] add --title t --body-file f" \
"[--status s] [--supersedes ID] | status | journal" \
" | index [kind] | check [--staged] [dir] | upgrade [dir]" >&2
return 2 ;;
esac
}
if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then _memory_main "$@"; fi