@mnemopay/react-native

Hermes-safe MnemoPay for React Native. Pure HTTPS client + React hooks for memory, wallet, commerce, and identity. No SQLite, no Node primitives, no native modules at load time.

Why this exists

@mnemopay/mobile-sdk was Node-only — it imports better-sqlite3 and fs at module load, which silently crashes every React Native runtime. This package replaces it with a thin HTTPS client that talks to the MnemoPay gateway (mcp-gateway-api.fly.dev) and exposes ergonomic React hooks.

Install

npm install @mnemopay/react-native
# peer deps: react >=18, react-native >=0.71

Quick start

import { configure, useAuth, useWallet, useRecall } from "@mnemopay/react-native";

// Once, at app boot (e.g. inside App.tsx or your AuthContext):
configure({ baseUrl: "https://mcp-gateway-api.fly.dev" });

// In a component:
function HomeScreen() {
  const { session, signInWithApple } = useAuth();
  const { balance, charge } = useWallet({ agentId: session?.agentId });
  const { memories, remember } = useRecall({
    namespace: `rider:${session?.agentId}`,
  });

  return <View>{/* … */}</View>;
}

Hooks

useAuth(initial?, cfg?)

Auth lifecycle. Wraps signInWithApple, signInWithIdentity, signOut. On success, automatically applies the token + agentId to the global config so useWallet / useRecall pick up the session without prop-drilling.

const { session, loading, signInWithApple, signOut } = useAuth();
await signInWithApple({
  identityToken: appleResult.identityToken,
  user: appleResult.user,
  email: appleResult.email,
});
// session.token + session.agentId now active globally

useWallet({ agentId?, autoLoad?, cfg? })

Balance + history + mutation helpers. Auto-loads on mount unless autoLoad: false.

const { balance, charge, settle, refund, refresh } = useWallet({ agentId });
await charge({ amount: 250, currency: "NGN", reason: "Ride to Ikeja" });

useRecall({ namespace?, agentId?, autoLoad?, cfg? })

Vector recall over the server-side memory store. Remembers the last query so refresh() / mutate-triggered re-runs use the same input.

const recall = useRecall({ namespace: `rider:${userId}` });
await recall.query({ query: "work", limit: 5, mode: "vector" });
// recall.memories — top-5 work-tagged memories
await recall.remember({ content: "office at Ikeja Ave 14", tags: ["place:work"] });

Direct client (no hooks)

For non-React code (background tasks, services), use MnemoPayClient directly:

import { MnemoPayClient } from "@mnemopay/react-native/client";

const client = new MnemoPayClient({
  baseUrl: "https://mcp-gateway-api.fly.dev",
  token: jwt,
  agentId: "rider:user-123",
});

const result = await client.recall({ query: "work", limit: 5 });

What this package does NOT do

• No local SQLite. All memory + wallet state lives server-side on the gateway. This is intentional — local SQLite is what killed @mnemopay/mobile-sdk on Hermes.
• No native Apple Sign-In bridge. You handle SiwA in your app (with expo-apple-authentication or @react-native-apple-authentication/apple-authentication) and pass the resulting identityToken to signInWithApple(). The server verifies the token against Apple.
• No on-device encryption / signing. Bearer tokens are managed by the server. Pair with expo-secure-store to persist the session.

Compatibility

• React Native ≥0.71 (Hermes engine assumed)
• Expo SDK ≥48 (we test against 52)
• Server: requires MnemoPay gateway ≥1.8 (the mcp-gateway-api Fly app)

License

Apache-2.0 © Jeremiah Omiagbo / MnemoPay