# @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()`.

## What it does

- **Add** notes with inferred kind, hashtags → tags, and entities
- **Search** ranked keywords over the newest 500 notes
- **Recent** / **by-tag** / **get** / **update** / **archive** (soft-delete)
- **Retriever** results shaped for agent context
- Optional **hosted notes UI** (`./app`)

## Prerequisites / setup

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

1. Fork or install [https://kody.codes/@kody/stash](https://kody.codes/@kody/stash)
   so your account owns a saved `stash` package. `packageStorage()` is per
   saved package, not shared across accounts.
2. Prefer calling **your installed fork** (resolve its export specifier with
   `packageList` + `packageGet`) so notes write to your bucket — not the live
   platform `@kody/stash` bucket.
3. Smoke-test with `recent` (read-only). Mutations (`add`, `update`, `archive`)
   accept `dryRun: true` — preview 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.

Agents: see [`AGENTS.md`](./AGENTS.md) for import paths, smoke checks, and
edge cases.

## Done when

- `recent` returns a `notes` array from your installed fork
- `add` with `dryRun: true` returns `dryRun: true` and a preview note (no write)
- Search / by-tag / get work against notes in your fork's bucket
- Optional hosted app loads for browsing notes

## Storage model

| Data | Store |
| --- | --- |
| Notes (text, kind, tags, entities, due dates, archive) | This package's `packageStorage()` SQLite |

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

## License

MIT