mnemosyne-react

Orpheus lost Eurydice because he looked back. Mnemosyne, titaness of memory, is the one who kept her name. This package family is the instrument of that preservation: adapters, SDKs, and runtimes that let AI agents store, recall, and forget without ever looking at the wrong thing at the wrong time.

React hooks and provider for the Mnemosyne memory substrate: useMemory, useRecall, useContainer, useSearch. TypeScript-first, Suspense-integrated, scoped to a single container via context. Built on TanStack Query with a Privy/JWT token provider.

Install

npm install @mnemosyne-eurydice/react @tanstack/react-query
# peer deps (if not already installed):
npm install react react-dom

Quick start

import { MnemosyneProvider, useRecall, useAddMemory, useProfile } from "@mnemosyne-eurydice/react";

function App() {
  return (
    <MnemosyneProvider apiKey={process.env.NEXT_PUBLIC_MNEMOSYNE_API_KEY}>
      <Chat />
    </MnemosyneProvider>
  );
}

function Chat() {
  const [query, setQuery] = useState("");
  const { data, isLoading } = useRecall({ containerTag: "default", query });
  const add = useAddMemory();

  return (
    <div>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      {isLoading && <p>Loading...</p>}
      {data?.map((m) => (
        <div key={m.id}>
          <strong>{m.score.toFixed(3)}</strong> {m.content}
        </div>
      ))}
      <button onClick={() => add.mutate({ containerTag: "default", content: "user just clicked" })}>
        Save
      </button>
    </div>
  );
}

API

<MnemosyneProvider>

Wraps your app and provides the Mnemosyne client + a TanStack Query client.

useAddMemory()

Mutation hook. Returns useMutation with mutate({ containerTag, content, ...rest }).

useRecall({ containerTag, query, ... })

Query hook. Returns useQuery over semantic search results.

useProfile(containerTag)

Query hook. Returns the learned profile for a container.

License

MIT © Geass Labs