Letting a closed endpoint or a single agent daemon hold memory hides it inside the vendor, ties it to one model, and blocks the EU. Mnemosyne keeps memory portable, inspectable, and on your infrastructure, with an identity that stays stable and provable when you swap one model for another.
Mnemosyne is persistent, portable, shared memory for your Massive Intelligence (IM) agents, the
hippocampus of the swarm. You construct it over a store, write namespaced, versioned, content-addressed
records any agent in the pool can read, and derive a deterministic identity seed that stays stable across a model swap.
Your code is two lines:
new Mnemosyne({ store }), then memory.remember({ key, value }).
A pluggable MemoryStore gives identical semantics in memory, on edge key-value, in a Node file store, or any key-value backend. A persona projects to the same 256-dimensional vector regardless of model, so drift is a measurable cosine distance. Field-level masking and a data residency tag apply before memory crosses a boundary, a tamper-evident SHA-256 hash-chained audit log records every operation, and Ed25519-signed snapshots move between infrastructures. The node-free core speaks only Web Crypto.
Take a real production scene: a pool of agents that must remember the same facts, keep their identity when you swap a model, and prove who read what, with the data on your own infrastructure.
Portable memory is the middle ground between a vendor that hides it and a daemon that traps it; it keeps the records, the identity, and the audit trail in your hands, on your infrastructure, with every operation exposed and provable.
install to your first shared memory.pnpm add @takk/mnemosynenpm install @takk/mnemosyneyarn add @takk/mnemosynebun add @takk/mnemosyneThe core has no runtime dependencies and a node-free core. Every @takk sibling is an optional
peer; install only what you compose with.
# nothing else is required to start experimenting
# optional: install a sibling you compose with, for example
pnpm add @takk/keymesh @takk/modelchainimport { Mnemosyne, inMemoryStore, definePersona, deriveIdentity, identityDistance } from '@takk/mnemosyne';
// inMemoryStore() is the default; swap it for edge KV, a Node file store, or any backend.
const memory = new Mnemosyne({ store: inMemoryStore(), namespace: 'support' });
await memory.remember({ key: 'ticket:4821', value: { status: 'open', owner: 'agent-a' } });
const record = await memory.recall('ticket:4821'); // any agent in the pool reads the same record
// A persona projects to the same 256-dimensional vector regardless of model.
const persona = definePersona('triage', { tone: 'concise', role: 'assistant' });
const underGpt = await deriveIdentity(persona);
const underClaude = await deriveIdentity(persona);
const drift = identityDistance(underGpt, underClaude); // 0, the persona is unchanged across a model swapimport { createMemoryTools } from '@takk/mnemosyne/mcp';
// Framework-agnostic descriptors (name, description, JSON Schema, handler) that
// match what MCP servers and tool-calling APIs expect: mnemosyne_remember, recall, query.
const [remember, recall, query] = createMemoryTools(memory);
const result = await recall.handler({
key: 'ticket:4821',
});
// the host fixes the store and namespace; the caller only sends a key or queryOne store interface, identical semantics everywhere: in-memory, edge key-value such as Cloudflare Workers KV and lookalikes, a Node file store, or any key-value backend you bring.
Memory written on the edge reads the same in Node and the browser, with no rewrite.
Persistent, namespaced, versioned, content-addressed entries that any agent in the pool reads and writes, the hippocampus of the swarm. The same key resolves to the same record for every agent.
Agents stop re-deriving the same facts and start building on one shared memory.
A deterministic 256-dimensional identity projects a persona to the same vector byte-for-byte regardless of model, so an agent keeps the same identity seed when you swap GPT for Claude. It is a fingerprint of the persona definition, not a behavioral guarantee about the model.
Drift in the persona definition is a measurable cosine distance from
identityDistance, not a guess.
Memory lives in your process, on your infrastructure. The node-free core never opens a network socket; no vendor sits between a read and a write, and the EU and EEA are not blocked.
Keep memory where a closed, region-locked endpoint cannot follow you.
Redact, hash, or partially mask fields, and attach a data residency tag, applied before memory crosses a boundary. Hashing is deterministic, so masked records stay joinable.
Sensitive fields never leave the boundary in the clear, yet records still join on a hash.
A shared context with a budgeted window and a typed handoff passes the baton between agents without losing state, so the working set stays bounded as it moves.
Hand off between agents without dropping context or blowing the window.
An append-only SHA-256 hash-chained log of every remember, recall, forget, snapshot, and restore, that you
append to and verifyChain via the Web Crypto API.
Prove who read or wrote what, in Node, edge runtimes, or the browser, when an access is questioned.
Ed25519-signed snapshots move memory between infrastructures over Web Crypto, and memory is exposed as a Model Context Protocol (MCP) resource and tools.
Move a verified memory set between runtimes, and let any MCP host read it, instead of a store you cannot export.
Every published version signed with npm publish --provenance through GitHub Actions OIDC.
Lockfile committed, zero required runtime dependencies, node-free core.
Verify in one command that the tarball you installed was built from the source commit you trust.
You pick the store that fits the runtime, and the behavior is identical across all of them. The same
remember and recall resolve the same way whether the backend is RAM, edge KV, or a
file on disk.
| Store | What it is | When you reach for it |
|---|---|---|
memory |
An in-memory store, the fastest path and the deterministic stand-in for tests with no I/O. | Tests, short-lived processes, or a warm cache in front of another store. |
edge |
An edge key-value store such as Cloudflare Workers KV and lookalikes, with identical semantics. | Workers and edge functions where memory must live close to the request. |
file |
A Node file store that persists records to disk, content-addressed and versioned like the rest. Single-process: agents sharing the file in one process are safe; a concurrent multi-process pool should use a key-value backend with a real database. | A single Node host or a sovereign deployment that keeps memory on your own disk. |
custom |
Any key-value backend behind the MemoryStore interface, your database, cache, or object store. | You already run a backend and want memory to live in it without new semantics. |
The MemoryStore interface is the single seam: a record written through any store reads back identically through another, so memory is portable across runtimes without a migration.
| Entry point | Subpath export | Runtime | Use it when |
|---|---|---|---|
| Toolkit barrel | @takk/mnemosyne |
node-free | You want the Mnemosyne facade, the stores, identity, masking, audit, snapshots, and the adapters. |
| Identity | @takk/mnemosyne/identity |
node-free | You want deriveIdentity and identityDistance on their own to measure drift. |
| Audit and snapshots | @takk/mnemosyne/audit |
node-free | You want the SHA-256 hash chain and Ed25519-signed snapshots over Web Crypto. |
| Node file store | @takk/mnemosyne/node |
Node only | You need the file store that persists records to disk on a Node host. |
The mnemosyne binary runs the compiled engine. remember, recall, and
forget manage records; query searches them; identity derives a vector;
snapshot and restore move a signed memory set; keygen creates an
Ed25519 key pair; audit-verify checks a sealed chain.
# write a namespaced record, then read it back from any agent
npx @takk/mnemosyne remember ticket:4821 --value '{ "status": "open" }' --namespace support
npx @takk/mnemosyne recall ticket:4821 --namespace support# project a persona to a 256-dimensional vector, then sign and export a snapshot
npx @takk/mnemosyne identity 'concise triage assistant' --out identity.json
npx @takk/mnemosyne snapshot --sign --key signing.key --out memory.snapshot
npx @takk/mnemosyne audit-verify chain.json
npx @takk/mnemosyne --version
# exit codes: 0 ok, 2 usage or input, 20 broken chain, 21 bad signatureSeal every remember, recall, forget, snapshot, and restore into a tamper-evident, hash-chained log. And
because each operation is explicit, recall returns the value, the version, the content address,
and the residency tag, so memory is never a black box. Both are node-free and need no external service.
import { verifyChain } from '@takk/mnemosyne/audit';
// Enable the tamper-evident chain when you build the memory.
const memory = new Mnemosyne({ namespace: 'ops', audit: true });
// Every operation is sealed into the chain as it completes.
await memory.remember({ key: 'alert:992', value: { severity: 'high' } });
await memory.recall('alert:992');
const trail = memory.auditTrail(); // every remember, recall, forget, snapshot, restore
await verifyChain(trail); // { valid: true }, until any entry is alteredconst record = await memory.recall('incident:7');
// {
// key: 'incident:7',
// value: { ... }, // the stored value
// kind: 'fact', // the memory kind
// version: 4, // versioned on every write
// contentHash: '9f2c...', // SHA-256 content address of the value
// residency: 'eu', // the data residency tag
// updatedAt: 1751284800000 // epoch milliseconds
// }The record carries its version, its content address, and its residency tag, so you can see what was stored and where it may live. Seal each operation into the audit chain with no runtime dependency, the governance seam for a non-human entity sharing memory across a pool of models it operates.
The other approaches solve part of the problem. The contrast clarifies where Mnemosyne sits.
| Capability | Mnemosyne | Closed memory endpoint | Single agent daemon | Vector database | Hand-rolled |
|---|---|---|---|---|---|
| Distribution | npm library | hosted endpoint | a process you run | a service you run | your repo |
| Inspectable memory | content-addressed | black box | hidden inside | opaque vectors | varies |
| Portable across runtimes | one store seam | trapped | trapped | server-bound | none |
| Identity across model swaps | 256-dim vector | none | none | no | varies |
| Field masking and residency | built in | vendor policy | none | no | varies |
| Local-first sovereignty | your infra | region-locked | yes | yes | yes |
| Tamper-evident audit | yes | no | no | no | no |
| Zero deps, node-free | yes | n/a | deps | deps | varies |
| License | Apache-2.0 | proprietary | mixed | mixed | your call |
The honest summary: a closed endpoint is fine when you never need to move or inspect the memory, and a single agent daemon is fine when one agent owns it alone. Pick Mnemosyne when a pool of agents must share memory, keep their identity across a model swap, mask sensitive fields, and prove every access, all in one node-free TypeScript library you embed in production.
Mnemosyne is portable memory over a pluggable store, and that has boundaries. They are documented, and where reality bends them, there is an explicit choice rather than a silent fudge.
| Assumption or property | What it means | How Mnemosyne handles it |
|---|---|---|
| Pluggable store | The durability is the backing store's; an in-memory store does not survive a restart. | Pick the store that fits the runtime; semantics are identical, so you choose durability without changing code. |
| Deterministic identity | A persona projects to the same 256-dimensional vector regardless of model. | It is a stable projection of the persona, not a learned embedding; drift is a cosine distance you can measure. |
| Content-addressed values | A record is keyed and versioned, and its value is addressed by its SHA-256 hash. | An identical value reuses its address, so duplicate writes are cheap and a tampered value is detectable. |
| Masking before the boundary | Redact, hash, and partial masks apply before memory crosses a boundary. | Hashing is deterministic, so masked records stay joinable; the original value never leaves the boundary in the clear. |
| Residency is a tag | A data residency tag travels with the record and is enforced at the boundary. | The tag is recorded and checked; placing the bytes in a region is the deployment's job, which the tag governs. |
| Budgeted shared context | The shared window is bounded and a typed handoff passes the baton. | A handoff that would exceed the window is rejected up front rather than silently truncating state. |
| Audit over every operation | Every remember, recall, forget, snapshot, and restore is appended to the chain. | It is read off the chain, not asserted by the agents; an altered entry breaks verifyChain at the first index. |
| Integrity and signature | The audit chain proves a log was not altered; snapshots prove who produced them. | A SHA-256 hash chain seals the log and Ed25519 signs snapshots, both via Web Crypto. |
141 tests passing under Vitest with about 94% coverage, across 16 suites on the Node 20,
22, and 24 matrix. Runnable examples and a benchmark exercise remember, recall, and identity against the
built artifact end to end. Run pnpm test on a fresh clone to reproduce.
TypeScript 6 in maximum strict mode (exactOptionalPropertyTypes,
useUnknownInCatchVariables, noUncheckedIndexedAccess,
noImplicitOverride, noImplicitReturns). Zero errors under tsc
--noEmit.
Biome clean across src and tests. publint clean and
@arethetypeswrong/cli green across every subpath. Dual ESM + CJS with separate
.d.ts and .d.cts per subpath.
A persona projects to the same 256-dimensional vector across models, a record reads back identically from every store, masking holds before the boundary, and the audit chain detects a tampered entry at exactly its index. Every invariant is a test.
A smoke test exercises the compiled ESM and CJS artifacts and spawns the compiled CLI as a single Node process, run on the Node 20, 22, and 24 matrix.
Committed pnpm lockfile, zero required runtime dependencies, node-free core, and SLSA provenance
attestation on every published version. Verify with npm view @takk/mnemosyne@1.0.0 --json | jq
.dist.attestations.
Yes. 141 tests across 16 suites pass under Vitest with about 94% coverage; TypeScript maximum strict mode
is clean; Biome lint is clean; publint and @arethetypeswrong/cli are clean across
every subpath. The suite and the distribution smoke test are run on the Node 20, 22, and 24 matrix. Every
published release carries SLSA provenance produced by GitHub Actions.
A closed endpoint or a single agent daemon keeps memory hidden inside itself: you cannot inspect what it holds, you cannot move it to another runtime or vendor, and it lives where the vendor decides. Mnemosyne keeps memory portable, inspectable, and on your infrastructure, with an identity that is stable and provable across model swaps. That is the differentiator.
You can, and many do. The cost is a pool of agents that re-derive the same facts, disagree about state, and cannot pick up where another left off. Mnemosyne is the hippocampus of the swarm: namespaced, versioned, content-addressed records that every agent reads and writes, so the working knowledge is shared instead of duplicated and drifting.
No. The MemoryStore is pluggable: an in-memory store, an edge key-value store such as Cloudflare Workers KV and lookalikes, a Node file store, or any key-value backend you bring. The semantics are identical everywhere, so a record written through one store reads back identically through another, and your provider credentials never live in Mnemosyne.
Yes. The core is node-free; the audit chain and snapshot signatures use the Web Crypto API, not
node:crypto. Import @takk/mnemosyne on any runtime with Web Crypto. Only
@takk/mnemosyne/node, the file store, requires the Node standard library.
Mnemosyne holds the records you remember and the configuration you pass, nothing else. The node-free core makes no outbound network calls of its own. Field-level masking and a data residency tag apply before a record crosses a boundary, hashing is deterministic so masked records stay joinable, and with the file store only the files you point it at are read from disk.
A deterministic 256-dimensional identity projects a persona to the same vector byte-for-byte regardless of
model, so an agent keeps the same identity seed when you swap GPT for Claude. This is a fingerprint of the
persona definition, not a behavioral guarantee: it proves the identity you configured is unchanged across
the swap, not that a different model answers the same way. Call deriveIdentity to get the
vector and identityDistance to measure persona-definition drift as a cosine distance, a number
rather than a guess.
Both, for different things. The access log is a SHA-256 hash chain, where each entry is chained to the previous through a hash of its canonical form, so any later edit breaks the chain. That is an integrity seal. Snapshots go further and are Ed25519-signed, so a transferred memory set also proves who produced it. Both run over Web Crypto.
Any of them. Memory is model-agnostic: OpenAI, Anthropic, Google, a local model, or a mix all share the
same records, and a persona keeps the same identity across them. Memory is also exposed as a Model Context
Protocol (MCP) resource and tools (mnemosyne_remember, recall, query),
so any MCP host can read and write it.
Wherever the store you choose puts it: RAM with the in-memory store, your own KV with the edge store, or
disk with @takk/mnemosyne/node. Ed25519-signed snapshots move a memory set between
infrastructures over Web Crypto, so you can export from one runtime and restore into another, or checkpoint
between edge invocations.
Field-level masking applies redact, hash, or partial masks before memory crosses a boundary, and a data residency tag travels with the record and is enforced at the boundary. Hashing is deterministic, so a masked field still joins across records, and the original value never leaves the boundary in the clear.
Every release is published with npm publish --provenance. Check the attestations with
npm view @takk/mnemosyne@<version> --json | jq .dist.attestations. The attestation
links the tarball you installed to the GitHub Actions workflow that built it from a specific source commit.
Strict SemVer 2.0.0, starting from 1.0.0. The binding stability surface is documented in SPEC.md section 5. Major bumps require a deprecation cycle; security fixes follow the disclosure flow in SECURITY.md.