Skip to content

A team of long-lived bots for DeepSeek Harness, with main bots, bot-to-bot messages and group chats.

Recover interrupted memory writes with their journal records

klarkxyea86eb4226cb
diff --git a/docs/plans/2026-10-09-context-and-memory.md b/docs/plans/2026-10-09-context-and-memory.md
index 4c474b8c..7855bf76 100644
--- a/docs/plans/2026-10-09-context-and-memory.md
+++ b/docs/plans/2026-10-09-context-and-memory.md
@@ -84,6 +84,8 @@ Bot 是长期的:用户和一个 Bot 聊几周、几个月,上下文一定
| `groups/<群 id>/` | 群记忆:这个群的成员共享,只在这个群里读 |
| `team/` | 团队记忆,所有 Bot 都读 |
| `journal.jsonl` | 每一次改动,带改动前后的那一行 |
+| `journal.torn` | 写到一半的日志行:留着当证据,日志本身补好 |
+| `pending.json` | 一次还没写完的改动:先写下它要改哪些文件,写完才去掉 |
| `snapshots/` | 每个 Session 冻结的记忆段 |
| `summaries/` | 记忆面板给每个 Bot、每个群的摘要 |
| `archive/` | 已删除 Bot 和已删除群的记忆,整份 |
@@ -111,6 +113,8 @@ Bot 是长期的:用户和一个 Bot 聊几周、几个月,上下文一定
- 删除群时,群记忆整份移到 `archive/`,成员的群会话里冻结的记忆段一起作废。
- 三条路走同一个写入路径,一次只写一个,由持有团队的那个进程写。
- 历史不用 git:文件原地修改,`journal.jsonl` 记下每次改动替换了什么。
+- 一次改动会碰几个文件(条目、主题的 `## Index` 链接、`journal.jsonl` 那一行),先写 `pending.json` 记下这次要改什么,再改文件、最后写日志那一行。写一半被打断时,`pending.json` 留着,下次读或写记忆之前(或重启时)接着写完:条目不会没有日志那一行,主题也不会少了链接。同一行不会写两遍。
+- `journal.jsonl` 末尾可能有一行写到一半(写日志时被打断)。半行不算数:它挪到 `journal.torn` 留着当证据,日志本身补好,下一行另起一行。
**怎么用**:
@@ -141,3 +145,4 @@ Bot 是长期的:用户和一个 Bot 聊几周、几个月,上下文一定
- 2026-10-08:定记忆的格式、存放和「整理不用 git」。
- 2026-10-09:分段从「到线就换段」改为「管家判断压缩还是换段」;所有线改为跟着模型走。
- 2026-10-17:加群记忆(#151)。之前群里学到的东西只能进团队记忆,所有 Bot 都读,群外新建的 Bot 也会带上;现在群聊按群整理,只写群记忆。
+- 2026-10-23:加 `pending.json`,一次改动当成一次来做(#481)。之前文件先写、日志后写,中断会留下没有日志的条目,或没有链接的主题。
diff --git a/ds-bot/src/host/memory-pending.js b/ds-bot/src/host/memory-pending.js
new file mode 100644
index 00000000..61b81521
--- /dev/null
+++ b/ds-bot/src/host/memory-pending.js
@@ -0,0 +1,95 @@
+// The record of a memory change that is about to be published.
+//
+// A change touches more than one file (the entry, the Index that links a topic, the
+// change log), and each of them is written on its own, so an interruption can leave
+// half of it done: an entry without its row in the change log, a topic without its
+// link. This keeps the record of what the change will do, so the change can be
+// finished later instead of being half done.
+//
+// The record is written before the change is published, and it is what accepts the
+// change: before the record is there, nothing has changed. It holds the files to
+// write, the files to remove, and the row that goes with them in the change log, so
+// finishing a change later is the same work as publishing it in the first place.
+import { readFileSync } from 'node:fs'
+import { join, relative, resolve, sep } from 'node:path'
+
+// The record inside the memory folder.
+export const PENDING_FILE = 'pending.json'
+// A record that cannot be read or understood stops the memory: what it would have
+// changed is unknown, so nothing goes on until it is fixed.
+const PENDING = 'memory/pending'
+// A change is one entry, so its record stays small; a larger one was not written by
+// this.
+const MAX_BYTES = 1_048_576
+
+export function pendingPath(root) {
+ return join(root, PENDING_FILE)
+}
+
+// A path inside the memory folder, as the record holds it: relative, so the folder
+// can be moved, and never outside it.
+export function inside(root, path) {
+ const base = resolve(root)
+ const full = resolve(base, path)
+ if (full !== base && !full.startsWith(base + sep)) throw new Error(`the path ${path} is outside the memory folder`)
+ return full
+}
+
+// The path of a file in the memory folder, as the record holds it.
+export function relativePath(root, path) {
+ return relative(resolve(root), resolve(path)).split(sep).join('/')
+}
+
+// The record of a change: what it does, and the row that goes with it.
+export function record({ id, time, op, scope, steps, row }) {
+ return { id, time, op, scope, steps, row: { time, id, ...row } }
+}
+
+// The record of a change, as it is written down. A record that would be too large is
+// refused: the memory folder holds one change at a time, and a record that cannot be
+// read back would stop the memory for good. The size is the same one the read side
+// uses, so a record that is written can always be read.
+export function serialize(record) {
+ const text = JSON.stringify(record)
+ const size = Buffer.byteLength(text)
+ if (size > MAX_BYTES) {
+ throw Object.assign(new Error(`The memory change is too large to record (${size} of ${MAX_BYTES} bytes). Make the memory file smaller first.`), { code: 'memory/too-large' })
+ }
+ return text
+}
+
+// The record waiting to be finished, if there is one. A record that cannot be read
+// or understood is an error, not an empty record: the change it holds is unknown,
+// and a change that is half done must not be passed over.
+export function read(root) {
+ const path = pendingPath(root)
+ let text
+ try {
+ text = readFileSync(path, 'utf8')
+ } catch (error) {
+ if (error?.code === 'ENOENT') return undefined
+ throw Object.assign(new Error(`${PENDING_FILE} could not be read (${error?.code ?? error?.message})`), { code: PENDING })
+ }
+ if (Buffer.byteLength(text) > MAX_BYTES) {
+ throw Object.assign(new Error(`${PENDING_FILE} is larger than a memory change record`), { code: PENDING })
+ }
+ let value
+ try {
+ value = JSON.parse(text)
+ } catch (error) {
+ throw Object.assign(new Error(`${PENDING_FILE} is not readable (${error.message})`), { code: PENDING })
+ }
+ if (!wellFormed(value)) throw Object.assign(new Error(`${PENDING_FILE} is not a memory change record`), { code: PENDING })
+ return value
+}
+
+const wellFormed = (value) => {
+ if (value === null || typeof value !== 'object' || Array.isArray(value)) return false
+ if (typeof value.id !== 'string' || value.id === '') return false
+ if (typeof value.op !== 'string' || typeof value.scope !== 'string') return false
+ if (!Array.isArray(value.steps) || value.steps.length === 0) return false
+ if (!value.steps.every(step => step !== null && typeof step === 'object' && typeof step.path === 'string' && step.path !== ''
+ && (step.action === 'remove' ? step.text === undefined : step.action === 'write' && typeof step.text === 'string'))) return false
+ if (value.row === null || typeof value.row !== 'object' || Array.isArray(value.row)) return false
+ return typeof value.row.id === 'string' && value.row.id !== ''
+}
diff --git a/ds-bot/src/host/memory.js b/ds-bot/src/host/memory.js
index 41092863..1116d73a 100644
--- a/ds-bot/src/host/memory.js
+++ b/ds-bot/src/host/memory.js
@@ -23,13 +23,14 @@
// memory section the first time it renders, so its prompt stays byte-stable and the
// provider's prefix cache holds; a fresh part, or a checkpoint (which breaks the cache
// anyway), freezes it anew.
-import { createHash } from 'node:crypto'
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { createHash, randomUUID } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, truncateSync, unlinkSync, writeFileSync } from 'node:fs'
import { appendFile, mkdir, rename, unlink, writeFile } from 'node:fs/promises'
import { dirname, join } from 'node:path'
import { BlockAssembler } from '@deepseek-ai/dsh-llm'
import { defineTool } from '@deepseek-ai/dsh-tools'
import { replaceFile } from './files.js'
+import { inside, pendingPath, read as readPending, record as pendingRecord, relativePath, serialize as serializePending } from './memory-pending.js'
import { splitRef, unquote } from './text.js'
import { speakerOf } from '../shared/mentions.js'
import { output } from './tools.js'
@@ -453,6 +454,8 @@ export function install(rt) {
const reviewOn = config.memoryReview !== false
const root = join(home, 'memory')
const journalPath = join(root, 'journal.jsonl')
+ // The half-written row of the change log, kept beside it as the evidence it is.
+ const tornPath = join(root, 'journal.torn')
const dayFormat = new Intl.DateTimeFormat('en-CA', { ...(config.timeZone ? { timeZone: config.timeZone } : {}), year: 'numeric', month: '2-digit', day: '2-digit' })
const today = () => dayFormat.format(Date.now())
@@ -510,16 +513,147 @@ export function install(rt) {
await writeFile(temp, text, 'utf8')
await replaceFile(temp, path)
}
- async function journal(record) {
- await mkdir(root, { recursive: true })
- await appendFile(journalPath, `${JSON.stringify({ time: new Date().toISOString(), ...record })}\n`, 'utf8')
- }
let writing = Promise.resolve()
const queued = (job) => {
const run = writing.then(job)
writing = run.catch(() => {})
return run
}
+
+ // ---------------------------------------------------------------------------
+ // Publishing a change.
+ //
+ // A change touches more than one file (the entry, the Index that links a topic, the
+ // change log), and each of them is written on its own, so an interruption can leave
+ // half of it done: an entry without its row in the change log, a topic without its
+ // link. The record of what the change will do is written first, so the change can
+ // be finished later instead of being half done.
+ //
+ // The record is what accepts the change: before it is there, nothing has changed.
+ // It holds the files to write, the files to remove, and the row that goes with
+ // them in the change log, so finishing a change later is the same work as
+ // publishing it in the first place.
+
+ const writeStep = (path, text) => ({ action: 'write', path: relativePath(root, path), text })
+ const removeStep = path => ({ action: 'remove', path: relativePath(root, path) })
+
+ // The files of a change, in the order they are written.
+ async function applySteps(steps) {
+ for (const step of steps) {
+ const path = inside(root, step.path)
+ if (step.action === 'remove') await unlink(path).catch(error => { if (error?.code !== 'ENOENT') throw error })
+ else await writeText(path, step.text)
+ }
+ }
+
+ // The change log as it is. A log that cannot be read stops the memory: it is what
+ // says what was done.
+ function readJournal() {
+ try {
+ return readFileSync(journalPath, 'utf8')
+ } catch (error) {
+ if (error?.code === 'ENOENT') return ''
+ unreadable(journalPath, error)
+ }
+ }
+
+ // Whether the change log already holds the row of a change. Only a row that parses
+ // counts: a half-written row is not proof that anything was done.
+ function journalled(text, id) {
+ return text.split('\n').some(line => {
+ if (!line.includes(id)) return false
+ try { return JSON.parse(line)?.id === id } catch { return false }
+ })
+ }
+
+ // Whether a line of the change log is a whole row.
+ const whole = (line) => {
+ try {
+ const value = JSON.parse(line)
+ return value !== null && typeof value === 'object'
+ } catch {
+ return false
+ }
+ }
+
+ // The row of a change in the change log, written once: a change that is finished
+ // twice (after an interruption) does not get a second row. The row keeps the
+ // fields it always had, so a later undo can still read what each change replaced.
+ //
+ // The log can end in a half-written row, when a change was interrupted while its
+ // row was being appended. A half row is not proof that anything was done: it is
+ // kept beside the log as the evidence it is, the log is cut back to the rows that
+ // are whole, and the row after it starts on a line of its own.
+ async function journalRow(row) {
+ const text = readJournal()
+ if (journalled(text, row.id)) return false
+ const cut = text.lastIndexOf('\n') + 1
+ const half = text.slice(cut)
+ const line = JSON.stringify(row)
+ mkdirSync(root, { recursive: true })
+ if (half === '') {
+ await appendFile(journalPath, `${line}\n`, 'utf8')
+ return true
+ }
+ if (whole(half)) {
+ // A whole row that lost its newline: it is ended, and the row after it starts
+ // on a line of its own.
+ await appendFile(journalPath, `\n${line}\n`, 'utf8')
+ return true
+ }
+ await appendFile(tornPath, `${half}\n`, 'utf8')
+ truncateSync(journalPath, Buffer.byteLength(text.slice(0, cut), 'utf8'))
+ await appendFile(journalPath, `${line}\n`, 'utf8')
+ return true
+ }
+
+ // Publishes a change: the files it touches, then the row that goes with it in the
+ // change log. A change that cannot be published stays pending: the record is left
+ // behind, and the change is finished before memory is read or written again.
+ async function publish({ op, scope, steps, row }) {
+ const id = randomUUID()
+ const time = new Date().toISOString()
+ const record = pendingRecord({ id, time, op, scope, steps, row })
+ // The record has to be readable back, so its size is checked before the change
+ // is accepted: a record that cannot be read would stop the memory for good.
+ const text = serializePending(record)
+ await writeText(pendingPath(root), text)
+ try {
+ await applySteps(steps)
+ await journalRow(record.row)
+ await unlink(pendingPath(root)).catch(error => { if (error?.code !== 'ENOENT') throw error })
+ } catch (error) {
+ rt.warn('ds-bot: memory change %s is pending: %s', id, error)
+ throw error
+ }
+ }
+
+ // Finishes the changes that were interrupted: the files they touch, then the rows
+ // that go with them. A change that was already finished is not finished again, so
+ // its row is not written twice.
+ async function recoverPending() {
+ if (rt.readOnly() !== undefined) return
+ const record = readPending(root)
+ if (record === undefined) return
+ await applySteps(record.steps)
+ await journalRow(record.row)
+ await unlink(pendingPath(root)).catch(error => { if (error?.code !== 'ENOENT') throw error })
+ }
+
+ // The recovery runs in the writer's line, so it never runs beside a change that is
+ // being published.
+ const recover = () => queued(recoverPending)
+ // A read waits for the writer's line, so it reads files that are whole.
+ const settled = (read) => queued(async () => {
+ await recoverPending()
+ return read()
+ })
+
+ // A change that was interrupted is finished when the host starts.
+ ctx.effect(() => {
+ void rt.load().then(() => recover()).catch(error => rt.warn('ds-bot: memory recovery failed: %s', error?.message ?? error))
+ }, 'ds-bot: memory recovery')
+
// Checked when the write runs: a Bot or group chat deleted after the write was
// queued has its memory archived already, and writing would bring the folder back;
// nor does a deleted Bot write the team memory, or one no longer Main Bot or group
@@ -605,6 +739,7 @@ export function install(rt) {
function addEntry({ scope, topic, text, meta, actor, label }) {
return queued(async () => {
+ await recoverPending()
writable(scope, actor)
const files = loadScope(scope)
const [same] = matchEntries(allEntries(files), text).filter(entry => squash(entry.text) === squash(text))
@@ -625,9 +760,9 @@ export function install(rt) {
index = joinLines(addLink(main.lines.length > 0 ? main.lines : parseMemory(EMPTY_MAIN).lines, topic))
checkSize(main, index, label)
}
- await writeText(target.path, next)
- if (index !== undefined) await writeText(main.path, index)
- await journal({ op: 'add', scope: scopeKey(scope), file: target.file, ...actorOf(actor), after: line })
+ const steps = [writeStep(target.path, next)]
+ if (index !== undefined) steps.push(writeStep(main.path, index))
+ await publish({ op: 'add', scope: scopeKey(scope), steps, row: { op: 'add', scope: scopeKey(scope), file: target.file, ...actorOf(actor), after: line } })
noteNews(scope, actor, 'add', line)
const where = topic === undefined ? MAIN : fresh ? `the new topic [[${topic}]], linked from MEMORY.md` : `topic [[${topic}]]`
return { changed: true, file: target, message: `Saved to ${label}, in ${where} (${sizeNote(target, next.length)}).` }
@@ -649,6 +784,7 @@ export function install(rt) {
// The entry keeps its place; `topic` only narrows where to look.
function replaceEntry({ scope, topic, match, text, meta, actor, label }) {
return queued(async () => {
+ await recoverPending()
writable(scope, actor)
const old = findOne(loadScope(scope), topic, match, label)
const line = formatEntry(text, meta)
@@ -657,8 +793,12 @@ export function install(rt) {
lines[old.line] = line
const next = joinLines(lines)
checkSize(old.file, next, label)
- await writeText(old.file.path, next)
- await journal({ op: 'replace', scope: scopeKey(scope), file: old.file.file, ...actorOf(actor), before, after: line })
+ await publish({
+ op: 'replace',
+ scope: scopeKey(scope),
+ steps: [writeStep(old.file.path, next)],
+ row: { op: 'replace', scope: scopeKey(scope), file: old.file.file, ...actorOf(actor), before, after: line },
+ })
noteNews(scope, actor, 'replace', line)
return { changed: true, file: old.file, message: `Updated in ${label} (${fileName(old.file)}): "${old.text}" is now "${text}".` }
})
@@ -666,6 +806,7 @@ export function install(rt) {
function removeEntry({ scope, topic, match, actor, label }) {
return queued(async () => {
+ await recoverPending()
writable(scope, actor)
const files = loadScope(scope)
const old = findOne(files, topic, match, label)
@@ -673,14 +814,20 @@ export function install(rt) {
const lines = old.file.lines.filter((_line, index) => index !== old.line)
// A topic left with nothing but its title goes, and so does its link.
const empty = old.file.topic !== undefined && lines.every(line => line.trim() === '' || HEADING.test(line))
+ const steps = []
if (empty) {
- await unlink(old.file.path).catch(error => { if (error?.code !== 'ENOENT') throw error })
+ steps.push(removeStep(old.file.path))
const main = files[0]
- if (main.links.includes(old.file.topic)) await writeText(main.path, joinLines(removeLink(main.lines, old.file.topic)))
+ if (main.links.includes(old.file.topic)) steps.push(writeStep(main.path, joinLines(removeLink(main.lines, old.file.topic))))
} else {
- await writeText(old.file.path, joinLines(lines))
+ steps.push(writeStep(old.file.path, joinLines(lines)))
}
- await journal({ op: 'remove', scope: scopeKey(scope), file: old.file.file, ...actorOf(actor), before, ...(empty ? { removedTopic: true } : {}) })
+ await publish({
+ op: 'remove',
+ scope: scopeKey(scope),
+ steps,
+ row: { op: 'remove', scope: scopeKey(scope), file: old.file.file, ...actorOf(actor), before, ...(empty ? { removedTopic: true } : {}) },
+ })
noteNews(scope, actor, 'remove', before)
return { changed: true, file: old.file, message: `Removed from ${label} (${fileName(old.file)}): "${old.text}", all of it, so save again with remember any part that is still true. The change log keeps a copy.${empty ? ` The topic [[${old.file.topic}]] was empty, so it is gone too.` : ''}` }
})
@@ -694,13 +841,15 @@ export function install(rt) {
news.delete(botId)
return queued(async () => {
if (rt.readOnly() !== undefined) return
+ // A change that was interrupted is finished first, so the archive holds it.
+ await recoverPending()
await unlink(join(root, 'summaries', `${safeId(botId)}.json`)).catch(() => {})
const dir = dirOf(ownScope(botId))
if (!existsSync(dir)) return
const name = `${safeId(botId)}-${new Date().toISOString().replace(/[:.]/g, '-')}`
await mkdir(join(root, 'archive'), { recursive: true })
await rename(dir, join(root, 'archive', name))
- await journal({ op: 'archive', scope: scopeKey(ownScope(botId)), actor: 'user', actorName: 'user', botName: bot?.name, to: `archive/${name}` })
+ await journalRow({ id: randomUUID(), time: new Date().toISOString(), op: 'archive', scope: scopeKey(ownScope(botId)), actor: 'user', actorName: 'user', botName: bot?.name, to: `archive/${name}` })
}).catch(error => rt.warn('ds-bot: memory of %s not archived: %s', bot?.name ?? botId, error))
}
@@ -713,13 +862,15 @@ export function install(rt) {
news.delete(room.id)
return queued(async () => {
if (rt.readOnly() !== undefined) return
+ // A change that was interrupted is finished first, so the archive holds it.
+ await recoverPending()
await unlink(summaryPath(room.id)).catch(() => {})
const dir = dirOf(groupScope(room.id))
if (!existsSync(dir)) return
const name = `group-${safeId(room.id)}-${new Date().toISOString().replace(/[:.]/g, '-')}`
await mkdir(join(root, 'archive'), { recursive: true })
await rename(dir, join(root, 'archive', name))
- await journal({ op: 'archive', scope: scopeKey(groupScope(room.id)), actor: 'user', actorName: 'user', groupName: room.name, to: `archive/${name}` })
+ await journalRow({ id: randomUUID(), time: new Date().toISOString(), op: 'archive', scope: scopeKey(groupScope(room.id)), actor: 'user', actorName: 'user', groupName: room.name, to: `archive/${name}` })
}).catch(error => rt.warn('ds-bot: memory of group %s not archived: %s', room.name, error))
}
@@ -792,6 +943,18 @@ export function install(rt) {
}
}
+ // A change that was interrupted is finished before memory is read again. Until it
+ // is, the section is not frozen, so the next render reads the finished state; a
+ // record that cannot be read stops the memory, as an unreadable file does.
+ function pendingChange() {
+ try {
+ return { pending: readPending(root) !== undefined }
+ } catch (error) {
+ rt.warn('ds-bot: %s', error?.message ?? error)
+ return { failed: true }
+ }
+ }
+
/** @type {Map<string, string>} */
const frozen = new Map()
const snapshotPath = sessionId => join(root, 'snapshots', `${safeId(sessionId)}.md`)
@@ -807,18 +970,19 @@ export function install(rt) {
const holds = text => marks.every(mark => text.includes(mark))
const kept = frozen.get(sessionId)
if (kept !== undefined && holds(kept)) return kept
+ const pending = pendingChange()
const path = snapshotPath(sessionId)
const snap = existsSync(path) ? sectionRead(path) : { text: '' }
let text = snap.text
// A render that could not read everything is used but not kept: it is written
// down neither as the snapshot nor as the frozen copy, so the next render tries
// the files again.
- let failed = snap.failed !== undefined
+ let failed = snap.failed !== undefined || pending.failed === true
if (text === '' || !holds(text)) {
const section = memorySection(bot, roomId)
text = section.text
failed = failed || section.failed
- if (!failed && rt.readOnly() === undefined) {
+ if (!failed && rt.readOnly() === undefined && pending.pending !== true) {
try {
mkdirSync(dirname(path), { recursive: true })
writeFileSync(`${path}.tmp`, text, 'utf8')
@@ -828,7 +992,8 @@ export function install(rt) {
}
}
}
- if (!failed) frozen.set(sessionId, text)
+ if (!failed && pending.pending !== true) frozen.set(sessionId, text)
+ if (pending.pending === true) void recover().catch(error => rt.warn('ds-bot: memory recovery failed: %s', error?.message ?? error))
return text
}
// The Session's next render freezes the memory as it is then.
@@ -988,7 +1153,7 @@ export function install(rt) {
if (error) return error
let loaded
try {
- loaded = scopes.map(scope => ({ scope, tag: tagOf(scope, self), label: labelOf(scope, self), files: loadScope(scope) }))
+ loaded = await settled(() => scopes.map(scope => ({ scope, tag: tagOf(scope, self), label: labelOf(scope, self), files: loadScope(scope) })))
} catch (failure) {
return failure.message
}
@@ -1154,9 +1319,9 @@ export function install(rt) {
// The summary is written again when the entries or the interface language change;
// a failed one waits for `regenerate`, or a new model for the keeper, instead of
// retrying on every poll.
- function memoryView(body) {
+ async function memoryView(body) {
const panel = panelOf(body)
- const loaded = Object.fromEntries(Object.entries(panel.scopes).map(([tag, scope]) => [tag, loadScope(scope)]))
+ const loaded = await settled(() => Object.fromEntries(Object.entries(panel.scopes).map(([tag, scope]) => [tag, loadScope(scope)])))
const entries = Object.entries(loaded).flatMap(([tag, files]) => panelEntries(files, tag))
const language = languageNow()
const hash = createHash('sha256').update(JSON.stringify([language, ...Object.values(loaded).map(linesFor)])).digest('hex')
@@ -1182,7 +1347,7 @@ export function install(rt) {
if (panel.keeper === undefined) throw new Error('No Bot is left in this group chat')
const text = String(body.text ?? '').trim().slice(0, ASK_TEXT_MAX)
if (text === '') throw new Error('Type a question or a change first')
- const numbered = Object.entries(panel.scopes).flatMap(([tag, scope]) => allEntries(loadScope(scope)).map(entry => ({ ...entry, scope: tag })))
+ const numbered = await settled(() => Object.entries(panel.scopes).flatMap(([tag, scope]) => allEntries(loadScope(scope)).map(entry => ({ ...entry, scope: tag }))))
const answer = parseAsk(await botShot(panel.keeper, askSystem(panel.group), askRequest({ name: panel.name, group: panel.group, numbered, language: languageNow(), text }), panel.tag))
const meta = { source: 'memory panel', by: 'user', added: today() }
const home = panel.group ? 'group' : 'own'
@@ -1209,7 +1374,7 @@ export function install(rt) {
changes.push({ op, scope: tag, text: next || target?.text || '', ok: false, error: failure.message })
}
}
- return { reply: answer.reply, changes, view: memoryView(panelBody(panel)) }
+ return { reply: answer.reply, changes, view: await memoryView(panelBody(panel)) }
}
// One entry the user removes from the list.
@@ -1218,7 +1383,7 @@ export function install(rt) {
const scope = panel.scopes[body.scope] ?? panel.scopes[panel.group ? 'group' : 'own']
const topic = body.topic === null || body.topic === undefined ? undefined : cleanTopic(body.topic)
await removeEntry({ scope, topic, match: String(body.text ?? ''), actor: USER, label: panelLabel(panel, scope) })
- return memoryView(panelBody(panel))
+ return await memoryView(panelBody(panel))
}
// ---------------------------------------------------------------------------
@@ -1433,8 +1598,7 @@ export function install(rt) {
}
// Only the user's words are kept, so lines without any need no model call.
if (read.some(line => line.who === 'user')) {
- const homeFiles = loadScope(home)
- const teamFiles = loadScope(TEAM)
+ const { homeFiles, teamFiles } = await settled(() => ({ homeFiles: loadScope(home), teamFiles: loadScope(TEAM) }))
const said = read.filter(line => line.who === 'user').map(line => line.text).join('\n')
const tagged = group ? 'group' : 'own'
const { numbered, left } = reviewEntries(homeFiles, teamFiles, REVIEW_MEMORY_MAX, said, tagged)
diff --git a/ds-bot/test/install.test.js b/ds-bot/test/install.test.js
index b71d0845..ecc0ffa8 100644
--- a/ds-bot/test/install.test.js
+++ b/ds-bot/test/install.test.js
@@ -76,6 +76,7 @@ test('apply registers listeners, tools, and effects in a fixed order', (t) => {
'on agent/inbox/discarded',
'on session/event',
'effect ds-bot: resume interrupted turns',
+ 'effect ds-bot: memory recovery',
'effect ds-bot: memory section',
'prompt bot-memory 645',
'tool remember',
diff --git a/ds-bot/test/memory-pending.test.js b/ds-bot/test/memory-pending.test.js
new file mode 100644
index 00000000..b52f5f65
--- /dev/null
+++ b/ds-bot/test/memory-pending.test.js
@@ -0,0 +1,275 @@
+// A memory change that was interrupted.
+//
+// The faults come from the file system: a path that cannot be written (a directory
+// where a file belongs) fails the write that would have carried the change, and the
+// record of the change says what still has to happen.
+import assert from 'node:assert/strict'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { test } from 'node:test'
+import { apply } from '../index.js'
+import { PENDING_FILE, record } from '../src/host/memory-pending.js'
+import { fakeContext } from './fake-ctx.js'
+
+const TEAM = {
+ version: 1,
+ mainBotIds: ['m1'],
+ revision: 1,
+ whaleStored: true,
+ bots: {
+ m1: { id: 'm1', sessionId: 'm1', name: 'Chief', role: 'Chief of Staff', model: 'deepseek/v4', instructions: '', createdAt: 1 },
+ b2: { id: 'b2', sessionId: 'b2', name: 'Writer', role: '写作', model: 'deepseek/v4', instructions: '', createdAt: 2 },
+ },
+ rooms: {},
+ exchanges: [],
+ exchangeTurns: {},
+ questions: {},
+}
+
+function start({ home = mkdtempSync(join(tmpdir(), 'ds-bot-memory-')) } = {}) {
+ if (!existsSync(join(home, 'state.json'))) writeFileSync(join(home, 'state.json'), JSON.stringify(TEAM))
+ const ctx = fakeContext()
+ apply(ctx, { home })
+ const tool = (name, args, sessionId) => ctx.registeredTools.get(name).execute(args, { agent: { id: sessionId } })
+ const read = (...path) => readFileSync(join(home, 'memory', ...path), 'utf8')
+ const journal = () => read('journal.jsonl').trim().split('\n').map(line => JSON.parse(line))
+ const stop = async ({ keep = false } = {}) => {
+ await ctx.dispose()
+ if (!keep) rmSync(home, { recursive: true, force: true, maxRetries: 5 })
+ }
+ return { ctx, home, tool, read, journal, stop }
+}
+
+const settle = () => new Promise(resolve => setTimeout(resolve, 20))
+
+async function until(check) {
+ for (let tries = 0; tries < 200 && !check(); tries += 1) await settle()
+ assert.ok(check(), 'the condition did not hold within 4 s')
+}
+
+const pendingFile = home => join(home, 'memory', PENDING_FILE)
+const warned = (home, text) => until(() => {
+ const path = join(home, 'logs', 'diagnostics.jsonl')
+ return existsSync(path) && readFileSync(path, 'utf8').includes(text)
+})
+// The record of a change that was interrupted, as it lies on disk.
+const interrupted = (home, { id = 'change-1', op = 'add', scope = 'bot:b2', steps, row }) => {
+ const time = '2026-10-23T10:00:00.000Z'
+ writeFileSync(pendingFile(home), JSON.stringify(record({ id, time, op, scope, steps, row })))
+}
+
+test('a change that cannot be published stays pending, and is finished before the next read', async (t) => {
+ const { home, tool, read, journal, stop } = start()
+ t.after(() => stop())
+ // The change log cannot be written: the entry is published, but its row is not.
+ mkdirSync(join(home, 'memory', 'journal.jsonl'), { recursive: true })
+ const said = await tool('remember', { text: 'Trip to Kyoto', topic: 'travel' }, 'b2')
+ assert.doesNotMatch(said, /^Saved to your memory/)
+ assert.match(read('bots', 'b2', 'travel.md'), /Trip to Kyoto/)
+ assert.ok(existsSync(pendingFile(home)), 'the change is pending')
+ await warned(home, 'is pending')
+ // The change log is there again: the next read finishes the change.
+ rmSync(join(home, 'memory', 'journal.jsonl'), { recursive: true, force: true })
+ assert.match(await tool('recall', { query: 'Kyoto' }, 'b2'), /Trip to Kyoto/)
+ assert.ok(!existsSync(pendingFile(home)), 'the change is finished')
+ assert.deepEqual(journal().map(row => [row.op, row.scope, row.file]), [['add', 'bot:b2', 'travel.md']])
+ assert.match(read('bots', 'b2', 'MEMORY.md'), /- \[\[travel\]\]/)
+ // Reading again does not write a second row.
+ await tool('recall', {}, 'b2')
+ assert.equal(journal().length, 1)
+})
+
+test('a change that cannot be accepted leaves the memory as it was', async (t) => {
+ const { home, tool, read, stop } = start()
+ t.after(() => stop())
+ await tool('remember', { text: 'First fact' }, 'b2')
+ const before = read('bots', 'b2', 'MEMORY.md')
+ // The record of the change cannot be written: the change is not accepted, so
+ // nothing changed.
+ mkdirSync(pendingFile(home), { recursive: true })
+ const said = await tool('remember', { text: 'Second fact' }, 'b2')
+ assert.doesNotMatch(said, /Second fact/)
+ assert.equal(read('bots', 'b2', 'MEMORY.md'), before)
+ assert.doesNotMatch(read('journal.jsonl'), /Second fact/)
+ // With the record writable again, the change goes through.
+ rmSync(pendingFile(home), { recursive: true, force: true })
+ assert.match(await tool('remember', { text: 'Second fact' }, 'b2'), /^Saved to your memory/)
+ assert.match(read('bots', 'b2', 'MEMORY.md'), /Second fact/)
+})
+
+test('an interrupted change is finished when the host starts', async (t) => {
+ const home = mkdtempSync(join(tmpdir(), 'ds-bot-memory-'))
+ writeFileSync(join(home, 'state.json'), JSON.stringify(TEAM))
+ // A change that was interrupted after its topic was written, before the Index
+ // that links it.
+ mkdirSync(join(home, 'memory', 'bots', 'b2'), { recursive: true })
+ const topic = '# travel\n\n- Trip to Kyoto [source: part 1 #10; added: 2026-10-23]\n'
+ writeFileSync(join(home, 'memory', 'bots', 'b2', 'travel.md'), topic)
+ interrupted(home, {
+ steps: [
+ { action: 'write', path: 'bots/b2/travel.md', text: topic },
+ { action: 'write', path: 'bots/b2/MEMORY.md', text: '# Memory\n\n## Index\n- [[travel]]\n' },
+ ],
+ row: { op: 'add', scope: 'bot:b2', file: 'travel.md', actor: 'b2', actorName: 'Writer', after: '- Trip to Kyoto [source: part 1 #10; added: 2026-10-23]' },
+ })
+ const { read, journal, stop } = start({ home })
+ t.after(() => stop())
+ await until(() => !existsSync(pendingFile(home)))
+ assert.match(read('bots', 'b2', 'MEMORY.md'), /- \[\[travel\]\]/)
+ assert.deepEqual(journal().map(row => [row.op, row.file]), [['add', 'travel.md']])
+})
+
+test('an interrupted change that removes a topic and its link is finished as one', async (t) => {
+ const home = mkdtempSync(join(tmpdir(), 'ds-bot-memory-'))
+ writeFileSync(join(home, 'state.json'), JSON.stringify(TEAM))
+ mkdirSync(join(home, 'memory', 'bots', 'b2'), { recursive: true })
+ writeFileSync(join(home, 'memory', 'bots', 'b2', 'MEMORY.md'), '# Memory\n\n## Index\n- [[travel]]\n')
+ writeFileSync(join(home, 'memory', 'bots', 'b2', 'travel.md'), '# travel\n\n- Trip to Kyoto [added: 2026-10-23]\n')
+ // The change was interrupted after the topic was removed, before the Index lost
+ // its link.
+ interrupted(home, {
+ op: 'remove',
+ steps: [
+ { action: 'remove', path: 'bots/b2/travel.md' },
+ { action: 'write', path: 'bots/b2/MEMORY.md', text: '# Memory\n\n## Index\n' },
+ ],
+ row: { op: 'remove', scope: 'bot:b2', file: 'travel.md', actor: 'b2', actorName: 'Writer', before: '- Trip to Kyoto [added: 2026-10-23]', removedTopic: true },
+ })
+ const { read, journal, stop } = start({ home })
+ t.after(() => stop())
+ await until(() => !existsSync(pendingFile(home)))
+ assert.doesNotMatch(read('bots', 'b2', 'MEMORY.md'), /travel/)
+ assert.ok(!existsSync(join(home, 'memory', 'bots', 'b2', 'travel.md')))
+ assert.deepEqual(journal().map(row => [row.op, row.removedTopic]), [['remove', true]])
+})
+
+test('a change that was already finished does not get a second row', async (t) => {
+ const home = mkdtempSync(join(tmpdir(), 'ds-bot-memory-'))
+ writeFileSync(join(home, 'state.json'), JSON.stringify(TEAM))
+ const row = { op: 'add', scope: 'bot:b2', file: 'MEMORY.md', actor: 'b2', actorName: 'Writer', after: '- One [added: 2026-10-23]' }
+ // The change is finished: its row is in the change log, and the record of it is
+ // still there.
+ mkdirSync(join(home, 'memory'), { recursive: true })
+ writeFileSync(join(home, 'memory', 'journal.jsonl'), `${JSON.stringify({ id: 'change-1', time: '2026-10-23T10:00:00.000Z', ...row })}\n`)
+ interrupted(home, {
+ steps: [{ action: 'write', path: 'bots/b2/MEMORY.md', text: '# Memory\n\n- One [added: 2026-10-23]\n\n## Index\n' }],
+ row,
+ })
+ const { read, journal, stop } = start({ home })
+ t.after(() => stop())
+ await until(() => !existsSync(pendingFile(home)))
+ assert.equal(journal().length, 1)
+ assert.match(read('bots', 'b2', 'MEMORY.md'), /- One/)
+})
+
+test('a record of a change that cannot be read stops the memory', async (t) => {
+ const { home, tool, read, stop } = start()
+ t.after(() => stop())
+ await tool('remember', { text: 'First fact' }, 'b2')
+ const before = read('bots', 'b2', 'MEMORY.md')
+ writeFileSync(pendingFile(home), '{ this is not a record')
+ assert.match(await tool('recall', {}, 'b2'), /pending\.json is not readable/)
+ assert.doesNotMatch(await tool('remember', { text: 'Second fact' }, 'b2'), /Second fact/)
+ assert.equal(read('bots', 'b2', 'MEMORY.md'), before)
+})
+
+test('an interrupted change that replaces an entry is finished with the line it had before', async (t) => {
+ const home = mkdtempSync(join(tmpdir(), 'ds-bot-memory-'))
+ writeFileSync(join(home, 'state.json'), JSON.stringify(TEAM))
+ mkdirSync(join(home, 'memory', 'bots', 'b2'), { recursive: true })
+ writeFileSync(join(home, 'memory', 'bots', 'b2', 'MEMORY.md'), '# Memory\n\n- Likes tea [added: 2026-10-23]\n\n## Index\n')
+ interrupted(home, {
+ op: 'replace',
+ steps: [{ action: 'write', path: 'bots/b2/MEMORY.md', text: '# Memory\n\n- Likes green tea [added: 2026-10-23]\n\n## Index\n' }],
+ row: { op: 'replace', scope: 'bot:b2', file: 'MEMORY.md', actor: 'b2', actorName: 'Writer', before: '- Likes tea [added: 2026-10-23]', after: '- Likes green tea [added: 2026-10-23]' },
+ })
+ const { read, journal, stop } = start({ home })
+ t.after(() => stop())
+ await until(() => !existsSync(pendingFile(home)))
+ assert.match(read('bots', 'b2', 'MEMORY.md'), /Likes green tea/)
+ assert.deepEqual(journal().map(row => [row.op, row.before, row.after]), [['replace', '- Likes tea [added: 2026-10-23]', '- Likes green tea [added: 2026-10-23]']])
+})
+
+test('a change log from before the operation ids keeps its rows', async (t) => {
+ const home = mkdtempSync(join(tmpdir(), 'ds-bot-memory-'))
+ writeFileSync(join(home, 'state.json'), JSON.stringify(TEAM))
+ mkdirSync(join(home, 'memory'), { recursive: true })
+ writeFileSync(join(home, 'memory', 'journal.jsonl'), `${JSON.stringify({ time: '2026-10-01T10:00:00.000Z', op: 'add', scope: 'bot:b2', file: 'MEMORY.md', actor: 'b2', actorName: 'Writer', after: '- Older fact' })}\n`)
+ const { tool, journal, stop } = start({ home })
+ t.after(() => stop())
+ await tool('remember', { text: 'Newer fact' }, 'b2')
+ const rows = journal()
+ assert.equal(rows.length, 2)
+ assert.equal(rows[0].id, undefined)
+ assert.equal(typeof rows[1].id, 'string')
+})
+
+test('a half-written row of the change log is not proof: the change gets one whole row', async (t) => {
+ const home = mkdtempSync(join(tmpdir(), 'ds-bot-memory-'))
+ writeFileSync(join(home, 'state.json'), JSON.stringify(TEAM))
+ mkdirSync(join(home, 'memory'), { recursive: true })
+ // The row of op-1 was cut in half while it was being appended.
+ const half = '{"id":"op-1","time":"2026-10-23T10:00:00.000Z","op":"ad'
+ writeFileSync(join(home, 'memory', 'journal.jsonl'), half)
+ interrupted(home, {
+ id: 'op-1',
+ steps: [{ action: 'write', path: 'bots/b2/MEMORY.md', text: '# Memory\n\n- One [added: 2026-10-23]\n\n## Index\n' }],
+ row: { op: 'add', scope: 'bot:b2', file: 'MEMORY.md', actor: 'b2', actorName: 'Writer', after: '- One [added: 2026-10-23]' },
+ })
+ const { read, stop } = start({ home })
+ t.after(() => stop())
+ await until(() => !existsSync(pendingFile(home)))
+ // Every line of the log parses, and the change has one whole row.
+ const rows = read('journal.jsonl').trim().split('\n').map(line => JSON.parse(line))
+ assert.deepEqual(rows.map(row => row.id), ['op-1'])
+ assert.match(read('bots', 'b2', 'MEMORY.md'), /- One/)
+ // The half row is kept beside the log, as the evidence it is.
+ assert.ok(read('journal.torn').includes(half))
+})
+
+test('a half-written row of another change does not swallow the row after it', async (t) => {
+ const home = mkdtempSync(join(tmpdir(), 'ds-bot-memory-'))
+ writeFileSync(join(home, 'state.json'), JSON.stringify(TEAM))
+ mkdirSync(join(home, 'memory'), { recursive: true })
+ const older = `${JSON.stringify({ time: '2026-10-01T10:00:00.000Z', id: 'op-old', op: 'add', scope: 'bot:b2', file: 'MEMORY.md', actor: 'b2', actorName: 'Writer', after: '- 旧的记录' })}\n`
+ const half = '{"id":"op-0","time":"2026-10-23T10:00:00.000Z","op":"ad'
+ writeFileSync(join(home, 'memory', 'journal.jsonl'), `${older}${half}`)
+ const { tool, read, stop } = start({ home })
+ t.after(() => stop())
+ await tool('remember', { text: 'Second fact' }, 'b2')
+ const rows = read('journal.jsonl').trim().split('\n').map(line => JSON.parse(line))
+ assert.deepEqual(rows.map(row => row.id).slice(0, 1), ['op-old'])
+ assert.match(rows[0].after, /旧的记录/)
+ assert.match(rows.at(-1).after, /^- Second fact/)
+ assert.ok(read('journal.torn').includes(half))
+})
+
+test('a change that would not fit in the record is refused, and the memory still reads', async (t) => {
+ const home = mkdtempSync(join(tmpdir(), 'ds-bot-memory-'))
+ writeFileSync(join(home, 'state.json'), JSON.stringify(TEAM))
+ mkdirSync(join(home, 'memory', 'bots', 'b2'), { recursive: true })
+ // A memory file that was edited by hand and is far past its size.
+ const huge = `# Memory\n\n- Teas and a long story about the tea [added: 2026-10-23]\n${'x'.repeat(1_200_000)}\n\n## Index\n`
+ writeFileSync(join(home, 'memory', 'bots', 'b2', 'MEMORY.md'), huge)
+ const { tool, read, stop } = start({ home })
+ t.after(() => stop())
+ // The change would leave a record that cannot be read back, so it is refused
+ // before it is accepted: the memory is as it was, and still reads.
+ const said = await tool('remember', { text: 'Coffee', replace: 'Teas and a long story about the tea' }, 'b2')
+ assert.match(said, /too large to record/)
+ assert.equal(read('bots', 'b2', 'MEMORY.md'), huge)
+ assert.ok(!existsSync(pendingFile(home)), 'the change was not accepted')
+ assert.match(await tool('recall', { query: 'Teas and a long story' }, 'b2'), /Teas and a long story/)
+})
+
+test('the change log keeps what each change replaced, and the id that tells it apart', async (t) => {
+ const { tool, journal, stop } = start()
+ t.after(() => stop())
+ await tool('remember', { text: 'Likes tea' }, 'b2')
+ await tool('remember', { text: 'Likes green tea', replace: 'Likes tea' }, 'b2')
+ const [added, replaced] = journal()
+ assert.deepEqual(Object.keys(added).sort(), ['actor', 'actorName', 'after', 'file', 'id', 'op', 'scope', 'time'])
+ assert.equal(replaced.before, added.after)
+ assert.notEqual(replaced.id, added.id)
+})