@namzu/sdk 43.0.0 → 44.0.0

package/src/store/memory/disk.ts

@@ -12,13 +12,20 @@ import type {
 	MemoryStore,
 	UpdateMemoryParams,
 } from '../../types/memory/index.js'
-import { assertMemoryStatus } from '../../types/memory/index.js'
+import { assertMemoryStatus, isMemoryType } from '../../types/memory/index.js'
 import { generateMemoryId, isEntityId } from '../../utils/id.js'
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
 import { DiskRecordStore } from '../kv/record-store.js'
-import { defineSchema } from '../schema.js'
+import { SCHEMA_VERSION_KEY, defineSchema } from '../schema.js'
 import { InMemoryMemoryIndex, searchMemoryEntries } from './index.js'
+import {
+	MemoryNameConflictError,
+	assertOptionalMemoryFields,
+	isMemoryName,
+	nameHolder,
+	withOptionalFields,
+} from './naming.js'
 import {
 	DEFAULT_MEMORY_LOCK_TIMEOUT_MS,
 	acquireMemoryOperationLock,
@@ -86,6 +93,7 @@ function assertMemoryIndexEntries(value: unknown): asserts value is readonly Mem
 	if (!Array.isArray(value)) invalidIndex('the top-level value must be an array')
 
 	const ids = new Set<string>()
+	const names = new Set<string>()
 	for (const [entryIndex, candidate] of value.entries()) {
 		if (candidate === null || typeof candidate !== 'object' || Array.isArray(candidate)) {
 			invalidIndex('each entry must be an object', { entryIndex })
@@ -119,6 +127,23 @@ function assertMemoryIndexEntries(value: unknown): asserts value is readonly Mem
 				invalidIndex(`${field} must be a finite number`, { entryIndex, field })
 			}
 		}
+		// Optional since typed memory; absent on every index written before it.
+		if (entry.name !== undefined) {
+			if (!isMemoryName(entry.name)) {
+				invalidIndex('name must be a kebab-case memory name', { entryIndex, field: 'name' })
+			}
+			if (names.has(entry.name)) invalidIndex('names must be unique', { entryIndex, field: 'name' })
+			names.add(entry.name)
+		}
+		if (entry.description !== undefined && typeof entry.description !== 'string') {
+			invalidIndex('description must be a string', { entryIndex, field: 'description' })
+		}
+		if (entry.type !== undefined && !isMemoryType(entry.type)) {
+			invalidIndex('type must be user, feedback, project or reference', {
+				entryIndex,
+				field: 'type',
+			})
+		}
 	}
 }
 
