Skip to content

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

Restore a single memory change from its journal

klarkxyefaf93300af9
diff --git a/docs/plans/2026-11-01-memory-restore.md b/docs/plans/2026-11-01-memory-restore.md
new file mode 100644
index 00000000..2f2297c6
--- /dev/null
+++ b/docs/plans/2026-11-01-memory-restore.md
@@ -0,0 +1,48 @@
+---
+date: 2026-11-01
+issue: 464
+---
+
+# Restore a memory change from journal.jsonl
+
+## What and why
+
+`journal.jsonl` (and a private Bot's own log) already keeps every memory change with
+the line before and after, but nothing reads it for undo: a wrong remember, replace,
+or forget is permanent unless the files are edited by hand. This adds a narrow,
+API-only restore — `memory-restore` on the `api/bot` channel — that applies the
+inverse of one journal row. A panel History view can come later; this is the part
+that makes the log actionable.
+
+## Shape
+
+- Request: `{ line, botId? }`. `line` is the 1-based line of the change log;
+ `botId` picks a private Bot's own log (`bots/<id>/journal.jsonl`), everything
+ else is in the shared log — the same routing `journalFor` uses for writes.
+- One row is undone with its inverse op, and only while what it reads still reads
+ as the row left it:
+ - `add` → the recorded `after` line is taken back out, verbatim. A topic left
+ with only its title is removed, and its `## Index` link with it — the same
+ cleanup a forget does.
+ - `remove` → the `before` line is put back where a new entry would go (the
+ original position is not in the row). A topic the remove took away is made
+ again with its link; a line already back is not duplicated.
+ - `replace` → the line that still reads `after` is put back to `before`.
+- Drift is a `NO_MATCH` failure, not a silent delete: the entry changed since, it
+ is already back, or the line is there more than once.
+- Restored content goes through `checkSize` like any other change.
+- `archive` rows move whole folders and are not undone this way; any other row
+ that is not a well-formed add/remove/replace is refused.
+- A restore is itself a change: it is queued on the writer's line, published
+ through `publish` like the rest — pending record first, files, then its own
+ journal row. The row is the inverse op carrying `restored: <id>` of the row it
+ undid, so a restore can itself be restored.
+- Writes the user may do are what may be restored: `writable(scope, user)` — the
+ deleted-Bot, deleted-group, and read-only guards all apply.
+
+## Deliberately out of scope
+
+- No version tree, no git, no multi-step undo. One row, one inverse.
+- No UI. The endpoint is for the host channel now; a History view in the memory
+ panel is the follow-up that consumes it.
+- `archive` is a different, folder-level path and stays irreversible here.
diff --git a/ds-bot/src/host/channel.js b/ds-bot/src/host/channel.js
index 59168534..611dda9e 100644
--- a/ds-bot/src/host/channel.js
+++ b/ds-bot/src/host/channel.js
@@ -388,6 +388,7 @@ export function install(rt) {
case 'memory-view':
case 'memory-ask':
case 'memory-forget':
+ case 'memory-restore':
await rt.load()
return ok(await rt.memoryEndpoint(endpoint, body))
case 'learning-answer':
diff --git a/ds-bot/src/host/memory.js b/ds-bot/src/host/memory.js
index e6a0ac20..2803ab6d 100644
--- a/ds-bot/src/host/memory.js
+++ b/ds-bot/src/host/memory.js
@@ -1452,6 +1452,120 @@ export function install(rt) {
return await memoryView(panelBody(panel))
}
+ // ---------------------------------------------------------------------------
+ // Undoing a change from the change log.
+ //
+ // Every row of journal.jsonl (or a private Bot's own log) holds the line a change
+ // left and the one it replaced, so one row can be undone with its inverse: an add
+ // is taken out, a remove or replace puts its line back. A restore is applied only
+ // while what it reads still reads as the row left it — an entry that changed
+ // since, or a line already back, is a NO_MATCH rather than a silent delete. The
+ // restore itself is a change: it goes through publish like the rest, and its row
+ // is the inverse op with the id of the row it undid, so it can be undone again.
+ // Archive rows move whole folders and are not undone this way.
+
+ const journalScope = key => (key === 'team' ? TEAM
+ : typeof key === 'string' && key.startsWith('bot:') ? ownScope(key.slice(4))
+ : typeof key === 'string' && key.startsWith('group:') ? groupScope(key.slice(6))
+ : undefined)
+ // The entry lines a file still has exactly as a row recorded them; restoring on
+ // less than a whole line would undo a different change than the one it reads.
+ const exactLines = (file, line) => file.entries.filter(entry => file.lines[entry.line] === line)
+ const noMatch = message => Object.assign(new Error(message), { code: NO_MATCH })
+
+ async function memoryRestore(body) {
+ const line = Number(body.line)
+ if (!Number.isInteger(line) || line < 1) throw new Error('Give the change log line of the change to restore, 1 being the first line.')
+ return queued(async () => {
+ await recoverPending()
+ // `botId` picks a private Bot's own log; every other change is in the shared
+ // log, which journalFor resolves for a public or unknown Bot too.
+ const { path } = journalFor(body.botId === undefined ? 'team' : `bot:${body.botId}`, 'restore')
+ const raw = readJournal(path).split('\n').filter(row => row !== '')[line - 1]
+ let row
+ try { row = raw === undefined ? undefined : JSON.parse(raw) } catch { row = null }
+ if (row === undefined || row === null || typeof row !== 'object') {
+ throw new Error(`Line ${line} of the change log is not a change that can be restored.`)
+ }
+ const scope = journalScope(row.scope)
+ if (scope === undefined || typeof row.file !== 'string' || row.file === '') {
+ throw new Error(`Line ${line} of the change log is not a change that can be restored.`)
+ }
+ if (row.op === 'archive') throw new Error('An archived memory cannot be restored from the change log.')
+ if (row.op !== 'add' && row.op !== 'remove' && row.op !== 'replace') {
+ throw new Error(`Line ${line} of the change log is not a change that can be restored.`)
+ }
+ writable(scope, USER)
+ const label = labelOf(scope)
+ const files = loadScope(scope)
+ const target = files.find(file => file.file === row.file)
+ const base = { scope: scopeKey(scope), file: row.file, ...actorOf(USER), restored: row.id }
+ const steps = []
+
+ if (row.op === 'add') {
+ // Undoing an add takes the line back out. It must still read as it was
+ // written; a topic left with only its title goes, and its link with it.
+ if (target === undefined || typeof row.after !== 'string') {
+ throw noMatch(`The entry that line ${line} added is not where the change log left it; it may have changed or been removed since.`)
+ }
+ const found = exactLines(target, row.after)
+ if (found.length === 0) throw noMatch(`The entry that line ${line} added is no longer in ${label}; it may have changed or been removed since.`)
+ if (found.length > 1) throw noMatch(`The line that line ${line} added is in ${label} more than once; restore it by hand so the wrong one is not removed.`)
+ const lines = target.lines.filter((_line, index) => index !== found[0].line)
+ const empty = target.topic !== undefined && lines.every(item => item.trim() === '' || HEADING.test(item))
+ if (empty) {
+ steps.push(removeStep(target.path))
+ const main = files[0]
+ if (main.links.includes(target.topic)) steps.push(writeStep(main.path, joinLines(removeLink(main.lines, target.topic))))
+ } else {
+ steps.push(writeStep(target.path, joinLines(lines)))
+ }
+ await publish({ op: 'remove', scope: scopeKey(scope), steps, row: { op: 'remove', ...base, before: row.after, ...(empty ? { removedTopic: true } : {}) } })
+ return { restored: row.id, op: 'remove', scope: row.scope, file: row.file, text: splitMeta(row.after.replace(/^[-*]\s+/, '')).text }
+ }
+
+ if (row.op === 'remove') {
+ // Undoing a remove puts the line back. The original place is not in the
+ // row, so it goes where a new entry would; a topic the remove took away
+ // is made again with its link, and a line already back is not duplicated.
+ if (typeof row.before !== 'string') throw new Error(`Line ${line} of the change log is not a change that can be restored.`)
+ let file = target
+ if (file === undefined) {
+ const topic = row.removedTopic === true && row.file.endsWith('.md') && row.file !== MAIN ? row.file.slice(0, -3) : undefined
+ if (topic === undefined) throw noMatch(`The file that line ${line} took the entry from is gone; restore it by hand.`)
+ file = { topic, file: row.file, path: join(dirOf(scope), row.file), content: '', ...parseMemory(`# ${topic}\n`) }
+ }
+ if (file.lines.includes(row.before)) throw noMatch(`The entry that line ${line} removed is already in ${label}; there is nothing to restore.`)
+ const lines = file.lines.length > 0 ? file.lines : parseMemory(`# ${file.topic}\n`).lines
+ const next = joinLines(insertEntry(lines, row.before))
+ checkSize(file, next, label)
+ steps.push(writeStep(file.path, next))
+ const main = files[0]
+ if (file.topic !== undefined && !main.links.includes(file.topic)) {
+ const index = joinLines(addLink(main.lines, file.topic))
+ checkSize(main, index, label)
+ steps.push(writeStep(main.path, index))
+ }
+ await publish({ op: 'add', scope: scopeKey(scope), steps, row: { op: 'add', ...base, after: row.before } })
+ return { restored: row.id, op: 'add', scope: row.scope, file: row.file, text: splitMeta(row.before.replace(/^[-*]\s+/, '')).text }
+ }
+
+ // row.op === 'replace': the recorded after-line is put back to before.
+ if (target === undefined || typeof row.before !== 'string' || typeof row.after !== 'string') {
+ throw noMatch(`The entry that line ${line} changed is not where the change log left it; it may have changed or been removed since.`)
+ }
+ const found = exactLines(target, row.after)
+ if (found.length === 0) throw noMatch(`The entry that line ${line} changed is no longer in ${label}; it may have changed or been removed since.`)
+ if (found.length > 1) throw noMatch(`The line that line ${line} changed is in ${label} more than once; restore it by hand so the wrong one is not changed.`)
+ const lines = [...target.lines]
+ lines[found[0].line] = row.before
+ const next = joinLines(lines)
+ checkSize(target, next, label)
+ await publish({ op: 'replace', scope: scopeKey(scope), steps: [writeStep(target.path, next)], row: { op: 'replace', ...base, before: row.after, after: row.before } })
+ return { restored: row.id, op: 'replace', scope: row.scope, file: row.file, text: splitMeta(row.before.replace(/^[-*]\s+/, '')).text }
+ })
+ }
+
// ---------------------------------------------------------------------------
// The memory review. When a conversation goes idle, a model reads what is new there
// and keeps, changes, or removes entries, as a person would after a talk. A Bot's own
@@ -1800,6 +1914,7 @@ export function install(rt) {
if (endpoint === 'memory-view') return memoryView(body)
if (endpoint === 'memory-ask') return memoryAsk(body)
if (endpoint === 'memory-forget') return memoryForget(body)
+ if (endpoint === 'memory-restore') return memoryRestore(body)
throw new Error(`Unknown endpoint ${endpoint}`)
}
diff --git a/ds-bot/test/memory.test.js b/ds-bot/test/memory.test.js
index 808dcfaf..2674b8c5 100644
--- a/ds-bot/test/memory.test.js
+++ b/ds-bot/test/memory.test.js
@@ -243,6 +243,89 @@ test('topics hold details, linked from MEMORY.md, and go when their last entry d
assert.equal(read('bots', 'b2', 'MEMORY.md'), '# Memory\n\n## Index\n')
})
+test('a journal line restores its change: remove, replace, and add undone', async (t) => {
+ const { tool, call, read, journal, stop } = start()
+ t.after(() => stop())
+ await tool('remember', { text: 'User prefers short replies' }, 'b2')
+ const added = journal().at(-1)
+ assert.equal(added.op, 'add')
+
+ // Undoing a remove puts the line back.
+ await tool('forget', { entry: 'short replies' }, 'b2')
+ const removed = journal().at(-1)
+ assert.equal(removed.op, 'remove')
+ assert.equal(parseMemory(read('bots', 'b2', 'MEMORY.md')).entries.length, 0)
+ const line = journal().length
+ const restored = await call('memory-restore', { line })
+ assert.equal(restored.ok, true, JSON.stringify(restored))
+ assert.equal(restored.value.op, 'add')
+ assert.equal(restored.value.restored, removed.id)
+ assert.match(read('bots', 'b2', 'MEMORY.md'), /- User prefers short replies \[/)
+ assert.equal(journal().at(-1).op, 'add')
+ assert.equal(journal().at(-1).restored, removed.id)
+
+ // A remove already undone is not undone twice: the line is back, so NO_MATCH.
+ const twice = await call('memory-restore', { line })
+ assert.equal(twice.ok, false)
+ assert.match(twice.error.message, /already in/)
+
+ // Undoing an add takes the line back out, while it still reads as written.
+ const addLine = journal().findIndex(record => record.id === added.id) + 1
+ const undone = await call('memory-restore', { line: addLine })
+ assert.equal(undone.ok, true, JSON.stringify(undone))
+ assert.equal(undone.value.op, 'remove')
+ assert.equal(parseMemory(read('bots', 'b2', 'MEMORY.md')).entries.length, 0)
+
+ // A replace puts the before-line back.
+ await tool('remember', { text: 'Lives in Hangzhou' }, 'b2')
+ await tool('remember', { text: 'Lives in Shanghai', replace: 'Hangzhou' }, 'b2')
+ const replaced = journal().at(-1)
+ const back = await call('memory-restore', { line: journal().length })
+ assert.equal(back.ok, true, JSON.stringify(back))
+ assert.equal(back.value.op, 'replace')
+ assert.equal(back.value.restored, replaced.id)
+ assert.match(read('bots', 'b2', 'MEMORY.md'), /- Lives in Hangzhou \[/)
+ assert.doesNotMatch(read('bots', 'b2', 'MEMORY.md'), /Shanghai/)
+})
+
+test('a restore refuses drift and rows that are not restorable', async (t) => {
+ const { tool, call, read, journal, stop } = start()
+ t.after(() => stop())
+ await tool('remember', { text: 'User prefers short replies' }, 'b2')
+ const addLine = journal().length
+ // The entry the add wrote was replaced since: undoing it now is a NO_MATCH,
+ // not a delete of the newer text.
+ await tool('remember', { text: 'User prefers very short replies', replace: 'short replies' }, 'b2')
+ const drift = await call('memory-restore', { line: addLine })
+ assert.equal(drift.ok, false)
+ assert.match(drift.error.message, /no longer in|not where the change log left it/)
+ assert.match(read('bots', 'b2', 'MEMORY.md'), /very short replies/)
+
+ for (const body of [{ line: 0 }, { line: -2 }, { line: 'three' }, {}]) {
+ const bad = await call('memory-restore', body)
+ assert.equal(bad.ok, false, JSON.stringify(body))
+ assert.match(bad.error.message, /line/)
+ }
+ const pastEnd = await call('memory-restore', { line: journal().length + 10 })
+ assert.equal(pastEnd.ok, false)
+ assert.match(pastEnd.error.message, /not a change that can be restored/)
+})
+
+test('restoring a remove that took a topic with it makes the topic again', async (t) => {
+ const { tool, call, read, journal, stop, home } = start()
+ t.after(() => stop())
+ await tool('remember', { text: 'Flies from Hangzhou', topic: 'Travel' }, 'b2')
+ await tool('forget', { entry: 'Flies', topic: 'travel' }, 'b2')
+ const removed = journal().at(-1)
+ assert.equal(removed.removedTopic, true)
+ assert.equal(existsSync(join(home, 'memory', 'bots', 'b2', 'travel.md')), false)
+
+ const restored = await call('memory-restore', { line: journal().length })
+ assert.equal(restored.ok, true, JSON.stringify(restored))
+ assert.match(read('bots', 'b2', 'travel.md'), /^# travel\n\n- Flies from Hangzhou \[/)
+ assert.match(read('bots', 'b2', 'MEMORY.md'), /- \[\[travel\]\]/)
+})
+
test('recall finds a continuous Chinese phrase, and keeps space-separated and Latin matching', async (t) => {
const { tool, stop } = start()
t.after(() => stop())