react-mnemonic

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.

Installation

npm install react-mnemonic

React 18 or later is required.

Quick start

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.

Why use it

• useState-like API: useMnemonicKey returns { 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

Pick the right entrypoint

| 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.

Optional persistence for component libraries

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.

AI resources

| 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 |

Learn more

• Documentation home
• Quick Start
• Optional Persistence
• Server Rendering
• Canonical Key Definitions
• Single Source of Truth Schemas
• Schema Migration
• Auth-Aware Persistence
• Context7 Rankings
• API Reference
• AI Overview

License

MIT