@@ -246,7 +271,12 @@ export class DiskMemoryStore implements MemoryStore {
 		const content = await this.records.read(this.contentPath(location, id))
 		if (content === null) invalidContent(id, 'the indexed content record is missing')
 		assertMemoryContent(content, id)
-		return content
+		// The version stamp is the file's, not the record's: leaving it on
+		// handed every reader a `schemaVersion` field MemoryContent does not have.
+		const { [SCHEMA_VERSION_KEY]: _stamp, ...record } = content as MemoryContent & {
+			[SCHEMA_VERSION_KEY]?: unknown
+		}
+		return record
 	}
 
 	private async writeIndex(
@@ -259,19 +289,27 @@ export class DiskMemoryStore implements MemoryStore {
 	async create(
 		params: CreateMemoryParams,
 	): Promise<{ entry: MemoryIndexEntry; content: MemoryContent }> {
+		assertOptionalMemoryFields(params)
 		return this.withAuthoritativeIndex(async (location) => {
+			if (params.name !== undefined) {
+				const holder = nameHolder(this.index.allEntries(), params.name)
+				if (holder) throw new MemoryNameConflictError(params.name, holder.id)
+			}
 			const id = generateMemoryId()
 			const now = Date.now()
 
-			const entry: MemoryIndexEntry = {
-				id,
-				title: params.title,
-				summary: params.summary,
-				tags: params.tags ? [...params.tags] : [],
-				status: 'active',
-				createdAt: now,
-				updatedAt: now,
-			}
+			const entry: MemoryIndexEntry = withOptionalFields(
+				{
+					id,
+					title: params.title,
+					summary: params.summary,
+					tags: params.tags ? [...params.tags] : [],
+					status: 'active',
+					createdAt: now,
+					updatedAt: now,
+				},
+				params,
+			)
 
 			const memoryContent: MemoryContent = {
 				id,
@@ -319,19 +357,27 @@ export class DiskMemoryStore implements MemoryStore {
 
 	async update(id: MemoryId, updates: UpdateMemoryParams): Promise<MemoryIndexEntry | undefined> {
 		if (updates.status !== undefined) assertMemoryStatus(updates.status)
+		assertOptionalMemoryFields(updates)
 		return this.withAuthoritativeIndex(async (location) => {
 			assertStorageMemoryId(id, (reason) => invalidContent(id, reason, { field: 'id' }))
 			const existing = this.index.getEntry(id)
 			if (!existing) return undefined
-			const existingContent = await this.readContent(location, id)
-			const updated: MemoryIndexEntry = {
-				...existing,
-				title: updates.title ?? existing.title,
-				summary: updates.summary ?? existing.summary,
-				tags: updates.tags ? [...updates.tags] : existing.tags,
-				status: updates.status ?? existing.status,
-				updatedAt: Date.now(),
+			if (updates.name !== undefined) {
+				const holder = nameHolder(this.index.allEntries(), updates.name, id)
+				if (holder) throw new MemoryNameConflictError(updates.name, holder.id)
 			}
+			const existingContent = await this.readContent(location, id)
+			const updated: MemoryIndexEntry = withOptionalFields(
+				{
+					...existing,
+					title: updates.title ?? existing.title,
+					summary: updates.summary ?? existing.summary,
+					tags: updates.tags ? [...updates.tags] : existing.tags,
+					status: updates.status ?? existing.status,
+					updatedAt: Date.now(),
+				},
+				updates,
+			)
 			const updatesContent =
 				updates.content !== undefined ||
 				updates.format !== undefined ||

package/src/store/memory/index-file.ts

@@ -0,0 +1,121 @@
+/**
+ * The generated `MEMORY.md`: one line per active memory someone chose to
+ * keep, the thing a host loads into every prompt so the model knows what
+ * exists without reading it.
+ *
+ * It is an index and never a source. Nothing reads it back; every line is
+ * rebuilt from the memory files, so an edit to it is overwritten at the next
+ * write and an edit to a memory file reaches it then.
+ */
+
+import type { MemoryIndexEntry, MemoryRecord } from '../../types/memory/index.js'
+import { memoryOrigin } from './origin.js'
+
+/** Lines of index a prompt carries before the rest is left to search. */
+export const MEMORY_INDEX_MAX_LINES = 200
+/** One index line, link and description together. */
+export const MEMORY_INDEX_LINE_MAX_CHARS = 150
+
+export const MEMORY_INDEX_FILE_HEADER =
+	'<!-- Generated from the memory files beside it. Edits here are overwritten; edit a memory file instead. -->'
+
+function clip(text: string, limit: number): string {
+	if (text.length <= limit) return text
+	if (limit < 1) return ''
+	let head = text.slice(0, limit - 1)
+	if (/[\uD800-\uDBFF]$/.test(head)) head = head.slice(0, -1)
+	return `${head.trimEnd()}…`
+}
+
+/**
+ * `- [name](name.md) — description`, never longer than
+ * {@link MEMORY_INDEX_LINE_MAX_CHARS}: the description is clipped to the room
+ * the link leaves. A name at the 64-character limit leaves ten characters;
+ * the link alone always fits.
+ */
+export function memoryIndexLine(
+	entry: Pick<MemoryIndexEntry, 'name' | 'description' | 'summary'>,
+): string {
+	const name = entry.name ?? ''
+	const link = `- [${name}](${name}.md)`
+	const description = (entry.description ?? entry.summary).replace(/\s+/g, ' ').trim()
+	const room = MEMORY_INDEX_LINE_MAX_CHARS - link.length - 3
+	if (!description || room < 2) return link
+	return `${link} — ${clip(description, room)}`
+}
+
+export interface RenderedMemoryIndex {
+	/** The index lines, followed by a note when some were left out. Empty when nothing is listed. */
+	readonly text: string
+	/**
+	 * Memories the index covers: active, named, and not derived by the
+	 * runtime (see `memoryOrigin`). Derived records are in the store and found
+	 * by search, never counted here — unless the index was rendered with
+	 * `derived: true`, when it covers only them.
+	 */
+	readonly total: number
+	/** How many of those `text` does not list. */
+	readonly omitted: number
+}
+
+/**
+ * Where a memory sits in the index. The cap keeps the head, so the head is
+ * what nobody else may displace: an operator's `feedback` and `user`
+ * memories, then the model's, then everything else.
+ */
+function tier(record: MemoryRecord): number {
+	const personal = record.entry.type === 'feedback' || record.entry.type === 'user'
+	if (!personal) return 2
+	return memoryOrigin(record.content.metadata) === 'operator' ? 0 : 1
+}
+
+/**
+ * Render the index of the active, named records a person or the model chose
+ * to keep. A record the runtime derived — a session memory promoter's or
+ * consolidation's account of a turn — is left out: it is written after almost
+ * every turn, and an index that changed with it would change the system prompt
+ * nearly every turn.
+ *
+ * Ordered by {@link tier}, then by name, so an unchanged set of memories
+ * renders byte-identical text — a prompt that carries it keeps its cache
+ * until a memory someone chose to keep changes — and the cap drops `project`
+ * and `reference` memories before any operator `feedback` or `user` one.
+ *
+ * `derived: true` renders the other half instead: the active, named records
+ * the runtime derived, newest first, for an operator inspecting what turns
+ * recorded. That listing is not for a prompt; it changes with every turn.
+ */
+export function renderMemoryIndex(
+	records: readonly MemoryRecord[],
+	options: { readonly maxLines?: number; readonly derived?: boolean } = {},
+): RenderedMemoryIndex {
+	const maxLines = options.maxLines ?? MEMORY_INDEX_MAX_LINES
+	if (!Number.isSafeInteger(maxLines) && maxLines !== Number.POSITIVE_INFINITY) {
+		throw new Error('maxLines must be a positive integer')
+	}
+	if (maxLines < 1) throw new Error('maxLines must be a positive integer')
+	const derived = options.derived === true
+	const byName = (a: { name: string }, b: { name: string }) =>
+		a.name < b.name ? -1 : a.name > b.name ? 1 : 0
+	const listed = records
+		.filter(
+			(record) =>
+				record.entry.status === 'active' &&
+				record.entry.name &&
+				(memoryOrigin(record.content.metadata) === 'derived') === derived,
+		)
+		.map((record) => ({ tier: tier(record), name: record.entry.name ?? '', entry: record.entry }))
+		.sort((a, b) =>
+			derived
+				? b.entry.updatedAt - a.entry.updatedAt || byName(a, b)
+				: a.tier - b.tier || byName(a, b),
+		)
+	const shown = listed.slice(0, maxLines).map((row) => memoryIndexLine(row.entry))
+	const omitted = listed.length - shown.length
+	if (omitted > 0) {
+		shown.push(
+			`(${omitted} more ${omitted === 1 ? 'memory is' : 'memories are'} not listed here. Use search_memory to find them.)`,
+		)
+	}
+	return { text: shown.join('\n'), total: listed.length, omitted }
+}

package/src/store/memory/index.ts

@@ -54,8 +54,10 @@ export function searchMemoryEntries(
 			let coverage = 0
 			let score = 0
 			if (query.size > 0) {
-				const title = terms(entry.title)
-				const summary = terms(entry.summary)
+				// A name is a title spelled as a slug and a description is a
+				// summary kept to one line; each scores as the field it stands in for.
+				const title = terms(`${entry.title} ${(entry.name ?? '').replace(/-/g, ' ')}`)
+				const summary = terms(`${entry.summary} ${entry.description ?? ''}`)
 				const body = terms(contentOf(entry.id))
 				for (const term of query) {
 					const weight =

package/src/store/memory/links.ts

@@ -0,0 +1,37 @@
+/**
+ * Two things every reader of a memory needs besides its body: which other
+ * memories it points at, and how old it is.
+ */
+
+import { MEMORY_NAME_MAX_LENGTH } from './naming.js'
+
+const LINK = /\[\[([a-z0-9]+(?:-[a-z0-9]+)*)\]\]/g
+const MAX_LINKS = 20
+const DAY_MS = 86_400_000
+
+/** The distinct `[[name]]` targets in `content`, in order of first mention, at most 20. */
+export function memoryLinkNames(content: string): string[] {
+	const names: string[] = []
+	for (const match of content.matchAll(LINK)) {
+		const name = match[1]
+		if (!name || name.length > MEMORY_NAME_MAX_LENGTH || names.includes(name)) continue
+		names.push(name)
+		if (names.length >= MAX_LINKS) break
+	}
+	return names
+}
+
+/**
+ * `today`, `1 day old`, `12 days old`. Whole days, because a memory is a
+ * point-in-time claim and the question a reader has is whether the world has
+ * had time to move since — which hours do not answer and days do.
+ */
+export function describeMemoryAge(updatedAt: number, now: number = Date.now()): string {
+	const days = Math.max(0, Math.floor((now - updatedAt) / DAY_MS))
+	if (days === 0) return 'today'
+	return `${days} day${days === 1 ? '' : 's'} old`
+}
+
+/** The sentence every aged memory carries, so the model checks before it relies. */
+export const MEMORY_VERIFY_NOTICE =
+	'Memories are point-in-time: a file, function, flag or command a memory names may have changed or gone since. Verify it against the current code before relying on it, and update or archive the memory if it is wrong.'

package/src/store/memory/markdown-format.ts

@@ -0,0 +1,276 @@
+/**
+ * One memory as one Markdown file: YAML frontmatter, a blank line, the body.
+ *
+ * ```markdown
+ * ---
+ * name: tests-need-a-built-sdk
+ * description: The CLI's tests import the SDK's dist, so build it first
+ * type: feedback
+ * status: active
+ * createdAt: 2026-09-21T09:30:00.000Z
+ * updatedAt: 2026-09-21T09:30:00.000Z
+ * tags: ["testing"]
+ * id: 0b6c2a4e-…
+ * ---
+ *
+ * Run `pnpm -r build` before `pnpm --filter @namzu/cli test`.
+ *
+ * Why: the CLI resolves `@namzu/sdk` through its package exports.
+ * How to apply: after any SDK change, before trusting a CLI failure.
+ * ```
+ *
+ * **Deliberately not a YAML parser**, for the reason `utils/frontmatter.ts`
+ * gives: a reader that half-understands YAML produces a value that passes
+ * validation and means nothing. That reader cannot be reused here because it
+ * refuses lists and mappings by design, and a memory has tags and metadata.
+ * This one reads exactly three value spellings — a plain scalar, a
+ * double-quoted JSON value (string, array or object; JSON is YAML's flow
+ * syntax), a single-quoted YAML string — and a block list of those under a
+ * key with no value. A value opening with `[` or `{` that is not JSON is read
+ * as the plain string it was written as, so a field that needs a list or an
+ * object refuses it by type and a description like `[WIP] notes` just works.
+ * Everything else is refused with the file and line, as is an unknown or
+ * repeated key: a key this build does not know is a field it
+ * would silently drop on the next write.
+ *
+ * The writer only emits what the reader reads, so every file this store
+ * writes parses back to the same record, body byte for byte.
+ */
+
+import type { MemoryStatus, MemoryType } from '../../types/memory/index.js'
+
+/** Keys this build reads and writes, in the order it writes them. */
+export const MEMORY_FRONTMATTER_KEYS = [
+	'name',
+	'description',
+	'type',
+	'status',
+	'createdAt',
+	'updatedAt',
+	'tags',
+	'id',
+	'title',
+	'summary',
+	'format',
+	'metadata',
+	'schemaVersion',
+] as const
+
+export type MemoryFrontmatterKey = (typeof MEMORY_FRONTMATTER_KEYS)[number]
+
+export type FrontmatterScalar = string | number | boolean | null
+export type FrontmatterJson =
+	| FrontmatterScalar
+	| readonly FrontmatterJson[]
+	| { readonly [key: string]: FrontmatterJson }
+
+export interface ParsedMemoryFile {
+	/** Plain scalars arrive as strings; the caller decides what each key's string means. */
+	readonly values: ReadonlyMap<MemoryFrontmatterKey, FrontmatterJson>
+	readonly body: string
+}
+
+export class MemoryFileFormatError extends Error {
+	constructor(
+		readonly file: string,
+		readonly reason: string,
+		readonly line?: number,
+	) {
+		super(`${file}${line === undefined ? '' : `:${line}`}: ${reason}`)
+		this.name = 'MemoryFileFormatError'
+	}
+}
+
+const KEYS = new Set<string>(MEMORY_FRONTMATTER_KEYS)
+const FENCE = /^---[ \t]*$/
+const KEY_LINE = /^([A-Za-z][A-Za-z0-9_]*):(?:[ \t]+(.*))?$/
+const ITEM_LINE = /^[ \t]+-(?:[ \t]+(.*))?$/
+
+function parseValue(raw: string, file: string, line: number): FrontmatterJson {
+	const value = raw.trim()
+	if (value.startsWith('"') || value.startsWith('[') || value.startsWith('{')) {
+		try {
+			return JSON.parse(value) as FrontmatterJson
+		} catch {
+			// `description: [WIP] deploy notes` is a plain string to the person
+			// who wrote it. A `[` or `{` value that is not JSON is read as that
+			// string; a field that needs a list or an object (tags, metadata)
+			// still refuses it by type. An unterminated `"` has no such reading.
+			if (!value.startsWith('"')) return value
+			throw new MemoryFileFormatError(
+				file,
+				'a value starting with " must be a valid JSON string',
+				line,
+			)
+		}
+	}
+	if (value.startsWith("'")) {
+		if (value.length < 2 || !value.endsWith("'") || /(^|[^'])'(?!')/.test(value.slice(1, -1))) {
+			throw new MemoryFileFormatError(file, 'an unterminated single-quoted string', line)
+		}
+		return value.slice(1, -1).replace(/''/g, "'")
+	}
+	if (/^[>|][-+]?$/.test(value) || value.startsWith('&') || value.startsWith('*')) {
+		throw new MemoryFileFormatError(
+			file,
+			'block scalars, anchors and aliases are not supported; write a single-line value',
+			line,
+		)
+	}
+	return value
+}
+
+/**
+ * Split a memory file into frontmatter values and body.
+ *
+ * The body is everything after the closing fence, less ONE leading newline
+ * (the blank line the writer puts there) and ONE trailing newline, `\n` or
+ * `\r\n` (the one the writer adds; it writes `\r\n` after a body ending in
+ * `\r`). Removing exactly one of each, not trimming, is what makes a body
+ * that itself begins or ends with blank lines, or with a `\r`, round-trip.
+ */
+export function parseMemoryFile(raw: string, file: string): ParsedMemoryFile {
+	const text = raw.startsWith('\uFEFF') ? raw.slice(1) : raw
+	const lines = text.split('\n')
+	if (!FENCE.test((lines[0] ?? '').replace(/\r$/, ''))) {
+		throw new MemoryFileFormatError(
+			file,
+			'a memory file must start with a --- frontmatter fence',
+			1,
+		)
+	}
+	let closing = -1
+	for (let i = 1; i < lines.length; i++) {
+		if (FENCE.test((lines[i] ?? '').replace(/\r$/, ''))) {
+			closing = i
+			break
+		}
+	}
+	if (closing < 0) throw new MemoryFileFormatError(file, 'the frontmatter is never closed')
+
+	const values = new Map<MemoryFrontmatterKey, FrontmatterJson>()
+	let listKey: MemoryFrontmatterKey | undefined
+	let list: FrontmatterJson[] | undefined
+	// A key with no value holds the empty string until a list item under it
+	// makes it a list, which a caller then validates like any other value.
+	const closeList = (): void => {
+		if (listKey && list && list.length > 0) values.set(listKey, list)
+		listKey = undefined
+		list = undefined
+	}
+	for (let i = 1; i < closing; i++) {
+		const lineNumber = i + 1
+		const line = (lines[i] ?? '').replace(/\r$/, '')
+		if (!line.trim() || line.trimStart().startsWith('#')) continue
+		const item = ITEM_LINE.exec(line)
+		if (item) {
+			if (!list) {
+				throw new MemoryFileFormatError(
+					file,
+					'a list item must follow a key with no value',
+					lineNumber,
+				)
+			}
+			list.push(parseValue(item[1] ?? '', file, lineNumber))
+			continue
+		}
+		const pair = KEY_LINE.exec(line)
+		if (!pair) {
+			throw new MemoryFileFormatError(
+				file,
+				'expected "key: value" at the start of the line',
+				lineNumber,
+			)
+		}
+		closeList()
+		const key = pair[1] ?? ''
+		if (!KEYS.has(key)) {
+			throw new MemoryFileFormatError(
+				file,
+				`unknown key "${key}"; this build reads ${MEMORY_FRONTMATTER_KEYS.join(', ')}`,
+				lineNumber,
+			)
+		}
+		const typedKey = key as MemoryFrontmatterKey
+		if (values.has(typedKey)) {
+			throw new MemoryFileFormatError(file, `"${key}" appears twice`, lineNumber)
+		}
+		const rawValue = pair[2]?.trim() ?? ''
+		if (rawValue === '') {
+			listKey = typedKey
+			list = []
+			values.set(typedKey, '')
+			continue
+		}
+		values.set(typedKey, parseValue(rawValue, file, lineNumber))
+	}
+	closeList()
+
+	let body = lines.slice(closing + 1).join('\n')
+	body = body.replace(/^\r?\n/, '').replace(/\r?\n$/, '')
+	return { values, body }
+}
+
+const RESERVED_PLAIN = /^(?:true|false|null|yes|no|on|off|~|[-+]?(?:\d[\d_]*)?\.?\d.*)$/i
+
+/** A string the reader gets back unchanged without quotes, and YAML reads as the same string. */
+function isPlainSafe(value: string): boolean {
+	return (
+		value.length > 0 &&
+		value === value.trim() &&
+		!/^[-?:,[\]{}#&*!|>'"%@`]/.test(value) &&
+		!/: |\s#|:$/.test(value) &&
+		// biome-ignore lint/suspicious/noControlCharactersInRegex: refusing control characters is the point
+		!/[\u0000-\u001f\u007f]/.test(value) &&
+		!RESERVED_PLAIN.test(value)
+	)
+}
+
+function formatValue(value: FrontmatterJson): string {
+	if (typeof value === 'string') return isPlainSafe(value) ? value : JSON.stringify(value)
+	return JSON.stringify(value)
+}
+
+export interface MemoryFileFields {
+	readonly name: string
+	readonly description: string
+	readonly type: MemoryType
+	readonly status: MemoryStatus
+	readonly createdAt: number
+	readonly updatedAt: number
+	readonly tags: readonly string[]
+	readonly id: string
+	readonly title: string
+	readonly summary: string
+	readonly format: 'text' | 'markdown' | 'json'
+	readonly metadata?: Record<string, unknown>
+}
+
+/**
+ * The file for one memory. Fields that repeat another are left out — a title
+ * equal to the name, a summary equal to the description, the default format —
+ * so an ordinary file carries the reference shape and nothing else.
+ */
+export function formatMemoryFile(fields: MemoryFileFields, body: string): string {
+	const lines: string[] = ['---']
+	const put = (key: MemoryFrontmatterKey, value: FrontmatterJson): void => {
+		lines.push(`${key}: ${formatValue(value)}`)
+	}
+	put('name', fields.name)
+	put('description', fields.description)
+	put('type', fields.type)
+	put('status', fields.status)
+	put('createdAt', new Date(fields.createdAt).toISOString())
+	put('updatedAt', new Date(fields.updatedAt).toISOString())
+	if (fields.tags.length > 0) lines.push(`tags: ${JSON.stringify(fields.tags)}`)
+	put('id', fields.id)
+	if (fields.title !== fields.name) put('title', fields.title)
+	if (fields.summary !== fields.description) put('summary', fields.summary)
+	if (fields.format !== 'markdown') put('format', fields.format)
+	if (fields.metadata !== undefined) lines.push(`metadata: ${JSON.stringify(fields.metadata)}`)
+	lines.push('---', '', body)
+	// The reader removes one trailing `\n` or `\r\n`, the second so a
+	// hand-written CRLF file reads cleanly. A body that itself ends in `\r`
+	// would lose it to that `\r\n`, so it is closed with one of its own.
+	return `${lines.join('\n')}${body.endsWith('\r') ? '\r\n' : '\n'}`
+}