@kody/stash

@kody/stash

Searchable personal notes, reminders, contacts, instructions, and facts. Use this when someone says "stash this" or needs to find a previously saved snippet. Not an email inbox.

Intent

Give every Kody account a zero-auth stash that is better than @kody/personal-capture: inferred kinds, hashtags, ranked search, archive, a retriever, and an optional hosted notes UI, all in this package's packageStorage().

Auth

Zero-auth. No OAuth, API key, or bot token.

• OAuth: not used. Do not open https://kody.codes/connect/oauth?provider=stash.
• Secrets: not used. Do not open https://kody.codes/account/secrets/new?name=stash&allowedHosts=.
• Required hosts: none.
• Scopes: none.

If a call returns 403 or "insufficient scope", this package is the wrong place to add credentials. The usual cause is running a static kody:@kody/stash import against the live official package (platform bucket) instead of a fork, or invoking outside the package runtime so packageStorage() is missing. Fork the listing or use packages.invoke as shown below.

User setup

1. Fork or install https://kody.codes/@kody/stash so your account owns a saved stash package. packageStorage() is per saved package, not shared across accounts.
2. Prefer packages.invoke({ kodyId: 'stash', ... }) (or a static import of your fork) so notes write to your bucket.
3. Smoke-test with recent (read-only). Mutations (add, update, archive) accept dryRun: true and must be previewed that way before a live write.
4. Optional: open the hosted package app to add and search notes in a browser.

Platform @kody/* packages run live for every user, but storage stays on the package that actually executed. After you fork, notes stay in your fork's bucket.

Exports

• kody:@kody/stash — dispatcher: add when text is present, search when query is present, otherwise overview.
• kody:@kody/stash/add — add a note; pass dryRun: true to preview.
• kody:@kody/stash/search — ranked keyword search over the newest 500 notes.
• kody:@kody/stash/recent — newest notes (default 20, max 50). Read-only smoke test.
• kody:@kody/stash/by-tag — filter by hashtag or inferred tag.
• kody:@kody/stash/get — load one note by id.
• kody:@kody/stash/update — update text/tags/kind/due date; supports dryRun: true.
• kody:@kody/stash/archive — soft-archive a note; supports dryRun: true.
• kody:@kody/stash/retriever — retriever-shaped search results for agent context.
• kody:@kody/stash/app — hosted notes UI (fetch handler).

Named ESM exports work via static import { ... }. For keyless packages.invoke, use a subpath whose default export is the function (exportName: 'recent'), or call the root dispatcher.

Smoke test

import { packages } from 'kody:runtime'

export default async function main() {
	const preview = await packages.invoke({
		kodyId: 'stash',
		exportName: 'add',
		params: { text: 'Projector bulb: 250W #home', dryRun: true },
	})
	const recent = await packages.invoke({
		kodyId: 'stash',
		exportName: 'recent',
		params: { limit: 5 },
	})
	return { preview, recent }
}

A successful smoke test returns preview.dryRun === true plus a recent.notes array. It does not create a note.

Example (live add after dry-run)

import addNote from 'kody:@kody/stash/add'
import searchNotes from 'kody:@kody/stash/search'

await addNote({ text: 'Projector bulb: 250W #home', dryRun: true })
const { note } = await addNote({ text: 'Projector bulb: 250W #home' })
const hits = await searchNotes({ query: 'projector wattage', limit: 5 })

Storage model

No R2, no extra repo, no Cloudflare token. Put a URL in the note body if you need to point at a file elsewhere.