@loopengine-co/records 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evan Yan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @loopengine-co/records
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [loopengine](https://github.com/loopengine-co/loopengine) ability:
+named lists of records an agent keeps between runs (punch-ins, a daily
+pick, what's already been done), with tools to add, find and remove
+records, plus a skill on keeping them tidy. Removing records asks a
+person first by default. No settings or accounts needed.
+
+```sh
+npx loopengine add-ability @loopengine-co/records --agent <your-agent>
+```
+
+## What's in it
+
+- **Tools**
+  - `records_add(list, records, unique_by?)`: saves one or more records
+    (objects of fields) to a list, created on first use. Each gets an
+    `id` and an `added_at` time. `unique_by` names fields that must not
+    repeat, e.g. `["date", "person"]`: a repeat is skipped and reported
+    with the existing record's id.
+  - `records_find(list, where?, range?, max_results?, oldest_first?)`:
+    records whose fields equal `where` (a list of values matches any),
+    and whose `range.field` is between `from` and `to` (compared as text,
+    so ISO dates work). Newest first.
+  - `records_remove(list, ids? | where?)`: removes records by id or by
+    fields, and returns them. Never empties a list without either.
+  - `records_lists()`: the agent's lists, with record counts and when
+    each last changed.
+- **Skill**: `keeping-records`: consistent fields and dates, `unique_by`
+  for one-per-day rules, and answering from the records, not memory.
+- **actauth rules**: adding, finding and listing are `allow`; removing is
+  `ask`.
+
+## Example: a daily verse
+
+Two lists. Each morning a scheduled workflow finds the verses already
+used, picks a new one and saves it:
+
+```json
+records_add {"list": "verses", "records": [{"date": "2026-11-12", "reference": "Philippians 4:13", "text": "I can do all things through Christ which strengtheneth me."}], "unique_by": ["date"]}
+```
+
+When someone in the group says they've memorised it:
+
+```json
+records_add {"list": "memorised", "records": [{"date": "2026-11-12", "person": "Alice", "reference": "Philippians 4:13", "time": "08:40"}], "unique_by": ["date", "person"]}
+```
+
+And in the evening's report:
+
+```json
+records_find {"list": "memorised", "where": {"date": "2026-11-12"}}
+```
+
+## Where records are kept
+
+Each list is a JSON file, `agents/<agent>/records/<list>.json`, in the
+project the server runs from (on LoopEngine Cloud, the workspace's
+volume, so it survives restarts and upgrades). Each agent has its own
+lists. Writes replace the file in one step, and changes to a list wait
+for each other, so records aren't lost when two people write at once.
+
+A list holds up to 10,000 records, each up to 10,000 characters.
+
+## Permissions
+
+| Tool | Default | Why |
+| --- | --- | --- |
+| `records_add`, `records_find`, `records_lists` | allow | Only the agent's own lists |
+| `records_remove` | ask | Deletes what people recorded |
+
+Change these in the agent's Permissions tab.

package/actauth/rules.yml

@@ -0,0 +1,22 @@
+# Saving, finding and listing records only touch the agent's own lists,
+# so they're allowed. Removing records deletes what people recorded
+# (punch-ins, history), so it asks a person first.
+- name: records-add-allowed
+  scope: "*/*"
+  tool: records_add
+  decision: allow
+
+- name: records-find-allowed
+  scope: "*/*"
+  tool: records_find
+  decision: allow
+
+- name: records-lists-allowed
+  scope: "*/*"
+  tool: records_lists
+  decision: allow
+
+- name: records-remove-needs-approval
+  scope: "*/*"
+  tool: records_remove
+  decision: ask

package/loopengine.ability.json

@@ -0,0 +1,12 @@
+{
+  "loopengineVersion": ">=0.1.62 <1.0.0",
+  "tools": [
+    "tools/records_add.ts",
+    "tools/records_find.ts",
+    "tools/records_remove.ts",
+    "tools/records_lists.ts"
+  ],
+  "skills": ["skills/keeping-records"],
+  "actauth": "actauth/rules.yml",
+  "env": []
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@loopengine-co/records",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "A loopengine ability: keep named lists of records (punch-ins, daily picks, what's been done) that last between runs, with tools to add, find and remove records (removing asks first by default), plus a skill on keeping them tidy.",
+  "license": "MIT",
+  "keywords": [
+    "loopengine",
+    "loopengine-ability",
+    "records",
+    "storage",
+    "memory",
+    "tracking"
+  ],
+  "files": [
+    "loopengine.ability.json",
+    "tools",
+    "skills",
+    "actauth",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://loopengine.co",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/loopengine-co/records.git"
+  },
+  "bugs": {
+    "url": "https://github.com/loopengine-co/records/issues"
+  }
+}

package/skills/keeping-records/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: keeping-records
+description: How to use the @loopengine-co/records tools to keep lists that last between runs (punch-ins, daily picks, what's already been done), with consistent fields, no duplicates, and answers drawn from the records rather than memory.
+---
+
+# Keeping records
+
+The @loopengine-co/records tools keep named lists of records for this
+agent, saved between runs and conversations. Use them for anything you
+must remember exactly: who punched in, what was chosen each day, which
+items were already handled.
+
+## Lists and fields
+
+- One list per kind of thing, named plainly: `punch-ins`, `verses`,
+  `answered-posts`. Check `records_lists` before inventing a new name, so
+  the same thing doesn't end up in two lists.
+- Keep the same field names and formats in every record of a list. Dates
+  as `YYYY-MM-DD` in the workspace's time zone, times as `HH:MM`, people
+  by the name the chat shows. Then `where` and `range` find them reliably.
+- Save what later questions need, and link records with a shared field:
+  a punch-in can carry the `reference` of the verse it was for.
+
+## No duplicates
+
+When something may only happen once (one punch-in per person per day,
+one verse per day), pass `unique_by` to `records_add`, e.g.
+`["date", "person"]`. A repeat is skipped and reported with the existing
+record's id, even if two people write at the same moment. Tell the
+person it was already recorded; don't add it again.
+
+## Read before you answer
+
+Answer questions about the past from `records_find`, never from memory
+or the chat: "who punched in today", "which verses have we used", "how
+many days did Bob memorise this month" (a `range` on `date`). Before
+picking something new that mustn't repeat, find what's already in the
+list.
+
+## Removing
+
+`records_remove` asks a person first by default. Remove only what's
+clearly wrong (a punch-in by mistake, a duplicate), by id where you can.
+It returns the removed records, so say what was removed.
+
+## Never
+
+- Never claim something was recorded without a successful `records_add`.
+- Never edit a list's file by hand or keep records anywhere else.
+- Never remove records just to tidy up, or to make a report look better.

package/tools/records_add.ts

@@ -0,0 +1,146 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
+import { join } from 'node:path'
+import type { ToolDefinition } from 'loopengine'
+
+// ---- Shared helpers --------------------------------------------------
+// Duplicated verbatim across every tool file in this ability: add-ability
+// copies each tool file standalone, with no shared-module support, so
+// this block is the contract between them. Keep the copies identical.
+//
+// Each list is one JSON file, agents/<agent>/records/<list>.json (from
+// the project folder the server runs in), holding an array of records.
+// Every record gets an `id` and an `added_at` time. Writes go to a
+// temporary file that's then renamed over the list, so a crash never
+// leaves half a file, and changes to one list wait for each other (one
+// lock per list, shared by every tool file in the process).
+const MAX_RECORDS = 10_000
+const MAX_RECORD_BYTES = 10_000
+
+type StoredRecord = { id: string; added_at: string } & Record<string, unknown>
+
+function listName(action: string, value: unknown): string {
+  const name = String(value ?? '').trim()
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name)) {
+    throw new Error(`${action}: list must be a name of letters, digits, - and _ (up to 64), e.g. "punch-ins"`)
+  }
+  return name
+}
+
+function recordsDir(agentName: string): string {
+  if (!/^[A-Za-z0-9_-]+$/.test(agentName)) throw new Error(`records: unexpected agent name "${agentName}"`)
+  return join(process.cwd(), 'agents', agentName, 'records')
+}
+
+function readList(agentName: string, list: string): StoredRecord[] {
+  const file = join(recordsDir(agentName), `${list}.json`)
+  if (!existsSync(file)) return []
+  const parsed = JSON.parse(readFileSync(file, 'utf8')) as unknown
+  if (!Array.isArray(parsed)) throw new Error(`records: ${file} isn't a list of records`)
+  return parsed as StoredRecord[]
+}
+
+function writeList(agentName: string, list: string, records: StoredRecord[]): void {
+  const dir = recordsDir(agentName)
+  mkdirSync(dir, { recursive: true })
+  const file = join(dir, `${list}.json`)
+  const temp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`
+  writeFileSync(temp, `${JSON.stringify(records, null, 2)}\n`)
+  renameSync(temp, file)
+}
+
+function listNames(agentName: string): string[] {
+  const dir = recordsDir(agentName)
+  try {
+    return readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -5)).sort()
+  } catch {
+    return []
+  }
+}
+
+// One queue per list, on globalThis so the separately loaded tool files
+// share it.
+const LOCKS_KEY = Symbol.for('loopengine-records.locks')
+const locks: Map<string, Promise<unknown>> = ((globalThis as Record<symbol, unknown>)[LOCKS_KEY] as Map<string, Promise<unknown>> | undefined) ??
+  ((globalThis as Record<symbol, unknown>)[LOCKS_KEY] = new Map<string, Promise<unknown>>())
+
+async function withList<T>(agentName: string, list: string, change: () => T): Promise<T> {
+  const key = `${agentName}/${list}`
+  const previous = locks.get(key) ?? Promise.resolve()
+  const run = previous.catch(() => undefined).then(change)
+  locks.set(key, run)
+  try {
+    return await run
+  } finally {
+    if (locks.get(key) === run) locks.delete(key)
+  }
+}
+
+// `where`: field -> value (equal) or a list of values (any of them).
+function matches(record: Record<string, unknown>, where: Record<string, unknown>): boolean {
+  return Object.entries(where).every(([field, wanted]) => {
+    const value = record[field]
+    return Array.isArray(wanted) ? wanted.some((w) => sameValue(value, w)) : sameValue(value, wanted)
+  })
+}
+
+function sameValue(a: unknown, b: unknown): boolean {
+  return a === b || (a !== undefined && a !== null && b !== undefined && b !== null && String(a) === String(b))
+}
+
+function whereOf(action: string, value: unknown): Record<string, unknown> {
+  if (value === undefined || value === null) return {}
+  if (typeof value !== 'object' || Array.isArray(value)) throw new Error(`${action}: where must be an object of field: value, e.g. {"date": "2026-11-12"}`)
+  return value as Record<string, unknown>
+}
+// ---- End of shared helpers -------------------------------------------
+
+export const recordsAdd: ToolDefinition = {
+  name: 'records_add',
+  description:
+    'Save one or more records to a named list, e.g. today\'s verse to "verses", or a punch-in to "punch-ins". A record is an object of fields (text, numbers, true/false), such as {"date": "2026-11-12", "person": "Alice"}. Each gets an id and an added_at time. unique_by names fields that must not repeat: a record whose values for them match one already saved (or one earlier in the same call) is skipped and reported, e.g. unique_by ["date", "person"] for one punch-in per person per day. Lists are created on first use and kept between runs.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      list: { type: 'string', description: 'The list\'s name: letters, digits, - and _, e.g. "punch-ins".' },
+      records: { type: 'array', items: { type: 'object' }, description: 'The records to save, each an object of fields.' },
+      unique_by: { type: 'array', items: { type: 'string' }, description: 'Fields whose values together must not repeat in the list.' },
+    },
+    required: ['list', 'records'],
+  },
+  execute: async (input, ctx) => {
+    const action = 'records_add'
+    const list = listName(action, input.list)
+    const incoming = Array.isArray(input.records) ? input.records : input.records && typeof input.records === 'object' ? [input.records] : []
+    if (!incoming.length) throw new Error(`${action}: records must be a list of one or more objects`)
+    if (incoming.length > 500) throw new Error(`${action}: up to 500 records at a time`)
+    const uniqueBy = Array.isArray(input.unique_by) ? input.unique_by.map(String).filter(Boolean) : []
+    const fresh = incoming.map((r, i) => {
+      if (!r || typeof r !== 'object' || Array.isArray(r)) throw new Error(`${action}: record ${i + 1} isn't an object of fields`)
+      const fields = Object.fromEntries(Object.entries(r as Record<string, unknown>).filter(([k]) => k !== 'id' && k !== 'added_at'))
+      if (!Object.keys(fields).length) throw new Error(`${action}: record ${i + 1} has no fields`)
+      if (JSON.stringify(fields).length > MAX_RECORD_BYTES) throw new Error(`${action}: record ${i + 1} is over ${MAX_RECORD_BYTES} characters`)
+      for (const field of uniqueBy) if (!(field in fields)) throw new Error(`${action}: record ${i + 1} has no "${field}", which unique_by needs`)
+      return fields
+    })
+    return withList(ctx.agentName, list, () => {
+      const records = readList(ctx.agentName, list)
+      const added: StoredRecord[] = []
+      const skipped: { record: Record<string, unknown>; existing_id: string }[] = []
+      for (const fields of fresh) {
+        const key = Object.fromEntries(uniqueBy.map((f) => [f, fields[f]]))
+        const existing = uniqueBy.length ? records.find((r) => matches(r, key)) : undefined
+        if (existing) {
+          skipped.push({ record: fields, existing_id: existing.id })
+          continue
+        }
+        const record = { id: randomBytes(5).toString('hex'), added_at: new Date().toISOString(), ...fields } as StoredRecord
+        records.push(record)
+        added.push(record)
+      }
+      if (records.length > MAX_RECORDS) throw new Error(`${action}: "${list}" would hold over ${MAX_RECORDS} records; remove old ones first`)
+      if (added.length) writeList(ctx.agentName, list, records)
+      return JSON.stringify({ list, added, ...(skipped.length ? { skipped } : {}), total: records.length })
+    })
+  },
+}

