@kody/stash

@kody/stash — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke/dryRun execute snippets, and edge cases. No user secrets. Do not disable live webhooks or jobs.

Secrets

None. Zero-auth. Do not open OAuth connect or secrets URLs for this package.

If a call returns 403 or "insufficient scope", you are usually running a static kody:@kody/stash import against the live official package (platform bucket) or invoking outside the package runtime so packageStorage() is missing. Fork the listing or invoke your installed fork as shown below.

Import paths

Named ESM exports work via static import { ... }. Prefer static kody:@…/stash/... imports from execute when calling your fork. When the installed fork's specifier is data (from packageGet), use computed import(specifier) — do not lead with packages.invoke.

Root dispatcher: add when text is present, search when query is present, otherwise overview. Explicit action: add, update, get, recent, by-tag, archive, search, overview.

Installed-fork storage

packageStorage() is per saved package. To write to the caller's bucket, resolve the installed fork's import specifier, then call that export:

import { kody } from 'kody:runtime'

export default async function main() {
	const saved = await kody.packageList({})
	const packageId = saved.packages.find((pkg) => pkg.kody_id === 'stash')
		?.package_id
	if (!packageId) throw new Error('Install or fork stash first.')
	const installed = await kody.packageGet({ package_id: packageId })
	const specifier = (subpath: string) => {
		const value = installed.exports.find(
			(entry) => entry.subpath === subpath,
		)?.import_specifier
		if (!value) throw new Error(`Installed stash is missing ${subpath}.`)
		return value
	}
	const recentSpec = specifier('./recent')
	const recentMod = await import(recentSpec)
	return await recentMod.default({ limit: 5 })
}

Prefer a subpath whose default export is the function (for example ./recent), or call the root dispatcher.

Smoke test (read-only)

import { kody } from 'kody:runtime'

export default async function main() {
	const saved = await kody.packageList({})
	const packageId = saved.packages.find((pkg) => pkg.kody_id === 'stash')
		?.package_id
	if (!packageId) throw new Error('Install or fork stash first.')
	const installed = await kody.packageGet({ package_id: packageId })
	const recentSpec = installed.exports.find(
		(entry) => entry.subpath === './recent',
	)?.import_specifier
	if (!recentSpec) throw new Error('Installed stash is missing ./recent.')
	const recentMod = await import(recentSpec)
	return await recentMod.default({ limit: 5 })
}

A successful smoke test returns a notes array. It does not create a note.

Static import against the live platform package (read-only overview only):

import runStash from 'kody:@kody/stash'

export default async function main() {
	return await runStash()
}

dryRun / confirm (mutations)

add, update, and archive accept dryRun: true and must be previewed that way before a live write.

import { kody } from 'kody:runtime'

export default async function main() {
	const saved = await kody.packageList({})
	const packageId = saved.packages.find((pkg) => pkg.kody_id === 'stash')
		?.package_id
	if (!packageId) throw new Error('Install or fork stash first.')
	const installed = await kody.packageGet({ package_id: packageId })
	const addSpec = installed.exports.find(
		(entry) => entry.subpath === './add',
	)?.import_specifier
	if (!addSpec) throw new Error('Installed stash is missing ./add.')
	const addMod = await import(addSpec)
	return await addMod.default({ text: 'Projector bulb: 250W #home', dryRun: true })
}

Expect dryRun: true plus a preview note (inferred kind/tags). No write.

Edge cases

• Static kody:@kody/stash imports hit the platform package bucket when the official listing runs live — fork first for personal notes.
• Search ranks over the newest 500 notes; recent defaults to 20 (max 50).
• Hashtags in text become tags; kind is inferred when omitted.
• Soft-archive via ./archive; do not hard-delete unless the API grows that.
• Put a URL in the note body to point at files elsewhere — no R2/blob store.
• Not an email inbox; use mail packages for that.