AI-friendly, persistent, type-safe state for React.
react-mnemonic gives your components persistent memory through a hook that feels like useState. Values survive reloads, can stay in sync across tabs, and remain SSR-safe by default. It is designed to be AI-friendly, prioritizing visible structure and unambiguous specifications. When you need more than raw storage, the package can validate, version, and migrate persisted data.
See our sister project, react-amnesia, an undo/redo framework for React:
npm install react-mnemonicReact 18 or later is required.
Wrap your app in a MnemonicProvider, then call useMnemonicKey anywhere
inside it.
import { MnemonicProvider, useMnemonicKey } from "react-mnemonic/core";
function Counter() {
const { value: count, set } = useMnemonicKey("count", {
defaultValue: 0,
});
return (
<div>
<p>Count: {count}</p>
<button onClick={() => set((c) => c + 1)}>Increment</button>
</div>
);
}
export default function App() {
return (
<MnemonicProvider namespace="my-app">
<Counter />
</MnemonicProvider>
);
}This persists the counter in localStorage as my-app.count, so the value
survives a full page reload.
useState-like API:useMnemonicKeyreturns{ value, set, reset, remove }- Namespaced persistence through
MnemonicProvider - Optional cross-tab synchronization
- SSR-safe defaults for server-rendered React apps
- Optional schema validation, versioning, migrations, and reconciliation
- Zero runtime dependencies with published TypeScript types
| Entrypoint | Approx ESM size | Use when |
|---|---|---|
react-mnemonic/optional |
~4.9 KB | You want the tiny component-library shim that falls back to local memory |
react-mnemonic/bootstrap |
~25 KB | You need synchronous first-paint recall before React renders |
react-mnemonic/core |
~61 KB | A provider is required and you want the lean persisted-state path |
react-mnemonic/schema |
~80.5 KB | A provider is required and you want schema validation, autoschema, and migrations |
react-mnemonic |
~80.5 KB | You want the top-level full entrypoint with the same schema-capable runtime surface |
These are rough current estimates from the built ESM entry files in dist/
before consumer-side minification and tree-shaking. They are useful for
relative comparison, not as a hard size guarantee.
If your component may render inside or outside a MnemonicProvider, import the
optional hook instead of branching at the call site.
import { useMnemonicKeyOptional } from "react-mnemonic/optional";
function SearchBox() {
const { value, set, remove } = useMnemonicKeyOptional("draft", {
defaultValue: "",
});
return (
<div>
<input value={value} onChange={(event) => set(event.target.value)} />
<button onClick={remove}>Clear</button>
</div>
);
}Inside a provider, the draft is persisted. Outside a provider, the same hook behaves like local in-memory state without throwing.
The lean optional entrypoint exports only:
useMnemonicKeyOptional(...)useMnemonicOptional()defineMnemonicKey(...)
Schema metadata such as schema: { version } can still be passed through the
optional hook. Applications pay the schema/runtime cost only when they mount a
schema-capable MnemonicProvider.
| Resource | Purpose |
|---|---|
| AI Docs | Canonical invariants, decision matrix, recipes, anti-patterns, and setup guidance |
llms.txt |
Compact retrieval index for tight context windows |
llms-full.txt |
Long-form export for indexing and larger prompt contexts |
ai-contract.json |
Machine-readable persistence contract for tooling and agent integrations |
| DeepWiki priorities | Steering file that points DeepWiki toward the highest-signal sources |
| AI Assistant Setup | Generated instruction packs plus the documented MCP-friendly retrieval path |