package/tools/records_find.ts

@@ -0,0 +1,137 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
+import { join } from 'node:path'
+import type { ToolDefinition } from 'loopengine'
+
+// ---- Shared helpers --------------------------------------------------
+// Duplicated verbatim across every tool file in this ability: add-ability
+// copies each tool file standalone, with no shared-module support, so
+// this block is the contract between them. Keep the copies identical.
+//
+// Each list is one JSON file, agents/<agent>/records/<list>.json (from
+// the project folder the server runs in), holding an array of records.
+// Every record gets an `id` and an `added_at` time. Writes go to a
+// temporary file that's then renamed over the list, so a crash never
+// leaves half a file, and changes to one list wait for each other (one
+// lock per list, shared by every tool file in the process).
+const MAX_RECORDS = 10_000
+const MAX_RECORD_BYTES = 10_000
+
+type StoredRecord = { id: string; added_at: string } & Record<string, unknown>
+
+function listName(action: string, value: unknown): string {
+  const name = String(value ?? '').trim()
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name)) {
+    throw new Error(`${action}: list must be a name of letters, digits, - and _ (up to 64), e.g. "punch-ins"`)
+  }
+  return name
+}
+
+function recordsDir(agentName: string): string {
+  if (!/^[A-Za-z0-9_-]+$/.test(agentName)) throw new Error(`records: unexpected agent name "${agentName}"`)
+  return join(process.cwd(), 'agents', agentName, 'records')
+}
+
+function readList(agentName: string, list: string): StoredRecord[] {
+  const file = join(recordsDir(agentName), `${list}.json`)
+  if (!existsSync(file)) return []
+  const parsed = JSON.parse(readFileSync(file, 'utf8')) as unknown
+  if (!Array.isArray(parsed)) throw new Error(`records: ${file} isn't a list of records`)
+  return parsed as StoredRecord[]
+}
+
+function writeList(agentName: string, list: string, records: StoredRecord[]): void {
+  const dir = recordsDir(agentName)
+  mkdirSync(dir, { recursive: true })
+  const file = join(dir, `${list}.json`)
+  const temp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`
+  writeFileSync(temp, `${JSON.stringify(records, null, 2)}\n`)
+  renameSync(temp, file)
+}
+
+function listNames(agentName: string): string[] {
+  const dir = recordsDir(agentName)
+  try {
+    return readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -5)).sort()
+  } catch {
+    return []
+  }
+}
+
+// One queue per list, on globalThis so the separately loaded tool files
+// share it.
+const LOCKS_KEY = Symbol.for('loopengine-records.locks')
+const locks: Map<string, Promise<unknown>> = ((globalThis as Record<symbol, unknown>)[LOCKS_KEY] as Map<string, Promise<unknown>> | undefined) ??
+  ((globalThis as Record<symbol, unknown>)[LOCKS_KEY] = new Map<string, Promise<unknown>>())
+
+async function withList<T>(agentName: string, list: string, change: () => T): Promise<T> {
+  const key = `${agentName}/${list}`
+  const previous = locks.get(key) ?? Promise.resolve()
+  const run = previous.catch(() => undefined).then(change)
+  locks.set(key, run)
+  try {
+    return await run
+  } finally {
+    if (locks.get(key) === run) locks.delete(key)
+  }
+}
+
+// `where`: field -> value (equal) or a list of values (any of them).
+function matches(record: Record<string, unknown>, where: Record<string, unknown>): boolean {
+  return Object.entries(where).every(([field, wanted]) => {
+    const value = record[field]
+    return Array.isArray(wanted) ? wanted.some((w) => sameValue(value, w)) : sameValue(value, wanted)
+  })
+}
+
+function sameValue(a: unknown, b: unknown): boolean {
+  return a === b || (a !== undefined && a !== null && b !== undefined && b !== null && String(a) === String(b))
+}
+
+function whereOf(action: string, value: unknown): Record<string, unknown> {
+  if (value === undefined || value === null) return {}
+  if (typeof value !== 'object' || Array.isArray(value)) throw new Error(`${action}: where must be an object of field: value, e.g. {"date": "2026-11-12"}`)
+  return value as Record<string, unknown>
+}
+// ---- End of shared helpers -------------------------------------------
+
+export const recordsFind: ToolDefinition = {
+  name: 'records_find',
+  description:
+    'Find records in a list: those whose fields equal the values in where (a list of values matches any of them), and, with range, those whose field is between from and to (compared as text, so ISO dates like "2026-11-01" work). Newest first. Returns how many match and the records. With no where or range, the latest records. records_lists shows the lists there are.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      list: { type: 'string', description: 'The list\'s name.' },
+      where: { type: 'object', description: 'Field: value to match, e.g. {"date": "2026-11-12"} or {"person": ["Alice", "Bob"]}.' },
+      range: {
+        type: 'object',
+        description: 'A field between two values, inclusive, e.g. {"field": "date", "from": "2026-11-01", "to": "2026-11-30"}. Either end can be left out.',
+        properties: { field: { type: 'string' }, from: { type: 'string' }, to: { type: 'string' } },
+        required: ['field'],
+      },
+      max_results: { type: 'number', description: 'How many records to return, 1 to 1000. Default 100.' },
+      oldest_first: { type: 'boolean', description: 'Oldest first instead of newest first.' },
+    },
+    required: ['list'],
+  },
+  execute: async (input, ctx) => {
+    const action = 'records_find'
+    const list = listName(action, input.list)
+    const where = whereOf(action, input.where)
+    const range = input.range && typeof input.range === 'object' ? (input.range as { field?: unknown; from?: unknown; to?: unknown }) : undefined
+    if (range && !range.field) throw new Error(`${action}: range needs a field`)
+    const inRange = (r: Record<string, unknown>) => {
+      if (!range) return true
+      const value = r[String(range.field)]
+      if (value === undefined || value === null) return false
+      const text = String(value)
+      return (range.from === undefined || text >= String(range.from)) && (range.to === undefined || text <= String(range.to))
+    }
+    const found = readList(ctx.agentName, list).filter((r) => matches(r, where) && inRange(r))
+    if (!input.oldest_first) found.reverse()
+    const limit = Math.max(1, Math.min(1000, Math.floor(Number(input.max_results) || 100)))
+    return JSON.stringify({ list, matched: found.length, records: found.slice(0, limit) })
+  },
+  safe: true,
+}

package/tools/records_lists.ts

@@ -0,0 +1,114 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
+import { join } from 'node:path'
+import type { ToolDefinition } from 'loopengine'
+
+// ---- Shared helpers --------------------------------------------------
+// Duplicated verbatim across every tool file in this ability: add-ability
+// copies each tool file standalone, with no shared-module support, so
+// this block is the contract between them. Keep the copies identical.
+//
+// Each list is one JSON file, agents/<agent>/records/<list>.json (from
+// the project folder the server runs in), holding an array of records.
+// Every record gets an `id` and an `added_at` time. Writes go to a
+// temporary file that's then renamed over the list, so a crash never
+// leaves half a file, and changes to one list wait for each other (one
+// lock per list, shared by every tool file in the process).
+const MAX_RECORDS = 10_000
+const MAX_RECORD_BYTES = 10_000
+
+type StoredRecord = { id: string; added_at: string } & Record<string, unknown>
+
+function listName(action: string, value: unknown): string {
+  const name = String(value ?? '').trim()
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name)) {
+    throw new Error(`${action}: list must be a name of letters, digits, - and _ (up to 64), e.g. "punch-ins"`)
+  }
+  return name
+}
+
+function recordsDir(agentName: string): string {
+  if (!/^[A-Za-z0-9_-]+$/.test(agentName)) throw new Error(`records: unexpected agent name "${agentName}"`)
+  return join(process.cwd(), 'agents', agentName, 'records')
+}
+
+function readList(agentName: string, list: string): StoredRecord[] {
+  const file = join(recordsDir(agentName), `${list}.json`)
+  if (!existsSync(file)) return []
+  const parsed = JSON.parse(readFileSync(file, 'utf8')) as unknown
+  if (!Array.isArray(parsed)) throw new Error(`records: ${file} isn't a list of records`)
+  return parsed as StoredRecord[]
+}
+
+function writeList(agentName: string, list: string, records: StoredRecord[]): void {
+  const dir = recordsDir(agentName)
+  mkdirSync(dir, { recursive: true })
+  const file = join(dir, `${list}.json`)
+  const temp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`
+  writeFileSync(temp, `${JSON.stringify(records, null, 2)}\n`)
+  renameSync(temp, file)
+}
+
+function listNames(agentName: string): string[] {
+  const dir = recordsDir(agentName)
+  try {
+    return readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -5)).sort()
+  } catch {
+    return []
+  }
+}
+
+// One queue per list, on globalThis so the separately loaded tool files
+// share it.
+const LOCKS_KEY = Symbol.for('loopengine-records.locks')
+const locks: Map<string, Promise<unknown>> = ((globalThis as Record<symbol, unknown>)[LOCKS_KEY] as Map<string, Promise<unknown>> | undefined) ??
+  ((globalThis as Record<symbol, unknown>)[LOCKS_KEY] = new Map<string, Promise<unknown>>())
+
+async function withList<T>(agentName: string, list: string, change: () => T): Promise<T> {
+  const key = `${agentName}/${list}`
+  const previous = locks.get(key) ?? Promise.resolve()
+  const run = previous.catch(() => undefined).then(change)
+  locks.set(key, run)
+  try {
+    return await run
+  } finally {
+    if (locks.get(key) === run) locks.delete(key)
+  }
+}
+
+// `where`: field -> value (equal) or a list of values (any of them).
+function matches(record: Record<string, unknown>, where: Record<string, unknown>): boolean {
+  return Object.entries(where).every(([field, wanted]) => {
+    const value = record[field]
+    return Array.isArray(wanted) ? wanted.some((w) => sameValue(value, w)) : sameValue(value, wanted)
+  })
+}
+
+function sameValue(a: unknown, b: unknown): boolean {
+  return a === b || (a !== undefined && a !== null && b !== undefined && b !== null && String(a) === String(b))
+}
+
+function whereOf(action: string, value: unknown): Record<string, unknown> {
+  if (value === undefined || value === null) return {}
+  if (typeof value !== 'object' || Array.isArray(value)) throw new Error(`${action}: where must be an object of field: value, e.g. {"date": "2026-11-12"}`)
+  return value as Record<string, unknown>
+}
+// ---- End of shared helpers -------------------------------------------
+
+export const recordsLists: ToolDefinition = {
+  name: 'records_lists',
+  description: 'The lists this agent keeps, each with how many records it holds and when the last one was added.',
+  input_schema: { type: 'object', properties: {} },
+  execute: async (_input, ctx) => {
+    const lists = listNames(ctx.agentName).map((name) => {
+      try {
+        const records = readList(ctx.agentName, name)
+        return { list: name, records: records.length, last_added_at: records.at(-1)?.added_at ?? null }
+      } catch (err) {
+        return { list: name, error: err instanceof Error ? err.message : String(err) }
+      }
+    })
+    return JSON.stringify({ lists })
+  },
+  safe: true,
+}

package/tools/records_remove.ts

@@ -0,0 +1,124 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
+import { join } from 'node:path'
+import type { ToolDefinition } from 'loopengine'
+
+// ---- Shared helpers --------------------------------------------------
+// Duplicated verbatim across every tool file in this ability: add-ability
+// copies each tool file standalone, with no shared-module support, so
+// this block is the contract between them. Keep the copies identical.
+//
+// Each list is one JSON file, agents/<agent>/records/<list>.json (from
+// the project folder the server runs in), holding an array of records.
+// Every record gets an `id` and an `added_at` time. Writes go to a
+// temporary file that's then renamed over the list, so a crash never
+// leaves half a file, and changes to one list wait for each other (one
+// lock per list, shared by every tool file in the process).
+const MAX_RECORDS = 10_000
+const MAX_RECORD_BYTES = 10_000
+
+type StoredRecord = { id: string; added_at: string } & Record<string, unknown>
+
+function listName(action: string, value: unknown): string {
+  const name = String(value ?? '').trim()
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name)) {
+    throw new Error(`${action}: list must be a name of letters, digits, - and _ (up to 64), e.g. "punch-ins"`)
+  }
+  return name
+}
+
+function recordsDir(agentName: string): string {
+  if (!/^[A-Za-z0-9_-]+$/.test(agentName)) throw new Error(`records: unexpected agent name "${agentName}"`)
+  return join(process.cwd(), 'agents', agentName, 'records')
+}
+
+function readList(agentName: string, list: string): StoredRecord[] {
+  const file = join(recordsDir(agentName), `${list}.json`)
+  if (!existsSync(file)) return []
+  const parsed = JSON.parse(readFileSync(file, 'utf8')) as unknown
+  if (!Array.isArray(parsed)) throw new Error(`records: ${file} isn't a list of records`)
+  return parsed as StoredRecord[]
+}
+
+function writeList(agentName: string, list: string, records: StoredRecord[]): void {
+  const dir = recordsDir(agentName)
+  mkdirSync(dir, { recursive: true })
+  const file = join(dir, `${list}.json`)
+  const temp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`
+  writeFileSync(temp, `${JSON.stringify(records, null, 2)}\n`)
+  renameSync(temp, file)
+}
+
+function listNames(agentName: string): string[] {
+  const dir = recordsDir(agentName)
+  try {
+    return readdirSync(dir).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -5)).sort()
+  } catch {
+    return []
+  }
+}
+
+// One queue per list, on globalThis so the separately loaded tool files
+// share it.
+const LOCKS_KEY = Symbol.for('loopengine-records.locks')
+const locks: Map<string, Promise<unknown>> = ((globalThis as Record<symbol, unknown>)[LOCKS_KEY] as Map<string, Promise<unknown>> | undefined) ??
+  ((globalThis as Record<symbol, unknown>)[LOCKS_KEY] = new Map<string, Promise<unknown>>())
+
+async function withList<T>(agentName: string, list: string, change: () => T): Promise<T> {
+  const key = `${agentName}/${list}`
+  const previous = locks.get(key) ?? Promise.resolve()
+  const run = previous.catch(() => undefined).then(change)
+  locks.set(key, run)
+  try {
+    return await run
+  } finally {
+    if (locks.get(key) === run) locks.delete(key)
+  }
+}
+
+// `where`: field -> value (equal) or a list of values (any of them).
+function matches(record: Record<string, unknown>, where: Record<string, unknown>): boolean {
+  return Object.entries(where).every(([field, wanted]) => {
+    const value = record[field]
+    return Array.isArray(wanted) ? wanted.some((w) => sameValue(value, w)) : sameValue(value, wanted)
+  })
+}
+
+function sameValue(a: unknown, b: unknown): boolean {
+  return a === b || (a !== undefined && a !== null && b !== undefined && b !== null && String(a) === String(b))
+}
+
+function whereOf(action: string, value: unknown): Record<string, unknown> {
+  if (value === undefined || value === null) return {}
+  if (typeof value !== 'object' || Array.isArray(value)) throw new Error(`${action}: where must be an object of field: value, e.g. {"date": "2026-11-12"}`)
+  return value as Record<string, unknown>
+}
+// ---- End of shared helpers -------------------------------------------
+
+export const recordsRemove: ToolDefinition = {
+  name: 'records_remove',
+  description:
+    'Remove records from a list: by their ids, or every record whose fields equal the values in where. Give ids or where, not neither: it never empties a list by itself. Returns the removed records, so they can be added back.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      list: { type: 'string', description: 'The list\'s name.' },
+      ids: { type: 'array', items: { type: 'string' }, description: 'The ids of the records to remove.' },
+      where: { type: 'object', description: 'Field: value; every matching record is removed, e.g. {"date": "2026-11-12", "person": "Alice"}.' },
+    },
+    required: ['list'],
+  },
+  execute: async (input, ctx) => {
+    const action = 'records_remove'
+    const list = listName(action, input.list)
+    const ids = Array.isArray(input.ids) ? input.ids.map(String) : []
+    const where = whereOf(action, input.where)
+    if (!ids.length && !Object.keys(where).length) throw new Error(`${action}: give ids or where for the records to remove`)
+    return withList(ctx.agentName, list, () => {
+      const records = readList(ctx.agentName, list)
+      const removed = records.filter((r) => (ids.length ? ids.includes(r.id) : true) && matches(r, where))
+      if (removed.length) writeList(ctx.agentName, list, records.filter((r) => !removed.includes(r)))
+      return JSON.stringify({ list, removed, total: records.length - removed.length })
+    })
+  },
+}