runbook: the M5a memory entries as the plan gave them

Found in the M5a review: task 13 renamed core-memory-unreadable to
memory-unavailable but kept its body, which still described
memory/core.md, and appended a memory-index-damaged entry of its own that
names a pointer memoryd never prints and leaves out `bxctl reindex`. Its
log row says both fragments were copied. Both entries are now the plan's
fragments, verbatim.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-09-25 21:02:32 -07:00
co-authored by Claude Opus 5.5
parent e963ef72bb
commit 96e319043e
+23 -31
View File
@@ -397,24 +397,25 @@ the cache was lost, which `loopd` logs as a cache loss.
## memory-unavailable ## memory-unavailable
**What you see.** Starting a new session fails with an error naming `memory/core.md`, and this **What you see.** Starting a new session fails with a line naming `memoryd` or a file under
entry. Existing sessions still work: they use the baseline saved when they started. `memory/`, and this entry. Existing sessions still work: they use the baseline saved when they
started.
**Why.** `memory/core.md` exists but cannot be read. A missing file is fine, but starting without **Why.** A new session's baseline takes the memory block from `memoryd` (`soul.md`, `memory.md`,
memory you wrote, and without telling you, is not. `user.md`), and `loopd` could not get it: `memoryd` is not running or not listening at
`<home>/run/loop-memory/memory.sock` (or `[memory] socket` in `loopd.toml`), or it refused because
a file is unreadable or over its limit (`soul.md` 4,000 characters, `memory.md` 2,200, `user.md`
1,375; an owner's edit can put it over). Starting without the memory the agent is, and without
telling you, is what this prevents.
**Confirm.** **Confirm.** `pgrep -x memoryd`; the line names the file or the socket. For a file,
`wc -m <home>/memory/<file>`.
```sh **Fix.** Start `memoryd serve --config <path>`, or shorten the file (for `memory.md` and `user.md`,
ls -l "$BOXMAKER_HOME/memory/core.md"; head -c 100 "$BOXMAKER_HOME/memory/core.md" move entries to `notes.md` by hand: an entry under a line `§ moved <time> from memory.md in session
``` owner`).
Look for wrong ownership or mode, or a file that is not UTF-8 text. **Check.** Start a new conversation; it answers.
**Fix.** Make it readable by the user `loopd` runs as (`chmod 0600` and `chown` to that user), or
save it again as UTF-8.
**Check.** A new session starts, and its `0.baseline.json` contains the text.
## gatewayd-start-failed ## gatewayd-start-failed
@@ -638,24 +639,15 @@ listening elsewhere, or is stuck.
## memory-index-damaged ## memory-index-damaged
**What you see.** `memoryd` exits 1 at start with `index: <reason>` naming its index file, then **What you see.** `recall` fails with a line starting `index:`, or `memoryd` logs one at start.
this entry.
**Why.** The index is the fast path to memory. If `memoryd` cannot read it, it does not know what **Why.** `index/memory.sqlite3` could not be read or written. It is disposable: everything in it
it has stored, so it stops rather than guess. A missing file is a first start and is fine. comes from `sessions/` and `memory/notes.md`.
**Confirm.** **Confirm.** `ls -l <home>/index/`; the end of `memoryd`'s log.
```sh **Fix.** `bxctl reindex`, which builds a new index beside the old one and replaces it. If that
ls -l "$BOXMAKER_HOME/index/memory.sqlite3" fails too, stop `memoryd`, move `index/memory.sqlite3` aside, and start `memoryd`, which rebuilds
python3 -c 'import sqlite3; sqlite3.connect("<path>").execute("SELECT count(*) FROM sqlite_master")' it.
```
**Fix.** Move it aside and start `memoryd`, which rebuilds it: **Check.** `bxctl reindex` prints how many logs, records and notes it read.
```sh
mv "$BOXMAKER_HOME/index/memory.sqlite3" "$BOXMAKER_HOME/index/memory.sqlite3.damaged"
memoryd serve --config <path>
```
**Check.** `memoryd serve --config <path>` prints `memoryd: serving`, and a `recall` call answers.